配置

hermes 配置指南

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

目录结构

~/.hermes/
├── config.yaml     # 设置（模型、终端、TTS、压缩等）
├── .env            # API 密钥和机密信息
├── auth.json       # OAuth 提供者凭据（Nous Portal 等）
├── SOUL.md         # 智能体核心身份（系统提示词中的 #1 插槽）
├── memories/       # 持久化记忆 (MEMORY.md, USER.md)
├── skills/         # 智能体创建的技能（通过 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

配置优先级

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

CLI 参数 —— 例如 hermes chat --model anthropic/claude-sonnet-4（单次调用覆盖）
~/.hermes/config.yaml —— 所有非机密设置的主要配置文件
~/.hermes/.env —— 环境变量的备选方案；机密信息（API 密钥、令牌、密码）必需放在此处
内置默认值 —— 未设置任何内容时硬编码的安全默认值

环境变量替换

你可以在 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。

提供商超时设置

你可以通过 providers.<id>.request_timeout_seconds 设置提供商范围内的请求超时，还可以通过 providers.<id>.models.<model>.timeout_seconds 为特定模型设置覆盖值。这适用于每种传输方式（OpenAI 协议、原生 Anthropic、Anthropic 兼容协议）上的主要轮询客户端、备选链、凭据轮换后的重建，以及（对于 OpenAI 协议）单次请求的超时参数 —— 因此配置的值优先于旧有的 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 支持七种终端后端。每种后端决定了智能体的 Shell 命令实际执行的位置 —— 无论是你的本地机器、Docker 容器、通过 SSH 连接的远程服务器、Modal 云端沙箱（直接连接或通过 Nous 管理的网关）、Daytona 工作区、Vercel 沙箱，还是 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 容器	完全隔离 (namespaces, cap-drop)	安全沙箱、CI/CD
ssh	通过 SSH 连接的远程服务器	网络边界隔离	远程开发、高性能硬件
modal	Modal 云端沙箱	完全隔离 (云端 VM)	临时云端计算、评估
daytona	Daytona 工作区	完全隔离 (云端容器)	托管式云端开发环境
vercel_sandbox	Vercel 沙箱	完全隔离 (云端 microVM)	具有快照支持的文件系统持久化云端执行
singularity	Singularity 容器	命名空间隔离 (—containall)	HPC 集群、共享机器

Local 后端（本地）

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

terminal:
  backend: local

Docker 后端

在经过安全强化的 Docker 容器中运行命令（丢弃所有 capabilities，禁止权限提升，限制 PID 数量）。

单个持久化容器，而非按命令创建： Hermes 在首次使用时启动一个长效容器，并将每个终端、文件和 execute_code 调用通过 docker exec 路由到该容器中 —— 跨越会话、/new、/reset 以及 delegate_task 子智能体 —— 在整个 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 以及常见的安装位置。原生支持 Podman：设置 HERMES_DOCKER_BINARY=podman 即可强制使用。
容器生命周期： Hermes 复用单个长效容器。命令通过 docker exec 以登录 Shell 运行，因此状态得以保留。通过 delegate_task 生成的并行子智能体共享此容器 —— 并发的 cd、环境变更和路径写入会产生冲突。
安全强化：
- --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 中解析。技能（Skills）也可以声明 required_environment_variables，这些变量会自动合并。

SSH 后端

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 实现连接复用。默认启用持久化 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 的命令会自动退回到单次执行（one-shot）模式。

在 Modal 云端沙箱中运行命令。每个任务获得一个独立的 VM，支持配置 CPU、内存和磁盘。文件系统可以在会话间进行快照/恢复。

terminal:
  backend: modal
  container_cpu: 1                 # CPU 核心数
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # 快照/恢复文件系统

要求： 需要 MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 环境变量，或者 ~/.modal.toml 配置文件。

持久化： 启用后，沙箱文件系统将在清理时生成快照，并在下次会话时恢复。快照记录在 ~/.hermes/modal_snapshots.json 中。这仅保留文件系统状态，不保留活跃进程、PID 空间或后台作业。

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

Daytona 后端

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

terminal:
  backend: daytona
  container_cpu: 1                 # CPU 核心数
  container_memory: 5120           # MB → 转换为 GiB
  container_disk: 10240            # MB → 转换为 GiB (最大 10 GiB)
  container_persistent: true       # 停止/恢复而非删除

要求： DAYTONA_API_KEY 环境变量。

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

磁盘限制： Daytona 强制执行 10 GiB 的最大限制。超过此值的请求将被限制并发出警告。

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]'

要求身份验证： 配置访问令牌（access-token）认证，需同时提供 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 令牌寿命较短，不应作为文档记录的部署路径使用。

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

持久化： 当 container_persistent: true 时，Hermes 会在清理期间对沙箱文件系统进行快照，并从该快照为同一任务恢复后续沙箱。快照内容可以包含 Hermes 同步的凭据、技能（skills）以及复制到沙箱中的缓存文件。这仅保留文件系统状态；不保留活跃沙箱的标识、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 文件将直接使用。

临时目录（Scratch directory）： 解析优先级依次为：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 后端（即智能体的工作树位于与运行 Hermes 的宿主机不同的机器上时），Hermes 会追踪智能体在远程沙箱内触碰过的文件，并在会话拆卸/沙箱清理时，将修改后的文件同步回宿主机的 ~/.hermes/cache/remote-syncs/<session-id>/ 目录下。

触发时机：会话关闭、/new、/reset、网关消息超时、以及当子智能体使用远程后端时的 delegate_task 完成。
覆盖范围：涵盖智能体修改过的整个树，而不不仅仅是它显式打开的文件。新增、编辑和删除都会被捕获。
权威记录：当你去查看时，远程沙箱可能已经被拆卸；本地的 ~/.hermes/cache/remote-syncs/… 副本是智能体所做更改的权威记录。
大小限制：大型二进制输出（如模型检查点、原始数据集）会受到大小限制 —— 同步将跳过超过 file_sync_max_mb（默认 100 MB）的文件。如果你预期会有更大的产出物，请调高此值。

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

通过这种方式，你可以从会话结束后即被销毁的临时云端沙箱中回收结果，而无需显式命令智能体去执行 scp 或 modal volume put 每一个产出物。

Docker 卷挂载

使用 Docker 后端时，docker_volumes 允许你将宿主机目录共享给容器。每个条目均使用标准的 Docker -v 语法：宿主机路径:容器路径[:选项]。

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # 读写（默认）
    - "/home/user/datasets:/data:ro"              # 只读
    - "/home/user/.hermes/cache/documents:/output" # 网关可见的导出目录

此功能适用于：

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

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

在 Docker 内部将文件写入 /output/...
在 MEDIA: 中使用宿主机路径，例如：MEDIA:/home/user/.hermes/cache/documents/report.txt
切勿直接使用 /workspace/... 或 /output/...，除非宿主机上的网关进程也存在完全相同的路径。

也可以通过环境变量设置：TERMINAL_DOCKER_VOLUMES='["/宿主机:/容器"]'（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 保存）。

以宿主用户身份运行容器

默认情况下，Docker 容器以 root 用户（UID 0）运行。在 /workspace 或其他绑定挂载（bind-mounts）中创建的文件在宿主机上最终归 root 所有，因此在会话结束后，你必须执行 sudo chown 才能通过宿主机的编辑器对其进行编辑。terminal.docker_run_as_host_user 标志可以修复此问题：

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

启用后，Hermes 会在 docker run 命令中附加 --user $(id -u):$(id -g)，这样写入绑定挂载目录（/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，该宿主目录将通过绑定挂载（bind-mount）连接到 /workspace。
Docker 后端将在 /workspace 中启动。
文件工具和终端命令都能看到同一个挂载的项目。

禁用时： 除非你通过 docker_volumes 显式挂载了内容，否则 /workspace 将由沙箱自身所有。

安全权衡：

false：维持沙箱边界。
true：允许沙箱直接访问你启动 Hermes 时所在的目录。

仅当你确实希望容器对宿主机的实时文件进行操作时，才开启此选项。

持久化 Shell (Persistent Shell)

默认情况下，每个终端命令都在各自的子进程中运行 —— 工作目录、环境变量和 Shell 变量在命令之间会重置。当启用 持久化 Shell 时，一个长效的 bash 进程会在多次 execute() 调用之间保持活跃，从而使状态在命令间得以延续。

这对于 SSH 后端 最为有用，因为它还能消除每条命令的连接开销。SSH 后端 默认启用 持久化 Shell，而本地（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`	跟随配置
本地覆盖	`TERMINAL_LOCAL_PERSISTENT`	`false`

各后端专属的环境变量具有最高优先级。如果你也希望在本地后端使用持久化 Shell：

export TERMINAL_LOCAL_PERSISTENT=true

有关各后端的详细信息，请参阅 README 的 Code Execution 和 Terminal 部分。

技能设置

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

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

技能设置的工作原理：

hermes config migrate 会扫描所有已启用的技能，查找未配置的设置，并提供输入提示。
hermes config show 会在 “Skill Settings” 下显示所有技能设置，并标明它们所属的技能。
当技能加载时，其解析后的配置值会自动注入到技能上下文中。

手动设置值：

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

有关在自定义技能中声明配置设置的详细信息，请参阅 Creating Skills — Config Settings。

智能体创建技能的写入保护 (Guard)

当智能体使用 skill_manage 创建、编辑、修补或删除技能时，Hermes 可以选择性地扫描新内容/更新内容中是否存在危险的关键词模式（凭据窃取、明显的提示词注入、数据外泄指令）。此扫描程序 默认关闭 —— 因为合法的智能体工作流（如正常触碰 ~/.ssh/ 或提及 $OPENAI_API_KEY）经常会触发此类启发式规则。如果你希望在智能体写入技能前让扫描程序提示你进行确认，请将其开启：

skills:
  guard_agent_created: true   # 默认值：false

开启后，任何被标记的 skill_manage 写入操作都会以包含扫描理由的审批提示形式弹出。获准的写入将生效；被拒绝的写入将向智能体返回说明性错误。

记忆配置 (Memory Configuration)

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

文件读取安全 (File Read Safety)

控制单次 read_file 调用可以返回的内容上限。超过限制的读取会被拒绝，并报错提示智能体使用 offset（偏移量）和 limit（限制）来读取更小的范围。这可以防止单次读取压缩后的 JS 包或大型数据文件时冲垮上下文窗口。

file_read_max_chars: 100000  # 默认值 —— 约 2.5-3.5 万 tokens

如果你使用的模型具有大型上下文窗口且经常需要读取大文件，可以调高此值。对于小上下文模型，应降低此值以保持读取效率：

# 大型上下文模型 (200K+)
file_read_max_chars: 200000

# 小型本地模型 (16K 上下文)
file_read_max_chars: 30000

智能体还会自动对文件读取进行去重 —— 如果重复读取同一个文件的同一区域且文件内容未发生变化，系统将返回一个轻量级的存根（stub），而不是重新发送内容。该机制会在上下文压缩时重置，以便智能体在内容被总结（summarized）后能够重新读取文件。

工具输出截断限制 (Tool Output Truncation Limits)

三个相关上限控制工具在被 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（在典型分词器中约合 1.2-1.5 万 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

全局工具集禁用 (Global Toolset Disable)

若要在一个地方集中禁用 CLI 和所有网关平台上的特定工具集，请在 agent.disabled_toolsets 下列出它们的名称：

agent:
  disabled_toolsets:
    - memory       # 隐藏记忆工具 + 禁用 MEMORY_GUIDANCE 注入
    - web          # 任何地方都不允许 web_search / web_extract

此设置在平台专属工具配置（通过 hermes tools 写入的 platform_toolsets）之后生效，因此此处列出的工具集始终会被移除 —— 即使某个平台的保存配置中仍包含它。当你需要一个 “一键全局关闭 X” 的开关，而不是在 hermes tools UI 中编辑 15 个以上的平台行时，请使用此选项。

如果列表为空或省略该键，则不执行任何操作。

Git 工作树隔离 (Git Worktree Isolation)

启用隔离的 Git 工作树（worktree），以便在同一个仓库上并行运行多个智能体：

worktree: true    # 始终创建工作树（等同于使用 hermes -w）
# worktree: false # 默认值 —— 仅在传递 -w 标志时创建

启用后，每个 CLI 会话都会在 .worktrees/ 下创建一个带有独立分支的新工作树。智能体可以编辑文件、提交、推送并创建 PR，而不会互相干扰。未进行修改的工作树在退出时会被移除；有修改的工作树会被保留以便手动恢复。

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

.env
.venv/
node_modules/

上下文压缩 (Context Compression)

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

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

完整参考

compression:
  enabled: true                                     # 开启/关闭压缩
  threshold: 0.50                                   # 当达到上下文限制的此百分比时进行压缩
  target_ratio: 0.20                                # 保留作为近期“尾部”消息的比例（占 threshold 的比例）
  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 兼容端点（覆盖 provider）

hygiene_hard_message_limit 是一个仅限网关使用的 预压缩安全阀。拥有数千条消息的失控会话可能会在触发正常的 “上下文百分比阈值” 之前就触及模型上下文限制；当消息数量超过此上限时，Hermes 无论 token 使用情况如何都会强制进行压缩。默认值为 400 —— 对于超长会话属于常态的平台，可以调高此值；若要强制执行更激进的压缩，可以调低此值。在运行中的网关上修改此值将在下一条消息时生效（见下文）。

常用设置

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

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、z.ai、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 / 等	未设置	强制使用该提供商，使用其认证方式
任意值	设置了 URL	直接使用自定义端点（忽略 provider）

上下文引擎 (Context Engine)

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

context:
  engine: "compressor"    # 默认值 —— 内置的有损总结

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

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

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

有关记忆插件类似的单选系统，请参阅 Memory Providers。

迭代预算压力 (Iteration Budget Pressure)

当智能体正在处理涉及多次工具调用的复杂任务时，可能会在没有意识到余量不足的情况下消耗掉迭代预算（默认：90 轮）。预算压力机制会在模型接近限制时自动发出警告：

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

警告会被注入到最后一个工具结果的 JSON 中（作为 _budget_warning 字段），而不是作为独立的消息发送 —— 这样可以保留提示词缓存（prompt caching），且不会破坏对话结构。

agent:
  max_turns: 90                # 每轮对话的最大迭代次数（默认：90）
  api_max_retries: 3           # 在启动备用方案前，每个提供商的重试次数（默认：3）

预算压力默认开启。智能体会自然地将警告视为工具结果的一部分，从而鼓励其整合工作并在迭代耗尽前交付回复。

当迭代预算完全耗尽时，CLI 会向用户显示通知：⚠ Iteration budget reached (90/90) — response may be incomplete.（迭代预算已达上限，回复可能不完整）。如果预算在执行任务期间耗尽，智能体会在停止前生成一份已完成工作的摘要。

agent.api_max_retries 控制在故障转移（fallback）切换发生前，Hermes 针对提供商 API 调用的瞬时错误（如速率限制、连接断开、5xx 错误）重试的次数。默认值为 3 —— 即总共尝试四次。如果你配置了备用提供商（fallback providers）并希望更快地进行故障切换，可以将此值降至 0，这样主提供商的首次瞬时错误就会立即触发向备用提供商的移交，而不会在不稳定的端点上反复重试。

API 超时设置 (API Timeouts)

Hermes 为流式传输（streaming）设置了独立的超时层，并为非流式调用设置了停滞检测器（stale detector）。仅当你保留默认设置时，停滞检测器才会针对本地提供商进行自动调整。

超时项	默认值	本地提供商	配置 / 环境变量
套接字读取超时	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 read timeout) 控制 httpx 等待来自提供商的下一块数据的时间。本地 LLM 在生成第一个 token 之前，处理大上下文的预填充（prefill）可能需要数分钟，因此 Hermes 在检测到本地端点时会将此值提高到 30 分钟。如果你显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论端点检测结果如何，都将始终使用该设定值。

流式停滞检测 (Stale stream detection) 会切断那些仅接收到 SSE 保持活跃（keep-alive） ping 信号但没有实际内容的连接。由于本地提供商在预填充期间不会发送保持活跃 ping，因此对本地提供商完全禁用此项。

非流式停滞检测 (Stale non-stream detection) 会切断那些长时间没有响应的非流式调用。默认情况下，Hermes 在本地端点上禁用此功能，以避免在漫长的预填充过程中出现误报。如果你显式设置了 providers.<id>.stale_timeout_seconds、providers.<id>.models.<model>.stale_timeout_seconds 或 HERMES_API_CALL_STALE_TIMEOUT，即使在本地端点上也会遵循这些显式设定的值。

上下文压力警告 (Context Pressure Warnings)

与迭代预算压力不同，上下文压力追踪的是对话距离压缩阈值（compaction threshold）的接近程度 —— 即触发上下文压缩以总结旧消息的临界点。这有助于你和智能体共同了解对话何时变得过长。

进度	级别	发生的情况
达到阈值的 ≥ 60%	信息	CLI 显示青色进度条；网关发送信息通知
达到阈值的 ≥ 85%	警告	CLI 显示粗体黄色进度条；网关警告压缩即将来临

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

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

在即时通讯平台（网关）上，会发送纯文本通知：

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

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

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

凭据池策略 (Credential Pool Strategies)

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

credential_pool_strategies:
  openrouter: round_robin    # 均匀循环使用各个密钥
  anthropic: least_used      # 始终选择使用次数最少的密钥

选项： fill_first（默认，填满首个）、round_robin（轮询）、least_used（最少使用）、random（随机）。详细文档请参阅 Credential Pools。

辅助模型 (Auxiliary Models)

Hermes 使用 “辅助” 模型来处理侧边任务，如图像分析、网页总结、浏览器截图分析、会话标题生成以及上下文压缩。默认情况下（auxiliary.*.provider: "auto"），Hermes 会将所有辅助任务路由到你的 主聊天模型 —— 即你在 hermes model 中选择的相同提供商/模型。你无需进行任何配置即可开始使用，但请注意，在昂贵的推理模型（如 Opus、MiniMax M2.7 等）上，辅助任务会增加显著的成本。如果你希望无论主模型是什么，侧边任务都能保持 “廉价且快速”，请显式设置 auxiliary.<task>.provider 和 auxiliary.<task>.model（例如，在 OpenRouter 上使用 Gemini Flash 处理视觉和网页提取）。

交互式配置辅助模型

与其手动编辑 YAML，不如运行 hermes model 并从菜单中选择 “Configure auxiliary models”。你会获得一个逐项任务的交互式选择器：

$ hermes model
→ Configure auxiliary models

[ ] vision               当前: auto / 主模型
[ ] web_extract          当前: auto / 主模型
[ ] session_search       当前: openrouter / google/gemini-2.5-flash
[ ] title_generation     当前: openrouter / google/gemini-3-flash-preview
[ ] compression          当前: auto / 主模型
[ ] approval             当前: auto / 主模型
[ ] triage_specifier     当前: auto / 主模型

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

视频课程

通用配置模式

Hermes 中的每个模型插槽 —— 辅助任务、压缩、备用模型 —— 都使用相同的三个控制项：

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

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

辅助任务可用提供商： auto、main，以及提供商注册表中的任何成员 —— openrouter、nous、openai-codex、copilot、anthropic、gemini、deepseek、minimax、ollama-cloud、bedrock 等 —— 或你 custom_providers 列表中的任何自定义提供商。

完整辅助配置参考

auxiliary:
  # 图像分析 (vision_analyze 工具 + 浏览器截图)
  vision:
    provider: "auto"           # "auto", "openrouter", "nous", "main" 等
    model: ""                  # 例如 "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI 兼容端点
    api_key: ""                # base_url 的 API 密钥
    timeout: 120               # 秒 — 视觉负载需要较宽松的超时时间
    download_timeout: 30       # 秒 — 图像下载超时

  # 网页总结 + 浏览器页面文本提取
  web_extract:
    provider: "auto"
    model: ""                  # e.g. "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # 秒 (6分钟) — 每次总结尝试的超时

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

  # 上下文压缩超时 (独立于 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 tool dispatch
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Kanban triage specifier — `hermes kanban specify <id>` (or the
  # dashboard's ✨ Specify button on Triage-column cards) uses this
  # slot to expand a one-liner into a concrete spec and promote the
  # task to `todo`. Cheap fast models work well here; spec expansion
  # is short and doesn't need reasoning depth.
  triage_specifier:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 120

会话搜索调优 (Session Search Tuning)

如果你在 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

当你的提供商对突发请求进行频率限制（rate-limits），且你希望 session_search 通过降低并行度来换取稳定性时，请使用 max_concurrency。

仅当你的提供商文档中注明了你希望 Hermes 在该任务中传递的 OpenAI 兼容请求体字段时，才使用 extra_body。Hermes 会原样转发该对象。

辅助任务的 OpenRouter 路由与 Pareto Code

当辅助任务解析到 OpenRouter 时（无论是显式指定，还是在主智能体使用 OpenRouter 时通过 provider: "main" 路由），主智能体的 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

提供商选项 (Provider Options)

这些选项适用于 辅助任务配置（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 端点。

环境变量 (旧版)

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

设置项	环境变量
视觉提供商 (Vision provider)	`AUXILIARY_VISION_PROVIDER`
视觉模型 (Vision model)	`AUXILIARY_VISION_MODEL`
视觉端点 (Vision endpoint)	`AUXILIARY_VISION_BASE_URL`
视觉 API 密钥 (Vision API key)	`AUXILIARY_VISION_API_KEY`
网页提取提供商 (Web extract provider)	`AUXILIARY_WEB_EXTRACT_PROVIDER`
网页提取模型 (Web extract model)	`AUXILIARY_WEB_EXTRACT_MODEL`
网页提取端点 (Web extract endpoint)	`AUXILIARY_WEB_EXTRACT_BASE_URL`
网页提取 API 密钥 (Web extract API key)	`AUXILIARY_WEB_EXTRACT_API_KEY`

注意： 压缩（Compression）和备用模型（fallback model）设置仅支持通过 config.yaml 配置。

推理强度 (Reasoning Effort)

控制模型在回答前进行多少“思考”：

agent:
  reasoning_effort: ""   # 为空 = medium (默认)。选项：none, minimal, low, medium, high, xhigh (最大)

当未设置（默认）时，推理强度默认为 “medium” —— 这是一个适用于大多数任务的平衡水平。设置具体值后会覆盖默认选项 —— 更高的推理强度在处理复杂任务时会产生更好的结果，但代价是消耗更多 token 且延迟更高。

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

/reasoning —— 显示当前的强度级别和显示状态
/reasoning high —— 将推理强度设置为 high
/reasoning none —— 禁用推理
/reasoning show —— 在每个回答上方显示模型思考过程
/reasoning hide —— 隐藏模型思考过程

工具使用强制执行 (Tool-Use Enforcement)

某些模型偶尔会将预定操作描述为文本，而不是进行实际的工具调用（例如，说 “我会运行测试…” 而不是真正调用终端）。工具使用强制执行机制会向系统提示词中注入引导信息，从而引导模型回归到实际调用工具的行为。

agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["模型子字符串", ...]

属性值	行为
”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 Configuration)

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 Settings)

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 皮肤
  personality: "kawaii"  # 旧版外观字段，仍出现在某些摘要中
  compact: false          # 紧凑输出模式（减少空白）
  resume_display: full    # full (恢复时显示之前的消息) | minimal (仅显示一行)
  bell_on_complete: false # 智能体完成任务时播放终端铃声（适合耗时任务）
  show_reasoning: false   # 在每个回答上方显示模型推理/思考过程（通过 /reasoning show|hide 切换）
  streaming: false        # 在 token 到达时将其流式传输到终端（实时输出）
  show_cost: false        # 在 CLI 状态栏中显示预估美元成本
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 无限制，显示完整路径/命令）
  runtime_footer:         # 网关：在最终回复中附加运行时上下文页脚
    enabled: false
    fields: ["model", "context_pct", "cwd"]
  language: en            # 静态消息的 UI 语言（审批提示、部分网关回复）。en | zh | ja | de | es | fr | tr | uk

文件变更校验器 (File-mutation verifier)

当 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 审批提示、少数网关斜杠命令回复（例如重启排空通知、“审批已过期”、“目标已清除”）。它不会翻译智能体的回答、日志行、工具输出、错误追溯或斜杠命令说明 —— 这些内容保持为英文。如果你希望智能体本身以另一种语言回答，只需在提示词或系统消息中告知它即可。

支持的值： 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 状态栏中显示的相同信息（模型、上下文占比、当前工作目录、会话时长、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 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 会将已完成的回合中期助手更新作为独立的聊天消息发送。这与 tool_progress 相互独立，且不需要网关流式传输支持。

隐私 (Privacy)

privacy:
  redact_pii: false  # 从 LLM 上下文中脱敏个人身份信息（仅限网关）

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

字段	处理方式
电话号码（WhatsApp/Signal 上的用户 ID）	哈希处理为 `user_<12位字符的sha256>`
用户 ID	哈希处理为 `user_<12位字符的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 中的按住说话（Push-to-talk）快捷键
  max_recording_seconds: 120    # 长录音的强制停止时间
  auto_tts: false               # 当 /voice 开启时自动启用语音回复
  beep_enabled: true            # 在 CLI 语音模式下播放录音开始/停止的提示音
  silence_threshold: 200        # 用于语音检测的 RMS 阈值
  silence_duration: 3.0         # 自动停止前的静音秒数

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

流式传输 (Streaming)

在 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 则始终就地编辑。

群聊会话隔离 (Group Chat Session Isolation)

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

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

true 是默认值，也是推荐设置。在 Discord 频道、Telegram 群组、Slack 频道以及类似的共享上下文中，只要平台提供了用户 ID，每位发送者都会获得自己的独立会话。
false 会恢复到旧版的共享房间行为。如果你明确希望 Hermes 将一个频道视为一场协作对话，这会很有用，但这也意味着用户将共享上下文、token 成本和中断状态。
私聊（Direct messages） 不受影响。Hermes 仍像往常一样通过聊天/私聊 ID 来索引私聊。
无论如何设置，帖子/线程（Threads） 都会与其父频道保持隔离；在设置为 true 的情况下，线程内的每个参与者也会获得各自的会话。

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

未授权私聊行为 (Unauthorized DM Behavior)

控制当未知用户发送私聊消息时 Hermes 的行为：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair 是默认设置。Hermes 会拒绝访问，但在私聊中回复一个一次性的配对代码。
ignore 会静默丢弃未授权的私聊消息。
平台特定的配置区块会覆盖全局默认设置，因此你可以保持广泛启用配对功能，同时让某个特定平台更加安静。

快捷命令 (Quick Commands)

定义自定义命令，可以直接运行 shell 命令而不调用 LLM，或者将一个斜杠命令映射到另一个命令（别名）。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 秒超时：长时间运行的命令将被终止并显示错误消息。
优先级：快捷命令在技能（skill）命令之前进行检查，因此你可以覆盖技能名称。
自动补全：快捷命令在分发时解析，不会显示在内置的斜杠命令自动补全表格中。
类型：支持的类型为 exec 和 alias；其他类型将显示错误。
全平台通用：适用于 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant。

注意：仅包含字符串的提示词快捷方式（Prompt shortcuts）不是有效的快捷命令。对于可重用的提示词工作流，请创建一个技能或设置一个指向现有斜杠命令的别名。

人为延迟 (Human Delay)

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

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

代码执行 (Code Execution)

配置 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 Backends)

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

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

  # 或者使用针对特定能力的配置项来混合使用提供商（例如：免费搜索 + 付费提取）：
  search_backend: "searxng"
  extract_backend: "firecrawl"

后端	环境变量	搜索 (Search)	提取 (Extract)	爬取 (Crawl)
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（智能体模式，默认值）。

Exa：在 ~/.hermes/.env 中设置 EXA_API_KEY。支持 category 分类过滤公司(company)、研究论文(research paper)、新闻(news)、人物(people)、个人网站(personal site)、pdf 以及域名/日期过滤。

浏览器 (Browser)

配置浏览器自动化行为：

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 和默认的本地智能体浏览器模式下会被忽略。
  dialog_policy: must_respond    # must_respond | auto_dismiss | auto_accept
  dialog_timeout_s: 300          # must_respond 模式下的安全自动关闭时间（秒）
  camofox:
    managed_persistence: false   # 为 true 时，Camofox 会在重启后保留 Cookie/登录状态
    user_id: ""                  # Optional externally managed Camofox userId
    session_key: ""              # Optional session key sent when Hermes creates a tab
    adopt_existing_tab: false    # Reuse an existing tab for this identity before creating one

对话框策略：

must_respond（默认）—— 捕获对话框，将其显示在 browser_snapshot.pending_dialogs 中，并等待智能体调用 browser_dialog(action=...)。如果 dialog_timeout_s 秒内没有响应，对话框将自动关闭，以防止页面的 JS 线程永久停滞。
auto_dismiss —— 捕获并立即关闭。智能体随后仍能在 browser_snapshot.recent_dialogs 中看到该对话框记录，其 closed_by 值为 "auto_policy"。
auto_accept —— 捕获并立即接受。对于带有强制性 beforeunload 提示的页面非常有用。

有关完整的对话框工作流，请参阅浏览器功能页面。该工具集支持多个提供商（如 Browserbase、Browser Use 和本地 Chrome CDP 配置等），详见相关文档。

时区 (Timezone)

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

timezone: "America/New_York"   # IANA 时区（默认："" = 服务器本地时间）

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

Discord

为消息网关配置 Discord 特有的行为：

discord:
  require_mention: true          # 在服务器频道中回复时是否需要 @mention（艾特）
  free_response_channels: ""     # 逗号分隔的频道 ID，机器人无需被艾特即可在这些频道中回复
  auto_thread: true              # 在频道中被艾特时自动创建帖子/线程

require_mention —— 为 true（默认）时，机器人仅在被 @机器人名称 艾特时才在服务器频道中回复。私聊（DM）始终无需艾特。
free_response_channels —— 频道 ID 列表，机器人在这些频道内会响应每一条消息。
auto_thread —— 为 true（默认）时，频道内的艾特会自动为对话创建一个帖子/线程，以保持频道整洁（类似于 Slack 的线程机制）。

安全 (Security)

执行前的安全扫描和敏感信息脱敏：

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 密钥、令牌（token）和密码的模式，然后再将其进入对话上下文和日志。默认关闭 — 如果您经常在工具输出中使用真实凭据并希望获得安全保障，请启用此项。显式设置为 true 以开启。
tirith_enabled — 当为 true 时，终端命令在执行前将由 Tirith 进行扫描，以检测潜在的危险操作。
tirith_path — tirith 二进制文件的路径。如果 tirith 安装在非标准位置，请设置此项。
tirith_timeout — 等待 tirith 扫描的最长秒数。如果扫描超时，命令将继续执行。
tirith_fail_open — 当为 true（默认）时，如果 tirith 不可用或失败，允许执行命令。设置为 false 时，若 tirith 无法验证命令，则拦截该命令。

网站黑名单 (Website Blocklist)

禁止智能体的网页和浏览器工具访问特定的域名：

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 秒，因此配置更改无需重启即可快速生效。

Smart Approvals

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

approvals:
   mode: manual   # manual | smart | off

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

智能模式（Smart mode）对于减少审批疲劳特别有用 —— 它让代理在安全操作上更自主地工作，同时仍能捕捉到真正具有破坏性的命令。

Checkpoints

在破坏性文件操作之前自动执行文件系统快照。详见 “检查点与回滚（Checkpoints & Rollback）”。

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

Delegation

为 delegate 工具配置子代理（subagent）行为：

delegation:
    # model: "google/gemini-3-flash-preview"  # 覆盖模型（为空 = 继承父级）
    # provider: "openrouter"                  # 覆盖供应商（为空 = 继承父级）
    # base_url: "http://localhost:1234/v1"    # 直接指向 OpenAI 兼容端点（优先级高于 provider）
    # api_key: "local-key"                    # base_url 的 API 密钥（回退至 OPENAI_API_KEY）
    max_concurrent_children: 3                # 每批次并行子代理数量（最小为 1，无上限）。也可通过 DELEGATION_MAX_CONCURRENT_CHILDREN 环境变量设置。
    max_spawn_depth: 1                        # 授权树深度上限（1-3，强制锚定）。1 = 扁平（默认）：父级生成的叶子节点无法再授权。2 = 编排者（orchestrator）子级可以生成叶子孙级。3 = 三层结构。
    orchestrator_enabled: true                # 全局总开关。为 false 时，role="orchestrator" 将被忽略，无论 max_spawn_depth 为多少，每个子代理都强制为叶子节点。

子代理供应商:模型覆盖： 默认情况下，子代理继承父代理的供应商和模型。设置 delegation.provider 和 delegation.model 可以将子代理路由到不同的供应商:模型组合 —— 例如，在主代理运行昂贵的推理模型时，使用廉价/快速的模型处理范围较窄的子任务。

直接端点覆盖： 如果你想使用自定义端点路径，请设置 delegation.base_url、delegation.api_key 和 delegation.model。这会将子代理直接发送到该 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、智谱 GLM，或者代理了 Anthropic 格式后端的 LiteLLM 代理 —— 请将 delegation.api_mode 明确设置为 chat_completions、codex_responses 或 anthropic_messages 之一。保持为空（默认值）则继续使用自动检测。

授权供应商使用与 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 限制了每批次并行运行的子代理数量（默认 3，最小 1，无上限）。也可以通过 DELEGATION_MAX_CONCURRENT_CHILDREN 环境变量进行设置。当模型提交的 tasks 数组长度超过上限时，delegate_task 会返回说明限制的工具错误，而不是静默截断。max_spawn_depth 控制授权树的深度（强制在 1-3 之间）。在默认值 1 时，授权是扁平的：子级不能生成孙级，且传递 role="orchestrator" 会静默降级为 leaf。提高到 2，编排者子级可以生成叶子孙级；3 则支持三层树结构。代理通过每次调用的 role="orchestrator" 来选择加入编排；orchestrator_enabled: false 会强制所有子代理回归叶子节点，无论其他设置如何。成本呈乘法级增长 —— 在 max_spawn_depth: 3 且 max_concurrent_children: 3 时，树结构最多可达 3×3×3 = 27 个并发叶子代理。有关使用模式，请参阅子代理授权 → 深度限制与嵌套编排。

Clarify

配置澄清提示（clarification prompt）行为：

clarify:
    timeout: 120                 # 等待用户澄清回复的秒数

Context Files (SOUL.md, AGENTS.md)

Hermes 使用两种不同的上下文范围：

文件	用途	范围
SOUL.md	主代理身份 —— 定义代理是谁（系统提示词中的第 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 是代理的核心身份。它占据系统提示词的第 1 栏，完全取代内置的默认身份。通过编辑它来全面自定义代理的人设。
如果 SOUL.md 缺失、为空或无法加载，Hermes 将回退到内置的默认身份。
项目上下文文件 采用优先级系统 —— 仅加载其中一种类型（首个匹配项胜出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
AGENTS.md 具有层级性：如果子目录也包含 AGENTS.md，则所有内容都会被合并。
如果尚不存在 SOUL.md，Hermes 会自动生成一个默认文件。
所有加载的上下文文件上限为 20,000 个字符，并带有智能截断。

另请参阅：

Working Directory

上下文	默认值
CLI (hermes)	运行命令所在的当前目录
Messaging gateway	用户主目录 `~`（可通过 `MESSAGING_CWD` 覆盖）
Docker / Singularity / Modal / SSH	容器或远程机器内的用户主目录

覆盖工作目录：

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