Hermes Agent 配置文件 \~/\.hermes/config\.yaml 完整解读-尧图网络科技

$Hermes Agent 配置文件 \~/\.hermes/config\.yaml 完整解读$

适用版本: 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: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 的"插件"机制。