配置

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

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

配置优先级

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

CLI 参数——例如 hermes chat --model anthropic/claude-sonnet-4（每次调用的覆盖）
~/.hermes/config.yaml——所有非机密设置的主要配置文件
~/.hermes/.env——环境变量回退；必需用于机密信息（API 密钥、token、密码）
内置默认值——未设置任何值时使用的硬编码安全默认值

:::info 经验法则机密信息（API 密钥、机器人 token、密码）放入 .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 兼容）的主轮次客户端、回退链、凭据轮换后的重建，以及（对于 OpenAI-wire）每次请求的超时参数——因此配置值优先级高于旧的 HERMES_API_TIMEOUT 环境变量。

你还可以设置 providers.<id>.stale_timeout_seconds 用于非流式陈旧调用检测器，以及 providers.<id>.models.<model>.stale_timeout_seconds 作为模型特定的覆盖。此值优先级高于旧的 HERMES_API_CALL_STALE_TIMEOUT 环境变量。

保持这些未设置则保留旧版默认值（HERMES_API_TIMEOUT=1800s、HERMES_API_CALL_STALE_TIMEOUT=300s、原生 Anthropic 900s）。目前不适用于 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: []  # 转发到沙箱执行的环境变量名称（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 和 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）	带快照支持文件系统持久化的云端执行
singularity	Singularity/Apptainer 容器	命名空间（—containall）	HPC 集群、共享机器

Local 后端

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

terminal:
  backend: local

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

Docker 后端

在 Docker 容器内运行命令，具有安全加固（丢弃所有 capabilities、无权限提升、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 表示只读
  docker_extra_args:               # 逐字附加到 `docker run` 的额外标志
    - "--gpus=all"
    - "--network=host"
 
  # 资源限制
  container_cpu: 1                 # CPU 核心数（0 = 不限）
  container_memory: 5120           # MB（0 = 不限）
  container_disk: 51200            # MB（需要 XFS+pquota 上的 overlay2）
  container_persistent: true       # 跨会话持久化 /workspace 和 /root

terminal.docker_extra_args（也可通过 TERMINAL_DOCKER_EXTRA_ARGS='["--gpus=all"]' 覆盖）允许你传递 Hermes 未作为一等键暴露的任意 docker run 标志——--gpus、--network、--add-host、替代的 --security-opt 覆盖等。每个条目必须是字符串；列表附加到组装的 docker run 调用的最后，以便必要时覆盖 Hermes 的默认值。谨慎使用——与沙箱加固冲突的标志（capability 丢弃、--user、工作区绑定挂载）会静默削弱隔离性。

要求： 已安装并运行的 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
大小限制的 tmpfs 用于 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）

凭据转发： docker_forward_env 中列出的环境变量首先从你的 shell 环境解析，然后从 ~/.hermes/.env 中回退。技能也可以声明 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 token 等）并在每个命令前同步。

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/...，除非主机上的网关进程也能访问同一路径

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

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

Docker 凭据转发

默认情况下，Docker 终端会话不会继承任意主机凭据。如果容器内需要特定 token，请将其添加到 terminal.docker_forward_env。

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

Hermes 首先从当前 shell 解析每个列出的变量，然后回退到 ~/.hermes/.env（如果已通过 hermes config set 保存）。

:::warning 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 拥有的路径（如 /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 启用，对 local 后端禁用。

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`	跟随配置
Local 覆盖	`TERMINAL_LOCAL_PERSISTENT`	`false`

按后端的环境变量优先级最高。如果你也想在 local 后端上使用持久 shell：

export TERMINAL_LOCAL_PERSISTENT=true

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

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

技能设置

技能可以通过其 SKILL.md 前置元数据声明自己的配置设置。这些是非机密值（路径、偏好设置、领域设置），存储在 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 可选择扫描新/更新内容中是否存在危险关键词模式（凭据窃取、明显的提示注入、数据外泄指令）。扫描器默认关闭——合法 agent 工作流中正常涉及 ~/.ssh/ 或提及 $OPENAI_API_KEY 的操作为了避免频繁触发启发式规则。如果你希望扫描器在 agent 的技能写入生效前提示你，请重新启用：

skills:
  guard_agent_created: true   # 默认：false

启用后，任何被标记的 skill_manage 写入会显示一个审批提示及扫描器的理由。批准的写入生效；拒绝的写入向 agent 返回解释性错误。

内存配置

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 在其内容被摘要掉后可以重新读取文件。

工具输出截断限制

三个相关的上限控制工具可返回的原始输出量，超过后 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 tokens）。
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

此设置在平台工具配置（platform_toolsets，通过 hermes tools 写入）之后应用，因此此处列出的工具集始终被移除——即使平台的已保存配置中仍列有它们。当你希望通过一个开关”在所有地方关闭 X”时使用此设置，而不是编辑 hermes tools UI 中的 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 兼容端点（覆盖提供商）

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

hygiene_hard_message_limit 是仅限网关的压缩前安全阀。拥有数千条消息的失控会话可能在正常的百分比上下文阈值触发之前就达到模型上下文限制；当消息数量超过此上限时，Hermes 会强制压缩，无论 token 使用量如何。默认 400——对于非常长的会话属于正常情况的平台，请提高此值；要强制更积极的压缩，请降低此值。在运行中的网关上编辑此值会在下一条消息时生效（见下方）。

:::tip 网关热重载压缩和上下文长度自近期版本起，在运行中的网关上编辑 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` 等	未设置	强制使用该提供商及其认证
任意	已设置	直接使用自定义端点（忽略提供商）

:::warning 摘要模型上下文长度要求摘要模型的必须拥有至少与主 agent 模型一样大的上下文窗口。压缩器会将对话的完整中间部分发送给摘要模型——如果该模型的上下文窗口小于主模型，摘要调用会因上下文长度错误而失败。发生这种情况时，中间轮次会被丢弃且无摘要，从而静默丢失对话上下文。如果你覆盖了模型，请确认其上下文长度等于或超过你的主模型。 :::

上下文引擎

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

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

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

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

插件引擎永远不会自动激活——你必须显式将 context.engine 设置为插件名称。可通过 hermes plugins → 提供商插件 → 上下文引擎浏览和选择可用的引擎。

请参阅内存提供商了解内存插件的类似单选系统。

迭代预算压力

当 agent 正在处理包含许多工具调用的复杂任务时，它可能会在不知不觉中消耗完迭代预算（默认：90 轮）。预算压力会在接近限制时自动警告模型：

阈值	级别	模型看到的内容
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: 3           # 每个提供商在回退生效前的重试次数（默认：3）

预算压力默认启用。Agent 会在工具结果中自然地看到警告，鼓励它整合工作并在迭代用尽之前交付响应。

当迭代预算完全耗尽时，CLI 会向用户显示通知：⚠ 迭代预算已到达 (90/90) — 响应可能不完整。如果在活跃工作中预算耗尽，agent 会在停止前生成已完成内容的摘要。

agent.api_max_retries 控制在临时错误（速率限制、连接断开、5xx）上 Hermes 重试提供商 API 调用的次数，在回退提供商切换生效之前。默认值为 3——总共四次尝试。如果你配置了回退提供商并希望更快地故障转移，请将此值降至 0，以便主提供商上的第一个临时错误立即交给回退，而不是在有问题的端点上反复重试。

API 超时

Hermes 对流式传输有单独的超时层，加上非流式调用的陈旧检测器。当你将它们保持隐式默认值时，陈旧检测器会自动为本地提供商调整。

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

Socket 读取超时控制 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

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

◐ 上下文：████████████░░░░░░░░ 距离压缩还有 62%（阈值：窗口的 50%）。

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

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

凭据池策略

当你对同一提供商拥有多个 API 密钥或 OAuth 令牌时，配置轮换策略：

credential_pool_strategies:
  openrouter: round_robin    # 均匀轮换使用密钥
  anthropic: least_used      # 始终选择使用最少的密钥

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

提示缓存

当活跃的提供商支持时，Hermes 会自动启用跨会话提示缓存——无需用户配置。

对于原生 Anthropic、OpenRouter 和 Nous Portal 上的 Claude，Hermes 会以 1 小时 TTL（ttl: "1h"）在系统提示和技能块上附加 cache_control 断点。新小时内的首次发送按完整输入费率计费；同一小时内跨任何会话的后续发送以折扣的缓存读取费率从缓存中拉取。这意味着系统提示、已加载的技能内容以及任何长上下文包含的早期部分会在 hermes 会话和分叉子 agent 之间在第一个小时内被复用。

Qwen Cloud（Alibaba DashScope）上游将缓存 TTL 限制为 5 分钟，因此 Hermes 在那里使用 5 分钟断点 TTL 替代。其他通过第三方路径的 Claude（AWS Bedrock、Azure Foundry）回退到提供商自己的缓存默认值。xAI Grok 使用单独的会话固定 conversation-id 机制——请参阅 xAI 提示缓存。

没有可用于禁用的开关——缓存始终开启，即使在单轮对话中也能省钱，因为仅系统提示就占输入 token 数的相当比例。

辅助模型

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

:::note 为什么”auto”使用你的主模型早期版本将聚合器用户（OpenRouter、Nous Portal）分流到提供商端的便宜默认模型。这令人惊讶——为聚合器订阅付费的用户会看到不同的模型处理他们的辅助流量。现在 auto 对所有用户使用主模型，而 config.yaml 中按任务的覆盖仍然有效（参见下方辅助配置完整参考）。 :::

交互式配置辅助模型

无需手动编辑 YAML，运行 hermes model 并从菜单中选择 “配置辅助模型”。你会进入交互式按任务选择器：

$ hermes model
→ 配置辅助模型

[ ] vision               currently: auto / main model
[ ] web_extract          currently: auto / main model
[ ] 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
[ ] kanban_decomposer    currently: auto / main model
[ ] profile_describer    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、xai-oauth、ollama-cloud、alibaba、bedrock、huggingface、arcee、xiaomi、kilocode、opencode-zen、opencode-go、ai-gateway、azure-foundry——或来自 custom_providers 列表的任何命名自定义提供商（例如 provider: "beans"）。

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

:::tip xAI Grok OAuth xai-oauth 通过浏览器 OAuth 为 SuperGrok 和 X Premium+ 订阅用户登录（无需 API 密钥）。运行 hermes model 并选择 xAI Grok OAuth (SuperGrok Subscription) 进行认证。同一 OAuth 令牌可复用于所有直接面向 xAI 的界面（聊天、辅助任务、TTS、图像生成、视频生成、转录）。请参阅 xAI Grok OAuth 指南，如果 Hermes 在远程主机上，请参阅远程主机的 OAuth。 :::

:::warning "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               # 秒——压缩需要摘要长对话，需要更多时间
 
  # 技能中心——技能匹配和搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
 
  # MCP 工具分发
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
 
  # Kanban 分类指定器——`hermes kanban specify <id>`（或仪表盘上
  # 分类列卡片的 ✨ 指定按钮）使用此槽位将一行描述扩展为具体
  # 规格说明并将任务提升为 `todo`。便宜快速的模型效果好；
  # 规格扩展内容简短，不需要推理深度。
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

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

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

用于辅助任务的 OpenRouter 路由和 Pareto Code

当辅助任务解析到 OpenRouter 时（无论是因为显式设置还是因为主 agent 在 OpenRouter 上而使用了 provider: "main"），主 agent 的 provider_routing 和 openrouter.min_coding_score 设置不会传播——这是设计使然，每个辅助任务都是独立的。要为特定辅助任务设置 OpenRouter 提供商偏好或使用 Pareto Code 路由器，请通过 extra_body 按任务设置：

auxiliary:
  compression:
    provider: openrouter
    model: openrouter/pareto-code         # 为此任务使用 Pareto Code 路由器
    extra_body:
      provider:                            # OpenRouter 提供商路由偏好
        order: [anthropic, google]         # 按顺序尝试这些提供商
        sort: throughput                   # 或 "price" | "latency"
        # only: [anthropic]                # 限制到特定提供商
        # ignore: [deepinfra]              # 排除特定提供商
      plugins:                             # OpenRouter Pareto Code 路由器旋钮
        - id: pareto-router
          min_coding_score: 0.5            # 0.0–1.0；越高 = 编码能力越强

结构镜像了 OpenRouter 在 chat completions 请求体中接受的内容。Hermes 逐字转发整个 extra_body，因此任何其他在 openrouter.ai/docs 中记载的 OpenRouter 请求体字段都可以以相同方式工作。

更改视觉模型

要使用 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"`	最佳可用（默认）。Vision 尝试 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)
`"xai-oauth"`	强制 xAI Grok OAuth（SuperGrok 或 X Premium+ 订阅用户的浏览器登录，无需 API 密钥）。同一 OAuth 令牌涵盖聊天、TTS、图像、视频和转录。	`hermes model` → xAI Grok OAuth (SuperGrok Subscription)
`"main"`	使用你的活跃自定义/主端点。可来自 `OPENAI_BASE_URL` + `OPENAI_API_KEY`，或通过 `hermes model` / `config.yaml` 保存的自定义端点。适用于 OpenAI、本地模型或任何 OpenAI 兼容 API。仅限辅助任务——对 `model.provider` 无效。	自定义端点凭据 + base 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) 进行登录并自动设置此配置。对于中国地区，base URL 将是 https://api.minimaxi.com/anthropic。完整指南请参阅 MiniMax OAuth 指南。

使用本地/自托管模型：

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

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

:::tip 如果你使用 Codex OAuth 作为主模型提供商，视觉功能会自动工作——无需额外配置。Codex 包含在视觉的自动检测链中。 :::

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

环境变量（旧版）

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

设置	环境变量
Vision 提供商	`AUXILIARY_VISION_PROVIDER`
Vision 模型	`AUXILIARY_VISION_MODEL`
Vision 端点	`AUXILIARY_VISION_BASE_URL`
Vision API 密钥	`AUXILIARY_VISION_API_KEY`
Web 提取提供商	`AUXILIARY_WEB_EXTRACT_PROVIDER`
Web 提取模型	`AUXILIARY_WEB_EXTRACT_MODEL`
Web 提取端点	`AUXILIARY_WEB_EXTRACT_BASE_URL`
Web 提取 API 密钥	`AUXILIARY_WEB_EXTRACT_API_KEY`

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

:::tip 运行 hermes config 查看你当前的辅助模型设置。覆盖仅在不同于默认值时显示。 :::

推理力度

控制模型在响应前进行多少”思考”：

agent:
  reasoning_effort: ""   # 空 = medium（默认）。选项：none、minimal、low、medium、high、xhigh（max）

未设置时（默认），推理力度默认为 “medium”——一个适用于大多数任务的平衡级别。设置值会覆盖它——更高的推理力度在复杂任务上提供更好的结果，但代价是更多的 token 和延迟。

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

/reasoning           # 显示当前力度级别和显示状态
/reasoning high      # 将推理力度设为 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 - Neutral（默认）
  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  # 网关：将自然的轮次中助手更新作为单独消息发送
  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 状态栏中显示估算费用
  timestamps: false       # 启用时，在 CLI / TUI 记录中为用户和助手标签添加 [HH:MM] 时间戳前缀
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 不限，显示完整路径/命令）
  runtime_footer:         # 网关：附加运行时上下文页脚到最终回复
    enabled: false
    fields: ["model", "context_pct", "cwd"]
  file_mutation_verifier: true    # 当本轮 write_file/patch 调用失败时附加建议性页脚
  language: en            # 静态消息的 UI 语言（审批提示、某些网关回复）。en | zh | zh-hant | ja | de | es | fr | tr | uk | af | ko | it | ga | pt | ru | hu

文件变更验证器

当 display.file_mutation_verifier 为 true（默认）时，如果本轮中 write_file 或 patch 调用失败且未被对同一路径的成功写入覆盖，Hermes 会在助手的最终回复中附加一行建议性说明。这捕获了”一批并行补丁，一半静默失败，模型总结成功”这类过度声明的情况，而无需你在每次编辑后手动运行 git status。

示例页脚：

⚠️ 文件变更验证器：本轮有 3 个文件未被修改，尽管上述措辞可能暗示其他情况。运行 `git status` 或 `read_file` 以确认。
  • concepts/automatic-organization.md — [patch] 找不到 old_string 的匹配项
  • concepts/lora.md — [patch] 找不到 old_string 的匹配项
  • concepts/rag-pipeline.md — [patch] 找不到 old_string 的匹配项

设置 file_mutation_verifier: false（或 HERMES_FILE_MUTATION_VERIFIER=0）以禁止显示该页脚。验证器仅在轮次结束时确实有未解决的失败时触发——在同一轮中重试失败的补丁并成功的模型不会触发该文件的验证器。

静态消息的 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_footer.enabled: true 时，Hermes 会在每个网关轮次的最终消息后附加一个小的运行时上下文页脚——显示与 CLI 状态栏相同的信息（模型、上下文百分比、cwd、会话持续时间、token、费用）。默认关闭；如果你的团队希望每条回复都包含来源信息，请按网关选择启用。

display:
  runtime_footer:
    enabled: true
    fields: ["model", "context_pct", "cwd"]   # 可选：model、context_pct、cwd、duration、tokens、cost

/footer 斜杠命令可在任何会话中运行时切换此功能。

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

— claude-opus-4.7 · 12 次工具调用 · 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 会将已完成的轮次中助手更新作为单独的聊天消息发送。这与 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 切换语音回复。请参阅语音模式了解端到端设置和平台特定行为。

流式传输

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

CLI 流式传输

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

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

网关流式传输（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 = 始终原地编辑

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

对于没有渐进式 token 编辑的独立轮次中间助手更新，设置 display.interim_assistant_messages: true。

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

全新最终消息（Telegram）： Telegram 的 editMessageText 会保留原始消息的时间戳，因此长时间运行的流式回复即使完成后也会保留第一个 token 的时间戳。当 fresh_final_after_seconds > 0（默认 60）时，完成的回复会作为全新消息投递（旧的预览会被尽力删除），使 Telegram 的可见时间戳反映完成时间。短预览仍然原地最终化。设置为 0 以始终原地编辑。

:::note 流式传输默认禁用。在 ~/.hermes/config.yaml 中启用它以尝试流式传输用户体验。 :::

群聊会话隔离

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

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 拒绝访问，但会在 DM 中回复一次性配对码。
ignore 静默丢弃未授权的 DM。
平台部分会覆盖全局默认值，因此你可以广泛保持配对启用，同时让一个平台更安静。

快捷命令

定义在不调用 LLM 的情况下运行 shell 命令的自定义命令，或将一个斜杠命令别名到另一个。Exec 快捷命令是零 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 搜索后端

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 设置说明，请参阅 Web 搜索设置指南。

自托管 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 直接附加到你自己的
  # Chromium 系列浏览器（通过 /browser connect），而非启动无头浏览器。
  cdp_url: ""
  # 对话框监督器——控制当附加了 CDP 后端时（Browserbase、本地 Chromium 系列
  # 浏览器通过 /browser connect），原生 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   # 启用后，Camofox 会话在重启后保持 cookie/登录状态
    user_id: ""                  # 可选的外部管理的 Camofox userId
    session_key: ""              # Hermes 创建标签页时发送的可选会话密钥
    adopt_existing_tab: false    # 在创建新标签页之前为此身份复用现有标签页

对话框策略：

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 和本地 Chromium 系列 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 提及时才响应。DM 始终无需提及即可工作。
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 的 Web 和浏览器工具访问特定域名：

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

启用后，任何匹配被阻止域名模式的 URL 都会在 Web 或浏览器工具执行前被拒绝。这适用于 web_search、web_extract、browser_navigate 以及任何访问 URL 的工具。

域名规则支持：

精确域名：admin.example.com
通配符子域名：*.internal.company.com（阻止所有子域名）
TLD 通配符：*.local

共享文件每行包含一条域名规则（空行和 # 注释被忽略）。缺失或无法读取的文件会记录警告，但不会禁用其他 Web 工具。

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

智能审批

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

approvals:
  mode: manual   # manual | smart | off

模式	行为
`manual`（默认）	在执行任何标记的命令之前提示用户。在 CLI 中显示交互式审批对话框。在消息中，排队待处理的审批请求。
`smart`	使用辅助 LLM 评估标记的命令是否真正危险。低风险命令自动批准，具有会话级持久性。真正危险的命令会升级给用户。
`off`	跳过所有审批检查。相当于 `HERMES_YOLO_MODE=true`。请谨慎使用。

智能模式在减少审批疲劳方面特别有用——它允许 agent 在安全操作上更自主地工作，同时仍然捕获真正具有破坏性的命令。

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

检查点

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

checkpoints:
  enabled: false                 # 启用自动检查点（也可：hermes chat --checkpoints）。默认：false（可选启用）。
  max_snapshots: 20              # 每个目录保留的最大检查点数（默认：20）

委托

配置子 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）
  # api_mode: ""                            # base_url 的线路协议："chat_completions"、"codex_responses" 或 "anthropic_messages"。空 = 从 URL 自动检测（例如 /anthropic 后缀 → anthropic_messages）。对于启发式无法检测的非标准端点，请显式设置。
  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 provider:model 覆盖： 默认情况下，子 agent 继承父 agent 的提供商和模型。设置 delegation.provider 和 delegation.model 可将子 agent 路由到不同的 provider:model 对——例如，对范围狭窄的子任务使用便宜/快速的模型，同时主 agent 运行昂贵的推理模型。

直接端点覆盖： 如果你想要明确的自定义端点路径，设置 delegation.base_url、delegation.api_key 和 delegation.model。这会将子 agent 直接发送到该 OpenAI 兼容端点，优先级高于 delegation.provider。如果省略 delegation.api_key，Hermes 仅回退到 OPENAI_API_KEY。

线路协议（api_mode）： Hermes 会从 delegation.base_url 自动检测线路协议（例如以 /anthropic 结尾的路径 → anthropic_messages；Codex / 原生 Anthropic / Kimi-coding 主机名保留其现有的检测方式）。对于启发式无法分类的端点——例如 Azure AI Foundry、MiniMax、Zhipu GLM 或前置于 Anthropic 形状后端的 LiteLLM 代理——请显式设置 delegation.api_mode 为 chat_completions、codex_responses 或 anthropic_messages 之一。保持为空（默认）以保留自动检测。

委托提供商使用与 CLI/网关启动相同的凭据解析。所有配置的提供商都受支持：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。设置提供商后，系统会自动解析正确的 base 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                # 所有终端会话

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

配置

配置

目录结构

管理配置

配置优先级

环境变量替换

提供商超时

终端后端配置

后端概览

Local 后端

Docker 后端

SSH 后端

Modal 后端

Daytona 后端

Vercel Sandbox 后端

Singularity/Apptainer 后端

常见终端后端问题

关闭时远程到主机的文件同步

Docker 卷挂载

Docker 凭据转发

以主机用户身份运行容器

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

持久 Shell

技能设置

Agent 创建技能写入的防护

内存配置

文件读取安全

工具输出截断限制

全局工具集禁用

Git 工作树隔离

上下文压缩

完整参考

常见设置

三个旋钮的交互方式

上下文引擎

迭代预算压力

API 超时

上下文压力警告

凭据池策略

提示缓存

辅助模型

交互式配置辅助模型

视频教程

辅助配置完整参考

用于辅助任务的 OpenRouter 路由和 Pareto Code

更改视觉模型

提供商选项

常见设置

环境变量（旧版）

推理力度

工具使用强制

注入内容

何时开启

TTS 配置

显示设置

文件变更验证器

静态消息的 UI 语言

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

按平台进度覆盖

隐私

语音转文本（STT）

语音模式（CLI）

流式传输

CLI 流式传输

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

群聊会话隔离

未授权 DM 行为

快捷命令

人类延迟

代码执行

Web 搜索后端

浏览器

时区

Discord