OpenClaw 飞书接入保姆级教程📚 第一部分：开篇必读 1.1 为什么要接飞书？恭喜你，已经成功“养虾”（安装O

OpenClaw 飞书接入保姆级教程：终极完整版 v3.2

—— 经全网验证、一步不落、零失败的“喂饭级”教程（含配置文件详解、企业网络/IP白名单/多语言/权限补全）

文档版本：3.2 | 适用读者：完全零基础 | 最后更新：2024年
核心原则：每一步都告诉你“为什么做”、“怎么做”、“做完会看到什么”

📚 第一部分：开篇必读

1.1 为什么要接飞书？

恭喜你，已经成功“养虾”（安装OpenClaw）！但现在的龙虾还只能通过浏览器访问，就像关在笼子里的小宠物。把它接入飞书后：

✅ 手机随时用：通勤路上、出差途中，打开飞书就能给AI发指令
✅ 文件直接传：在飞书里直接发文档、图片给AI处理，无需上传下载
✅ 群聊共享：把机器人拉进群，整个团队都能用（可设置仅@时响应）
✅ 24小时在线：配合云服务器部署，随时随地唤醒你的AI助理

1.2 准备工作清单

在开始之前，请确认以下事项都准备好了：

需要准备的东西	状态	检查方法
OpenClaw已安装并正常运行	✅ 必需	浏览器打开 `http：//127.0.0.1：18789` 能看到聊天界面
飞书账号	✅ 必需	手机号注册即可，免费
记事本	✅ 推荐	用来临时保存复制的密钥（App ID/Secret）
终端已打开	✅ 必需	根据你的系统打开对应的命令行工具
网络通畅	✅ 必需	能访问 `open.feishu.cn` 和 GitHub
企业网络权限	⚠️ 按需确认	如在公司内网，需确认飞书API域名是否被防火墙拦截（详见12.10节）
耐心	✅ 必需	全程约20-25分钟，按步骤来一定能成功

1.3 整体流程概览

为了让心里有数，先看看我们要做哪几件事：

🤖 第二部分：在飞书开放平台创建机器人

2.1 进入飞书开放平台

打开浏览器，访问飞书开放平台：https：//open.feishu.cn/
点击右上角的 “登录” 按钮
使用你的飞书账号登录（手机号扫码或密码登录均可）

你会看到：登录后进入开发者后台首页，显示“还没有应用，立即创建”之类的提示。

2.2 创建企业自建应用

在开发者后台，找到并点击 “创建应用” 按钮（通常在页面中央或右上角）
在弹出的窗口中，选择 “企业自建应用”

小提示：不要选“商店应用”，那是给上架飞书商店用的，我们需要的是企业内部使用的机器人。
填写应用基本信息：
- 应用名称：输入你喜欢的名字，比如 我的龙虾助理、OpenClaw小帮手（后续可修改）
- 应用描述：简单写几句，比如“我的AI智能助手，可以帮我处理文件、查询信息”
- 应用图标：可以不上传，用默认的；如果想个性化，准备一张正方形图片（≥240×240像素，2MB以内）
点击 “创建” 按钮

你会看到：创建成功后，自动进入这个应用的管理页面。请记住这个页面，我们接下来会反复用到！

2.3 为应用添加机器人能力

在应用管理页面的左侧导航栏，找到 “添加应用能力”
点击后，在弹出的能力列表中，找到 “机器人”
点击 “添加” 按钮

你会看到：页面刷新，左侧导航栏会增加 “机器人” 相关菜单。

提示：添加机器人之后，可以暂不发布，待其他配置完成后一并发布。

2.4 获取核心凭证：App ID 和 App Secret（先复制保存）

这是最关键的一步，这两个字符串就是飞书机器人的“身份证”，OpenClaw需要用它们来识别和连接你的机器人。

在应用管理页面左侧导航栏，找到 “凭证与基础信息” （或“应用凭证”）并点击
在页面中，你会看到两个重要的字段：
- App ID：一串字符，类似 cli_xxxxxxxxxxxxxxx
- App Secret：一串更长的字符，类似 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
分别点击右侧的“复制”按钮，将这两个字符串粘贴到你的记事本中保存好

⚠️ 安全提醒：

App Secret 相当于机器人的密码，不要分享给任何人
如果不小心泄露，可以在这里点击“重置”重新生成
记事本保存后，建议用完就关闭，不要在电脑上长期明文保存

🔌 第三部分：安装飞书插件（最关键！最容易漏掉）

3.1 为什么需要安装插件？

OpenClaw采用模块化设计，核心程序只提供基础功能，连接不同的聊天软件需要安装对应的“通道插件”。就像手机要装微信才能聊天一样，OpenClaw需要装飞书插件才能和飞书通信。

如果跳过这一步：后面所有配置都会白费，机器人永远无法收到消息！

3.2 选择哪个飞书插件？

根据NPM官方信息，目前主流的有两个飞书插件，任选其一即可：

插件名称	特点	推荐度
`feishu-openclaw`	官方推荐，轻量稳定，支持OpenClaw和Clawdbot双环境	⭐⭐⭐ 首选
`@overlink/openclaw-feishu`	功能更丰富，支持国内版/国际版双版本、富媒体处理、消息卡片、自动回复模式等	⭐⭐ 备选

本教程以 feishu-openclaw 为例，如果你需要国际版（Lark）支持，建议使用 @overlink/openclaw-feishu 并配置 domain： "lark"。

3.3 打开终端

根据你的安装方式，打开相应的命令行工具：

你的安装方式	打开什么
macOS/Linux 原生安装	打开 “终端” （Terminal）
Windows WSL2 安装	打开 “Ubuntu” （紫色图标）
Windows PowerShell 原生安装	打开 PowerShell（普通权限即可）

3.4 执行插件安装命令

在终端中复制粘贴以下命令（一整行），然后回车：

openclaw plugins install feishu-openclaw

你会看到：

很多文字滚动
最后出现类似 Plugin feishu-openclaw installed successfully 的提示

如果你在中国大陆，可能遇到网络问题（下载慢或超时），可以尝试：

# 先设置npm镜像源（淘宝源）
npm config set registry https：//registry.npmmirror.com/

# 再次尝试安装
openclaw plugins install feishu-openclaw

如果仍然失败，可以手动安装：

# 方式2：通过npm全局安装
npm install -g feishu-openclaw

# 方式3：下载离线包安装
curl -O https：//registry.npmjs.org/feishu-openclaw/-/feishu-openclaw-0.3.1.tgz
openclaw plugins install ./feishu-openclaw-0.3.1.tgz

3.5 验证插件是否安装成功

openclaw plugins list

你应该看到类似下面的输出：

Installed plugins：
  ✔ feishu-openclaw    v0.3.1    enabled    Feishu integration
  ✔ ...（其他插件）

关键检查点 ：

✅ 确保 feishu-openclaw 在列表中
✅ 确保状态是 enabled（已启用）
✅ 如果显示 disabled，执行：openclaw plugins enable feishu-openclaw

3.6 ⚠️ 如果遇到“插件冲突”问题（重要！）

根据社区反馈，OpenClaw旧版本可能内置了一个飞书插件（@openclaw/feishu），和新安装的 feishu-openclaw 冲突，导致两个插件争抢同一个通道。

现象：执行 openclaw plugins list 后，看到多个飞书插件，比如：

Installed plugins：
  ✔ @openclaw/feishu    v0.5.0    enabled    Feishu integration (built-in)
  ✔ feishu-openclaw     v0.3.1    enabled    Feishu integration

解决方法 ：

# 1. 禁用内置的旧版插件
openclaw plugins disable @openclaw/feishu

# 2. 确认状态
openclaw plugins list

现在应该只看到 feishu-openclaw 是 enabled 状态。

如果还不放心，可以重启网关：

openclaw gateway restart

3.7 ⚠️ 插件安全配置（生产环境建议）

如果你在生产环境部署，建议配置插件加载白名单，增强安全性：

# 设置允许加载的插件列表
openclaw config set plugins.allow '["feishu-openclaw"]'

为什么这样做：如果 plugins.allow 为空，任何未捆绑的插件都可能自动加载，存在安全隐患。

🔧 第四部分：在OpenClaw中配置飞书通道

现在插件装好了，我们要告诉OpenClaw：“嘿，你的飞书机器人小伙伴的身份证在这里，去连接它吧！”

4.1 ⚠️ 关键顺序提醒（全网验证，必读！）

飞书开放平台要求：必须先验证App ID/Secret有效，才能配置长连接！

因此，请务必严格按照以下顺序操作：

✅ 先在OpenClaw中配置App ID/Secret（本节内容）
✅ 然后重启网关（4.4节）
✅ 最后再去飞书开放平台配置长连接（第五部分）

如果顺序颠倒（先配置长连接再配App ID），飞书会报错“未建立长连接”，导致配置失败。

4.2 执行配置命令

我们将使用 openclaw config set 命令来逐项配置。请一条一条复制执行，不要一次性全贴。

第一步：启用飞书通道

openclaw config set channels.feishu.enabled true

第二步：配置飞书机器人的 App ID

openclaw config set channels.feishu.appId "粘贴你的App ID"

示例：openclaw config set channels.feishu.appId "cli_abc123def456"

第三步：配置飞书机器人的 App Secret

openclaw config set channels.feishu.appSecret "粘贴你的App Secret"

示例：openclaw config set channels.feishu.appSecret "8a5f3c9b2e1d4a7f8c3b6e9d2a5f8c1b"

第四步：设置连接模式为 WebSocket（推荐）

openclaw config set channels.feishu.connectionMode websocket

为什么选 WebSocket？ 这是长连接模式，不需要公网IP和域名配置，最简单稳定。

第五步：配置私聊策略

openclaw config set channels.feishu.dmPolicy pairing

选项说明：

pairing：用户需要先与机器人“配对”才能私聊（推荐，最安全）

open：所有人可聊

allowlist：仅白名单用户可聊

第六步：配置群聊策略

openclaw config set channels.feishu.groupPolicy allowlist

选项说明：

allowlist：只有在白名单中的群才能使用机器人（推荐，需配置群ID）

open：所有群开放

disabled：禁用群聊

第七步：配置是否需要@才响应

openclaw config set channels.feishu.requireMention true

推荐选 true：在群聊中，只有@机器人时它才会响应，避免它在群里“自言自语”。

第八步（可选）：配置飞书版本（国内版/国际版）

# 飞书国内版（默认）
openclaw config set channels.feishu.domain feishu

# 如果你使用的是Lark国际版
openclaw config set channels.feishu.domain lark

4.3 验证配置是否成功

执行以下命令，查看飞书通道的配置：

openclaw config get channels.feishu

你会看到：类似下面的输出，说明配置已生效

appId： "cli_abc123def456"
appSecret： "********"  # 出于安全，不会明文显示
enabled： true
connectionMode： "websocket"
domain： "feishu"
dmPolicy： "pairing"
groupPolicy： "allowlist"
requireMention： true

4.4 重启网关使配置生效

所有配置修改后，需要重启OpenClaw的网关服务：

openclaw gateway restart

你会看到：

Gateway restarting...
Gateway restarted successfully

4.5 验证通道状态

openclaw channel list

你应该看到类似输出：

Channels：
  ✔ Feishu     enabled    running    configured
  ✘ Telegram   disabled   stopped    not configured

关键检查点：如果 Feishu 显示：

enabled：已启用 ✅
running：正在运行 ✅
configured：已配置 ✅

三个都绿了，说明插件和基础配置成功！

4.6 再次验证网关状态

openclaw status

确保看到 gateway： running，并且飞书相关的状态也是正常的。

⚙️ 第五部分：配置飞书机器人权限和事件

现在OpenClaw这边已经准备好了，我们回到飞书开放平台，告诉飞书机器人：“你的AI大脑已经就位，可以接收消息了！”

5.1 ⚠️ 先确认：网关已重启

在继续之前，请确保上一步的网关重启已完成，且 openclaw status 显示 running。

5.2 配置事件订阅方式为长连接

因为我们在OpenClaw中设置了 connectionMode websocket，所以飞书这边也要对应选择“长连接” 。

回到浏览器中的飞书开放平台，确保还在你的应用管理页面
左侧导航栏找到 “事件与回调” ，点击进入
在 “事件配置” 标签页中，找到 “订阅方式”
选择 “使用长连接接收事件” （不要选“HTTP回调”，那是需要公网地址的）
点击页面下方的 “保存” 按钮

如果保存时报错“未建立长连接” ：

别慌，这是最常见的情况
检查上一步的 appId 和 appSecret 是否配置正确
回到终端，执行 openclaw gateway restart 再重启一次
等待10-20秒，让长连接重新建立
返回飞书页面再次点击“保存”

5.3 添加“接收消息”事件

这是最关键的一步——告诉飞书，当用户给机器人发消息时，要把这个消息转发给OpenClaw处理。

在“事件与回调”页面的 “事件配置” 标签页，找到 “添加事件” 按钮，点击
在弹出的搜索框中，输入 “接收消息”
在搜索结果中，找到 “接收消息” 事件（英文名 im.message.receive_v1）
点击它，然后点击 “确认添加”

你会看到：页面可能会提示需要开通权限，点击“确认开通”或“同意”即可。

可选事件：如果你想让机器人知道进群/退群事件，可以额外添加 机器人进群、机器人被移出群 等事件。

5.4 配置回调配置（同样选择长连接）

在“事件与回调”页面，切换到 “回调配置” 标签页
同样将 “订阅方式” 设置为 “使用长连接接收回调”
点击 “保存”

5.5 开通必要的权限（完整版，已验证）

为了让机器人能够正常收发消息、进群、处理文件等，需要开通一系列权限。这一步很多人漏掉文件权限，导致机器人收不到图片！

左侧导航栏找到 “权限管理” ，点击进入
你会看到很多权限列表，我们需要开通以下几类核心权限：

📌 基础权限（必须开通）

权限标识	权限名称	作用
`contact：user.base：readonly`	获取基础用户信息	知道谁在发消息
`im：message`	收发消息	核心功能，必须
`im：message.p2p_msg：readonly`	读取机器人的私信消息	处理私聊消息
`im：message.group_at_msg：readonly`	接收群内@机器人的消息	处理群聊@消息
`im：message：send_as_bot`	以机器人身份发送消息	让机器人能回复

📁 文件处理权限（非常重要！很多人漏掉）

权限标识	权限名称	作用
`im：resource`	获取与上传图片或文件资源	没有这个权限，机器人无法接收和处理图片、文件！

👥 群聊相关权限（推荐开通）

权限标识	权限名称	作用
`im：chat：readonly`	读取群聊信息	获取群名称、成员列表等
`contact：contact.base：readonly`	读取通讯录基础信息	获取用户姓名、部门等
`im：chat.members：bot_access`	获取群成员信息	了解群里有谁

📄 文档处理权限（可选）

权限标识	权限名称	作用	推荐等级
`docs：document.content：read`	读取文档内容	需要AI阅读飞书文档时开通	⭐ 可选
`sheets：spreadsheet`	读写表格	处理飞书表格	⭐ 可选

⚠️ 敏感权限（谨慎开通）

权限标识	权限名称	作用	风险说明
`im：message.group_msg`	接收群聊中所有消息	无需@也能响应	可能看到群内所有对话，隐私风险高
`im：message：readonly`	查询消息历史	获取历史消息	可能泄露历史对话

批量开通方法 ：

可以逐个搜索上述权限并开启
也可以点击页面中的 “批量导入/导出权限” 按钮，将以下权限代码粘贴导入：

{
  "scopes": {
    "tenant": [
      "contact:user.base:readonly",
      "contact:contact.base:readonly",
      "im:message",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "im:chat:readonly",
      "im:chat.members:bot_access",
      "docs:document.content:read",
      "sheets:spreadsheet"
    ]
  }
}

开通后记得保存：权限修改后，页面底部会有“保存”按钮，点击保存。

🚀 第六部分：创建版本并发布

配置完成后，需要发布应用才能正式生效。

6.1 创建版本

左侧导航栏找到 “版本管理与发布” ，点击进入
点击右上角的 “创建版本” 按钮
填写版本信息：
- 应用版本号：可以写 1.0.0（遵循语义化版本规范）
- 更新说明：简单写，比如“首次发布，接入OpenClaw AI助手”
点击 “保存”

6.2 提交发布

保存后，页面会显示刚创建的版本
点击版本右侧的 “提交发布” 或 “发布” 按钮
如果组织有管理员审核，需要等待审核通过；如果你是组织创建者，通常会即时生效

你会看到：版本状态变为“已发布”或“审核通过”。

提示：在飞书管理后台可以设置“自建应用免审”，这样发布后自动生效。

6.3 在飞书中找到你的机器人

打开飞书客户端（PC端或手机端均可）
在消息列表中，点击顶部的 “+” 或 “搜索”
搜索你创建的应用名称（比如“我的龙虾助理”）
点击进入，就可以开始和机器人聊天了！

🤝 第七部分：首次对话与配对

7.1 第一次对话可能遇到的问题

当你第一次给机器人发消息时，可能会收到一条特殊回复，类似：

【配对请求】
您正在尝试与OpenClaw机器人建立连接。为了安全起见，请执行以下命令完成配对：
openclaw pair --code ABC123 --user your_user_id

这是因为我们在配置中设置了 dmPolicy： pairing（配对模式），需要用户先和机器人“配对”才能使用。

7.2 如何完成配对

复制机器人回复中的配对命令（以 openclaw pair 开头的那行）
回到你的终端（和之前配置时用的同一个）

粘贴并执行这条命令

openclaw pair --code ABC123 --user your_user_id

你会看到：Pairing successful！ You can now chat with the bot.

如果使用较新版本，命令格式可能不同，可以尝试：

openclaw pairing approve feishu ABC123

7.3 查看待处理的配对请求

如果你想查看有哪些待批准的配对请求：

openclaw pairing list feishu

7.4 再次尝试对话

配对成功后，回到飞书，再发一条消息试试：

你好，现在能正常回复我吗？

你应该看到：机器人正常回复了！🎉

📱 第八部分：在手机端使用（移动办公）

飞书的最大优势就是移动端体验。现在你可以在手机上随时随地召唤AI助理了。

8.1 手机端操作步骤

下载飞书App（如果还没装）
- iOS：App Store 搜索“飞书”
- Android：各大应用商店搜索“飞书”
登录同一账号（和电脑端创建机器人时用的是同一个组织）
找到机器人：
- 点击底部的“消息”标签
- 点击右上角的“+”或搜索图标
- 搜索你的机器人名称
- 点击进入对话
开始使用：
- 输入文字指令：帮我整理一下今天的待办事项
- 发送文件：点击“+”→“文件”，选择文件发送给机器人
- 查看结果：机器人会处理并回复

8.2 移动端使用技巧

语音输入：飞书App支持语音转文字，可以直接说话发指令
图片处理：可以发截图给AI，让它识别图片中的文字或内容
后台运行：只要电脑/服务器上的OpenClaw在运行，手机随时可用

👥 第九部分：进阶配置——把机器人拉进群聊

9.1 将机器人添加到群聊

在飞书群聊中，点击右上角的“...”或群设置
选择 “群机器人” 或 “添加机器人”
搜索你的机器人名称，点击添加
确认添加

9.2 配置允许的群聊白名单

如果你在配置时选择了 groupPolicy： allowlist，需要告诉OpenClaw允许哪些群使用。

获取群ID的方法 ：

在飞书PC端，打开群聊
查看群聊URL，找到一串数字ID
例如群聊URL是 https：//applink.feishu.cn/client/chat/123456789，那么 123456789 就是群ID
更准确的方法是查看群聊信息，复制群ID（格式类似 oc_7725c177ac3fec7500c47047036a1b3e）

添加群到白名单 ：

# 使用 groupAllowFrom 配置（注意不同插件配置项名称可能不同）
openclaw config set channels.feishu.groupAllowFrom '["群ID1", "群ID2"]'

示例：

openclaw config set channels.feishu.groupAllowFrom '["oc_7725c177ac3fec7500c47047036a1b3e", "oc_987654321abcdef"]'

查看当前白名单：

openclaw config get channels.feishu.groupAllowFrom

重启网关生效 ：

openclaw gateway restart

9.3 群聊中使用技巧

必须@才响应：如果设置了 requireMention： true，在群里需要 @机器人它才会回应
避免干扰：这样机器人不会对群里的每一条消息都回应，只在被召唤时出现
示例：@我的龙虾助理帮我总结一下今天的聊天记录

🖼️ 第十部分：让机器人学会发图片和文件（进阶技巧）

10.1 飞书发图原理

飞书发送图片需要先上传获取 image_key，再调用API发送。高级插件如 @overlink/openclaw-feishu 已经内置了图片处理能力。

10.2 如果你使用基础版插件

如果使用 feishu-openclaw 基础版，可以通过配置让AI学会正确方法。

在OpenClaw工作区找到/创建 TOOLS.md 文件：

macOS/Linux/WSL2：~/.openclaw/TOOLS.md
Windows：C：\Users\你的用户名.openclaw\TOOLS.md

在文件中添加以下内容：

## 飞书发送图片的正确方法

注意：发送图片需要分三步：

### 步骤1：获取 tenant_access_token
curl -X POST "https：//open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type： application/json" \
  -d '{
    "app_id"："你的App ID",
    "app_secret"："你的App Secret"
  }'

### 步骤2：上传图片获取 image_key
curl -X POST "https：//open.feishu.cn/open-apis/im/v1/images" \
  -H "Authorization： Bearer 你的tenant_access_token" \
  -F "image_type=message" \
  -F "image=@/path/to/your/image.jpg"

### 步骤3：发送图片消息
curl -X POST "https：//open.feishu.cn/open-apis/im/v1/messages" \
  -H "Authorization： Bearer 你的tenant_access_token" \
  -H "Content-Type： application/json" \
  -d '{
    "receive_id"："用户的open_id",
    "msg_type"："image",
    "content"："{"image_key"： "你的image_key"}"
  }'

10.3 使用高级插件的媒体功能

如果使用 @overlink/openclaw-feishu 插件，可以配置媒体文件选项：

# 设置媒体文件保存目录
openclaw config set channels.feishu.mediaDir "~/.openclaw/media/feishu"

# 设置单个文件大小限制（MB）
openclaw config set channels.feishu.mediaMaxMb 30

10.4 文件大小限制

根据飞书官方限制：

图片：≤10MB
普通文件：≤30MB
语音消息：≤20MB

🌐 第十一部分：高级配置选项

11.1 设置机器人的回复语言

OpenClaw可以根据配置使用特定语言回复：

# 查看当前语言设置
openclaw config get model.language

# 设置为英文
openclaw config set model.language en

# 设置为中文
openclaw config set model.language zh

# 设置为自动检测（根据用户消息语言）
openclaw config set model.language auto

# 重启生效
openclaw gateway restart

语言代码：en(英语)、zh(中文)、ja(日语)、ko(韩语)、fr(法语)、de(德语)、es(西班牙语)等。

11.2 配置自动回复模式（无人值守群聊）

@overlink/openclaw-feishu 插件支持“自动回复模式”，让机器人像真人一样观察群聊并决定是否回复。

工作原理 ：

机器人收集群聊消息到缓冲区
当满足条件（消息数≥N，时间≥T，且3秒无新消息）
让AI决定是否回复（可以输出 [NO_RESPONSE] 保持沉默）

# 启用自动回复模式
openclaw config set channels.feishu.autoReply.enabled true

# 最少累积消息数（默认5条）
openclaw config set channels.feishu.autoReply.minMessages 5

# 最小时间窗口（毫秒，默认60000即1分钟）
openclaw config set channels.feishu.autoReply.minTimeMs 60000

# 防抖时间（毫秒，默认3000即3秒）
openclaw config set channels.feishu.autoReply.debounceMs 3000

# 重启生效
openclaw gateway restart

注意：@机器人的消息总是会触发回复，不受自动回复模式影响。

11.3 配置流式消息（打字机效果）

让机器人回复像打字一样逐字显示：

# 启用流式消息合并
openclaw config set channels.feishu.blockStreamingCoalesce.enabled true

# 最小发送延迟（毫秒）
openclaw config set channels.feishu.blockStreamingCoalesce.minDelayMs 500

# 最大发送延迟（毫秒）
openclaw config set channels.feishu.blockStreamingCoalesce.maxDelayMs 2000

# 启用“正在思考”卡片
openclaw config set channels.feishu.streamingCard.enabled true
openclaw config set channels.feishu.streamingCard.title "正在思考..."

11.4 配置多账号支持（高级）

OpenClaw支持同时管理多个飞书机器人：

# 直接编辑配置文件（~/.openclaw/openclaw.json）
# 第十二部分：配置文件详解（新增如何打开openclaw.json）

配置文件示例：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_main_xxx",
          "appSecret": "secret1",
          "botName": "主机器人"
        },
        "support": {
          "appId": "cli_support_xxx",
          "appSecretFile": "~/.secrets/support-bot.txt",
          "botName": "客服机器人",
          "dmPolicy": "allowlist"
        }
      }
    }
  }
}

11.5 配置多Agent路由（高级）

将不同的飞书对话路由到不同的AI Agent ：

{
  "bindings": [
    {
      "agentId": "tech-support",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "group",
          "id": "oc_tech_support_group"
        }
      }
    },
    {
      "agentId": "sales-assistant",
      "match": {
        "channel": "feishu",
        "peer": {
          "kind": "group",
          "id": "oc_sales_group"
        }
      }
    }
  ]
}

11.6 配置按用户细分的工具权限

根据发送者身份配置不同的工具权限：

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_your_group_id": {
          "requireMention": false,
          "toolsBySender": {
            "张三": { "deny": ["shell", "write_file"] },
            "ou_admin_id": { "allow": ["*"] },
            "*": { "allow": ["web_search", "feishu_card"] }
          }
        }
      }
    }
  }
}

📝 第十二部分：配置文件详解（新增完整章节）

12.1 什么是配置文件？

OpenClaw的配置文件是一个JSON格式的文件，记录了你的所有设置——包括飞书通道的App ID/Secret、各种策略、权限等。它是OpenClaw的“大脑”，所有配置都集中在这里。

12.2 配置文件在哪里？

根据你的操作系统，配置文件位于：

你的操作系统	配置文件完整路径	通俗理解
macOS	`/Users/你的用户名/.openclaw/openclaw.json`	你个人文件夹下的隐藏目录
Linux	`/home/你的用户名/.openclaw/openclaw.json`	同上
Windows	`C:\Users\你的用户名.openclaw\openclaw.json`	你的“用户”文件夹下的隐藏目录

注意：路径中的 ~ 符号代表“当前用户的主目录”，这是Linux/macOS中的简写。

12.3 如何打开配置文件？

macOS 用户

方法1：通过访达（Finder）打开（最简单）

打开访达（Finder）
点击顶部菜单栏的 “前往” → “前往文件夹...” （或按快捷键 Shift + Command + G）
在弹出的输入框中，复制粘贴以下内容：
```
~/.openclaw
```
点击 “前往”
你会看到：一个名为 openclaw.json 的文件（如果文件不存在，说明还没生成，可以先运行 openclaw onboard 生成）
双击该文件，系统会自动用默认的文本编辑器（如文本编辑）打开

方法2：通过终端 + 命令行编辑器

# 用 nano 打开（最简单，适合新手）
nano ~/.openclaw/openclaw.json

# 或者用 vim（需要一点学习成本）
vim ~/.openclaw/openclaw.json

# 或者用 VS Code（如果有安装）
code ~/.openclaw/openclaw.json

Windows 用户

方法1：通过文件资源管理器打开（最简单）

打开 “文件资源管理器” （任意文件夹窗口）
在地址栏直接复制粘贴以下内容，然后按回车：
```
%userprofile%.openclaw
```
为什么用这个：%userprofile% 是Windows的系统变量，会自动替换成你的用户文件夹路径，比如 C:\Users\张三
你会看到：openclaw.json 文件
右键点击该文件 → 选择 “打开方式” → 选择 “记事本” 或其他编辑器（推荐 VS Code 或 Notepad++）

方法2：让文件夹显示隐藏文件

如果看不到 .openclaw 文件夹（以点开头的文件夹在Windows中可能被隐藏）：

在文件资源管理器中，点击顶部菜单的 “查看”
勾选 “隐藏的项目”
隐藏的文件夹就会显示出来

方法3：通过 PowerShell 打开

# 用记事本打开
notepad $env:USERPROFILE.openclaw\openclaw.json

# 或者用 VS Code（如果安装了）
code $env:USERPROFILE.openclaw\openclaw.json

Linux 用户（包括 WSL2 Ubuntu）

方法1：通过命令行编辑器

# 用 nano 打开（最简单，适合新手）
nano ~/.openclaw/openclaw.json

# 用 vim 打开
vim ~/.openclaw/openclaw.json

# 用 VS Code（如果安装了）
code ~/.openclaw/openclaw.json

方法2：通过文件管理器

# 在文件管理器中打开目录
nautilus ~/.openclaw   # Ubuntu默认文件管理器
# 或者
xdg-open ~/.openclaw   # 任何Linux发行版

12.4 用什么软件打开最好？

软件名称	适用系统	优点	缺点	推荐度
VS Code	Windows/macOS/Linux	语法高亮、自动补全、JSON校验	需要安装	⭐⭐⭐⭐⭐ 首选
记事本	Windows	系统自带，不用装	无语法高亮，容易改错格式	⭐⭐ 临时用
文本编辑	macOS	系统自带	默认是富文本，需改纯文本	⭐⭐ 临时用
nano	Linux/macOS	终端内直接编辑，轻量	需要记快捷键	⭐⭐⭐ 推荐
Sublime Text	全平台	轻量、语法高亮好	需安装	⭐⭐⭐⭐
Notepad++	Windows	免费、语法高亮	需安装	⭐⭐⭐⭐

如果你还没安装 VS Code，强烈建议安装：https://code.visualstudio.com/

12.5 如果文件不存在怎么办？

如果你发现 .openclaw 文件夹不存在，或者里面没有 openclaw.json 文件，可能是因为：

你还没有运行过 OpenClaw：首次安装后需要运行 openclaw onboard 才会生成配置文件
运行了但还没完成初始化：执行以下命令手动生成：
```
openclaw onboard  # 重新运行配置向导
```

12.6 JSON 格式敏感，修改要小心！

JSON 文件对格式要求非常严格，多一个逗号、少一个引号都会导致 OpenClaw 启动失败！

常见错误：

// ❌ 错误：多了一个逗号
{
  "enabled": true,   ← 最后一个属性后面不能有逗号
}

// ✅ 正确
{
  "enabled": true
}

修改建议：

如果手动修改，修改后可以用在线工具校验：https://jsonlint.com/
推荐用 VS Code 编辑，它会自动提示格式错误

12.7 备份好再改！

修改前强烈建议备份：

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d)

12.8 修改后要重启网关

配置文件修改后，需要重启 OpenClaw 网关才能生效：

openclaw gateway restart

12.9 完整配置示例

一个完整的飞书通道配置示例：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxx",
      "domain": "feishu",
      "connectionMode": "websocket",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "requireMention": true,
      "groupAllowFrom": [
        "oc_7725c177ac3fec7500c47047036a1b3e"
      ],
      "mediaDir": "~/.openclaw/media",
      "mediaMaxMb": 30,
      "autoReply": {
        "enabled": false,
        "minMessages": 5,
        "minTimeMs": 60000,
        "debounceMs": 3000
      }
    }
  }
}

🚨 第十三部分：故障排查大全（全网验证版）

13.1 飞书机器人完全收不到消息

检查清单 ：

检查项	检查方法	正确状态
✅ 插件已安装	`openclaw plugins list`	看到 `feishu-openclaw` enabled
✅ 插件无冲突	`openclaw plugins list`	只有一个飞书插件
✅ App ID/Secret已配置	`openclaw config get channels.feishu`	有appId，appSecret显示*****
✅ 网关已重启	`openclaw status`	gateway： running
✅ 通道状态正常	`openclaw channel list`	Feishu显示 enabled/running/configured
✅ 飞书应用已发布	飞书开放平台→版本管理	状态为“已发布”
✅ 事件订阅配置正确	飞书开放平台→事件与回调	订阅方式为“长连接”，已添加接收消息事件
✅ 权限已开通	飞书开放平台→权限管理	所有必需权限已开通
✅ 应用可用范围包含你	飞书开放平台→成员管理	你的账号在可用成员列表中

13.2 长连接报错“未建立长连接”

现象：在飞书开放平台保存事件配置时报错

原因：App ID/Secret未通过验证，或网关未正确重启

解决方法 ：

# 1. 确认App ID/Secret正确
openclaw config get channels.feishu

# 2. 重启网关
openclaw gateway restart

# 3. 等待10-20秒

# 4. 返回飞书开放平台再次保存

13.3 插件冲突问题

现象：openclaw plugins list 看到多个飞书插件

解决方法 ：

# 禁用内置插件
openclaw plugins disable @openclaw/feishu

# 重启网关
openclaw gateway restart

13.4 启动命令误用

现象：执行 openclaw start 提示 error： unknown command 'start'

根因：OpenClaw CLI 没有 start 命令，正确的启动命令是 gateway

解决方法：

openclaw gateway start

13.5 长连接已开启但机器人无响应

现象：群内@机器人无回复，运行日志无新增事件记录

根因：仅开启长连接模式，未订阅消息类事件

解决方法：在飞书开放平台补订阅 im.message.receive_v1 事件

13.6 群白名单策略配置失准

现象：服务启动正常、长连接已建立，但群内@机器人仍无响应

根因：groupPolicy 设为 allowlist 时，groupAllowFrom 未配置真实群ID

解决方法 ：

# 将正确的群ID添加到白名单
openclaw config set channels.feishu.groupAllowFrom '["oc_真实的群ID"]'
openclaw gateway restart

13.7 配对失败

现象：执行配对命令后提示失败

可能原因：

配对码已过期（通常5分钟内有效）
执行的终端与运行OpenClaw的不是同一台机器

解决方法：

让机器人重新发一条消息，获取新的配对码
确保在运行OpenClaw的机器上执行配对命令
如果是WSL2环境，确保在Ubuntu终端中执行

13.8 群聊中机器人不响应@

现象：在群里@机器人，但没有反应

可能原因 ：

权限问题：检查是否开通了 im：message.group_at_msg：readonly 权限
白名单问题：如果设置了 groupPolicy： allowlist，需要把群ID加入白名单
@格式问题：确保输入法正确，@后要有空格或直接跟上内容

查看当前白名单：

openclaw config get channels.feishu.groupAllowFrom

添加群到白名单 ：

openclaw config set channels.feishu.groupAllowFrom '["群ID1"]'
openclaw gateway restart

13.9 文件发送失败

现象：发送文件给机器人，机器人无法处理

可能原因 ：

未开通 im：resource 权限
文件格式不支持或过大（图片≤10MB，文件≤30MB）

解决方法 ：

在飞书开放平台开通 im：resource 权限
重新发布应用
重启网关
再次尝试发送小文件测试

13.10 ⚠️ 企业IP白名单问题（新增！）

现象：所有配置正确，但飞书开放平台一直提示“未建立长连接”，或日志中显示连接超时

可能原因：企业开启了IP白名单，拦截了对飞书API的访问

解决方法 ：

联系企业IT管理员，将运行OpenClaw的服务器IP加入白名单
需要开放的域名：
- open.feishu.cn
- api.feishu.cn
- www.feishu.cn

终极解决方案：如果无法加入白名单，可以使用 Cloudflare Tunnel 等内网穿透工具：

# 安装 cftunnel
npm install -g cftunnel

# 启动隧道（自动提供HTTPS）
cftunnel --port 18789

13.11 Windows安装失败（spawn npm ENOENT）

现象：openclaw plugins install 失败，提示 spawn npm ENOENT

解决方法 ：改用手动安装（见3.4节的“方式3”）

13.12 如何查看完整日志

# 实时查看日志（最常用）
openclaw logs follow

# 查看最近100行日志
openclaw logs --lines 100

# 将日志保存到文件，方便求助时发送
openclaw logs > error.log

启动成功标识 ：

gateway listening on ws：//...（网关监听正常）
feishu ... ws client ready（飞书长连接建立）

📝 第十四部分：常用命令速查表

14.1 插件管理命令

操作	命令
安装飞书插件	`openclaw plugins install feishu-openclaw`
安装高级插件	`openclaw plugins install @overlink/openclaw-feishu`
查看插件列表	`openclaw plugins list`
启用插件	`openclaw plugins enable feishu-openclaw`
禁用插件	`openclaw plugins disable feishu-openclaw`

14.2 配置命令

操作	命令
启用飞书通道	`openclaw config set channels.feishu.enabled true`
配置App ID	`openclaw config set channels.feishu.appId "你的App ID"`
配置App Secret	`openclaw config set channels.feishu.appSecret "你的App Secret"`
设置连接模式	`openclaw config set channels.feishu.connectionMode websocket`
设置私聊策略	`openclaw config set channels.feishu.dmPolicy pairing`
设置群聊策略	`openclaw config set channels.feishu.groupPolicy allowlist`
设置需要@	`openclaw config set channels.feishu.requireMention true`
设置国内版	`openclaw config set channels.feishu.domain feishu`
设置国际版	`openclaw config set channels.feishu.domain lark`

14.3 白名单配置命令

操作	命令
设置群白名单	`openclaw config set channels.feishu.groupAllowFrom '["群ID1"]'`
查看群白名单	`openclaw config get channels.feishu.groupAllowFrom`
设置用户白名单	`openclaw config set channels.feishu.allowFrom '["用户ID1"]'`

14.4 高级配置命令

操作	命令
设置媒体目录	`openclaw config set channels.feishu.mediaDir "~/.openclaw/media"`
设置文件大小限制	`openclaw config set channels.feishu.mediaMaxMb 30`
启用自动回复	`openclaw config set channels.feishu.autoReply.enabled true`
设置语言	`openclaw config set model.language en`
启用流式消息	`openclaw config set channels.feishu.blockStreamingCoalesce.enabled true`

14.5 查询命令

操作	命令
查看飞书通道配置	`openclaw config get channels.feishu`
查看所有通道状态	`openclaw channel list`
查看网关状态	`openclaw status`
健康检查	`openclaw doctor`
查看实时日志	`openclaw logs follow`

14.6 网关管理命令

操作	命令
启动网关	`openclaw gateway start`
停止网关	`openclaw gateway stop`
重启网关	`openclaw gateway restart`
查看网关状态	`openclaw gateway status`

14.7 配对管理命令

操作	命令
查看待处理配对	`openclaw pairing list feishu`
批准配对	`openclaw pairing approve feishu <CODE>`

14.8 直接修改配置文件

如果你更喜欢编辑文件，配置文件位置：

macOS/Linux/WSL2：~/.openclaw/openclaw.json
Windows：C：\Users\你的用户名.openclaw\openclaw.json

🎓 第十五部分：总结

恭喜你！现在你已经成功将OpenClaw接入了飞书，拥有了一个24小时在线的AI助理。回顾一下我们今天完成的工作：

✅ 创建机器人：在飞书开放平台创建了企业自建应用
✅ 获取凭证：拿到了App ID和App Secret这对“身份证”
✅ 安装插件：安装了 feishu-openclaw 插件（最关键！很多人漏掉）
✅ 配置通道：在OpenClaw中配置了飞书通道
✅ 处理冲突：禁用了可能冲突的旧版插件
✅ 配置飞书：开通了权限、添加了事件、选择了长连接
✅ 发布应用：让机器人正式上线
✅ 完成配对：安全验证后开始使用
✅ 学习技巧：学会了群聊配置、图片发送、自动回复、多语言等高级功能
✅ 掌握配置文件：学会了如何打开和编辑 openclaw.json

从此以后，你的AI助理就住进了聊天框——无论是在电脑前办公，还是在通勤路上，甚至出差在外，只要打开飞书，就能随时唤醒它帮你干活。

常见错误预防清单

错误类型	预防措施
插件没装	✅ 执行 `openclaw plugins list` 确认
配置顺序错	✅ 先配App ID再配长连接
文件权限漏	✅ 确认开通 `im：resource` 权限
插件冲突	✅ 禁用内置 `@openclaw/feishu`
配对失败	✅ 在运行OpenClaw的机器上执行
群聊不响应	✅ 检查 `groupAllowFrom` 白名单
企业网络限制	✅ 确认IP白名单或使用隧道
配置文件打不开	✅ 按12.3节方法正确打开
JSON格式错误	✅ 用VS Code编辑，修改前备份

下一站可以做什么？

安装更多技能：让AI学会更多本领，比如文件整理、网页搜索

openclaw skills search 文件管理
openclaw skills install 文件整理大师

配置更多模型：尝试不同的AI模型，找到最适合你的

openclaw config set model.provider openai
openclaw config set model.apiKey sk-xxxxx

部署到云服务器：实现7×24小时不间断运行，彻底摆脱本地电脑限制
- 推荐：阿里云/腾讯云轻量应用服务器（2核4G足够）
- 系统选 Ubuntu 22.04，按Linux版教程安装
配置多Agent路由：让不同的群使用不同的AI Agent

获取帮助

如果在配置过程中遇到任何问题：

查看实时日志 ：
```
openclaw logs follow
```

使用求助模板（复制发给别人）：

系统：Windows WSL2/macOS/Linux
问题现象：______
已做操作：______
日志最后10行：
[粘贴日志]

官方资源：
- OpenClaw官方文档：https：//docs.openclaw.ai/zh-CN
- GitHub Issues：https：//github.com/openclaw/openclaw/issues
- 飞书开放平台文档：https：//open.feishu.cn/document

📖 附录：术语解释表

术语	通俗解释
App ID	飞书机器人的“身份证号”，用来唯一标识你的机器人
App Secret	飞书机器人的“密码”，用于验证身份，不能泄露
WebSocket	一种长连接技术，让OpenClaw和飞书服务器保持实时通信，无需公网IP
长连接	双方建立连接后一直保持，有新消息即时推送，不用反复握手
插件	给OpenClaw扩展功能的组件，飞书插件让它能和飞书通信
Gateway	OpenClaw的核心服务，负责消息路由和连接管理
配对（Pairing）	首次使用时的安全验证，确保是你本人在操作
白名单	允许访问的列表，只有在名单中的群/用户才能使用机器人
domain	指定飞书版本（国内版feishu/国际版lark）
自动回复模式	机器人像真人一样观察群聊，智能决定是否回复
JSON	一种轻量级的数据交换格式，用于存储配置信息
配置文件	存储OpenClaw所有设置的“大脑”，位于 `~/.openclaw/openclaw.json`