OpenClaw教程补充内容——如何进行飞书Bot的配置

📚 来源 ：基于官方教程优化

✨ 更新 ：2026-03-10

🎯 目标：30 分钟内完成飞书机器人配置

---

📱 飞书的优势

优势	说明
🏢 现代化办公	文档协作、多维表格、视频会议
💬 高效沟通	消息卡片、互动组件、流式输出
👨‍💻 开发友好	API 设计优秀、文档详细、WebSocket 长连接
💰 免费使用	功能强大、稳定可靠

---

🚀 快速开始（2 种方式）

方式一：安装向导（推荐新手）

openclaw setup

向导会自动引导你完成：

1. ✅ 创建飞书应用并获取凭证
2. ✅ 配置应用凭证
3. ✅ 启动网关

方式二：命令行添加（推荐老手）

openclaw channels add

然后根据提示选择 Feishu，输入 App ID 和 App Secret。

低版本的在这里选择Download fron npm，高版本已经内置了，选择Use local plugin path 即可：

根据提示输入飞书获取的信息即可。

---

📋 详细配置步骤

步骤 1：创建飞书应用

1.1 访问飞书开放平台

• 国内版：https://open.feishu.cn/app
• 国际版 ：https://open.larksuite.com/app（配置时需设置 domain: "lark"）

1.2 创建应用

1. 点击 创建企业自建应用
   

2. 填写应用名称（如 "OpenClaw 助手"）

3. 选择应用图
   

1.3 获取应用凭证

在 凭证与基础信息 页面，复制：

• App ID （格式如 cli_xxx）
• App Secret

⚠️ 重要 ：请妥善保管 App Secret，不要分享给他人！

1.4 配置应用权限

在 权限管理 页面，点击 批量导入，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_msg",
      "im:chat",
      "contact:contact.base:readonly",
      "contact:user.employee_id:readonly"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

必需权限说明：

权限标识	用途	是否必需
im:message	接收和发送消息	✅ 必需
im:message:send_as_bot	以机器人身份回复	✅ 必需
contact:contact.base:readonly	识别用户身份	✅ 必需

💡 为什么需要 contact:contact.base:readonly？

这个权限用于获取用户基本信息，OpenClaw 需要它来：

• ✅ 识别消息发送者
• ✅ 实现访问控制
• ✅ 提供个性化服务

同样也可以点击【开通权限】按钮手动操作，在这儿我就不在多加演示。

1.5 启用机器人能力

在 应用能力 > 机器人 页面：

1. 开启机器人能力
2. 配置机器人名称和头像
   

1.6 提交发布申请

在 版本管理与发布 页面：

1. 选择 创建版本

2. 填写版本号等信息后发布

1.7 配置事件订阅

⚠️ 前提条件：

1. 已运行 openclaw channels add 添加飞书渠道
2. 网关处于启动状态（openclaw gateway status 检查）

在 事件订阅 页面：

1. 选择 使用长连接接收事件（WebSocket 模式）

2. 添加事件：im.message.receive_v1
   点击添加事件按钮：
   
   然后再搜索框搜索：im.message.receive_v1
   选中接受消息权限，点击右下角添加按钮：
   

---

步骤 2：配置 OpenClaw

2.1 打开配置界面

访问 OpenClaw Control UI：

http://127.0.0.1:18789/
# 或你的公网地址：https://XXX.XXX.XXX.XXX:XXXX/

2.2 添加飞书渠道

在文章开头如果已经设置好了，这儿可以直接跳过，下面讲的是在可视化界面上的一个操作，如果文章开头部分没有操作，也可以根据命令进行添加相关操作：

openclaw config set channels.feishu.appId "XXXXXX"                  
openclaw config set channels.feishu.appSecret "XXXXXX"                  
openclaw config set channels.feishu.enabled true                  
openclaw config set channels.feishu.connectionMode websocket 

App ID和App Secret换成你们自己的就可以。

如果文章开头已经创建，但是想要更换，可以如下操作进行：

1. 进入 设置 → 渠道 → 飞书 (需要已经添加了飞书渠道，如果没有可以直接执行命令添加相应数据即可)
2. 填入信息：
   • App ID：步骤 1.3 获取的 App ID
   • App Secret：步骤 1.3 获取的 App Secret
   • Encrypt Key：可选（加密验证）
   • Verification Token：用于验证回调
3. 保存配置

2.3 配置访问控制

在 openclaw.json 中添加允许的用户/群组：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxx",
      "appSecret": "xxx",
      "allowFrom": [
        "feishu:ou_xxx"  // 你的用户 ID
      ],
      "groupPolicy": "allowlist",
      "groupAllowFrom": [
        "feishu:oc_xxx"  // 群组 ID
      ]
    }
  }
}

---

步骤 3：启动并测试

3.1 启动网关

openclaw gateway start

3.2 查看日志

openclaw logs --follow

寻找类似这样的成功信息：

feishu ws connected
feishu provider ready

3.3 测试连接

1. 在飞书中找到你的机器人
2. 发送一条消息：你好
3. 确认收到回复

第一次需要配对，所以返回的消息是带有Pairing code的，需要去授权配对：

openclaw pairing approve feishu XXX

把XXX替换成你的code即可。

---

🔧 高级配置

获取群组/用户 ID

方法一：通过日志获取

在日志中查找消息记录：

feishu sendMessage ok chat=ou_xxx message=123

方法二：通过 API 获取

# 获取用户 ID
curl -X GET "https://open.feishu.cn/open-apis/contact/v3/users/me" \
  -H "Authorization: Bearer $(openclaw feishu token)"

# 获取群组 ID
curl -X GET "https://open.feishu.cn/open-apis/im/v1/chats" \
  -H "Authorization: Bearer $(openclaw feishu token)"

多账号配置

在 openclaw.json 中配置多个飞书账号：

{
  "channels": {
    "feishu_main": {
      "enabled": true,
      "appId": "cli_xxx1",
      "appSecret": "xxx1",
      "accountId": "main"
    },
    "feishu_test": {
      "enabled": true,
      "appId": "cli_xxx2",
      "appSecret": "xxx2",
      "accountId": "test"
    }
  }
}

多 Agent 配置

配合飞书使用多 Agent（小墨、小文、小 C）：

{
  "agents": {
    "main": {
      "id": "main",
      "bindings": ["feishu_main"]
    },
    "writer": {
      "id": "writer",
      "bindings": ["feishu_writer"]
    },
    "tech": {
      "id": "tech",
      "bindings": ["feishu_tech"]
    }
  }
}

---

❓ 常见问题

问题 1：机器人无法响应

排查步骤：

1. ✅ 检查 App ID 和 App Secret 是否正确
2. ✅ 确认权限是否已添加（特别是 contact:contact.base:readonly）
3. ✅ 验证网关是否启动（openclaw gateway status）
4. ✅ 查看日志中的错误信息

问题 2：长连接配置失败

原因：网关未启动或渠道未添加

解决方法：

# 1. 先添加渠道
openclaw channels add

# 2. 启动网关
openclaw gateway start

# 3. 再配置事件订阅
# （在飞书开放平台操作）

问题 3：访问控制不生效

检查配置：

{
  "channels": {
    "feishu": {
      "allowFrom": [
        "feishu:ou_xxx"  // 确保格式正确
      ],
      "groupPolicy": "allowlist"  // 或 "open"
    }
  }
}

---

🔒 安全配置

配置项	建议
App Secret	妥善保管，不要提交到 Git
HTTPS	生产环境建议使用 HTTPS
Verification Token	定期更换
权限范围	遵循最小权限原则
访问控制	配置 allowFrom 白名单

---

📊 配置检查清单

在开始测试前，请确认：

• 已创建飞书应用
• 已获取 App ID 和 App Secret
• 已添加必需权限
• 已启用机器人能力
• 已配置事件订阅（长连接）
• 已在 OpenClaw 配置飞书渠道
• 网关已启动
• 已配置访问控制
• 日志显示 feishu provider ready

---

🎯 下一步

配置完成后，你可以：

1. 私聊机器人 - 一对一对话
2. 拉入群组 - 团队协作用
3. 配置多 Agent - 不同场景用不同助手
4. 集成 Ontology - 结构化知识管理

---