跳到主要内容

配置

所有设置均存储在 ~/.hermes/ 目录中，便于访问。

目录结构​

~/.hermes/
├── config.yaml     # 配置项（模型、终端、TTS、压缩等）
├── .env            # API 密钥与敏感信息
├── auth.json       # OAuth 提供商凭证（Nous Portal 等）
├── SOUL.md         # 主 Agent 身份（系统提示中的第 1 槽位）
├── memories/       # 持久记忆（MEMORY.md、USER.md）
├── skills/         # Agent 创建的技能（由 skill_manage 工具管理）
├── cron/           # 定时任务
├── sessions/       # 网关会话
└── logs/           # 日志（errors.log、gateway.log——自动脱敏）

管理配置​

hermes config              # 查看当前配置
hermes config edit         # 在编辑器中打开 config.yaml
hermes config set KEY VAL  # 设置指定配置项
hermes config check        # 检查缺失配置项（升级后常用）
hermes config migrate      # 交互式补全缺失配置项

# 示例：
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # 保存到 `.env`
提示

hermes config set 命令会自动将值路由到正确的文件 —— API 密钥保存到 .env，其余所有内容保存到 config.yaml。

配置优先级​

设置按以下顺序解析（优先级从高到低）：

  1. CLI 参数 —— 例如 hermes chat --model anthropic/claude-sonnet-4（每次调用的覆盖）
  2. ~/.hermes/config.yaml —— 用于所有非敏感设置的主要配置文件
  3. ~/.hermes/.env —— 环境变量的备用位置；必须用于敏感信息（API 密钥、令牌、密码）
  4. 内置默认值 —— 当其他设置均未配置时使用的硬编码安全默认值
通用规则

敏感信息（API 密钥、机器人令牌、密码）应存放在 .env 中。其余所有内容（模型、终端后端、压缩设置、记忆限制、工具集）应存放在 config.yaml 中。当两者均被设置时，config.yaml 对非敏感设置具有更高优先级。

环境变量替换​

您可以在 config.yaml 中使用 ${VAR_NAME} 语法引用环境变量：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

单个值中支持多个引用：url: "${HOST}:${PORT}"。如果引用的变量未设置，占位符将原样保留（${UNDEFINED_VAR} 保持不变）。仅支持 ${VAR} 语法 —— 未加花括号的 $VAR 不会被展开。

关于 AI 提供商设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），请参阅 AI 提供商。

终端后端配置​

Hermes 支持六种终端后端。每种后端决定了 Agent 的 shell 命令实际执行的位置 —— 您的本地机器、Docker 容器、通过 SSH 连接的远程服务器、Modal 云沙箱、Daytona 工作区，或 Singularity/Apptainer 容器。

terminal:
  backend: local    # 任选：本地 | docker | ssh |莫代尔|代托纳 |奇点
  cwd: "."          # 工作目录（local 用当前目录，容器默认用 /根目录）
  timeout: 180      # 每条命令的超时时间（秒）
  env_passthrough: []  # 透传到沙箱执行环境的环境变量名（terminal + execute_code）
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Singularity 后端使用的容器镜像
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Modal 后端使用的容器镜像
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Daytona 后端使用的容器镜像

对于 Modal 和 Daytona 等云沙箱，container_persistent: true 表示 Hermes 将尝试在沙箱重建时保留文件系统状态。但这并不保证相同的实时沙箱、PID 空间或后台进程在稍后仍处于运行状态。

后端概览​

后端命令执行位置隔离级别适用场景
local直接在您的机器上无开发、个人使用
dockerDocker 容器内完全隔离（命名空间、能力降级）安全沙箱、CI/CD
ssh通过 SSH 连接的远程服务器网络边界远程开发、高性能硬件
modalModal 云沙箱完全隔离（云虚拟机）临时云计算、评估
daytonaDaytona 工作区完全隔离（云容器）受管理的云开发环境
singularitySingularity/Apptainer 容器内命名空间（--containall）HPC 集群、共享机器

本地后端​

默认后端。命令直接在您的机器上运行，无任何隔离。无需特殊设置。

terminal:
  backend: local
注意

Agent 具有与您的用户账户相同的文件系统访问权限。请使用 hermes tools 禁用您不希望使用的工具，或切换到 Docker 以实现沙箱隔离。

Docker 后端​

在 Docker 容器中运行命令，并进行安全加固（所有能力被丢弃，无权限提升，PID 限制）。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # 将启动目录挂载到 /workspace
  docker_forward_env:              # 透传进容器的环境变量
    - "GITHUB_TOKEN"
  docker_volumes:                  # 挂载主机目录
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro 表示只读

  # 资源限制
  container_cpu: 1                 # CPU 核数（0 = 不限）
  container_memory: 5120           # 内存 / 磁盘大小，单位 MB（0 = 不限）
  container_disk: 51200            # 磁盘大小，单位 MB（需要 overlay2 + XFS+pquota）
  container_persistent: true       # 在会话间持久化 /workspace 和 /root

要求： 已安装并运行 Docker Desktop 或 Docker Engine。Hermes 会探测 $PATH 以及常见的 macOS 安装路径（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 应用包）。

容器生命周期： 每个会话启动一个长期运行的容器（docker run -d ... sleep 2h）。命令通过 docker exec 以登录 shell 执行。清理时，容器将被停止并删除。

安全加固：

  • --cap-drop ALL，仅重新添加 DAC_OVERRIDE、CHOWN、FOWNER
  • --security-opt no-new-privileges
  • --pids-limit 256
  • 为 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）设置大小受限的 tmpfs

凭证转发： docker_forward_env 列出的环境变量首先从您的 shell 环境中解析，然后从 ~/.hermes/.env 中解析。技能也可以声明 required_environment_variables，这些变量会自动合并。

SSH 后端​

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 实现连接复用（5 分钟空闲保活）。默认启用持久化 shell —— 状态（当前工作目录、环境变量）在命令之间保持不变。

terminal:
  backend: ssh
  persistent_shell: true           # 保持一个长期存活的 bash 会话（默认 true）

必需的环境变量：

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

可选：

变量默认值描述
TERMINAL_SSH_PORT22SSH 端口
TERMINAL_SSH_KEY（系统默认）SSH 私钥路径
TERMINAL_SSH_PERSISTENTtrue启用持久化 shell

工作原理： 初始化时以 BatchMode=yes 和 StrictHostKeyChecking=accept-new 连接。持久化 shell 会在远程主机上保持一个单一的 bash -l 进程运行，通过临时文件进行通信。需要 stdin_data 或 sudo 的命令会自动回退到一次性模式。

在 Modal 云沙箱中运行命令。每个任务都会获得一个可配置 CPU、内存和磁盘的隔离虚拟机。文件系统可在会话间进行快照/恢复。

terminal:
  backend: modal
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # 内存大小，单位 MB（5GB）
  container_disk: 51200            # 磁盘大小，单位 MB（50GB）
  container_persistent: true       # 对文件系统进行快照 / 恢复

必需项： 必须设置 MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 环境变量，或存在 ~/.modal.toml 配置文件。

持久化： 启用后，沙箱文件系统会在清理时进行快照，并在下次会话时恢复。快照信息记录在 ~/.hermes/modal_snapshots.json 中。这会保留文件系统状态，但不会保留运行中的进程、PID 空间或后台任务。

凭证文件： 自动从 ~/.hermes/ 挂载（如 OAuth 令牌等），并在每次命令执行前同步。

Daytona 后端​

在 Daytona 管理的工作区中运行命令。支持停止/恢复以实现持久化。

terminal:
  backend: daytona
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # 单位 MB，会自动换算为 GiB
  container_disk: 10240            # 单位 MB，会自动换算为 GiB（最大 10 GiB）
  container_persistent: true       # 停止 / 恢复，而不是直接删除

必需项： 必须设置 DAYTONA_API_KEY 环境变量。

持久化： 启用后，沙箱在清理时会被停止（而非删除），并在下次会话时恢复。沙箱名称遵循 hermes-{task_id} 的模式。

磁盘限制： Daytona 强制最大 10 GiB。超过此限制的请求将被警告并截断。

Singularity/Apptainer 后端​

在 Singularity/Apptainer 容器中运行命令。专为 Docker 不可用的 HPC 集群和共享机器设计。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # 内存大小，单位 MB
  container_persistent: true       # 可写 overlay 在会话间持久化

要求： $PATH 中需存在 apptainer 或 singularity 二进制文件。

镜像处理： Docker URL（docker://...）会自动转换为 SIF 文件并缓存。已存在的 .sif 文件将直接使用。

临时目录： 按以下顺序解析：TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent（HPC 常规路径）→ ~/.hermes/sandboxes/singularity。

隔离： 使用 --containall --no-home 实现完整的命名空间隔离，且不挂载主机家目录。

常见终端后端问题​

如果终端命令立即失败，或终端工具被报告为禁用：

  • 本地（Local） — 无特殊要求。开始时最安全的默认选项。
  • Docker — 运行 docker version 以验证 Docker 是否正常工作。若失败，请修复 Docker 或执行 hermes config set terminal.backend local。
  • SSH — 必须同时设置 TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER。若任一缺失，Hermes 会记录明确错误。
  • Modal — 需要 MODAL_TOKEN_ID 环境变量或 ~/.modal.toml 文件。运行 hermes doctor 进行检查。
  • Daytona — 需要 DAYTONA_API_KEY。Daytona SDK 会处理服务器 URL 配置。
  • Singularity — 需要 apptainer 或 singularity 在 $PATH 中。这在 HPC 集群上很常见。

如有疑问，将 terminal.backend 设置回 local，并先确认命令在此模式下能否正常运行。

Docker 卷挂载​

使用 Docker 后端时，docker_volumes 允许将主机目录共享给容器。每个条目使用标准 Docker -v 语法：host_path:container_path[:options]。

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # 可读写（默认）
    - "/home/user/datasets:/data:ro"              # 只读
    - "/home/user/outputs:/outputs"               # Agent 写入，你来读取

这适用于：

  • 提供文件给 Agent（数据集、配置文件、参考代码）
  • 接收文件自 Agent（生成的代码、报告、导出文件）
  • 共享工作区，你和 Agent 均可访问相同文件

也可通过环境变量设置：TERMINAL_DOCKER_VOLUMES='["/host:/container"]'（JSON 数组格式）。

Docker 凭证转发​

默认情况下，Docker 终端会话不会继承主机的任意凭证。若需在容器内使用特定令牌，请将其添加到 terminal.docker_forward_env。

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Hermes 会首先从当前 shell 解析每个列出的变量，若未找到，则回退至 ~/.hermes/.env（如果曾通过 hermes config set 保存过）。

注意

docker_forward_env 中列出的任何内容都会对容器内运行的命令可见。仅转发你愿意暴露给终端会话的凭证。

可选：将启动目录挂载到 /workspace​

Docker 沙箱默认保持隔离。Hermes 不会自动将当前主机工作目录传递给容器，除非你显式启用此功能。

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用后：

  • 若你从 ~/projects/my-app 启动 Hermes，该主机目录将被绑定挂载至 /workspace
  • Docker 后端将从 /workspace 启动
  • 文件工具和终端命令均能访问相同的挂载项目

禁用后，/workspace 保持沙箱独占，除非你通过 docker_volumes 显式挂载内容。

安全权衡：

  • false 保持沙箱边界
  • true 使沙箱可直接访问你启动 Hermes 时所在的目录

仅在你有意让容器操作主机上的实时文件时才启用此选项。

持久化 Shell​

默认情况下，每个终端命令都在独立的子进程中运行 —— 工作目录、环境变量和 shell 变量在命令之间都会重置。当启用 持久化 Shell 时，会保持一个长期运行的 bash 进程，跨 execute() 调用存活，从而使状态在命令间持续保留。

这对于 SSH 后端 最为有用，同时也能消除每条命令的连接开销。持久化 shell 默认为 SSH 启用，本地后端禁用。

terminal:
  persistent_shell: true   # 默认值——为 SSH 启用持久化 shell

禁用方法：

hermes config set terminal.persistent_shell false

跨命令保持的内容：

  • 工作目录（cd /tmp 对下一条命令仍然有效）
  • 导出的环境变量（export FOO=bar）
  • Shell 变量（MY_VAR=hello）

优先级顺序：

级别变量默认值
配置terminal.persistent_shelltrue
SSH 覆盖TERMINAL_SSH_PERSISTENT与配置一致
本地覆盖TERMINAL_LOCAL_PERSISTENTfalse

按后端设置的环境变量具有最高优先级。若你也希望在本地后端启用持久化 shell：

export TERMINAL_LOCAL_PERSISTENT=true
备注

需要 stdin_data 或使用 sudo 的命令会自动回退到一次性模式，因为持久化 shell 的 stdin 已被 IPC 协议占用。

有关每个后端的详细信息，请参阅 代码执行 和 README 中的终端部分。

技能设置​

技能可通过其 SKILL.md 前置元数据声明自己的配置设置。这些是非敏感值（路径、偏好、领域设置），存储在 config.yaml 的 skills.config 命名空间下。

skills:
  config:
    wiki:
      path: ~/wiki          # 供 llm-wiki 技能使用

技能设置的工作方式：

  • hermes config migrate 会扫描所有启用的技能，查找未配置的设置，并提示你进行配置
  • hermes config show 会显示所有技能设置，按所属技能分类列出
  • 当技能加载时，其解析后的配置值会自动注入到技能上下文中

手动设置值：

hermes config set skills.config.wiki.path ~/my-research-wiki

有关在你自己的技能中声明配置设置的详细信息，请参阅 创建技能 — 配置设置。

记忆配置​

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # 约 800 tokens
  user_char_limit: 1375     # 约 500 tokens

文件读取安全​

控制单次 read_file 调用可返回的内容量。超过限制的读取将被拒绝，并提示 Agent 使用 offset 和 limit 来获取更小的范围。这可防止对一个压缩后的 JS 包或大型数据文件的一次性读取，导致上下文窗口被淹没。

file_read_max_chars: 100000  # 默认值——约 25–35K tokens

如果你使用的是具有大上下文窗口的模型，并且频繁读取大文件，可以适当提高该值。对于上下文较小的模型，则应降低该值以保持读取效率：

# 大上下文模型（200K+）
file_read_max_chars: 200000

# 小上下文本地模型（16K 上下文）
file_read_max_chars: 30000

Agent 还会自动去重文件读取 —— 如果同一文件区域被读取两次且文件未更改，则返回轻量级占位符，而非重新发送内容。该机制在上下文压缩后重置，因此 Agent 可在内容被摘要后重新读取文件。

Git 工作树隔离​

为在同一个仓库上并行运行多个 Agent，启用隔离的 Git 工作树：

worktree: true    # 始终创建 worktree（等同于 hermes -w）
# worktree: false # 默认值——仅在传入 -w 时创建

启用后，每个 CLI 会话都会在 .worktrees/ 下创建一个全新的工作树，并拥有自己的分支。Agent 可以编辑文件、提交、推送和创建 PR，互不干扰。退出时会自动清理干净的工作树；脏的工作树则保留以供手动恢复。

你还可以通过在仓库根目录下的 .worktreeinclude 文件列出要复制到工作树中的被忽略文件：

# .worktreeinclude 示例
.env
.venv/
node_modules/

上下文压缩​

Hermes 会自动压缩长时间对话，以保持在模型的上下文窗口限制内。压缩摘要器是一个独立的 LLM 调用 —— 你可以将其指向任何提供方或端点。

所有压缩设置均位于 config.yaml 中（不使用环境变量）。

完整参考​

compression:
  enabled: true                                     # 开启 / 关闭上下文压缩
  threshold: 0.50                                   # 达到上下文限制该比例时触发压缩
  target_ratio: 0.20                                # 作为最近消息尾部保留的阈值比例
  protect_last_n: 20                                # 至少保留多少条最近消息不压缩
  summary_model: "google/gemini-3-flash-preview"    # 用于摘要压缩的模型
  summary_provider: "auto"                          # 提供商：auto、openrouter、nous、codex、main 等
  summary_base_url: null                            # 自定义 OpenAI 兼容端点（优先于 provider）

常见配置​

默认（自动检测）—— 无需配置：

compression:
  enabled: true
  threshold: 0.50

使用第一个可用的提供方（OpenRouter → Nous → Codex），使用 Gemini Flash。

强制指定特定提供方（基于 OAuth 或 API 密钥）：

compression:
  summary_provider: nous
  summary_model: gemini-3-flash

适用于任何提供方：nous、openrouter、codex、anthropic、main 等。

自定义端点（自托管、Ollama、zai、DeepSeek 等）：

compression:
  summary_model: glm-4.7
  summary_base_url: https://api.z.ai/api/coding/paas/v4

指向一个自定义的 OpenAI 兼容端点。使用 OPENAI_API_KEY 进行认证。

三个配置项的交互方式​

summary_providersummary_base_url结果
auto（默认）未设置自动检测最佳可用提供方
nous / openrouter / 等未设置强制使用该提供方，使用其认证方式
任意值已设置直接使用自定义端点（提供方被忽略）

summary_model 必须支持至少与主模型相同长度的上下文，因为它需要接收对话的中间完整部分进行压缩。

上下文引擎​

上下文引擎控制在接近模型标记限制时如何管理对话。内置的 compressor 引擎使用有损摘要（参见 上下文压缩）。插件引擎可替换它，以采用其他策略。

context:
  engine: "compressor"    # 默认值——内置有损摘要引擎

要使用插件引擎（例如 LCM 实现无损上下文管理）：

context:
  engine: "lcm"          # 必须与插件名称一致

插件引擎从不自动激活——您必须显式设置 context.engine 为插件名称。可通过 hermes plugins → Provider Plugins → Context Engine 浏览并选择可用的引擎。

有关记忆插件的类似单选系统，请参阅 记忆提供者。

迭代预算压力​

当 Agent 在处理复杂任务并进行大量工具调用时，可能在未察觉的情况下耗尽其迭代预算（默认：90 轮）。预算压力会在接近限制时自动向模型发出警告：

阈值等级模型所见内容
70%警告[BUDGET: 63/90. 27 次迭代剩余。开始整合工作。]
90%警告[BUDGET WARNING: 81/90. 仅剩 9 次。立即响应。]

警告会注入到最后一个工具结果的 JSON 中（作为 _budget_warning 字段），而非作为独立消息——这保留了提示缓存机制，且不会破坏对话结构。

agent:
  max_turns: 90                # 每轮对话允许的最大迭代次数（默认 90）

预算压力默认启用。Agent 会自然地将警告视为工具结果的一部分，从而鼓励其整合工作并在耗尽迭代次数前交付响应。

流式传输超时​

LLM 流式连接包含两层超时机制。对于本地提供者（localhost、局域网 IP）两者均会自动调整——大多数设置无需配置。

超时默认值本地提供者环境变量
套接字读取超时120s自动提升至 1800sHERMES_STREAM_READ_TIMEOUT
静默流检测180s自动禁用HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）1800s保持不变HERMES_API_TIMEOUT

套接字读取超时控制 httpx 等待提供者发送下一块数据的时间。本地 LLM 在大上下文预填充阶段可能需要数分钟才能生成第一个 token，因此 Hermes 在检测到本地端点时会将该值提升至 30 分钟。如果您显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论端点检测结果如何，都将始终使用该值。

静默流检测会终止接收 SSE 心跳 ping 但无实际内容的连接。此机制对本地提供者完全禁用，因为它们在预填充期间不会发送心跳 ping。

上下文压力警告​

与迭代预算压力不同，上下文压力跟踪对话距离压缩阈值的接近程度——即上下文压缩触发以总结较早消息的临界点。这有助于您和 Agent 了解对话是否正在变长。

进度等级发生什么
≥ 60% 至阈值信息CLI 显示青色进度条；网关发送信息通知
≥ 85% 至阈值警告CLI 显示粗体黄色条；网关警告压缩即将发生

在 CLI 中，上下文压力以工具输出流中的进度条形式显示：

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

在消息平台中，会发送纯文本通知：

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

如果禁用了自动压缩，警告会提示上下文可能会被截断。

上下文压力为自动机制——无需配置。它仅作为面向用户的提示触发，不会修改消息流，也不会向模型上下文注入任何内容。

凭证池策略​

当您为同一提供者拥有多个 API 密钥或 OAuth 令牌时，可配置轮换策略：

credential_pool_strategies:
  openrouter: round_robin    # 均匀轮换各个 key
  anthropic: least_used      # 总是优先选择使用次数最少的 key

选项：fill_first（默认）、round_robin、least_used、random。完整文档请参见 Credential Pools。

辅助模型​

Hermes 使用轻量级“辅助”模型执行图像分析、网页摘要、浏览器截图分析等辅助任务。默认情况下，这些任务通过自动检测使用 Gemini Flash——您无需进行任何配置。

通用配置模式​

Hermes 中的每个模型槽位——辅助任务、压缩、回退——均使用相同的三个控制项：

键作用默认值
provider用于认证和路由的提供者"auto"
model请求的模型提供者的默认模型
base_url自定义 OpenAI 兼容端点（覆盖提供者）未设置

当设置 base_url 时，Hermes 忽略提供者，直接调用该端点（使用 api_key 或 OPENAI_API_KEY 进行认证）。当仅设置 provider 时，Hermes 使用该提供者的内置认证和基础 URL。

可用于辅助任务的提供者：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、minimax，任何注册在 提供者注册表 中的提供者，或您 custom_providers 列表中命名的任何自定义提供者（例如 provider: "beans"）。

"main" 仅用于辅助任务

"main" 提供商选项表示“使用我主 Agent 所使用的任何提供者”——它仅在 auxiliary:、compression: 和 fallback_model: 配置中有效。它不是顶层 model.provider 设置的有效值。如果你使用自定义的 OpenAI 兼容端点，请在 model: 部分设置 provider: custom。有关所有主模型提供者选项，请参阅 AI 提供商。

完整的辅助配置参考​

auxiliary:
  # 图像分析（vision_analyze 工具 + 浏览器截图）
  vision:
    provider: "auto"           # 可选：auto、openrouter、nous、codex、main 等
    model: ""                  # 例如：openai/gpt-4o、google/gemini-2.5-flash
    base_url: ""               # 自定义 OpenAI 兼容端点（优先于 provider）
    api_key: ""                # base_url 对应的 API key（未填时回退到 OPENAI_API_KEY）
    timeout: 30                # 单位秒——LLM API 调用超时；本地慢速视觉模型可适当调大
    download_timeout: 30       # 单位秒——图片 HTTP 下载超时；慢网环境可适当调大

  # 网页摘要 + 浏览器页面文本提取
  web_extract:
    provider: "auto"
    model: ""                  # 例如：google/gemini-2.5-flash
    base_url: ""
    api_key: ""
    timeout: 360               # 单位秒（6 分钟）——单次 LLM 摘要调用超时

  # 危险命令审批分类器
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # 单位秒

  # 上下文压缩超时（独立于 compression.* 配置）
  compression:
    timeout: 120               # 单位秒——压缩长对话通常更耗时

  # 会话搜索——总结过去会话的匹配结果
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Skills Hub——技能匹配与搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具调度
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # 记忆刷新——为持久记忆生成对话摘要
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
提示

每个辅助任务都有一个可配置的 timeout（以秒为单位）。默认值：vision 30 秒，web_extract 360 秒，approval 30 秒，compression 120 秒。如果你为辅助任务使用较慢的本地模型，请增加这些值。vision 还有一个独立的 download_timeout（默认 30 秒），用于 HTTP 图像下载——对于慢速连接或自托管图像服务器，请增加此值。

信息

上下文压缩有其自身的顶层 compression: 块，包含 summary_provider、summary_model 和 summary_base_url——请参阅上方的 上下文压缩。回退模型使用 fallback_model: 块——请参阅 回退模型。这三个配置遵循相同的提供者/模型/基础 URL 模式。

更改视觉模型​

要使用 GPT-4o 而不是 Gemini Flash 进行图像分析：

auxiliary:
  vision:
    model: "openai/gpt-4o"

或通过环境变量（在 ~/.hermes/.env 中）：

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供商选项​

这些选项适用于 辅助任务配置（auxiliary:、compression:、fallback_model:），而不是你的主 model.provider 设置。

提供商描述要求
"auto"最佳可用选项（默认）。视觉尝试 OpenRouter → Nous → Codex。—
"openrouter"强制使用 OpenRouter —— 路由到任意模型（Gemini、GPT-4o、Claude 等）。OPENROUTER_API_KEY
"nous"强制使用 Nous Portalhermes auth
"codex"强制使用 Codex OAuth（ChatGPT 账户）。支持视觉（gpt-5.3-codex）。hermes model → Codex
"main"使用你当前的自定义/主端点。这可以来自 OPENAI_BASE_URL + OPENAI_API_KEY，或来自 hermes model / config.yaml 保存的自定义端点。支持 OpenAI、本地模型或任何 OpenAI 兼容 API。仅限辅助任务 —— 不适用于 model.provider。自定义端点凭据 + 基础 URL

常见配置​

使用直接自定义端点（比 provider: "main" 更清晰，适用于本地/自托管 API）：

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url 优先于 provider，因此这是将辅助任务路由到特定端点的最明确方式。对于直接端点覆盖，Hermes 使用配置的 api_key，或回退到 OPENAI_API_KEY；它不会为该自定义端点重用 OPENROUTER_API_KEY。

使用 OpenAI API 密钥进行视觉分析：

# 写在 ~/.hermes/.env 中：
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...

auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"       # 或者用更便宜的 gpt-4o-mini

使用 OpenRouter 进行视觉分析（路由到任意模型）：

auxiliary:
  vision:
    provider: "openrouter"
    model: "openai/gpt-4o"      # 或 google/gemini-2.5-flash 等

使用 Codex OAuth（ChatGPT Pro/Plus 账户 —— 无需 API 密钥）：

auxiliary:
  vision:
    provider: "codex"     # 使用你的 ChatGPT OAuth 凭证
    # 模型 默认是 gpt-5.3-codex（支持视觉）

使用本地/自托管模型：

auxiliary:
  vision:
    provider: "main"      # 使用你当前激活的自定义端点
    model: "my-local-model"

provider: "main" 使用 Hermes 用于正常聊天的任何提供者——无论是命名的自定义提供者（例如 beans）、内置提供者如 openrouter，还是旧版的 OPENAI_BASE_URL 端点。

提示

如果你将 Codex OAuth 作为主模型提供者，视觉功能将自动生效——无需额外配置。Codex 已包含在视觉的自动检测链中。

注意

视觉功能需要多模态模型。 如果你设置 provider: "main"，请确保你的端点支持多模态/视觉功能——否则图像分析将失败。

环境变量（旧版）​

辅助模型也可以通过环境变量进行配置。然而，config.yaml 是首选方法——它更容易管理，并支持所有选项，包括 base_url 和 api_key。

设置环境变量
视觉提供者AUXILIARY_VISION_PROVIDER
视觉模型AUXILIARY_VISION_MODEL
视觉端点AUXILIARY_VISION_BASE_URL
视觉 API 密钥AUXILIARY_VISION_API_KEY
网页提取提供者AUXILIARY_WEB_EXTRACT_PROVIDER
网页提取模型AUXILIARY_WEB_EXTRACT_MODEL
网页提取端点AUXILIARY_WEB_EXTRACT_BASE_URL
网页提取 API 密钥AUXILIARY_WEB_EXTRACT_API_KEY

压缩和回退模型设置仅支持 config.yaml。

提示

运行 hermes config 以查看当前的辅助模型设置。仅当与默认值不同时，覆盖项才会显示。

推理努力​

控制模型在响应前进行“思考”的程度：

agent:
  reasoning_effort: ""   # 留空 = medium（默认）；可选：none、minimal、low、medium、high、xhigh（最高）

未设置时（默认），推理努力默认为“中等”——一个对大多数任务都表现良好的平衡水平。设置一个值将覆盖默认值——更高的推理努力在复杂任务上可获得更好结果，但会增加 token 消耗和延迟。

你也可以在运行时通过 /reasoning 命令更改推理努力：

/reasoning           # 显示当前推理强度与展示状态
/reasoning high      # 将推理强度设为 high
/reasoning none      # 关闭推理
/reasoning show      # 在每条回复上方显示模型思考
/reasoning hide      # 隐藏模型思考

工具使用强制执行​

某些模型（尤其是 GPT 系列）偶尔会将预期操作描述为文本，而不是实际调用工具。工具调用强制机制会注入引导信息，促使模型回到实际调用工具的行为。

agent:
  tool_use_enforcement: "auto"   # 可选："auto" | true | false | ["模型名子串", ...]
值行为
"auto"（默认）对 GPT 模型（gpt-、openai/gpt-）启用，对其他所有模型禁用。
true对所有模型始终启用。
false对所有模型始终禁用。
["gpt-", "o1-", "custom-model"]仅对名称中包含列表中任一子字符串的模型启用。

启用后，系统提示中会包含引导信息，提醒模型应实际调用工具，而非仅描述其行为。此机制对用户透明，且对已能可靠使用工具的模型无影响。

TTS 配置​

tts:
  provider: "edge"              # 可选：edge | elevenlabs | openai | neutts
  edge:
    voice: "en-US-AriaNeural"   # 共 322 个声音、74 种语言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # 可选：alloy、echo、fable、onyx、nova、shimmer
    base_url: "https://api.openai.com/v1"  # 用于覆盖 OpenAI 兼容 TTS 端点
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

此配置同时控制 text_to_speech 工具和语音模式下的语音回复（CLI 中的 /voice tts 或消息网关）。

显示设置​

display:
  tool_progress: all      # 可选：off | new | all | verbose
  tool_progress_command: false  # 在消息网关中启用 /verbose 斜杠命令
  tool_progress_overrides: {}  # 按平台覆盖（见下文）
  skin: default           # 内置或自定义 CLI 皮肤（见 user-guide/features/skins）
  personality: "kawaii"  # 旧版外观字段，部分摘要里仍会显示
  compact: false          # 紧凑输出模式（减少空白）
  resume_display: full    # full（恢复时显示历史消息）| minimal（只显示一行概览）
  bell_on_complete: false # Agent 完成时播放终端响铃（适合长任务）
  show_reasoning: false   # 在回复上方显示模型推理 / 思考（可用 /reasoning show|hide 切换）
  streaming: false        # 在 token 到达时实时流式输出到终端
  show_cost: false        # 在 CLI 状态栏显示预估美元成本
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 不限，显示完整路径 / 命令）
模式你将看到的内容
off静音 — 仅显示最终响应
new仅当工具变更时显示工具指示器
all每次工具调用均显示简短预览（默认）
verbose显示完整参数、结果和调试日志

在 CLI 中，使用 /verbose 命令循环切换这些模式。要在消息平台（Telegram、Discord、Slack 等）中使用 /verbose，请在上述 display 部分设置 tool_progress_command: true。该命令将循环切换模式并保存至配置文件。

各平台进度显示覆盖设置​

不同平台对详细程度的需求不同。例如，Signal 不支持编辑消息，因此每次进度更新都会变成一条独立消息 —— 容易造成噪音。使用 tool_progress_overrides 可为各平台设置独立的显示模式：

display:
  tool_progress: all          # 全局默认值
  tool_progress_overrides:
    signal: 'off'             # 在 Signal 中关闭进度显示
    telegram: verbose         # 在 Telegram 中显示详细进度
    slack: 'off'              # 在共享 Slack 工作区中保持安静

未设置覆盖的平台将回退到全局 tool_progress 值。有效平台键名：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles。

隐私​

privacy:
  redact_pii: false  # 从 LLM 上下文中剥离 PII（仅网关场景）

当 redact_pii 为 true 时，网关会在支持的平台上将系统提示中的个人身份信息（PII）进行脱敏处理后再发送给 LLM：

字段处理方式
电话号码（WhatsApp/Signal 中的用户 ID）哈希为 user_<12-char-sha256>
用户 ID哈希为 user_<12-char-sha256>
聊天 ID数字部分哈希，平台前缀保留（如 telegram:<hash>）
主频道 ID数字部分哈希
用户名 / 用户别名不受影响（由用户选择，公开可见）

平台支持： 脱敏适用于 WhatsApp、Signal 和 Telegram。Discord 和 Slack 被排除，因为其提及系统（<@user_id>）需要在 LLM 上下文中保留真实 ID。

哈希为确定性生成 —— 同一用户始终映射到同一哈希值，因此模型仍可在群聊中区分不同用户。路由与交付仍使用原始值在内部处理。

语音转文本（STT）​

stt:
  provider: "local"            # 可选：local | groq | openai
  local:
    model: "base"              # 可选：tiny、base、small、medium、large-v3
  openai:
    model: "whisper-1"         # 开关：whisper-1 | gpt-4o-mini-转录 | gpt-4th-转录
  # model: "whisper-1"         # 仍兼容旧版回退字段

提供方行为：

  • local 使用运行在你本地机器上的 faster-whisper。请使用 pip install faster-whisper 单独安装。
  • groq 使用 Groq 的 Whisper 兼容端点，并读取 GROQ_API_KEY。
  • openai 使用 OpenAI 的语音 API，并读取 VOICE_TOOLS_OPENAI_KEY。

如果请求的提供方不可用，Hermes 会按以下顺序自动降级：local → groq → openai。

Groq 和 OpenAI 的模型覆盖由环境变量驱动：

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

语音模式（CLI）​

voice:
  record_key: "ctrl+b"         # CLI 内的按住说话快捷键
  max_recording_seconds: 120    # 超长录音的强制停止时长
  auto_tts: false               # 开启 /voice 后自动播放语音回复
  silence_threshold: 200        # 语音检测的 RMS 阈值
  silence_duration: 3.0         # 自动停止前允许的静音秒数

在 CLI 中使用 /voice on 启用麦克风模式，使用 record_key 开始/停止录音，使用 /voice tts 切换语音回复。详见 语音模式 以获取端到端设置及各平台的具体行为说明。

流式传输​

在完整响应生成前，逐个令牌地将内容流式传输到终端或消息平台，而非等待全部响应完成。

CLI 流式传输​

display:
  streaming: true         # 在终端中实时流式输出 token
  show_reasoning: true    # 同时流式显示 reasoning / thinking token（可选）

启用后，响应将以流式框内逐令牌显示。工具调用仍会静默捕获。若提供方不支持流式传输，将自动回退到正常显示模式。

网关流式传输（Telegram、Discord、Slack）​

streaming:
  enabled: true           # 启用渐进式消息编辑
  transport: edit         # 可选：edit（渐进编辑）或 off
  edit_interval: 0.3      # 两次消息编辑之间的间隔（秒）
  buffer_threshold: 40    # 累积到多少字符后强制刷新编辑
  cursor: " ▉"            # 流式输出时显示的光标

启用后，机器人在首个令牌到达时发送消息，随后随着更多令牌到达逐步编辑该消息。对于不支持消息编辑的平台（Signal、Email、Home Assistant），将在首次尝试时自动检测 —— 该会话中流式传输将优雅禁用，避免消息泛滥。

溢出处理： 若流式文本超过平台的消息长度限制（约 4096 字符），当前消息将被确认并自动开启新消息。

备注

流式传输默认禁用。请在 ~/.hermes/config.yaml 中启用以体验流式交互体验。

群聊会话隔离​

控制共享聊天是按房间保持一个对话，还是按参与者保持独立对话：

group_sessions_per_user: true  # true = 群组/频道按用户隔离；false = 每个聊天共用一个会话
  • true 是默认且推荐的设置。在 Discord 频道、Telegram 群组、Slack 频道等共享上下文中，当平台提供用户 ID 时，每位发送者都会获得自己的会话。
  • false 会回退到旧的共享房间行为。这在你明确希望 Hermes 将某个频道视为单一协作对话时可能有用，但同时也意味着用户会共享上下文、Token 消耗和中断状态。
  • 私信不受影响。Hermes 仍按聊天/私信 ID 键控私信，如常操作。
  • 无论设置为何，线程始终与父频道隔离；当设置为 true 时，线程内的每位参与者也会拥有自己的会话。

有关行为细节和示例，请参阅 会话 和 Discord 指南。

未授权私信行为​

控制 Hermes 在未知用户发送私信时的行为：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • pair 是默认值。Hermes 拒绝访问，但在私信中回复一个一次性配对码。
  • ignore 会静默丢弃未授权的私信。
  • 平台配置项会覆盖全局默认值，因此你可以在整体保持配对功能开启的同时，让某个平台更安静。

快速命令​

定义自定义命令，运行 shell 命令而不调用大语言模型 —— 零 Token 消耗，即时执行。特别适用于消息平台（如 Telegram、Discord 等）中的快速服务器检查或实用脚本。

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  disk:
    type: exec
    command: df -h /
  update:
    type: exec
    command: cd ~/.hermes/hermes-agent && git pull && pip install -e .
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader

使用方法：在 CLI 或任意消息平台中输入 /status、/disk、/update 或 /gpu。命令将在主机上本地执行，并直接返回输出 —— 无需调用 LLM，不消耗任何 Token。

  • 30 秒超时 —— 长运行命令将被终止并返回错误消息
  • 优先级 —— 快速命令在技能命令之前检查，因此你可以覆盖技能名称
  • 自动补全 —— 快速命令在分发时解析，不会显示在内置斜杠命令自动补全表中
  • 类型 —— 仅支持 exec（运行 shell 命令）；其他类型会报错
  • 全平台可用 —— CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

人类延迟​

在消息平台中模拟类人响应节奏：

human_delay:
  mode: "off"                  # 可选：off | natural | custom
  min_ms: 800                  # 最小延迟（custom 模式）
  max_ms: 2500                 # 最大延迟（custom 模式）

代码执行​

配置沙箱化的 Python 代码执行工具：

code_execution:
  timeout: 300                 # 最大执行时长（秒）
  max_tool_calls: 50           # 代码执行期间允许的最大工具调用次数

网络搜索后端​

web_search、web_extract 和 web_crawl 工具支持四种后端提供商。可在 config.yaml 中配置后端，或通过 hermes tools 命令设置：

web:
  backend: firecrawl    # 可选：firecrawl | parallel | tavily | exa
后端环境变量搜索提取爬取
Firecrawl（默认）FIRECRAWL_API_KEY✔✔✔
ParallelPARALLEL_API_KEY✔✔—
TavilyTAVILY_API_KEY✔✔✔
ExaEXA_API_KEY✔✔—

后端选择：如果未设置 web.backend，系统将根据可用的 API 密钥自动检测后端。若仅设置了 EXA_API_KEY，则使用 Exa。若仅设置了 TAVILY_API_KEY，则使用 Tavily。若仅设置了 PARALLEL_API_KEY，则使用 Parallel。否则默认使用 Firecrawl。

自托管 Firecrawl：设置 FIRECRAWL_API_URL 指向你自己的实例。当设置了自定义 URL 时，API 密钥变为可选（在服务器上设置 USE_DB_AUTHENTICATION=false 可禁用认证）。

Parallel 搜索模式：设置 PARALLEL_SEARCH_MODE 以控制搜索行为 —— fast、one-shot 或 agentic（默认：agentic）。

浏览器​

配置浏览器自动化行为：

browser:
  inactivity_timeout: 120        # 空闲多久后自动关闭会话（秒）
  command_timeout: 30             # 浏览器命令超时时间（秒，如截图、导航等）
  record_sessions: false         # 自动将浏览器会话录制为 WebM 视频并保存到 ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # 为 true 时，Camofox 会在重启后保留 cookies / 登录态

浏览器工具集支持多个提供商。有关 Browserbase、Browser Use 和本地 Chrome CDP 设置的详细信息，请参阅 浏览器功能页面。

时区​

使用 IANA 时区字符串覆盖服务器本地时区。影响日志中的时间戳、定时任务调度以及系统提示中的时间注入。

timezone: "America/New_York"   # IANA 时区（默认留空 = 使用服务器本地时区）

支持的值：任意 IANA 时区标识符（例如 America/New_York、Europe/London、Asia/Kolkata、UTC）。留空或省略则使用服务器本地时间。

Discord​

为消息网关配置 Discord 特定行为：

discord:
  require_mention: true          # 在服务器频道中必须 @ 提及才响应
  free_response_channels: ""     # 无需 @ 提及也会响应的频道 ID（逗号分隔）
  auto_thread: true              # 在频道里被 @ 时自动创建线程
  • require_mention —— 当为 true（默认），机器人仅在频道中被 @BotName 提及时才响应。私信始终无需提及即可工作。
  • free_response_channels —— 逗号分隔的频道 ID 列表，机器人在这些频道中对每条消息都响应，无需提及。
  • auto_thread —— 当为 true（默认），频道中的提及会自动创建线程以保持频道整洁（类似于 Slack 的线程功能）。

安全​

执行前的安全扫描与密钥脱敏：

security:
  redact_secrets: true           # 脱敏工具输出与日志中的 API key 模式
  tirith_enabled: true           # 为终端命令启用 Tirith 安全扫描
  tirith_path: "tirith"          # Tirith 可执行文件路径（默认是 $PATH 中的 tirith）
  tirith_timeout: 5              # Tirith 扫描超时时间（秒）
  tirith_fail_open: true         # Tirith 不可用时仍允许执行命令
  website_blocklist:             # 详见下方“网站黑名单”章节
    enabled: false
    domains: []
    shared_files: []
  • redact_secrets — 自动检测并屏蔽工具输出中看起来像 API 密钥、令牌和密码的模式，在进入对话上下文和日志之前进行脱敏处理。
  • tirith_enabled — 当设置为 true 时，终端命令在执行前会通过 Tirith 扫描，以检测潜在危险操作。
  • tirith_path — Tirith 可执行文件的路径。如果 Tirith 安装在非标准位置，请设置此项。
  • tirith_timeout — 等待 Tirith 扫描的最大秒数。若扫描超时，命令仍将继续执行。
  • tirith_fail_open — 当设置为 true（默认值）时，若 Tirith 不可用或执行失败，命令仍允许执行。设置为 false 可在 Tirith 无法验证命令时阻止其执行。

网站黑名单​

阻止 Agent 的网页和浏览器工具访问特定域名：

security:
  website_blocklist:
    enabled: false               # 启用 URL 屏蔽（默认 false）
    domains:                     # 要屏蔽的域名模式列表
      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # 从外部文件加载附加规则
      - "/etc/hermes/blocked-sites.txt"

启用后，任何匹配被屏蔽域名模式的 URL 都会在网页或浏览器工具执行前被拒绝。此规则适用于 web_search、web_extract、browser_navigate 以及所有访问 URL 的工具。

域名规则支持：

  • 精确域名：admin.example.com
  • 通配符子域名：*.internal.company.com（屏蔽所有子域名）
  • 顶级域名通配符：*.local

共享文件中每行包含一个域名规则（空行和以 # 开头的注释会被忽略）。若文件缺失或无法读取，将记录警告信息，但不会禁用其他网页工具。

该策略缓存时间为 30 秒，因此配置更改无需重启即可快速生效。

智能审批​

控制 Hermes 如何处理潜在危险命令：

approvals:
  mode: manual   # 可选：manual | smart | off
模式行为
manual（默认）在执行任何被标记的命令前提示用户确认。在 CLI 中显示交互式审批对话框；在消息系统中将审批请求放入待处理队列。
smart使用辅助 LLM 评估被标记命令是否真正危险。低风险命令将自动批准，并在会话级别持久化。真正高风险命令则升级至用户确认。
off跳过所有审批检查。等价于 HERMES_YOLO_MODE=true。请谨慎使用。

智能模式特别适用于减少审批疲劳——它允许 Agent 在安全操作上更自主地运行，同时仍能捕捉真正具有破坏性的命令。

注意

将 approvals.mode: off 设置为关闭状态将禁用终端命令的所有安全检查。仅在受信任的沙箱环境中使用。

检查点​

在破坏性文件操作前自动创建文件系统快照。详情请参见 检查点与回滚。

checkpoints:
  enabled: true                  # 启用自动检查点（也可用 hermes --checkpoints）
  max_snapshots: 50              # 每个目录最多保留多少个检查点

委派​

配置委派工具的子 Agent 行为：

delegation:
  # model: "google/gemini-3-flash-preview"  # 覆盖 model（留空 = 继承父 Agent）
  # provider: "openrouter"                  # 覆盖 provider（留空 = 继承父 Agent）
  # base_url: "http://localhost:1234/v1"    # 直接指定 OpenAI 兼容端点（优先于 Provider）
  # api_key: "local-key"                    # base_url 对应的 API key（未填时回退到 OPENAI_API_KEY）

子 Agent 提供者:模型覆盖：默认情况下，子 Agent 继承父 Agent 的提供者和模型。可通过设置 delegation.provider 和 delegation.model 将子 Agent 路由至不同的提供者:模型组合——例如，对范围狭窄的子任务使用廉价快速的模型，而主 Agent 则运行成本较高的推理模型。

直接端点覆盖：若希望使用明确的自定义端点路径，请设置 delegation.base_url、delegation.api_key 和 delegation.model。这将使子 Agent 直接连接到该 OpenAI 兼容端点，并优先于 delegation.provider。若未设置 delegation.api_key，Hermes 将仅回退使用 OPENAI_API_KEY。

委派提供者使用与 CLI/网关启动时相同的凭证解析机制。所有已配置的提供者均受支持：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。设置提供者后，系统会自动解析正确的基础 URL、API 密钥和 API 模式——无需手动配置凭证。

优先级顺序：delegation.base_url（配置中）→ delegation.provider（配置中）→ 父级提供者（继承）。delegation.model（配置中）→ 父级模型（继承）。仅设置 model 而不设置 provider 时，仅更改模型名称，保留父级凭证（适用于在同一家提供者内切换模型，如 OpenRouter）。

明确化​

配置明确化提示行为：

clarify:
  timeout: 120                 # 等待用户补充说明的时长（秒）

上下文文件（SOUL.md, AGENTS.md）​

Hermes 使用两种不同的上下文作用域：

文件用途作用域
SOUL.md主 Agent 身份 —— 定义 Agent 的身份（系统提示中的第 #1 位置）~/.hermes/SOUL.md 或 $HERMES_HOME/SOUL.md
.hermes.md / HERMES.md项目特定指令（最高优先级）向上遍历至 Git 仓库根目录
AGENTS.md项目特定指令，编码规范递归目录遍历
CLAUDE.mdClaude Code 上下文文件（也支持检测）当前工作目录
.cursorrulesCursor IDE 规则（也支持检测）当前工作目录
.cursor/rules/*.mdcCursor 规则文件（也支持检测）当前工作目录
  • SOUL.md 是 Agent 的主要身份标识。它占据系统提示中的第 #1 位置，完全取代内置的默认身份。通过编辑此文件，可完全自定义 Agent 的身份。
  • 如果缺少 SOUL.md 文件、文件为空或无法加载，Hermes 将回退到内置的默认身份。
  • 项目上下文文件使用优先级系统 —— 仅加载一种类型（首个匹配项胜出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
  • AGENTS.md 具有层级结构：如果子目录中也包含 AGENTS.md，所有文件将被合并。
  • 如果不存在 SOUL.md，Hermes 会自动创建一个默认的 SOUL.md。
  • 所有加载的上下文文件均限制在 20,000 个字符以内，并采用智能截断。

另请参阅：

工作目录​

上下文默认值
CLI（hermes）运行命令时所在的当前目录
消息网关用户主目录 ~（可通过 MESSAGING_CWD 覆盖）
Docker / Singularity / Modal / SSH容器或远程机器中的用户主目录

覆盖工作目录：

# 写在 ~/.hermes/.env 或 ~/.hermes/config.yaml 中：
MESSAGING_CWD=/home/myuser/projects    # 网关会话
TERMINAL_CWD=/workspace                # 所有终端会话