批准后，你就可以正常聊天了。

***

## 概览

* **飞书机器人渠道**：由 Gateway 网关管理的飞书机器人
* **确定性路由**：回复始终返回到飞书
* **会话隔离**：私信共享主会话；群组彼此隔离
* **WebSocket 连接**：通过飞书 SDK 建立长连接，无需公共 URL

***

## 访问控制

### 私信

* **默认**：`dmPolicy: "pairing"`（未知用户会收到配对码）

* **批准配对**：

  ```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  ```

* **Allowlist 模式**：设置 `channels.feishu.allowFrom`，填入允许的 Open ID

### 群聊

**1. 群组策略**（`channels.feishu.groupPolicy`）：

* `"open"` = 允许群组中的所有人（默认）
* `"allowlist"` = 仅允许 `groupAllowFrom`
* `"disabled"` = 禁用群消息

**2. 提及要求**（`channels.feishu.groups.<chat_id>.requireMention`）：

* `true` = 需要 @ 提及（默认）
* `false` = 无需提及也会回复

***

## 群组配置示例

### 允许所有群组，要求 @ 提及（默认）

```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    feishu: {
      groupPolicy: "open",
      // Default requireMention: true
    },
  },
}

允许所有群组，无需 @ 提及

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
feishu: {
groups: {
oc_xxx: { requireMention: false },
},
},
},
}

### 仅允许特定群组

```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

限制哪些发送者可以在群组中发消息（发送者 allowlist）

除了允许群组本身外，该群组中的所有消息还会按发送者 open_id 进行限制：只有列在 groups.<chat_id>.allowFrom 中的用户，其消息才会被处理；其他成员发送的消息会被忽略（这是完整的发送者级限制，而不只是对 /reset 或 /new 等控制命令生效）。

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
feishu: {
groupPolicy: “allowlist”,
groupAllowFrom: [“oc_xxx”],
groups: {
oc_xxx: {
// Feishu user IDs (open_id) look like: ou_xxx
allowFrom: [“ou_user1”, “ou_user2”],
},
},
},
},
}

***

## 获取群组/用户 ID

### 群组 ID（`chat_id`）

群组 ID 看起来像 `oc_xxx`。

**方法 1（推荐）**

1. 启动 Gateway 网关并在群里 @ 提及机器人
2. 运行 `openclaw logs --follow` 并查找 `chat_id`

**方法 2**

使用飞书 API 调试器列出群聊。

### 用户 ID（`open_id`）

用户 ID 看起来像 `ou_xxx`。

**方法 1（推荐）**

1. 启动 Gateway 网关并向机器人发送私信
2. 运行 `openclaw logs --follow` 并查找 `open_id`

**方法 2**

检查配对请求中的用户 Open ID：

```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw pairing list feishu

常用命令

注意：飞书暂不支持原生命令菜单，因此命令必须以文本形式发送。

Gateway 网关 网关管理命令

故障排除

机器人在群聊中没有响应

1. 请确保机器人已加入群组
2. 请确保你 @ 提及了机器人（默认行为）
3. 检查 groupPolicy 未设置为 "disabled"
4. 检查日志：openclaw logs --follow

机器人未接收到消息

1. 请确保应用已发布并获批准
2. 请确保事件订阅包含 im.message.receive_v1
3. 请确保已启用长连接
4. 请确保应用权限完整
5. 请确保 Gateway 网关 网关正在运行：openclaw gateway status
6. 检查日志：openclaw logs --follow

App Secret 泄露

1. 在飞书开放平台中重置 App Secret
2. 在你的配置中更新 App Secret
3. 重启 Gateway 网关 网关

消息发送失败

1. 请确保应用具有 im:message:send_as_bot 权限
2. 请确保应用已发布
3. 查看日志以获取详细错误信息

高级配置

多账户

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
渠道s: {
feishu: {
defaultAccount: “main”,
accounts: {
main: {
appId: “cli_xxx”,
appSecret: “xxx”,
botName: “Primary bot”,
},
backup: {
appId: “cli_yyy”,
appSecret: “yyy”,
botName: “Backup bot”,
enabled: false,
},
},
},
},
}

`defaultAccount` 用于控制当出站 API 未显式指定 `accountId` 时，使用哪个飞书账户。

### 消息限制

* `textChunkLimit`：出站文本分块大小（默认：2000 个字符）
* `mediaMaxMb`：媒体上传/下载限制（默认：30 MB）

### 流式传输

飞书通过交互式卡片支持流式回复。启用后，机器人会在生成文本时更新卡片。

```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    feishu: {
      streaming: true, // 启用流式卡片输出（默认 true）
      blockStreaming: true, // 启用分块流式传输（默认 true）
    },
  },
}

将 streaming: false 设为等待完整回复生成后再发送。

ACP 会话

飞书支持以下 ACP 场景：

• 私信
• 群组话题会话

飞书 ACP 由文本命令驱动。没有原生斜杠命令菜单，因此请直接在会话中使用 /acp ... 消息。

持久化 ACP 绑定

使用顶层类型化 ACP 绑定，将飞书私信或话题会话固定到持久化 ACP 会话。

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
agents: {
list: [
{
id: “codex”,
runtime: {
type: “acp”,
acp: {
agent: “codex”,
backend: “acpx”,
mode: “persistent”,
cwd: “/workspace/openclaw”,
},
},
},
],
},
bindings: [
{
type: “acp”,
agentId: “codex”,
match: {
渠道: “feishu”,
accountId: “default”,
peer: { kind: “direct”, id: “ou_1234567890” },
},
},
{
type: “acp”,
agentId: “codex”,
match: {
渠道: “feishu”,
accountId: “default”,
peer: { kind: “group”, id: “oc_group_chat:topic:om_topic_root” },
},
acp: { label: “codex-feishu-topic” },
},
],
}

#### 从聊天中按线程绑定 ACP 生成

在飞书私信或话题会话中，你可以就地生成并绑定一个 ACP 会话：

```text  theme={"theme":{"light":"min-light","dark":"min-dark"}}
/acp spawn codex --thread here

说明：

• --thread here 适用于私信和飞书话题。
• 绑定后的私信/话题中的后续消息会直接路由到该 ACP 会话。
• v1 不支持针对通用的非话题群聊。

多智能体路由

使用 bindings 将飞书私信或群组路由到不同的智能体。

json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
agents: {
list: [
{ id: "main" },
{
id: "clawd-fan",
workspace: "/home/user/clawd-fan",
agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
},
{
id: "clawd-xi",
workspace: "/home/user/clawd-xi",
agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
},
],
},
bindings: [
{
agentId: "main",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_xxx" },
},
},
{
agentId: "clawd-fan",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_yyy" },
},
},
{
agentId: "clawd-xi",
match: {
channel: "feishu",
peer: { kind: "group", id: "oc_zzz" },
},
},
],
}

路由字段：

• match.channel："feishu"
• match.peer.kind："direct" 或 "group"
• match.peer.id：用户 Open ID（ou_xxx）或群组 ID（oc_xxx）

查找提示请参见 获取群组/用户 ID。

配置参考

完整配置：Gateway 网关 网关配置

关键选项：

dmPolicy 参考

支持的消息类型

接收

• ✅ 文本
• ✅ 富文本（post）
• ✅ 图片
• ✅ 文件
• ✅ 音频
• ✅ 视频
• ✅ 贴纸

发送

• ✅ 文本
• ✅ 图片
• ✅ 文件
• ✅ 音频
• ⚠️ 富文本（部分支持）