Hermes AI 助手日常管理经验总结

发表于 更新于 分类于

一、使用背景

  • 系统：macOS + WSL2
  • 核心用途：个人 AI 助手，通过飞书对话
  • 主要模型：MiniMax-M2.7（主力）、Qwen3.5-4B-MLX-4bit（本地）

二、配置文件体系

目录结构

所有配置存放在 ~/.hermes/ 目录下：

1
2
3
4
5
6
7
8
9
10
~/.hermes/
├── config.yaml     # 主配置文件（模型、终端、TTS、压缩等）
├── .env             # API Key 和密钥（secrets）
├── auth.json        # OAuth 凭证（Nous Portal 等）
├── SOUL.md          # 主体身份定义（系统提示词 slot #1）
├── memories/        # 持久化记忆（MEMORY.md、USER.md）
├── skills/          # Agent 创建的技能（通过 skill_manage 管理）
├── cron/             # 定时任务
├── sessions/        # 网关会话
└── logs/             # 日志（errors.log、gateway.log — 敏感信息自动脱敏）

三个核心配置文件

文件 作用 重要性
config.yaml 运行时主配置 最高
.env 环境变量（API Key 单一真相来源） 最高
auth.json 凭证池缓存（仅用于 Nous/Copilot/Custom Provider） 一般

配置优先级（从上到下，高优先级覆盖低优先级）

  1. CLI 参数 — 例如 hermes chat --model anthropic/claude-sonnet-4（每次调用时覆盖）
  2. config.yaml — 所有非密钥配置的主文件
  3. .env — 环境变量后备；密钥（API Key、Token、密码）必须放这里
  4. 内置默认值 — 以上均未设置时的安全默认值

经验总结

  • 标准规则：密钥（API Key、Bot Token、密码）放 .env；其他配置（模型、终端后端、压缩设置、工具集）放 config.yaml
  • 标准 api_key 类型 provider（如 minimax-cn、omlx）不走 credential_pool，直接读 .env
  • API Key 应只保存在 .env，避免冗余存储
  • 配置修改流程：改 config.yaml → hermes doctor --fix → 重启网关

hermes config 命令行

1
2
3
4
5
hermes config                  # 查看当前配置
hermes config edit             # 在编辑器中打开 config.yaml
hermes config set KEY VAL      # 设置指定值（API Key 自动写入 .env，其他写入 config.yaml）
hermes config check            # 检查缺失项（升级后使用）
hermes config migrate          # 交互式添加缺失配置项

技巧：hermes config set 会自动判断写入目标 — API Key 写入 .env，其他写入 config.yaml。

环境变量引用

config.yaml 中支持 ${VAR_NAME} 语法引用环境变量：

1
2
3
4
auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

未定义的环境变量保持原样写入（${UNDEFINED_VAR} 不展开）。

三、常见故障与修复

问题 根因 解决方案
MiniMax API doctor 报 404 doctor 检查 /v1/models 端点，但 MiniMax 只有 /anthropic/v1/messages 误报，不影响实际使用
OMLX 本地模型 401 runtime_provider.py 只读 key_env，忽略 api_key_env 补丁同时兼容两个字段
auxiliary provider 失效 provider: auto 无法正确路由 显式指定 provider: minimax-cn
OMLX api_key_env 不生效 config 字段名与代码读取不匹配 确认使用 key_env 而非 api_key_env

四、日常维护命令

1
2
3
4
5
6
7
8
9
10
11
# 健康检查
hermes doctor

# 自动修复配置
hermes doctor --fix

# 重启网关
hermes gateway restart

# 查看配置
hermes config show

经验总结：

  • 修改 config.yaml 后必须先 hermes doctor --fix 再重启
  • 重启失败时检查是否有并发进程占用端口
  • WSL2 和 macOS 环境下的网关管理命令一致

五、核心功能体系

记忆系统（Memory）

Hermes 有两层持久化记忆：

文件 用途 字符上限
MEMORY.md Agent 的个人笔记 — 环境事实、约定、学到的经验 2,200 chars
USER.md 用户画像 — 偏好、沟通风格、期望 1,375 chars

两个文件均存放在 ~/.hermes/memories/，会话启动时注入系统提示词（冻结快照）。

原理：记忆变更在当前会话不生效（保持 LLM 前缀缓存性能），修改立即持久化到磁盘，下个会话起效。

技能系统（Skills）

技能是按需加载的知识文档，采用渐进式披露节省 token：

1
2
3
Level 0: skills_list() → [{name, description, category}, ...]  (~3k tokens)
Level 1: skill_view(name) → 完整内容 + 元数据
Level 2: skill_view(name, path) → 指定引用文件

技能通过 / 命令直接调用：

1
2
3
/axolotl                    # 加载技能并让 Agent 判断需要什么
/github-pr-workflow         # 直接执行
/plan                       # 加载 plan 技能，检查上下文后写实现计划

技能文件存放在 ~/.hermes/skills/，由 skill_manage 工具管理。

Cron 自动化

定时任务支持：

  • 定时触发（0 9 * * *、every 2h 等 cron 表达式）
  • 事件触发（webhook）
  • 交付目标：飞书、本地文件、或其他平台

六、工具链配置

  • TTS/图片/音乐：MiniMax 原生 API（MINIMAX_CN_API_KEY），不依赖 Hermes 内置 fal.ai 的 image_gen
  • 本地模型：OMLX（Ollama-MLX），通过 http://127.0.0.1:8000/v1 接入
  • Smart Routing：smart_model_routing.enabled: true 开启后，简单任务自动路由到本地免费模型
  • browser 工具：设置 cloud_provider: '' 使用本地 agent-browser 模式

七、安全与清理

7.1 安全配置审计

在日常维护中，定期运行安全审计能发现潜在风险。以下是我实际排查发现的问题：

高风险项

问题 发现方式 修复方案
.env 中 SUDO_PASSWORD 明文存储 人工检查 .env 文件 立即删除，不推荐存储在此
tirith_fail_open: true 配置审计 改为 tirith_fail_open: false
command_allowlist 规则过于宽泛 安全审计 手动收窄，仅保留必要命令

中风险项

问题 发现方式 处理建议
WhatsApp Bridge 源码存在 npm 漏洞 npm audit 配置已移除则无实际影响，源码目录可删除
streaming 配置冲突 配置比对 根级 streaming.enabled 与 display.streaming 含义不同，需确认业务场景

低风险项

问题 处理建议
config.yaml 中空配置块（whatsapp: {}、mattermost: {}、quick_commands: {}） 直接删除整段
service_tier: '' 空字符串 改为 service_tier: standard
timezone: '' 空字符串 改为 timezone: Asia/Shanghai

7.2 凭证管理

核心原则：API Key 只保存在 .env，不冗余存储。

实际排查发现 auth.json 中存在 request_count: 0 的凭证，说明从未被使用过。Hermes 运行时实际读取的是 .env 中的环境变量（通过 api_key_env 引用），auth.json 仅作为凭证池缓存层。

维护建议：

  • 定期检查 auth.json 中各 provider 的 request_count，及时清理从未使用的凭证
  • 保留 copilot（GitHub Copilot）等实际使用的凭证
  • 删除冗余凭证：minimax-cn、omlx 等（若实际走 .env）

7.3 Skills 精简

Skills 目录容易积累大量从未使用的技能，定期精简可减少维护负担。

精简标准（个人经验）：

  • 优先保留正在使用的 skill（如 github-pr-workflow、hexo-blog-post）
  • 删除空目录（仅含 DESCRIPTION.md 无实际内容）
  • 删除与当前配置不符的 skill（如无 Modal GPU 需求则删 modal-serverless-gpu）
  • 保留视频/音频相关 skill（若业务需要）

实际清理结果：

1
2
3
删除空目录：diagramming/、domain/、email/、feeds/、gaming/、gifs/、inference-sh/、smart-home/、social-media/、note-taking/
删除冗余 skill：modal-serverless-gpu、obliteratus、popular-web-designs
Skills 总数：114 → 约 105 个

7.4 配置精简

config.yaml 也会积累无效配置项，定期清理效果显著。

实际清理数据：

  • 初始行数：420 行
  • 清理后：约 391 行（减少约 30 行）

删除项：

  • 空平台工具集引用：telegram、discord、whatsapp、slack、signal、homeassistant
  • 空配置对象：honcho: {}、quick_commands: {}、personalities: {}
  • 重复的 delegation 块（patch 错误引入）

7.5 验证流程

清理完成后，按以下顺序验证：

1
2
3
4
5
6
7
8
9
10
11
# 1. 检查配置语法
hermes doctor --fix

# 2. 确认配置生效
hermes config show

# 3. 重启网关
hermes gateway restart

# 4. 验证核心功能
hermes doctor

注意：修改 config.yaml 后必须先运行 hermes doctor --fix 自动修复错误配置，最后再重启网关。

八、推荐的工作流

  1. 配置修改前先备份：cp config.yaml config.yaml.backup_日期
  2. 用 hermes doctor 验证修改结果
  3. 用 hermes config show 确认配置生效
  4. 最后 hermes gateway restart
  5. 重要决策（如删除 provider、修改认证逻辑）记录到记忆文件

九、使用技巧

来自官方文档的实践建议：

  • 明确表达需求：给出具体上下文（文件路径、错误信息、期望行为），减少来回次数
  • 前置上下文：一次性提供所有相关信息，胜过多次补充
  • 用 Context Files：重复出现的指令（如”use tabs not spaces”）写入 AGENTS.md，Agent 自动读取
  • 交给 Agent 探索：说”修复失败的测试”而非”打开 tests/test_foo.py 第 42 行然后…”
  • 优先用 Skill：复杂流程先查 /skills，再决定是否自己写提示词
  • Cron 自动化重复任务：新闻简报、定时提醒、数据采集等场景优先考虑