企业官网建设流程全解析

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-ECB，Hermes 内部自动加解密，你不需要自己处理。消息类型覆盖文本、图片、视频、文件、语音，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_KEY=sk-你的TaoTokenKey

这里有个细节：Hermes 读.env的时机是启动时，改完.env必须重启 gateway 才生效。我踩过的坑是改完 Key 直接发微信消息，Agent 一直不回复，查日志才发现进程还在用旧的环境变量。重启命令在后面验证章节给。

如果你同时用 Claude Code 或 Cline 这类工具，TaoToken 的 Key 可以复用，Base URL 也是同一个。Claude Code 的配置在~/.claude/settings.json，Cline 在 VS Code 设置里填 Base URL 和 Key，Model 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 required：

sudo apt update sudo apt install -y python3 python3-pip python3-venv curl git pip install aiohttp cryptography qrcode

qrcode是为了终端显示扫码二维码，不装的话终端不显示二维码，得用浏览器扫码，麻烦。

然后装 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 的 setup：

hermes gateway setup

它会让你选平台，选 weixin，然后终端显示二维码。用手机微信扫码，会提示"已经连接 OpenClaw，是否解除"，点"继续连接"。扫码成功后WEIXIN_ACCOUNT_ID和WEIXIN_TOKEN会自动写进~/.hermes/.env。如果终端不显示二维码，检查qrcode有没有装，或者用hermes gateway setup --browser-qr走浏览器扫码。

扫码后.env里应该有这两行：

# ~/.hermes/.env WEIXIN_ACCOUNT_ID=your-account-id WEIXIN_TOKEN=your-bot-token

访问策略按需配。私聊默认open，任何人可以私聊；群聊默认disabled，不响应群消息。如果你担心群聊触发风控，保持默认就行：

WEIXIN_DM_POLICY=open WEIXIN_GROUP_POLICY=disabled 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里加一个公共 DNS：

sudo 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 的 IP：

ip addr show eth0 | grep inet

拿到类似172.x.x.x的地址，在 Windows 浏览器里访问http://172.x.x.x:端口。但注意 WSL2 的 IP 每次重启会变，要固定的话得在 Windows 侧配端口转发，用netsh interface portproxy。不过对微信接入来说，这一步用不上，因为长轮询是出站的。

4. 验证请求：一条微信消息触发 Agent 回复

配置写完，启动 gateway：

cd ~/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 ID，Base 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.net：

nslookup taotoken.net curl -v https://taotoken.net/api/v1/models

解析失败就按第 3 节的 DNS 配置改/etc/resolv.conf。如果解析正常但连接超时，检查 WSL2 的防火墙或 Windows 侧的网络策略。还有一种情况是环境变量里残留了HTTP_PROXY或HTTPS_PROXY，Hermes 会优先走代理，但代理不可用就报 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_LEVEL=DEBUG，能看到更详细的请求和响应。

6. 把统一 Key 和微信入口固定下来的做法

跑通之后，建议把配置固化下来，避免每次重启 WSL2 都要重新折腾。第一件事是把 Hermes gateway 做成 systemd 服务，WSL2 支持 systemd 的话可以直接用，不支持就用nohup或tmux挂后台。systemd 的 unit 文件放~/.config/systemd/user/hermes-gateway.service，内容里ExecStart指向虚拟环境里的hermes gateway start，EnvironmentFile指向~/.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_KEY，Cline 在设置里填 OpenAI Compatible 的 Base URL 和 Key，Codex 的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 负责消息收发，三层各管各的，出问题也好定位。