适用版本: 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 大块逐字段注释, 每块给默认值 / 适用场景 / 改后效果三件套。读完后你能:看懂 90% 配置项的真实作用知道哪些配置可以小白不碰 (默认就好)知道哪些配置改 1 行能解锁 80% 定制能力一、model 块: 你跟哪个 AI 说话model:default:MiniMax-M3provider:minimax-cnbase_url:https://api.minimaxi.com/anthropiccontext_length:10485764 个字段, 决定整个 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不是/anthropiccontext_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 池, 给同一个请求发多个 APIfallback_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:51200backend: local— 跑在沙箱本地, 默认backend: docker— 跑在 Docker 容器, 隔离更安全backend: modal/singularity/daytona— 跑在云端 serverlesscontainer_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:2000checkpoints.enabled: false— 默认不存 checkpoint (省磁盘)max_file_size_mb: 10— 单文件最大读 10MBtool_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:52 次连续失败就告警, 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:5m99% 用户不用动。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 个辅助服务 providerauxiliary: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:ctrlbmax_recording_seconds:120beep_enabled:truetts.provider: edge— 默认 Microsoft Edge TTS (免费)老板场景: 改tts.provider: openai用 OpenAI TTS (质量好但花钱)反编造铁律: 老板的 PAI 语音合成不要用 edge TTS (中文发音不准, 改provider: openai或xai)十五、human_delay / context / memory: 人性化 上下文 记忆human_delay:mode:offmin_ms:800max_ms:2500context:engine:compressormemory:memory_enabled:trueuser_profile_enabled:truememory_char_limit:100000user_char_limit:50000nudge_interval:10flush_min_turns:6human_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:90delegation.max_concurrent_children: 3— 老板拍板3 子代理并行max_spawn_depth: 1— 子代理不能再 spawn (老板拍板防失控)curator.interval_hours: 168— 7 天整理一次 skill (1 周)十七、cron / kanban / code_execution / logging / mcp_servers: 任务调度 MCPcron: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-supabaselatest,--project-ref...,--read-only]env:{SUPABASE_ACCESS_TOKEN:...,SUPABASE_DB_PASSWORD:...}timeout:120connect_timeout:60MCP 是 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 4model:default:claude-sonnet-4provider:openrouterbase_url:https://openrouter.ai/api/v1改 2: 接管老板的 PC Chromebrowser:cdp_url:http://[::1]:9222engine:auto改 3: 给视觉用更稳的 GPT-4oauxiliary:vision:provider:openaimodel:gpt-4o改 4: 扩 memory 到 10 万字符memory:memory_char_limit:100000user_char_limit:50000改 5: 加 Supabase MCPmcp_servers:supabase:command:/root/.hermes/node/bin/npxargs:[-y,supabase/mcp-server-supabaselatest,--project-ref你的 ref,--read-only]env:SUPABASE_ACCESS_TOKEN:paste-your-token-hereSUPABASE_DB_PASSWORD:paste-your-password-heretimeout:120connect_timeout:60改完配置后必做 3 件事校验 YAML 语法(改坏会启动失败)python3-cimport yaml; yaml.safe_load(open(/root/.hermes/config.yaml))重启 Gatewayhermes gateway restart验证生效hermes config show总结~/.hermes/config.yaml是 Hermes Agent 的中央指挥部。17 大块各管一摊:model— AI 大脑providers/fallback_providers— 备胎管理toolsets— 工具集白名单agent— Agent 行为核心 (17 字段)terminal— 命令在哪儿跑web— Web 抓取后端browser— 老板 PC Chrome 接管checkpoints/tool_output— 大文件保护tool_loop_guardrails— 防死循环compression/prompt_caching— 上下文压缩openrouter/bedrock— 多 provider 微调auxiliary— 12 个辅助服务display— TUI 显示tts/stt/voice— 语音human_delay/context/memory— 人性化 上下文 记忆delegation/goals/skills/curator— 子代理cron/kanban/code_execution/logging/mcp_servers— 任务调度 MCP