配置

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

目录结构

text

~/.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 — 自动脱敏机密信息）

管理配置

bash

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

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

提示

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

配置优先级

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

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

经验法则

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

环境变量替换

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

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 提供商设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、备用模型等），请参阅 AI 提供商。

终端后端配置

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

yaml

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 集群、共享机器

本地后端

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

yaml

terminal:
  backend: local

警告

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

Docker 后端

在安全加固的 Docker 容器中运行命令（所有功能已删除，无特权提升，PID 限制）。

yaml

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）。命令通过登录 shell 使用 docker exec 运行。清理时，容器会被停止并删除。

安全加固：

--cap-drop ALL，仅重新添加 DAC_OVERRIDE、CHOWN、FOWNER
--security-opt no-new-privileges
--pids-limit 256
大小受限的 tmpfs 用于 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）

凭证转发： docker_forward_env 中列出的环境变量首先会从您的 shell 环境中解析，然后是 ~/.hermes/.env。技能还可以声明 required_environment_variables，它们会自动合并。

SSH 后端

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

yaml

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

必需的环境变量：

bash

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。文件系统可以在会话之间进行快照/恢复。

yaml

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 托管工作区中运行命令。支持停止/恢复以实现持久化。

yaml

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 集群和共享机器设计。

yaml

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

yaml

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

这适用于：

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

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

Docker 凭证转发

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

yaml

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

Hermes 首先会从您当前的 shell 解析每个列出的变量，如果它是用 hermes config set 保存的，则回退到 ~/.hermes/.env。

警告

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

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

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

在 config.yaml 中启用它：

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 启用，为本地后端禁用。

yaml

terminal:
  persistent_shell: true   # 默认值 — 为 SSH 启用持久 shell

要禁用：

bash

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：

bash

export TERMINAL_LOCAL_PERSISTENT=true

NOTE

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

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

技能设置

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

yaml

skills:
  config:
    wiki:
      path: ~/wiki          # 由 llm-wiki 技能使用

技能设置的工作原理：

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

手动设置值：

bash

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

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

记忆配置

yaml

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 令牌
  user_char_limit: 1375     # ~500 令牌

文件读取安全

控制单个 read_file 调用可以返回多少内容。超过限制的读取会被拒绝，并显示错误，告诉代理使用 offset 和 limit 获取更小的范围。这可以防止单个读取最小化的 JS 包或大文件数据淹没上下文窗口。

yaml

file_read_max_chars: 100000  # 默认值 — ~25-35K 令牌

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

yaml

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

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

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

Git 工作树隔离

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

yaml

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

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

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

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩

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

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

完整参考

yaml

compression:
  enabled: true                                     # 切换压缩开/关
  threshold: 0.50                                   # 在此上下文限制百分比时压缩
  target_ratio: 0.20                                # 保留为最近尾部的阈值比例
  protect_last_n: 20                                # 保持未压缩的最近消息最小数量
  summary_model: "google/gemini-3-flash-preview"    # 用于摘要的模型
  summary_provider: "auto"                          # 提供商："auto"、"openrouter"、"nous"、"codex"、"main" 等
  summary_base_url: null                            # 自定义 OpenAI 兼容端点（覆盖提供商）

常见设置

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

yaml

compression:
  enabled: true
  threshold: 0.50

使用 Gemini Flash 的第一个可用提供商（OpenRouter → Nous → Codex）。

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

yaml

compression:
  summary_provider: nous
  summary_model: gemini-3-flash

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

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

yaml

compression:
  summary_model: glm-4.7
  summary_base_url: https://api.z.ai/api/coding/paas/v4

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

三个旋钮如何交互

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

摘要模型上下文长度要求

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

上下文引擎

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

yaml

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

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

yaml

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

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

有关内存插件的类似单选系统，请参阅内存提供商。

迭代预算压力

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

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

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

yaml

agent:
  max_turns: 90                # 每次对话轮次的最大迭代次数（默认值：90）

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

流超时

LLM 流连接有两个超时层。两者都会为本地提供商（localhost、LAN IP）自动调整 — 大多数设置不需要配置。

超时	默认值	本地提供商	环境变量
套接字读取超时	120s	自动提高到 1800s	`HERMES_STREAM_READ_TIMEOUT`
流停滞检测	180s	自动禁用	`HERMES_STREAM_STALE_TIMEOUT`
API 调用（非流）	1800s	不变	`HERMES_API_TIMEOUT`

套接字读取超时控制 httpx 等待提供商下一个数据块的时间。本地 LLM 在生成第一个令牌之前可能需要几分钟进行大型上下文的预填充，因此 Hermes 在检测到本地端点时会将其提高到 30 分钟。如果您显式设置 HERMES_STREAM_READ_TIMEOUT，无论端点检测如何，都会使用该值。

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

上下文压力警告

与迭代预算压力分开，上下文压力跟踪对话接近 压缩阈值 的程度 — 即触发上下文压缩以对旧消息进行摘要的点。这有助于您和代理了解对话何时变长。

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

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

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

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

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

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

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

凭证池策略

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

yaml

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

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

辅助模型

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

通用配置模式

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

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

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

辅助任务的可用提供商：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、minimax、提供商注册表中注册的任何提供商，或来自您的 custom_providers 列表的任何命名自定义提供商（例如 provider: "beans"）。

"main" 仅用于辅助任务

"main" 提供商选项表示"使用我的主代理使用的任何提供商" — 仅在 auxiliary:、compression: 和 fallback_model: 配置中有效。它不是顶级 model.provider 设置的有效值。如果您使用自定义 OpenAI 兼容端点，请在 model: 部分设置 provider: custom。有关所有主模型提供商选项，请参阅 AI 提供商。

完整辅助配置参考

yaml

auxiliary:
  # 图像分析（vision_analyze 工具 + 浏览器屏幕截图）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI 兼容端点（覆盖提供商）
    api_key: ""                # base_url 的 API 密钥（回退到 OPENAI_API_KEY）
    timeout: 30                # 秒 — 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

  # 技能中心 — 技能匹配和搜索
  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 30s、web_extract 360s、approval 30s、compression 120s。如果您对辅助任务使用慢速本地模型，请提高这些值。Vision 还有单独的 download_timeout（默认 30s）用于 HTTP 图像下载 — 对于慢速连接或自托管图像服务器请提高。

信息

上下文压缩有自己的顶级 compression: 块，包含 summary_provider、summary_model 和 summary_base_url — 请参阅上面的上下文压缩。备用模型使用 fallback_model: 块 — 请参阅备用模型。这三个都遵循相同的 provider/model/base_url 模式。

更改视觉模型

要使用 GPT-4o 而不是 Gemini Flash 进行图像分析：

yaml

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

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

bash

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供商选项

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

提供商	描述	要求
`"auto"`	最佳可用（默认）。Vision 尝试 OpenRouter → Nous → Codex。	—
`"openrouter"`	强制 OpenRouter — 路由到任何模型（Gemini、GPT-4o、Claude 等）	`OPENROUTER_API_KEY`
`"nous"`	强制 Nous Portal	`hermes auth`
`"codex"`	强制 Codex OAuth（ChatGPT 帐户）。支持视觉（gpt-5.3-codex）。	`hermes model` → Codex
`"main"`	使用您活动的自定义/主端点。这可以来自 `OPENAI_BASE_URL` + `OPENAI_API_KEY` 或通过 `hermes model` / `config.yaml` 保存的自定义端点。适用于 OpenAI、本地模型或任何 OpenAI 兼容 API。仅辅助任务 — 对 `model.provider` 无效。	自定义端点凭证 + 基本 URL

常见设置

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

yaml

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 密钥进行视觉：

yaml

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

yaml

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

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

yaml

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

使用本地/自托管模型：

yaml

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

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

提示

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

警告

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

环境变量（旧版）

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

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

压缩和备用模型设置仅限 config.yaml。

提示

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

推理力度

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

yaml

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

未设置时（默认值），推理力度默认为"medium" — 适用于大多数任务的平衡级别。设置值会覆盖它 — 更高的推理力度在复杂任务上产生更好的结果，但会消耗更多的令牌和延迟。

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

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

工具使用强制执行

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

yaml

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 或将模型子字符串添加到列表：

yaml

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

TTS 配置

yaml

tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 种声音，74 种语言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy、echo、fable、onyx、nova、shimmer
    base_url: "https://api.openai.com/v1"  # 覆盖 OpenAI 兼容 TTS 端点
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

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

显示设置

yaml

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 # 代理完成时播放终端铃声（适用于长时间任务）
  show_reasoning: false   # 在每个响应上方显示模型推理/思考（用 /reasoning show|hide 切换）
  streaming: false        # 将令牌流式传输到终端（实时输出）
  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 设置每个平台的模式：

yaml

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。

interim_assistant_messages 仅限网关。启用后，Hermes 将完成的中间回合助手更新作为单独的聊天消息发送。这与 tool_progress 无关，不需要网关流。

隐私

yaml

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

当 redact_pii 为 true 时，网关在支持的平台上将个人身份信息从系统提示中删除后再发送到 LLM：

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

平台支持： 修订适用于 WhatsApp、Signal 和 Telegram。Discord 和 Slack 被排除，因为它们的提及系统（<@user_id>）需要 LLM 上下文中的真实 ID。

哈希是确定性的 — 同一用户始终映射到相同的哈希，因此模型仍然可以区分群聊中的用户。路由和交付在内部使用原始值。

语音转文本 (STT)

yaml

stt:
  provider: "local"            # "local" | "groq" | "openai"
  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 模型覆盖是环境驱动的：

bash

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)

yaml

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 切换语音回复。有关端到端设置和平台特定行为，请参阅语音模式。

流式传输

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

CLI 流式传输

yaml

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

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

网关流式传输 (Telegram、Discord、Slack)

yaml

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

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

对于没有渐进令牌编辑的单独自然中间回合助手更新，请设置 display.interim_assistant_messages: true。

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

NOTE

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

群聊会话隔离

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

yaml

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

true 是默认和推荐设置。在 Discord 频道、Telegram 群组、Slack 频道和类似的共享上下文中，每个发送者在平台提供用户 ID 时获得自己的会话。
false 恢复旧的共享房间行为。如果您明确希望 Hermes 将频道视为一个协作对话，这很有用，但它也意味着用户共享上下文、令牌成本和中断状态。
直接消息不受影响。Hermes 仍然像往常一样按键/DM ID 对 DM 进行键控。
线程无论如何都与父频道隔离；使用 true，每个参与者在线程内也获得自己的会话。

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

未经授权的 DM 行为

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

yaml

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

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

快速命令

定义运行 shell 命令的自定义命令而无需调用 LLM — 零令牌使用，即时执行。特别适用于从消息平台（Telegram、Discord 等）进行快速服务器检查或实用程序脚本。

yaml

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 调用，无令牌消耗。

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

人类延迟

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

yaml

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

代码执行

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

yaml

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

网页搜索后端

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

yaml

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

浏览器

配置浏览器自动化行为：

yaml

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

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

时区

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

yaml

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

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

Discord

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

yaml

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

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

安全

执行前安全扫描和机密修订：

yaml

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 密钥、令牌和密码的模式。
tirith_enabled — 为 true 时，终端命令在执行前由 Tirith 扫描以检测潜在危险操作。
tirith_path — tirith 二进制文件的路径。如果 tirith 安装在非标准位置，请设置此项。
tirith_timeout — 等待 tirith 扫描的最大秒数。如果扫描超时，命令会继续。
tirith_fail_open — 为 true（默认）时，如果 tirith 不可用或失败，允许命令执行。设置为 false 以在 tirith 无法验证它们时阻止命令。

网站阻止列表

阻止特定域被代理的网页和浏览器工具访问：

yaml

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

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

域规则支持：

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

共享文件每行包含一个域规则（忽略空行和 # 注释）。缺失或不可读的文件会记录警告，但不会禁用其他网页工具。

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

智能批准

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

yaml

approvals:
  mode: manual   # manual | smart | off

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

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

警告

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

检查点

破坏性文件操作前的自动文件系统快照。有关详细信息，请参阅检查点和回滚。

yaml

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

委托

为委托工具配置子代理行为：

yaml

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

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

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

委托提供商使用与 CLI/网关启动相同的凭证解析。支持所有配置的提供商：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。设置提供商后，系统会自动解析正确的基本 URL、API 密钥和 API 模式 — 无需手动凭证布线。

优先级： 配置中的 delegation.base_url → 配置中的 delegation.provider → 父提供商（继承）。配置中的 delegation.model → 父模型（继承）。仅设置 model 而不设置 provider 仅更改模型名称，同时保留父级的凭证（对于在同一提供商内切换模型很有用，如 OpenRouter）。

澄清

配置澄清提示行为：

yaml

clarify:
  timeout: 120                 # 等待用户澄清响应的秒数

上下文文件 (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，它们都会合并。
Hermes 会自动播种默认的 SOUL.md（如果不存在）。
所有加载的上下文文件上限为 20,000 字符，带有智能截断。

另请参阅：

工作目录

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

覆盖工作目录：

bash

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

配置 ​

目录结构 ​

管理配置 ​

配置优先级 ​

环境变量替换 ​

终端后端配置 ​

后端概览 ​

本地后端 ​

Docker 后端 ​

SSH 后端 ​

Modal 后端 ​

Daytona 后端 ​

Singularity/Apptainer 后端 ​

常见终端后端问题 ​

Docker 卷挂载 ​

Docker 凭证转发 ​

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

持久 Shell ​

技能设置 ​

记忆配置 ​

文件读取安全 ​

Git 工作树隔离 ​

上下文压缩 ​

完整参考 ​

常见设置 ​

三个旋钮如何交互 ​

上下文引擎 ​

迭代预算压力 ​

流超时 ​

上下文压力警告 ​

凭证池策略 ​

辅助模型 ​

通用配置模式 ​

完整辅助配置参考 ​

更改视觉模型 ​

提供商选项 ​

常见设置 ​

环境变量（旧版） ​

推理力度 ​

工具使用强制执行 ​

它注入的内容 ​

何时启用它 ​

TTS 配置 ​

显示设置 ​

每个平台的进度覆盖 ​

隐私 ​

语音转文本 (STT) ​

语音模式 (CLI) ​

流式传输 ​

CLI 流式传输 ​

网关流式传输 (Telegram、Discord、Slack) ​

群聊会话隔离 ​

未经授权的 DM 行为 ​

快速命令 ​

人类延迟 ​

代码执行 ​

网页搜索后端 ​

浏览器 ​

时区 ​

Discord ​

安全 ​

网站阻止列表 ​

智能批准 ​

检查点 ​

委托 ​

澄清 ​

上下文文件 (SOUL.md, AGENTS.md) ​

工作目录 ​

配置

目录结构

管理配置

配置优先级

环境变量替换

终端后端配置

后端概览

本地后端

Docker 后端

SSH 后端

Modal 后端

Daytona 后端

Singularity/Apptainer 后端

常见终端后端问题

Docker 卷挂载

Docker 凭证转发

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

持久 Shell

技能设置

记忆配置

文件读取安全

Git 工作树隔离

上下文压缩

完整参考

常见设置

三个旋钮如何交互

上下文引擎

迭代预算压力

流超时

上下文压力警告

凭证池策略

辅助模型

通用配置模式

完整辅助配置参考

更改视觉模型

提供商选项

常见设置

环境变量（旧版）

推理力度

工具使用强制执行

它注入的内容

何时启用它

TTS 配置

显示设置

每个平台的进度覆盖

隐私

语音转文本 (STT)

语音模式 (CLI)

流式传输

CLI 流式传输

网关流式传输 (Telegram、Discord、Slack)

群聊会话隔离

未经授权的 DM 行为

快速命令

人类延迟

代码执行

网页搜索后端

浏览器

时区

Discord

安全

网站阻止列表

智能批准

检查点

委托

澄清

上下文文件 (SOUL.md, AGENTS.md)

工作目录