Hermes Agent v0.20.4 升级指南：核心更新与普通用户注意事项

版本：Hermes Agent v0.20.4 (2026.8.18)
基准版本：v0.18.2 (2026.7.7.2) → v0.20.0 (2026.8.3) → v0.20.4
来源：git log 分析、官方技能文档、实测验证

---

一、v0.20.x 核心更新项（v0.18.2 → v0.20.0 基线）

特性	说明	影响人群
Profile 导出/导入	新增 /export /import 斜杠命令、CLI hermes profile export/import、REST session.workspace.move。可打包 theme、layout、skills、plugins、extra_files。	团队协作、换机器、多项目复用配置
Desktop 多标签增强	Shift/Ctrl 多选拖拽、布局树整体移动、会话跨项目移动、已读/未读蓝点、/mark-read /mark-unread	Desktop App 用户
Plugin SDK：ctx.os	插件统一通过 ctx.os.notify()、ctx.os.open()、ctx.os.clipboard 调用原生能力，跨平台一致	插件开发者
Credential Pool 健壮性	403 计费错误改为短冷却+自动重试；Key 轮换自动清除 exhaustion；并发竞态加锁；区分瞬时/永久错误	所有用户（特别是多 Key 轮换场景）
Cron 调度器生产级修复	一次性任务完成后保留记录；修复生命周期误杀；批量调度不阻塞事件循环	定时任务/后台自动化用户
模型 ID 强制 vendor prefix	配置必须写 openrouter:anthropic/claude-3.5-sonnet，不能只写模型名	所有用户（升级后需检查 config.yaml）
MCP 修订号感知热重载	修改 mcp_servers.json 后跑 hermes mcp reload 或 /mcp-reload 即可生效	MCP 使用者

---

二、普通人升级注意事项（按平台分类）

1. Termux / Android（你的环境）

# ❌ 禁止：curl | bash / uv install —— 会从源码编译卡死
# ✅ 推荐：pip 直接安装预编译 wheel
pip install --upgrade hermes-agent==0.20.4

# 验证
python3 -c "import hermes_cli; print(hermes_cli.__version__)"
# 预期：0.20.4

• psutil 编译报错：v0.20.4 依赖 psutil==7.2.2，Termux 上无法编译。当前安装已跳过该可选依赖，不影响核心功能（仅缺进程监控相关指标）。
• 守护进程：无 systemd，用 termux-services 或 nohup 启动 gateway。
• 路径：~/.hermes 必须在 $HOME 下，外部存储权限受限。

2. Linux / macOS / WSL2

# 官方自动更新（推荐）
hermes update

# 或指定版本
hermes update --version v0.20.4

3. Windows

• 推荐 Windows Terminal + WSL2 运行，原生 PowerShell/CMD 下 TUI 光标易乱码。
• 安装：scoop install hermes-agent / winget install HermesAgent / 官方 PS1 脚本。

4. Desktop App

• 直接下载对应平台安装包（.dmg / .exe / .AppImage）覆盖安装，配置自动迁移。

---

三、升级后必跑验证清单

# 1. 版本号
hermes --version
# 预期：Hermes Agent v0.20.4 (2026.8.18)

# 2. Profile 命令
hermes --help | grep -E "export|import"

# 3. 主题命令
hermes skin --help

# 4. 凭据池状态
hermes credentials status

# 5. MCP 重载
hermes mcp reload

# 6. TUI 启动无报错
timeout 5 hermes --tui 2>&1 | head -20

# 7. Cron 记录保留
hermes cron list --all

---

四、常见升级后问题及修复

问题	现象	修复
主题不生效 / hermes skin 报错	配置残留旧 theme: 字段	sed -i '/^theme:/d' ~/.hermes/config.yaml && hermes skin reset
模型 ID 报错 "missing vendor prefix"	config.yaml 写 anthropic/claude-3.5-sonnet	改为 openrouter:anthropic/claude-3.5-sonnet
MCP 配置不生效	修改后工具不刷新	hermes mcp reload 或 TUI 内 /mcp-reload
TUI Widget 热加载失效	保存 .mjs 无新组件	node --check ~/.hermes/tui-widgets/xxx.mjs 检查语法；命名必须 .mjs，export default function register(sdk)

---

五、回滚方案（如需）

# 1. 恢复配置备份
cp ~/.hermes/config.yaml.bak.$(date +%Y%m%d) ~/.hermes/config.yaml
cp -r ~/.hermes/skills.bak.$(date +%Y%m%d) ~/.hermes/skills
cp -r ~/.hermes/skins.bak.$(date +%Y%m%d) ~/.hermes/skins 2>/dev/null || true

# 2. 降级
# Termux
pip install hermes-agent==0.19.0   # 或 0.18.2

# Linux/macOS/WSL2
hermes update --version v0.19.0

# 3. 验证
hermes --version

---

六、给普通用户的建议

1. 先备份：升级前把 ~/.hermes/config.yaml、skills/、skins/ 备份一份。
2. Termux 必用 pip：不要跑官方 install.sh，也别用 uv。
3. 检查模型 ID：升级后第一时间确认 config.yaml 里的 default_model 带 vendor prefix。
4. 关注 Credential Pool：如果你用多 Key 轮换，v0.20.x 的冷却重试机制能显著减少误判扣费。
5. Profile 导出：配置稳定后跑一次 hermes profile export，换机器/协作时直接 import。

版本号以 hermes --version 实测为准（当前 v0.20.4），文档参考 v0.20.0 基线特性，补丁版本不改核心行为。

---

如果你觉得本文有用，请点赞，收藏，转发

你有什么问题，请留言，我来帮你解答。