[特殊字符] OpenClaw + 飞书集成超详细教程

📌 前置准备

在开始之前，请确保您已准备好：

✅ OpenClaw 已安装并运行
✅ 飞书账号（个人或企业账号都可以）
✅ 电脑上可以访问飞书开放平台

🚀 第一阶段：飞书开放平台配置

步骤 1.1：登录飞书开放平台

打开浏览器，访问

复制代码

https://open.feishu.cn/

登录您的飞书账号
- 如果没有账号，先注册一个
- 推荐使用手机号或邮箱注册

步骤 1.2：创建自建应用

进入管理后台
- 登录后，点击右上角的"管理后台"
- 或直接访问: https://open.feishu.cn/app
创建新应用
- 点击"创建企业自建应用"
- 或者"创建自建应用"（如果没有企业选项）

填写应用信息

字段	填写内容	说明
应用名称	OpenClaw AI 助手	可以自定义
应用描述	我的个人 AI 助手，24/7 在线	简单描述即可
应用图标	上传一个图标（可选）	可以上传喜欢的图片

创建并记录重要信息
- 创建成功后，会自动进入应用详情页
- 重要：记录以下两个信息（后续需要）：
  - App ID: 在应用凭证页面，类似 cli_a1b2c3d4e5f6g7h8i9j0
  - App Secret: 在应用凭证页面，点击"查看"或"生成"，类似 abc123def456789...

步骤 1.3：配置应用权限

进入"权限管理"页面

在左侧导航栏找到"权限管理"

申请必需权限

逐一搜索并添加以下权限：

必需权限：

权限名称	权限值	用途
获取与发送消息	`im:message`	接收和发送消息
以应用身份发消息	`im:message:send_as_bot`	机器人发送消息
读取聊天信息	`im:chat`	读取群组/私聊信息
获取群组信息	`im:group`	获取群组成员等
获取用户信息	`contact:user.base:readonly`	获取发送消息的用户信息

申请权限
- 每个权限后面点击"申请权限"
- 选择"全部员工"或"指定成员"（选择自己即可）
- 点击"确定"
批量申请（推荐）
- 某些版本支持批量申请，可以一次性申请所有权限
- 在"批量申请权限"中粘贴上述权限值

步骤 1.4：获取应用凭证

进入"凭证与基础信息"页面

左侧导航栏 → "凭证与基础信息"

记录 App ID 和 App Secret

您会看到类似以下信息：

App ID: cli_a1b2c3d4e5f6g7h8i9j0klm

App Secret: ***************** (点击"查看"显示)

复制代码

3. **保存 App Secret**
- 点击 App Secret 旁边的"查看"或"显示"
- **重要**：App Secret 只显示一次，务必立即复制保存！
- 建议保存到记事本或密码管理器

4. **配置事件订阅（可选但推荐）**

在同一页面，您会看到：
- **Encrypt Key**（加密密钥）- 可选，用于消息加密
- **Verification Token**（验证令牌）- 可选，用于验证请求来源

如果是个人使用，可以先跳过这两项

5. **截图保存**
- 建议截图保存这一页面的所有信息
- 特别是 App ID 和 App Secret

---

### 步骤 1.5：发布应用

1. **进入"版本管理与发布"**
- 左侧导航栏 → "版本管理与发布"

2. **创建新版本**
- 点击"创建新版本"
- 版本号：`1.0.0`
- 版本描述：`初始版本，支持 OpenClaw 集成`

3. **申请发布**
- 点击"申请发布"
- 选择发布范围：可以选择"全部成员"或"指定成员"
- 如果是个人账号，直接点击"确定"即可

4. **等待审核**
- 自建应用通常会自动通过审核
- 几分钟内会显示"已发布"状态

---

## 🔧 第二阶段：配置事件订阅（重要）

### 步骤 2.1：启用事件订阅

1. **进入"事件订阅"页面**

- 左侧导航栏 → "事件订阅" → "添加事件"

2. **选择订阅事件**

勾选以下事件：

- ✅ `im.message.receive_v1` - **必需**：接收消息事件
- ✅ `im.message.message_read_v1` - 可选：消息已读事件
- ✅ `im.chat.member.user_added_v1` - 可选：成员加入群组事件

3. **点击"确定"保存**

---

### 步骤 2.2：配置 Request URL（关键）

#### 方案 A：本地测试（使用内网穿透）

1. **安装内网穿透工具**

推荐使用以下任一工具：

**选项 1: ngrok（推荐，简单）**
```bash
# 下载 ngrok
# 访问 https://ngrok.com/ 注册并下载

# 使用方法
ngrok http 18789

运行后会显示：

复制代码

Forwarding  https://abc123.ngrok.io -> http://localhost:18789

您的 Webhook URL 就是 : https://abc123.ngrok.io/channels/feishu/webhook

选项 2: localhost.run（更简单，无需注册）

bash 复制代码

# 直接在命令行运行
ssh -R 80:localhost:18789 nojack@localhost.run

会生成一个公网 URL，例如: https://random-name.localtunnel.me

配置 Request URL
- 在飞书开放平台的"事件订阅"页面
- 找到"Request URL"输入框
- 填入：https://your-ngrok-url.io/channels/feishu/webhook
- 点击"验证"
验证通过
- 如果显示"验证成功"，说明配置正确
- 点击"保存"或"确定"

方案 B：服务器部署（推荐用于生产环境）

如果您有服务器（云服务器、VPS 等）：

确保 OpenClaw 部署在服务器上
- 服务器需要开放 18789 端口
- 或者使用 Nginx 反向代理

配置 Request URL

复制代码

http://your-server-ip:18789/channels/feishu/webhook
# 或使用域名
https://your-domain.com/channels/feishu/webhook

配置防火墙

bash 复制代码

# 开放 18789 端口
sudo ufw allow 18789
# 或
sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload

方案 C：仅本地测试（暂不配置 Webhook）

如果您只是想在本地测试，可以暂时跳过事件订阅配置：

不使用 Webhook，使用轮询模式
或者手动触发消息
后续再配置 Webhook

步骤 2.3：测试事件订阅

发送测试消息
- 在飞书中给您的应用发送消息
- 或者将应用拉入一个测试群组
查看事件订阅日志
- 飞书开放平台 → "事件订阅" → "事件日志"
- 应该能看到消息事件
如果看到错误
- 检查 Request URL 是否正确
- 确认防火墙是否开放端口
- 查看 OpenClaw 日志

🎯 第三阶段：在 OpenClaw 中配置飞书渠道

步骤 3.1：准备配置信息

确保您已准备好以下信息：

yaml 复制代码

飞书应用信息:
  App ID: cli_a1b2c3d4e5f6g7h8i9j0
  App Secret: abc123def456789...
  Encrypt Key: (可选)
  Verification Token: (可选)

Webhook 信息:
  URL: http://your-server:18789/channels/feishu/webhook

步骤 3.2：添加飞书渠道到 OpenClaw

方式 1：交互式配置（推荐）

运行添加命令
bash 复制代码
```
openclaw channels add --channel feishu
```
按提示输入信息
- 输入 App ID
- 输入 App Secret
- 输入 Encrypt Key（如果没有，按 Enter 跳过）
- 输入 Verification Token（如果没有，按 Enter 跳过）
配置自动保存

方式 2：命令行配置（快速）

bash 复制代码

openclaw channels add \
  --channel feishu \
  --account default \
  --name "飞书机器人"

然后会提示您输入凭证信息。

步骤 3.3：验证配置

检查渠道状态
bash 复制代码
```
openclaw channels list
```
查看详细状态
bash 复制代码
```
openclaw channels status
```
查看日志
bash 复制代码
```
openclaw channels logs feishu
```

🎉 第四阶段：测试和使用

步骤 4.1：在飞书中测试

找到您的机器人应用
- 在飞书中搜索您的应用名称
- 或者直接使用应用链接
发送测试消息
复制代码
```
你好
```
查看回复
- OpenClaw 应该会自动回复
- 可以测试更复杂的问题

步骤 4.2：拉入群组测试

创建测试群组

在飞书中创建一个新的群组

添加机器人

邀请您的飞书应用加入群组

在群组中测试

复制代码

@OpenClaw AI 助手 介绍一下你自己

验证功能
- 机器人应该会响应 @ 提及
- 可以执行各种任务

步骤 4.3：常用命令示例

在飞书中可以直接使用的命令：

基础对话：

复制代码

你好，请介绍一下你自己
帮我制定今天的工作计划
搜索今天的科技新闻

文件操作：

复制代码

帮我在桌面创建一个测试文件
读取 C:\Users\test.txt 的内容

系统操作：

复制代码

查看当前系统状态
列出正在运行的进程

高级功能：

复制代码

帮我搜索最新的 AI 新闻并总结
创建一个待办事项列表

🔍 故障排查

常见问题及解决方案

问题 1：找不到"创建自建应用"

症状：在飞书开放平台找不到创建应用的入口

解决方案：

确保您使用的是飞书开放平台账号（open.feishu.cn）
个人账号和企业账号都可以创建自建应用
尝试刷新页面或使用其他浏览器

问题 2：App Secret 忘记保存

症状：App Secret 显示后忘记复制，现在找不到了

解决方案：

在"凭证与基础信息"页面
点击"重置"可以生成新的 Secret
注意：旧 Secret 会立即失效，需要重新配置 OpenClaw

问题 3：事件订阅验证失败

症状：配置 Request URL 后验证一直失败

解决方案：

检查 Webhook URL 是否正确

bash 复制代码

# 正确格式
http://your-ip:18789/channels/feishu/webhook
https://your-domain.com/channels/feishu/webhook

确认 OpenClaw Gateway 正在运行
bash 复制代码
```
openclaw gateway status
```

检查防火墙设置

bash 复制代码

# Windows
netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=TCP localport=18789

# Linux
sudo ufw allow 18789

查看 OpenClaw 日志
bash 复制代码
```
openclaw logs --follow
```

问题 4：机器人没有回复消息

症状：在飞书中给机器人发消息，但没有回复

排查步骤：

检查 Gateway 状态
bash 复制代码
```
openclaw gateway status
```
应该显示: Listening: 127.0.0.1:18789
检查飞书渠道状态
bash 复制代码
```
openclaw channels status
```
查看飞书渠道日志
bash 复制代码
```
openclaw channels logs feishu --follow
```
检查应用权限
- 确认已在飞书开放平台申请了必需权限
- 确认应用已发布
检查事件订阅
- 确认 Request URL 配置正确
- 查看事件订阅日志
测试 AI 模型
bash 复制代码
```
openclaw agent --agent main -m "测试消息"
```
如果本地能工作，说明问题在飞书集成

问题 5：没有公网服务器

症状：想在本地测试，但没有公网 IP

解决方案：

选项 1：使用 ngrok（推荐）

bash 复制代码

# 1. 下载并安装 ngrok
# 访问 https://ngrok.com/

# 2. 运行 ngrok
ngrok http 18789

# 3. 复制生成的 URL
# 例如：https://abc123.ngrok.io

# 4. 在飞书配置 Request URL
# https://abc123.ngrok.io/channels/feishu/webhook

选项 2：使用 localhost.run

bash 复制代码

ssh -R 80:localhost:18789 nojack@localhost.run

选项 3：使用其他内网穿透工具

Cloudflare Tunnel
frp
花生壳

选项 4：暂不配置 Webhook

先使用命令行测试 OpenClaw
后续有服务器再配置飞书

问题 6：权限申请被拒绝

症状：在飞书开放平台申请权限时被拒绝

解决方案：

自建应用通常不会拒绝权限申请
如果是企业账号，可能需要管理员审批
联系企业管理员审批权限
或使用个人账号创建应用

问题 7：消息发送失败

症状：机器人收到消息但无法回复

排查步骤：

检查应用是否发布
- 确认应用在"版本管理与发布"中已发布
- 未发布的应用无法发送消息
检查消息发送权限
- 确认已申请 im:message:send_as_bot 权限
- 在权限管理页面查看权限状态
查看错误日志
bash 复制代码
```
openclaw channels logs feishu --follow
```

重新配置渠道

bash 复制代码

# 删除现有配置
openclaw channels remove feishu

# 重新添加
openclaw channels add --channel feishu

问题 8：Windows 环境问题

症状：在 Windows 上运行遇到各种问题

解决方案：

推荐使用 WSL2

bash 复制代码

# 安装 WSL2
wsl --install

# 在 WSL2 中运行 OpenClaw

使用 PowerShell 管理员权限
powershell 复制代码
```
# 右键"以管理员身份运行" PowerShell
```

检查防火墙

powershell 复制代码

# 添加防火墙规则
netsh advfirewall firewall add rule name="OpenClaw" dir=in action=allow protocol=TCP localport=18789

检查 Node.js 版本
bash 复制代码
```
node --version
# 需要 22+ 版本
```

📚 附录

A. 快速参考命令

bash 复制代码

# OpenClaw 基础命令
openclaw --version              # 查看版本
openclaw gateway status          # 查看 Gateway 状态
openclaw gateway restart         # 重启 Gateway
openclaw health                  # 健康检查
openclaw logs --follow           # 实时日志

# 渠道管理
openclaw channels list           # 列出所有渠道
openclaw channels status         # 查看渠道状态
openclaw channels add --channel feishu    # 添加飞书渠道
openclaw channels remove feishu          # 删除飞书渠道
openclaw channels logs feishu    # 查看飞书日志

# Agent 交互
openclaw agent --agent main -m "消息"     # 发送消息
openclaw agent --agent main --thinking "消息"  # 带思考过程

# 插件管理
openclaw plugins list             # 列出所有插件
openclaw plugins enable feishu     # 启用飞书插件
openclaw plugins disable feishu    # 禁用飞书插件

B. 配置文件位置

bash 复制代码

# 主配置文件
~/.openclaw/openclaw.json

# 工作区
~/.openclaw/workspace/

# 会话存储
~/.openclaw/agents/main/sessions/

# 日志文件
/tmp/openclaw/openclaw-YYYY-MM-DD.log

# Windows 路径示例
C:\Users\YourName\.openclaw\openclaw.json

C. 端口说明

端口	用途	说明
18789	Gateway 默认端口	OpenClaw Gateway 服务端口
22	SSH	用于远程服务器管理
80/443	HTTP/HTTPS	Web 服务

D. 相关链接

官方文档：

OpenClaw 官方文档: https://docs.openclaw.ai
OpenClaw GitHub: https://github.com/openclaw/openclaw
飞书开放平台: https://open.feishu.cn
飞书开发文档: https://open.feishu.cn/document

教程资源：

工具下载：

ngrok: https://ngrok.com/
Node.js: https://nodejs.org/
WSL2: https://docs.microsoft.com/windows/wsl

✅ 配置检查清单

完成配置后，请逐项检查：

飞书开放平台

已创建自建应用
已记录 App ID 和 App Secret
已申请必需权限（im:message, im:message:send_as_bot 等）
已发布应用
已启用事件订阅
已配置 Request URL（如需要）
事件订阅验证通过

OpenClaw 配置

测试验证

能在飞书中发送消息给机器人
机器人能正常回复
能在群组中使用 @机器人
能执行基本命令
日志中无错误信息

🎓 进阶使用

1. 配置多个飞书应用

bash 复制代码

# 添加第一个账号
openclaw channels add --channel feishu --account work

# 添加第二个账号
openclaw channels add --channel feishu --account personal

# 列出所有账号
openclaw channels list

2. 自定义机器人行为

编辑配置文件 ~/.openclaw/openclaw.json：

json 复制代码

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-4.7"
      },
      "personality": "你是一个友好、专业	的AI助手"
    }
  }
}

3. 配置定时任务

bash 复制代码

# 添加每日新闻推送
openclaw cron add \
  --name "每日新闻" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --channel feishu \
  --message "生成今日科技新闻摘要"

4. 启用高级功能

bash 复制代码

# 启用浏览器自动化
openclaw config set tools.browser true

# 启用文件操作
openclaw config set tools.filesystem true

# 启用网络搜索
openclaw config set tools.web true

📞 获取帮助

如果遇到问题：

查看日志

bash 复制代码

openclaw logs --follow
openclaw channels logs feishu --follow

运行诊断
bash 复制代码
```
openclaw doctor
openclaw health --deep
```
查看官方文档
- OpenClaw 文档: https://docs.openclaw.ai
- 飞书开发文档: https://open.feishu.cn/document
提交问题
- OpenClaw GitHub Issues
- 飞书开发者社区

📝 更新日志

2026-03-07: 初始版本创建
基于 OpenClaw v2026.2.25
支持飞书/Lark 集成
包含完整的配置步骤和故障排查

祝您使用愉快！🦞

如有任何问题或建议，欢迎反馈！