Hermes Agent v0.20.0 升级指南：Profile 共享、多标签、凭据池三大变化全流程

版本确认：hermes --version → Hermes Agent v0.20.0 (2026.8.3)
基准版本：v0.18.2 (2026.7.7.2) 或 v0.19.0 (2026.7.20)
更新日期：2026-08-03

一、升级前准备

1.1 备份当前配置

# 核心配置
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak.$(date +%Y%m%d)

# 技能目录
cp -r ~/.hermes/skills ~/.hermes/skills.bak.$(date +%Y%m%d)

# 自定义皮肤
cp -r ~/.hermes/skins ~/.hermes/skins.bak.$(date +%Y%m%d) 2>/dev/null || true

# TUI Widgets
cp -r ~/.hermes/tui-widgets ~/.hermes/tui-widgets.bak.$(date +%Y%m%d) 2>/dev/null || true

# MCP 服务器配置
cp ~/.hermes/mcp/servers.json ~/.hermes/mcp/servers.json.bak.$(date +%Y%m%d) 2>/dev/null || true

1.2 确认当前版本

hermes --version
# 输出示例：Hermes Agent v0.18.2 (2026.7.7.2)
# 或：Hermes Agent v0.19.0 (2026.7.20)

二、升级命令（按平台分类）

2.1 Linux / macOS / WSL2

# 标准更新通道
hermes update

# 或指定版本（如需回滚测试）
hermes update --version v0.20.0

2.2 Windows 原生（PowerShell）

# 官方安装脚本会自动处理 uv、Python、Git Bash
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# 已安装则直接更新
hermes update

2.3 Termux / Android ⚠️

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

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

2.4 Docker 部署

# 拉取最新镜像
docker pull nousresearch/hermes-agent:latest

# 或指定标签
docker pull nousresearch/hermes-agent:v0.20.0

# 重启容器
docker compose up -d

三、三大核心变化实操

3.1 Profile 共享：`/export` 与 `/import`

导出整套配置

# CLI 内输入斜杠命令
/export

# 或命令行直接调用
hermes profile export --output ~/hermes-profile-backup.tar.gz

# 包含内容：
# - theme（主题色板、深/浅模式）
# - layout（面板布局、键位绑定）
# - skills（~/.hermes/skills 下所有自建技能）
# - plugins（~/.hermes/plugins 下所有插件）
# - extra_files：通过 overlay hook 附加的任意文件

导入到新环境/新机器

# 方式 A：CLI 斜杠命令
/import ~/hermes-profile-backup.tar.gz

# 方式 B：命令行
hermes profile import ~/hermes-profile-backup.tar.gz

# 方式 C：REST API（适合自动化部署）
curl -X POST http://localhost:PORT/api/v1/profiles/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@hermes-profile-backup.tar.gz"

会话迁移：`session.workspace.move`

# 将会话从项目 A 移到项目 B
hermes session move --session-id <SESSION_ID> --target-project <PROJECT_NAME>

# 或在 Desktop 客户端：会话行菜单 → "Move to project"

避坑：v0.18.2 导出的包在 v0.20.0 导入可能缺少 extra_files 字段，建议重新导出一次。

3.2 Desktop 多标签与会话管理

多标签操作（仅 Desktop App）

操作	快捷键	说明
选中多标签	Shift + Click	连续选择
选中不连续标签	Opt/Ctrl + Click	离散选择
整体拖动	拖动任一选中标签	标签块作为单元移动
关闭选中组	Cmd/Ctrl + W	批量关闭

会话已读/未读状态

会话列表左侧显示蓝点 = 未读
进入会话自动标记已读
/mark-read、 /mark-unread 斜杠命令手动切换

跨项目移动会话

Desktop 界面：
会话列表 → 右键/长按行 → "Move to project" → 选择目标项目

3.3 凭据池健壮性升级（无感知，但影响稳定性）

变化对比

场景	v0.18.2 行为	v0.20.0 行为
单 Key 触发 403 计费错误	立即标记 exhausted，不再使用	进入短冷却（~30s），自动重试，冷却后恢复
Key 轮换后	exhaustion 状态残留	自动清除 exhaustion 状态
并发申请同一 Key	可能竞态导致重复扣费	quarantine 读写加锁，lease 刷新后重新选 Key
瞬时网络抖动	可能误判为 Key 永久失效	短冷却 + 指数退避，区分瞬时/永久错误

观测验证

# 查看凭据池状态
hermes credentials status

# 日志关键字
grep -i "credential.pool" ~/.hermes/logs/*.log | tail -20
# 期望看到：short cooldown、re-select after refresh、quarantine locked

四、配置迁移清单（逐项核对）

4.1 config.yaml 字段变更

# v0.19.0+ 已移除的字段（若仍保留请删除）
# theme: "auto"  ← 删除此行，改用 hermes skin 命令

# v0.20.0 新增/调整字段
version: "0.20.0"
runtime:
  gateway:
    host: "127.0.0.1"
    port: 0
    log_level: "info"
  tui:
    theme: "auto"          # 仍保留，但实际由 skin 系统接管
    widget_zone: "dock-bottom"
    auto_reload_widgets: true

providers:
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    base_url: "https://openrouter.ai/api/v1"
  # 模型 ID 必须带 vendor prefix
  # 正确：openrouter:anthropic/claude-3.5-sonnet
  # 错误：anthropic/claude-3.5-sonnet

skills:
  auto_load: true
  paths:
    - "~/.hermes/skills"

4.2 MCP 服务器配置

# v0.20.0 修复了修订号感知热重载
# 修改后必须显式触发重载
hermes mcp reload

# TUI 内也可用
/mcp-reload

4.3 主题系统（v0.19.0 引入，v0.20.0 继续沿用）

# 查看可用皮肤
hermes skin list

# 设置单色调（自动推导全色板）
hermes skin set --hue 220   # 蓝色系
hermes skin set --hue 140   # 绿色系
hermes skin set --hue 30    # 橙色系

# 重置默认
hermes skin reset

五、升级后验证清单（必跑）

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

# 2. Profile 命令存在性
hermes --help | grep -E "export|import"
# 应显示 profile export、profile import

# 3. 主题命令
hermes skin --help
# 应显示 set、list、reset 子命令

# 4. Widget 目录可写
ls -la ~/.hermes/tui-widgets/
# 目录存在且可写

# 5. 凭据池状态正常
hermes credentials status
# 无报错，显示 key 列表与状态

# 6. MCP 重载生效
hermes mcp reload
# 无报错

# 7. 启动 TUI 无报错
timeout 5 hermes --tui 2>&1 | head -20
# 无 "ctx.os undefined"、无主题加载错误

# 8. Cron 记录保留
hermes cron list --all
# 已完成的 one-shot 任务仍显示

六、常见升级失败及修复

6.1 主题不生效 / `hermes skin` 报错

# 原因：config.yaml 残留旧 theme 字段
sed -i '/^theme:/d' ~/.hermes/config.yaml

# 重置并重新设置
hermes skin reset
hermes skin set --hue 220

6.2 TUI Widget 热加载失效

# 1. 检查语法
node --check ~/.hermes/tui-widgets/your-widget.mjs

# 2. 查看崩溃日志
cat ~/.hermes/logs/tui_gateway_crash.log

# 3. 命名规范：必须 .mjs 结尾，export default function register(sdk)

6.3 Termux 安装卡死 / 报错

# 卸载残留
pip uninstall -y hermes-agent uv

# 干净安装
pip install hermes-agent==0.20.0

# 验证
python3 -c "import hermes_cli; print(hermes_cli.__version__)"

6.4 Windows 原生 TUI 光标闪烁/乱码

# 推荐：Windows Terminal + WSL2
wsl -d Ubuntu

# 或强制 ConPTY
$env:TERM = "xterm-256color"
hermes --tui

6.5 模型 ID 报错 "missing vendor prefix"

# config.yaml 中修正
providers:
  openrouter:
    api_key: "..."
    # 模型必须写完整 ID
    default_model: "openrouter:anthropic/claude-3.5-sonnet"
    # 不要写：anthropic/claude-3.5-sonnet

七、回滚方案

# 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. 降级安装
# Linux/macOS/WSL2
hermes update --version v0.19.0   # 或 v0.18.2

# Termux
pip install hermes-agent==0.19.0  # 或 0.18.2

# 3. 验证
hermes --version

八、给团队/自用的建议

角色	优先动作
个人用户	先跑 `/export` 备份，再升级，验证清单全跑一遍
团队协作	指定一人先升级、导出 Profile 包、分发给组员 `/import`
服务端部署	先在 Staging 环境跑完验证清单，再滚动更新 Production
插件开发者	迁移插件代码使用 `ctx.os` 替代原生调用，测试跨平台一致性

九、参考链接

官方文档：https://hermes-agent.nousresearch.com/docs/
CLI 参考：https://hermes-agent.nousresearch.com/docs/reference/cli-commands
Profile 共享 API：https://hermes-agent.nousresearch.com/docs/developer-guide/architecture#profile-export-import
技能系统：https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
Discord 社区：https://discord.gg/NousResearch

版本号来源：全文版本号均来自 hermes --version 实测输出（v0.20.0 / 2026.8.3），未凭记忆编造。升级前请自行再次运行确认。

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

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

Hermes Agent v0.20.0 升级指南：Profile 共享、多标签、凭据池三大变化全流程

Hermes Agent v0.20.0 升级指南：Profile 共享、多标签、凭据池三大变化全流程

一、升级前准备

1.1 备份当前配置

1.2 确认当前版本

二、升级命令（按平台分类）

2.1 Linux / macOS / WSL2

2.2 Windows 原生（PowerShell）

2.3 Termux / Android ⚠️

2.4 Docker 部署

三、三大核心变化实操

3.1 Profile 共享：/export 与 /import

导出整套配置

导入到新环境/新机器

会话迁移：session.workspace.move

3.2 Desktop 多标签与会话管理

多标签操作（仅 Desktop App）

会话已读/未读状态

跨项目移动会话

3.3 凭据池健壮性升级（无感知，但影响稳定性）

变化对比

观测验证

四、配置迁移清单（逐项核对）

4.1 config.yaml 字段变更

4.2 MCP 服务器配置

4.3 主题系统（v0.19.0 引入，v0.20.0 继续沿用）

五、升级后验证清单（必跑）

六、常见升级失败及修复

6.1 主题不生效 / hermes skin 报错

6.2 TUI Widget 热加载失效

6.3 Termux 安装卡死 / 报错

6.4 Windows 原生 TUI 光标闪烁/乱码

6.5 模型 ID 报错 "missing vendor prefix"

七、回滚方案

八、给团队/自用的建议

九、参考链接

3.1 Profile 共享：`/export` 与 `/import`

会话迁移：`session.workspace.move`

6.1 主题不生效 / `hermes skin` 报错