装完就懵？一份文件告诉你 Hermes 的每个配置到底管什么

Fri, 22 May 2026 10:00:00 +0800

开篇导语

装好 Hermes Agent，~/.hermes/ 下一堆文件，config.yaml、.env、SOUL.md… 哪个改哪个不改，新手完全懵。

第一章：你的 ~/.hermes/ 长什么样

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


~/.hermes/
├── 核心配置（3个文件）
│ ├── config.yaml # 主配置文件（300+ 行）
│ ├── .env # API 密钥和凭证（405 行，18+ 供应商）
│ └── SOUL.md # Agent 个性定义（每轮加载，改了立生效）
│
├── 数据存储
│ ├── sessions/ # 历史会话 JSON 文件
│ ├── memories/ # 记忆文件（MEMORY.md、USER.md）
│ ├── kanban/ # 看板任务和日志
│ ├── cron/ # 定时任务输出
│ ├── logs/ # 日志文件（agent.log、errors.log）
│ ├── state.db # SQLite 数据库（会话索引、状态）
│ └── checkpoints/ # 文件系统快照（/rollback 使用）
│
├── 扩展层
│ ├── skills/ # 技能目录（SKILL.md + 脚本/模板）
│ ├── scripts/ # 自定义脚本
│ ├── plugins/ # 插件目录（MCP 服务器、平台适配器）
│ └── hooks/ # 事件钩子脚本
│
├── Profile 隔离
│ └── profiles/ # 多配置并行目录
│ ├── blog-writer/ # 博客写作 profile
│ ├── reviewer/ # 审核 profile
│ └── yuan/ # 个人 AI profile
│
└── 其他
 ├── auth.json # 认证状态（OAuth token）
 ├── kanban.db # 看板 SQLite 数据库
 ├── memory.db # 记忆系统数据库
 └── .update_check # 版本检查缓存

每个 profile（如 blog-writer）是完整的并行 ~/.hermes/，包含独立的 config.yaml、.env、SOUL.md、state.db、sessions/、logs/ 等。

第二章：三大核心文件（新手必读）

文件	作用	怎么改
`config.yaml`	所有行为参数（模型、工具、终端、压缩、看板等）	编辑文本，改后立即生效（部分需重启 gateway）
`.env`	API 密钥和平台凭证	`export KEY=xxx` 或直接编辑，改后立即生效
`SOUL.md`	Agent 个性、称呼、反驳机制	编辑 Markdown，每轮对话重新加载，不需要重启

config.yaml 核心字段速查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


model:
 default: glm-5.1  # 默认模型
 provider: zai  # 默认供应商
 api_key: xxx  # API 密钥（也可用 .env）
 context_length: 204800 # 上下文长度（tokens）
 max_tokens: 131072 # 最大输出（tokens）

agent:
 max_turns: 90 # 最大对话轮数
 gateway_timeout: 1800 # Gateway 空闲超时（秒）
 reasoning_effort: medium  # 推理强度
 tool_use_enforcement: auto # 工具调用强制策略

terminal:
 backend: local  # 终端后端：local/docker/ssh/modal
 timeout: 180 # 命令超时（秒）

compression:
 enabled: true # 上下文压缩
 threshold: 0.5 # 触发阈值（50%）
 target_ratio: 0.2 # 压缩到阈值比例

toolsets:
 - hermes-cli  # 启用的工具集
 - kanban

.env 环境变量全表（按供应商分类）

供应商	必须环境变量	可选环境变量	备注
OpenRouter	`OPENROUTER_API_KEY`		路由到多模型
Anthropic	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_TOKEN`		Claude 模型
OpenAI	`OPENAI_API_KEY`		GPT、o1 系列
Z.AI / GLM	`ZAI_API_KEY` 或 `GLM_API_KEY`		智谱 GLM 模型
Kimi	`KIMI_API_KEY` 或 `KIMI_CN_API_KEY`		月之暗面
MiniMax	`MINIMAX_API_KEY` 或 `MINIMAX_CN_API_KEY`		国产大模型
DeepSeek	`DEEPSEEK_API_KEY`		深度求索
Google / Gemini	`GOOGLE_API_KEY` 或 `GEMINI_API_KEY`		Gemini 系列
xAI	`XAI_API_KEY`		Grok 模型
Bedrock	`AWS_BEARER_TOKEN_BEDROCK`	`AWS_SECRET`	AWS 托管

平台凭证（消息平台）：

微信：WEIXIN_TOKEN、WEIXIN_ACCOUNT_ID
飞书：FEISHU_APP_ID、FEISHU_APP_SECRET
Telegram：TELEGRAM_BOT_TOKEN
Discord：DISCORD_BOT_TOKEN

SOUL.md 实战框架

SOUL.md 定义 Agent 行为，核心六要素：

要素	作用	示例
身份定位	谁是 Agent，谁是用户	“我是忞的自主执行者和思考伙伴”
核心职责	Agent 要做什么	“任务执行、思考伙伴、信息管理、风险预警”
个性特点	风格和语气	“专业、简洁、贴心、高效、可靠、直率”
执行原则	怎么干活	“先执行后汇报，主动提醒，结果导向”
反驳机制	何时反对用户	“必须反驳 + 必须带证据 + 替代方案”
沟通风格	怎么说话	“简洁、结构化、结果先行、主动、坦诚”

默认 SOUL vs 深度定制 SOUL 对比：

行为	默认 SOUL	深度定制 SOUL
称呼	“用户”	“忞”
语言	中英文混合	始终中文
反驳	不会反驳	强制反驳（带证据）
问责	不追问	主动追问输出是否采纳
风格	标准客服	专业伙伴

第三章：config.yaml 全字段速查

model — 模型配置

字段	默认值	常见调法	踩坑提示
`default`	""	`glm-5.1`、`openrouter/anthropic/claude-sonnet-4`	空字符串时走 auto-detect
`provider`	""	`zai`、`openrouter`、`anthropic`	`base_url` 指定时 provider 可选
`base_url`	""	OpenAI 兼容端点	必须以 `https://` 或 `http://` 开头
`api_key`	""	密钥（或用环境变量）	优先级：`config.yaml` > `.env`
`context_length`	（模型决定）	`128000`（Claude）、`200000`（GLM）	超出模型实际上限会报错
`max_tokens`	（模型决定）	`4096`（短响应）、`131072`（长输出）	截断时 `finish_reason='length'`

fallback_providers — 故障自动切换

1
2
3
4
5
6
7


fallback_providers:
 - provider: zai
 model: glm-4.7
 base_url: https://open.bigmodel.cn/api/coding/paas/v4
 api_key: ${GLM_API_KEY}
 context_length: 200000
 max_tokens: 65536

触发条件	行为
429（Rate Limit）	切换到 fallback_providers 下一个
503（服务不可用）	切换到下一个
连接失败	切换到下一个

踩坑提示：fallback 不支持轮询（round-robin），只会从上到下尝试一次。需要配置多个 fallback 条目以实现多级切换。

auxiliary — 辅助模型（视觉 / 压缩 / 搜索 / 抽取）

任务	provider 默认值	model 默认值	timeout
`vision`	auto	“"（自动）	120s
`web_extract`	auto	"”	360s
`compression`	auto	""	120s
`session_search`	auto	""	30s
`skills_hub`	auto	""	30s
`approval`	auto	""	30s
`mcp`	auto	""	30s
`title_generation`	auto	""	30s
`triage_specifier`	auto	""	120s
`curator`	auto	""	600s

provider: auto 时，Hermes 自动选择最佳可用供应商（OpenRouter → Nous → Codex → 自定义）。

踩坑提示：视觉任务（vision）超时需设为 120s 或更高，图片下载需要额外时间。

agent — 行为参数

字段	默认值	常见调法	踩坑提示
`max_turns`	90	`20`（短任务）、`200`（长推理）	超限后停止，无错误提示
`reasoning_effort`	medium	low / medium / high	某些模型不支持此参数
`tool_use_enforcement`	auto	auto / true / false / [“gpt”, “codex”]	强制模型调用工具而非描述动作
`image_input_mode`	auto	native / text	`native` 直接传图片，`text` 先用 vision_analyze 描述
`gateway_timeout`	1800	`3600`（长任务）、`600`（短任务）	空闲超时，不是任务总时长
`gateway_notify_interval`	180	`600`（长任务反馈）、`0`（关闭）	周期性"仍工作中"通知间隔

terminal — 终端后端

字段	默认值	可选值	踩坑提示
`backend`	local	local / docker / ssh / modal / daytona	Docker 需要容器运行时
`timeout`	180	`600`（长任务）	超时后进程被 SIGTERM
`auto_source_bashrc`	true	true / false	`false` 时只读 `~/.bash_profile`
`persistent_shell`	true	true / false	SSH 后端自动持久化

容器资源限制（适用于 docker、modal、daytona）：

字段	默认值	说明
`container_cpu`	1	CPU 核心数
`container_memory`	5120	内存（MB），默认 5GB
`container_disk`	51200	磁盘（MB），默认 50GB

compression — 上下文压缩策略

字段	默认值	说明
`enabled`	true	是否启用压缩
`threshold`	0.5	触发阈值（50% 上下文使用率）
`target_ratio`	0.2	压缩到阈值比例（保留 20%）
`protect_last_n`	20	保留最近 N 条消息不压缩
`protect_first_n`	3	保留开篇 N 条非系统消息

踩坑提示：压缩发生在每轮对话结束，不是实时压缩。protect_first_n 包含在 protect_last_n 之外。

toolsets / platform_toolsets — 工具集配置

平台	默认工具集
cli（命令行）	browser、clarify、code_execution、cronjob、delegation、file、memory、session_search、skills、terminal、todo、tts、vision
telegram	hermes-telegram
discord	hermes-discord
whatsapp	hermes-whatsapp

禁用工具集：在 config.yaml 中设置 disabled_toolsets: ["vision", "tts"]。

踩坑提示：platform_toolsets 在 tools_config.py 中读取，不是直接在 config.py 中。

smart_model_routing — 简单问题用便宜模型

⚠️ 当前版本（0.14.0）此配置键未实现。配置文件中存在，但源码中无读取逻辑。

官方文档提及该功能，但目前需通过 Shell Hook 自实现（见 memory 记录）。

session_reset — 会话自动重置

字段	默认值	说明
`mode`	both	idle（空闲）、daily（每日）、both（两者）
`idle_minutes`	1440	空闲 N 分钟后重置
`at_hour`	4	每日 N 点强制重置

踩坑提示：会话重置在 gateway 模式下生效，CLI 模式不受影响。

checkpoints — 文件系统快照

字段	默认值	说明
`enabled`	false	是否启用
`max_snapshots`	20	每个项目最多快照数
`max_total_size_mb`	500	总大小上限（MB）
`max_file_size_mb`	10	单文件跳过阈值
`auto_prune`	true	自动清理过期快照
`retention_days`	7	保留天数

踩坑提示：enabled 默认 false，需要主动开启。/rollback 命令依赖此功能。

mcp_servers — MCP 服务器连接

1
2
3
4
5
6


mcp_servers:
 browser-use:
 url: https://api.browser-use.com/v3/mcp
 headers:
 x-browser-use-api-key: ${BROWSER_USE_API_KEY}
 timeout: 300

字段	必填	说明
`url`	是	MCP 服务器地址
`headers`	否	自定义 HTTP 头
`timeout`	否	连接超时（秒）

plugins — 插件启用 / 禁用

1
2
3
4
5
6


plugins:
 enabled:
 - disk-cleanup
 - rtk-rewrite
 disabled:
 - some-plugin

踩坑提示：插件需先安装在 ~/.hermes/plugins/ 目录，否则找不到。

第四章：.env 环境变量全表（按供应商分类）

供应商	必须变量	可选变量
OpenRouter	`OPENROUTER_API_KEY`
Anthropic	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_TOKEN`
OpenAI	`OPENAI_API_KEY`
Z.AI / GLM	`ZAI_API_KEY` 或 `GLM_API_KEY`
Kimi	`KIMI_API_KEY` 或 `KIMI_CN_API_KEY`
MiniMax	`MINIMAX_API_KEY` 或 `MINIMAX_CN_API_KEY`
DeepSeek	`DEEPSEEK_API_KEY`
Google / Gemini	`GOOGLE_API_KEY` 或 `GEMINI_API_KEY`
xAI	`XAI_API_KEY`
Bedrock	`AWS_BEARER_TOKEN_BEDROCK`	`AWS_SECRET`
平台凭证
- 微信	`WEIXIN_TOKEN`、`WEIXIN_ACCOUNT_ID`
- 飞书	`FEISHU_APP_ID`、`FEISHU_APP_SECRET`
- Telegram	`TELEGRAM_BOT_TOKEN`
	- Discord	`DISCORD_BOT_TOKEN`

踩坑提示：.env 文件不支持 bash 变量展开（如 ${HOME}），只能用字面路径。

第五章：SOUL.md — 给 Agent 一个灵魂

SOUL.md 每轮对话加载，改了立即生效，不需要重启。

实战框架：六要素

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


## 身份定位
我是忞的**自主执行者和思考伙伴**。

## 核心职责
1. **任务执行**：完成忞交代的任务
2. **思考伙伴**：评估想法再执行
3. **信息管理**：主动收集整理信息
4. **风险预警**：发现潜在风险立即告知

## 个性特点
- **专业**：专家级能力，判断准确
- **简洁**：一句话说清，表格优先
- **贴心**：主动提醒风险
- **高效**：立即执行，先做后报

## 执行原则
1. **高执行力**：先执行后汇报
2. **主动提醒**：发现风险立即告知
3. **主动总结**：任务完成自动总结

## 反驳机制（强制执行）
- **必须反驳**：有问题必须指出
- **必须带证据**：每次反驳附带数据或案例
- **禁止为反而反**：没有依据的抬杠毫无价值

## 沟通风格
- ✅ **简洁**：能一句话不用两句
- ✅ **结构化**：表格优先
- ✅ **结果先行**：先说结论
- ❌ **禁止**：冗余解释、废话铺垫

默认 SOUL vs 深度定制 SOUL

行为	默认 SOUL	深度定制 SOUL
称呼	“用户”	“忞”
反驳	无反驳机制	强制反驳 + 证据
问责	不追问	主动追问输出是否采纳
风格	标准客服	专业伙伴

第六章：数据目录 — Agent 的"记忆宫殿"

目录	作用	能否删除
`sessions/`	历史会话 JSON 文件	可以，但失去历史记录
`memories/`	记忆文件（MEMORY.md、USER.md）	不要删，丢失记忆
`state.db`	SQLite 数据库（会话索引）	不要删，破坏数据完整性
`kanban/`	看板任务和日志	可以，但失去看板状态
`cron/`	定时任务输出	可以，临时文件
`logs/`	日志文件（agent.log、errors.log）	可以，但失去调试信息
`checkpoints/`	文件系统快照	可以，失去 /rollback 能力
`auth.json`	OAuth token	可以，但需重新授权

踩坑提示：state.db 和 memory.db 是核心数据库，删除会导致会话和记忆丢失。

第七章：扩展层 — 让 Agent 越来越强

目录	作用	使用方式
`skills/`	技能目录（SKILL.md + 脚本）	`/skills` 命令管理
`scripts/`	自定义脚本	终端直接调用
`plugins/`	插件目录（MCP 服务器、平台适配器）	`config.yaml` → `plugins.enabled`
`hooks/`	事件钩子脚本	会话开始/结束时执行

踩坑提示：技能必须包含 SKILL.md（YAML frontmatter + Markdown body），否则无法加载。

第八章：Profiles — 多实例并行

每个 profile 是完整的并行 ~/.hermes/：

1
2
3
4
5
6
7


~/.hermes/profiles/blog-writer/
├── config.yaml # 独立配置
├── .env # 独立凭证
├── SOUL.md # 独立个性
├── state.db # 独立数据库
├── sessions/ # 独立会话
└── logs/ # 独立日志

典型场景：

blog-writer：博客写作，模型 glm-4.7
reviewer：审核质量，模型 glm-5.1
yuan：个人 AI，模型 glm-5-turbo

切换 profile：hermes -p blog-writer

踩坑提示：profile 不共享配置和状态，完全隔离。

第九章：安全地图

文件/配置	安全等级	建议
🟢 `config.yaml`	低	可以自由修改
🟢 `.env`	高	包含 API 密钥，不要提交到版本控制
🟢 `SOUL.md`	低	可以自由修改
🟡 `state.db`	中	包含会话数据，谨慎删除
🟡 `memory.db`	中	包含记忆数据，谨慎删除
🔴 `auth.json`	高	包含 OAuth token，不要泄露
🔴 `.env` 密钥	高	不要在对话中完整展示

附录

A. hermes doctor 输出解读

hermes doctor 检查项：

检查项	输出示例	说明
Python 版本	`✓ Python 3.13.0`	版本满足要求
Hermes 版本	`✓ Hermes Agent v0.14.0`	当前版本
OpenAI SDK	`✓ OpenAI SDK 1.x`	SDK 已安装
API 密钥	`✓ OPENROUTER_API_KEY set`	凭证已配置
配置文件	`✓ config.yaml valid`	配置格式正确

B. 常见报错对应的配置项

报错	对应配置项	解决方案
`401 Unauthorized`	`api_key` 或 `.env`	检查密钥是否正确
`429 Rate Limit`	`fallback_providers`	配置备用供应商
`max_tokens exceeded`	`max_tokens`	减小输出长度
`context length exceeded`	`context_length`	减小上下文长度
`tool not found`	`toolsets` / `disabled_toolsets`	检查工具集配置
`permission denied`	`terminal.backend`	检查容器权限

C. 最小启动配置模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


model:
 default: glm-5.1
 provider: zai
 api_key: ${ZAI_API_KEY}

agent:
 max_turns: 90

terminal:
 backend: local
 timeout: 180

compression:
 enabled: true

toolsets:
 - hermes-cli
 - terminal
 - file

.env：

1

ZAI_API_KEY=your_key_here

总结

Hermes 配置文件结构清晰：

核心三文件：config.yaml（行为）、.env（凭证）、SOUL.md（个性）
数据目录：sessions/、memories/、state.db 是 Agent 的"记忆宫殿"
扩展层：skills/、plugins/ 让 Agent 越来越强
Profiles：多实例并行，每个 profile 完全独立
安全第一：.env 和 auth.json 包含敏感信息，谨慎处理

记住：SOUL.md 改了立即生效，config.yaml 部分配置需重启 gateway。

关注 varkm，一起学习，一起成长。

教程 on Kalend's Blog