配置

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

目录结构

~/.hermes/
├── config.yaml     # 设置（模型、终端、TTS、压缩等）
├── .env            # API 密钥和密钥
├── auth.json       # OAuth Provider 凭据（Nous Portal 等）
├── SOUL.md         # 主要 Agent 身份（系统提示中的插槽 #1）
├── memories/       # 持久记忆（MEMORY.md, USER.md）
├── skills/         # Agent 创建的 Skill（通过 skill_manage 工具管理）
├── cron/           # 定时任务
├── sessions/       # 网关会话
└── logs/           # 日志（errors.log, gateway.log — 密钥自动脱敏）

管理配置

hermes config              # 查看当前配置
hermes config edit         # 在编辑器中打开 config.yaml
hermes config set KEY VAL  # 设置特定值
hermes config check        # 检查缺失选项（更新后使用）
hermes config migrate      # 交互式添加缺失选项

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

提示

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

配置优先级

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

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

经验法则

密钥（API 密钥、Bot 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 Provider 设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），参见 AI Providers。

Provider 超时

你可以通过 providers.<id>.request_timeout_seconds 设置提供商级别的请求超时，以及通过 providers.<id>.models.<model>.timeout_seconds 设置模型特定的覆盖。适用于所有传输（OpenAI 协议、原生 Anthropic、Anthropic 兼容）上的主动轮次客户端、Fallback 链、凭证轮换后的重建，以及（对于 OpenAI 协议）每请求超时参数 — 因此配置值优先于旧的 HERMES_API_TIMEOUT 环境变量。

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

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

终端后端配置

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

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # 工作目录（"." = local 使用当前目录，容器使用 "/root"）
  timeout: 180      # 每条命令的超时时间（秒）
  env_passthrough: []  # 转发到沙箱执行的环境变量名（terminal + execute_code）
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Singularity 后端的容器镜像
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Modal 后端的容器镜像
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Daytona 后端的容器镜像

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

后端概览

后端	命令执行位置	隔离性	适用场景
local	你的本机	无	开发、个人使用
docker	Docker 容器	完整（命名空间、cap-drop）	安全沙箱、CI/CD
ssh	通过 SSH 的远程服务器	网络边界	远程开发、强大硬件
modal	Modal 云沙箱	完整（云 VM）	临时云计算、评估
daytona	Daytona 工作区	完整（云容器）	托管云开发环境
singularity	Singularity/Apptainer 容器	命名空间（--containall）	HPC 集群、共享机器

Local 后端

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

terminal:
  backend: local

注意

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

Docker 后端

在 Docker 容器内运行命令，带有安全加固（丢弃所有能力、禁止权限提升、PID 限制）。

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

  # 资源限制
  container_cpu: 1                 # CPU 核心数（0 = 无限制）
  container_memory: 5120           # MB（0 = 无限制）
  container_disk: 51200            # MB（需要 XFS+pquota 上的 overlay2）
  container_persistent: true       # 跨会话持久化 /workspace 和 /root

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

容器生命周期： 每次会话启动一个长生命周期容器（docker run -d ... sleep 2h）。命令通过 docker exec 使用登录 Shell 执行。清理时，容器停止并移除。

安全加固：

--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 解析。Skill 也可以声明 required_environment_variables，这些会自动合并。

SSH 后端

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

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

必需的环境变量：

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

可选：

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

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

在 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 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。超过此值的请求会被上限截断并发出警告。

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，先验证命令能在那里运行。

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" # Gateway 可见的导出

适用于：

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

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

在 Docker 内将文件写入 /output/...
在 MEDIA: 中发出主机路径，例如：MEDIA:/home/user/.hermes/cache/documents/report.txt
不要发出 /workspace/... 或 /output/...，除非该确切路径在主机上的 Gateway 进程也可访问

注意

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 保存过）。

注意

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

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

Docker 沙箱默认保持隔离。除非你明确选择启用，Hermes 不会将当前的宿主机工作目录传入容器。

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用时：

如果你从 ~/projects/my-app 启动 Hermes，该宿主机目录会被绑定挂载到 /workspace
Docker 后端在 /workspace 中启动
文件工具和终端命令都看到相同的挂载项目

禁用时，/workspace 保持沙箱自有，除非你通过 docker_volumes 显式挂载。

安全权衡：

false 保持沙箱边界
true 给沙箱直接访问你启动 Hermes 的目录

仅在有意让容器处理实时宿主机文件时才启用此选项。

持久 Shell

默认情况下，每条终端命令在自己的子进程中运行 —— 工作目录、环境变量和 Shell 变量在命令之间重置。启用持久 Shell 后，一个长期运行的 bash 进程在 execute() 调用之间保持活跃，使状态在命令之间保持。

这对 SSH 后端最有用，还能消除每条命令的连接开销。持久 Shell 对 SSH 默认启用，对 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

备注

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

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

Skill 设置

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

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

Skill 设置的工作原理：

hermes config migrate 扫描所有启用的 Skill，找到未配置的设置，并提示你输入
hermes config show 在"Skill 设置"下显示所有 Skill 设置及其所属 Skill
Skill 加载时，其解析后的配置值会自动注入 Skill 上下文

手动设置值：

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

关于在你自己的 Skill 中声明配置设置的详情，参见创建 Skill — 配置设置。

记忆配置

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

文件读取安全

控制单次 read_file 调用可以返回多少内容。超过限制的读取会被拒绝并返回错误，告诉 Agent 使用 offset 和 limit 读取更小的范围。这防止单次读取压缩 JS 包或大型数据文件导致上下文窗口溢出。

file_read_max_chars: 100000  # 默认 — 约 25-35K Token

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

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

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

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

Git Worktree 隔离

启用隔离的 Git Worktree 以在同一仓库上并行运行多个 Agent：

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

启用时，每个 CLI 会话在 .worktrees/ 下创建一个带有自己分支的新 Worktree。Agent 可以编辑文件、提交、推送和创建 PR，互不干扰。干净的 Worktree 在退出时移除；有未提交更改的保留以便手动恢复。

你还可以通过仓库根目录中的 .worktreeinclude 列出要复制到 Worktree 的 gitignored 文件：

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩

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

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

完整参考

compression:
  enabled: true                                     # 开关压缩
  threshold: 0.50                                   # 在上下文限制的此百分比时压缩
  target_ratio: 0.20                                # 作为近期尾部保留的阈值比例
  protect_last_n: 20                                # 保持不压缩的最少近期消息数

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

旧配置迁移

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

常见配置

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

compression:
  enabled: true
  threshold: 0.50

使用第一个可用的 Provider（OpenRouter → Nous → Codex）配合 Gemini Flash。

强制指定 Provider（OAuth 或 API 密钥）：

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

适用于任何 Provider：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`（默认）	未设置	自动检测最佳可用 Provider
`nous` / `openrouter` / 等	未设置	强制使用该 Provider，使用其认证
任意	已设置	直接使用自定义端点（Provider 被忽略）

摘要模型上下文长度要求

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

上下文引擎

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

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

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

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

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

参见 Memory Providers 了解类似的内存插件单选系统。

迭代预算压力

当 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）

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

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

API 超时

Hermes 有独立的流式超时层，加上非流式调用的过期检测器。过期检测器仅在保留隐式默认值时为本地 Provider 自动调整。

超时	默认值	本地 Provider	配置 / 环境变量
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 等待 Provider 下一个数据块的时间。本地 LLM 在大上下文的预填充阶段可能需要几分钟才能产生第一个 Token，因此 Hermes 检测到本地端点时会将其提升到 30 分钟。如果你显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论端点检测结果如何都使用该值。

静默流检测会终止接收 SSE 保活 Ping 但无实际内容的连接。这对本地 Provider 完全禁用，因为它们在预填充期间不发送保活 Ping。

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

上下文压力警告

与迭代预算压力分开，上下文压力跟踪对话距离压缩阈值的接近程度 —— 即上下文压缩触发摘要旧消息的时间点。这帮助你和 Agent 了解对话何时变长。

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

在 CLI 中，上下文压力显示为工具输出信息流中的进度条：

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

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

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

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

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

凭据池策略

当你有同一 Provider 的多个 API 密钥或 OAuth Token 时，配置轮换策略：

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

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

辅助模型

Hermes 使用轻量级"辅助"模型处理图片分析、网页摘要和浏览器截图分析等辅助任务。默认情况下，这些使用 Gemini Flash 通过自动检测 —— 无需配置。

通用配置模式

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

键	作用	默认值
`provider`	使用哪个 Provider 进行认证和路由	`"auto"`
`model`	请求哪个模型	Provider 的默认值
`base_url`	自定义 OpenAI 兼容端点（覆盖 Provider）	未设置

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

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

"main" 仅用于辅助任务

"main" Provider 选项表示"使用我主 Agent 使用的任何 Provider" —— 它只在 auxiliary:、compression: 和 fallback_model: 配置内有效。它不是顶层 model.provider 设置的有效值。如果你使用自定义 OpenAI 兼容端点，在 model: 部分设置 provider: custom。参见 AI Providers 了解所有主模型 Provider 选项。

完整辅助配置参考

auxiliary:
  # 图片分析（vision_analyze 工具 + 浏览器截图）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI 兼容端点（覆盖 Provider）
    api_key: ""                # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
    timeout: 120               # 秒 — LLM API 调用超时；视觉载荷需要充足的超时
    download_timeout: 30       # 秒 — 图片 HTTP 下载；慢连接时增加

  # 网页摘要 + 浏览器页面文本提取
  web_extract:
    provider: "auto"
    model: ""                  # 例如 "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # 秒（6分钟）— 每次尝试的 LLM 摘要

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

  # 上下文压缩超时（与 compression.* 配置分开）
  compression:
    timeout: 120               # 秒 — 压缩摘要长对话，需要更多时间

  # 会话搜索 — 摘要过去的会话匹配
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
    max_concurrency: 3       # 限制并行摘要以减少请求突发 429 错误
    extra_body: {}           # 提供商特定的 OpenAI 兼容请求字段

  # Skills Hub — Skill 匹配和搜索
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP 工具分发
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # 记忆刷新 — 摘要对话用于持久记忆
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

提示

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

信息

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

会话搜索调优

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

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

示例：

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

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

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

注意

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

更改视觉模型

使用 GPT-4o 代替 Gemini Flash 进行图片分析：

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

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

AUXILIARY_VISION_MODEL=openai/gpt-4o

Provider 选项

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

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
`"main"`	使用你的活跃自定义/主端点。可来自 `OPENAI_BASE_URL` + `OPENAI_API_KEY` 或通过 `hermes model` / `config.yaml` 保存的自定义端点。适用于 OpenAI、本地模型或任何 OpenAI 兼容 API。仅限辅助任务 — 对 `model.provider` 无效。	自定义端点凭据 + base URL

常见配置

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

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

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

使用 OpenAI API 密钥进行视觉：

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

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

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

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

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

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

使用本地/自托管模型：

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

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

提示

如果你使用 Codex OAuth 作为主模型 Provider，视觉会自动工作 —— 无需额外配置。Codex 已包含在视觉的自动检测链中。

注意

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

环境变量（旧版）

辅助模型也可以通过环境变量配置。但 config.yaml 是首选方法 —— 更易管理且支持所有选项包括 base_url 和 api_key。

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

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

提示

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

推理强度

控制模型响应前做多少"思考"：

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

未设置时（默认），推理强度默认为 "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                    # 全局速度倍率（所有 Provider 的回退）
  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 或消息网关）。

速度回退层级： Provider 特定速度（如 tts.edge.speed）→ 全局 tts.speed → 1.0 默认。设置全局 tts.speed 可在所有 Provider 间应用统一速度，或按 Provider 覆盖以进行精细控制。

显示设置

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # 在消息网关中启用 /verbose 斜杠命令
  tool_progress_overrides: {}  # 按平台覆盖（见下文）
  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 状态栏中显示预估费用
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 无限制，显示完整路径/命令）

模式	你看到的
`off`	静默 — 仅最终响应
`new`	工具变化时显示指示器
`all`	每个工具调用带简短预览（默认）
`verbose`	完整参数、结果和调试日志

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

按平台进度覆盖

不同平台有不同的详细度需求。例如，Signal 无法编辑消息，因此每次进度更新都变成一条单独消息 —— 很吵。使用 tool_progress_overrides 设置按平台的模式：

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

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

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	数字部分哈希
用户名 / username	不受影响（用户自选、公开可见）

平台支持： 脱敏适用于 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"         # 旧版回退键仍然有效

Provider 行为：

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

如果请求的 Provider 不可用，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 时自动语音回复
  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 出现在流式框内。工具调用仍静默捕获。如果 Provider 不支持流式传输，自动回退到正常显示。

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

streaming:
  enabled: true           # 启用渐进式消息编辑
  transport: edit         # "edit"（渐进式消息编辑）或 "off"
  edit_interval: 0.3      # 消息编辑间隔（秒）
  buffer_threshold: 40    # 强制编辑刷新的字符数
  cursor: " ▉"            # 流式传输时显示的光标

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

对于不使用渐进式 Token 编辑的独立自然轮次中间助手更新，设置 display.interim_assistant_messages: true。

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

备注

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

群聊会话隔离

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

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

true 是默认且推荐的设置。在 Discord 频道、Telegram 群组、Slack 频道等共享环境中，当平台提供用户 ID 时，每个发送者都有自己的会话。
false 恢复旧的共享房间行为。如果你明确希望 Hermes 将频道视为一个协作对话，这可能有用，但也意味着用户共享上下文、Token 费用和中断状态。
私信不受影响。Hermes 仍按聊天/私信 ID 处理私信。
线程无论如何都与父频道隔离；启用 true 时，每个参与者在线程内也有自己的会话。

行为详情和示例参见会话和 Discord 指南。

未授权私信行为

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

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

快捷命令

定义自定义命令，运行 Shell 命令而无需调用 LLM —— 零 Token 消耗，即时执行。特别适合从消息平台（Telegram、Discord 等）快速检查服务器或运行工具脚本。

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

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

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

模拟人类延迟

在消息平台中模拟类人的回复节奏：

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

代码执行

配置 execute_code 工具：

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

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

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

环境清理（剥离 *_API_KEY、*_TOKEN、*_SECRET、*_PASSWORD、*_CREDENTIAL、*_PASSWD、*_AUTH）和工具白名单在两种模式下相同 —— 切换模式不改变安全态势。

网页搜索后端

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

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

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

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

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

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

浏览器

配置浏览器自动化行为：

browser:
  inactivity_timeout: 120        # 空闲会话自动关闭的秒数
  command_timeout: 30             # 浏览器命令超时秒数（截图、导航等）
  record_sessions: false         # 自动录制浏览器会话为 WebM 视频到 ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # 为 true 时，Camofox 会话跨重启持久化 Cookie/登录

浏览器工具集支持多个 Provider。详见浏览器功能页了解 Browserbase、Browser Use 和本地 Chrome CDP 设置。

时区

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

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

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

Discord

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

discord:
  require_mention: true          # 在服务器频道中需要 @提及才响应
  free_response_channels: ""     # Bot 无需 @提及即响应的频道 ID（逗号分隔）
  auto_thread: true              # 在频道中被 @提及时自动创建线程

require_mention — 为 true（默认）时，Bot 仅在被 @BotName 提及时才在服务器频道中响应。私信始终无需提及。
free_response_channels — 逗号分隔的频道 ID 列表，Bot 在这些频道中对每条消息响应而无需提及。
auto_thread — 为 true（默认）时，频道中的提及会自动为对话创建线程，保持频道整洁（类似 Slack 线程）。

安全

预执行安全扫描和密钥脱敏：

security:
  redact_secrets: true           # 在工具输出和日志中脱敏 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 — 自动检测并脱敏工具输出中类似 API 密钥、Token 和密码的模式，在进入对话上下文和日志之前。
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 在安全操作上更自主工作，同时仍捕获真正具有破坏性的命令。

注意

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

检查点

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

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

委派

配置 delegate 工具的子 Agent 行为：

delegation:
  # model: "google/gemini-3-flash-preview"  # 覆盖模型（空 = 继承父级）
  # provider: "openrouter"                  # 覆盖 Provider（空 = 继承父级）
  # base_url: "http://localhost:1234/v1"    # 直接 OpenAI 兼容端点（优先于 Provider）
  # api_key: "local-key"                    # base_url 的 API 密钥（回退到 OPENAI_API_KEY）

子 Agent Provider:模型覆盖： 默认情况下，子 Agent 继承父 Agent 的 Provider 和模型。设置 delegation.provider 和 delegation.model 可将子 Agent 路由到不同的 Provider:模型对 —— 例如，对范围狭窄的子任务使用便宜/快速的模型，而主 Agent 运行昂贵的推理模型。

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

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

优先级： 配置中的 delegation.base_url → 配置中的 delegation.provider → 父级 Provider（继承）。配置中的 delegation.model → 父级模型（继承）。只设置 model 不设置 provider 仅更改模型名称而保持父级的凭据（适用于在同一 Provider 如 OpenRouter 内切换模型）。

澄清

配置澄清提示行为：

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

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

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

文件	用途	范围
`SOUL.md`	主要 Agent 身份 — 定义 Agent 是谁（系统提示中的插槽 #1）	`~/.hermes/SOUL.md` 或 `$HERMES_HOME/SOUL.md`
`.hermes.md` / `HERMES.md`	项目特定指令（最高优先级）	遍历到 Git 根目录
`AGENTS.md`	项目特定指令、编码约定	递归目录遍历
`CLAUDE.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                # 所有终端会话

📝 本文由 AI 翻译，如有疑问请参考英文原版

目录结构​

管理配置​

配置优先级​

环境变量替换​

Provider 超时​

终端后端配置​

后端概览​

Local 后端​

Docker 后端​

SSH 后端​

Modal 后端​

Daytona 后端​

Singularity/Apptainer 后端​

常见终端后端问题​

Docker 卷挂载​

Docker 凭据转发​

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

持久 Shell​

Skill 设置​

记忆配置​

文件读取安全​

Git Worktree 隔离​

上下文压缩​

完整参考​

常见配置​

三个旋钮的交互方式​

上下文引擎​

迭代预算压力​

API 超时​

上下文压力警告​

凭据池策略​

辅助模型​

通用配置模式​

完整辅助配置参考​

会话搜索调优​

更改视觉模型​

Provider 选项​

常见配置​

环境变量（旧版）​

推理强度​

工具使用强制​

它注入什么​

何时启用​

TTS（文本转语音）配置​

显示设置​

按平台进度覆盖​

隐私​

语音转文本（STT）​

语音模式（CLI）​

流式传输​

CLI 流式传输​

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

群聊会话隔离​

未授权私信行为​

快捷命令​

模拟人类延迟​

代码执行​

网页搜索后端​

浏览器​

时区​

Discord​

安全​

网站屏蔽列表​

智能审批​

检查点​

委派​

澄清​

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

工作目录​

目录结构

管理配置

配置优先级

环境变量替换

Provider 超时

终端后端配置

后端概览

Local 后端

Docker 后端

SSH 后端

Modal 后端

Daytona 后端

Singularity/Apptainer 后端

常见终端后端问题

Docker 卷挂载

Docker 凭据转发

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

持久 Shell

Skill 设置

记忆配置

文件读取安全

Git Worktree 隔离

上下文压缩

完整参考

常见配置

三个旋钮的交互方式

上下文引擎

迭代预算压力

API 超时

上下文压力警告

凭据池策略

辅助模型

通用配置模式

完整辅助配置参考

会话搜索调优

更改视觉模型

Provider 选项

常见配置

环境变量（旧版）

推理强度

工具使用强制

它注入什么

何时启用

TTS（文本转语音）配置

显示设置

按平台进度覆盖

隐私

语音转文本（STT）

语音模式（CLI）

流式传输

CLI 流式传输

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

群聊会话隔离

未授权私信行为

快捷命令

模拟人类延迟

代码执行

网页搜索后端

浏览器

时区

Discord

安全

网站屏蔽列表

智能审批

检查点

委派

澄清

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

工作目录