Hermes v0.20.0 升级实操：双机踩坑全记录

结论先行： 昨天（8月4日）我把 Hermes Agent 从 v0.19.0 升到了 v0.20.0——本地 Windows 和远程 Linux 服务器两台机器都升完了，QQ 频道、飞书、企业微信、微信 4 个平台通道全部恢复正常。整个升级过程踩了 6 个坑，几乎全是国内环境特有的：代理失效、GitHub 被墙、PyPI 发布滞后、pip 环境被污染、路径误报、重启后依赖丢失。本文记录完整实操过程，文末附 v0.20.0 新功能盘点。

一、为什么升：v0.20.0「The Herald Release」

Hermes Agent 是 Nous Research 出品的开源 AI 智能体框架。8月3日它发布了 v0.20.0，代号 The Herald Release（信使之名），距上一版 v0.19.0（7月20日）只隔了 14 天，但体量惊人：

• 约 3,650 个提交、1,400+ 合并的 PR、650+ 社区贡献者
• 关闭了约 1,200 个 issue，其中包括挂了很久的老 issue #514（A2A 智能体互联）

代号"信使"名副其实：这一版它会说话（流式语音对话）、会替众神传话（A2A 智能体协议）、会向你的系统宣告事件（出站 Webhook）、会引用出处（可溯源研究）。

二、升级前：先搞清楚两件事

第一件：确认安装方式。 我一直以为 Hermes 是 Pinokio 装的，结果 which hermes 一查，实际是标准 git 安装（C:\Users\woodt\AppData\Local\hermes\hermes-agent），Pinokio 里另有一个独立副本。装在哪、怎么装的，决定你用哪套升级命令——Windows git 安装和 Linux pip 安装的升级路径完全不同，后面这个差异踩了大坑。

第二件：备份。 升级前把整个 Hermes 目录打成 hermes-backup-v0.19.0-20260804_171143.tar.gz（339MB，含 277 个技能），远程主机的备份也拉回本地一份——异地双备份，升级翻车随时回滚。

三、本地 Windows 升级：五步走

四、六个坑，全是国内环境特有的

坑 1：Clash 代理失效 + GitHub 直连被墙 → 换镜像

升级第一步就卡住：hermes update 报 Could not connect to server over proxy 127.0.0.1——全局 git 代理指向 127.0.0.1:7897，但端口根本没监听（Clash 服务挂了）；清掉代理直连 GitHub，又超时（被墙）。

解法：走 gh-proxy.com 镜像 + git URL 重写，并显式清掉代理：

git config url."https://gh-proxy.com/https://github.com/".insteadOf "https://github.com/"
timeout 280 git -c http.proxy= -c https.proxy= \
  -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=60 fetch origin

两个细节：git 会继承失效的全局代理配置，必须用 -c http.proxy= 显式清掉；大仓库拉取容易超时，要加低速保护参数和长超时。

坑 2：Pinokio 污染了 pip 环境

机器上装了 Pinokio，它的环境变量把 pip 的缓存目录全部指向了 d:\pinokio\cache\...，还有一个 PIP_CONFIG_FILE=d:\pinokio\pipconfig。不清理的话，装依赖会装到奇怪的地方。

解法：覆盖全部环境变量，再用清华镜像：

export PIP_CONFIG_FILE=/dev/null
export PIP_CACHE_DIR="$HOME/.pip-cache-hermes"
export PIP_TMPDIR="$HOME/.pip-tmp-hermes"
venv/Scripts/python.exe -m pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple -e ".[cron,pty,mcp,web]"

坑 3：hermes doctor 误报 —— MSYS 路径问题

升级完跑 hermes doctor 体检，居然报 config.yaml not found！吓一跳，以为是数据丢了。查了半天才发现：从 git-bash 里 HERMES_HOME 是 MSYS 格式 /c/Users/...，Hermes 把它拼成了 \c\Users\... 这种坏路径。

解法：用 Windows 原生路径：

export HERMES_HOME="C:\Users\woodt\AppData\Local\hermes"
venv/Scripts/hermes.exe doctor   # 全绿，虚惊一场

坑 4：PyPI 上还没有 0.20.0（远程主机专属）

本地是 git 安装，拉 GitHub 源码没问题。但远程 Linux 主机是 pip 安装，pip index versions hermes-agent 一查，PyPI 最新仍是 0.19.0——GitHub 先发了 v0.20.0 的 tag，PyPI 包还没同步上去，pip 一直提示"已是最新"。

解法：用 git tag 方式从镜像装，保留 pip 的可回滚结构：

pip install "hermes-agent @ git+https://gh-proxy.com/https://github.com/NousResearch/hermes-agent.git@v2026.8.3"

远程主机上还有一层坑：存在两套 Hermes 环境（系统 pip 的 3.12 + 网关在跑的 agent-reach-venv 的 3.11），只升一套会导致 CLI 和网关版本分裂，必须两套都装。用户手动在远程直连 GitHub 折腾了多次 git clone 全部超时（被墙），换镜像后一次成功。

坑 5：网关重启后，平台依赖丢了

升级完重启网关，日志报：

Platform 'WeCom' requirements not met
Weixin: aiohttp/cryptography not installed

网关重启会清理部分依赖，飞书/企微/微信/QQ 通道全连不上。

解法：重启后补装依赖，然后等它慢慢连：

pip install 'aiohttp>=3.8.0' 'cryptography>=41.0.0' 'httpx>=0.25.0'

重要教训：重启后别急着判断"平台没连上"。 适配器是逐个初始化的，完整拉起 4 个平台要 5–8 分钟，刚重启那会儿看状态全是断开是正常假象。

坑 6：微信 session 过期不是故障

日志里反复出现 [Weixin] Session expired。这不是升级坏了，是微信登录态正常过期——在微信端给机器人发一条消息就会自动重新登录。

五、双机最终状态

六、v0.20.0 新功能盘点

最值得关注的是 A2A 协议：它让不同框架的智能体之间有了统一的"普通话"（与 MCP 互补——MCP 是给智能体"手"，A2A 是给智能体"同事"），这是多智能体协作从各自为战走向标准化的关键一步。

七、说点题外的

智能体工具链的迭代速度，本身就是全球 AI 竞赛的一个缩影。斯坦福 HAI 2026 报告显示，中美主流大模型的能力差距已缩小到 2.7%；虽然美国 AI 投资仍是我们约 23 倍，但中国在论文和专利数量上双双全球第一，工业机器人装机量更是美国的 9 倍。开源生态里，中国开发者的身影越来越重——像 Hermes 这种开源智能体框架，正是国内开发者参与全球 AI 协作、保持工具链自主可控的抓手。

一句话总结： 升级 Hermes 不难，难的是在国内网络环境下识别那些"环境特有的坑"。记住六条——镜像拉代码、清 pip 污染、用原生路径、git tag 装包、重启后补依赖、别慌 session 过期——你也能十分钟升完双机。

我是三木，专注 AI 工具与技术的实战记录。觉得有用就点个关注，下次升级不迷路。