企业官网建设流程全解析

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，注意这个地址后面不要带斜杠，也不要自己拼/v1，Hermes 的 Provider 配置里会按 OpenAI 兼容格式去拼路径，多写反而会 404。

拿 Key 的路径是这样：打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，登录后进控制台，在 API Keys 页面创建一个新 Key。创建时建议给它起个能认出来的名字，比如hermes-local，方便以后按项目吊销。Key 只在创建时完整显示一次，复制下来先存到安全的地方。

如果你还没决定用哪个模型，可以先去模型对话页面试一下手感，确认这个通道能正常出结果，再去配 Hermes。模型对话入口在 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_KEY=sk-你的TaoTokenKey' >> ~/.hermes/.env echo 'OPENAI_BASE_URL=https://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/api，Key 放在.env的OPENAI_API_KEY，Model ID 填你实际要用的模型名。三者缺一，请求就会失败。Model ID 一定要和通道支持的模型名完全一致，写错了会报模型不存在。

配完验证一下 CLI 能不能对话：

hermes chat -q "你好，做个自我介绍"

能正常返回内容，说明 CLI 初始化和 LLM 通道都通了。如果报 401，回去检查.env里的 Key；如果报连接超时，检查 Base URL 是不是写成了带/v1的完整路径。

这一步过了之后，再装飞书接入需要的依赖：

pip3 install lark-oapi websockets

lark-oapi是飞书官方 SDK，websockets是 WebSocket 长连接模式需要的。两个都装上，后面 Gateway 启动才不会报缺模块。

4. 飞书机器人接入与 Gateway 启动：连通性测试与消息回执确认

飞书这一侧是整个流程里最容易漏步骤的地方，我按「建应用 → 开权限 → 订阅事件 → 发布版本 → 配 Gateway → 启动验证」的顺序写。

先在飞书开放平台创建企业自建应用，在「凭证与基础信息」页面拿到 App ID 和 App Secret。然后到「应用功能 → 机器人」启用机器人能力。

权限这块是重灾区，必须开全。进入「权限管理」，至少开通这几个：

很多人只开了im:message，结果单聊完全没反应，就是因为漏了im:message.p2p_msg:readonly。这个权限专门管单聊消息读取，不开的话机器人收不到你私聊它的内容。

接着到「开发配置 → 事件订阅」添加事件im.message.receive_v1。用 WebSocket 模式不需要配回调地址，但事件必须订阅，否则 Gateway 连上了也收不到消息。

然后是最容易漏的一步：发布版本。在「版本管理与发布 → 创建版本 → 申请发布」。飞书开放平台上修改权限和事件订阅后，不重新发布版本是不生效的。我踩过的坑就是权限加完、事件也订阅了，机器人还是不理人，最后发现是没发布。

飞书侧配完，回到服务器配 Gateway。编辑~/.hermes/.env，加上飞书相关配置：

FEISHU_APP_ID=cli_你的AppID FEISHU_APP_SECRET=你的AppSecret FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket GATEWAY_ALLOW_ALL_USERS=true

FEISHU_DOMAIN飞书填feishu，Lark 填lark。FEISHU_CONNECTION_MODE推荐websocket，不需要公网 URL，本地和 WSL 都能跑。GATEWAY_ALLOW_ALL_USERS=true是开发阶段用的，生产环境要换成白名单。

启动 Gateway，先前台跑，方便看日志：

hermes gateway run

成功启动后日志里会出现：

✓ feishu connected Gateway running with 1 platform(s)

看到这两行，说明 Gateway 和飞书的长连接建起来了。这时候去飞书里找到你的机器人，发一句「你好」。如果 Gateway 日志里出现：

info gateway.run: inbound message: platform=feishu ... info gateway.run: response ready: platform=feishu ...

说明消息进来了、回复也发出去了，全链路通了。飞书那边应该能收到 Hermes 的回复。

如果你要后台跑，WSL 环境推荐用 tmux：

tmux 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_USERS=true，重启 Gateway。

报错五：加了GATEWAY_ALLOW_ALL_USERS=true还是没反应。去飞书开放平台检查权限，重点看im:message.p2p_msg:readonly有没有开。单聊消息读取靠这个权限，漏了就收不到。

报错六：权限都开了还是没反应。检查版本有没有发布。飞书修改权限和事件订阅后必须重新创建版本并发布，不发布不生效。这是最隐蔽的一个坑。

报错七：Cron Job 投递失败，日志显示no delivery target resolved for deliver=all。这是没配FEISHU_HOME_CHANNEL。先在飞书给机器人发一条消息，从 Gateway 日志里找到chat_id，然后在.env里加：

FEISHU_HOME_CHANNEL=oc_你的chatid

重启 Gateway 后，deliver=all就能找到投递目标了。也可以用命令行直接推送：

hermes send -t feishu "消息内容" hermes send -t feishu -f /path/to/message.txt

排查的时候，日志是最好的朋友。Gateway 日志在~/.hermes/logs/gateway.log，Agent 日志在~/.hermes/logs/agent.log。用tail -f盯着看，消息进来和回复出去都有记录。

6. 长期运行与扩展：Coding Plan、API 文档与模型对话入口

链路跑通之后，如果你打算长期用，有几个方向可以继续。

第一是换更合适的调用方案。按量 Key 适合验证和低频使用，如果你要跑编码类 Agent 或高频任务，可以看看 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它针对长期编码和 Agent 场景做了优化，成本结构更适合持续调用。

第二是把接入细节查清楚。TaoToken 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各语言的调用示例和参数说明。API Keys 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以按项目建多个 Key，方便隔离和吊销。控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，能看用量和调用记录。

第三是验证模型效果。换模型之前，先去模型对话页面试一下，入口在 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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，后者漏了会表现为机器人完全不回复。把这两段按上面的清单逐项核对，基本一次能通。