长期记忆和 Gateway

ClawPanel 本地安装和配置 Hermes

在 ClawPanel 内切换 Hermes Agent，一键安装后配置 Coding Hub，启动 Gateway，再接入飞书等消息平台。

内容源：飞书当前文档

HermesAgent 引擎
Gateway消息入口
18当前配图
ClawPanel 本地安装和配置 Hermes 全流程漫画

导读

先看懂 Hermes 的 5 个角色

第一次配置 Hermes Agent 时，最容易混淆的是：ClawPanel、Hermes Agent、Gateway、Coding Hub、飞书到底谁负责什么。

简单理解：

  • ClawPanel：本地管理面板，负责安装、切换引擎、打开仪表盘、启动服务。
  • Hermes Agent：真正工作的智能体，负责会话、记忆、工具调用和任务处理。
  • Gateway：本地网关，负责把消息平台、对话面板等外部消息接进 Hermes。
  • Coding Hub：公司统一模型接口，给 Hermes 提供 gpt-5.5、gpt-5.4-mini 等模型能力。
  • 飞书等消息平台：日常聊天入口。Gateway 正常后，消息平台才能把消息交给 Hermes。
飞书文档配图
飞书当前文档配图

1. 切换到 Hermes Agent

打开 ClawPanel 后，在左侧 引擎 区域点击当前引擎下拉框。

在下拉列表里选择 Hermes Agent。

飞书文档配图
飞书当前文档配图

这一步只是切换管理控制台，不会删除 OpenClaw 配置。后面你还可以再切回 OpenClaw。

2. 一键安装 Hermes Agent

切换后会进入 Hermes Agent 初始化安装界面。

页面上方是 5 个阶段：

  1. 检测
  2. 安装
  3. 配置
  4. 启动
  5. 完成

这里直接点击 一键安装。

飞书文档配图
飞书当前文档配图

一键安装会自动处理 Hermes Agent 核心包。页面里也会显示它会自动下载 uv 包管理器，并安装 hermes-agent 核心包。

3. 等待安装完成

安装过程中，页面会显示进度条和终端日志。

飞书文档配图
飞书当前文档配图

这里不要重复点击按钮，等进度走完即可。

如果安装卡住，先等 2-5 分钟。公司网络、GitHub、Python 包下载速度都会影响这一步。

4. 配置阶段先不要急着填模型

安装完成后，会进入 配置 Hermes Agent 页面。你会看到很多模型提供商按钮。

飞书文档配图
飞书当前文档配图

这里先不要在第一轮配置里纠结选哪个服务商。我们后面会在仪表盘里统一配置 Coding Hub。

往下滚动到页面底部，点击 跳过，稍后配置。

飞书文档配图
飞书当前文档配图

为什么可以先跳过？

飞书文档配图
飞书当前文档配图

对小白用户来说，先把 Hermes 安装成功并进入仪表盘，比在初始化页面里反复试模型更稳。仪表盘里的模型配置区更完整，也更方便检查 Gateway 状态。

5. 启动 Gateway 阶段也先跳过

接下来会进入 启动 Gateway 页面。

这里也先点击 跳过，稍后配置。

飞书文档配图
飞书当前文档配图

原因很简单：Gateway 要依赖模型配置。我们还没把 Coding Hub 配好，先启动 Gateway 容易让新手误以为系统坏了。

正确顺序是：

  1. 先进入仪表盘。
  2. 配好 Coding Hub 模型。
  3. 保存配置。
  4. 最后启动 Gateway。

6. 进入 Hermes 仪表盘

完成页会显示 设置完成。

点击 进入仪表盘。

飞书文档配图
飞书当前文档配图

进入仪表盘后，如果看到 Gateway 离线、模型未配置，都不用紧张。我们下一步就是配置模型。

7. 展开模型配置

在 Hermes 仪表盘里，找到 模型配置 区域。

点击或展开 模型配置。

飞书文档配图
飞书当前文档配图

仪表盘顶部通常会显示这些信息：

  • Gateway 状态
  • 当前模型
  • 版本号
  • API 地址
  • Hermes 对话面板入口

第一次配置时，Gateway 可能是 已停止，当前模型可能是 未配置。这是正常状态。

8. 配置 Coding Hub 作为模型提供商

在模型配置里填写公司 Coding Hub 信息。

8.1 填 API Base URL

Hermes 这里需要填写带 /v1 的地址：

plaintext
https://coding-hub.yeelight.com/v1

注意：这里不要漏掉 /v1。

8.2 填 API Key

API Key 填你自己在 Coding Hub 创建的密钥。

如果你之前已经在 Codex 或 Cherry Studio 教程里创建过密钥，可以继续使用同一个密钥。

8.3 获取模型列表并选择模型

点击 获取模型列表。

模型列表出来后，选择一个模型，例如：

  • gpt-5.5
  • gpt-5.4-mini

然后点击 保存配置。

飞书文档配图
飞书当前文档配图

建议第一次先选稳定、响应快的模型。后续熟悉后，再按任务复杂度选择更强模型。

9. 启动 Gateway

模型保存成功后，回到仪表盘顶部，点击 启动 Gateway。

飞书文档配图
飞书当前文档配图

启动成功后，Gateway 状态会从离线/已停止变成运行中。

如果页面上一直点 启动 Gateway 但不成功，可以打开终端执行：

shell
hermes gateway restart

执行后再回到 ClawPanel 仪表盘刷新状态。

飞书文档配图
飞书当前文档配图

真正通过的标准不是“按钮点过了”，而是：

  1. 模型配置区显示当前模型。
  2. Gateway 能正常启动。
  3. 在 Hermes 对话面板或消息平台里能收到一条真实回复。

10. Hermes 可以做什么

ClawPanel 官方 Hermes 图文指南里提到，Hermes Agent 把会话、长期记忆、人格档案、工具调用和消息渠道放在同一个管理面板中。

飞书文档配图
飞书当前文档配图

核心能力可以这样理解：

能力用来做什么
长期记忆用 Notes、User Profile、Soul 等 Markdown 文件沉淀事实、偏好和人格
会话运营查看会话、消息流、上下文和响应质量
工具调用观察 Agent 执行任务时调用了什么工具
消息渠道接入飞书、QQ、Telegram、Discord 等外部渠道
飞书文档配图
飞书当前文档配图
飞书文档配图
飞书当前文档配图
飞书文档配图
飞书当前文档配图

对普通同事来说，先不用一上来研究所有功能。先做到这 3 件事就够：

  1. Coding Hub 模型能用。
  2. Gateway 能启动。
  3. Hermes 对话面板或飞书里能正常回复。

11. 接入飞书消息渠道

Hermes 官方文档推荐使用 hermes gateway setup 做消息平台接入向导。

如果你要接飞书，可以参考官方文档：

  • Hermes 消息平台接入：https://hermes-zh.com/docs/start/getting-started/connect-message-platform
  • Hermes Feishu / Lark 文档：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/messaging/feishu.md

飞书接入的最小理解是：

  1. 先确认 Hermes 在本机对话里能正常回复。
  2. 再准备飞书应用的 App ID 和 App Secret。
  3. 优先选择 websocket 模式，因为本机不需要公网 webhook 地址。
  4. 启动 Gateway。
  5. 在飞书里给机器人发一条真实消息。

常见配置字段如下：

plaintext
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=***
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

如果你希望限制只有部分同事能使用机器人，还可以配置：

plaintext
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

飞书验收标准只有一个：在飞书私聊或群聊里收到 Hermes 的真实、可读、可复现回复。

12. 常见问题

Q1：我应该先用 OpenClaw 还是 Hermes Agent？

如果你只是想先完成公司 Coding Hub 接入、本地 Agent 和消息渠道配置，OpenClaw 教程已经足够。

如果你更关注长期记忆、会话运营、人格档案、工具调用和更完整的消息入口，可以继续使用 Hermes Agent。

两者都在 ClawPanel 里，不是互斥关系。你可以按需要切换。

Q2：为什么初始化阶段要跳过模型配置？

不是因为不需要配置模型，而是为了降低第一次上手的卡点。

初始化向导里 Provider 很多，新手容易在这里选错服务商或漏掉 Base URL。本文推荐进入仪表盘后再配置 Coding Hub，这样能同时看到模型、Gateway、API 地址和状态。

Q3：Hermes 的 API Base URL 为什么要写 /v1？

按当前 Hermes 模型配置页面和你的截图，这里填写：

plaintext
https://coding-hub.yeelight.com/v1

不要写成：

plaintext
https://coding-hub.yeelight.com

少了 /v1 时，常见表现是模型列表拉不到，或请求接口不匹配。

Q4：点击获取模型列表没有反应怎么办？

按顺序检查：

  1. API Base URL 是否是 https://coding-hub.yeelight.com/v1。
  2. API Key 是否复制完整，前后没有多余空格。
  3. Coding Hub 密钥是否还有效。
  4. 当前网络是否能访问 Coding Hub。
  5. 是否选中了自定义/custom 类配置，而不是误选某个固定服务商。

Q5：Gateway 点启动一直不成功怎么办？

先确认模型配置已经保存。然后打开终端执行：

shell
hermes gateway restart

如果仍然失败，再检查：

  1. Gateway 是否已经被旧进程占用。
  2. 8642 端口是否被占用。
  3. Hermes 是否能在命令行里正常调用模型。
  4. ClawPanel 页面是否需要刷新。

Q6：Hermes Dashboard 里的 127.0.0.1:8642 是什么？

这是本机 Gateway 地址。

127.0.0.1 表示你的电脑自己，8642 是 Gateway 监听端口。一般不需要手动改它。

Q7：页面里还有 打开 9119，需要点吗？

可以先不用。

9119 是原生 Hermes Dashboard 入口。第一次上手先在 ClawPanel 仪表盘里完成模型和 Gateway 配置即可。需要更深入管理 Hermes 时，再打开 9119。

Q8：飞书机器人为什么不回复？

先分层排查：

  1. Hermes 本机对话是否能回复。
  2. Gateway 是否在运行。
  3. 飞书应用 App ID / App Secret 是否正确。
  4. FEISHU_CONNECTION_MODE 是否为 websocket。
  5. 群聊里是否需要 @ 机器人。
  6. 是否配置了 FEISHU_ALLOWED_USERS，但当前发送人不在允许列表里。

如果本机对话都不能回复，先修模型配置，不要先排飞书。

Q9：飞书群聊里必须 @ 机器人吗？

按 Hermes Feishu / Lark 文档，群聊里通常需要 @ 机器人后才会回复。私聊里则会响应每条消息。

如果你修改了群聊策略，要确认团队是否真的需要读取所有群消息。默认要求 @ 更安全，也更不容易打扰群聊。

Q10：App Secret、API Key 可以发给别人帮忙看吗？

不要。

这些信息可以让别人调用你的模型或控制你的飞书应用。需要排查时，可以只截图字段是否填写的位置，把具体密钥打码。

Q11：安装 Hermes 时卡在下载怎么办？

常见原因是网络慢、Python 包下载慢、uv 安装慢。

可以先等 2-5 分钟。如果一直卡住：

  1. 退出 ClawPanel 后重新打开。
  2. 重新点击一键安装。
  3. 检查网络是否能访问 GitHub 和 Python 包源。
  4. 把安装日志里的最后几行复制给技术同事排查。

Q12：我已经配过 OpenClaw，会影响 Hermes 吗？

一般不会。

ClawPanel 是多引擎管理面板。OpenClaw 和 Hermes Agent 是两个不同引擎。切换引擎只是切换当前控制台和对应服务管理视图。

Q13：Hermes 和 Codex App 有什么区别？

Codex App 更适合工程开发和代码任务。

Hermes Agent 更像一个可以长期运行的本地智能体，适合接消息平台、保留长期记忆、做自动化和后台任务。

工程开发仍建议优先使用 Codex App；需要本地 Agent 或飞书机器人场景时，再使用 Hermes。

Q14：怎么判断我真的配置成功了？

不要只看页面按钮。

至少满足这 3 个条件：

  1. 模型配置里能看到已选择的模型。
  2. Gateway 状态能启动。
  3. Hermes 对话面板或飞书里能收到一条真实回复。

参考资料

  • ClawPanel Hermes Agent 图文指南：https://github.com/qingchencloud/clawpanel/blob/main/docs/hermes-agent.md
  • Hermes Agent 中文站：https://hermes-zh.com/
  • Hermes 消息平台接入：https://hermes-zh.com/docs/start/getting-started/connect-message-platform
  • Hermes Feishu / Lark 文档：https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/messaging/feishu.md