OpenClaw LaunchOpenClaw Launch
← Hermes Agent 中文介绍

渠道接入

Hermes Agent 接入飞书

把 Hermes Agent 接到飞书（Lark）机器人上，让同事在工作群里直接和 AI 对话。本文讲飞书开放平台自建应用怎么建、权限开哪些、webhook 怎么填、hermes.json 要改哪些字段、常见报错怎么修。

准备工作

  • 一个能登录 飞书开放平台 的账号（国际版叫 Lark Developer）
  • 已经在跑的 Hermes Agent（没跑起来先看 安装指南）
  • 一个公网可达的 HTTPS URL 指向 Hermes 网关 —— 飞书会把消息 POST 过来，没公网是不行的

第一步：在飞书开放平台建应用

  1. 打开 open.feishu.cn/app，点“创建企业自建应用”。
  2. 填应用名称、描述、图标。名字随便取，之后同事在群里 @ 的就是这个名字。
  3. 建好之后进入应用详情页，记下 App ID 和 App Secret，一会儿要填到 hermes.json 里。

第二步：开机器人能力

  1. 左侧菜单 → “应用能力” → “机器人” → 启用。
  2. 设置机器人名称和头像。
  3. 保存后，页面顶部会多出“版本管理与发布”入口。这一步先不用急着发布。

第三步：开权限

左侧 “权限管理”，把以下权限勾上（最少集合，按你用到的功能加）：

  • im:message — 读取群消息和 @ 消息
  • im:message.group_at_msg — 接收群里 @ 机器人的消息（必需）
  • im:message.p2p_msg — 私聊消息（想要私聊就开）
  • im:message:send_as_bot — 以机器人身份发消息
  • im:chat — 读群聊信息

如果之后加了图片生成、文件发送等技能，再回来补对应的权限就行。

第四步：填事件回调地址

  1. 左侧 “事件订阅”。
  2. 请求网址填：https://你的-hermes-域名/feishu/events（具体路径以你 hermes 配置为准，默认就是 /feishu/events）。
  3. Encrypt Key 和 Verification Token 复制下来，待会儿一起填进 hermes.json。
  4. “添加事件” → 勾上 im.message.receive_v1（接收消息）。

飞书会立刻发一个验证请求过来。Hermes 配好后它会自动响应，这时候“请求网址”下方会显示“已验证”。

第五步：改 hermes.json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxx",
      "appSecret": "${FEISHU_APP_SECRET}",
      "verificationToken": "${FEISHU_VERIFICATION_TOKEN}",
      "encryptKey": "${FEISHU_ENCRYPT_KEY}",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  }
}

两处都要开：channels.feishu 和 plugins.entries.feishu。漏一处飞书插件不会启动。把 secrets 放到环境变量里，不要硬编码到 hermes.json。

第六步：发布应用到企业内

  1. 顶部 “版本管理与发布” → “创建版本” → 填版本号（1.0.0 就行）。
  2. 提交审核。企业自建应用一般由企业管理员批准，国际版 Lark 更快。
  3. 审核通过后，管理员在“管理后台”给对应人员/群授权。
  4. 授权完成后，同事就能把机器人拉进群，或者在“联系人”里搜索发起私聊。

测试一下

  • 把机器人拉进一个测试群，@ 一下试试：“@你的机器人 你好”
  • 私聊机器人（如果开了 im:message.p2p_msg）：直接发消息
  • Hermes Agent 应该在几百毫秒内回复

常见报错

99991672 permission scope not granted

最高频报错，看着吓人其实无害。飞书在做某个自检时尝试调一个你没开的权限接口，Hermes 会吞掉这个错误继续跑。如果消息能正常收发，忽略它就行。想干净一点就在权限管理里把对应 scope 补上。

事件订阅一直验证失败

  • Hermes 不在公网上 —— 飞书访问不到你 https://你的域名/feishu/events
  • 没配 HTTPS —— 飞书只认 HTTPS，自签证书也不行，要真实证书
  • Encrypt Key / Verification Token 填错了 —— 复制的时候带了空格是最常见的

消息能收到但机器人不回

  • 看 docker logs hermes，如果有 “no model configured” 一类错误 —— OPENROUTER_API_KEY 没传对
  • 如果是 “channel not enabled” —— 检查 plugins.entries.feishu.enabled 有没有设为 true
  • 如果是 “permission denied” —— 需要在飞书后台补权限，然后 重新发布一个新版本，旧版不生效

国际版 Lark 和国内飞书的区别

  • 域名不同：Lark 用 open.larksuite.com，飞书用 open.feishu.cn
  • Hermes 一般自动识别 App ID 前缀判断走哪个域名，手动配置的话指定 domain: "lark" 或 domain: "feishu"
  • 权限名字基本一致，但 Lark 的审核比飞书国内版快很多

托管版：OpenClaw Launch

上面六步看起来不复杂，但真要上线你还得搞定：公网 HTTPS、证书续期、权限审核流程、每次改配置要不要重启、出问题怎么看日志。 OpenClaw Launch 直接提供 Hermes Agent 的托管网关，飞书渠道一键开通：填 App ID / App Secret 就能跑。首月 $3，之后 $6/月，不用自己管服务器。

下一步

一键接飞书

OpenClaw Launch 托管版直接开飞书渠道，不用处理 HTTPS 和证书。

立即部署