Skip to main content

配置

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

目录结构​

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

管理配置​

hermes config              # View current configuration
hermes config edit         # Open config.yaml in your editor
hermes config set KEY VAL  # Set a specific value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

# Examples:
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env
tip

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

配置优先级​

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

  1. CLI 参数 — 例如 hermes chat --model anthropic/claude-sonnet-4（每次调用时的覆盖）
  2. ~/.hermes/config.yaml — 所有非敏感设置的主要配置文件
  3. ~/.hermes/.env — 环境变量的备用来源；必须用于敏感信息（API 密钥、令牌、密码）
  4. 内置默认值 — 当其他设置均未指定时使用的硬编码安全默认值
口诀

敏感信息（API 密钥、机器人令牌、密码）请放入 .env。其余内容（模型、终端后端、压缩设置、内存限制、工具集等）请放入 config.yaml。当两者都已设置时，config.yaml 对非敏感设置具有更高优先级。

环境变量替换​

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

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

单个值中可包含多个引用：url: "${HOST}:${PORT}"。如果引用的变量未设置，则占位符将原样保留（如 ${UNDEFINED_VAR} 保持不变）。仅支持 ${VAR} 语法 —— 未经处理的 $VAR 不会被展开。

关于 AI 提供商设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），请参阅 AI 提供商。

终端后端配置​

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

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Working directory ("." = current dir for local, "/root" for containers)
  timeout: 180      # Per-command timeout in seconds
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

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

后端概览​

后端命令执行位置隔离级别适用场景
local你的机器上直接运行无开发、个人使用
dockerDocker 容器内完全隔离（命名空间、能力降权）安全沙箱、CI/CD
ssh通过 SSH 连接的远程服务器网络边界远程开发、高性能硬件
modalModal 云沙箱完全隔离（云虚拟机）临时云计算、评估测试
daytonaDaytona 工作区完全隔离（云容器）受管理的云开发环境
singularitySingularity/Apptainer 容器内命名空间隔离（--containall）HPC 集群、共享机器

本地后端​

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

terminal:
  backend: local
warning

该代理拥有与你用户账户相同的文件系统访问权限。建议使用 hermes tools 禁用不需要的工具，或切换至 Docker 以实现沙箱隔离。

Docker 后端​

在经过安全加固的 Docker 容器中运行命令（移除所有能力、禁止权限提升、限制 PID 数量）。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # Mount launch dir into /workspace
  docker_forward_env:              # Env vars to forward into container
    - "GITHUB_TOKEN"
  docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro for read-only

  # Resource limits
  container_cpu: 1                 # CPU cores (0 = unlimited)
  container_memory: 5120           # MB (0 = unlimited)
  container_disk: 51200            # MB (requires overlay2 on XFS+pquota)
  container_persistent: true       # Persist /workspace and /root across sessions

要求： 已安装并运行 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
  • 为 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）设置大小受限的 tmpfs

凭证转发： 列在 docker_forward_env 中的环境变量会首先从你的 shell 环境中解析，然后从 ~/.hermes/.env 解析。技能也可以声明 required_environment_variables，这些将自动合并。

SSH 后端​

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 实现连接复用（5 分钟空闲保活）。默认启用持久化 shell —— 状态（当前目录、环境变量）可在命令之间持续保留。

terminal:
  backend: ssh
  persistent_shell: true           # Keep a long-lived bash session (default: true)

必需环境变量：

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

可选参数：

变量默认值说明
TERMINAL_SSH_PORT22SSH 端口
TERMINAL_SSH_KEY（系统默认）SSH 私钥路径
TERMINAL_SSH_PERSISTENTtrue启用持久化 shell

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

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

terminal:
  backend: modal
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # Snapshot/restore filesystem

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

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

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

Daytona 后端​

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

terminal:
  backend: daytona
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB → converted to GiB
  container_disk: 10240            # MB → converted to GiB (max 10 GiB)
  container_persistent: true       # Stop/resume instead of delete

必需条件： 设置 DAYTONA_API_KEY 环境变量。

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

磁盘限制： Daytona 强制最大 10 GiB。超过此限制的请求将被警告并截断。

Singularity/Apptainer 后端​

在 Singularity/Apptainer 容器中运行命令。专为 HPC 集群和无法使用 Docker 的共享机器设计。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB
  container_persistent: true       # Writable overlay persists across sessions

要求： 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 实现完整的命名空间隔离，且不挂载主机家目录。

常见终端后端问题​

若终端命令立即失败或提示终端工具已禁用：

  • 本地 — 无特殊要求。开始使用时最安全的默认选项。
  • Docker — 运行 docker version 验证 Docker 是否正常工作。若失败，请修复 Docker 或检查 hermes config set terminal.backend local。
  • SSH — 必须同时设置 TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER。Hermes 会在任一缺失时输出清晰错误。
  • Modal — 需要 MODAL_TOKEN_ID 环境变量或 ~/.modal.toml。运行 hermes doctor 检查。
  • Daytona — 需要 DAYTONA_API_KEY。Daytona SDK 会处理服务器 URL 配置。
  • Singularity — 需要在 $PATH 中设置 apptainer 或 singularity。在 HPC 集群中常见。如有疑问，请将 terminal.backend 恢复为 local，并先验证命令是否可在该环境中正常运行。

Docker 卷挂载​

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

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # Read-write (default)
    - "/home/user/datasets:/data:ro"              # Read-only
    - "/home/user/outputs:/outputs"               # Agent writes, you read

这个能力在以下场景中尤其有用：

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

也可通过环境变量设置：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 保存过）。

warning

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

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

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

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用后：

  • 若你从 ~/projects/my-app 启动 Hermes，该主机目录将被绑定挂载至 /workspace
  • Docker 后端将在 /workspace 目录下启动
  • 文件工具和终端命令均能看到相同的已挂载项目

禁用时，/workspace 仍由沙箱独占，除非你通过 docker_volumes 显式挂载其他内容。

安全权衡：

  • false 保留沙箱边界
  • true 使沙箱可直接访问你启动 Hermes 时所在的目录

仅当你有意让容器操作主机上的实时文件时才启用此选项。

持久化 Shell​

默认情况下，每次终端命令都在独立的子进程中执行——工作目录、环境变量和 shell 变量在命令间重置。当启用 持久化 Shell 时，一个长期存活的 bash 进程将跨 execute() 调用保持运行，从而使状态在命令间持续存在。

这对 SSH 后端 最为有用，因为它还能消除每条命令的连接开销。持久化 Shell 在 SSH 后端 默认启用，在本地后端则默认关闭。

terminal:
  persistent_shell: true   # default — enables persistent shell for SSH

要禁用它：

hermes config set terminal.persistent_shell false

在命令间持续存在的内容：

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

优先级顺序：

层级变量默认值
配置terminal.persistent_shelltrue
SSH 覆盖TERMINAL_SSH_PERSISTENT继承配置
本地覆盖TERMINAL_LOCAL_PERSISTENTfalse

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

export TERMINAL_LOCAL_PERSISTENT=true
note

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

有关各后端的详细信息，请参阅 代码执行 和 README 中的终端章节。

技能设置​

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

skills:
  config:
    wiki:
      path: ~/wiki          # Used by the llm-wiki skill

技能设置的工作方式：

  • hermes config migrate 会扫描所有启用的技能，查找未配置的设置，并提示你输入
  • hermes config show 会在“技能设置”部分显示所有技能的配置项及其所属技能
  • 当技能加载时，其解析后的配置值会自动注入到技能上下文中

手动设置值：

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

关于如何在自定义技能中声明配置项，请参阅 创建技能：配置项设置。

内存配置​

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

文件读取安全​

控制单次 read_file 调用可返回的内容量。超过限制的读取将被拒绝，并提示代理改用 offset 和 limit 来指定更小的范围。此举防止单次读取压缩后的 JS 包或大型数据文件导致上下文窗口被填满。

file_read_max_chars: 100000  # default — ~25-35K tokens

如果你使用的是大上下文窗口模型且频繁读取大文件，可适当提高该值；对于小上下文模型，则应降低以保持读取效率：

# Large context model (200K+)
file_read_max_chars: 200000

# Small local model (16K context)
file_read_max_chars: 30000

代理还会自动去重文件读取——如果同一文件区域被重复读取且文件未更改，将返回轻量级占位符而非重新发送内容。该机制在上下文压缩后重置，因此代理可在内容被摘要后重新读取文件。

Git 工作树隔离​

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

worktree: true    # Always create a worktree (same as hermes -w)
# worktree: false # Default — only when -w flag is passed

启用后，每个 CLI 会话都会在 .worktrees/ 下创建一个全新的工作树，并拥有独立分支。代理可编辑文件、提交、推送及创建 PR，互不干扰。退出时干净的工作树会被自动清理；脏的工作树将保留以便手动恢复。

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

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩​

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

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

完整参考​

compression:
  enabled: true                                     # Toggle compression on/off
  threshold: 0.50                                   # Compress at this % of context limit
  target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
  protect_last_n: 20                                # Min recent messages to keep uncompressed

# The summarization model/provider is configured under auxiliary:
auxiliary:
  compression:
    model: "google/gemini-3-flash-preview"          # Model for summarization
    provider: "auto"                                # Provider: "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null                                  # Custom OpenAI-compatible endpoint (overrides provider)
旧配置迁移

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

常见配置方案​

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

compression:
  enabled: true
  threshold: 0.50

使用首个可用的提供商（OpenRouter → Nous → Codex），搭配 Gemini Flash。

强制指定特定提供商（OAuth 或 API-Key 方式）：

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

适用于任意提供商：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.providerauxiliary.compression.base_url结果
auto（默认）未设置自动检测最佳可用提供商
nous / openrouter / 等未设置强制使用该提供商，并使用其认证方式
任意值已设置直接使用自定义端点（忽略提供商）
摘要模型上下文长度要求

摘要模型 必须 具有至少与主代理模型相当的上下文窗口。压缩器会将对话中间部分完整发送给摘要模型——如果该模型的上下文窗口小于主模型，摘要调用将因上下文长度错误而失败。此时中间轮次将 被丢弃且无摘要，无声丢失对话上下文。若你覆盖了模型，请确保其上下文长度不低于主模型。

上下文引擎​

上下文引擎决定模型在接近 token 上限时如何管理对话。内置的 compressor 引擎采用有损摘要策略（参见 上下文压缩）。如果安装了插件，也可以切换到其他上下文管理策略。

context:
  engine: "compressor"    # default — built-in lossy summarization

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

context:
  engine: "lcm"          # must match the plugin's name

插件引擎不会自动激活——您必须显式将 context.engine 设置为插件名称。可用引擎可通过 hermes plugins → 提供商插件 → 上下文引擎 浏览并选择。

有关记忆插件的类似单选系统，请参见 记忆提供者。

迭代预算压力​

当代理执行复杂任务且调用多个工具时，可能在未察觉的情况下迅速耗尽其迭代预算（默认：90 轮）。预算压力会随着接近上限而自动向模型发出警告：

阈值等级模型所见内容
70%警示[BUDGET: 63/90. 27 iterations left. Start consolidating.]
90%警告[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]

警告以 _budget_warning 字段形式注入到上一个工具结果的 JSON 中，而非作为独立消息——这能保留提示缓存，并避免破坏对话结构。

agent:
  max_turns: 90                # Max iterations per conversation turn (default: 90)

迭代预算压力默认开启。代理会自然地在工具结果中看到这些警告，从而鼓励其整合工作，在迭代耗尽前提交最终响应。

当迭代预算完全耗尽时，CLI 会向用户显示通知：⚠ Iteration budget reached (90/90) — response may be incomplete。若在主动工作期间预算耗尽，代理将生成已完成工作的摘要后停止运行。

流式传输超时​

LLM 流式连接包含两层超时机制。对于本地提供者（localhost、局域网 IP），两者均会自动调整——大多数配置无需额外设置。

超时类型默认值本地提供者环境变量
套接字读取超时120s自动提升至 1800sHERMES_STREAM_READ_TIMEOUT
静默流检测180s自动禁用HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）1800s不变HERMES_API_TIMEOUT

套接字读取超时 控制 httpx 等待提供者发送下一数据块的时间。本地大上下文模型在生成首个 token 前可能需要数分钟预填充，因此 Hermes 在检测到本地端点时将其提升至 30 分钟。若您显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论是否检测到本地端点，都将始终使用该值。

静默流检测 会终止仅接收 SSE 心跳但无实际内容的连接。此功能对本地提供者完全禁用，因为它们在预填充阶段不会发送心跳包。

上下文压力警告​

与迭代预算压力不同，上下文压力跟踪对话距离压缩阈值（即触发上下文压缩以摘要旧消息的临界点）有多近。这有助于您和代理了解对话是否过长。

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

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

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

在即时通讯平台中，会发送纯文本通知：

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

若已禁用自动压缩，警告将提示上下文可能被截断。

上下文压力为自动启用——无需任何配置。它仅作为面向用户的提醒，不会修改消息流或向模型上下文注入任何内容。

凭证池策略​

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

credential_pool_strategies:
  openrouter: round_robin    # cycle through keys evenly
  anthropic: least_used      # always pick the least-used key

选项包括：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、kimi-coding-cn、arcee、minimax，以及注册在 提供者注册表 中的任意提供者，或您自定义提供者列表中的任意命名提供者（如 provider: "beans"）。

"main" 仅适用于辅助任务

"main" 提供者选项表示“沿用主代理当前使用的提供者”——它仅在 auxiliary:、compression: 和 fallback_model: 配置中有效。它不是顶层 model.provider 设置的合法值。若你使用的是自定义 OpenAI 兼容端点，请在 model: 部分设置 provider: custom。更多主模型提供者选项请参见 AI 提供商。

完整辅助配置参考​

auxiliary:
  # Image analysis (vision_analyze tool + browser screenshots)
  vision:
    provider: "auto"           # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                  # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""               # Custom OpenAI-compatible endpoint (overrides provider)
    api_key: ""                # API key for base_url (falls back to OPENAI_API_KEY)
    timeout: 120               # seconds — LLM API call timeout; vision payloads need generous timeout
    download_timeout: 30       # seconds — image HTTP download; increase for slow connections

  # Web page summarization + browser page text extraction
  web_extract:
    provider: "auto"
    model: ""                  # e.g. "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # seconds (6min) — per-attempt LLM summarization

  # Dangerous command approval classifier
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # seconds

  # Context compression timeout (separate from compression.* config)
  compression:
    timeout: 120               # seconds — compression summarizes long conversations, needs more time

  # Session search — summarizes past session matches
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Skills hub — skill matching and search
  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 — summarizes conversation for persistent memory
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
tip

每个辅助任务都有可配置的 timeout（单位：秒）。默认值：视觉任务 120 秒，网页提取 360 秒，审批任务 30 秒，压缩任务 120 秒。若使用较慢的本地模型处理辅助任务，可适当增加。视觉任务还有一项独立的 download_timeout（默认 30 秒），用于 HTTP 图像下载——对于慢速网络或自托管图像服务器，可提高该值。

info

上下文压缩有自己的 compression: 配置块用于设置阈值，auxiliary.compression: 配置块用于设置模型与提供者——详见上方 上下文压缩。回退模型使用 fallback_model: 配置块——详见 回退模型。三者遵循相同的 provider / model / base URL 配置模式。

更改视觉模型​

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

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

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

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供者选项​

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

提供商说明要求
"auto"最佳可用选项（默认）。视觉处理优先尝试 OpenRouter → Nous → Codex。—
"openrouter"强制使用 OpenRouter — 可路由至任意模型（Gemini、GPT-4o、Claude 等）OPENROUTER_API_KEY
"nous"强制使用 Nous Portalhermes 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）：

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

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

auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"       # or "gpt-4o-mini" for cheaper

使用 OpenRouter 进行视觉处理（路由至任意模型）：

auxiliary:
  vision:
    provider: "openrouter"
    model: "openai/gpt-4o"      # or "google/gemini-2.5-flash", etc.

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

auxiliary:
  vision:
    provider: "codex"     # uses your ChatGPT OAuth token
    # model defaults to gpt-5.3-codex (supports vision)

使用本地/自托管模型：

auxiliary:
  vision:
    provider: "main"      # uses your active custom endpoint
    model: "my-local-model"

provider: "main" 会复用 Hermes 当前用于常规聊天的提供者，无论它是命名的自定义提供者（如 beans）、内置提供者（如 openrouter），还是旧版的 OPENAI_BASE_URL 端点。

tip

如果你把 Codex OAuth 设为主模型提供者，视觉能力会自动生效，无需额外配置。Codex 已包含在视觉任务的自动检测链中。

warning

视觉功能需要多模态模型。 如果你设置了 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 中配置。

tip

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

推理努力程度​

控制模型在响应前“思考”的程度：

agent:
  reasoning_effort: ""   # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max)

未设置时（默认），推理努力程度为“中等”——一个对大多数任务都表现良好的平衡水平。设置具体值将覆盖默认值——更高的推理努力程度可在复杂任务上获得更好结果，代价是消耗更多 token 并增加延迟。

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

/reasoning           # Show current effort level and display state
/reasoning high      # Set reasoning effort to high
/reasoning none      # Disable reasoning
/reasoning show      # Show model thinking above each response
/reasoning hide      # Hide model thinking

工具调用强制执行​

某些模型偶尔会以文本形式描述预期操作，而非实际调用工具（例如“我会运行测试……”而不是真正调用终端）。工具调用强制执行通过注入系统提示引导，促使模型实际调用工具。

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"]仅当模型名称包含列表中的任一子字符串时启用（不区分大小写）。

注入内容​

启用后，系统提示中可能添加三层引导：

  1. 通用工具调用强制（所有匹配模型）—— 指示模型立即调用工具，而非描述意图；持续工作直至任务完成；绝不以“未来会做”作为本轮结束。

  2. OpenAI 执行纪律（仅限 GPT 和 Codex 模型）—— 针对 GPT 特有失败模式的额外引导：在部分结果时放弃工作、跳过前置检查、幻觉生成而非使用工具、在未验证情况下宣布“已完成”。

  3. 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                    # Global speed multiplier (fallback for all providers)
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
    speed: 1.0                  # Speed multiplier (converted to rate percentage, e.g. 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                  # Speed multiplier (clamped to 0.25–4.0 by the API)
    base_url: "https://api.openai.com/v1"  # Override for OpenAI-compatible TTS endpoints
  minimax:
    speed: 1.0                  # Speech speed multiplier
    # base_url: ""              # Optional: override for OpenAI-compatible TTS endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

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

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

显示设置​

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # Enable /verbose slash command in messaging gateway
  tool_progress_overrides: {}  # Per-platform overrides (see below)
  interim_assistant_messages: true  # Gateway: send natural mid-turn assistant updates as separate messages
  skin: default           # Built-in or custom CLI skin (see user-guide/features/skins)
  personality: "kawaii"  # Legacy cosmetic field still surfaced in some summaries
  compact: false          # Compact output mode (less whitespace)
  resume_display: full    # full (show previous messages on resume) | minimal (one-liner only)
  bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks)
  show_reasoning: false   # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
  streaming: false        # Stream tokens to terminal as they arrive (real-time output)
  show_cost: false        # Show estimated $ cost in the CLI status bar
  tool_preview_length: 0  # Max chars for tool call previews (0 = no limit, show full paths/commands)
模式你看到的内容
off静音 — 仅显示最终响应
new仅在工具变更时显示工具指示符
all每次工具调用附带简短预览（默认）
verbose显示完整参数、结果及调试日志

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

各平台进度覆盖​

不同平台对信息详略需求不同。例如，Signal 不支持编辑消息，因此每次进度更新都会变成独立消息 —— 易造成噪音。使用 tool_progress_overrides 可为各平台设置独立模式：

display:
  tool_progress: all          # global default
  tool_progress_overrides:
    signal: 'off'             # silence progress on Signal
    telegram: verbose         # detailed progress on Telegram
    slack: 'off'              # quiet in shared Slack workspace

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

interim_assistant_messages 仅适用于网关。启用后，Hermes 会将中途完成的助手更新作为独立聊天消息发送。此功能独立于 tool_progress，且不需要网关流式传输。

隐私​

privacy:
  redact_pii: false  # Strip PII from LLM context (gateway only)

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

字段处理方式
电话号码（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）​

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"         # Legacy fallback key still respected

服务提供商行为：

  • local 使用运行在您本地机器上的 faster-whisper。需单独安装，通过 pip install faster-whisper 进行配置。
  • groq 使用 Groq 的 Whisper 兼容接口，并读取 GROQ_API_KEY。
  • openai 使用 OpenAI 的语音 API，并读取 VOICE_TOOLS_OPENAI_KEY。

如果请求的服务提供商不可用，Hermes 将按以下顺序自动降级：local → groq → openai。

Groq 和 OpenAI 模型覆盖由环境变量驱动：

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

语音模式（CLI）​

voice:
  record_key: "ctrl+b"         # Push-to-talk key inside the CLI
  max_recording_seconds: 120    # Hard stop for long recordings
  auto_tts: false               # Enable spoken replies automatically when /voice on
  silence_threshold: 200        # RMS threshold for speech detection
  silence_duration: 3.0         # Seconds of silence before auto-stop

在 CLI 中使用 /voice on 启用麦克风模式，使用 record_key 开始或停止录音，使用 /voice tts 切换语音回复。详见 语音模式 了解端到端设置及各平台的具体行为说明。

流式传输​

将令牌逐个流式输出至终端或消息平台，而非等待完整响应。

CLI 流式传输​

display:
  streaming: true         # Stream tokens to terminal in real-time
  show_reasoning: true    # Also stream reasoning/thinking tokens (optional)

启用后，响应以流式框形式逐个 token 显示。工具调用仍会静默捕获。若提供商不支持流式传输，则自动回退至正常显示。

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

streaming:
  enabled: true           # Enable progressive message editing
  transport: edit         # "edit" (progressive message editing) or "off"
  edit_interval: 0.3      # Seconds between message edits
  buffer_threshold: 40    # Characters before forcing an edit flush
  cursor: " ▉"            # Cursor shown during streaming

启用后，机器人在首个 token 到达时发送一条消息，随后随着更多 token 到达逐步编辑该消息。对于不支持消息编辑的平台（如 Signal、电子邮件、Home Assistant），会在首次尝试时自动检测——该会话中流式传输将优雅禁用，避免消息泛滥。

如需在对话中途获得独立的自然更新（而非逐 token 编辑），请设置 display.interim_assistant_messages: true。

溢出处理： 若流式文本超过平台的消息长度限制（约 4096 字符），当前消息将被确认并自动开启新消息。

note

流式传输默认关闭。请在 ~/.hermes/config.yaml 中启用以体验流式交互界面。

群聊会话隔离​

控制共享聊天是否按房间保持一个会话，还是按参与者保持独立会话：

group_sessions_per_user: true  # true = per-user isolation in groups/channels, false = one shared session per chat
  • true 是默认且推荐的设置。在 Discord 频道、Telegram 群组、Slack 频道等共享上下文中，当平台提供用户 ID 时，每位发送者都将拥有自己的会话。
  • false 回退到旧版共享房间行为。这在你明确希望 Hermes 将频道视为单一协作对话时可能有用，但也会导致用户共享上下文、Token 成本和中断状态。
  • 私人消息不受影响。Hermes 仍按聊天/私信 ID 键控 DM。
  • 无论设置如何，线程始终与父频道隔离；使用 true 时，线程内每位参与者也将拥有自己的会话。

详细行为与示例，请参阅 会话 和 Discord 指南 。

未授权私信行为​

控制当未知用户发送私信时 Hermes 的应对策略：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • pair 为默认设置。Hermes 拒绝访问，但在私信中回复一次性配对码。
  • ignore 静默丢弃未授权的私信。
  • 平台设置可覆盖全局默认值，因此你可以在整体保持配对功能的同时，让某个平台更安静。

快速命令​

定义自定义命令，直接执行 shell 命令而不调用 LLM —— 零 Token 消耗，即时执行。特别适用于消息平台（Telegram、Discord 等）中的快速服务器检查或实用脚本。

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

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

  • 30 秒超时 —— 长时间运行的命令将被终止并返回错误信息
  • 优先级 —— 快速命令在技能命令之前检查，因此你可以覆盖技能名称
  • 自动补全 —— 快速命令在分派时解析，不会出现在内置斜杠命令自动补全列表中
  • 类型限制 —— 仅支持 exec（执行 shell 命令）；其他类型将报错
  • 跨平台可用 —— CLI、Telegram、Discord、Slack、WhatsApp、Signal、电子邮件、Home Assistant 均支持

人类延迟​

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

human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # Minimum delay (custom mode)
  max_ms: 2500                 # Maximum delay (custom mode)

代码执行​

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

code_execution:
  timeout: 300                 # Max execution time in seconds
  max_tool_calls: 50           # Max tool calls within code execution

网络搜索后端​

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

web:
  backend: firecrawl    # firecrawl | parallel | tavily | exa
后端环境变量搜索提取爬取
Firecrawl（默认）FIRECRAWL_API_KEY✔✔✔
ParallelPARALLEL_API_KEY✔✔—
TavilyTAVILY_API_KEY✔✔✔
ExaEXA_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        # Seconds before auto-closing idle sessions
  command_timeout: 30             # Timeout in seconds for browser commands (screenshot, navigate, etc.)
  record_sessions: false         # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # When true, Camofox sessions persist cookies/logins across restarts

浏览器工具集支持多个提供商。详情请见 浏览器功能页面 ，了解 Browserbase、Browser Use 及本地 Chrome CDP 设置。

时区​

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

timezone: "America/New_York"   # IANA timezone (default: "" = server-local time)

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

Discord​

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

discord:
  require_mention: true          # Require @mention to respond in server channels
  free_response_channels: ""     # Comma-separated channel IDs where bot responds without @mention
  auto_thread: true              # Auto-create threads on @mention in channels
  • require_mention —— 当 true（默认）时，机器人仅在被提及（含 @BotName）时响应服务器频道中的消息。私信始终无需提及即可工作。
  • free_response_channels —— 逗号分隔的频道 ID 列表，机器人在这些频道中对所有消息作出响应，无需提及。
  • auto_thread —— 当 true（默认）时，频道中的提及会自动创建线程以保持频道整洁（类似 Slack 的线程功能）。

安全​

预执行安全扫描与敏感信息脱敏：

security:
  redact_secrets: true           # Redact API key patterns in tool output and logs
  tirith_enabled: true           # Enable Tirith security scanning for terminal commands
  tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
  tirith_timeout: 5              # Seconds to wait for tirith scan before timing out
  tirith_fail_open: true         # Allow command execution if tirith is unavailable
  website_blocklist:             # See Website Blocklist section below
    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 无法验证命令时阻止其执行。

网站黑名单​

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

security:
  website_blocklist:
    enabled: false               # Enable URL blocking (default: false)
    domains:                     # List of blocked domain patterns
      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # Load additional rules from external files
      - "/etc/hermes/blocked-sites.txt"

启用后，任何匹配被屏蔽域名模式的 URL 都会在网页或浏览器工具执行前被拒绝。此规则适用于 web_search、web_extract、browser_navigate 以及所有访问 URL 的工具。

域名规则支持：

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

共享文件中每行一个域名规则（空行和 # 注释会被忽略）。文件缺失或无法读取时会记录警告，但不会禁用其他网页工具。

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

智能审批​

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

approvals:
  mode: manual   # manual | smart | off
模式行为
manual（默认）在执行任何标记命令前提示用户确认。在 CLI 中显示交互式审批对话框；在消息系统中将审批请求放入待处理队列。
smart使用辅助大模型评估标记命令是否真正危险。低风险命令自动批准，并在会话级别保持持久性。真正高风险命令则升级至用户确认。
off跳过所有审批检查。等同于 HERMES_YOLO_MODE=true。请谨慎使用。

智能模式特别有助于减少审批疲劳——让代理在安全操作上更自主地运行，同时仍能捕捉真正具有破坏性的命令。

warning

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

检查点​

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

checkpoints:
  enabled: true                  # Enable automatic checkpoints (also: hermes --checkpoints)
  max_snapshots: 50              # Max checkpoints to keep per directory

委托​

配置子代理在 delegate 工具中的行为：

delegation:
  # model: "google/gemini-3-flash-preview"  # Override model (empty = inherit parent)
  # provider: "openrouter"                  # Override provider (empty = inherit parent)
  # base_url: "http://localhost:1234/v1"    # Direct OpenAI-compatible endpoint (takes precedence over provider)
  # api_key: "local-key"                    # API key for base_url (falls back to OPENAI_API_KEY)

子代理提供者:模型覆盖：默认情况下，子代理继承父代理的提供者和模型。通过设置 delegation.provider 和 delegation.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）。

明确化​

配置澄清提示的行为：

clarify:
  timeout: 120                 # Seconds to wait for user clarification response

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

Hermes 使用两种不同的上下文作用域：

文件目的作用域
SOUL.md主代理身份 — 定义代理的身份（系统提示中的第 #1 位）~/.hermes/SOUL.md 或 $HERMES_HOME/SOUL.md
.hermes.md / HERMES.md项目特定指令（最高优先级）向 git 根目录遍历
AGENTS.md项目特定指令，编码规范递归目录遍历
CLAUDE.mdClaude Code 上下文文件（也支持检测）仅限工作目录
.cursorrulesCursor IDE 规则（也支持检测）仅限工作目录
.cursor/rules/*.mdcCursor 规则文件（也支持检测）仅限工作目录
  • 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容器或远程机器内的用户主目录

覆盖工作目录：

# In ~/.hermes/.env or ~/.hermes/config.yaml:
MESSAGING_CWD=/home/myuser/projects    # Gateway sessions
TERMINAL_CWD=/workspace                # All terminal sessions