1. 第一次私聊时，OpenClaw 默认会要求做一次配对审批，审批通过后才能正常聊天。

二、先看你适不适合直接做这套

你需要准备这几样东西：

  • 一台 Windows、Linux 或 macOS 机器
  • 能联网
  • 能安装 Node.js
  • 有一个可用的大模型 API Key
  • 有飞书账号，并且最好能进入飞书开放平台创建企业自建应用

OpenClaw 官方当前建议 Node.js 用 Node 24，同时说明 Node 22.16+ 也支持；安装完成后建议跑 openclaw onboard --install-daemon，然后用 openclaw gateway status 看 Gateway 是否已运行。

三、整体流程先看一遍

整个接入链路只有 6 步：

  1. 安装 OpenClaw
  2. 启动并确认 Gateway 正常
  3. 在飞书开放平台创建应用
  4. 开权限、开 Bot、开事件订阅
  5. 回到 OpenClaw 配置飞书 App ID / App Secret
  6. 在飞书里发消息，完成第一次配对审批

OpenClaw 官方飞书页本身就是按这个顺序写的：先建应用，再配 OpenClaw，再启动测试。

四、第 1 步：安装 OpenClaw

1）安装命令

如果你是 Linux / macOS：

curl -fsSL https://openclaw.ai/install.sh | bash

如果你是 Windows PowerShell：

iwr -useb https://openclaw.ai/install.ps1 | iex

这是 OpenClaw 官方 Getting Started 页给出的安装方式。

2）初始化 OpenClaw

安装后执行：

openclaw onboard --install-daemon

这个向导会引导你完成：

  • 模型提供商选择
  • API Key 配置
  • Gateway 配置

官方文档说明这个流程大约几分钟就能完成。

3）验证是否装好

执行：

node --version
openclaw gateway status
openclaw dashboard

如果 Gateway 正常，官方文档说你会看到它监听在 18789 端口；openclaw dashboard 会打开浏览器控制台页面。

五、第 2 步：先确认 OpenClaw 本体能工作

在接飞书前，先不要急着配飞书，先确认本体工作正常。

1）检查 Gateway 状态

openclaw gateway status

2）打开本地控制台

openclaw dashboard

或者直接浏览器访问：

http://127.0.0.1:18789/

OpenClaw 官方 Control UI 页面明确写了本地默认地址就是这个。

3）在 Dashboard 里发一条消息

如果这里都不能聊天，就先别继续接飞书。因为飞书只是把消息“转发进来”，本质上后端还是 OpenClaw 自己要先能正常回复。这个判断逻辑和 OpenClaw 官方 Getting Started 的步骤一致：先本地聊天成功，再去接渠道。

六、第 3 步：确认飞书插件是否可用

OpenClaw 当前官方飞书文档写得很清楚：
飞书插件随当前 OpenClaw 版本捆绑提供，通常不需要单独安装。
只有在较旧版本或自定义安装里，才需要手动安装：

openclaw plugins install @openclaw/feishu

所以你大多数情况下不用额外装插件。

你也可以先看一下当前插件情况：

openclaw plugins list

这不是飞书页强制要求，但对排查很有帮助。

七、第 4 步：在飞书开放平台创建应用

现在开始进入飞书侧。

OpenClaw 官方飞书页明确写了：
前往飞书开放平台创建企业应用；如果你是国际版 Lark 租户，要用 Lark 的开放平台，并在 OpenClaw 配置里把 domain 设成 lark。

1）打开飞书开放平台

进入飞书开放平台并登录你的账号。
如果是 Lark 国际版，使用对应国际版平台，并在后续配置中设置：

{
  "channels": {
    "feishu": {
      "domain": "lark"
    }
  }
}

这个 domain: "lark" 是 OpenClaw 官方飞书文档明确给出的。

2）创建企业自建应用

在平台里创建企业应用，填写：

  • 应用名称
  • 应用描述
  • 应用图标

OpenClaw 官方飞书页把这一步列为“Create enterprise app”。

3）复制两个最重要的值

创建好应用后，到 Credentials & Basic Info 页面，复制：

  • App ID
  • App Secret

OpenClaw 官方文档说明 App ID 的格式通常像 cli_xxx，同时特别提醒 App Secret 必须妥善保密。

八、第 5 步：先回 OpenClaw 里把飞书渠道加上

这一步非常关键，而且很多人会做反。

OpenClaw 官方飞书文档明确提醒：
在飞书平台里设置事件订阅前，你需要先运行过 openclaw channels add，并确保 Gateway 正在运行。
否则飞书长连接设置可能保存不了。

推荐做法：用交互式配置

执行：

openclaw channels add

然后在交互列表里选择 Feishu，接着输入：

  • App ID
  • App Secret

OpenClaw 官方飞书页把这一步列为推荐方式。

配完后建议立刻检查

openclaw gateway status
openclaw logs --follow

这是官方飞书页和官方 troubleshooting 页都建议优先使用的检查命令。

九、第 6 步：如果你想手工改配置文件，这样写

如果你不想走 openclaw channels add，也可以直接编辑：

~/.openclaw/openclaw.json

OpenClaw 官方给出的最基础飞书配置如下：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "My AI assistant"
        }
      }
    }
  }
}

这里最重要的几个字段含义是：

  • enabled: true：启用飞书渠道
  • dmPolicy: "pairing"：私聊默认先走配对审批
  • accounts.main.appId：飞书应用 ID
  • accounts.main.appSecret：飞书应用密钥
  • botName：机器人显示名称

这些字段都来自 OpenClaw 官方飞书文档。

通过环境变量也能配

官方还给了环境变量方式：

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

不过对小白来说，还是更建议用 openclaw channels add。

十、第 7 步：回到飞书开放平台，给应用开权限

OpenClaw 官方飞书页直接给了一段可批量导入的权限 JSON，其中包含很多权限；对聊天接入最关键的，是能接收消息、读取消息、以 Bot 身份发送消息。文档里明确列出了例如：

  • im:message.group_at_msg:readonly
  • im:message.p2p_msg:readonly
  • im:message:readonly
  • im:message:send_as_bot

这些权限在 OpenClaw 官方飞书文档中都写到了。

你在飞书开放平台的 Permissions 里，可以按官方文档建议使用 Batch import 导入权限。
如果你不想整段导入，至少要保证消息接收和 Bot 发送相关权限已加上，否则机器人收得到也发不出去。OpenClaw 官方飞书故障排查页特别点名：若消息发送失败，先看 im:message:send_as_bot 权限。

十一、第 8 步：启用 Bot 能力

在飞书开放平台里进入：

App Capability > Bot

然后：

  1. 启用 Bot
  2. 设置机器人名称

这是 OpenClaw 官方飞书接入页明写的步骤。不开这个能力，后面根本没法聊天。

十二、第 9 步：配置飞书事件订阅

这是飞书接入 OpenClaw 的核心步骤。

OpenClaw 官方飞书页明确说明：
它接飞书不是靠传统公网 webhook，而是靠WebSocket 长连接事件订阅。

你在飞书开放平台的 Event Subscription 里这样配：

  1. 选择 Use long connection to receive events（WebSocket）
  2. 添加事件：im.message.receive_v1

这两个点 OpenClaw 官方飞书页写得非常明确。

另外，飞书官方开发文档也确认：事件订阅支持两种模式——开发者服务器 URL 和长连接模式；长连接模式可以降低接入成本，适合企业自建应用。

这一页最容易踩的坑

如果你发现飞书平台里长连接设置保存不了，先检查两件事：

  • 你是不是已经执行过 openclaw channels add
  • openclaw gateway status 是否正常

这是 OpenClaw 官方飞书页直接给出的前置条件。

十三、第 10 步：发布飞书应用

飞书侧做完配置后，不能直接就拿来用，通常还要发布。

OpenClaw 官方飞书页给出的流程是：

  1. 到 Version Management & Release
  2. 创建版本
  3. 提交审核并发布
  4. 等待管理员批准

文档还提到企业应用通常会自动批准，但这取决于你的租户权限设置。

如果你是普通成员，没有企业管理员权限，这一步可能会卡住。那不是 OpenClaw 问题，而是飞书租户权限问题。

十四、第 11 步：启动 Gateway 并开始实测

现在回到 OpenClaw。

启动网关：

openclaw gateway

OpenClaw 官方飞书页把这个作为测试前的第一步。

另开一个终端，持续看日志：

openclaw logs --follow

这样你在飞书里发消息时，能第一时间看到有没有事件进来。这个命令也是官方排查命令梯子的一部分。

十五、第 12 步：在飞书里给机器人发第一条消息

现在去飞书客户端里：

  1. 找到你刚发布的机器人
  2. 给它发一条消息，比如：
    你好
    你是谁
    帮我写一段自我介绍

OpenClaw 官方飞书文档说明，默认情况下第一次私聊会触发配对流程。

十六、第 13 步：处理第一次配对审批

OpenClaw 的飞书默认私聊策略是：

"dmPolicy": "pairing"

这意味着未知用户第一次私聊不会直接进入正式聊天，而是先收到一个配对码。

1）查看待审批配对

openclaw pairing list feishu

2）批准该用户

openclaw pairing approve feishu <CODE>

OpenClaw 官方飞书文档和 Pairing 文档都明确列出了这两个命令。

审批完之后，你再回飞书继续发消息，就会正常回复了。

十七、第 14 步：验收是否真的接通

你可以用下面 5 条作为验收标准：

  1. openclaw gateway status 显示运行正常
  2. openclaw logs --follow 能看到飞书消息进入
  3. 飞书里能找到机器人
  4. 第一次私聊能收到配对码
  5. 批准配对后，机器人能正常回答问题

这几项都能对应到 OpenClaw 官方飞书文档、Pairing 文档和 Getting Started 文档。

十八、群聊怎么接入

当私聊跑通后，你再做群聊。

OpenClaw 官方飞书页明确说明，飞书群聊默认是允许的，但默认要求 @ 提及机器人 才会回复。

默认群聊行为

  • groupPolicy: "open"：允许群里消息
  • requireMention: true：默认必须 @ 机器人

官方文档给出的默认示例就是：

{
  "channels": {
    "feishu": {
      "groupPolicy": "open"
    }
  }
}

这里注释说明默认 requireMention: true。

如果你想群里不 @ 也回复

{
  "channels": {
    "feishu": {
      "groups": {
        "oc_xxx": {
          "requireMention": false
        }
      }
    }
  }
}

这里的 oc_xxx 就是飞书群的 chat_id。

如果你只想允许某几个群

{
  "channels": {
    "feishu": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["oc_xxx", "oc_yyy"]
    }
  }
}

这也是 OpenClaw 官方飞书页给的原生示例。

十九、怎么拿到飞书群 ID 和用户 ID

这是很多人后面做权限控制时一定会遇到的。

OpenClaw 官方飞书页写了最简单的方法：

拿群 ID（chat_id）

  1. 启动 Gateway
  2. 在群里 @ 机器人
  3. 执行：
openclaw logs --follow

然后在日志里找 chat_id，格式通常像 oc_xxx。

拿用户 ID（open_id）

  1. 给机器人发私聊
  2. 执行：
openclaw logs --follow

然后在日志里找 open_id，格式通常像 ou_xxx

另外也可以通过：

openclaw pairing list feishu

查看配对请求中的用户 Open ID。

二十、最常用的几个命令

飞书接入后，建议你先记住这些：

openclaw gateway status
openclaw gateway restart
openclaw logs --follow
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
openclaw channels status --probe
openclaw doctor

其中前 5 个在飞书页和 troubleshooting 页都能直接对应到；channels status --probe 和 doctor 是官方通用排查命令。

二十一、常见问题 1：机器人在群里不回我

这是最常见的问题之一。

OpenClaw 官方飞书页给出的检查思路是：

  1. 确认机器人已经被拉进群
  2. 确认你 @ 了机器人
  3. 确认 groupPolicy 不是 "disabled"
  4. 看日志 openclaw logs --follow

因为飞书群聊默认确实要求 @ 提及。

二十二、常见问题 2：机器人收不到消息

优先检查这几项：

  • 应用是不是已经发布
  • Event Subscription 是否选了 WebSocket
  • 是否加了 im.message.receive_v1
  • Gateway 是否正在运行
  • 是否已经先执行过 openclaw channels add

这些都是 OpenClaw 官方飞书页反复强调的关键点。

二十三、常见问题 3：机器人发不出消息

最先查权限：

  • im:message:send_as_bot

OpenClaw 官方飞书页在故障排查部分明确指出，消息发送失败时优先确认这个权限。

二十四、常见问题 4：我用了国际版 Lark，为什么不通

你需要在 OpenClaw 配置里加上：

{
  "channels": {
    "feishu": {
      "domain": "lark"
    }
  }
}

或者按账户设置 channels.feishu.accounts.<id>.domain。这是官方飞书文档给出的 Lark 国际版要求。

二十五、常见问题 5：我需要公网服务器吗

大多数情况下，不需要为了接收飞书消息额外做公网 webhook。
因为 OpenClaw 飞书接入的默认思路就是用飞书的 WebSocket 事件订阅。飞书官方文档也确认长连接是一种正式支持的接收事件方式。

只有当你自己特别想改成 webhook 模式时，才需要额外处理 verificationToken、encryptKey、以及绑定地址等问题。OpenClaw 飞书页也提到了 webhook 模式下这些字段。

二十六、常见问题 6：我想让回复更丝滑，能流式输出吗

可以。

OpenClaw 官方飞书页说明，飞书支持通过交互式卡片进行流式回复，而且默认就是开启的。配置示例如下：

{
  "channels": {
    "feishu": {
      "streaming": true,
      "blockStreaming": true
    }
  }
}

如果你不想流式，设成：

"streaming": false

即可。

二十七、适合小白的最稳配置

如果你现在只是想先跑通，我建议你先用这一版：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "你的AppSecret",
          "botName": "OpenClaw助手"
        }
      }
    }
  }
}

这个组合的特点是：

  • 私聊安全：第一次需要审批
  • 群聊能用：默认开放
  • 群聊不容易乱回：默认仍要求 @
  • 配置最少，问题最少

这些字段都来自 OpenClaw 官方飞书配置项。

二十八、给你一份“从 0 到 1 最短执行清单”

你可以直接照这个顺序走：

A. 装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

B. 创建飞书应用

  • 飞书开放平台创建企业应用
  • 复制 App ID / App Secret
  • 开 Bot 能力
  • 配消息权限
  • 事件订阅选 WebSocket
  • 加 im.message.receive_v1
  • 发布应用

C. 配 OpenClaw

openclaw channels add

选择 Feishu，填入 App ID / App Secret。

D. 启动并看日志

openclaw gateway
openclaw logs --follow

E. 飞书里发消息

第一次收到配对码后执行：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

审批后开始正常聊天。

二十九、你后面可以继续升级的方向

飞书接通后，下一步一般有三条路：

  1. 给它接你自己的知识库
  2. 给它绑定不同智能体
  3. 在群里按部门/项目做不同路由

OpenClaw 飞书页已经支持多账户、流式回复、ACP 会话、多智能体路由等更高级能力。

三十、最重要的排错口诀

只要出问题，先按官方命令梯子走：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

这是 OpenClaw 官方 troubleshooting 页明确给出的标准顺序。

# AI # ubuntu
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

【无标题】

avatar 龙虾开发者社区
cover

炸了！扒完 51 万行泄露的 AI 源码，我发现：你的 AI 傻，根本不是模型的锅

avatar 龙虾开发者社区

本地小龙虾搭建-16g内存

或使用镜像下载链接：https://openclaw.ikidi.top/api/download/package/22?如果你不想额外安装 Ollama，某些版本的 OpenClaw 一键安装包已经内置了优化版模型，无需任何配置即可使用。配置文件位置：C:\Users\你的用户名\.openclaw\openclaw.json。⚠️ 注意：内置模型可能不是最新的 Qwen3.5，具体取决于你下载

avatar 龙虾开发者社区