配置

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

目录结构

~/.hermes/
├── config.yaml     # 设置（model、terminal、TTS、compression 等）
├── .env            # API keys 和 secrets
├── auth.json       # OAuth provider 凭证（Nous Portal 等）
├── SOUL.md         # 主代理身份（system prompt 中的 slot #1）
├── memories/       # 持久记忆（MEMORY.md、USER.md）
├── skills/         # 由 agent 创建的 skills（通过 skill_manage tool 管理）
├── cron/           # 定时任务
├── sessions/       # Gateway sessions
└── logs/           # 日志（errors.log、gateway.log —— secrets 会自动脱敏）

管理配置

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

配置优先级

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

1. CLI arguments —— 例如 hermes chat --model anthropic/claude-sonnet-4（单次调用覆盖）
2. ~/.hermes/config.yaml —— 所有非敏感设置的主配置文件
3. ~/.hermes/.env —— env vars 的后备来源；对于 secrets（API keys、tokens、passwords）则是必需
4. 内置默认值 —— 在未设置任何值时使用的硬编码安全默认值

:::info 经验法则 Secrets（API keys、bot tokens、passwords）放在 .env 中。其他所有内容（model、terminal backend、compression settings、memory limits、toolsets）放在 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、自定义 endpoints、自托管 LLMs、fallback models 等），请参阅 AI Providers。

Terminal Backend 配置

Hermes 支持六种 terminal backends。它们决定了 agent 的 shell commands 实际在哪里执行——你的本地机器、Docker container、通过 SSH 连接的远程服务器、Modal cloud sandbox、Daytona workspace，或 Singularity / Apptainer container。

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

对于 Modal 和 Daytona 这类 cloud sandboxes，container_persistent: true 表示 Hermes 会尝试在重建 sandbox 后保留文件系统状态。但这并不保证之后仍然是同一个 live sandbox、PID 空间或后台进程。

Backend 概览

Local Backend

默认选项。命令直接在你的机器上运行，没有隔离。无需额外设置。

terminal:
  backend: local

Docker Backend

在 Docker container 中运行命令，并带有安全加固（移除所有 capabilities、禁止 privilege escalation、限制 PID 数）。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # 将启动目录挂载到 /workspace
  docker_forward_env:              # 转发到容器中的 env vars
    - "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（需要 overlay2 on XFS+pquota）
  container_persistent: true       # 在会话间保留 /workspace 和 /root

要求： 已安装并运行 Docker Desktop 或 Docker Engine。Hermes 会在 $PATH 以及常见的 macOS 安装位置中探测 Docker（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop app bundle）。

Container 生命周期： 每个 session 会启动一个长生命周期 container（docker run -d ... sleep 2h）。命令通过带 login shell 的 docker exec 执行。清理时，container 会被停止并移除。

安全加固：

• --cap-drop ALL，仅恢复 DAC_OVERRIDE、CHOWN、FOWNER
• --security-opt no-new-privileges
• --pids-limit 256
• 为 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）设置限额 tmpfs

凭证转发： docker_forward_env 中列出的 env vars 会优先从当前 shell 环境解析，其次从 ~/.hermes/.env 获取。Skills 也可声明 required_environment_variables，系统会自动合并。

SSH Backend

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 复用连接（空闲 5 分钟 keepalive）。默认启用 persistent shell——状态（cwd、env vars）会在命令之间保留。

terminal:
  backend: ssh
  persistent_shell: true           # 保持长生命周期 bash session（默认：true）

必需的环境变量：

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

可选项：

工作方式： 初始化时使用 BatchMode=yes 和 StrictHostKeyChecking=accept-new 建立连接。Persistent shell 会在远程主机上保持一个单独的 bash -l 进程，并通过临时文件通信。需要 stdin_data 或 sudo 的命令会自动退回到 one-shot 模式。

Modal Backend

在 Modal cloud sandbox 中运行命令。每个任务会得到一个隔离的 VM，CPU、memory 和 disk 都可配置。文件系统可以在 sessions 间 snapshot / restore。

terminal:
  backend: modal
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # MB（5GB）
  container_disk: 51200            # MB（50GB）
  container_persistent: true       # Snapshot / restore 文件系统

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

持久化： 启用后，sandbox 文件系统会在清理时做 snapshot，并在下次 session 恢复。Snapshots 记录在 ~/.hermes/modal_snapshots.json 中。这会保留文件系统状态，但不会保留 live processes、PID 空间或后台任务。

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

Daytona Backend

在 Daytona 托管的 workspace 中运行命令。支持 stop / resume 以实现持久化。

terminal:
  backend: daytona
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # MB → 转换为 GiB
  container_disk: 10240            # MB → 转换为 GiB（最大 10 GiB）
  container_persistent: true       # stop / resume，而不是 delete

必需： 环境变量 DAYTONA_API_KEY。

持久化： 启用后，sandboxes 在清理时会被停止而不是删除，并在下一次 session 中恢复。Sandbox 名称遵循 hermes-{task_id} 格式。

磁盘限制： Daytona 最大只允许 10 GiB。超过该值的请求会被截断并给出 warning。

Singularity / Apptainer Backend

在 Singularity / Apptainer container 中运行命令。适用于 Docker 不可用的 HPC clusters 和共享机器。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU 核数
  container_memory: 5120           # MB
  container_persistent: true       # 可写 overlay 在 sessions 间持久保存

要求： $PATH 中存在 apptainer 或 singularity binary。

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

Scratch 目录： 解析顺序为：TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent（HPC 常见约定）→ ~/.hermes/sandboxes/singularity。

隔离性： 使用 --containall --no-home，实现完整 namespace 隔离，并且不挂载宿主机 home 目录。

常见 Terminal Backend 问题

如果 terminal commands 一开始就失败，或者 terminal tool 被报告为 disabled：

• 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 会处理 server URL 配置。
• Singularity —— 需要 $PATH 中有 apptainer 或 singularity。在 HPC clusters 上较常见。

如果不确定，请先把 terminal.backend 设回 local，确认命令能在该模式下正常执行。

Docker Volume 挂载

使用 Docker backend 时，docker_volumes 可让你把宿主机目录共享给 container。每个条目使用标准 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 提供文件（datasets、configs、参考代码）
• 接收 agent 生成的文件（代码、报告、导出结果）
• 共享工作区，使你和 agent 都能访问同一批文件

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

Docker 凭证转发

默认情况下，Docker terminal sessions 不会继承任意宿主机凭证。如果你需要在 container 中使用特定 token，请把它加入 terminal.docker_forward_env。

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

Hermes 会优先从当前 shell 中解析这些变量，其次从 ~/.hermes/.env 获取它们（如果它们是通过 hermes config set 保存的）。

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

Docker sandboxes 默认保持隔离。除非你显式启用，否则 Hermes 不会把当前宿主机工作目录传入 container。

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用后：

• 如果你从 ~/projects/my-app 启动 Hermes，该宿主机目录会被 bind mount 到 /workspace
• Docker backend 会从 /workspace 启动
• file tools 和 terminal commands 都会看到同一个挂载项目

禁用时，/workspace 仍归 sandbox 所有，除非你通过 docker_volumes 显式挂载内容。

安全上的权衡：

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

只有在你明确希望 container 操作宿主机实时文件时，才应启用该选项。

Persistent Shell

默认情况下，每条 terminal command 都在各自独立的 subprocess 中运行——工作目录、环境变量和 shell 变量在命令之间都会重置。当启用 persistent shell 时，会在多次 execute() 调用之间保留一个长生命周期 bash 进程，从而让状态在命令之间持续存在。

这对 SSH backend 特别有用，因为还能消除每条命令都重新建立连接的开销。Persistent shell 在 SSH 中默认启用，在 local backend 中默认关闭。

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

关闭方法：

hermes config set terminal.persistent_shell false

可持久化的状态包括：

• 工作目录（例如 cd /tmp 会对下一条命令生效）
• 导出的环境变量（export FOO=bar）
• Shell 变量（MY_VAR=hello）

优先级：

各 backend 的环境变量拥有最高优先级。如果你也想在 local backend 中启用 persistent shell：

export TERMINAL_LOCAL_PERSISTENT=true

详情请参阅 Code Execution 和 README 中的 Terminal 部分。

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 Settings” 中显示所有 skill 设置及其所属 skill
• 当某个 skill 加载时，解析后的配置值会自动注入 skill context

手动设置值：

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

关于如何在你自己的 skills 中声明配置项，请参阅 Creating Skills — Config Settings。

Memory 配置

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 bundle 或大型数据文件时把 context window 挤满。

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

如果你使用的是大 context window 的 model，并且经常读取大文件，可以调高：

# 大 context model（200K+）
file_read_max_chars: 200000
# 小型本地 model（16K context）
file_read_max_chars: 30000

agent 还会自动去重文件读取——如果同一文件区域被读了两次，且文件未发生变化，则返回轻量级 stub，而不是重复发送内容。在 context compression 之后，这个状态会被重置，以便 agent 在内容被摘要压缩后重新读取文件。

Git Worktree 隔离

启用隔离的 git worktrees，以便多个 agents 在同一个 repo 上并行运行：

worktree: true    # 始终创建 worktree（等同于 hermes -w）
# worktree: false # 默认 —— 仅在传入 -w 参数时启用

启用后，每个 CLI session 都会在 .worktrees/ 下创建一个新的 worktree 和独立 branch。Agents 可以编辑文件、提交、push、创建 PR，而互不干扰。干净的 worktrees 会在退出时移除；有改动的 worktrees 会保留，以便人工恢复。

你也可以在 repo 根目录中通过 .worktreeinclude 列出需要复制到 worktrees 的 gitignored 文件：

# .worktreeinclude
.env
.venv/
node_modules/

Context Compression

Hermes 会自动压缩长对话，以保持在 model 的 context window 内。压缩摘要器会发起一个独立的 LLM 调用——你可以将其指向任意 provider 或 endpoint。

所有 compression 设置都位于 config.yaml 中（不使用环境变量）。

完整参考

compression:
  enabled: true                                     # 开关压缩
  threshold: 0.50                                   # 达到 context limit 这个比例时触发压缩
  target_ratio: 0.20                                # 作为最近上下文尾部保留的比例
  protect_last_n: 20                                # 至少保留最近多少条消息不压缩
  summary_model: "google/gemini-3-flash-preview"    # 用于摘要的 model
  summary_provider: "auto"                          # Provider: "auto"、"openrouter"、"nous"、"codex"、"main" 等
  summary_base_url: null                            # 自定义 OpenAI-compatible endpoint（覆盖 provider）

常见配置方式

默认（auto-detect）——无需配置：

compression:
  enabled: true
  threshold: 0.50

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

强制指定 provider（OAuth 或 API-key 模式）：

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

适用于任意 provider：nous、openrouter、codex、anthropic、main 等。

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

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

直接指向自定义 OpenAI-compatible endpoint。认证使用 OPENAI_API_KEY。

三个参数如何相互作用

summary_model 的 context length 至少要和你的主 model 一样大，因为它会接收对话中间的大段内容用于压缩。

Iteration Budget Pressure

当 agent 处理复杂任务并伴随大量 tool calls 时，可能会在没意识到的情况下耗尽 iteration budget（默认：90 turns）。Budget pressure 会在接近上限时自动提醒 model：

这些 warnings 会注入到最近一次 tool result 的 JSON 中（以 _budget_warning 字段形式），而不是作为独立消息——这样可以保留 prompt caching，并避免扰乱对话结构。

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

Budget pressure 默认启用。agent 会自然地在 tool results 中看到这些警告，从而倾向于整合工作，并在耗尽 iterations 之前给出响应。

Streaming Timeouts

LLM streaming connection 有两层 timeout。对于本地 providers（localhost、局域网 IP），二者都会自动调整——大多数情况下无需手动配置。

Socket read timeout 控制 httpx 最多等待 provider 返回下一个数据块多久。对于本地 LLM，在处理大上下文时，prefill 可能需要几分钟才会产生第一个 token，因此 Hermes 在检测到本地 endpoint 时，会把这个值提升到 30 分钟。如果你显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论 endpoint 检测结果如何，都会使用该值。

Stale stream detection 用来终止那些只收到 SSE keep-alive pings、但没有实际内容的连接。对于本地 providers，这一机制会被完全禁用，因为它们在 prefill 阶段通常不会发送 keep-alive pings。

Context Pressure Warnings

与 iteration budget pressure 不同，context pressure 跟踪的是当前对话距离 compaction threshold 还有多近——也就是触发 context compression、对旧消息进行摘要的那个点。这有助于你和 agent 理解对话是否已经变得很长。

在 CLI 中，context pressure 会显示为 tool output feed 中的进度条：

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

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

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

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

Context pressure 是自动机制——无需配置。它只作为面向用户的通知存在，不会修改消息流，也不会向 model 的 context 中注入任何内容。

Credential Pool 策略

当同一个 provider 存在多个 API keys 或 OAuth tokens 时，可以配置轮换策略：

credential_pool_strategies:
  openrouter: round_robin    # 均匀轮换 keys
  anthropic: least_used      # 始终选择使用次数最少的 key

可选项：fill_first（默认）、round_robin、least_used、random。完整说明请参阅 Credential Pools。

Auxiliary Models

Hermes 会为图像分析、网页摘要、浏览器截图分析等辅助任务使用轻量级 “auxiliary” models。默认情况下，它们通过自动检测使用 Gemini Flash —— 你无需手动配置。

通用配置模式

Hermes 中每一个 model slot——包括辅助任务、compression、fallback——都使用相同的三个参数：

当设置了 base_url 时，Hermes 会忽略 provider，直接调用该 endpoint（并使用 api_key 或 OPENAI_API_KEY 认证）。当只设置 provider 时，Hermes 会使用该 provider 自带的认证与 base URL。

辅助任务可用的 providers 包括：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、minimax、在 provider registry 中注册的任意 provider，以及你在 custom_providers 列表中命名的任意自定义 provider（例如 provider: "beans"）。

:::warning "main" 仅用于辅助任务 "main" provider 选项表示“使用我的主 agent 当前使用的 provider”——它只在 auxiliary:、compression: 和 fallback_model: 配置中有效。它不能作为顶层 model.provider 的合法值。如果你使用自定义 OpenAI-compatible endpoint，请在 model: 部分设置 provider: custom。关于主 model 可用的 provider 选项，请参阅 AI Providers。 :::

完整辅助配置参考

auxiliary:
  # 图像分析（vision_analyze tool + browser screenshots）
  vision:
    provider: "auto"           # "auto"、"openrouter"、"nous"、"codex"、"main" 等
    model: ""                  # 例如 "openai/gpt-4o"、"google/gemini-2.5-flash"
    base_url: ""               # 自定义 OpenAI-compatible endpoint（覆盖 provider）
    api_key: ""                # base_url 对应的 API key（回退到 OPENAI_API_KEY）
    timeout: 30                # 秒 —— LLM API 调用；慢速本地 vision models 可调高
    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                # 秒
  # Context compression timeout（独立于 compression.* 配置）
  compression:
    timeout: 120               # 秒 —— 长对话压缩需要更长时间
  # Session 搜索 —— 对历史 session 匹配做摘要
  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 tool dispatch
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
  # Memory flush —— 为持久记忆摘要对话
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

更改 Vision Model

如果你想在图像分析中使用 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 设置。

常见配置方式

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

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

base_url 的优先级高于 provider，因此这是将某个辅助任务明确路由到指定 endpoint 的最直接方式。对于直接 endpoint 覆盖，Hermes 使用配置中的 api_key，或回退到 OPENAI_API_KEY；它不会把 OPENROUTER_API_KEY 重用于该 custom endpoint。

使用 OpenAI API key 处理 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（可路由到任意 model）：

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

使用 Codex OAuth（ChatGPT Pro / Plus account —— 无需 API key）：

auxiliary:
  vision:
    provider: "codex"     # 使用你的 ChatGPT OAuth token
    # model 默认为 gpt-5.3-codex（支持 vision）

使用本地 / 自托管 model：

auxiliary:
  vision:
    provider: "main"      # 使用你当前激活的自定义 endpoint
    model: "my-local-model"

provider: "main" 会使用 Hermes 正常聊天时所使用的 provider——无论它是命名的 custom provider（例如 beans）、内置 provider（例如 openrouter），还是旧式 OPENAI_BASE_URL endpoint。

环境变量（legacy）

Auxiliary models 也可以通过环境变量配置。但更推荐使用 config.yaml——更易管理，而且支持包括 base_url 和 api_key 在内的全部选项。

Compression 和 fallback model 设置仅支持 config.yaml。

Reasoning Effort

控制 model 在响应前投入多少“思考”量：

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

未设置时（默认），reasoning effort 为 "medium"——这是一个适合大多数任务的平衡档位。显式设置后会覆盖默认值——更高的 reasoning effort 在复杂任务上通常效果更好，但会消耗更多 tokens，延迟也更高。

你也可以在运行时通过 /reasoning 命令修改：

/reasoning           # 显示当前 effort 等级和显示状态
/reasoning high      # 将 reasoning effort 设为 high
/reasoning none      # 关闭 reasoning
/reasoning show      # 在每次响应前显示 model thinking
/reasoning hide      # 隐藏 model thinking

Tool-Use Enforcement

某些 models（尤其是 GPT 系列）有时会用文字描述“它打算做什么”，而不是实际发起 tool calls。Tool-use enforcement 会注入提示，引导 model 真正去调用工具。

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

启用后，system prompt 中会加入提示，提醒 model 要实际发起 tool calls，而不是只描述自己会做什么。这对用户是透明的，而且对于本就可靠使用工具的 models 不会产生影响。

TTS 配置

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-compatible TTS endpoint
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

这既控制 text_to_speech tool，也控制 voice mode 下的语音回复（CLI 或 messaging gateway 中的 /voice tts）。

Display 设置

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # 在 messaging gateway 中启用 /verbose slash command
  tool_progress_overrides: {}  # 每个平台的覆盖设置（见下文）
  skin: default           # 内置或自定义 CLI skin（见 user-guide/features/skins）
  personality: "kawaii"  # 旧版外观字段，仍会在部分摘要中显示
  compact: false          # 紧凑输出模式（更少空白）
  resume_display: full    # full（恢复时显示历史消息）| minimal（只显示一行提示）
  bell_on_complete: false # agent 完成时播放终端提示音（适合长任务）
  show_reasoning: false   # 在每次响应前显示 model reasoning / thinking（可通过 /reasoning show|hide 切换）
  streaming: false        # 将 tokens 实时流式输出到终端
  show_cost: false        # 在 CLI 状态栏中显示预估美元成本
  tool_preview_length: 0  # tool call 预览最大字符数（0 = 不限制，显示完整路径 / 命令）

在 CLI 中，你可以通过 /verbose 在这些模式间切换。若想在 Telegram、Discord、Slack 等消息平台中使用 /verbose，请在上面的 display 部分中设置 tool_progress_command: true。之后该命令会循环切换模式，并保存到配置中。

每个平台的 progress 覆盖

不同平台对冗长程度的需求不同。例如，Signal 不能编辑消息，因此每次 progress 更新都会变成一条新消息，比较吵。你可以用 tool_progress_overrides 为不同平台设置不同模式：

display:
  tool_progress: all          # 全局默认值
  tool_progress_overrides:
    signal: 'off'             # Signal 上不显示 progress
    telegram: verbose         # Telegram 上显示详细 progress
    slack: 'off'              # 共享 Slack 工作区中保持安静

没有 override 的平台会回退到全局 tool_progress 值。有效的平台 key 包括：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、bluebubbles。

隐私

privacy:
  redact_pii: false  # 从 LLM context 中移除 PII（仅 gateway）

当 redact_pii 为 true 时，gateway 会在将 system prompt 发给 LLM 前，对受支持平台中的 personally identifiable information 进行脱敏：

平台支持： 脱敏适用于 WhatsApp、Signal 和 Telegram。Discord 和 Slack 不在此列，因为它们的 mention 系统（<@user_id>）要求在 LLM context 中保留真实 ID。

这些 hashes 是确定性的——同一个用户始终映射为相同的 hash，因此 model 在群聊中仍能区分不同用户。路由和消息投递在内部仍使用原始值。

Speech-to-Text（STT）

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"         # 旧版 fallback key 仍然兼容

Provider 行为：

• local 使用你本机运行的 faster-whisper。需单独安装：pip install faster-whisper。
• groq 使用 Groq 的 Whisper-compatible endpoint，并读取 GROQ_API_KEY。
• openai 使用 OpenAI speech API，并读取 VOICE_TOOLS_OPENAI_KEY。

如果请求的 provider 不可用，Hermes 会按以下顺序自动回退：local → groq → openai。

Groq 和 OpenAI 的 model overrides 通过环境变量控制：

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

Voice Mode（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。

Streaming

将 tokens 实时流式输出到终端或消息平台，而不是等待完整响应生成完毕。

CLI Streaming

display:
  streaming: true         # 在终端中实时流式显示 tokens
  show_reasoning: true    # 同时流式显示 reasoning / thinking tokens（可选）

启用后，响应会以 token-by-token 的方式出现在一个 streaming box 中。Tool calls 仍会被静默捕获。如果 provider 不支持 streaming，则会自动回退到普通显示模式。

Gateway Streaming（Telegram、Discord、Slack）

streaming:
  enabled: true           # 启用渐进式消息编辑
  transport: edit         # "edit"（渐进式编辑消息）或 "off"
  edit_interval: 0.3      # 两次消息编辑之间的秒数
  buffer_threshold: 40    # 达到多少字符后强制刷新一次编辑
  cursor: " ▉"            # streaming 过程中的光标

启用后，bot 会在第一个 token 到来时先发送一条消息，然后随着更多 tokens 到来不断编辑它。对于不支持消息编辑的平台（Signal、Email、Home Assistant），系统会在第一次尝试时自动检测，并为该 session 优雅地禁用 streaming，而不会导致消息刷屏。

溢出处理： 如果流式文本超过平台消息长度限制（约 4096 字符），当前消息会被定稿，然后自动开启新消息继续输出。

Group Chat Session 隔离

控制共享聊天是“每个房间一段对话”，还是“每个参与者一段对话”：

group_sessions_per_user: true  # true = 群组 / channel 中按用户隔离，false = 每个聊天共享一个 session

• true 是默认且推荐设置。在 Discord channels、Telegram groups、Slack channels 等共享场景中，只要平台能提供用户 ID，每个发送者都会拥有自己的 session。
• false 则恢复旧的共享房间行为。如果你明确希望 Hermes 把整个 channel 视为一段协作式对话，这会有用；但这也意味着用户会共享上下文、token 开销和 interrupt 状态。
• Direct messages 不受影响。Hermes 仍像往常一样根据 chat / DM ID 进行区分。
• Threads 在任意模式下都与父 channel 保持隔离；当 true 时，thread 内的每位参与者也会拥有各自独立的 session。

行为细节和示例请参阅 Sessions 和 Discord guide。

Unauthorized DM 行为

控制未知用户发送 direct message 时 Hermes 的处理方式：

unauthorized_dm_behavior: pair
whatsapp:
  unauthorized_dm_behavior: ignore

• pair 是默认值。Hermes 会拒绝访问，但会在 DM 中回复一次性 pairing code。
• ignore 会静默丢弃未授权 DM。
• 平台级配置会覆盖全局默认值，因此你可以在整体上启用 pairing，同时让某个平台更安静。

Quick Commands

定义无需调用 LLM、直接执行 shell commands 的自定义命令——零 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，也不消耗 tokens。

• 30 秒超时 —— 长时间运行的命令会被终止，并返回错误消息
• 优先级 —— quick commands 会在 skill commands 之前匹配，因此你可以覆盖 skill 名称
• 自动补全 —— quick commands 在分发阶段动态解析，不会显示在内置的 slash-command 自动补全表中
• 类型 —— 目前只支持 exec（运行 shell command）；其他类型会报错
• 适用范围广 —— CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant 都可用

Human Delay

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

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

Code Execution

配置带沙箱的 Python code execution tool：

code_execution:
  timeout: 300                 # 最大执行时间（秒）
  max_tool_calls: 50           # code execution 内允许的最大 tool calls 数

Web Search Backends

web_search、web_extract 和 web_crawl tools 支持四种 backend providers。可在 config.yaml 中或通过 hermes tools 进行配置：

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

Backend 选择： 如果没有设置 web.backend，系统会根据可用的 API keys 自动检测 backend。若仅设置了 EXA_API_KEY，则使用 Exa；仅设置了 TAVILY_API_KEY 时使用 Tavily；仅设置了 PARALLEL_API_KEY 时使用 Parallel；否则 Firecrawl 为默认值。

自托管 Firecrawl： 设置 FIRECRAWL_API_URL 指向你自己的实例。设置自定义 URL 后，API key 变为可选（在服务端设置 USE_DB_AUTHENTICATION=false 可关闭认证）。

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

Browser

配置浏览器自动化行为：

browser:
  inactivity_timeout: 120        # 空闲多久后自动关闭 session（秒）
  command_timeout: 30             # 浏览器命令超时（截图、导航等），单位秒
  record_sessions: false         # 自动将 browser sessions 录制为 WebM 视频，保存到 ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # 为 true 时，Camofox sessions 会在重启后保留 cookies / 登录状态

Browser toolset 支持多个 providers。详见 Browser feature page，其中介绍了 Browserbase、Browser Use 和本地 Chrome CDP 配置。

时区

使用 IANA timezone 字符串覆盖服务器本地时区。影响日志时间戳、cron 调度，以及 system prompt 中注入的时间。

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

支持任意 IANA timezone identifier（例如 America/New_York、Europe/London、Asia/Kolkata、UTC）。留空或省略则使用服务器本地时间。

Discord

配置 messaging gateway 中与 Discord 相关的行为：

discord:
  require_mention: true          # 在 server channels 中必须 @mention 才回应
  free_response_channels: ""     # 无需 @mention 即可回应的 channel ID 列表（逗号分隔）
  auto_thread: true              # 在 channel 中被 @mention 时自动创建 thread

• require_mention —— 为 true（默认）时，bot 仅在 server channels 中被 @BotName 提及时响应。在 DMs 中始终无需 mention。
• free_response_channels —— 一组以逗号分隔的 channel IDs，在这些 channels 中 bot 会对每条消息都响应，无需 mention。
• auto_thread —— 为 true（默认）时，在 channel 中被 mention 会自动创建 thread 来承载对话，从而让主 channel 保持整洁（类似 Slack threading）。

安全

执行前安全扫描与 secret 脱敏：

security:
  redact_secrets: true           # 在 tool output 和 logs 中脱敏 API key 模式
  tirith_enabled: true           # 对 terminal commands 启用 Tirith 安全扫描
  tirith_path: "tirith"          # tirith binary 路径（默认在 $PATH 中查找）
  tirith_timeout: 5              # 等待 tirith 扫描的最长秒数
  tirith_fail_open: true         # 如果 tirith 不可用，是否仍允许执行命令
  website_blocklist:             # 见下方 Website Blocklist 部分
    enabled: false
    domains: []
    shared_files: []

• redact_secrets —— 在 tool output 进入对话上下文和日志之前，自动检测并脱敏看起来像 API keys、tokens、passwords 的内容
• tirith_enabled —— 为 true 时，terminal commands 会在执行前通过 Tirith 扫描，以检测潜在危险操作
• tirith_path —— tirith binary 的路径。如果 tirith 安装在非标准位置，请在此设置
• tirith_timeout —— 等待 tirith 扫描的最长时间（秒）。若超时，命令仍会继续执行
• tirith_fail_open —— 为 true（默认）时，如果 tirith 不可用或扫描失败，命令仍允许执行。设为 false 则会在 tirith 无法验证时阻止命令执行

Website Blocklist

阻止 agent 的 web 和 browser tools 访问特定 domains：

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

启用后，所有匹配拦截规则的 URL 都会在 web 或 browser tool 执行前被拒绝。这适用于 web_search、web_extract、browser_navigate 以及所有会访问 URL 的工具。

Domain 规则支持：

• 精确域名：admin.example.com
• 通配子域名：*.internal.company.com（拦截所有子域）
• 顶级域通配：*.local

共享文件中每行一条 domain 规则（空行和 # 注释会被忽略）。如果文件缺失或不可读，会记录 warning，但不会禁用其他 web tools。

该策略缓存 30 秒，因此配置变更无需重启也能很快生效。

Smart Approvals

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

approvals:
  mode: manual   # manual | smart | off

Smart 模式非常适合减少 approval fatigue——它能让 agent 在安全操作上更自主，同时仍拦住真正有风险的命令。

Checkpoints

在执行破坏性文件操作前自动创建文件系统快照。详情请参阅 Checkpoints & Rollback。

checkpoints:
  enabled: true                  # 启用自动 checkpoints（也可通过 hermes --checkpoints）
  max_snapshots: 50              # 每个目录最多保留多少个 checkpoints

Delegation

配置 delegate tool 的 subagent 行为：

delegation:
  # model: "google/gemini-3-flash-preview"  # 覆盖 model（留空 = 继承父 agent）
  # provider: "openrouter"                  # 覆盖 provider（留空 = 继承父 agent）
  # base_url: "http://localhost:1234/v1"    # 直接指定 OpenAI-compatible endpoint（优先级高于 provider）
  # api_key: "local-key"                    # base_url 对应的 API key（回退到 OPENAI_API_KEY）

Subagent provider:model 覆盖： 默认情况下，subagents 会继承父 agent 的 provider 和 model。设置 delegation.provider 和 delegation.model 后，你可以让 subagents 路由到另一组 provider:model——例如，用便宜 / 快速的 model 处理范围明确的子任务，而主 agent 使用昂贵的 reasoning model。

直接 endpoint 覆盖： 如果你想走明确的 custom-endpoint 路径，可以设置 delegation.base_url、delegation.api_key 和 delegation.model。这样 subagents 会直接发送到该 OpenAI-compatible endpoint，并且优先于 delegation.provider。若省略 delegation.api_key，Hermes 只会回退到 OPENAI_API_KEY。

Delegation provider 使用与 CLI / gateway 启动相同的凭证解析机制。所有已配置 providers 都受支持：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。一旦设置了 provider，系统会自动解析正确的 base URL、API key 和 API mode——无需手动接线凭证。

优先级： 配置中的 delegation.base_url → 配置中的 delegation.provider → 父 provider（继承）。配置中的 delegation.model → 父 model（继承）。只设置 model 而不设置 provider，会只改变 model 名称，同时沿用父级凭证（适合在同一 provider 内切换 models，例如 OpenRouter）。

Clarify

配置澄清提问行为：

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

Context Files（SOUL.md、AGENTS.md）

Hermes 使用两种不同的 context 作用域：

• SOUL.md 是 agent 的主身份定义。它占据 system prompt 的 slot #1，并会完全替换内置默认身份。编辑它即可彻底自定义 agent 的身份。
• 如果 SOUL.md 缺失、为空，或无法加载，Hermes 会回退到内置默认身份。
• 项目 context files 使用优先级系统 —— 每次只加载一种类型（先匹配先使用）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
• AGENTS.md 是分层结构：如果子目录中也有 AGENTS.md，会全部组合起来。
• 如果默认 SOUL.md 不存在，Hermes 会自动生成一份默认版本。
• 所有加载的 context files 都会被限制在 20,000 个字符以内，并使用智能截断。

另请参阅：

• Personality & SOUL.md
• Context Files

工作目录

覆盖工作目录：

# 写入 ~/.hermes/.env 或 ~/.hermes/config.yaml：
MESSAGING_CWD=/home/myuser/projects    # Gateway sessions
TERMINAL_CWD=/workspace                # 所有 terminal sessions