配置

所有设置存储在 ~/.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。

配置优先级

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

CLI 参数 — 例如 hermes chat --model anthropic/claude-sonnet-4（每次调用的覆盖）
~/.hermes/config.yaml — 所有非密钥设置的主配置文件
~/.hermes/.env — 环境变量的后备；密钥（API 密钥、令牌、密码）必须放这里
内置默认值 — 未设置任何内容时的硬编码安全默认值

经验规则

密钥（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 提供商。

提供商超时

你可以为提供商设置 providers.<id>.request_timeout_seconds 作为全提供商请求超时，以及 providers.<id>.models.<model>.timeout_seconds 作为模型特定的覆盖。适用于每种传输（OpenAI-wire、原生 Anthropic、Anthropic-compatible）上的主轮客户端、后备链、凭据轮换后的重建，以及（对于 OpenAI-wire）每请求超时 kwarg — 因此配置的值优先于旧版 HERMES_API_TIMEOUT 环境变量。

你还可以设置 providers.<id>.stale_timeout_seconds 用于非流式过期调用检测器，以及 providers.<id>.models.<model>.stale_timeout_seconds 用于模型特定的覆盖。这优先于旧版 HERMES_API_CALL_STALE_TIMEOUT 环境变量。

不设置这些会保留旧版默认值（HERMES_API_TIMEOUT=1800 秒，HERMES_API_CALL_STALE_TIMEOUT=300 秒，原生 Anthropic 900 秒）。当前不适用于 AWS Bedrock（bedrock_converse 和 AnthropicBedrock SDK 路径都使用 boto3 及其自己的超时配置）。参见 cli-config.yaml.example 中的注释示例。

终端后端配置

Hermes 支持七种终端后端。每种后端决定 Agent 的 shell 命令实际在哪里执行 — 你的本地机器、Docker 容器、通过 SSH 的远程服务器、Modal 云沙箱（直接或通过 Nous 管理的网关）、Daytona 工作区、Vercel Sandbox 或 Singularity/Apptainer 容器。

terminal:
  backend: local    # local | docker | ssh | modal | daytona | vercel_sandbox | singularity
  cwd: "."          # 网关/定时任务工作目录（CLI 始终使用启动目录）
  timeout: 180      # 每条命令的超时（秒）
  env_passthrough: []  # 转发到沙箱执行的环境变量名（终端 + 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 和 Vercel Sandbox 等云沙箱，container_persistent: true 意味着 Hermes 将尝试在沙箱重建时保留文件系统状态。它不保证之后相同的活动沙箱、PID 空间或后台进程仍在运行。

后端概述

后端	命令运行位置	隔离	最适合
local	直接在你的机器上	无	开发、个人使用
docker	单个持久 Docker 容器（跨会话、`/new`、子 Agent 共享）	完整（命名空间、cap-drop）	安全沙箱、CI/CD
ssh	通过 SSH 的远程服务器	网络边界	远程开发、高性能硬件
modal	Modal 云沙箱	完整（云 VM）	临时云计算、评估
daytona	Daytona 工作区	完整（云容器）	托管云开发环境
vercel_sandbox	Vercel Sandbox 云 microVM	完整（云 microVM）	具有快照支持的文件系统持久性的云执行
singularity	Singularity/Apptainer 容器	命名空间（--containall）	HPC 集群、共享机器

本地后端

默认值。命令直接在你的机器上运行，无隔离。无需特殊设置。

terminal:
  backend: local

注意

Agent 拥有与你的用户账户相同的文件系统访问权限。使用 hermes tools 禁用不需要的工具，或切换到 Docker 进行沙箱化。

Docker 后端

在 Docker 容器内运行命令，具有安全加固（所有权限已丢弃，无权限提升，PID 限制）。

单个持久容器，而非每条命令。 Hermes 在首次使用时启动一个长期容器，并通过 docker exec 将所有终端、文件和 execute_code 调用路由到同一个容器中 — 跨会话、/new、/reset 和 delegate_task 子 Agent — 持续 Hermes 进程的整个生命周期。工作目录更改、已安装的包和 /workspace 中的文件会从一次工具调用延续到下一次，就像本地 shell 一样。容器在关闭时停止并删除。请参阅下面的容器生命周期。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # 将启动目录挂载到 /workspace
  docker_run_as_host_user: false   # 参见下面的"以宿主用户身份运行容器"
  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（需要 XFS+pquota 上的 overlay2）
  container_persistent: true       # 跨会话保持 /workspace 和 /root

要求： 已安装并运行 Docker Desktop 或 Docker Engine。Hermes 探测 $PATH 以及常见 macOS 安装位置（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 应用包）。支持 Podman：设置 HERMES_DOCKER_BINARY=podman（或完整路径）以在两者都安装时强制使用它。

容器生命周期： Hermes 为每个终端和文件工具调用重用单个长期容器（docker run -d ... sleep 2h），跨会话、/new、/reset 和 delegate_task 子 Agent，持续 Hermes 进程的整个生命周期。命令通过 docker exec 以登录 shell 运行，因此工作目录更改、已安装的包和 /workspace 中的文件都从一次工具调用延续到下一次。容器在 Hermes 关闭时（或空闲扫描回收时）停止并删除。

通过 delegate_task(tasks=[...]) 生成的并行子 Agent 共享这一个容器 — 并发的 cd、环境变动和对同一路径的写入会相互冲突。如果子 Agent 需要隔离的沙箱，它必须通过 register_task_env_overrides() 注册每任务镜像覆盖，RL 和基准环境（TerminalBench2、HermesSweEnv 等）会自动为其每任务 Docker 镜像执行此操作。

安全加固：

--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（如果通过 hermes config set 保存）。技能也可以声明自动合并的 required_environment_variables。

SSH 后端

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 进行连接复用（5 分钟空闲保活）。默认启用持久 shell — 状态（cwd、环境变量）在命令之间保存。

terminal:
  backend: ssh
  persistent_shell: true           # 保持长期 bash 会话（默认：true）

必需的环境变量：

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

可选：

变量	默认值	描述
`TERMINAL_SSH_PORT`	`22`	SSH 端口
`TERMINAL_SSH_KEY`	（系统默认）	SSH 私钥路径
`TERMINAL_SSH_PERSISTENT`	`true`	启用持久 shell

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

在 Modal 云沙箱中运行命令。每个任务获得一个具有可配置 CPU、内存和磁盘的隔离 VM。文件系统可以跨会话快照/恢复。

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。超过此限制的请求将被截断并显示警告。

Vercel Sandbox 后端

在 Vercel Sandbox 云 microVM 中运行命令。Hermes 使用普通终端和文件工具界面；没有 Vercel 特定的面向模型的工具。

terminal:
  backend: vercel_sandbox
  vercel_runtime: node24          # node24 | node22 | python3.13
  cwd: /vercel/sandbox            # 默认工作区根目录
  container_persistent: true      # 快照/恢复文件系统
  container_disk: 51200           # 仅共享默认值；不支持自定义磁盘

必需安装： 安装可选 SDK 额外包：

pip install 'hermes-agent[vercel]'

必需认证： 使用所有三个 VERCEL_TOKEN、VERCEL_PROJECT_ID 和 VERCEL_TEAM_ID 配置访问令牌认证。这是 Render、Railway、Docker 和类似宿主上的部署和正常长期运行 Hermes 进程的受支持设置。

对于一次性本地开发，Hermes 也接受短期 Vercel OIDC 令牌：

VERCEL_OIDC_TOKEN="$(vc project token <project-name>)" hermes chat

在已链接的 Vercel 项目目录中，可以省略项目名称：

VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat

OIDC 令牌是短期的，不应用作文档记录的部署路径。

运行时： terminal.vercel_runtime 支持 node24、node22 和 python3.13。如果未设置，Hermes 默认为 node24。

持久性： 当 container_persistent: true 时，Hermes 在清理期间对沙箱文件系统进行快照，并从该快照恢复同一任务的后续沙箱。快照内容可以包括复制到沙箱中的 Hermes 同步凭据、技能和缓存文件。这只保留文件系统状态；不保留活动沙箱身份、PID 空间、shell 状态或正在运行的后台进程。

后台命令： terminal(background=true) 使用 Hermes 的通用非本地后台进程流程。只要沙箱存活，你就可以通过普通进程工具生成、轮询、等待、查看日志和终止进程。Hermes 不提供清理或重启后的原生 Vercel 分离进程恢复。

磁盘大小： Vercel Sandbox 当前不支持 Hermes 的 container_disk 资源旋钮。将 container_disk 保持未设置或在共享默认值 51200；非默认值会使诊断和后端创建失败，而不是被静默忽略。

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       # 可写覆盖层跨会话保留

要求： $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 — 需要 $PATH 中有 apptainer 或 singularity。在 HPC 集群上很常见。

如有疑问，将 terminal.backend 设回 local，首先验证命令能在那里运行。

拆卸时远程到宿主文件同步

对于 SSH、Modal 和 Daytona 后端（Agent 工作树位于与运行 Hermes 的宿主不同的机器上），Hermes 跟踪 Agent 在远程沙箱内触碰的文件，并在会话拆卸/沙箱清理时，将修改的文件同步回宿主，存储在 ~/.hermes/cache/remote-syncs/<session-id>/ 下。

触发条件：会话关闭、/new、/reset、网关消息超时、子 Agent 使用远程后端时 delegate_task 子 Agent 完成。
覆盖 Agent 修改的整个树，而不仅仅是它明确打开的文件。添加、编辑和删除都被捕获。
当你去查找时，远程沙箱可能已被拆除；本地 ~/.hermes/cache/remote-syncs/… 副本是 Agent 更改内容的权威记录。
大型二进制输出（模型检查点、原始数据集）按大小限制 — 同步跳过超过 file_sync_max_mb（默认 100）的文件。如果期望更大的工件返回，请增加该值。

terminal:
  file_sync_max_mb: 100     # 默认 — 同步最大 100 MB 的文件
  file_sync_enabled: true   # 默认 — 设为 false 完全跳过同步

这是从会话结束后被销毁的临时云沙箱中恢复结果的方法，无需告诉 Agent 明确 scp 或 modal volume put 每个工件。

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/.hermes/cache/documents:/output" # 网关可见的导出

这对以下场景很有用：

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

如果你使用消息网关且希望 Agent 通过 MEDIA:/... 发送生成的文件，建议使用专用的宿主可见导出挂载，例如 /home/user/.hermes/cache/documents:/output。

在 Docker 内将文件写入 /output/...
在 MEDIA: 中发送宿主路径，例如：MEDIA:/home/user/.hermes/cache/documents/report.txt
不要发送 /workspace/... 或 /output/...，除非该确切路径也存在于宿主上的网关进程中

注意

YAML 重复键会静默覆盖之前的键。如果你已有 docker_volumes: 块，将新挂载合并到同一列表中，而不是在文件后面再添加一个 docker_volumes: 键。

也可以通过环境变量设置：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 config set 保存，则回退到 ~/.hermes/.env。

注意

docker_forward_env 中列出的任何内容都对容器内运行的命令可见。只转发你愿意向终端会话公开的凭据。

以宿主用户身份运行容器

默认情况下，Docker 容器以 root（UID 0）运行。在 /workspace 或其他绑定挂载内创建的文件在宿主上归 root 所有，因此会话结束后你必须执行 sudo chown 才能从宿主编辑器编辑它们。terminal.docker_run_as_host_user 标志解决了这个问题：

terminal:
  backend: docker
  docker_run_as_host_user: true   # 默认：false

启用后，Hermes 将 --user $(id -u):$(id -g) 追加到 docker run 命令，使写入绑定挂载目录（/workspace、/root、docker_volumes 中的任何内容）的文件由你的宿主用户而非 root 拥有。权衡：容器无法再 apt install 或写入 /root/.npm 等根拥有的路径 — 如果两者都需要，请使用 HOME 由非 root 用户拥有的基础镜像（或在镜像构建时添加所需工具）。

保持 false（默认）以获得向后兼容的行为。当你的工作流主要是"编辑挂载的宿主文件"且厌倦了 sudo chown -R 时，打开它。

可选：将启动目录挂载到 `/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_shell`	`true`
SSH 覆盖	`TERMINAL_SSH_PERSISTENT`	跟随配置
本地覆盖	`TERMINAL_LOCAL_PERSISTENT`	`false`

每后端环境变量具有最高优先级。如果你也想在本地后端上使用持久 shell：

export TERMINAL_LOCAL_PERSISTENT=true

备注

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

参见代码执行和 README 的终端部分了解每个后端的详细信息。

技能设置

技能可以通过其 SKILL.md frontmatter 声明自己的配置设置。这些是非密钥值（路径、首选项、域设置），存储在 config.yaml 中的 skills.config 命名空间下。

skills:
  config:
    myplugin:
      path: ~/myplugin-data   # 示例 — 每个技能定义自己的键

技能设置的工作原理：

hermes config migrate 扫描所有启用的技能，找到未配置的设置，并提供提示
hermes config show 在"技能设置"下显示所有技能设置，以及它们所属的技能
技能加载时，其解析的配置值会自动注入到技能上下文中

手动设置值：

hermes config set skills.config.myplugin.path ~/myplugin-data

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

Agent 创建技能写入的守卫

当 Agent 使用 skill_manage 创建、编辑、修补或删除技能时，Hermes 可以选择扫描新/更新内容，查找危险关键字模式（凭据收集、明显的提示注入、数据外泄指令）。扫描器默认关闭 — 合法触碰 ~/.ssh/ 或提及 $OPENAI_API_KEY 的真实 Agent 工作流触发启发式规则过于频繁。如果你希望扫描器在 Agent 的技能写入落地之前提示你，请重新打开它：

skills:
  guard_agent_created: true   # 默认：false

开启时，任何被标记的 skill_manage 写入都会显示一个带有扫描器理由的审批提示。被接受的写入落地；被拒绝的写入向 Agent 返回说明性错误。

记忆配置

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 个 token
  user_char_limit: 1375     # ~500 个 token

文件读取安全

控制单次 read_file 调用可以返回多少内容。超过限制的读取会被拒绝，并显示错误告知 Agent 使用 offset 和 limit 获取较小范围。这防止了单次读取压缩的 JS 包或大型数据文件时淹没上下文窗口。

file_read_max_chars: 100000  # 默认 — ~25-35K token

如果你使用大上下文窗口的模型且频繁读取大文件，则增加。对于小上下文模型，降低以保持读取高效：

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

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

Agent 还会自动去重文件读取 — 如果同一文件区域被读取两次且文件未更改，则返回轻量级存根而不是重新发送内容。这在上下文压缩时重置，以便 Agent 在内容被摘要后可以重新读取文件。

工具输出截断限制

三个相关的上限控制工具在 Hermes 截断前可以返回多少原始输出：

tool_output:
  max_bytes: 50000        # 终端输出上限（字符）
  max_lines: 2000         # read_file 分页上限
  max_line_length: 2000   # read_file 行号视图中的每行上限

max_bytes — 当 terminal 命令产生超过此字符数的组合 stdout/stderr 时，Hermes 保留前 40% 和后 60%，并在它们之间插入 [OUTPUT TRUNCATED] 提示。默认 50000（跨典型分词器约 12-15K token）。
max_lines — 单次 read_file 调用的 limit 参数上限。超过此限制的请求会被截断，防止单次读取淹没上下文窗口。默认 2000。
max_line_length — read_file 发出行号视图时应用的每行上限。超过此字符数的行会被截断，后跟 ... [truncated]。默认 2000。

对于大上下文窗口且每次调用可以承受更多原始输出的模型，增加限制。对于小上下文模型，降低以保持工具结果紧凑：

# 大上下文模型（200K+）
tool_output:
  max_bytes: 150000
  max_lines: 5000

# 小本地模型（16K 上下文）
tool_output:
  max_bytes: 20000
  max_lines: 500

全局工具集禁用

要在一个地方跨 CLI 和每个网关平台禁用特定工具集，在 agent.disabled_toolsets 下列出其名称：

agent:
  disabled_toolsets:
    - memory       # 隐藏记忆工具 + MEMORY_GUIDANCE 注入
    - web          # 任何地方都没有 web_search / web_extract

这在每平台工具配置（hermes tools 写入的 platform_toolsets）之后应用，因此此处列出的工具集始终被删除 — 即使平台的保存配置仍然列出它。当你想要一个"到处关闭 X"的单一开关，而不是编辑 15 个以上平台行时使用此功能。

留空列表，或省略键，是无操作。

Git 工作树隔离

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

worktree: true    # 始终创建工作树（与 hermes -w 相同）
# worktree: false # 默认 — 仅在传入 -w 标志时

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

你也可以通过仓库根目录中的 .worktreeinclude 列出要复制到工作树中的 gitignore 文件：

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩

Hermes 自动压缩长对话以保持在模型的上下文窗口内。压缩摘要器是单独的 LLM 调用 — 你可以将其指向任何提供商或端点。

所有压缩设置都在 config.yaml 中（无环境变量）。

完整参考

compression:
  enabled: true                                     # 切换压缩开/关
  threshold: 0.50                                   # 在上下文限制的此百分比时压缩
  target_ratio: 0.20                                # 要保留为最近尾部的阈值比例
  protect_last_n: 20                                # 保持未压缩的最少最近消息数
  hygiene_hard_message_limit: 400                   # 网关安全阀 — 见下文

# 摘要模型/提供商配置在 auxiliary: 下：
auxiliary:
  compression:
    model: "google/gemini-3-flash-preview"          # 摘要模型
    provider: "auto"                                # 提供商："auto"、"openrouter"、"nous"、"codex"、"main" 等
    base_url: null                                  # 自定义 OpenAI 兼容端点（覆盖提供商）

旧版配置迁移

具有 compression.summary_model、compression.summary_provider 和 compression.summary_base_url 的旧版配置在首次加载时自动迁移到 auxiliary.compression.*（配置版本 17）。无需手动操作。

hygiene_hard_message_limit 是仅限网关的预压缩安全阀。有数千条消息的失控会话可能在正常的上下文百分比阈值触发之前就达到模型上下文限制；当消息数量超过此上限时，Hermes 强制压缩而不考虑 token 使用量。默认 400 — 对于非常长的会话正常的平台，增加它；降低以强制更激进的压缩。在正在运行的网关上编辑此值会在下一条消息时生效（见下文）。

压缩和上下文长度的网关热重载

从最近的版本开始，在正在运行的网关上编辑 config.yaml 中的 model.context_length 或任何 compression.* 键会在下一条消息时生效 — 无需网关重启、/reset 或会话轮换。缓存的 Agent 签名包含这些键，因此网关在检测到变化时透明地重建 Agent。API 密钥和工具/技能配置仍需要通常的重载路径。

常见设置

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

compression:
  enabled: true
  threshold: 0.50

使用你的主提供商和主模型。如果你希望在比主聊天模型更便宜的模型上进行压缩，可以覆盖每个任务（例如 auxiliary.compression.provider: openrouter + model: google/gemini-2.5-flash）。

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

auxiliary:
  compression:
    provider: nous
    model: gemini-3-flash

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

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

auxiliary:
  compression:
    model: glm-4.7
    base_url: https://api.z.ai/api/coding/paas/v4

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

三个旋钮的交互方式

`auxiliary.compression.provider`	`auxiliary.compression.base_url`	结果
`auto`（默认）	未设置	自动检测最佳可用提供商
`nous` / `openrouter` / 等	未设置	强制该提供商，使用其认证
任意	已设置	直接使用自定义端点（忽略提供商）

摘要模型上下文长度要求

摘要模型必须具有至少与主 Agent 模型一样大的上下文窗口。压缩器将对话的完整中间部分发送到摘要模型 — 如果该模型的上下文窗口比主模型小，摘要调用将因上下文长度错误而失败。当发生这种情况时，中间轮次被丢弃而不生成摘要，静默丢失对话上下文。如果你覆盖模型，请验证其上下文长度是否符合或超过主模型的。

上下文引擎

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

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

使用插件引擎（例如用于无损上下文管理的 LCM）：

context:
  engine: "lcm"          # 必须与插件名称匹配

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

参见记忆提供商了解记忆插件的类似单选系统。

迭代预算压力

当 Agent 处理有许多工具调用的复杂任务时，它可能在没有意识到即将耗尽的情况下烧完其迭代预算（默认：90 轮）。预算压力在 Agent 接近限制时自动发出警告：

阈值	级别	模型看到的内容
70%	注意	`[BUDGET: 63/90. 27 iterations left. Start consolidating.]`
90%	警告	`[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]`

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

agent:
  max_turns: 90                # 每次对话轮的最大迭代次数（默认：90）
  api_max_retries: 2           # 后备参与前每个提供商的重试次数（默认：2）

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

当迭代预算完全耗尽时，CLI 向用户显示通知：⚠ Iteration budget reached (90/90) — response may be incomplete。如果预算在活跃工作期间耗尽，Agent 会在停止前生成已完成工作的摘要。

agent.api_max_retries 控制 Hermes 在瞬态错误（速率限制、连接中断、5xx）上重试提供商 API 调用的次数，在后备提供商切换参与之前。默认是 2 — 总共三次尝试，与 OpenAI SDK 默认值匹配。如果你配置了后备提供商并希望更快地故障转移，将此降至 0，这样主提供商上的第一个瞬态错误就会立即交给后备，而不是在不稳定的端点上进行重试。

API 超时

Hermes 为流式传输提供单独的超时层，并为非流式调用提供过期检测器。仅当你保持隐式默认值时，过期检测器才会为本地提供商自动调整。

超时	默认值	本地提供商	配置/环境变量
套接字读取超时	120 秒	自动提升至 1800 秒	`HERMES_STREAM_READ_TIMEOUT`
过期流检测	180 秒	自动禁用	`HERMES_STREAM_STALE_TIMEOUT`
过期非流检测	300 秒	保持隐式时自动禁用	`providers.<id>.stale_timeout_seconds` 或 `HERMES_API_CALL_STALE_TIMEOUT`
API 调用（非流式）	1800 秒	不变	`providers.<id>.request_timeout_seconds` / `timeout_seconds` 或 `HERMES_API_TIMEOUT`

套接字读取超时控制 httpx 等待来自提供商的下一块数据的时间。本地 LLM 在产生第一个 token 之前可能需要几分钟对大上下文进行预填充，因此当检测到本地端点时，Hermes 将此超时提升至 30 分钟。如果你明确设置 HERMES_STREAM_READ_TIMEOUT，该值始终被使用，不考虑端点检测。

过期流检测终止接收 SSE 保活 ping 但没有实际内容的连接。这对本地提供商完全禁用，因为它们在预填充期间不发送保活 ping。

过期非流检测终止长时间没有响应的非流式调用。默认情况下，Hermes 在本地端点上禁用此功能以避免长预填充期间的误报。如果你明确设置 providers.<id>.stale_timeout_seconds、providers.<id>.models.<model>.stale_timeout_seconds 或 HERMES_API_CALL_STALE_TIMEOUT，即使在本地端点上也会遵守该明确值。

上下文压力警告

与迭代预算压力分开，上下文压力追踪对话距压缩阈值有多近 — 上下文压缩触发以摘要旧消息的点。这帮助你和 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    # 均匀循环密钥
  anthropic: least_used      # 始终选择使用最少的密钥

选项：fill_first（默认）、round_robin、least_used、random。完整文档参见凭据池。

辅助模型

Hermes 使用"辅助"模型处理侧边任务，如图像分析、网页摘要、浏览器截图分析、会话标题生成和上下文压缩。默认情况下（auxiliary.*.provider: "auto"），Hermes 将每个辅助任务路由到你的主聊天模型 — 与你在 hermes model 中选择的提供商/模型相同。你无需配置任何内容即可开始，但请注意，在昂贵的推理模型（Opus、MiniMax M2.7 等）上，辅助任务会增加相当的成本。如果你希望侧边任务便宜且快速，无论主模型如何，请显式设置 auxiliary.<task>.provider 和 auxiliary.<task>.model（例如，OpenRouter 上的 Gemini Flash 用于视觉和网络提取）。

为什么"auto"使用主模型

早期版本将聚合器用户（OpenRouter、Nous Portal）拆分到提供商侧的廉价默认值。这让人意外 — 支付聚合器订阅的用户会看到不同的模型处理辅助流量。auto 现在对所有人使用主模型，config.yaml 中的每任务覆盖仍然优先（见下面的完整辅助配置参考）。

交互式配置辅助模型

不要手动编辑 YAML，而是运行 hermes model 并从菜单中选择**"配置辅助模型"**。你将获得一个交互式的每任务选择器：

$ hermes model
→ Configure auxiliary models

[ ] vision               currently: auto / main model
[ ] web_extract          currently: auto / main model
[ ] session_search       currently: openrouter / google/gemini-2.5-flash
[ ] title_generation     currently: openrouter / google/gemini-3-flash-preview
[ ] compression          currently: auto / main model
[ ] approval             currently: auto / main model
[ ] triage_specifier     currently: auto / main model

选择一个任务，选择一个提供商（OAuth 流程打开浏览器；API 密钥提供商会提示），选择一个模型。更改持久保存到 config.yaml 中的 auxiliary.<task>.*。与主模型选择器相同的机制 — 无需学习额外语法。

视频教程

通用配置模式

Hermes 中的每个模型槽 — 辅助任务、压缩、后备 — 使用相同的三个旋钮：

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

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

辅助任务的可用提供商：auto、main，加上提供商注册表中的任何提供商 — openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、gemini、google-gemini-cli、qwen-oauth、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、ollama-cloud、alibaba、bedrock、huggingface、arcee、xiaomi、kilocode、opencode-zen、opencode-go、ai-gateway、azure-foundry — 或 custom_providers 列表中任何命名的自定义提供商（例如 provider: "beans"）。

MiniMax OAuth

minimax-oauth 通过浏览器 OAuth 登录（无需 API 密钥）。运行 hermes model 并选择 MiniMax（OAuth） 进行认证。辅助任务自动使用 MiniMax-M2.7-highspeed。参见 MiniMax OAuth 指南。

"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 兼容端点（覆盖提供商）
    api_key: ""                # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
    timeout: 120               # 秒 — 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
    max_concurrency: 3       # 限制并行摘要以减少请求突发 429
    extra_body: {}           # 特定提供商的 OpenAI 兼容请求字段

  # 技能中心 — 技能匹配和搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

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

  # 看板 triage 规格化器 — `hermes kanban specify <id>`（或仪表板
  # Triage 列卡片上的 ✨ Specify 按钮）使用此槽位将一行描述扩展
  # 为完整规格并将任务提升为 `todo`。便宜的快速模型在此表现良好；
  # 规格扩展内容较短，不需要深度推理。
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

提示

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

信息

上下文压缩有自己的 compression: 块用于阈值，以及 auxiliary.compression: 块用于模型/提供商设置 — 参见上面的上下文压缩。后备模型使用 fallback_model: 块 — 参见后备模型。所有三者都遵循相同的 provider/model/base_url 模式。

会话搜索调优

如果你为 auxiliary.session_search 使用推理密集型模型，Hermes 现在提供两个内置控件：

auxiliary.session_search.max_concurrency：限制 Hermes 同时摘要多少匹配的会话
auxiliary.session_search.extra_body：在摘要调用上转发特定提供商的 OpenAI 兼容请求字段

示例：

auxiliary:
  session_search:
    provider: "main"
    model: "glm-4.5-air"
    timeout: 60
    max_concurrency: 2
    extra_body:
      enable_thinking: false

当你的提供商限制请求突发且你希望 session_search 用一些并行性换取稳定性时，使用 max_concurrency。

仅当你的提供商记录了你想让 Hermes 为该任务传递的 OpenAI 兼容请求体字段时，才使用 extra_body。Hermes 按原样转发对象。

注意

extra_body 仅在你的提供商实际支持你发送的字段时有效。如果提供商不公开原生的 OpenAI 兼容推理关闭标志，Hermes 无法代表它合成一个。

更改视觉模型

使用 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 Portal	`hermes auth`
`"codex"`	强制 Codex OAuth（ChatGPT 账户）。支持视觉（gpt-5.3-codex）。	`hermes model` → Codex
`"minimax-oauth"`	强制 MiniMax OAuth（浏览器登录，无需 API 密钥）。辅助任务使用 MiniMax-M2.7-highspeed。	`hermes model` → MiniMax (OAuth)
`"main"`	使用你的活动自定义/主端点。可以来自 `OPENAI_BASE_URL` + `OPENAI_API_KEY` 或通过 `hermes model` / `config.yaml` 保存的自定义端点。适用于 OpenAI、本地模型或任何 OpenAI 兼容 API。仅辅助任务 — 不适用于 `model.provider`。	自定义端点凭据 + 基础 URL

当你希望侧边任务绕过默认路由器时，主提供商目录中的直接 API 密钥提供商也可以在这里使用。配置 GMI_API_KEY 后，gmi 有效：

auxiliary:
  compression:
    provider: "gmi"
    model: "anthropic/claude-opus-4.6"

对于 GMI 辅助路由，使用 GMI 的 /v1/models 端点返回的精确模型 ID。

常见设置

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

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（支持视觉）

使用 MiniMax OAuth（浏览器登录，无需 API 密钥）：

model:
  default: MiniMax-M2.7
  provider: minimax-oauth
  base_url: https://api.minimax.io/anthropic

运行 hermes model 并选择 MiniMax（OAuth） 自动登录并设置此项。对于中国区域，基础 URL 将是 https://api.minimaxi.com/anthropic。完整步骤参见 MiniMax OAuth 指南。

使用本地/自托管模型：

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: ""   # 空 = 中等（默认）。选项：none、minimal、low、medium、high、xhigh（最大）

当未设置（默认）时，推理努力默认为"medium" — 一个对大多数任务效果良好的平衡级别。设置值会覆盖它 — 更高的推理努力在复杂任务上给出更好的结果，但代价是更多 token 和延迟。

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

/reasoning           # 显示当前努力级别和显示状态
/reasoning high      # 将推理努力设为高
/reasoning none      # 禁用推理
/reasoning show      # 在每次响应上方显示模型思考
/reasoning hide      # 隐藏模型思考

工具使用强制

某些模型偶尔将预期操作描述为文本，而不是进行工具调用（"我会运行测试……"而不是实际调用终端）。工具使用强制注入系统提示指导，引导模型实际调用工具。

agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]

值	行为
`"auto"`（默认）	为匹配以下模型启用：`gpt`、`codex`、`gemini`、`gemma`、`grok`。对所有其他模型禁用（Claude、DeepSeek、Qwen 等）。
`true`	始终启用，不考虑模型。如果你注意到当前模型描述操作而不是执行它们，则很有用。
`false`	始终禁用，不考虑模型。
`["gpt", "codex", "qwen", "llama"]`	仅当模型名称包含列出的子字符串之一时启用（不区分大小写）。

注入的内容

启用后，最多可以在系统提示中添加三层指导：

通用工具使用强制（所有匹配模型）— 指示模型立即进行工具调用而不是描述意图，持续工作直到任务完成，绝不以未来行动的承诺结束轮次。
OpenAI 执行纪律（仅 GPT 和 Codex 模型）— 针对 GPT 特有故障模式的额外指导：在部分结果上放弃工作、跳过先决条件查找、幻觉而不是使用工具，以及在没有验证的情况下宣布"完成"。
Google 操作指导（仅 Gemini 和 Gemma 模型）— 简洁性、绝对路径、并行工具调用和在编辑前验证的模式。

这些对用户透明，只影响系统提示。已经可靠使用工具的模型（如 Claude）不需要此指导，这就是为什么 "auto" 排除它们的原因。

何时打开

如果你使用的模型不在默认自动列表中，并注意到它频繁描述它会做什么而不是做它，将 tool_use_enforcement: true 或将模型子字符串添加到列表中：

agent:
  tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"]

TTS 配置

tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts"
  speed: 1.0                    # 全局速度乘数（所有提供商的后备）
  edge:
    voice: "en-US-AriaNeural"   # 322 个声音，74 种语言
    speed: 1.0                  # 速度乘数（转换为速率百分比，例如 1.5 → +50%）
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy、echo、fable、onyx、nova、shimmer
    speed: 1.0                  # 速度乘数（API 限制为 0.25–4.0）
    base_url: "https://api.openai.com/v1"  # OpenAI 兼容 TTS 端点的覆盖
  minimax:
    speed: 1.0                  # 语音速度乘数
    # base_url: ""              # 可选：OpenAI 兼容 TTS 端点的覆盖
  mistral:
    model: "voxtral-mini-tts-2603"
    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul - 中性（默认）
  gemini:
    model: "gemini-2.5-flash-preview-tts"   # 或 gemini-2.5-pro-preview-tts
    voice: "Kore"               # 30 个预建声音：Zephyr、Puck、Kore、Enceladus 等
  xai:
    voice_id: "eve"             # xAI TTS 声音
    language: "en"              # ISO 639-1
    sample_rate: 24000
    bit_rate: 128000            # MP3 比特率
    # base_url: "https://api.x.ai/v1"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

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

速度后备层级： 提供商特定速度（例如 tts.edge.speed）→ 全局 tts.speed → 1.0 默认值。设置全局 tts.speed 跨所有提供商应用统一速度，或按提供商覆盖以进行细粒度控制。

显示设置

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # 在消息网关中启用 /verbose 斜杠命令
  platforms: {}           # 每平台显示覆盖（见下文）
  tool_progress_overrides: {}  # 已弃用 — 改用 display.platforms
  interim_assistant_messages: true  # 网关：将自然的中途 Agent 更新作为单独消息发送
  skin: default           # 内置或自定义 CLI 皮肤（参见 user-guide/features/skins）
  personality: "kawaii"  # 旧版外观字段，仍在某些摘要中显示
  compact: false          # 紧凑输出模式（更少空白）
  resume_display: full    # full（恢复时显示之前消息）| minimal（仅一行）
  bell_on_complete: false # 代理完成时播放终端铃声（非常适合长任务）
  show_reasoning: false   # 在每次响应上方显示模型推理/思考（用 /reasoning show|hide 切换）
  streaming: false        # 令牌到达时流式传输到终端（实时输出）
  show_cost: false        # 在 CLI 状态栏中显示估计 $ 成本
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 无限制，显示完整路径/命令）
  runtime_metadata_footer: false  # 网关：在最终回复中附加运行时上下文页脚
  language: en            # 静态消息的 UI 语言（审批提示、某些网关回复）。en | zh | ja | de | es | fr | tr | uk

静态消息的 UI 语言

display.language 设置翻译少量静态面向用户的消息 — CLI 审批提示、少数网关斜杠命令回复（例如重启排空通知、"审批过期"、"目标已清除"）。它不翻译 Agent 响应、日志行、工具输出、错误回溯或斜杠命令描述 — 这些保持英文。如果你希望 Agent 本身用另一种语言回复，只需在提示或系统消息中告诉它。

支持的值：en（默认）、zh（简体中文）、ja（日语）、de（德语）、es（西班牙语）、fr（法语）、tr（土耳其语）、uk（乌克兰语）。未知值回退到英语。

你也可以用 HERMES_LANGUAGE 环境变量按会话设置，它会覆盖配置值。

display:
  language: zh   # CLI 审批提示以中文显示

模式	你看到的内容
`off`	静默 — 只有最终响应
`new`	工具更改时仅显示工具指示器
`all`	每次工具调用加短预览（默认）
`verbose`	完整参数、结果和调试日志

在 CLI 中，使用 /verbose 循环这些模式。要在消息平台（Telegram、Discord、Slack 等）中使用 /verbose，在上面的 display 部分设置 tool_progress_command: true。命令将循环模式并保存到配置。

运行时元数据页脚（仅限网关）

当 display.runtime_metadata_footer: true 时，Hermes 在每次网关轮次的最终消息中附加一个小的运行时上下文页脚 — 与 CLI 状态栏显示的相同信息（模型、会话持续时间、token、成本）。默认关闭；如果你的团队希望每次回复都包含来源信息，可按网关选择启用。

display:
  runtime_metadata_footer: true

附加到 Telegram/Discord/Slack 回复的页脚示例：

— claude-opus-4.7 · 12 tool calls · 2m 14s · $0.042

只有轮次的最终消息会有页脚；中途更新保持干净。

每平台进度覆盖

不同平台有不同的详细程度需求。例如，Signal 无法编辑消息，因此每次进度更新都会成为单独的消息 — 很嘈杂。使用 display.platforms 设置每平台模式：

display:
  tool_progress: all          # 全局默认
  platforms:
    signal:
      tool_progress: 'off'    # Signal 上静默进度
    telegram:
      tool_progress: verbose  # Telegram 上详细进度
    slack:
      tool_progress: 'off'    # 共享 Slack 工作区中安静

没有覆盖的平台回退到全局 tool_progress 值。有效平台键：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot。旧版 display.tool_progress_overrides 键仍然加载以向后兼容，但已弃用，并在首次加载时迁移到 display.platforms。

interim_assistant_messages 仅限网关。启用后，Hermes 将已完成的中途 Agent 更新作为单独的聊天消息发送。这独立于 tool_progress，不需要网关流式传输。

隐私

privacy:
  redact_pii: false  # 从 LLM 上下文中去除 PII（仅限网关）

当 redact_pii 为 true 时，网关在将系统提示发送到 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" | "mistral"
  local:
    model: "base"              # tiny、base、small、medium、large-v3
  openai:
    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  # 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 on 时自动启用语音回复
  beep_enabled: true            # CLI 语音模式中播放录音开始/停止提示音
  silence_threshold: 200        # 语音检测的 RMS 阈值
  silence_duration: 3.0         # 自动停止前的静默秒数

在 CLI 中使用 /voice on 启用麦克风模式，使用 record_key 开始/停止录音，使用 /voice tts 切换语音回复。端到端设置和平台特定行为参见语音模式。

流式传输

将令牌实时流式传输到终端或消息平台，而不是等待完整响应。

CLI 流式传输

display:
  streaming: true         # 实时将令牌流式传输到终端
  show_reasoning: true    # 同时流式传输推理/思考令牌（可选）

启用后，响应在流式传输框内逐令牌显示。工具调用仍然静默捕获。如果提供商不支持流式传输，它会自动回退到正常显示。

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

streaming:
  enabled: true           # 启用渐进式消息编辑
  transport: edit         # "edit"（渐进式消息编辑）或 "off"
  edit_interval: 0.3      # 消息编辑之间的秒数
  buffer_threshold: 40    # 强制编辑刷新前的字符数
  cursor: " ▉"            # 流式传输期间显示的光标
  fresh_final_after_seconds: 60   # 当预览超过此旧时发送新最终消息（Telegram）；0 = 始终原地编辑

启用后，机器人在第一个令牌时发送消息，然后随着更多令牌到来渐进式编辑。不支持消息编辑的平台（Signal、Email、Home Assistant）在第一次尝试时自动检测 — 该会话的流式传输优雅地禁用，不会产生大量消息。

对于不使用渐进式令牌编辑的独立自然中途 Agent 更新，设置 display.interim_assistant_messages: true。

溢出处理： 如果流式传输的文本超过平台的消息长度限制（约 4096 字符），当前消息会被最终确定，并自动开始新消息。

新鲜最终（Telegram）： Telegram 的 editMessageText 保留原始消息时间戳，因此长时间运行的流式回复即使在完成后也会保留第一个令牌的时间戳。当 fresh_final_after_seconds > 0（默认 60）时，已完成的回复作为全新消息发送（尽力删除过时预览），这样 Telegram 的可见时间戳就反映了完成时间。短预览仍然原地最终确定。设为 0 始终原地编辑。

备注

流式传输默认禁用。在 ~/.hermes/config.yaml 中启用它以试用流式传输 UX。

群聊会话隔离

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

group_sessions_per_user: true  # true = 群/频道中每用户隔离，false = 每个聊天一个共享会话

true 是默认值和推荐设置。在 Discord 频道、Telegram 群组、Slack 频道和类似共享上下文中，当平台提供用户 ID 时，每个发送者都有自己的会话。
false 恢复到旧的共享房间行为。如果你明确希望 Hermes 将频道视为一个协作对话，这可能很有用，但这也意味着用户共享上下文、token 成本和中断状态。
私信不受影响。Hermes 仍然像往常一样通过聊天/DM ID 键控 DM。
主题在任何情况下都与其父频道隔离；对于 true，每个参与者在主题内也有自己的会话。

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

未授权 DM 行为

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair 是默认值。Hermes 拒绝访问，但在私信中回复一次性配对代码。
ignore 静默丢弃未授权的私信。
平台部分覆盖全局默认值，因此你可以在广泛保持配对启用的同时使一个平台更安静。

快速命令

定义自定义命令，这些命令要么在不调用 LLM 的情况下运行 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
  restart:
    type: alias
    target: /gateway restart

用法：在 CLI 或任何消息平台中键入 /status、/disk、/update、/gpu 或 /restart。exec 命令在宿主本地运行并直接返回输出 — 无 LLM 调用，不消耗 token。alias 命令重写到配置的斜杠命令目标。

30 秒超时 — 长时间运行的命令会被终止并显示错误消息
优先级 — 快速命令在技能命令之前检查，因此你可以覆盖技能名称
自动完成 — 快速命令在调度时解析，不显示在内置斜杠命令自动完成表中
类型 — 支持的类型是 exec 和 alias；其他类型显示错误
适用于任何地方 — CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

仅字符串的提示快捷方式不是有效的快速命令。对于可重用的提示工作流，创建技能或别名到现有的斜杠命令。

人类延迟

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

human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # 最小延迟（自定义模式）
  max_ms: 2500                 # 最大延迟（自定义模式）

代码执行

配置 execute_code 工具：

code_execution:
  mode: project                # project（默认）| strict
  timeout: 300                 # 最大执行时间（秒）
  max_tool_calls: 50           # 代码执行中的最大工具调用次数

mode 控制脚本的工作目录和 Python 解释器：

project（默认）— 脚本在会话工作目录中以活动 virtualenv/conda 环境的 python 运行。项目依赖（pandas、torch、项目包）和相对路径（.env、./data.csv）自然解析，与 terminal() 看到的一致。
strict — 脚本在临时暂存目录中以 sys.executable（Hermes 自己的 python）运行。最大可重现性，但项目依赖和相对路径不会解析。

环境清理（去除 *_API_KEY、*_TOKEN、*_SECRET、*_PASSWORD、*_CREDENTIAL、*_PASSWD、*_AUTH）和工具白名单在两种模式下都同样适用 — 切换模式不会改变安全态势。

网络搜索后端

web_search、web_extract 和 web_crawl 工具支持五个后端提供商。在 config.yaml 中配置后端或通过 hermes tools：

web:
  backend: firecrawl    # firecrawl | searxng | parallel | tavily | exa

  # 或使用每功能键混合提供商（例如免费搜索 + 付费提取）：
  search_backend: "searxng"
  extract_backend: "firecrawl"

后端	环境变量	搜索	提取	爬取
Firecrawl（默认）	`FIRECRAWL_API_KEY`	✔	✔	✔
SearXNG	`SEARXNG_URL`	✔	—	—
Parallel	`PARALLEL_API_KEY`	✔	✔	—
Tavily	`TAVILY_API_KEY`	✔	✔	✔
Exa	`EXA_API_KEY`	✔	✔	—

后端选择： 如果未设置 web.backend，后端从可用 API 密钥自动检测。如果只设置了 SEARXNG_URL，使用 SearXNG。如果只设置了 EXA_API_KEY，使用 Exa。如果只设置了 TAVILY_API_KEY，使用 Tavily。如果只设置了 PARALLEL_API_KEY，使用 Parallel。否则 Firecrawl 是默认值。

SearXNG 是一个免费、自托管、尊重隐私的元搜索引擎，查询 70 多个搜索引擎。无需 API 密钥 — 只需将 SEARXNG_URL 设置为你的实例（例如 http://localhost:8080）。SearXNG 仅用于搜索；web_extract 和 web_crawl 需要单独的提取提供商（设置 web.extract_backend）。有关 Docker 设置说明，参见网络搜索设置指南。

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

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

Exa： 在 ~/.hermes/.env 中设置 EXA_API_KEY。支持 category 过滤（company、research paper、news、people、personal site、pdf）和域/日期过滤器。

浏览器

配置浏览器自动化行为：

browser:
  inactivity_timeout: 120        # 自动关闭空闲会话前的秒数
  command_timeout: 30             # 浏览器命令的超时（秒）（截图、导航等）
  record_sessions: false         # 自动将浏览器会话录制为 WebM 视频到 ~/.hermes/browser_recordings/
  # 可选 CDP 覆盖 — 设置后，Hermes 直接附加到你自己的
  # Chrome（通过 /browser connect）而不是启动无头浏览器。
  cdp_url: ""
  # 对话框监管器 — 控制当附加 CDP 后端（Browserbase、通过
  # /browser connect 的本地 Chrome）时如何处理原生 JS 对话框（alert / confirm / prompt）。
  # 在 Camofox 和默认本地 Agent 浏览器模式下忽略。
  dialog_policy: must_respond    # must_respond | auto_dismiss | auto_accept
  dialog_timeout_s: 300          # must_respond 下的安全自动关闭（秒）
  camofox:
    managed_persistence: false   # 为 true 时，Camofox 会话跨重启保留 cookie/登录

对话框策略：

must_respond（默认）— 捕获对话框，在 browser_snapshot.pending_dialogs 中显示，并等待 Agent 调用 browser_dialog(action=...)。dialog_timeout_s 秒后没有响应，对话框会自动关闭以防止页面的 JS 线程永远停滞。
auto_dismiss — 捕获，立即关闭。Agent 仍然在事后的 browser_snapshot.recent_dialogs 中看到对话框记录，closed_by="auto_policy"。
auto_accept — 捕获，立即接受。适用于有激进 beforeunload 提示的页面。

有关完整对话框工作流，参见浏览器功能页面。

浏览器工具集支持多个提供商。有关 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          # 在服务器频道中需要 @mention 才响应
  free_response_channels: ""     # 逗号分隔的频道 ID，机器人在这些频道无需 @mention 即可响应
  auto_thread: true              # 在频道中 @mention 时自动创建主题

require_mention — 当为 true（默认）时，机器人只有在提到 @BotName 时才在服务器频道中响应。私信始终无需提及即可工作。
free_response_channels — 逗号分隔的频道 ID 列表，机器人在这些频道响应每条消息，无需提及。
auto_thread — 当为 true（默认）时，频道中的提及会自动创建一个对话主题，保持频道整洁（类似于 Slack 主题功能）。

安全

执行前安全扫描和密钥去除：

security:
  redact_secrets: false          # 去除工具输出和日志中的 API 密钥模式（默认关闭）
  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 — 当为 true 时，自动检测并去除工具输出中看起来像 API 密钥、令牌和密码的模式，在其进入对话上下文和日志之前。默认关闭 — 如果你常常在工具输出中处理真实凭据并希望有安全网，则启用。显式设置为 true 打开。
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（阻止所有子域）
TLD 通配符：*.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"  # 覆盖模型（空 = 继承父级）
  # provider: "openrouter"                  # 覆盖提供商（空 = 继承父级）
  # base_url: "http://localhost:1234/v1"    # 直接 OpenAI 兼容端点（优先于提供商）
  # api_key: "local-key"                    # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
  max_concurrent_children: 3                # 每批并行子 Agent（下限 1，无上限）。也可通过 DELEGATION_MAX_CONCURRENT_CHILDREN 环境变量设置。
  max_spawn_depth: 1                        # 委派树深度上限（1-3，已截断）。1 = 平坦（默认）：父级生成无法委派的叶子。2 = 编排器子级可以生成叶子孙级。3 = 三层。
  orchestrator_enabled: true                # 全局终止开关。为 false 时，role="orchestrator" 被忽略，每个子级都被强制为叶子，不考虑 max_spawn_depth。

子 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 内切换模型很有用）。

宽度和深度： max_concurrent_children 限制每批并行运行多少子 Agent（默认 3，下限 1，无上限）。也可以通过 DELEGATION_MAX_CONCURRENT_CHILDREN 环境变量设置。当模型提交的 tasks 数组超过上限时，delegate_task 返回一个解释限制的工具错误，而不是静默截断。max_spawn_depth 控制委派树深度（截断到 1-3）。在默认 1 时，委派是平坦的：子级不能生成孙级，传递 role="orchestrator" 静默降级为 leaf。提升到 2 使编排器子级可以生成叶子孙级；3 用于三层树。Agent 通过调用时的 role="orchestrator" 选择编排；orchestrator_enabled: false 强制每个子级回到叶子，不考虑设置。成本乘法增加 — 在 max_spawn_depth: 3 和 max_concurrent_children: 3 时，树可以达到 3×3×3 = 27 个并发叶子 Agent。参见子 Agent 委派 → 深度限制和嵌套编排了解使用模式。

澄清

配置澄清提示行为：

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.md`	Claude Code 上下文文件（也被检测）	仅工作目录
`.cursorrules`	Cursor IDE 规则（也被检测）	仅工作目录
`.cursor/rules/*.mdc`	Cursor 规则文件（也被检测）	仅工作目录

SOUL.md 是 Agent 的主要身份。它占据系统提示的第 1 槽，完全替换内置的默认身份。编辑它可以完全自定义 Agent 是谁。
如果 SOUL.md 缺失、空或无法加载，Hermes 回退到内置的默认身份。
项目上下文文件使用优先级系统 — 只加载一种类型（第一个匹配获胜）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
AGENTS.md 是分层的：如果子目录也有 AGENTS.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                # 所有终端会话

目录结构​

管理配置​

配置优先级​

环境变量替换​

提供商超时​

终端后端配置​

后端概述​

本地后端​

Docker 后端​

SSH 后端​

Modal 后端​

Daytona 后端​

Vercel Sandbox 后端​

Singularity/Apptainer 后端​

常见终端后端问题​

拆卸时远程到宿主文件同步​

Docker 卷挂载​

Docker 凭据转发​

以宿主用户身份运行容器​

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

持久 Shell​

技能设置​

Agent 创建技能写入的守卫​

记忆配置​

文件读取安全​

工具输出截断限制​

全局工具集禁用​

Git 工作树隔离​

上下文压缩​

完整参考​

常见设置​

三个旋钮的交互方式​

上下文引擎​

迭代预算压力​

API 超时​

上下文压力警告​

凭据池策略​

辅助模型​

交互式配置辅助模型​

视频教程​

通用配置模式​

完整辅助配置参考​

会话搜索调优​

更改视觉模型​

提供商选项​

常见设置​

环境变量（旧版）​

推理努力​

工具使用强制​

注入的内容​

何时打开​

TTS 配置​

显示设置​

静态消息的 UI 语言​

运行时元数据页脚（仅限网关）​

每平台进度覆盖​

隐私​

语音转文字（STT）​

语音模式（CLI）​

流式传输​

CLI 流式传输​

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

群聊会话隔离​

未授权 DM 行为​

快速命令​

人类延迟​

代码执行​

网络搜索后端​

浏览器​

时区​

Discord​

安全​

网站黑名单​

智能审批​

检查点​

委派​

澄清​

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

工作目录​

目录结构

管理配置

配置优先级

环境变量替换

提供商超时

终端后端配置

后端概述

本地后端

Docker 后端

SSH 后端

Modal 后端

Daytona 后端

Vercel Sandbox 后端

Singularity/Apptainer 后端

常见终端后端问题

拆卸时远程到宿主文件同步

Docker 卷挂载

Docker 凭据转发

以宿主用户身份运行容器

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

持久 Shell

技能设置

Agent 创建技能写入的守卫

记忆配置

文件读取安全

工具输出截断限制

全局工具集禁用

Git 工作树隔离

上下文压缩

完整参考

常见设置

三个旋钮的交互方式

上下文引擎

迭代预算压力

API 超时

上下文压力警告

凭据池策略

辅助模型

交互式配置辅助模型

视频教程

通用配置模式

完整辅助配置参考

会话搜索调优

更改视觉模型

提供商选项

常见设置

环境变量（旧版）

推理努力

工具使用强制

注入的内容

何时打开

TTS 配置

显示设置

静态消息的 UI 语言

运行时元数据页脚（仅限网关）

每平台进度覆盖

隐私

语音转文字（STT）

语音模式（CLI）

流式传输

CLI 流式传输

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

群聊会话隔离

未授权 DM 行为

快速命令

人类延迟

代码执行

网络搜索后端

浏览器

时区

Discord

安全

网站黑名单

智能审批

检查点

委派

澄清

上下文文件（SOUL.md、AGENTS.md）

工作目录