配置

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

目录结构

~/.hermes/
├── config.yaml     # 设置（模型、终端、TTS、压缩等）
├── .env            # API 密钥和密钥
├── auth.json       # OAuth provider 凭证（Nous Portal 等）
├── SOUL.md         # 主要 agent 身份（系统提示词中的 slot #1）
├── memories/       # 持久化内存（MEMORY.md、USER.md）
├── skills/         # agent 创建的 skills（通过 skill_manage 工具管理）
├── cron/           # 定时任务
├── sessions/       # Gateway 会话
└── logs/           # 日志（errors.log、gateway.log — 密钥自动编辑）

管理配置

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

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

提示

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

配置优先级

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

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

经验法则

密钥（API 密钥、机器人令牌、密码）放在 .env。其他所有内容（模型、终端后端、压缩设置、内存限制、工具集）放在 config.yaml。当两者都设置时，config.yaml 在非密钥设置方面优先。

环境变量替换

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

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。

终端后端配置

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

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # 工作目录（"." = 本地当前目录，"/root" 用于容器）
  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 等云沙箱，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 解析。Skills 还可以声明 required_environment_variables，这些变量会自动合并。

SSH 后端

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

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

必需的环境变量：

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

可选：

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

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

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

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

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

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

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

Daytona 后端

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

terminal:
  backend: daytona
  container_cpu: 1                 # CPU 核心数
  container_memory: 5120           # MB → 转换为 GiB
  container_disk: 10240            # MB → 转换为 GiB（最大 10 GiB）
  container_persistent: true       # 停止而不是删除

必需： DAYTONA_API_KEY 环境变量。

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

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

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       # 可写覆盖跨会话持久化

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

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

临时目录： 按顺序解析： TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent（HPC 约定）→ ~/.hermes/sandboxes/singularity。

隔离： 使用 --containall --no-home 进行完整的命名空间隔离，而不挂载主机主目录。

常见终端后端问题

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

Local — 无特殊要求。入门时最安全的选择。
Docker — 运行 docker version 验证 Docker 工作正常。如果失败，修复 Docker 或设置 hermes config set terminal.backend local。
SSH — TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER 都必须设置。如果任一缺失，Hermes 会记录清晰的错误。
Modal — 需要 MODAL_TOKEN_ID 环境变量或 ~/.modal.toml。运行 hermes doctor 检查。
Daytona — 需要 DAYTONA_API_KEY。Daytona SDK 处理服务器 URL 配置。
Singularity — 需要 apptainer 或 singularity 在 $PATH 中。常见于 HPC 集群。

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

Docker 卷挂载

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

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

这对于以下场景很有用：

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

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

Docker 凭证转发

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

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

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

注意

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

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

Docker 沙箱默认保持隔离。Hermes 不会将您当前的主机工作目录传递到容器中，除非您明确选择加入。

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用后：

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

禁用时，/workspace 保持沙箱所有，除非您通过 docker_volumes 明确挂载内容。

安全权衡：

false 保留沙箱边界
true 给予沙箱直接访问您启动 Hermes 的目录的权限

仅在您有意希望容器处理实时主机文件时才使用opt-in。

持久 Shell

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

这对于 SSH 后端最有用，它还消除了每个命令的连接开销。持久 shell 默认启用 for SSH，禁用 for 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`

每个后端的环境变量具有最高优先级。如果您也想在本地后端启用持久 shell：

export TERMINAL_LOCAL_PERSISTENT=true

备注

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

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

Skill 设置

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

skills:
  config:
    wiki:
      path: ~/wiki          # llm-wiki skill 使用

skill 设置的工作原理：

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

手动设置值：

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

有关在您自己的 skills 中声明配置设置的详细信息，请参阅 Creating Skills — Config Settings。

内存配置

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

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

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

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

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

Git Worktree 隔离

为在同一仓库上并行运行多个 agent 启用隔离的 git worktrees：

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

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

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

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩

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

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

完整参考

compression:
  enabled: true                                     # 切换压缩开/关
  threshold: 0.50                                   # 在上下文限制的此百分比处压缩
  target_ratio: 0.20                                # 作为最近尾部的保留比例
  protect_last_n: 20                                # 保持未压缩的最小最近消息数

# summarization model/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）

Summarization 模型上下文长度要求

summary 模型必须具有与您的主要 agent 模型至少一样大的上下文窗口。压缩器将对话的完整中间部分发送到 summary 模型 — 如果该模型的上下文窗口小于主要模型的，summarization 调用将因上下文长度错误而失败。当这种情况发生时，中间轮次在没有任何摘要的情况下被丢弃，静默丢失对话上下文。如果您覆盖模型，请验证其上下文长度满足或超过您的主要模型。

上下文引擎

上下文引擎控制对话在接近模型令牌限制时的管理方式。内置的 compressor 引擎使用有损摘要（请参阅 Context Compression）。插件引擎可以用替代策略替换它。

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

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

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

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

有关 memory plugins 的类似单一选择系统，请参阅 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。如果预算在 active work 期间耗尽，agent 会生成一个关于完成内容的摘要然后停止。

流式超时

LLM 流式连接有两层超时。两者都为本地 provider（localhost、LAN IP）自动调整 — 大多数设置无需配置。

超时	默认值	本地 provider	环境变量
Socket 读取超时	120s	自动提高到 1800s	`HERMES_STREAM_READ_TIMEOUT`
过时流检测	180s	自动禁用	`HERMES_STREAM_STALE_TIMEOUT`
API 调用（非流式）	1800s	不变	`HERMES_API_TIMEOUT`

socket 读取超时 控制 httpx 等待 provider 下一块数据的时长。本地 LLM 在大上下文上进行预填充时可能需要数分钟才能产生第一个 token，因此当 Hermes 检测到本地端点时会将其提高到 30 分钟。如果您明确设置 HERMES_STREAM_READ_TIMEOUT，则无论端点检测如何，都将始终使用该值。

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

上下文压力警告

与迭代预算压力不同，上下文压力跟踪对话接近压缩阈值的程度 — 即上下文压缩触发以总结较早消息的 point。这有助于您和 agent 了解对话何时变长。

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

在 CLI 中，上下文压力作为工具输出提要中的进度条出现：

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

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

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

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

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

凭证池策略

当您有多个相同 provider 的 API 密钥或 OAuth 令牌时，配置轮换策略：

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 的内置身份验证和 base URL。

辅助任务可用的 provider：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、kimi-coding-cn、arcee、minimax、任何在 provider 注册表中注册的 provider，或您 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 调用超时；vision payload 需要慷慨的超时
    download_timeout: 30       # 秒 — 图像 HTTP 下载；对慢速连接增加

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

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

  # 上下文压缩超时（独立于 compression.* 配置）
  compression:
    timeout: 120               # 秒 — 压缩总结长对话，需要更多时间

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

  # Skills hub — 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 设置 — 请参阅上面的 Context Compression。回退模型使用 fallback_model: 块 — 请参阅 Fallback Model。所有三个都遵循相同的 provider/model/base_url 模式。

更改 Vision 模型

要使用 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 账户）。支持 vision（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 密钥进行 vision：

# 在 ~/.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 进行 vision（路由到任何模型）：

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 令牌
    # model 默认为 gpt-5.3-codex（支持 vision）

使用本地/自托管模型：

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

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

提示

如果您将 Codex OAuth 作为主要模型 provider，vision 会自动工作 — 无需额外配置。Codex 包含在 vision 的自动检测链中。

注意

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

环境变量（旧）

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

设置	环境变量
Vision provider	`AUXILIARY_VISION_PROVIDER`
Vision model	`AUXILIARY_VISION_MODEL`
Vision endpoint	`AUXILIARY_VISION_BASE_URL`
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`
Web extract API key	`AUXILIARY_WEB_EXTRACT_API_KEY`

压缩和回退模型设置仅在 config.yaml 中。

提示

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

推理努力

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

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

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

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

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

工具使用强制

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

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

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

它注入什么

启用时，可能会向系统提示添加三层指导：

通用工具使用强制（所有匹配的模型）— 指示模型立即进行工具调用而不是描述意图，持续工作直到任务完成，并且永远不要以承诺未来操作的 turn 结束。
OpenAI 执行纪律（仅 GPT 和 Codex 模型）— 解决 GPT 特定失败模式的额外指导：在部分结果上放弃工作、跳过先决条件查找、而不是使用工具进行 hallucinate，以及在未验证的情况下声明"完成"。
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" | "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 端点的覆盖
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

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

速度回退层次： provider 特定速度（例如 tts.edge.speed）→ 全局 tts.speed → 1.0 默认值。设置全局 tts.speed 以对所有 provider 应用统一速度，或按 provider 覆盖以进行细粒度控制。

显示设置

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # 在消息 gateway 中启用 /verbose 斜杠命令
  tool_progress_overrides: {}  # 每个平台的覆盖（见下文）
  interim_assistant_messages: true  # Gateway：将自然的轮次中助手更新作为单独消息发送
  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 仅适用于 gateway。启用时，Hermes 将完成的轮次中助手更新作为单独的聊天消息发送。这独立于 tool_progress，不需要 gateway 流式传输。

隐私

privacy:
  redact_pii: false  # 从 LLM 上下文中剥离 PII（仅限 gateway）

当 redact_pii 为 true 时，gateway 在将系统提示发送到受支持平台上的 LLM 之前从中编辑个人身份信息：

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

平台支持： PII 编辑适用于 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 切换语音回复。请参阅 Voice Mode 了解端到端设置和平台特定行为。

流式传输

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

CLI 流式传输

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

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

Gateway 流式传输（Telegram、Discord、Slack）

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

启用后，机器人在第一个 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 仍按聊天/DM ID 对 DMs 进行键控。
线程无论如何都与父频道隔离；使用 true，每个参与者在线程内也有自己的会话。

有关行为详细信息和示例，请参阅 Sessions 和 Discord 指南。

未授权 DM 行为

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair 是默认设置。Hermes 拒绝访问，但在 DMs 中回复一次性配对码。
ignore 静默丢弃未授权的 DMs。
平台部分覆盖全局默认值，因此您可以在保持一个平台安静的同时在另一个平台上启用配对。

快速命令

定义在调用 LLM 时立即运行 shell 命令的自定义命令 — 零 token 使用，即时执行。特别适用于消息平台（Telegram、Discord 等）上的快速服务器检查或实用脚本。

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

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

30 秒超时 — 运行时间过长的命令会被终止并显示错误消息
优先级 — 快速命令在 skill 命令之前检查，因此您可以覆盖 skill 名称
自动补全 — 快速命令在调度时解析，不显示在内置斜杠命令自动补全表中
随处可用 — CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

人类延迟

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

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

代码执行

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

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

Web 搜索后端

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 会话在重启之间保持 cookies/登录状态

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

时区

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

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

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

Discord

为消息 gateway 配置 Discord 特定行为：

discord:
  require_mention: true          # 在服务器频道中需要 @mention 才能回复
  free_response_channels: ""     # 无需 @mention 即可回复的逗号分隔频道 ID
  auto_thread: true              # 在频道中 @mention 时自动创建线程

require_mention — 当为 true（默认）时，机器人在被 @mention 时才在服务器频道中回复。DMs 始终无需 mention 即可工作。
free_response_channels — 逗号分隔的频道 ID 列表，机器人在其中无需要求 mention 即可回复每条消息。
auto_thread — 当为 true（默认）时，频道中的 mention 会自动为对话创建线程，保持频道整洁（类似于 Slack 线程）。

安全

预执行安全扫描和密钥编辑：

security:
  redact_secrets: true           # 在工具输出和日志中编辑 API 密钥模式
  tirith_enabled: true           # 启用 Tirith 安全扫描终端命令
  tirith_path: "tirith"          # tirith 二进制文件的路径（默认：在 $PATH 中）
  tirith_timeout: 5              # tirith 扫描超时前的秒数
  tirith_fail_open: true         # 如果 tirith 不可用则允许命令执行
  website_blocklist:             # 见下面的网站黑名单部分
    enabled: false
    domains: []
    shared_files: []

redact_secrets — 在工具输出进入对话上下文和日志之前，自动检测并编辑看起来像 API 密钥、令牌和密码的模式。
tirith_enabled — 当为 true 时，终端命令在执行前由 Tirith 扫描，以检测潜在的危险操作。
tirith_path — tirith 二进制文件的路径。如果 tirith 安装在非标准位置，请设置此项。
tirith_timeout — tirith 扫描的最长等待秒数。命令在扫描超时时继续执行。
tirith_fail_open — 当为 true（默认）时，如果 tirith 不可用或失败，命令被允许执行。设置为 false 以在 tirith 无法验证时阻止命令。

网站黑名单

阻止特定域被 agent 的 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 中，显示交互式批准对话框。在消息中，队列 pending 批准请求。
`smart`	使用辅助 LLM 评估标记命令是否真正危险。低风险命令（例如 `python -c "print('hello')"`）被自动批准。真正危险的命令被自动拒绝。不确定的情况升级到手动提示。
`off`	跳过所有批准检查。等同于使用 `--yolo` 运行。谨慎使用。

智能模式对于减少批准疲劳特别有用 — 它让 agent 在安全操作上更自主地工作，同时仍能捕获真正危险的命令。

注意

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

检查点

在破坏性文件操作之前进行自动文件系统快照。请参阅 Checkpoints & Rollback 了解详细信息。

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

委托

为 delegate 工具配置 subagent 行为：

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）

Subagent provider:model 覆盖： 默认情况下，subagent 继承父 agent 的 provider 和模型。设置 delegation.provider 和 delegation.model 以将 subagent 路由到不同的 provider:model 对 — 例如，使用廉价/快速模型处理狭窄范围的子任务，而您的主要 agent 运行昂贵的推理模型。

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

委托 provider 使用与 CLI/gateway 启动相同的凭证解析。支持所有配置的 provider：openrouter、nous、copilot、zai、kimi-coding、minimax。设置 provider 后，系统会自动解析正确的 base 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 是谁（系统提示中的 slot #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 的主要身份。它占据系统提示中的 slot #1，完全替换内置默认身份。编辑它以完全自定义 agent 的身份。
如果 SOUL.md 缺失、为空或无法加载，Hermes 回退到内置默认身份。
项目上下文文件使用优先级系统 — 仅加载一种类型（第一个匹配）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
AGENTS.md 是分层的：如果子目录也有 AGENTS.md，则所有都被合并。
如果 SOUL.md 不存在，Hermes 会自动生成一个默认的 SOUL.md。
所有加载的上下文文件上限为 20,000 个字符，并进行智能截断。

另请参阅：

工作目录

上下文	默认值
CLI（`hermes`）	运行命令的当前目录
消息 gateway	主目录 `~`（使用 `MESSAGING_CWD` 覆盖）
Docker / Singularity / Modal / SSH	容器内或远程机器内的用户主目录

覆盖工作目录：

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

目录结构​

管理配置​

配置优先级​

环境变量替换​

终端后端配置​

后端概览​

Local 后端​

Docker 后端​

SSH 后端​

Modal 后端​

Daytona 后端​

Singularity/Apptainer 后端​

常见终端后端问题​

Docker 卷挂载​

Docker 凭证转发​

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

持久 Shell​

Skill 设置​

内存配置​

文件读取安全​

Git Worktree 隔离​

上下文压缩​

完整参考​

常见设置​

三个旋钮如何交互​

上下文引擎​

迭代预算压力​

流式超时​

上下文压力警告​

凭证池策略​

辅助模型​

通用配置模式​

完整辅助配置参考​

更改 Vision 模型​

Provider 选项​

常见设置​

环境变量（旧）​

推理努力​

工具使用强制​

它注入什么​

何时开启​

TTS 配置​

显示设置​

每个平台的进度覆盖​

隐私​

语音转文本（STT）​

语音模式（CLI）​

流式传输​

CLI 流式传输​

Gateway 流式传输（Telegram、Discord、Slack）​

群聊会话隔离​

未授权 DM 行为​

快速命令​

人类延迟​

代码执行​

Web 搜索后端​

浏览器​

时区​

Discord​

安全​

网站黑名单​

智能批准​

检查点​

委托​

澄清​

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

工作目录​

目录结构

管理配置

配置优先级

环境变量替换

终端后端配置

后端概览

Local 后端

Docker 后端

SSH 后端

Modal 后端

Daytona 后端

Singularity/Apptainer 后端

常见终端后端问题

Docker 卷挂载

Docker 凭证转发

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

持久 Shell

Skill 设置

内存配置

文件读取安全

Git Worktree 隔离

上下文压缩

完整参考

常见设置

三个旋钮如何交互

上下文引擎

迭代预算压力

流式超时

上下文压力警告

凭证池策略

辅助模型

通用配置模式

完整辅助配置参考

更改 Vision 模型

Provider 选项

常见设置

环境变量（旧）

推理努力

工具使用强制

它注入什么

何时开启

TTS 配置

显示设置

每个平台的进度覆盖

隐私

语音转文本（STT）

语音模式（CLI）

流式传输

CLI 流式传输

Gateway 流式传输（Telegram、Discord、Slack）

群聊会话隔离

未授权 DM 行为

快速命令

人类延迟

代码执行

Web 搜索后端

浏览器

时区

Discord

安全

网站黑名单

智能批准

检查点

委托

澄清

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

工作目录