开篇导语
装好 Hermes Agent,~/.hermes/ 下一堆文件,config.yaml、.env、SOUL.md… 哪个改哪个不改,新手完全懵。
第一章:你的 ~/.hermes/ 长什么样
用一棵目录树展示所有文件/目录分层:
| |
每个 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 核心字段速查
| |
.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 — 故障自动切换
| |
| 触发条件 | 行为 |
|---|---|
| 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 |
| 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 服务器连接
| |
| 字段 | 必填 | 说明 |
|---|---|---|
url | 是 | MCP 服务器地址 |
headers | 否 | 自定义 HTTP 头 |
timeout | 否 | 连接超时(秒) |
plugins — 插件启用 / 禁用
| |
踩坑提示:插件需先安装在 ~/.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 每轮对话加载,改了立即生效,不需要重启。
实战框架:六要素
| |
默认 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/:
| |
典型场景:
blog-writer:博客写作,模型 glm-4.7reviewer:审核质量,模型 glm-5.1yuan:个人 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. 最小启动配置模板
| |
.env:
| |
总结
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,一起学习,一起成长。