Hermes Agent 安装与飞书接入实战记录：从 CLI 到 Gateway 的 TaoToken 配置

1. Hermes Agent 是什么本地 CLI 与飞书 Gateway 接入能解决什么问题Hermes Agent 是 Nous Research 开源的一套 AI Agent 框架它最大的特点是「一套 Agent 内核多平台接入」。你可以把它理解成一个住在你服务器上的智能助手它通过 CLI 在终端里跟你对话也能通过 Gateway 服务把自己挂到飞书、Telegram、Discord 这些消息平台上让你在手机飞书里就能指挥它干活。它适合谁我总结了三类人第一类是喜欢在终端里折腾、想把 LLM 能力接进自己工作流的开发者第二类是团队里想搭一个内部机器人、但又不想从零写消息网关的后端同学第三类是想给飞书群加一个能记住上下文、能跑定时任务的 Agent 的运维或产品同学。核心能力可以拆成四块。跨平台 Gateway 让同一个 Agent 同时服务多个平台飞书、Telegram、Discord 加起来支持十几种Provider 无关意味着你换模型只需要改一行配置DeepSeek、OpenAI、Anthropic 甚至自建兼容接口都能接Skills 系统让 Agent 从经验里沉淀可复用的流程持久化 Memory 则让它跨会话记住你的偏好和环境细节。但真正落地的时候坑往往不在 Agent 本身而在「LLM 通道」和「平台侧配置」这两段。LLM 通道要解决的是你的 Agent 到底调用哪个模型服务、Base URL 填什么、Key 怎么管。平台侧要解决的是飞书应用权限开没开全、事件订阅加没加、版本发布没发布。这篇记录就按「CLI 初始化 → LLM 通道配置 → Gateway 启动 → 飞书接入 → 全链路验证」的顺序把每一步的可复制配置和验证命令都写清楚。我试过在本地和 WSL 两种环境各跑一遍结论是只要 LLM 通道的 Base URL 和 Key 配对飞书侧的权限和发布别漏整个链路半小时内能通。下面直接进入操作。2. 前置准备TaoToken 的 Base URL 与 API Key 怎么拿在装 Hermes Agent 之前先把 LLM 通道准备好否则后面hermes model选完 Provider 会卡在鉴权上。这里我用 TaoToken 作为统一的大模型接入通道原因是它把多家模型的调用收敛到一个兼容接口上Base URL 和 Key 一套就够换模型不用重新申请账号。你需要准备两样东西一个 API Key一个 Base URL。Base URL 固定是https://taotoken.net/api注意这个地址后面不要带斜杠也不要自己拼/v1Hermes 的 Provider 配置里会按 OpenAI 兼容格式去拼路径多写反而会 404。拿 Key 的路径是这样打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后进控制台在 API Keys 页面创建一个新 Key。创建时建议给它起个能认出来的名字比如hermes-local方便以后按项目吊销。Key 只在创建时完整显示一次复制下来先存到安全的地方。如果你还没决定用哪个模型可以先去模型对话页面试一下手感确认这个通道能正常出结果再去配 Hermes。模型对话入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个模型发一句话能回就说明 Key 和通道都没问题。这里有个细节要注意Hermes 的 Provider 配置里Base URL 和 Key 是分开填的Key 通常放在~/.hermes/.env里Base URL 放在模型配置里。很多人第一次配的时候把完整 URL 连同/chat/completions一起填进去结果请求路径变成双份直接报 404。记住只填到/api这一层。另外如果你打算长期跑编码类或 Agent 类任务可以顺手看一下 Coding Plan它更适合高频调用场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不过这篇教程先用按量 Key 把链路跑通后面再换也不迟。准备好 Key 之后先别急着装 Hermes用一条 curl 验证通道是否通curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: deepseek-v4-pro, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道正常。如果返回 401说明 Key 不对或没带上如果返回 404多半是路径拼错了。这一步过了再往下装 Hermes 会顺很多。3. 可复制配置Hermes Agent 安装、CLI 初始化与 LLM 通道设置这一节是整篇的核心我把安装、CLI 初始化、LLM 通道配置三段拆开写每段都给可直接复制的命令或配置片段。先装 Hermes Agent。官方提供一键脚本curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash装完会自动创建~/.hermes/目录里面有配置文件、日志目录和一个独立的 venv。装完先跑一次健康检查hermes doctor它会检查依赖、Python 环境、配置文件是否齐全。如果这一步报缺依赖按提示补装即可。接下来配置 LLM 通道。Hermes 的模型配置支持交互式和命令行两种方式。交互式是hermes model在界面里选 Provider 时如果你用的是 TaoToken 这种 OpenAI 兼容通道选openai或custom这类兼容项然后填 Base URL 和模型名。但交互式容易点错我更推荐直接用命令行写配置可控性强。先编辑~/.hermes/.env把 Key 写进去echo OPENAI_API_KEYsk-你的TaoTokenKey ~/.hermes/.env echo OPENAI_BASE_URLhttps://taotoken.net/api ~/.hermes/.env注意这里变量名用的是OPENAI_API_KEY和OPENAI_BASE_URL因为 Hermes 走的是 OpenAI 兼容协议。如果你用的 Provider 名不同变量前缀可能不一样但思路一致Key 和 Base URL 成对出现。然后设置模型配置。Hermes 的配置可以用hermes config set逐项写hermes config set model.provider openai hermes config set model.default deepseek-v4-pro hermes config set model.base_url https://taotoken.net/api如果你更喜欢直接改配置文件~/.hermes/config.toml里对应的片段长这样[model] provider openai default deepseek-v4-pro base_url https://taotoken.net/api这里三件套必须齐全Base URL 指向https://taotoken.net/apiKey 放在.env的OPENAI_API_KEYModel ID 填你实际要用的模型名。三者缺一请求就会失败。Model ID 一定要和通道支持的模型名完全一致写错了会报模型不存在。配完验证一下 CLI 能不能对话hermes chat -q 你好做个自我介绍能正常返回内容说明 CLI 初始化和 LLM 通道都通了。如果报 401回去检查.env里的 Key如果报连接超时检查 Base URL 是不是写成了带/v1的完整路径。这一步过了之后再装飞书接入需要的依赖pip3 install lark-oapi websocketslark-oapi是飞书官方 SDKwebsockets是 WebSocket 长连接模式需要的。两个都装上后面 Gateway 启动才不会报缺模块。4. 飞书机器人接入与 Gateway 启动连通性测试与消息回执确认飞书这一侧是整个流程里最容易漏步骤的地方我按「建应用 → 开权限 → 订阅事件 → 发布版本 → 配 Gateway → 启动验证」的顺序写。先在飞书开放平台创建企业自建应用在「凭证与基础信息」页面拿到 App ID 和 App Secret。然后到「应用功能 → 机器人」启用机器人能力。权限这块是重灾区必须开全。进入「权限管理」至少开通这几个权限说明是否必需im:message获取与发送单聊、群组消息必需im:message.p2p_msg:readonly读取用户发给机器人的单聊消息必需im:message.group_at_msg:readonly获取群组中 机器人 的消息群聊需要im:resource获取与上传图片或文件资源必需很多人只开了im:message结果单聊完全没反应就是因为漏了im:message.p2p_msg:readonly。这个权限专门管单聊消息读取不开的话机器人收不到你私聊它的内容。接着到「开发配置 → 事件订阅」添加事件im.message.receive_v1。用 WebSocket 模式不需要配回调地址但事件必须订阅否则 Gateway 连上了也收不到消息。然后是最容易漏的一步发布版本。在「版本管理与发布 → 创建版本 → 申请发布」。飞书开放平台上修改权限和事件订阅后不重新发布版本是不生效的。我踩过的坑就是权限加完、事件也订阅了机器人还是不理人最后发现是没发布。飞书侧配完回到服务器配 Gateway。编辑~/.hermes/.env加上飞书相关配置FEISHU_APP_IDcli_你的AppID FEISHU_APP_SECRET你的AppSecret FEISHU_DOMAINfeishu FEISHU_CONNECTION_MODEwebsocket GATEWAY_ALLOW_ALL_USERStrueFEISHU_DOMAIN飞书填feishuLark 填lark。FEISHU_CONNECTION_MODE推荐websocket不需要公网 URL本地和 WSL 都能跑。GATEWAY_ALLOW_ALL_USERStrue是开发阶段用的生产环境要换成白名单。启动 Gateway先前台跑方便看日志hermes gateway run成功启动后日志里会出现✓ feishu connected Gateway running with 1 platform(s)看到这两行说明 Gateway 和飞书的长连接建起来了。这时候去飞书里找到你的机器人发一句「你好」。如果 Gateway 日志里出现info gateway.run: inbound message: platformfeishu ... info gateway.run: response ready: platformfeishu ...说明消息进来了、回复也发出去了全链路通了。飞书那边应该能收到 Hermes 的回复。如果你要后台跑WSL 环境推荐用 tmuxtmux new -s hermes hermes gateway run之后用hermes gateway status查状态hermes gateway restart重启。5. 常见报错排查401、local proxy failed、reading choices 与飞书无回执这一节按真实报错来对每个报错给出原因和解决路径。报错一401 Unauthorized。这是 LLM 通道鉴权失败。先确认.env里的OPENAI_API_KEY是不是完整的 Key有没有多余空格或换行。再确认 Base URL 是不是https://taotoken.net/api如果写成了带/v1/chat/completions的完整路径请求会打到错误地址。还有一种情况是 Key 被吊销了去控制台重新建一个。报错二local proxy failed 或 connection refused。这个通常是 Base URL 写错或网络不通。检查model.base_url是不是https://taotoken.net/api注意不要带尾部斜杠。如果本地有代理软件干扰先确认环境变量里没有残留的HTTP_PROXY之类设置。报错三reading choices 相关错误。这个报错说明请求发出去了但返回体里没有choices字段通常是模型名写错了或者通道不支持这个模型。回去核对model.default里的 Model ID 是否和通道支持的模型名完全一致。三件套里 Model ID 是最容易写错的一项。报错四飞书机器人不回复Gateway 日志显示No user allowlists configured。这是 Gateway 默认拒绝所有用户。在.env里加GATEWAY_ALLOW_ALL_USERStrue重启 Gateway。报错五加了GATEWAY_ALLOW_ALL_USERStrue还是没反应。去飞书开放平台检查权限重点看im:message.p2p_msg:readonly有没有开。单聊消息读取靠这个权限漏了就收不到。报错六权限都开了还是没反应。检查版本有没有发布。飞书修改权限和事件订阅后必须重新创建版本并发布不发布不生效。这是最隐蔽的一个坑。报错七Cron Job 投递失败日志显示no delivery target resolved for deliverall。这是没配FEISHU_HOME_CHANNEL。先在飞书给机器人发一条消息从 Gateway 日志里找到chat_id然后在.env里加FEISHU_HOME_CHANNELoc_你的chatid重启 Gateway 后deliverall就能找到投递目标了。也可以用命令行直接推送hermes send -t feishu 消息内容 hermes send -t feishu -f /path/to/message.txt排查的时候日志是最好的朋友。Gateway 日志在~/.hermes/logs/gateway.logAgent 日志在~/.hermes/logs/agent.log。用tail -f盯着看消息进来和回复出去都有记录。6. 长期运行与扩展Coding Plan、API 文档与模型对话入口链路跑通之后如果你打算长期用有几个方向可以继续。第一是换更合适的调用方案。按量 Key 适合验证和低频使用如果你要跑编码类 Agent 或高频任务可以看看 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它针对长期编码和 Agent 场景做了优化成本结构更适合持续调用。第二是把接入细节查清楚。TaoToken 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言的调用示例和参数说明。API Keys 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以按项目建多个 Key方便隔离和吊销。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 能看用量和调用记录。第三是验证模型效果。换模型之前先去模型对话页面试一下入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认新模型在你的任务上表现符合预期再改 Hermes 配置。第四是常用命令速查我整理了一份# 配置 hermes model # 交互式选模型 hermes config edit # 编辑配置 hermes doctor # 健康检查 # Gateway hermes gateway run # 前台启动 hermes gateway status # 查状态 hermes gateway restart # 重启 # Cron hermes cron list # 查看定时任务 hermes cron run id # 手动触发 # 推送 hermes send -t feishu 消息内容 hermes send -t feishu -f file.txt # 日志 tail -f ~/.hermes/logs/gateway.log tail -f ~/.hermes/logs/agent.log最后说一个实际经验整个链路里LLM 通道的三件套Base URL、Key、Model ID和飞书侧的「权限 事件 发布」是最容易出问题的两段。前者配错会报 401 或 reading choices后者漏了会表现为机器人完全不回复。把这两段按上面的清单逐项核对基本一次能通。