适用版本: Hermes Agent v24+ (2026-06 升级版)
配置文件位置: ~/.hermes/config.yaml (14 KB, _config_version: 24)
适用读者: 想深度定制 Hermes Agent 行为的小白到中级用户
阅读时长: 25 分钟
关键提示: 改完配置后必须 hermes gateway restart 才生效

写在前面: 为什么要读 config.yaml

~/.hermes/config.yaml 是 Hermes Agent 的"中央指挥部"。它决定了:

• 你的对话用哪个 AI 模型 (model 块)

• 你的 Agent 能调多少轮 (agent.max_turns)

• 你的终端跑在哪里 (terminal.backend)

• 你的浏览器怎么接管老板的 PC Chrome (browser.cdp_url)

• 你的 MCP 服务怎么连数据库 (mcp_servers.*)

700 行的配置, 99% 用默认值就能跑。但只要你想深度定制 1 项, 必须先读懂这块的设计意图。这是 Hermes Agent 配置设计的核心铁律 — 一切默认值都考虑过"小白能跑"和"老炮能改"的双向兼容。

本文按 17 大块逐字段注释, 每块给"默认值 / 适用场景 / 改后效果"三件套。读完后你能:

1. 看懂 90% 配置项的真实作用

2. 知道哪些配置可以"小白不碰" (默认就好)

3. 知道哪些配置改 1 行能解锁 80% 定制能力

一、model 块: 你跟哪个 AI 说话

model:
  default: MiniMax-M3
  provider: minimax-cn
  base_url: https://api.minimaxi.com/anthropic
  context_length: 1048576

4 个字段, 决定整个 Agent 的"大脑"。

default: 模型 ID

• 默认: MiniMax-M3

• 适用: 默认 provider 下的主模型

• 改后: 切到别的模型, 比如 claude-sonnet-4 / gpt-4o / 本地 ollama/llama3

• 反编造铁律: 不要写"测试"或"dev"这类含糊模型名, 模型不存在会启动失败

provider: 模型提供方

• 默认: minimax-cn

• 适用: 默认走 MiniMax 的 API endpoint

• 改后: openrouter / anthropic / openai / bedrock 走对应平台

• 实战: 切到 openrouter 时建议 openrouter.min_coding_score: 0.65 过滤低质量模型

base_url: API endpoint

• 默认: https://api.minimaxi.com/anthropic

• 适用: MiniMax 用 Anthropic 兼容协议

• 改后: 指向自部署的 Ollama (http://localhost:11434/v1) 或 LiteLLM proxy

• 关键坑: OpenRouter 的 base_url 是 https://openrouter.ai/api/v1 不是 /anthropic

context_length: 上下文窗口

• 默认: 1048576 (1M tokens, MiniMax M3 旗舰)

• 适用: 1M 上下文能塞下整个代码库

• 改后: 切到 8K / 32K / 128K / 200K 不同模型时同步调整

• 反编造铁律: 改 context_length 必须跟模型真实上限匹配, 不要改大 (会"幻觉"以为有 1M)

二、providers / fallback_providers / credential_pool_strategies: 备胎管理

providers: {}
fallback_providers: []
credential_pool_strategies: {}

3 块都是 {} 或 [] 空, 小白用户不用动。

老炮场景:

• providers: 多 provider 池, 给同一个请求发多个 API

• fallback_providers: 主 provider 失败时自动切换的备胎列表

• credential_pool_strategies: 多 key 轮询/权重分配, 防单 key 限流

什么时候改: 你跑生产 cron 高频调用, 单 key 5 分钟 60 次触限, 必须配 key 池

三、toolsets: 启用的工具集白名单

toolsets:
- hermes-cli

• 默认: hermes-cli (CLI 模式)

• 适用: 跑 cron / no_agent 模式只用 CLI 工具

• 改后: terminal / file / web / search 等可加多个

• 反编造铁律: 加 toolset 必先 hermes tools list 看实际名字, 不存在会报 Unknown toolset

四、agent 块: Agent 行为核心

agent:
  max_turns: 90
  gateway_timeout: 1800
  restart_drain_timeout: 180
  api_max_retries: 3
  service_tier: ''
  tool_use_enforcement: auto
  gateway_timeout_warning: 900
  clarify_timeout: 600
  gateway_notify_interval: 180
  gateway_auto_continue_freshness: 3600
  image_input_mode: auto
  disabled_toolsets: []
  verbose: false
  reasoning_effort: medium
  personalities:
    helpful: You are a helpful, friendly AI assistant.
    concise: You are a concise assistant. Keep responses brief and to the point.
    technical: You are a technical expert. Provide detailed, accurate technical information.
    creative: You are a creative assistant. Think outside the box and offer innovative solutions.
    teacher: You are a patient teacher. Explain concepts clearly with examples.
    kawaii: "You are a kawaii assistant! Use cute expressions like (◕‿◕✿) ★ ♪ and ~!"
    # ... 还有 catgirl / pirate / shakespeare / surfer / noir / uwu / philosopher / hype 12 种人格

17 字段, 决定 Agent 怎么"干活"。

关键 4 字段 (90% 用户必懂)

max_turns: 90 — Agent 一次会话最大轮次

• 默认 90 (够日常用)

• 改小: 限制 Agent “一直想” (省 token, 但复杂任务会半路断)

• 改大: 100-200 给"老板说写完整篇 CSDN"这种长任务

gateway_timeout: 1800 — Gateway 30 分钟硬超时

• 默认 1800s (30 min)

• cron job 跑超出 30 min 会被杀

• 改大: 6000+ 给"老板跑全量数据迁移" (不推荐, 应该拆任务)

api_max_retries: 3 — API 调用失败重试

• 默认 3 次

• 改大: 5-10 给"老板跑生产 cron 网络抖"

• 改小: 0-1 给"测试场景快速失败"

reasoning_effort: medium — 模型思考深度

• 默认 medium / 可选 lowmediumhighmax

• 改 low: 快但笨, 给"老板 cron 跑 1 行 fetch"

• 改 high / max: 慢但聪明, 给"老板要写完整架构方案"

personalities: 12 种人格切换

personalities.<name> 字段定义人格的 system prompt, 通过 /personality kawaii 切换。老板场景常用:

• concise: 老板喜欢直接简洁 (默认推荐)

• technical: 写代码 / 看架构时用

• teacher: 教新人时用

• kawaii / catgirl / pirate: 老板玩, 不影响业务

五、terminal 块: 命令在哪儿跑

terminal:
  backend: local
  modal_mode: auto
  cwd: .
  timeout: 180
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200

• backend: local — 跑在沙箱本地, 默认

• backend: docker — 跑在 Docker 容器, 隔离更安全

• backend: modal / singularity / daytona — 跑在云端 serverless

• container_memory: 5120 (5GB) — Docker 容器内存

• container_disk: 51200 (50GB) — Docker 容器磁盘

• 反编造铁律: 改 docker_image 必须镜像存在 (本地 docker pull 验证), 不存在会启动失败

六、web 块: Web 抓取后端

web:
  backend: ''
  search_backend: ''
  extract_backend: ''

3 字段默认空, 意思是用默认的 Firecrawl / Apify 后端。

老炮场景:

• backend: 'apify' — 强制 Apify (抓公开站)

• backend: 'firecrawl' — 强制 Firecrawl (抓 SPA / JS 渲染)

• search_backend: 'brave' / extract_backend: 'jina' — 拆分搜索 vs 提取后端

七、browser 块: 老板的 PC Chrome 接管

browser:
  inactivity_timeout: 120
  command_timeout: 30
  record_sessions: false
  allow_private_urls: false
  engine: auto
  cdp_url: ''
  dialog_policy: must_respond
  dialog_timeout_s: 300
  camofox:
    managed_persistence: false
    user_id: ''

最关键字段: ****cdp_url。

• cdp_url: '' — 默认 (沙箱自带 Chromium)

• cdp_url: 'http://[::1]:9222' — 接管老板 PC Chrome 调试端口

• 适用: 老板要"我本地浏览器登录 Boss/猎聘"场景

• 反编造铁律: cdp_url 必须用 IPv6 [::1]:9222, IPv4 127.0.0.1:9222 不通 (老板 PC Chrome 9222 限制)

engine: auto 默认智能选 Playwright / Camofox; 改 'camofox' 用 stealth 反爬方案。

八、checkpoints / file_read_max_chars / tool_output: 大文件保护

checkpoints:
  enabled: false
  max_snapshots: 20
  max_total_size_mb: 500
  max_file_size_mb: 10
  auto_prune: true
  retention_days: 7
file_read_max_chars: 500000
tool_output:
  max_bytes: 200000
  max_lines: 5000
  max_line_length: 2000

• checkpoints.enabled: false — 默认不存 checkpoint (省磁盘)

• max_file_size_mb: 10 — 单文件最大读 10MB

• tool_output.max_bytes: 200000 — 工具输出截 200KB

• 反编造铁律: 改大这些值会撑爆磁盘, 不要"为方便"全开

九、tool_loop_guardrails: 防 Agent 死循环

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

2 次连续失败就告警, 5 次就硬停。

老板场景:

• warn_after.exact_failure: 2 — 同一 tool 失败 2 次给告警

• hard_stop_after.exact_failure: 5 — 失败 5 次直接停 (防 token 烧光)

十、compression / prompt_caching: 上下文压缩 + 缓存

compression:
  enabled: true
  threshold: 0.85
  target_ratio: 0.2
  protect_last_n: 20
  protect_first_n: 3
prompt_caching:
  cache_ttl: 5m

99% 用户不用动。

• compression.enabled: true — 对话超 85% 上下文自动压缩

• prompt_caching.cache_ttl: 5m — 5 分钟内的相同 prompt 走缓存 (老板省 token)

十一、openrouter / bedrock: 多 provider 微调

openrouter:
  response_cache: true
  response_cache_ttl: 300
  min_coding_score: 0.65
bedrock:
  region: ''
  discovery:
    enabled: true
    refresh_interval: 3600

老板场景: 用 OpenRouter 跑 cron 时建议 min_coding_score: 0.65 过滤低质量模型 (避免"用 Qwen 7B 写完整篇 CSDN"翻车)。

十二、auxiliary 块: 12 个辅助服务 provider

auxiliary:
  vision: {provider: auto, model: '', timeout: 120, ...}
  web_extract: {provider: auto, model: '', timeout: 360, ...}
  compression: {provider: auto, model: '', timeout: 120, ...}
  skills_hub: {provider: auto, model: '', timeout: 30, ...}
  approval: {provider: auto, model: '', timeout: 30, ...}
  mcp: {provider: auto, model: '', timeout: 30, ...}
  title_generation: {provider: auto, model: '', timeout: 30, ...}
  triage_specifier: {provider: auto, model: '', timeout: 120, ...}
  kanban_decomposer: {provider: auto, model: '', timeout: 180, ...}
  profile_describer: {provider: auto, model: '', timeout: 60, ...}
  curator: {provider: auto, model: '', timeout: 600, ...}

12 个 provider 全部默认 auto (用主模型跑)。

老炮场景: 给特定辅助任务配独立模型, 比如:

auxiliary:
  vision:
    provider: openai
    model: gpt-4o
  curator:    # 自动整理 skill 的后台任务
    provider: ollama
    model: llama3:8b

十三、display 块: TUI 显示定制

display:
  compact: false
  personality: kawaii
  language: en
  show_reasoning: false
  show_cost: false
  skin: default
  tui_status_indicator: kaomoji

老板场景: 改 language: zh 让 TUI 显示中文; 改 personality: concise 让默认人格简洁。

十四、tts / stt / voice: 语音配置

tts:
  provider: edge
  edge:
    voice: en-US-AriaNeural
stt:
  enabled: true
  provider: local
  local:
    model: base
voice:
  record_key: ctrl+b
  max_recording_seconds: 120
  beep_enabled: true

• tts.provider: edge — 默认 Microsoft Edge TTS (免费)

• 老板场景: 改 tts.provider: openai 用 OpenAI TTS (质量好但花钱)

• 反编造铁律: 老板的 PAI 语音合成不要用 edge TTS (中文发音不准, 改 provider: openai 或 xai)

十五、human_delay / context / memory: 人性化 + 上下文 + 记忆

human_delay:
  mode: 'off'
  min_ms: 800
  max_ms: 2500
context:
  engine: compressor
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 100000
  user_char_limit: 50000
  nudge_interval: 10
  flush_min_turns: 6

• human_delay.mode: 'off' — 关闭"模拟人类打字延迟"

• memory.memory_char_limit: 100000 — 老板场景扩到 10 万字符 (老板 6/3 拍板)

• memory.user_char_limit: 50000 — 用户画像 5 万字符

十六、delegation / goals / skills / curator: 子代理 + 目标 + 技能

delegation:
  max_iterations: 50
  child_timeout_seconds: 600
  max_concurrent_children: 3
  max_spawn_depth: 1
  orchestrator_enabled: true
  subagent_auto_approve: false
goals:
  max_turns: 20
skills:
  external_dirs: []
  template_vars: true
  inline_shell: false
curator:
  enabled: true
  interval_hours: 168
  min_idle_hours: 2
  stale_after_days: 30
  archive_after_days: 90

• delegation.max_concurrent_children: 3 — 老板拍板"3 子代理并行"

• max_spawn_depth: 1 — 子代理不能再 spawn (老板拍板防失控)

• curator.interval_hours: 168 — 7 天整理一次 skill (1 周)

十七、cron / kanban / code_execution / logging / mcp_servers: 任务调度 + MCP

cron:
  wrap_response: true
  max_parallel_jobs: null
kanban:
  dispatch_in_gateway: true
  failure_limit: 2
code_execution:
  mode: project
  timeout: 300
  max_tool_calls: 50
logging:
  level: INFO
  max_size_mb: 5
mcp_servers:
  postgres:
    command: /root/.hermes/node/bin/node
    args: [/root/.hermes/mcp/postgres-wrapper.mjs]
    env: {PGHOST: 192.168.11.1, ...}
    timeout: 60
  supabase:
    command: /root/.hermes/node/bin/npx
    args: [-y, '@supabase/mcp-server-supabase@latest', --project-ref=..., --read-only]
    env: {SUPABASE_ACCESS_TOKEN: ..., SUPABASE_DB_PASSWORD: ...}
    timeout: 120
    connect_timeout: 60

MCP 是 Hermes Agent 的"插件"机制。

老板场景:

• mcp_servers.postgres — 连本地 Postgres (192.168.11.1:5432)

• mcp_servers.supabase — 连 Supabase 远程 DB (kyfimfqqokbcypnaxvwh)

• 反编造铁律: MCP server 改后必须 hermes gateway restart, 不重启不生效

老板实战 5 件套 (重点)

下面是老板真在生产用的 5 个配置改法, 改完能解锁 80% 定制能力:

改 1: 切到 Claude Sonnet 4

model:
  default: claude-sonnet-4
  provider: openrouter
  base_url: https://openrouter.ai/api/v1

改 2: 接管老板的 PC Chrome

browser:
  cdp_url: 'http://[::1]:9222'
  engine: auto

改 3: 给视觉用更稳的 GPT-4o

auxiliary:
  vision:
    provider: openai
    model: gpt-4o

改 4: 扩 memory 到 10 万字符

memory:
  memory_char_limit: 100000
  user_char_limit: 50000

改 5: 加 Supabase MCP

mcp_servers:
  supabase:
    command: /root/.hermes/node/bin/npx
    args: [-y, '@supabase/mcp-server-supabase@latest', --project-ref=<你的 ref>, --read-only]
    env:
      SUPABASE_ACCESS_TOKEN: <paste-your-token-here>
      SUPABASE_DB_PASSWORD: <paste-your-password-here>
    timeout: 120
    connect_timeout: 60

改完配置后必做 3 件事

1. 校验 YAML 语法 (改坏会启动失败)

   python3 -c "import yaml; yaml.safe_load(open('/root/.hermes/config.yaml'))"
   

2. 重启 Gateway

   hermes gateway restart
   

3. 验证生效

   hermes config show
   

总结

~/.hermes/config.yaml 是 Hermes Agent 的"中央指挥部"。17 大块各管一摊:

1. model — AI 大脑

2. providers / fallback_providers — 备胎管理

3. toolsets — 工具集白名单

4. agent — Agent 行为核心 (17 字段)

5. terminal — 命令在哪儿跑

6. web — Web 抓取后端

7. browser — 老板 PC Chrome 接管

8. checkpoints / tool_output — 大文件保护

9. tool_loop_guardrails — 防死循环

10. compression / prompt_caching — 上下文压缩

11. openrouter / bedrock — 多 provider 微调

12. auxiliary — 12 个辅助服务

13. display — TUI 显示

14. tts / stt / voice — 语音

15. human_delay / context / memory — 人性化 + 上下文 + 记忆

16. delegation / goals / skills / curator — 子代理

17. cron / kanban / code_execution / logging / mcp_servers — 任务调度 + MCP