OpenClaw 添加飞书机器人：从零到上线的完整指南

如果你正在用 OpenClaw 搭建 AI 助手，飞书作为国内主流的办公协作平台，自然是一个不可忽视的消息渠道。把 AI 能力接入飞书，意味着你的团队成员可以直接在飞书里和 AI 机器人对话——无论是私聊还是群组，都能随时获得智能回复。

这篇文档会带你一步步完成 OpenClaw 飞书机器人的配置，从创建飞书应用到最终上线，每个环节都有详细说明。

你需要准备什么

在开始之前，请确认以下几点：

• 已经安装好 OpenClaw 并完成基础配置
• 拥有飞书账号（管理员权限更佳）
• 能够访问飞书开放平台

安装飞书插件

OpenClaw 通过插件机制支持不同的消息渠道。要接入飞书，首先需要安装 Feishu 插件：

openclaw plugins install @openclaw/feishu

如果你是从源码开发，也可以使用本地安装方式（在 git 仓库内运行）：

openclaw plugins install ./extensions/feishu

两种添加飞书渠道的方式

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

如果你刚装完 OpenClaw，直接运行向导是最省心的选择：

openclaw onboard

向导会一步步引导你完成创建飞书应用、配置凭证、启动网关这三个关键步骤，基本上跟着提示走就行。

配置完成后，可以用这两个命令确认一切就绪：

• openclaw gateway status — 查看网关运行状态
• openclaw logs --follow — 查看实时日志

方式二：命令行手动添加

已经用过 OpenClaw 的话，可以直接用命令行添加渠道：

openclaw channels add

在交互式提示中选择 Feishu，输入 App ID 和 App Secret 即可。配置完成后，记得用 openclaw gateway restart 重启网关让新配置生效。

第一步：创建飞书应用

这一步需要在飞书开放平台上操作，一共有 7 个小步骤。

1. 登录飞书开放平台

访问 飞书开放平台，用你的飞书账号登录。

如果你使用的是 Lark（国际版），请访问 https://open.larksuite.com/app ，并在后续配置中设置 domain: "lark"。

2. 创建企业自建应用

登录后，点击 创建企业自建应用，填写应用名称和描述，选择一个应用图标。

3. 获取应用凭证

进入应用的 凭证与基础信息 页面，你需要复制两个关键信息：

• App ID（格式类似 cli_xxx）
• App Secret

这两个凭证后续配置 OpenClaw 时会用到，请妥善保管，特别是 App Secret，千万不要分享给他人。

4. 配置应用权限

在 权限管理 页面，点击 批量导入 按钮，粘贴以下 JSON 配置，即可一键导入所有必需权限：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "docs:document.content:read",
      "event:ip_list",
      "im:chat",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "sheets:spreadsheet",
      "wiki:wiki:readonly"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

5. 启用机器人能力

进入 应用能力 > 机器人 页面，开启机器人能力并配置机器人名称。这一步很简单，打开开关就好。

6. 配置事件订阅

这一步有个前提条件需要特别注意：在配置事件订阅前，你必须先完成以下两件事：

1. 运行 openclaw channels add 添加了飞书渠道
2. 网关处于启动状态（可通过 openclaw gateway status 确认）

确认无误后，在 事件订阅 页面：

1. 选择 使用长连接接收事件（WebSocket 模式）
2. 添加事件：im.message.receive_v1（接收消息）

如果网关没有启动或渠道还没添加，长连接设置会保存失败，这是一个容易踩的坑。

7. 发布应用

最后一步，在 版本管理与发布 页面创建版本，提交审核并发布。企业自建应用通常会自动通过审批，不需要等太久。

第二步：配置 OpenClaw

拿到 App ID 和 App Secret 之后，就可以在 OpenClaw 这边进行配置了。这里提供三种配置方式，选择最适合你的即可。

方式一：命令行交互式配置（推荐）

openclaw channels add

选择 Feishu，按提示输入凭证信息，最简单直接。

方式二：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的AI助手",
        },
      },
    },
  },
}

方式三：环境变量

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

Lark 国际版配置

如果你的租户在 Lark 国际版，需要额外设置域名：

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

第三步：启动并测试

配置完成后，启动网关：

openclaw gateway

然后在飞书中找到你创建的机器人，给它发一条消息。

默认情况下，机器人会回复一个 配对码。你需要在终端中批准这个配对请求：

openclaw pairing approve feishu <配对码>

批准后就可以正常对话了。试着发几条消息，确认机器人能正确响应。

访问控制配置

OpenClaw 提供了灵活的访问控制机制，你可以精确控制谁能和机器人对话。

私聊策略（dmPolicy）

群组策略（groupPolicy）

默认情况下，机器人在群组中需要被 @提及 才会响应。如果你希望机器人在某个群组中无需 @也能响应，可以针对特定群组关闭这个限制：

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

如何获取群组和用户 ID

在配置访问控制时，你需要知道群组 ID（oc_xxx 格式）和用户 ID（ou_xxx 格式）。最简单的获取方法是：

1. 启动网关
2. 在飞书中给机器人发消息或在群组中 @机器人
3. 运行 openclaw logs --follow 查看日志，里面会包含对应的 ID 信息

高级功能

流式输出

飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容来展示生成进度。这个功能默认是开启的：

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

消息引用

在群聊场景中，机器人的回复可以引用用户的原始消息，让对话上下文更加清晰：

需要注意的是，消息引用和流式卡片输出不能同时使用。

多账号管理

如果你需要管理多个飞书机器人，可以在配置中设置多个账号：

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "主机器人",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "备用机器人",
          enabled: false,
        },
      },
    },
  },
}

多 Agent 路由

通过 bindings 配置，你可以用一个飞书机器人对接多个不同功能的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent：

{
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "dm", id: "ou_28b31a88..." },
      },
    },
    {
      agentId: "customer-service",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_xxx..." },
      },
    },
  ],
}

配额优化

如果你担心飞书 API 调用量过大，可以通过以下配置来优化：

• typingIndicator: false — 不发送"正在输入"状态提示
• resolveSenderNames: false — 不拉取发送者资料信息

常用命令速查

机器人内置命令

飞书目前不支持原生命令菜单，这些命令需要以文本形式直接发送。

网关管理命令

支持的消息类型

接收（飞书 → 机器人）

• 文本消息
• 富文本（帖子）
• 图片
• 文件
• 音频
• 视频
• 表情包

发送（机器人 → 飞书）

• 文本消息
• 图片
• 文件
• 音频
• 富文本（部分支持）

遇到问题怎么办

机器人在群组中不响应

1. 确认机器人已经被添加到群组
2. 检查是否 @了机器人（默认需要 @提及）
3. 确认 groupPolicy 没有设置为 "disabled"
4. 查看日志排查：openclaw logs --follow

机器人完全收不到消息

1. 确认应用已发布并审批通过
2. 检查事件订阅配置是否正确（需添加 im.message.receive_v1）
3. 确认选择了长连接模式
4. 检查应用权限是否完整
5. 确认网关正在运行：openclaw gateway status

App Secret 不小心泄露了

1. 立刻去飞书开放平台重置 App Secret
2. 更新本地配置文件中的 App Secret
3. 重启网关：openclaw gateway restart

消息发送失败

1. 检查应用是否拥有 im:message:send_as_bot 权限
2. 确认应用已发布
3. 查看日志获取详细错误信息

以上就是 OpenClaw 接入飞书机器人的完整流程。整个过程核心就是三步：在飞书创建应用拿到凭证、在 OpenClaw 配置凭证、启动网关测试。如果你在配置过程中遇到其他问题，可以查看 OpenClaw 官方文档 获取更多帮助。