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

Hermes Agent 装好后,~/.hermes/ 下堆满文件,哪个改哪个不改?本文从源码验证每个配置项的作用、默认值和踩坑提示。

开篇导语

装好 Hermes Agent,~/.hermes/ 下一堆文件,config.yaml.envSOUL.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.envSOUL.mdstate.dbsessions/logs/ 等。

第二章:三大核心文件(新手必读)

文件作用怎么改
config.yaml所有行为参数(模型、工具、终端、压缩、看板等)编辑文本,改后立即生效(部分需重启 gateway)
.envAPI 密钥和平台凭证export KEY=xxx 或直接编辑,改后立即生效
SOUL.mdAgent 个性、称呼、反驳机制编辑 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 环境变量全表(按供应商分类)

供应商必须环境变量可选环境变量备注
OpenRouterOPENROUTER_API_KEY路由到多模型
AnthropicANTHROPIC_API_KEYANTHROPIC_TOKENClaude 模型
OpenAIOPENAI_API_KEYGPT、o1 系列
Z.AI / GLMZAI_API_KEYGLM_API_KEY智谱 GLM 模型
KimiKIMI_API_KEYKIMI_CN_API_KEY月之暗面
MiniMaxMINIMAX_API_KEYMINIMAX_CN_API_KEY国产大模型
DeepSeekDEEPSEEK_API_KEY深度求索
Google / GeminiGOOGLE_API_KEYGEMINI_API_KEYGemini 系列
xAIXAI_API_KEYGrok 模型
BedrockAWS_BEARER_TOKEN_BEDROCKAWS_SECRETAWS 托管

平台凭证(消息平台)

  • 微信:WEIXIN_TOKENWEIXIN_ACCOUNT_ID
  • 飞书:FEISHU_APP_IDFEISHU_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.1openrouter/anthropic/claude-sonnet-4空字符串时走 auto-detect
provider""zaiopenrouteranthropicbase_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
visionauto“"(自动)120s
web_extractauto"”360s
compressionauto""120s
session_searchauto""30s
skills_hubauto""30s
approvalauto""30s
mcpauto""30s
title_generationauto""30s
triage_specifierauto""120s
curatorauto""600s

provider: auto 时,Hermes 自动选择最佳可用供应商(OpenRouter → Nous → Codex → 自定义)。

踩坑提示:视觉任务(vision)超时需设为 120s 或更高,图片下载需要额外时间。

agent — 行为参数

字段默认值常见调法踩坑提示
max_turns9020(短任务)、200(长推理)超限后停止,无错误提示
reasoning_effortmediumlow / medium / high某些模型不支持此参数
tool_use_enforcementautoauto / true / false / [“gpt”, “codex”]强制模型调用工具而非描述动作
image_input_modeautonative / textnative 直接传图片,text 先用 vision_analyze 描述
gateway_timeout18003600(长任务)、600(短任务)空闲超时,不是任务总时长
gateway_notify_interval180600(长任务反馈)、0(关闭)周期性"仍工作中"通知间隔

terminal — 终端后端

字段默认值可选值踩坑提示
backendlocallocal / docker / ssh / modal / daytonaDocker 需要容器运行时
timeout180600(长任务)超时后进程被 SIGTERM
auto_source_bashrctruetrue / falsefalse 时只读 ~/.bash_profile
persistent_shelltruetrue / falseSSH 后端自动持久化

容器资源限制(适用于 docker、modal、daytona):

字段默认值说明
container_cpu1CPU 核心数
container_memory5120内存(MB),默认 5GB
container_disk51200磁盘(MB),默认 50GB

compression — 上下文压缩策略

字段默认值说明
enabledtrue是否启用压缩
threshold0.5触发阈值(50% 上下文使用率)
target_ratio0.2压缩到阈值比例(保留 20%)
protect_last_n20保留最近 N 条消息不压缩
protect_first_n3保留开篇 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
telegramhermes-telegram
discordhermes-discord
whatsapphermes-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 — 会话自动重置

字段默认值说明
modebothidle(空闲)、daily(每日)、both(两者)
idle_minutes1440空闲 N 分钟后重置
at_hour4每日 N 点强制重置

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

checkpoints — 文件系统快照

字段默认值说明
enabledfalse是否启用
max_snapshots20每个项目最多快照数
max_total_size_mb500总大小上限(MB)
max_file_size_mb10单文件跳过阈值
auto_prunetrue自动清理过期快照
retention_days7保留天数

踩坑提示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
字段必填说明
urlMCP 服务器地址
headers自定义 HTTP 头
timeout连接超时(秒)

plugins — 插件启用 / 禁用

1
2
3
4
5
6
plugins:
  enabled:
    - disk-cleanup
    - rtk-rewrite
  disabled:
    - some-plugin

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

第四章:.env 环境变量全表(按供应商分类)

供应商必须变量可选变量平台凭证
OpenRouterOPENROUTER_API_KEY
AnthropicANTHROPIC_API_KEYANTHROPIC_TOKEN
OpenAIOPENAI_API_KEY
Z.AI / GLMZAI_API_KEYGLM_API_KEY
KimiKIMI_API_KEYKIMI_CN_API_KEY
MiniMaxMINIMAX_API_KEYMINIMAX_CN_API_KEY
DeepSeekDEEPSEEK_API_KEY
Google / GeminiGOOGLE_API_KEYGEMINI_API_KEY
xAIXAI_API_KEY
BedrockAWS_BEARER_TOKEN_BEDROCKAWS_SECRET
平台凭证
- 微信WEIXIN_TOKENWEIXIN_ACCOUNT_ID
- 飞书FEISHU_APP_IDFEISHU_APP_SECRET
- TelegramTELEGRAM_BOT_TOKEN
- DiscordDISCORD_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.dbSQLite 数据库(会话索引)不要删,破坏数据完整性
kanban/看板任务和日志可以,但失去看板状态
cron/定时任务输出可以,临时文件
logs/日志文件(agent.log、errors.log)可以,但失去调试信息
checkpoints/文件系统快照可以,失去 /rollback 能力
auth.jsonOAuth token可以,但需重新授权

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

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

目录作用使用方式
skills/技能目录(SKILL.md + 脚本)/skills 命令管理
scripts/自定义脚本终端直接调用
plugins/插件目录(MCP 服务器、平台适配器)config.yamlplugins.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

切换 profilehermes -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.xSDK 已安装
API 密钥✓ OPENROUTER_API_KEY set凭证已配置
配置文件✓ config.yaml valid配置格式正确

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

报错对应配置项解决方案
401 Unauthorizedapi_key.env检查密钥是否正确
429 Rate Limitfallback_providers配置备用供应商
max_tokens exceededmax_tokens减小输出长度
context length exceededcontext_length减小上下文长度
tool not foundtoolsets / disabled_toolsets检查工具集配置
permission deniedterminal.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 配置文件结构清晰:

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

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

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