Hermes-Agent 安装全记录：WSL2 下接 DeepSeek 与飞书 WebSocket 的 TaoToken 配置骨架

1. 为什么要在 WSL2 里跑 Hermes-AgentHermes-Agent 是 Nous Research 开源的自进化 AI Agent 框架核心卖点是记忆系统和技能生态——用得越久越贴合你的习惯。它支持飞书接入而且走的是 WebSocket 长连接不需要公网 IP这对本地开发环境来说省掉了内网穿透那一整套麻烦事。但它的安装链路比较长WSL2 Ubuntu → Python/Node 依赖 → Hermes 本体 → 模型 API → 飞书 Bot 通道。任何一环配置错位最后表现都是「飞书里发消息没反应」排查起来很费时间。这篇记录的是我在 WSL2 下从零装 Hermes-Agent、接 DeepSeek、打通飞书 WebSocket 的完整过程。重点放在两块一是可复制的config.toml与settings.json骨架二是把模型调用统一收敛到 TaoToken 的 API 通道上这样后面换模型、加通道都不用改 Hermes 本体配置。适合谁看Windows 上想跑本地 Agent 服务、又不想折腾公网 IP 的开发者已经在用 DeepSeek 但想把模型入口统一管理的飞书 Bot 配了一半卡在 WebSocket 连不上的。前置条件就四样Windows 10/11 开了 WSL2、一个 DeepSeek 或 TaoToken 的 Key、飞书开放平台账号、能正常访问 GitHub 和 PyPI 的网络。下面按顺序来。2. TaoToken 前置统一 Key 与 API 通道Hermes-Agent 默认直连 DeepSeek 的https://api.deepseek.com/v1。能跑但有两个问题一是 Key 散落在.env里换模型要改多处二是后面想加 Claude、Qwen 之类的通道得逐个改 Hermes 的 provider 配置。我的做法是把模型入口统一走 TaoToken 的 API 通道Hermes 只认一个 Base URL 和一个 Key。这样config.toml里的 provider 段保持稳定换模型只改model字段。先拿 Key。打开控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2在 API Keys 页面创建一个新 Key复制出来。注意两点Key 只在创建时完整显示一次关掉页面就看不到了创建时如果让你选权限范围本地 Agent 场景给对话补全权限就够不需要开管理类权限。拿到 Key 后API 入口是https://taotoken.net/api这个地址不加任何查询参数直接作为 OpenAI 兼容的 Base URL 用。Hermes 的 provider 配置里填https://taotoken.net/api/v1即可OpenAI 兼容协议默认带/v1路径。注意Key 不要写进会提交到 Git 的文件。Hermes 的.env默认在~/.hermes/下这个目录不在任何仓库里相对安全但也别手动复制到项目目录。如果你后面要长期跑编码类 Agent 任务可以顺带看下 Coding Plan 的额度说明https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2接入文档在这里provider 字段对不上时查这个https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl23. 可复制配置config.toml 与 settings.json 骨架3.1 安装 WSL2 与 Hermes 本体管理员 PowerShell 里执行wsl --install -d Ubuntu重启后从开始菜单进 Ubuntu建 Linux 用户名和密码输密码时不显示字符正常。如果镜像下载卡在 Provisioning直接从 Microsoft Store 装 Ubuntu快很多。进 WSL 后先确认网络curl -I https://github.com 21 | head -3返回HTTP/2 200就继续。不通的话先查/etc/resolv.conf的 DNS 和 Windows 防火墙别急着往下装。装 Hermescurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash10 到 20 分钟自动装 Python 3.11、Node.js 和依赖。如果卡在Installing TUI dependencies超过 20 分钟CtrlC 跳过TUI 不影响核心功能。修权限sudo chmod -R 755 /root/.local/share/uv/ sudo chmod 755 /root hermes --version3.2 config.toml 骨架Hermes 的主配置在~/.hermes/config.toml。下面是我实测能跑通的骨架provider 指向 TaoToken# ~/.hermes/config.toml [agent] name hermes-local default_model deepseek-chat memory_enabled true skills_dir ~/.hermes/skills [providers.taotoken] type openai base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY models [deepseek-chat, deepseek-reasoner] [gateway] enabled true platform feishu connection websocket dm_policy pairing group_policy mention [gateway.feishu] app_id_env FEISHU_APP_ID app_secret_env FEISHU_APP_SECRET几个字段说明api_key_env指向环境变量名而不是直接写 Key这样配置文件可以随便备份connection websocket是飞书免公网 IP 的关键dm_policy pairing表示私聊需要配对码审批防止别人乱发消息触发你的额度。3.3 settings.json 骨架部分版本 Hermes 用settings.json存运行时参数和config.toml分工是toml 管结构json 管开关和阈值。骨架如下{ runtime: { log_level: info, request_timeout: 60, max_retries: 3 }, feishu: { reconnect_interval: 5, heartbeat_interval: 30, event_types: [im.message.receive_v1] }, model: { temperature: 0.7, max_tokens: 4096, stream: true } }event_types只订阅im.message.receive_v1别全开不然飞书推一堆无关事件过来日志会很难看。heartbeat_interval是 WebSocket 心跳30 秒比较稳太短会被飞书限流。3.4 环境变量Key 和飞书凭证写进~/.hermes/.envTAOTOKEN_API_KEY你的TaoTokenKey FEISHU_APP_IDcli_xxxxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxx飞书的 App ID 和 Secret 在开放平台应用详情页的「凭证与基础信息」里。创建应用时记得开「机器人」能力事件订阅方式选「长连接」而不是「Webhook 地址」——选错了后面 WebSocket 根本连不上。4. 验证请求从模型连通到飞书长连接4.1 先验模型通道配置写完别急着启网关先单独验模型能不能通hermes doctor正常输出里 provider 那行应该是绿的✓ TaoToken (deepseek-chat) - 312ms ✓ Memory system - ok ✓ Skills loaded: 12如果显示invalid API key先查.env里有没有多余空格或换行。用这条快速替换sed -i s/^TAOTOKEN_API_KEY.*/TAOTOKEN_API_KEY你的新Key/ ~/.hermes/.env想单独测一下 API 通道本身直接 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]}返回带choices字段的 JSON 就说明通道没问题问题在 Hermes 配置侧。4.2 启网关并验飞书长连接hermes gateway restart看日志里 WebSocket 握手那几行tail -f ~/.hermes/logs/gateway.log成功的话会看到[feishu] websocket connecting... [feishu] handshake ok, conn_idxxxx [feishu] heartbeat started, interval30s [gateway] ready, listening for events然后去飞书找你的 Bot 发一条消息会收到配对码。终端里审批hermes pairing approve feishu 配对码配对成功后飞书里再发消息Agent 就会回复了。这一步跑通说明 WebSocket 事件通道、模型调用、记忆系统三条链路全通了。4.3 验证记忆是否生效Hermes 的记忆系统是它的核心。测一下飞书里告诉它「我叫张三在做 Python 后端」然后新开一个会话问「我叫什么」。能答出来说明记忆写入和召回都正常。如果答不出来查memory_enabled是不是true以及~/.hermes/memory/目录有没有写权限。5. 本篇常见错排查5.1 WebSocket 连不上日志报 handshake failed最常见的原因是飞书应用的事件订阅方式选成了「Webhook 地址」。去开放平台「事件与回调」页面把订阅方式改成「长连接」。改完要重新发布应用版本不发布不生效。另一个原因是 App ID 和 Secret 填反了。cli_开头的是 App ID另一串是 Secret别搞混。5.2 hermes doctor 显示 provider 超时先确认 WSL2 内能访问https://taotoken.netcurl -I https://taotoken.net/api 21 | head -3不通就是 WSL2 网络问题查 DNS。通但 doctor 超时多半是base_url写错了——注意要带/v1写成https://taotoken.net/api会 404。5.3 Permission denied: bad interpreter安装脚本以 root 跑普通用户访问不了 venv 里的 Python。执行sudo chmod -R 755 /root/.local/share/uv/ sudo chmod 755 /root5.4 Gateway already running之前启过没关干净hermes gateway restart还不行就hermes gateway stop再start。5.5 飞书发消息没反应但日志显示 ready检查settings.json里的event_types有没有包含im.message.receive_v1。另外群聊里默认要 机器人才回复这是group_policy mention控制的私聊不受影响。5.6 模型回复截断max_tokens设太小。DeepSeek 的deepseek-chat支持到 8K 输出settings.json里调到 4096 以上。如果还是截断看是不是stream开了但客户端没处理流式分片。6. 后续怎么用模型切换与通道扩展配置骨架搭好之后日常维护其实很轻。切模型只改config.toml里的default_modelprovider 段不用动——这就是把入口收敛到 TaoToken 的好处。想加新模型在providers.taotoken.models数组里补上模型名就行。飞书那边如果后面要加群聊自动回复、或者接多个 Botgateway.feishu段可以复制成多份各自用不同的 App ID。Hermes 支持同时跑多个 gateway 实例。验证模型对话效果可以直接在网页端试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2管理 Key 和查看用量在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contenthermes_wsl2最后提一个实际经验Hermes 的日志默认只保留 7 天排查历史问题时容易丢线索。可以在settings.json里把log_level临时调到debug复现完再调回info不然日志量会涨得很快。