适用版本: 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-M3provider:minimax-cnbase_url:https://api.minimaxi.com/anthropiccontext_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:90gateway_timeout:1800restart_drain_timeout:180api_max_retries:3service_tier:''tool_use_enforcement:autogateway_timeout_warning:900clarify_timeout:600gateway_notify_interval:180gateway_auto_continue_freshness:3600image_input_mode:autodisabled_toolsets:[]verbose:falsereasoning_effort:mediumpersonalities: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:localmodal_mode:autocwd:.timeout:180docker_image:nikolaik/python-nodejs:python3.11-nodejs20container_cpu:1container_memory:5120container_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:120command_timeout:30record_sessions:falseallow_private_urls:falseengine:autocdp_url:''dialog_policy:must_responddialog_timeout_s:300camofox:managed_persistence:falseuser_id:''

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

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

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

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

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

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

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

checkpoints:enabled:falsemax_snapshots:20max_total_size_mb:500max_file_size_mb:10auto_prune:trueretention_days:7file_read_max_chars:500000tool_output:max_bytes:200000max_lines:5000max_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:truehard_stop_enabled:falsewarn_after:exact_failure:2same_tool_failure:3idempotent_no_progress:2hard_stop_after:exact_failure:5same_tool_failure:8idempotent_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:truethreshold:0.85target_ratio:0.2protect_last_n:20protect_first_n:3prompt_caching:cache_ttl:5m

99% 用户不用动。

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

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

十一、openrouter / bedrock: 多 provider 微调

openrouter:response_cache:trueresponse_cache_ttl:300min_coding_score:0.65bedrock:region:''discovery:enabled:truerefresh_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:openaimodel:gpt-4ocurator:# 自动整理 skill 的后台任务provider:ollamamodel:llama3:8b

十三、display 块: TUI 显示定制

display:compact:falsepersonality:kawaiilanguage:enshow_reasoning:falseshow_cost:falseskin:defaulttui_status_indicator:kaomoji

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

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

tts:provider:edgeedge:voice:en-US-AriaNeuralstt:enabled:trueprovider:locallocal:model:basevoice:record_key:ctrl+bmax_recording_seconds:120beep_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:800max_ms:2500context:engine:compressormemory:memory_enabled:trueuser_profile_enabled:truememory_char_limit:100000user_char_limit:50000nudge_interval:10flush_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:50child_timeout_seconds:600max_concurrent_children:3max_spawn_depth:1orchestrator_enabled:truesubagent_auto_approve:falsegoals:max_turns:20skills:external_dirs:[]template_vars:trueinline_shell:falsecurator:enabled:trueinterval_hours:168min_idle_hours:2stale_after_days:30archive_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:truemax_parallel_jobs:nullkanban:dispatch_in_gateway:truefailure_limit:2code_execution:mode:projecttimeout:300max_tool_calls:50logging:level:INFOmax_size_mb:5mcp_servers:postgres:command:/root/.hermes/node/bin/nodeargs:[/root/.hermes/mcp/postgres-wrapper.mjs]env:{PGHOST:192.168.11.1,...}timeout:60supabase:command:/root/.hermes/node/bin/npxargs:[-y,'@supabase/mcp-server-supabase@latest',--project-ref=...,--read-only]env:{SUPABASE_ACCESS_TOKEN:...,SUPABASE_DB_PASSWORD:...}timeout:120connect_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-4provider:openrouterbase_url:https://openrouter.ai/api/v1

改 2: 接管老板的 PC Chrome

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

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

auxiliary:vision:provider:openaimodel:gpt-4o

改 4: 扩 memory 到 10 万字符

memory:memory_char_limit:100000user_char_limit:50000

改 5: 加 Supabase MCP

mcp_servers:supabase:command:/root/.hermes/node/bin/npxargs:[-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:120connect_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