Hermes Agent v0.17.0 → v0.18.0 版本对比

第 23 讲：迁移指南与最佳实践

基于 Hermes Agent 源码 · 2026-07-06

一、版本升级概览

本讲是 v0.17.0 → v0.18.0 对比系列的最后一讲。前两讲我们分析了架构演进（第21讲）和新特性详解（第22讲），本讲聚焦实际迁移——从配置变更、命令迁移到最佳实践，帮你安全、无痛地完成升级。

二、破坏性变更清单

本次升级共涉及 2,225 个文件，254,012 行新增代码。以下是需要手动处理的破坏性变更：

2.1 认证命令变更：hermes login → hermes auth

v0.16.0 使用 hermes login 登录 Nous Portal，v0.18.0 已统一为 hermes auth add nous。

# ❌ v0.16.0（已废弃）
hermes login

# ✅ v0.18.0（新命令）
hermes auth add nous

# 其他 provider 也使用 auth 子命令
hermes auth add openai
hermes auth add anthropic
hermes auth add vertex

配置文件中相关注释也已同步更新：

# cli-config.yaml.example 变更
- #   "nous"         - Nous Portal OAuth (requires: hermes login)
+ #   "nous"         - Nous Portal OAuth (requires: hermes auth add nous)

2.2 safe 工具集移除 MoA

safe 复合工具集不再包含 mixture_of_agents。如果你依赖 safe 工具集同时使用 MoA，需要显式添加：

# cli-config.yaml.example 变更
- #   safe         - web + vision + moa (no terminal access)
+ #   safe         - web + vision (no terminal access)

# 需要 MoA 的用户应显式声明：
platform_toolsets:
  cli:
    enabled_toolsets:
      - web
      - vision
      - moa          # 显式添加

三、配置变更对照表

以下是 v0.18.0 中所有新增和变更的配置项：

四、升级步骤

4.1 标准升级流程

4.2 具体操作

1. 备份配置和会话数据：

# 备份 HERMES_HOME
cp -r ~/.hermes ~/.hermes.backup.$(date +%Y%m%d)

# 确认备份包含关键数据
ls ~/.hermes.backup.*/config.yaml
ls ~/.hermes.backup.*sessions/

2. 执行升级：

# 管理式安装（推荐）
hermes update

# 手动 pip 安装
pip install --upgrade hermes-agent

3. 检查配置兼容性：

# 运行诊断
hermes doctor

# 检查配置有效性
hermes config validate

4. 重新认证（如使用 Nous Portal）：

# 如果 hermes login 不再可用
hermes auth add nous

# 查看已配置的认证
hermes auth list

5. 验证关键功能：

# 测试基本对话
hermes --model gpt-5.5 "Hello, what version am I?"

# 测试工具集
hermes --toolsets all "List files in current directory"

# 测试 MoA（如已配置）
hermes --model moa/deep-reasoning "Compare two approaches..."

五、安全加固注意事项

v0.18.0 包含 88 次安全相关提交，以下变更可能影响现有工作流：

六、性能优化建议

6.1 超时配置调整

v0.18.0 将 stale_timeout_seconds 默认值从 300s 降至 90s。如果你使用大上下文或慢速模型，建议显式设置：

model:
  # 大上下文（128K+）建议 180-300s
  stale_timeout_seconds: 180
  # 流式超时保持默认即可
  # stream_timeout_seconds: 1800

6.2 代码验证功能配置

v0.18.0 引入了 verify_on_stop 机制，建议在编码场景中启用：

agent:
  # 编码完成后自动提醒验证
  verify_on_stop: auto
  # 最多提醒 3 次
  max_verify_nudges: 3
  # 启用编码指导
  verify_guidance: true
  # 自定义编码指令
  coding_instructions:
    - "For UI work, don't run tsc/lint until I approve the look."
    - "Clean the diff before you commit and push."

6.3 Worktree 同步策略

新增 worktree_sync 选项，控制 worktree 分支来源：

git:
  worktree: true
  # 默认 true：从远程最新提交创建 worktree
  worktree_sync: true
  # 设为 false 从本地 HEAD 创建（离线场景）
  # worktree_sync: false

七、Gateway 部署升级

7.1 重启行为变更

restart_drain_timeout 默认值从 60s 改为 0（立即中断）。如果你使用 systemd 管理 Gateway，需要注意：

agent:
  # 如需优雅关闭，显式设置
  restart_drain_timeout: 60
  # 注意：该值应远小于 systemd 的 TimeoutStopSec

7.2 新：Gateway 设置向导

v0.18.0 引入了 hermes raft 命令，提供交互式 Gateway 设置向导，简化了部署流程。支持自动检测平台、配置凭证和验证连接。

7.3 /resume 安全变更

本次升级对 /resume 命令进行了 10+ 次安全加固，包括：

🔹 所有平台 /resume 现在按调用者身份作用域隔离

🔹 Matrix 平台 /resume 按线程（thread）而非房间（room）隔离

🔹 无身份验证的调用者 /resume 直接拒绝（fail-closed）

🔹 共享群组 /resume 需要显式授权

🔹 持久化 /resume 需要来源证明（provenance）

八、桌面应用升级

8.1 安装器重新设计

桌面应用安装器完全重新设计，支持：

🔹 新的设计系统和 OS 主题适配

🔹 粒度化更新（选择性安装组件）

🔹 已安装主题标记（避免重复安装）

8.2 Managed Node.js 改进

Windows 用户特别注意，v0.18.0 大幅改进了 Managed Node.js 支持：

# hermes_constants.py 新增功能
- Windows 便携式 Node 自动下载与修复
- node_tool_runnable() 运行时验证
- hermes_managed_node_tree_present() 健康检查
- _heal_managed_node_windows() 自动修复
- Node 22 为目标版本（可配置 HERMES_NODE_TARGET_MAJOR）

九、常见问题排查

十、回滚方案

如果升级后遇到问题，可以回滚到 v0.17.0：

# 回滚到 v0.17.0 标签tag
cd ~/.hermes/hermes-agent/
git checkout v2026.6.19

# 或使用 pip 回滚
pip install hermes-agent==2026.6.19

# 恢复配置备份
cp ~/.hermes.backup.*/config.yaml ~/.hermes/config.yaml

十一、总结

v0.17.0 → v0.18.0 是 Hermes Agent 历史上改动量最大的版本之一。本系列三讲完整覆盖了：

🔹 第 21 讲：架构演进与核心变化（5,009 次提交，254K 行新增代码）

🔹 第 22 讲：新特性详解（MoA、代码验证、Vertex AI、Kanban、安全加固）

🔹 第 23 讲：迁移指南与最佳实践（破坏性变更、升级步骤、故障排查）

— 系列导航 —

← 第 22 讲：新特性详解

v0.17.0 → v0.18.0 对比系列完结

下一系列：OpenCode 源码解析

📖 源码仓库：github.com/NousResearch/hermes-agent

关注公众号获取更多技术干货 🚀