Hermes Agent config.yaml 中文配置说明

Hermes Agent 安装完成后，主要配置文件通常是：

~/.hermes/config.yaml

多 profile 场景下，每个 profile 也会有自己的配置：

~/.hermes/profiles/<profile>/config.yaml

这篇按官方 cli-config.yaml.example 和官方配置参考整理，查询时间是 2026-05-30。Hermes 仍在快速迭代，字段可能随版本变化。生产环境不要追求“字段越多越好”，只保留自己理解且确实需要的配置。

参考资料：

修改前先备份

先切到运行 Hermes 的用户，例如：

sudo su - hermesuser

备份配置：

HERMES_HOME="${HOME}/.hermes"
CONFIG="${HERMES_HOME}/config.yaml"

cp "$CONFIG" "${CONFIG}.bak.$(date +%Y%m%d-%H%M%S)"

编辑配置：

nvim "$CONFIG"

如果系统没有 nvim：

nano "$CONFIG"

改完先检查 Hermes：

hermes doctor

如果修改了 Gateway、Telegram、工具显示、模型或平台参数，重启对应服务：

systemctl --user restart hermes-gateway.service
systemctl --user status hermes-gateway.service --no-pager

多 profile 先看服务名：

systemctl --user list-units 'hermes*' --no-pager

总体结构

官方示例配置的主干大致如下：

model:
  default: "anthropic/claude-opus-4.6"
  provider: "auto"
  base_url: "https://openrouter.ai/api/v1"

terminal:
  backend: "local"
  cwd: "."
  timeout: 180

display:
  tool_progress: all
  interim_assistant_messages: true
  long_running_notifications: true
  background_process_notifications: all
  show_reasoning: false
  streaming: true

streaming:
  enabled: false

platform_toolsets:
  cli: [hermes-cli]
  telegram: [hermes-telegram]

platforms:
  telegram:
    reply_to_mode: "first"
    guest_mode: false
    extra:
      disable_link_previews: false

agent:
  max_turns: 60
  verbose: false
  reasoning_effort: "medium"

compression:
  enabled: true
  threshold: 0.50

stt:
  enabled: true

你自己的文件不一定每段都有。缺失字段一般会使用默认值，不要把整份示例无脑复制进去。

model：模型与供应商

model 是最重要的一段，决定默认模型和 provider。

model:
  default: "anthropic/claude-opus-4.6"
  provider: "auto"
  base_url: "https://openrouter.ai/api/v1"

常用字段：

字段	作用	常见值
`model.default`	默认模型名，也可用 `model.model`	`anthropic/claude-opus-4.6`、`openai/gpt-4.1`
`model.provider`	推理供应商	`auto`、`openrouter`、`nous`、`nous-api`、`anthropic`、`openai-codex`、`gemini`、`custom`
`model.base_url`	OpenAI-compatible 接口地址	`https://openrouter.ai/api/v1` 或自建接口
`model.api_key`	直接写 API Key	不推荐写在配置里
`model.context_length`	总上下文窗口	默认自动检测，只有检测错才手动写
`model.max_tokens`	单次输出上限	想限制回答长度时设置

API Key 推荐放在：

~/.hermes/.env

例如：

OPENROUTER_API_KEY=填自己的
OPENAI_API_KEY=填自己的
ANTHROPIC_API_KEY=填自己的
GOOGLE_API_KEY=填自己的
NVIDIA_API_KEY=填自己的

OpenAI-compatible 本地或中转接口示例：

model:
  provider: "custom"
  default: "qwen-plus"
  base_url: "https://api.example.com/v1"

自定义接口的密钥读取方式要以当前 Hermes 版本为准。不要默认所有 OpenAI-compatible 接口都读取 OPENAI_API_KEY；有些版本会根据 base_url 主机名派生环境变量名，例如 https://api.example.com/v1 可能读取 EXAMPLE_API_KEY。生产环境推荐：

先用 hermes config show 确认 model.provider、model.default、model.base_url。
把真实密钥写在 ~/.hermes/.env，不要写进公开教程、聊天记录或截图。
设置后用 hermes -z "请只回复：模型连通性测试通过" 做真实连通性测试。
如果 Telegram 提示 provider failed，再看 journalctl --user -u hermes-gateway.service -n 120 --no-pager -o cat，只记录 provider、model、base_url、HTTP 状态码和错误摘要。

providers：供应商超时和模型例外

providers 用来给某个供应商或某个模型单独设置超时。

providers:
  ollama-local:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900
  anthropic:
    request_timeout_seconds: 30
    models:
      claude-opus-4.6:
        timeout_seconds: 600

适合场景：

本地模型冷启动慢。
某个云模型偶发长时间等待。
大上下文模型需要更长超时。

provider_routing 与 openrouter

这两段主要服务 OpenRouter。

provider_routing:
  sort: "throughput"
  only: ["anthropic", "google"]
  ignore: ["deepinfra"]
  require_parameters: true
  data_collection: "deny"

openrouter:
  response_cache: true
  response_cache_ttl: 300

说明：

字段	作用
`provider_routing.sort`	按价格、吞吐或延迟排序
`provider_routing.only`	只允许指定 OpenRouter provider
`provider_routing.ignore`	排除指定 provider
`provider_routing.order`	按指定顺序尝试 provider
`provider_routing.data_collection`	控制是否排除可能留存数据的 provider
`openrouter.response_cache`	开启 OpenRouter 边缘响应缓存
`openrouter.response_cache_ttl`	缓存秒数

如果对数据去向敏感，可以设置 data_collection: "deny"。

terminal：命令执行环境

terminal 决定 Hermes 的 terminal 工具在哪里执行命令。

本机执行：

terminal:
  backend: "local"
  cwd: "."
  timeout: 180
  lifetime_seconds: 300
  docker_mount_cwd_to_workspace: false

SSH 远程执行：

terminal:
  backend: "ssh"
  cwd: "/home/hermesuser/project"
  timeout: 180
  lifetime_seconds: 300
  ssh_host: "server.example.com"
  ssh_user: "hermesuser"
  ssh_port: 22
  ssh_key: "~/.ssh/id_ed25519"

Docker 沙箱执行：

terminal:
  backend: "docker"
  cwd: "/workspace"
  timeout: 180
  lifetime_seconds: 300
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: true
  docker_run_as_host_user: true
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

字段说明：

字段	作用
`backend`	`local`、`ssh`、`docker`、`singularity`、`modal`、`daytona`
`cwd`	命令执行目录
`timeout`	单条命令超时
`lifetime_seconds`	会话保活时间
`sudo_password`	明文 sudo 密码，不推荐
`docker_mount_cwd_to_workspace`	是否把启动目录挂到容器 `/workspace`
`docker_forward_env`	转发哪些环境变量进容器
`docker_extra_args`	额外 `docker run` 参数
`container_cpu/memory/disk`	容器资源限制
`container_persistent`	容器文件系统是否持久

如果已经给 hermesuser 做了 sudo 免密，通常不要把 sudo 密码写进 config.yaml。

display：显示、进度和安静模式

display 控制 Hermes 在 CLI 和 Gateway 平台上显示多少过程信息。

Telegram 安静模式：

display:
  tool_progress: off
  cleanup_progress: true
  interim_assistant_messages: false
  long_running_notifications: true
  busy_ack_detail: true
  background_process_notifications: off
  show_reasoning: false
  streaming: false
  platforms:
    telegram:
      tool_progress: off
      cleanup_progress: true
      interim_assistant_messages: false
      long_running_notifications: true
      busy_ack_detail: true
      background_process_notifications: off

字段说明：

字段	作用
`display.compact`	是否使用紧凑启动 banner
`display.tool_progress`	工具进度显示级别：`off`、`new`、`all`、`verbose`
`display.cleanup_progress`	最终回复后是否清理临时进度消息
`display.interim_assistant_messages`	是否发送中途自然语言状态更新
`display.long_running_notifications`	长任务是否发送“仍在工作”心跳
`display.busy_ack_detail`	busy/heartbeat 是否显示迭代、工具、耗时细节
`display.busy_input_mode`	忙碌时新消息是打断、排队还是 steer
`display.background_process_notifications`	后台进程 watcher 消息：`off`、`result`、`error`、`all`
`display.bell_on_complete`	完成时是否响铃
`display.show_reasoning`	是否显示模型 reasoning
`display.streaming`	CLI token 流式输出
`display.skin`	CLI 皮肤主题
`display.platforms.telegram`	Telegram 单独覆盖显示策略

想要 Telegram 干净但不失联，就把工具进度、中途消息和后台进程通知关掉，保留带 iteration/API 等进度细节的长任务心跳。

streaming：Gateway 流式输出

注意：display.streaming 主要影响 CLI 显示；顶层 streaming 是 Gateway 消息平台的流式输出。

Telegram 只要最终答案：

streaming:
  enabled: false

想体验 Telegram/Discord/Slack 边生成边编辑消息：

streaming:
  enabled: true
  transport: edit
  edit_interval: 0.3
  buffer_threshold: 40
  cursor: " ▉"

Telegram 安静模式建议保持 enabled: false。

agent：Agent 行为

agent:
  max_turns: 60
  verbose: false
  reasoning_effort: "medium"

说明：

字段	作用
`max_turns`	单次任务最多工具循环轮数
`gateway_timeout`	Gateway Agent 空闲超时
`gateway_timeout_warning`	超时前警告
`restart_drain_timeout`	Gateway stop/restart 时等待任务收尾的秒数
`api_max_retries`	API 错误重试次数
`verbose`	是否开启详细日志
`reasoning_effort`	推理强度：`xhigh`、`high`、`medium`、`low`、`minimal`、`none`
`personalities`	自定义 personality

长期 Telegram 服务建议 max_turns 不要太低，否则复杂任务容易中断；也不要过高，否则失败任务会拖太久。

platform_toolsets：各平台工具集

platform_toolsets 决定不同入口能用哪些工具。

默认类似：

platform_toolsets:
  cli: [hermes-cli]
  telegram: [hermes-telegram]
  discord: [hermes-discord]
  whatsapp: [hermes-whatsapp]
  slack: [hermes-slack]

如果想限制 Telegram 权限，可以改成只给少量工具：

platform_toolsets:
  telegram: [web, terminal, file, todo]

更保守的只读思路：

platform_toolsets:
  telegram: [web, vision, skills, todo]

常见工具集：

名称	作用
`web`	搜索和网页提取
`terminal`	执行命令
`file`	读写、搜索、打补丁
`browser`	浏览器自动化
`vision`	图片理解
`image_gen`	图片生成
`skills`	查看和使用技能
`todo`	内存任务计划
`cronjob`	创建和管理定时任务
`hermes-cli`	CLI 默认预设
`hermes-telegram`	Telegram 默认预设

生产环境不要给不可信群聊默认开放强工具。

platforms.telegram：Telegram 平台参数

Telegram 专属设置放在 platforms.telegram 下：

platforms:
  telegram:
    reply_to_mode: "off"
    guest_mode: false
    allowed_chats: ["-1001234567890"]
    extra:
      disable_link_previews: true

字段说明：

字段	作用
`reply_to_mode`	回复引用模式：`off`、`first`、`all`
`guest_mode`	非 allowlist 群里被明确 @ 时是否允许通过
`allowed_chats`	允许的群、频道或私聊 ID
`extra.disable_link_previews`	禁用 Telegram URL 预览

Telegram token 和 home channel 通常放在 .env 或 onboarding 生成的环境文件里：

TELEGRAM_BOT_TOKEN=填自己的
TELEGRAM_HOME_CHANNEL=填自己的
TELEGRAM_HOME_CHANNEL_THREAD_ID=

第一次绑定 home channel 可在 Telegram 私聊里发：

/sethome

group_sessions_per_user

群聊里是否按用户分离会话：

group_sessions_per_user: true

建议保持 true。如果设成 false，整个群可能共享一个上下文，容易把不同人的任务和偏好混在一起。

skills：技能配置

skills:
  creation_nudge_interval: 15
  external_dirs:
    - ~/.agents/skills

字段说明：

字段	作用
`creation_nudge_interval`	每隔多少轮提醒模型考虑沉淀技能，`0` 表示关闭
`external_dirs`	额外技能目录，只读加载

适合把常用部署、备份、运维流程沉淀成技能。

compression：上下文压缩

Hermes 会在上下文接近模型限制时自动压缩中间历史。

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20
  protect_first_n: 3

说明：

字段	作用
`enabled`	是否自动压缩
`threshold`	到达上下文多少比例时触发
`target_ratio`	压缩后保留多少近期尾部上下文
`protect_last_n`	永远保留最近多少条消息
`protect_first_n`	保护开头多少条非 system 消息

长期 Gateway 建议保持开启。

auxiliary：辅助模型

auxiliary 给后台任务指定更便宜或更快的模型，例如标题、摘要、压缩：

auxiliary:
  compression:
    model: "google/gemini-3-flash-preview"
    provider: "openrouter"

适合把昂贵主模型留给正式回答，把摘要压缩交给便宜模型。

browser 与 tool_loop_guardrails

浏览器工具超时：

browser:
  inactivity_timeout: 120

工具循环护栏：

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: false
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2

这类配置用于防止 Agent 卡在重复失败工具调用里。生产环境建议保留 warning，谨慎开启 hard stop。

security 与 privacy

命令安全扫描：

security:
  tirith_enabled: true
  tirith_path: "tirith"
  tirith_timeout: 5
  tirith_fail_open: true
  redact_secrets: true

隐私脱敏：

privacy:
  redact_pii: false

说明：

字段	作用
`security.tirith_enabled`	启用 tirith 命令安全扫描
`security.redact_secrets`	从工具输出里脱敏 token、密码、API key
`privacy.redact_pii`	给 LLM 上下文里的用户 ID、手机号等做脱敏

stt、tts 与 human_delay

语音转文字：

stt:
  enabled: true
  local:
    model: "base"
  openai:
    model: "whisper-1"

文字转语音：

tts:
  provider: "edge"

消息平台拟人延迟：

human_delay:
  mode: "off"
  min_ms: 800
  max_ms: 2500

Telegram 只想干净高效时，human_delay.mode 用 off 即可。

code_execution 与 delegation

程序化代码执行工具：

code_execution:
  timeout: 300
  max_tool_calls: 50

子代理：

delegation:
  max_iterations: 50
  max_concurrent_children: 3
  max_spawn_depth: 1
  subagent_auto_approve: false

生产环境里，subagent_auto_approve 不建议开。子代理遇到危险命令应该默认停下来等确认。

mcp_servers：MCP 服务

mcp_servers:
  time:
    command: uvx
    args: ["mcp-server-time"]
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

如果要配置 GitHub、Notion、数据库等 MCP，不要把真实 token 写进公开文章。生产配置最好从环境变量读取。

hooks：Shell Hook

Hook 可在工具调用、LLM 调用、会话开始结束等时机执行脚本。

hooks:
  pre_tool_call:
    - matcher: "terminal"
      command: "~/.hermes/agent-hooks/block-rm-rf.sh"
      timeout: 10
hooks_auto_accept: false

适合做：

阻止危险命令。
自动格式化。
注入当前目录上下文。
记录审计日志。

不建议自动接受陌生 hook。非交互 gateway 场景如果需要 hook，要先在测试环境确认。

dashboard

Dashboard 反向代理、OAuth 和公网地址相关配置：

dashboard:
  oauth:
    client_id: ""
    portal_url: ""
  public_url: "https://example.com/hermes"

如果 Dashboard 放到公网，必须有 TLS、认证和访问控制。不要把 --insecure 直接暴露到互联网。

checkpoints

Hermes 可在破坏性文件操作前自动做快照：

checkpoints:
  enabled: true
  max_snapshots: 50

如果支持 /rollback，这能救回一部分误改文件。但它不是完整备份，服务器级备份仍然要做。

session_reset

Gateway 会话自动重置：

session_reset:
  mode: "both"
  idle_minutes: 1440
  at_hour: 4

字段说明：

字段	作用
`mode`	`both`、`idle`、`daily`、`none`
`idle_minutes`	空闲多少分钟后重置
`at_hour`	每天几点重置

长期 Telegram bot 建议开启会话重置，避免旧上下文无限污染新任务。

timezone、prefill、quick_commands

时区：

timezone: "Asia/Shanghai"

每次 API 调用注入的临时消息文件：

prefill_messages_file: "~/.hermes/prefill.json"

快速命令：

quick_commands:
  status:
    type: exec
    command: "systemctl --user status hermes-gateway.service --no-pager"

quick_commands 会绕过 Agent loop，适合固定查询，不适合高风险写操作。

model_aliases 与 personalities

模型别名：

model_aliases:
  opus:
    model: claude-opus-4-6
    provider: anthropic
  local:
    model: "qwen3"
    provider: custom
    base_url: "http://127.0.0.1:1234/v1"

自定义人格：

agent:
  personalities:
    daily: "你是一个中文日常助手，回答简洁、直接、少废话。"
    ops: "你是一个严谨的运维助手，先确认风险，再给出可执行步骤。"

不确定字段怎么处理

Hermes 更新很快，遇到不确定字段按这个顺序处理：

查当前版本的官方配置参考。
查当前版本的 cli-config.yaml.example。
修改前备份 config.yaml。
每次只改一小段。
重启 gateway 后看日志。
没有被当前版本识别或没有行为变化的字段，不要长期保留。

配置文件最好的状态不是“参数最多”，而是“每个参数都知道为什么存在”。

修改前先备份

总体结构

model：模型与供应商

providers：供应商超时和模型例外

provider_routing 与 openrouter

terminal：命令执行环境

display：显示、进度和安静模式

streaming：Gateway 流式输出

agent：Agent 行为

platform_toolsets：各平台工具集

platforms.telegram：Telegram 平台参数

group_sessions_per_user

skills：技能配置

compression：上下文压缩

auxiliary：辅助模型

browser 与 tool_loop_guardrails

security 与 privacy

stt、tts 与 human_delay

code_execution 与 delegation

mcp_servers：MCP 服务

hooks：Shell Hook

dashboard

checkpoints

session_reset

timezone、prefill、quick_commands

model_aliases 与 personalities

推荐 Telegram 安静配置

不确定字段怎么处理