Hermes Agent 连接个人微信指南：Ubuntu 下 gateway 与 iLink Bot API 配置

1. 为什么要在 Ubuntu 上把 Hermes Agent 接到个人微信Hermes Agent 是一个可以跑在终端里的智能体框架能调用大模型完成对话、写代码、跑任务。而个人微信是我们每天打开次数最多的 App把 Hermes 接到微信上等于给自己造了一个随时能发消息的私人助理出门在外发一句「帮我查下这段报错」服务器上的 Hermes 就能调模型回你。这篇聚焦 Ubuntu 环境22.04 桌面版和 Server 版都适用把 Hermes Agent 通过 gateway 和 iLink Bot API 连接个人微信的完整路径走一遍。需要先说明一个关键点这里说的是个人微信 Weixin不是企业微信 WeCom。Hermes 的微信适配器走的是腾讯 iLink Bot API扫码后连接的是一个独立的 iLink Bot 身份不是把你的普通微信号变成完全可控的机器人。实测下来私聊最可靠普通微信群通常收不到事件。适合谁看手上有一台 Ubuntu 机器本地或云主机都行、想用微信当入口调大模型、又不想折腾公网 IP 和 Webhook 的人。整个方案用 HTTP long-polling 收消息不需要 Nginx、不需要 HTTPS 证书、不需要内网穿透。下面从依赖安装、模型配置、微信适配器、gateway 启动到日志排查一步步给出可复制的命令和配置片段。2. 前置准备TaoToken 统一 Key 与 API 通道在接微信之前Hermes 本身必须先能正常和大模型对话。如果 CLI 对话都跑不通叠加 gateway 只会让问题更难定位。模型提供商这块我建议用 TaoToken 做统一入口。它的好处是一个 Key 就能覆盖多种主流模型切换模型时不用改一堆环境变量对后面调试微信链路特别省事。TaoToken 提供 OpenAI 兼容的 API 通道Hermes 里凡是支持自定义 base_url 的 provider 都能直接对接。你需要准备的东西一台 Ubuntu 22.04桌面版或 Server 版一个可扫码登录的个人微信账号一个 TaoToken 的 API Key服务器能正常访问 iLink API 和微信 CDNTaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。拿到 Key 之后在 Hermes 里把它填到自定义 provider 的 api_key 和 base_url 即可。注意TaoToken 是合规的 API 聚合通道配置时只填 base_url 和 Key不要在任何地方写代理相关的东西。先把基础依赖装上sudo apt update sudo apt install -y git curl xz-utils ca-certificates如果你在桌面版 Ubuntu 上还想用 Hermes Desktop 或需要编译原生模块再补一个sudo apt install -y build-essentialHermes 官方安装器在 Linux 上主要依赖 git、curl、xz-utilsPython 3.11、Node.js v22、ripgrep、ffmpeg、uv 这些它会自己处理不用手动装。3. 安装 Hermes Agent 并配置模型3.1 安装与 PATH 检查在 Ubuntu 终端执行官方安装脚本curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash装完重新加载 shellsource ~/.bashrc验证命令是否可用hermes --version如果提示找不到命令检查 PATHecho $PATH ls -la ~/.local/bin也可以临时补一下export PATH$HOME/.local/bin:$PATH3.2 用 TaoToken 配置模型Hermes 的普通配置放在~/.hermes/config.yaml密钥和 token 这类敏感信息放在~/.hermes/.env。我们走自定义 provider 的方式接 TaoToken。先跑完整向导hermes setup在 provider 选择环节选自定义 / OpenAI 兼容然后填入# ~/.hermes/config.yaml 片段 [providers.taotoken] type openai base_url https://taotoken.net/api model gpt-4o-mini对应的 Key 写进.env# ~/.hermes/.env TAOTOKEN_API_KEY你的-taoToken-key配置完成后测试 CLI 是否能正常对话hermes输入一句只回复HERMES_OK能正常返回HERMES_OK再往下走。这一步是整个链路的地基别跳过。4. 安装微信适配器依赖并扫码4.1 装 aiohttp 和 cryptographyHermes 的 Weixin 适配器需要两个包aiohttp负责 HTTP 通信cryptography负责微信图片、视频、文件等媒体的 CDN 加解密。终端二维码显示依赖 messaging extra。cd ~/.hermes/hermes-agent uv pip install -e .[messaging]如果系统 Python 不允许直接 pip install优先用上面的 uv 方式不要随便sudo pip install。4.2 运行微信配置向导hermes gateway setup平台选择时选Weixin不要选成 WeCom。向导会自动完成向 iLink Bot API 请求二维码、在终端显示二维码或给出 URL、等你用手机微信扫码、手机端确认登录、把账号凭据保存到~/.hermes/weixin/accounts/。扫码成功后你会看到类似输出微信连接成功account_idyour-account-id把这个 account_id 记下来后面.env要用。4.3 写 .env 配置打开配置文件nano ~/.hermes/.env第一次测试用最简配置WEIXIN_ACCOUNT_ID你的-account-id WEIXIN_DM_POLICYopen WEIXIN_GROUP_POLICYdisabled WEIXIN_HOME_CHANNEL_NAMEHome注意通常不要手动写WEIXIN_TOKEN扫码向导已经自动保存了 token。只有缺失时才需要重新跑hermes gateway setup。5. 启动 gateway 并验证消息收发5.1 前台启动看日志先别急着做后台服务前台跑方便看日志hermes gateway启动后日志里应该能看到 Weixin 适配器恢复凭据、连接 iLink API、开始 long-polling。Weixin 适配器用 HTTP long-polling 收消息不需要公网 IP、Webhook、WebSocket、Nginx 或 HTTPS。5.2 发消息验证在微信里给扫码后出现的 iLink Bot 联系人发消息只回复WEIXIN_OK注意不是给「扫码的那个普通微信号」发消息。扫码连接的是一个独立的 iLink Bot 身份比如xxxim.bot它和你的普通微信号不是同一个身份。正常情况应该看到这条链路微信发出消息 Gateway 收到 inbound message Hermes 调用模型 微信收到 WEIXIN_OK5.3 改成白名单模式测试成功后不建议长期用WEIXIN_DM_POLICYopen。更稳妥的是白名单WEIXIN_ACCOUNT_ID你的-account-id WEIXIN_DM_POLICYallowlist WEIXIN_ALLOWED_USERSuser_id_1,user_id_2 WEIXIN_GROUP_POLICYdisabled WEIXIN_HOME_CHANNEL_NAMEHomeWEIXIN_ALLOWED_USERS填的是 Weixin 用户 ID不是昵称也不是微信号。它只是入站过滤器不会自动邀请用户。每个允许的人必须先能给这个 iLink Bot 发私聊然后你从 Gateway 日志里找到发送者 ID再加进白名单。查看日志tail -f ~/.hermes/logs/gateway.log改完.env后重启 gateway# 前台运行的话 CtrlC 再重跑 hermes gateway5.4 设置 Home ChannelHome Channel 用于 cron、通知、后台任务结果推送。更简单的方法是在微信 Bot 私聊里直接发/sethome常用微信内命令命令作用/status查看当前会话状态/new新建会话/reset重置会话/model查看或切换模型/stop停止当前任务/sethome把当前聊天设为通知默认目标/help查看帮助5.5 配置后台常驻服务前台确认可用后再装 systemd 服务。用户级服务推荐用于普通服务器和开发机hermes gateway install hermes gateway start hermes gateway status查看日志journalctl --user -u hermes-gateway -f让服务在 SSH 退出后继续运行sudo loginctl enable-linger $USERVPS 或无头主机也可以用系统级服务sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system注意不要同时安装用户级和系统级 Gateway否则 start、stop、status 的行为会变得模糊。6. 本篇常见错误排查6.1 Weixin startup failed: aiohttp and cryptography are required缺依赖回到适配器目录重装cd ~/.hermes/hermes-agent uv pip install -e .[messaging]6.2 二维码不显示同样是 messaging extra 没装好重装后重新跑hermes gateway setup如果终端二维码仍不显示打开二维码上方打印出来的 URL 用手机扫。6.3 扫码成功但微信没回复先看 Gateway 是否还在运行hermes gateway status前台运行直接看终端日志用户服务用journalctl --user -u hermes-gateway -f系统服务用journalctl -u hermes-gateway -f。重点检查.env里的WEIXIN_ACCOUNT_ID、WEIXIN_DM_POLICY、WEIXIN_ALLOWED_USERS、WEIXIN_GROUP_POLICY。如果WEIXIN_DM_POLICYallowlist发送者 ID 必须在WEIXIN_ALLOWED_USERS里。6.4 提示 WEIXIN_TOKEN is required重新扫码hermes gateway setup选 Weixin 再扫一次。token 通常通过 QR login 自动保存缺失时才需要重新 setup。6.5 提示另一个 Gateway 正在使用同一个 token同一个 Weixin token 同一时间只能被一个 Gateway 实例使用。检查是否重复启动ps aux | grep hermes systemctl --user status hermes-gateway sudo systemctl status hermes-gateway停掉多余实例hermes gateway stop sudo hermes gateway stop --system6.6 出现 errcode-14这是登录会话过期重新跑 setup 扫码即可hermes gateway setup6.7 群里 机器人没反应先确认.env里是否写了WEIXIN_GROUP_POLICYopen但更关键的是看日志有没有收到群消息。如果日志完全没有 inbound group event那不是 Hermes 配置问题而是 iLink 没把普通微信群事件推给这个 Bot。QR 登录的 iLink Bot 身份通常收不到普通微信群消息个人微信建议保持WEIXIN_GROUP_POLICYdisabled。需要稳定群聊协作更建议改用企业微信 WeCom、飞书、Telegram 或 Discord。6.8 图片、文件、视频失败确认 cryptography 装好并检查网络能否访问微信 CDNcurl -I https://novac2c.cdn.weixin.qq.com/c2c媒体通过加密 CDN 传输Hermes 会自动处理 AES-128-ECB 加解密这也是必须装 cryptography 的原因。7. 接入文档与后续动作到这里从零到可用的连接闭环就跑通了。核心判断标准就四条Hermes CLI 能回复、Weixin 扫码成功、Gateway 能收到私聊、微信能收到模型回复。如果你在配置 TaoToken 的 Key 或 API 通道时卡住可以直接去 API Keys 页面生成和管理密钥https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先在网页里验证模型能不能正常回话用模型对话页面最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果你打算把 Hermes 长期挂在服务器上跑编码任务或 Agent 工作流Coding Plan 会更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后给一个我踩过的坑改完.env一定要重启 gateway前台运行就 CtrlC 重跑服务模式就hermes gateway restart否则新配置不生效你会对着旧日志怀疑人生。