1. 为什么要在 WSL2 里折腾 Hermes Agent 接微信Hermes Agent 是 NousResearch 出的开源 Agent 框架它最特别的地方是带了一套闭环学习系统能把每次对话的结果沉淀下来复用。最近官方文档里多了一个微信适配器走的是腾讯 iLink Bot API也就是说不用公网 IP、不用 WebSocket、不用 Webhook普通家用宽带就能把 Agent 挂到微信上。这件事对做本地自动化的人来说吸引力很大你不需要买云服务器不需要备案域名一台常年开机的笔记本就能让 Agent 24 小时在线。但真正动手时会撞上两个坑。第一个是平台限制Hermes Agent 原生 Windows 跑不起来官方明确要求 Linux、macOS、WSL2 或 Android Termux。第二个是模型配置Hermes 支持多供应商切换如果你同时用智谱、DeepSeek、Claude 几个模型每个供应商一套 Base URL 和 Key散落在.env、config.toml、环境变量里改一次配置要翻三四个文件。我试过在 WSL2 里把这两件事一起解决——用 TaoToken 做统一 API 通道把多模型的 Base URL 和 Key 收敛成一份配置再让 Hermes 通过 iLink Bot API 连微信。这篇面向的是已经在 WSL2 里跑过 Python 项目、想给 Hermes Agent 接微信但被 Key 管理搞烦的人。读完你能拿到一份可复制的 WSL2 网络与端口配置、一份 TaoToken 统一 Key 的 auth 片段、一条微信消息触发 Agent 回复的完整验证链路以及几个真实报错的排查方法。核心检索词就三个Hermes Agent 接入微信、iLink Bot API、WSL2 环境配置。先说清楚 Hermes 接微信的机制。它用的是腾讯 QClaw 公开的 iLink Bot API 适配器扫码登录后拿到WEIXIN_ACCOUNT_ID和WEIXIN_TOKEN之后靠长轮询收消息。消息加密是 AES-128-ECBHermes 内部自动加解密你不需要自己处理。消息类型覆盖文本、图片、视频、文件、语音Markdown 会自动转成微信能显示的格式比如标题转成【标题】、表格转成键值列表。单条消息上限 4000 字符超了会按逻辑边界分片。这些能力都是适配器内置的配置里只需要关心访问策略和模型通道。模型通道这块就是 TaoToken 的用武之地。Hermes 的模型配置支持自定义 Base URL你把 TaoToken 的 API 地址填进去Key 用 TaoToken 生成的统一 Key之后切换模型只改 Model ID不用再动 Base URL 和认证信息。这样.env里跟模型相关的行数从十几行压到三行排障时也少一个变量。下面从环境准备开始一步步走完。2. TaoToken 统一 Key 与 Hermes 模型通道配置TaoToken 在这里扮演的是统一 API 网关的角色。你注册后在控制台生成一个 Key所有支持的模型都通过同一个 Base URL 访问模型区分靠请求里的 Model ID。对 Hermes 来说这意味着config.toml里的 provider 段可以只保留一份不用为每个模型供应商写一套。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 只在创建时完整显示一次丢了就重新生成。拿到后先别急着写进 Hermes用 curl 验一下通道通不通curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: glm-4-plus, messages: [{role: user, content: ping}], max_tokens: 16 }返回里如果有choices数组且content有内容说明 Key 和通道都正常。如果返回 401先检查 Key 有没有复制全、有没有多余空格。这一步单独验的好处是后面 Hermes 报错时你能确定问题出在 Hermes 配置还是通道本身。接下来是 Hermes 的模型配置。Hermes 的配置文件在~/.hermes/config.toml模型供应商段长这样。注意 Base URL 用https://taotoken.net/api/v1不要带 UTM 参数认证走 Bearer[providers.taotoken] base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY model glm-4-plus [providers.taotoken.models] glm glm-4-plus deepseek deepseek-chat claude claude-sonnet-4-20250514然后在~/.hermes/.env里放 Key不要写进 config.toml避免提交到 git 时泄露# ~/.hermes/.env TAOTOKEN_API_KEYsk-你的TaoTokenKey这里有个细节Hermes 读.env的时机是启动时改完.env必须重启 gateway 才生效。我踩过的坑是改完 Key 直接发微信消息Agent 一直不回复查日志才发现进程还在用旧的环境变量。重启命令在后面验证章节给。如果你同时用 Claude Code 或 Cline 这类工具TaoToken 的 Key 可以复用Base URL 也是同一个。Claude Code 的配置在~/.claude/settings.jsonCline 在 VS Code 设置里填 Base URL 和 KeyModel ID 按需选。这样你本地所有 AI 工具走一个通道用量和账单在一个控制台看比每个工具单独配省事。配置写完先做一次本地 dry run不接微信直接让 Hermes 用这个 provider 回一句话确认模型通道没问题cd ~/hermes-agent source .venv/bin/activate hermes chat --provider taotoken --model glm-4-plus --message 用一句话介绍你自己能打印出模型回复说明 TaoToken 通道和 Hermes 的 provider 解析都对了。这一步过了再往下接微信否则微信侧的问题会和模型侧的问题混在一起排查成本翻倍。3. WSL2 网络、端口与 iLink Bot API 可复制配置WSL2 的网络是 NAT 模式默认情况下 Windows 主机和 WSL2 之间能互通但外部设备访问 WSL2 里的服务需要端口转发。Hermes 接微信走的是长轮询是 WSL2 主动往外发请求不需要公网入站所以理论上不用配端口转发。但有两个场景需要动网络配置一是你想从 Windows 侧访问 Hermes 的本地管理端口二是 WSL2 的 DNS 或时间同步出问题导致长轮询断连。先确认 WSL2 版本和网络模式。在 PowerShell 里执行wsl --version wsl --list --verbose确保你的发行版是 WSL2 而不是 WSL1。WSL1 的网络栈和系统调用兼容性都不够Hermes 的 aiohttp 长连接在 WSL1 下会出各种奇怪问题。如果是 WSL1用wsl --set-version 发行版名 2升级。WSL2 里先装依赖。Hermes 的微信适配器需要 aiohttp 和 cryptography这两个不装会在启动时报aiohttp and cryptography are requiredsudo apt update sudo apt install -y python3 python3-pip python3-venv curl git pip install aiohttp cryptography qrcodeqrcode是为了终端显示扫码二维码不装的话终端不显示二维码得用浏览器扫码麻烦。然后装 Hermes。官方一行命令curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash安装脚本会检测已有的 OpenClaw 配置并询问是否导入。如果你之前配过 OpenClaw可以导入 SOUL、USER 设定和.env里的供应商信息。没配过就跳过。安装完成后进入 Hermes 目录激活虚拟环境cd ~/hermes-agent source .venv/bin/activate接下来配微信。先跑 gateway 的 setuphermes gateway setup它会让你选平台选 weixin然后终端显示二维码。用手机微信扫码会提示已经连接 OpenClaw是否解除点继续连接。扫码成功后WEIXIN_ACCOUNT_ID和WEIXIN_TOKEN会自动写进~/.hermes/.env。如果终端不显示二维码检查qrcode有没有装或者用hermes gateway setup --browser-qr走浏览器扫码。扫码后.env里应该有这两行# ~/.hermes/.env WEIXIN_ACCOUNT_IDyour-account-id WEIXIN_TOKENyour-bot-token访问策略按需配。私聊默认open任何人可以私聊群聊默认disabled不响应群消息。如果你担心群聊触发风控保持默认就行WEIXIN_DM_POLICYopen WEIXIN_GROUP_POLICYdisabled WEIXIN_ALLOWED_USERS WEIXIN_GROUP_ALLOWED_USERS如果只想让特定用户私聊把WEIXIN_DM_POLICY改成allowlist然后在WEIXIN_ALLOWED_USERS里填用户 ID多个用逗号分隔。用户 ID 从 Hermes 日志里能看到第一次收到消息时会打印发送者 ID。WSL2 网络这块还有一个容易忽略的点DNS 解析。WSL2 默认用 Windows 的 DNS有时候会抽风导致taotoken.net解析失败表现为长轮询超时。如果遇到在/etc/resolv.conf里加一个公共 DNSsudo tee /etc/resolv.conf /dev/null EOF nameserver 223.5.5.5 nameserver 119.29.29.29 EOF注意 WSL2 重启后/etc/resolv.conf可能被覆盖要持久化的话在/etc/wsl.conf里加[network] generateResolvConf false然后重启 WSL。这一步不是必须的只在遇到解析问题时做。端口方面Hermes 的 gateway 默认监听本地回环不对外暴露。如果你想从 Windows 侧看 Hermes 的状态页需要知道 WSL2 的 IPip addr show eth0 | grep inet拿到类似172.x.x.x的地址在 Windows 浏览器里访问http://172.x.x.x:端口。但注意 WSL2 的 IP 每次重启会变要固定的话得在 Windows 侧配端口转发用netsh interface portproxy。不过对微信接入来说这一步用不上因为长轮询是出站的。4. 验证请求一条微信消息触发 Agent 回复配置写完启动 gatewaycd ~/hermes-agent source .venv/bin/activate hermes gateway start启动日志里会打印微信适配器的初始化信息包括账号 ID、访问策略、模型 provider。看到weixin adapter ready之类的字样说明适配器加载成功。如果日志里报WEIXIN_TOKEN is required说明.env没读到检查文件路径是不是~/.hermes/.env以及有没有重启进程。启动后需要一次配对。Hermes 会在日志里打印配对码类似pairing code: E6JNGBCX在 Hermes 的对话框里输入hermes pairing approve weixin E6JNGBCX配对成功后微信侧会显示连接状态。现在用手机微信给这个 bot 发一条消息比如你好帮我列一下今天的待办。正常情况下微信里会先显示正在输入状态几秒后收到 Agent 的回复。验证的时候看三个地方。第一是 Hermes 的 gateway 日志会打印收到消息、调用模型、返回结果的完整链路。第二是 TaoToken 控制台的用量页面能看到这次请求的 token 消耗和模型。第三是微信对话框本身回复内容应该和你在本地hermes chat里得到的一致。如果消息发出去了但没回复按这个顺序查。先看 gateway 日志有没有收到消息没有的话是 iLink Bot API 侧的问题检查WEIXIN_TOKEN是否过期。收到了但没调模型检查 provider 配置和TAOTOKEN_API_KEY。调了模型但报错看错误码401 是 Key 问题404 是 Model ID 写错超时是网络问题。验证通过后你可以试试多模型切换。在微信里发用 deepseek 回答今天天气怎么样如果 Hermes 支持按消息指定模型它会走deepseek-chat。不支持的话就在 config.toml 里改默认 model重启 gateway 再试。TaoToken 的好处在这里体现切模型只改一行 Model IDBase URL 和 Key 不动。再验一个上下文持久化。发一条消息让 Agent 记住某个信息比如记住我的项目代号是 falcon然后重启 gateway再发我的项目代号是什么。如果回复 falcon说明context_token自动保存生效了。这个机制是 Hermes 内置的重启后自动续接上下文不需要额外配置。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth接微信这条链路上报错集中在几个地方。下面按真实遇到的错误对照排查。401 Unauthorized。这个最常见出现在两个位置。一是 curl 验 TaoToken 通道时说明 Key 错了或没带Bearer前缀。检查Authorization: Bearer sk-xxx格式Key 有没有复制全。二是 Hermes 调模型时说明.env里的TAOTOKEN_API_KEY没被读到。确认.env路径是~/.hermes/.env改完重启 gateway。如果 Key 是对的还报 401检查 config.toml 里api_key_env的名字和.env里的变量名是否一致大小写敏感。local proxy failed。这个报错通常出现在 WSL2 网络异常时Hermes 尝试走本地代理但连不上。先检查 WSL2 能不能解析taotoken.netnslookup taotoken.net curl -v https://taotoken.net/api/v1/models解析失败就按第 3 节的 DNS 配置改/etc/resolv.conf。如果解析正常但连接超时检查 WSL2 的防火墙或 Windows 侧的网络策略。还有一种情况是环境变量里残留了HTTP_PROXY或HTTPS_PROXYHermes 会优先走代理但代理不可用就报 local proxy failed。用env | grep -i proxy查一下有的话 unset 掉再重启。reading choices 相关报错。这个出现在 Hermes 解析模型响应时报错类似error reading choices或choices is empty。原因通常是 TaoToken 返回的响应格式和 Hermes 期望的不一致或者 Model ID 写错导致返回了错误结构。先确认 Model ID 在 TaoToken 支持列表里用 curl 单独测一次curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:glm-4-plus,messages:[{role:user,content:hi}]}如果 curl 返回正常但 Hermes 报错检查 config.toml 里 provider 段的base_url有没有多写或漏写/v1。TaoToken 的 Base URL 是https://taotoken.net/api/v1少写/v1会 404多写会 401。OAuth 相关报错。Hermes 某些 provider 走 OAuth 认证如果你在 config.toml 里混用了 OAuth 和 API Key 配置会报 OAuth token 无效。用 TaoToken 的话统一走 API Key不需要 OAuth。检查 config.toml 里有没有残留的oauth_字段删掉。如果 Hermes 启动时提示某个 provider 需要 OAuth 授权说明它没识别到你的 API Key 配置检查api_key_env指向的环境变量是否存在。微信侧报错。Session expired (errcode-14)说明扫码登录的会话过期了重新跑hermes gateway setup扫码。Another gateway is using this token说明同一个WEIXIN_TOKEN被两个 gateway 实例占用停掉多余的实例。QR code expired是二维码超时Hermes 会自动刷新最多 3 次3 次都失败就检查网络。Bot 不响应私聊检查WEIXIN_DM_POLICY是不是disabled或者白名单里没加你的用户 ID。Bot 忽略群消息是默认行为要开群聊把WEIXIN_GROUP_POLICY改成open或allowlist。媒体上传下载失败。检查cryptography有没有装以及 WSL2 能不能访问微信的媒体服务器。这个报错在发图片或文件时出现文本消息不受影响。如果只是文本场景可以先忽略。排查时养成一个习惯每次只改一个变量改完重启 gateway看日志变化。同时改多个配置出错了不知道是哪个引起的。日志级别可以在.env里调LOG_LEVELDEBUG能看到更详细的请求和响应。6. 把统一 Key 和微信入口固定下来的做法跑通之后建议把配置固化下来避免每次重启 WSL2 都要重新折腾。第一件事是把 Hermes gateway 做成 systemd 服务WSL2 支持 systemd 的话可以直接用不支持就用nohup或tmux挂后台。systemd 的 unit 文件放~/.config/systemd/user/hermes-gateway.service内容里ExecStart指向虚拟环境里的hermes gateway startEnvironmentFile指向~/.hermes/.env。这样systemctl --user start hermes-gateway就能拉起开机自启也方便。第二件事是把 TaoToken 的 Key 和 Base URL 记在一个地方。如果你同时用 Claude Code、Cline、Codex 这些工具它们的配置格式不一样但 Base URL 和 Key 是同一份。Claude Code 的settings.json里填ANTHROPIC_BASE_URL和ANTHROPIC_API_KEYCline 在设置里填 OpenAI Compatible 的 Base URL 和 KeyCodex 的auth.json里填OPENAI_API_KEY和base_url。Model ID 按各工具支持的填。这样你换 Key 的时候只改一处其他工具引用同一个值。第三件事是给微信 bot 设一个合理的访问策略。私聊用allowlist比open安全只允许你自己的用户 ID。群聊保持disabled除非你明确需要。风控这件事没有绝对安全的做法但减少暴露面总是对的。用户 ID 从日志里拿第一次发消息时会打印。最后留一个实用技巧Hermes 的context_token存在~/.hermes/下的某个文件里重启后自动续接。如果你想清空上下文重新开始找到这个文件删掉再重启 gateway。具体文件名看日志里的路径提示不同版本可能不一样。这个操作在调试时有用比如你发现 Agent 一直记着某个错误的上下文清掉就能重置。端到端跑通之后你可以把微信当成 Agent 的入口背后挂什么模型、什么工具链都由 Hermes 和 TaoToken 这层统一管理。本地 WSL2 负责跑进程TaoToken 负责模型通道iLink Bot API 负责消息收发三层各管各的出问题也好定位。