企业官网建设流程全解析

Hermes Agent 网关连上飞书后机器人不回复，先别反复改飞书事件——打开 TaoToken 官网（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=）创建模型通道 Key，再回到服务器补 ~/.hermes/config.yaml 的模型段。本文针对的正是这种排障场景：云端已经执行 hermes gateway run 或 hermes gateway start，日志里能看到 feishu gateway started、websocket connection established，飞书开放平台的 App ID、App Secret、im.message.receive_v1 事件、WebSocket 长连接模式也都配好了，但用户在单聊里发“您好”或在群里 @ 机器人发“/help”时，机器人没有任何回复。飞书网关负责把消息接进来，模型通道负责把回复生成出去；只完成前者，Hermes Agent 就像只接通了电话线但没有大脑，消息能到达却无法返回内容。TaoToken 在这里的角色是提供模型 Key 和 Base URL，飞书凭证依旧在飞书开放平台获取，两者不要混。下面按云端服务器上的实际修改顺序，把 ~/.hermes/config.yaml 的模型段补齐，并用 hermes gateway restart 验证。

原问题与场景：Hermes Agent 飞书网关已连上，机器人却无回复

这个排障场景的关键特征很明确：飞书侧看起来已经通了，服务器侧看起来也已经启动成功。执行 hermes gateway run 时终端持续输出日志，执行 hermes gateway start 后进程常驻；日志中出现了 feishu gateway started、websocket connection established，说明 Hermes Agent 已经作为飞书应用的长连接客户端连上开放平台。此时如果只看到连接成功，就误以为整条链路都完成，很容易忽略后面还有模型调用这一段。

飞书开放平台里的配置只解决“消息怎么到 Hermes Agent”的问题。App ID、App Secret 用来确认机器人身份，im.message.receive_v1 用来订阅接收消息事件，WebSocket 长连接模式让云端服务器不需要暴露公网回调地址。但消息到达 Hermes Agent 之后，Agent 还要把用户输入交给模型，拿到模型回复，再把回复通过飞书机器人发回去。如果 ~/.hermes/config.yaml 里只有飞书网关段，没有模型通道段，或者模型段的 Base URL、API Key、模型 ID 不正确，就会出现一种很迷惑的现象：飞书消息已经进来了，日志里也能看到消息接收，但机器人就是不回复，或者只回复一个空内容、错误提示。

更准确地说，可以按日志分成两类。第一类：日志只有 websocket 连接成功，没有出现消息接收相关记录。这种通常要回查飞书权限、事件订阅、应用发布范围、机器人是否被添加。第二类：日志出现了消息接收，但后面没有模型请求或模型响应记录。这种就是本篇重点，也就是模型通道没有补齐。云端部署时还要注意运行身份：你用当前 SSH 用户执行 hermes gateway restart，服务读取的是当前用户的 ~/.hermes/config.yaml；如果 hermes 已经 install 成 systemd 服务，而服务以 root 或其他用户运行，它可能读取 /root/.hermes/config.yaml 或别的家目录。改错配置文件，也会表现为“怎么改都不生效”。

TaoToken 前置：只补模型通道 Key 与 Base URL，不碰飞书凭证

TaoToken 在本篇里只承担模型通道的角色：提供可用的 Base URL 和 API Key，让 Hermes Agent 能调用模型生成回复。飞书凭证仍然来自飞书开放平台，两者职责不同，不能互相替代。App ID 一般以 cli_ 开头，App Secret 是飞书应用的身份密钥；TaoToken 的 Key 是模型接口鉴权用的，格式和用途都不一样。把飞书 App Secret 填到模型 api_key，或者把 TaoToken Key 填到飞书 app_secret，都会导致对应环节失败。

需要先创建模型通道 Key。打开 TaoToken 官网，登录后进入控制台，在 API Keys 相关页面创建一个新的 Key。创建后复制保存，后面要填入 ~/.hermes/config.yaml 的模型段。这个 Key 可以先用占位符 YOUR_API_KEY 写在配置里，实际保存时替换成你自己的 Key。如果服务器上有多个服务共用，建议给这个 Hermes Agent 单独建一个 Key，后续排查或轮换时更容易定位。

模型段必须有三类信息。第一是 Base URL，填写 https://taotoken.net/api。注意这里不要带 /v1，也不要把官网首页地址填进去。官网地址是给人打开控制台、创建 Key、看文档用的；Base URL 是给 Hermes Agent 发模型请求用的，两者不是同一个东西。第二是 API Key，填写你在 TaoToken 创建的 Key。第三是模型 ID，填写你要 Hermes Agent 调用的具体模型标识。模型 ID 要根据控制台或文档里实际可用的名称填写，不要凭记忆写一个不存在的名字。模型 ID 写错时，常见表现是模型请求返回 404 或类似“model not found”的错误。

还有一点容易忽略：Base URL 不带 /v1，不代表所有手工请求路径都不带 /v1。某些 OpenAI 兼容客户端会在内部拼接版本路径，所以配置项只填 https://taotoken.net/api。如果你后来用 curl 手工验证 Key，可能看到请求地址里带有 /v1/chat/completions，这是手工测试路径，不要反过来把 /v1 写回 config.yaml 的 base_url。排障时先保持配置项干净，避免 Hermes Agent 内部再拼一次路径，变成 /api/v1/v1 这类错误地址。

可复制配置：在 ~/.hermes/config.yaml 补全模型段

先编辑配置文件。登录云端服务器后，打开 Hermes Agent 的配置文件：

nano ~/.hermes/config.yaml

或者使用你习惯的编辑器。重点是在原有飞书网关配置段之后，补上模型通道配置。下面是一个示例结构，字段名请以你当前 Hermes 版本实际支持的写法为准；如果版本使用 llm、model.default 或 models 节点，就把同样的值放到对应层级里。核心是 base_url、api_key、model 三个值不要错。

feishu: app_id: "cli_xxxxxxxx" app_secret: "xxxxxxxx" connection_mode: "websocket" event_types: - "im.message.receive_v1" model: provider: "openai" base_url: "https://taotoken.net/api" api_key: "YOUR_API_KEY" model: "YOUR_MODEL_ID"

如果你的 Hermes Agent 版本要求把模型配置放在 llm 节点下，可以写成类似这样：

llm: provider: "openai" base_url: "https://taotoken.net/api" api_key: "YOUR_API_KEY" model: "YOUR_MODEL_ID"

如果版本要求使用多模型结构，也可以写成：

models: default: provider: "openai" base_url: "https://taotoken.net/api" api_key: "YOUR_API_KEY" model: "YOUR_MODEL_ID"

无论使用哪一种层级，检查时只盯住三点：base_url 是否为 https://taotoken.net/api，api_key 是否为 TaoToken 创建出来的 Key，model 是否为实际可用的模型 ID。不要把飞书 app_secret 混进 api_key，也不要把官网首页 https://taotoken.net/ 写进 base_url。

保存文件后，为了防止 YAML 缩进错误，可以用 Python 或 Hermes 自带检查命令读取一次。YAML 对缩进敏感，不要用 Tab，统一用两个空格或四个空格。如果配置文件权限过宽，也建议收紧到当前用户可读写：

chmod 600 ~/.hermes/config.yaml

如果使用 systemd 托管 Hermes 网关，还要确认服务实际读取的是哪个用户的配置文件。可以查看服务定义：

systemctl cat hermes-gateway

如果里面指定了 User=root，而你在普通用户下改了 ~/.hermes/config.yaml，那么 root 用户下的 /root/.hermes/config.yaml 才是实际生效文件。这个细节在云端排障中很常见，配置明明改了但重启后无变化，多半是改错了路径。

验证请求与成功结果：hermes gateway restart 后看两组日志

修改完成后重启网关。前台运行可以直接 Ctrl+C 停掉再执行 hermes gateway run；后台服务或 systemd 服务使用：

hermes gateway restart

如果当前没有安装成服务，也可以先执行：

hermes gateway run

观察实时日志。成功时不要再只看 websocket connection established，而要看两组日志是否都出现。第一组是飞书消息接收，例如收到某个用户发来的 message，或者出现 im.message.receive_v1 相关处理记录。第二组是模型调用，例如向模型接口发起请求、收到模型响应、准备发送回复。不同 Hermes 版本的日志字段可能不同，但排障思路一样：有消息进入，还要有模型调用，最后才有回复发出。

然后在飞书里重新测试。单聊搜索机器人，发送“您好”；群聊把机器人拉进群，@ 机器人发送“/help”。不要只发一次就下结论，可以连续发两条，便于区分首次连接延迟和真正的模型错误。正常情况下，飞书端会收到机器人回复，服务器日志里也能看到从接收消息到模型响应再到发送回复的完整链路。

如果日志里出现了模型请求但报错，重点看报错类型。401 或 403 通常指向 API Key 不对、Key 被禁用、请求头鉴权格式不对；404 通常指向 Base URL 或模型 ID 不对；400 可能是请求体格式或模型不支持该参数；超时则要检查云端服务器到模型接口的网络是否稳定。需要单独验证模型通道时，可以用 curl 手工请求一次，但注意配置里的 base_url 仍然保持 https://taotoken.net/api，不要因为手工命令里有 /v1 就把配置改掉。

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"ping"}]}'

这个命令只用于确认 Key、模型 ID 和网络是否可用。如果它返回正常，但 Hermes Agent 仍然不回复，就要回到 Hermes 配置层级、日志级别和服务运行身份上查。如果它本身也失败，就先解决 TaoToken Key 或模型 ID 问题，再继续飞书侧测试。

完成模型通道验证后，再按原文顺序回查飞书侧：服务器网络是否允许长连接和 HTTPS 请求；飞书 App ID、App Secret 是否与开放平台一致；连接模式是否为 WebSocket；im.message.receive_v1 是否订阅；应用是否已经发布到企业内部并处于可用范围。这个顺序可以避免一上来就怀疑飞书，结果根因其实是模型段没生效。

本篇常见错排查：config.yaml、Base URL、连接模式与应用发布

第一种：只配了飞书段，没有配模型段。现象是 websocket 连接成功，消息也可能进来，但机器人不生成回复。处理方式就是在 ~/.hermes/config.yaml 里补上 model、llm 或 models 节点，并确保重启后生效。

第二种：Base URL 写错。把官网首页 https://taotoken.net/ 填进 base_url，或者写成 https://taotoken.net/api/v1。前者不是模型接口地址，后者可能被 Hermes 内部再次拼接版本路径。配置项保持 https://taotoken.net/api。

第三种：API Key 混用。把飞书 App Secret 填进模型 api_key，或者把 TaoToken Key 填进飞书 app_secret。飞书凭证去飞书开放平台找，模型 Key 去 TaoToken 控制台创建，二者不要交叉。

第四种：环境变量没有加载。如果你在配置里写了 ${TAOTOKEN_API_KEY}，但 systemd 服务没有加载这个变量，实际运行时就取不到 Key。要么在服务文件中显式配置环境变量，要么先直接在配置里填入 YOUR_API_KEY 对应的真实 Key，确认跑通后再做变量化。

第五种：YAML 缩进错误。Hermes 启动时可能直接报解析失败，也可能静默使用旧配置。检查缩进、冒号、引号，不要混用 Tab。修改后最好先执行一次配置解析或 hermes gateway run，看看有没有 YAML 相关报错。

第六种：模型 ID 不存在或当前 Key 无权调用。日志里通常会出现模型接口报错。把 model 换成控制台或文档中确认可用的模型 ID，再重启测试。

第七种：连接模式或事件订阅不对。飞书开放平台里如果选的是回调 URL 模式，而 Hermes 这边按 WebSocket 配置，连接可能建立但事件分发不正常。确认事件与回调里使用的是长连接模式，并订阅 im.message.receive_v1。

第八种：应用未发布或机器人不在可用范围。飞书企业自建应用配置好后，通常需要发布到企业内部，并确保机器人对测试用户或群开放。应用未发布时，客户端可能搜不到机器人，或发消息没有事件。

第九种：群聊没有 @ 机器人。群聊场景下，很多机器人只处理 @ 消息。测试时要在群里 @ 机器人再发“/help”，不要只发普通文本。

第十种：服务器出站网络受限。WebSocket 已连上，不代表后续模型 HTTPS 请求一定通。云端安全组、防火墙、代理设置都可能影响模型接口访问。查看日志中模型请求是否超时，并用 curl 做一次独立验证。

第十一种：日志等级不够。默认日志可能看不到模型调用细节。可以临时提高日志级别，或者前台运行 hermes gateway run 观察完整输出。排障结束后再恢复。

第十二种：多用户配置文件路径不一致。systemd 服务、Docker 容器、tmux 会话可能使用不同 HOME。确认 hermes gateway restart 实际重启的是哪个进程，读取的是哪个 ~/.hermes/config.yaml。

语义一致 CTA：先创建 Key，再回服务器补模型段

如果你的 Hermes Agent 已经出现 feishu gateway started、websocket connection established，但飞书机器人仍然不回复，优先按本篇顺序处理：先打开 TaoToken 创建模型通道 Key，再回到云端服务器编辑 ~/.hermes/config.yaml，把模型段补齐，最后执行 hermes gateway restart 并重新发送测试消息。

创建 Key 可以走 TaoToken 官网入口：

https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

也可以直接进入 API Keys 页面创建和管理：

https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

如果你对 Base URL、模型 ID 或 OpenAI 兼容配置写法不确定，可以同时打开接入文档核对：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

拿到 Key 后，回到服务器把 ~/.hermes/config.yaml 的模型段补成：

model: base_url: "https://taotoken.net/api" api_key: "YOUR_API_KEY" model: "YOUR_MODEL_ID"

再执行：

hermes gateway restart

重发“您好”或 @ 机器人发送“/help”。当天日志里既有飞书消息收发，又有模型调用记录时，Hermes Agent 与飞书的这条链路才算真正打通。飞书凭证继续留在飞书开放平台管理，模型通道 Key 和 Base URL 交给 TaoToken，排障时不要把两边配置混在一起。