1. 为什么要在 Linux 上把 Hermes Agent 接进企业微信Hermes Agent 是 Nous Research 开源的一个 AI Agent 框架它能从对话经验里自动沉淀技能、跨会话保留记忆并且原生支持 Telegram、Discord、Slack、企业微信、飞书、钉钉等一堆消息平台。如果你所在团队已经在用企业微信办公最省事的做法就是把它接成企业微信里的一个 AI Bot同事在企微里直接发消息Agent 在后台跑推理回复再推回企微会话整个过程不需要公网 IP也不需要单独开发一个前端。这篇教程聚焦的场景很具体一台 Linux 服务器Ubuntu 20.04 及以上都行从零部署 Hermes Agent用 WebSocket 长连接方式对接企业微信 AI Bot并且把 LLM 通道统一收敛到 TaoToken 的 API 上。适合需要私有化接入企业微信的运维和后端同学跟着做能一次跑通机器人收发消息。我会给出可直接复制的config.toml与settings.json骨架、TaoToken 统一 Key 的接入位置以及消息回调的连通性验证动作。需要提前说明的是Hermes Agent 本身支持多种 LLM 提供商但如果你希望用一个 Key 就能在 Claude、GPT、GLM、Kimi 等模型之间切换用 TaoToken 的 API 通道会省掉反复改环境变量的麻烦。下面所有配置都以这个思路展开。2. 环境准备与 TaoToken 前置配置2.1 系统与依赖检查先确认基础环境。Hermes Agent 要求 Python 3.11 或更高版本推荐用uv作为包管理器它比 pip 快很多依赖解析也更稳。python3 --version # 期望输出Python 3.11.x 或更高 which uv # 如果没有输出说明 uv 未安装如果uv没装执行官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc uv --version网络方面你需要能访问 PyPI 和 GitHub。国内环境建议提前配好镜像后面安装依赖时会用到清华源。2.2 获取 TaoToken API Key在开始配置 Hermes 之前先把 LLM 通道准备好。打开 TaoToken 官网注册账号进入控制台创建 API Key。这个 Key 后面会写进 Hermes 的.env文件作为统一的模型调用凭证。创建 Key 的入口在控制台的 API Keys 页面生成后复制保存它只会完整显示一次。TaoToken 的 API 基地址是https://taotoken.net/api兼容 OpenAI 风格的调用格式所以 Hermes 里只要把base_url指向它、把 Key 填进去就能用。如果你后续想长期跑编码类或 Agent 类任务可以关注一下 Coding Plan它针对高频调用场景做了额度优化比按量计费更适合常驻的机器人。模型对话入口则适合先手动验证某个模型是否可用再写进配置。2.3 企业微信侧准备登录企业微信管理后台进入「应用管理」找到「AI 助手」或搜索「AI Bot」创建一个新的 AI Bot。创建完成后记录两个值Bot ID 和 Secret。这两个值在 Hermes 的配置里对应WECOM_BOT_ID和WECOM_SECRET。WebSocket 地址默认是wss://openws.work.weixin.qq.com国内可直连不需要改。这一点是 AI Bot 模式相比自建应用回调模式的最大优势——不用公网 IP不用配回调 URL省掉一堆证书和端口映射的麻烦。3. 安装 Hermes Agent 并写入配置骨架3.1 克隆代码与安装依赖仓库体积不小含文档和资源文件建议用浅克隆只拉最新代码cd ~ git clone --depth 1 https://github.com/NousResearch/hermes-agent.git cd hermes-agent然后创建虚拟环境并安装依赖。这里用清华镜像源避免 PyPI 超时uv venv venv source venv/bin/activate uv pip install -e .[messaging,cron,cli,pty,mcp,dev] \ -i https://pypi.tuna.tsinghua.edu.cn/simple/ \ --trusted-host pypi.tuna.tsinghua.edu.cn安装完成后验证企业微信模块是否就绪python -c from gateway.platforms.wecom import check_wecom_requirements; print(OK:, check_wecom_requirements()) # 期望输出OK: True3.2 config.toml 骨架Hermes 的模型配置可以放在~/.hermes/config.toml部分版本也兼容config.yaml以你安装的版本为准。下面这份骨架把 LLM 通道指向 TaoToken并把企业微信 AI Bot 的开关打开# ~/.hermes/config.toml [model] default claude-sonnet-4-6 provider openai base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [platforms.wecom] enabled true websocket_url wss://openws.work.weixin.qq.com dm_policy open group_policy open [platforms.wecom.extra] bot_id 你的Bot_ID secret 你的Secret几个关键点解释一下。provider写openai是因为 TaoToken 的接口兼容 OpenAI 格式Hermes 会按这个协议发请求。base_url指向https://taotoken.net/api注意这里不带任何查询参数。api_key_env指定从环境变量读取 Key这样 Key 不会硬编码进配置文件更安全。dm_policy和group_policy都设为open表示私聊和群聊都允许触发。如果你只想让特定人用可以改成白名单模式具体取值参考官方文档。3.3 settings.json 骨架除了 TOMLHermes 的部分运行时设置走settings.json。这份骨架控制网关行为和日志级别{ gateway: { host: 0.0.0.0, port: 8645, log_level: info, reconnect_interval: 5 }, agent: { max_history: 50, memory_enabled: true, skill_autocreate: true }, wecom: { heartbeat_interval: 30, message_timeout: 60 } }reconnect_interval是 WebSocket 断线后的重连间隔单位秒。heartbeat_interval是心跳间隔企业微信长连接对心跳有要求设成 30 秒比较稳。memory_enabled和skill_autocreate是 Hermes 的自学习特性开关建议保持开启。3.4 环境变量文件在项目根目录创建.env把敏感信息集中放这里# ~/hermes-agent/.env TAOTOKEN_API_KEY你的TaoToken密钥 WECOM_BOT_ID你的Bot_ID WECOM_SECRET你的Secret WECOM_HOME_CHANNEL你的用户ID.env里的值会覆盖config.toml中的同名配置所以 Bot ID 和 Secret 你只需要配一处。WECOM_HOME_CHANNEL是可选的用于 cron 定时任务的默认发送目标不跑定时任务可以不填。4. 启动网关并验证消息收发4.1 启动前自检先跑一次诊断命令确认配置没有语法错误、依赖没有缺失source venv/bin/activate hermes doctor输出里会分模块列出检查项重点看 WeCom 部分是否显示配置正确、API Key 是否可读。如果这里报错先别急着启动网关按提示修完再继续。4.2 启动网关首次使用直接运行hermes gateway它会以交互式菜单启动你可以选前台运行方便看日志。启动成功的日志里应该出现类似内容[WeCom] Connected via WebSocket to wss://openws.work.weixin.qq.com [WeCom] Authentication successful看到Authentication successful就说明长连接建立成功、鉴权通过了。这里有个坑要提前说不要一上来就用hermes gateway start。这个命令会尝试通过 systemd 启动后台服务但首次使用时服务单元还没安装会报Unit hermes-gateway.service not found。如果你确实需要后台常驻先跑hermes gateway install安装服务单元再用start。4.3 验证请求与成功结果网关跑起来后打开企业微信找到你创建的那个 AI Bot发一条消息比如「你好介绍一下你自己」。正常情况下几秒内会收到回复。如果没回复先看网关日志有没有收到消息事件。日志里应该出现类似[WeCom] Received message from ...的行。有收到但没回复说明 LLM 调用出了问题检查 TaoToken 的 Key 和base_url是否正确。完全没收到说明 WebSocket 连接或 Bot 配置有问题回到hermes doctor排查。你也可以用 TaoToken 的模型对话入口先单独验证 Key 是否可用在网页里选一个模型发一句话能正常返回就说明 Key 和通道没问题问题在 Hermes 侧。4.4 快捷启动脚本每次手动激活虚拟环境再启动有点烦写个脚本#!/bin/bash # ~/hermes-agent/start.sh cd ~/hermes-agent source venv/bin/activate hermes gatewaychmod x start.sh ./start.sh5. 本篇常见错误排查5.1 依赖安装超时或版本找不到现象是operation timed out或No solution found when resolving dependencies。前者是 PyPI 直连不稳后者多半是镜像源同步不全。解决办法统一用清华源别用阿里云源阿里云对openai2.21.0这类新版本包同步不及时会直接报无解。uv pip install -e .[messaging,cron,cli,pty,mcp,dev] \ -i https://pypi.tuna.tsinghua.edu.cn/simple/ \ --trusted-host pypi.tuna.tsinghua.edu.cn5.2 网关启动报 systemd 服务不存在报错长这样Failed to start hermes-gateway.service: Unit hermes-gateway.service not found.原因前面说过start依赖 systemd 服务单元。首次直接用hermes gateway前台跑或者先hermes gateway install再start。5.3 WebSocket 连不上或频繁断线先确认服务器能解析并访问openws.work.weixin.qq.com。如果日志里反复出现重连检查settings.json里的heartbeat_interval是不是设得太长30 秒是稳妥值。另外确认 Bot ID 和 Secret 没有多余空格从后台复制时容易带上换行。5.4 消息收到但模型不回复这种多半是 LLM 通道的问题。检查.env里的TAOTOKEN_API_KEY是否有效config.toml里的base_url是不是https://taotoken.net/api注意不要多加路径。如果用的是某个特定模型名确认 TaoToken 侧支持这个模型标识。可以先用模型对话入口验证 Key再回来查 Hermes 配置。5.5 群聊里 机器人没反应检查group_policy是否为open。如果设成了白名单模式需要把群 ID 加进去。另外企业微信 AI Bot 在群里的触发方式可能要求 提及确认你的操作符合后台配置的触发规则。6. 把 Key 和文档入口收好后续扩展更顺配置跑通之后建议把几个入口存进书签后面调模型、加平台、排障都用得上。TaoToken 的 API Key 管理在控制台的 API Keys 页面接入文档里有完整的参数说明和示例请求遇到base_url或鉴权头的问题直接查文档最快。如果你打算让这个机器人长期跑编码或 Agent 任务Coding Plan 的额度模型比按量计费更划算适合常驻场景。Hermes Agent 本身还支持 Telegram、飞书、钉钉等平台配置结构和企业微信类似都是platforms.name下面加一段。等你把企微这条链路跑顺了加其他平台基本就是复制粘贴改几个字段的事。真正容易踩坑的地方集中在依赖安装和长连接鉴权这两块把这两处的一次性配置固化进脚本和.env后面重启机器、迁移服务器都能几分钟恢复。
1. 为什么要在 Linux 上把 Hermes Agent 接进企业微信Hermes Agent 是 Nous Research 开源的一个 AI Agent 框架它能从对话经验里自动沉淀技能、跨会话保留记忆并且原生支持 Telegram、Discord、Slack、企业微信、飞书、钉钉等一堆消息平台。如果你所在团队已经在用企业微信办公最省事的做法就是把它接成企业微信里的一个 AI Bot同事在企微里直接发消息Agent 在后台跑推理回复再推回企微会话整个过程不需要公网 IP也不需要单独开发一个前端。这篇教程聚焦的场景很具体一台 Linux 服务器Ubuntu 20.04 及以上都行从零部署 Hermes Agent用 WebSocket 长连接方式对接企业微信 AI Bot并且把 LLM 通道统一收敛到 TaoToken 的 API 上。适合需要私有化接入企业微信的运维和后端同学跟着做能一次跑通机器人收发消息。我会给出可直接复制的config.toml与settings.json骨架、TaoToken 统一 Key 的接入位置以及消息回调的连通性验证动作。需要提前说明的是Hermes Agent 本身支持多种 LLM 提供商但如果你希望用一个 Key 就能在 Claude、GPT、GLM、Kimi 等模型之间切换用 TaoToken 的 API 通道会省掉反复改环境变量的麻烦。下面所有配置都以这个思路展开。2. 环境准备与 TaoToken 前置配置2.1 系统与依赖检查先确认基础环境。Hermes Agent 要求 Python 3.11 或更高版本推荐用uv作为包管理器它比 pip 快很多依赖解析也更稳。python3 --version # 期望输出Python 3.11.x 或更高 which uv # 如果没有输出说明 uv 未安装如果uv没装执行官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc uv --version网络方面你需要能访问 PyPI 和 GitHub。国内环境建议提前配好镜像后面安装依赖时会用到清华源。2.2 获取 TaoToken API Key在开始配置 Hermes 之前先把 LLM 通道准备好。打开 TaoToken 官网注册账号进入控制台创建 API Key。这个 Key 后面会写进 Hermes 的.env文件作为统一的模型调用凭证。创建 Key 的入口在控制台的 API Keys 页面生成后复制保存它只会完整显示一次。TaoToken 的 API 基地址是https://taotoken.net/api兼容 OpenAI 风格的调用格式所以 Hermes 里只要把base_url指向它、把 Key 填进去就能用。如果你后续想长期跑编码类或 Agent 类任务可以关注一下 Coding Plan它针对高频调用场景做了额度优化比按量计费更适合常驻的机器人。模型对话入口则适合先手动验证某个模型是否可用再写进配置。2.3 企业微信侧准备登录企业微信管理后台进入「应用管理」找到「AI 助手」或搜索「AI Bot」创建一个新的 AI Bot。创建完成后记录两个值Bot ID 和 Secret。这两个值在 Hermes 的配置里对应WECOM_BOT_ID和WECOM_SECRET。WebSocket 地址默认是wss://openws.work.weixin.qq.com国内可直连不需要改。这一点是 AI Bot 模式相比自建应用回调模式的最大优势——不用公网 IP不用配回调 URL省掉一堆证书和端口映射的麻烦。3. 安装 Hermes Agent 并写入配置骨架3.1 克隆代码与安装依赖仓库体积不小含文档和资源文件建议用浅克隆只拉最新代码cd ~ git clone --depth 1 https://github.com/NousResearch/hermes-agent.git cd hermes-agent然后创建虚拟环境并安装依赖。这里用清华镜像源避免 PyPI 超时uv venv venv source venv/bin/activate uv pip install -e .[messaging,cron,cli,pty,mcp,dev] \ -i https://pypi.tuna.tsinghua.edu.cn/simple/ \ --trusted-host pypi.tuna.tsinghua.edu.cn安装完成后验证企业微信模块是否就绪python -c from gateway.platforms.wecom import check_wecom_requirements; print(OK:, check_wecom_requirements()) # 期望输出OK: True3.2 config.toml 骨架Hermes 的模型配置可以放在~/.hermes/config.toml部分版本也兼容config.yaml以你安装的版本为准。下面这份骨架把 LLM 通道指向 TaoToken并把企业微信 AI Bot 的开关打开# ~/.hermes/config.toml [model] default claude-sonnet-4-6 provider openai base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [platforms.wecom] enabled true websocket_url wss://openws.work.weixin.qq.com dm_policy open group_policy open [platforms.wecom.extra] bot_id 你的Bot_ID secret 你的Secret几个关键点解释一下。provider写openai是因为 TaoToken 的接口兼容 OpenAI 格式Hermes 会按这个协议发请求。base_url指向https://taotoken.net/api注意这里不带任何查询参数。api_key_env指定从环境变量读取 Key这样 Key 不会硬编码进配置文件更安全。dm_policy和group_policy都设为open表示私聊和群聊都允许触发。如果你只想让特定人用可以改成白名单模式具体取值参考官方文档。3.3 settings.json 骨架除了 TOMLHermes 的部分运行时设置走settings.json。这份骨架控制网关行为和日志级别{ gateway: { host: 0.0.0.0, port: 8645, log_level: info, reconnect_interval: 5 }, agent: { max_history: 50, memory_enabled: true, skill_autocreate: true }, wecom: { heartbeat_interval: 30, message_timeout: 60 } }reconnect_interval是 WebSocket 断线后的重连间隔单位秒。heartbeat_interval是心跳间隔企业微信长连接对心跳有要求设成 30 秒比较稳。memory_enabled和skill_autocreate是 Hermes 的自学习特性开关建议保持开启。3.4 环境变量文件在项目根目录创建.env把敏感信息集中放这里# ~/hermes-agent/.env TAOTOKEN_API_KEY你的TaoToken密钥 WECOM_BOT_ID你的Bot_ID WECOM_SECRET你的Secret WECOM_HOME_CHANNEL你的用户ID.env里的值会覆盖config.toml中的同名配置所以 Bot ID 和 Secret 你只需要配一处。WECOM_HOME_CHANNEL是可选的用于 cron 定时任务的默认发送目标不跑定时任务可以不填。4. 启动网关并验证消息收发4.1 启动前自检先跑一次诊断命令确认配置没有语法错误、依赖没有缺失source venv/bin/activate hermes doctor输出里会分模块列出检查项重点看 WeCom 部分是否显示配置正确、API Key 是否可读。如果这里报错先别急着启动网关按提示修完再继续。4.2 启动网关首次使用直接运行hermes gateway它会以交互式菜单启动你可以选前台运行方便看日志。启动成功的日志里应该出现类似内容[WeCom] Connected via WebSocket to wss://openws.work.weixin.qq.com [WeCom] Authentication successful看到Authentication successful就说明长连接建立成功、鉴权通过了。这里有个坑要提前说不要一上来就用hermes gateway start。这个命令会尝试通过 systemd 启动后台服务但首次使用时服务单元还没安装会报Unit hermes-gateway.service not found。如果你确实需要后台常驻先跑hermes gateway install安装服务单元再用start。4.3 验证请求与成功结果网关跑起来后打开企业微信找到你创建的那个 AI Bot发一条消息比如「你好介绍一下你自己」。正常情况下几秒内会收到回复。如果没回复先看网关日志有没有收到消息事件。日志里应该出现类似[WeCom] Received message from ...的行。有收到但没回复说明 LLM 调用出了问题检查 TaoToken 的 Key 和base_url是否正确。完全没收到说明 WebSocket 连接或 Bot 配置有问题回到hermes doctor排查。你也可以用 TaoToken 的模型对话入口先单独验证 Key 是否可用在网页里选一个模型发一句话能正常返回就说明 Key 和通道没问题问题在 Hermes 侧。4.4 快捷启动脚本每次手动激活虚拟环境再启动有点烦写个脚本#!/bin/bash # ~/hermes-agent/start.sh cd ~/hermes-agent source venv/bin/activate hermes gatewaychmod x start.sh ./start.sh5. 本篇常见错误排查5.1 依赖安装超时或版本找不到现象是operation timed out或No solution found when resolving dependencies。前者是 PyPI 直连不稳后者多半是镜像源同步不全。解决办法统一用清华源别用阿里云源阿里云对openai2.21.0这类新版本包同步不及时会直接报无解。uv pip install -e .[messaging,cron,cli,pty,mcp,dev] \ -i https://pypi.tuna.tsinghua.edu.cn/simple/ \ --trusted-host pypi.tuna.tsinghua.edu.cn5.2 网关启动报 systemd 服务不存在报错长这样Failed to start hermes-gateway.service: Unit hermes-gateway.service not found.原因前面说过start依赖 systemd 服务单元。首次直接用hermes gateway前台跑或者先hermes gateway install再start。5.3 WebSocket 连不上或频繁断线先确认服务器能解析并访问openws.work.weixin.qq.com。如果日志里反复出现重连检查settings.json里的heartbeat_interval是不是设得太长30 秒是稳妥值。另外确认 Bot ID 和 Secret 没有多余空格从后台复制时容易带上换行。5.4 消息收到但模型不回复这种多半是 LLM 通道的问题。检查.env里的TAOTOKEN_API_KEY是否有效config.toml里的base_url是不是https://taotoken.net/api注意不要多加路径。如果用的是某个特定模型名确认 TaoToken 侧支持这个模型标识。可以先用模型对话入口验证 Key再回来查 Hermes 配置。5.5 群聊里 机器人没反应检查group_policy是否为open。如果设成了白名单模式需要把群 ID 加进去。另外企业微信 AI Bot 在群里的触发方式可能要求 提及确认你的操作符合后台配置的触发规则。6. 把 Key 和文档入口收好后续扩展更顺配置跑通之后建议把几个入口存进书签后面调模型、加平台、排障都用得上。TaoToken 的 API Key 管理在控制台的 API Keys 页面接入文档里有完整的参数说明和示例请求遇到base_url或鉴权头的问题直接查文档最快。如果你打算让这个机器人长期跑编码或 Agent 任务Coding Plan 的额度模型比按量计费更划算适合常驻场景。Hermes Agent 本身还支持 Telegram、飞书、钉钉等平台配置结构和企业微信类似都是platforms.name下面加一段。等你把企微这条链路跑顺了加其他平台基本就是复制粘贴改几个字段的事。真正容易踩坑的地方集中在依赖安装和长连接鉴权这两块把这两处的一次性配置固化进脚本和.env后面重启机器、迁移服务器都能几分钟恢复。
