# 飞书渠道接入

接入飞书（Feishu/Lark）企业自建应用，完成机器人配置。

---

## 常见踩坑

### 事件订阅保存失败

**现象**：在飞书开放平台配置「长连接」事件订阅时保存失败。

**原因**：「长连接」模式要求 OpenClaw 网关已启动且已添加 Feishu 渠道。

**解决方案**：确保先完成 Step 5（插件安装 + 网关重启），再回来配置事件订阅。

---

## 飞书权限列表

在 Step 4 权限管理「批量导入」时使用以下 JSON：

```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"
    ]
  }
}
```

---

## Step 4：创建飞书应用

> 若用户明确指定使用已有应用，跳过创建，直接让用户提供凭据进入 Step 5。

请用户按以下步骤在飞书开放平台手动完成应用创建：

1. 打开 [飞书开放平台](https://open.feishu.cn/app?lang=zh-CN)，登录后点击「创建企业自建应用」
2. 填写应用名称 `OpenClaw`、描述 `OpenClaw`，随机选择图标，完成创建
3. 在「凭证与基础信息」页面找到并复制 **App ID**（格式 `cli_xxx`）和 **App Secret**
4. 在「应用能力 > 添加应用能力」页面添加机器人能力
5. 在「开发配置 > 权限管理」页面点击「批量导入」，粘贴上方「飞书权限列表」中的 JSON 并确认

完成后，请将 **App ID** 和 **App Secret** 粘贴给我。

**等待用户提供 App ID 和 App Secret，收到后继续执行 Step 5。**

---

## Step 5：安装插件，写入飞书凭据，重启网关

首先执行插件安装（如插件已存在则执行 update）：

```bash
openclaw plugins install @openclaw/feishu
# 若插件已存在：
# openclaw plugins update @openclaw/feishu
```

安装完成后，使用 Read + Edit/Write 工具修改 `~/.openclaw/openclaw.json`，填写 `channels.feishu`：

```json
"channels": {
  "feishu": {
    "appId": "<APP_ID>",
    "appSecret": "<APP_SECRET>",
    "enabled": true,
    "requireMention": true,
    "allowFrom": [],
    "chunkMode": "length",
    "connectionMode": "websocket",
    "dmPolicy": "pairing",
    "domain": "feishu",
    "groupPolicy": "open"
  }
}
```

写入完成后重启网关：

```bash
openclaw gateway restart
```

---

## Step 6：配置飞书事件订阅

> 确保 Step 5 已完成（网关已启动），否则长连接保存会失败。详见上方"事件订阅保存失败"踩坑。

请用户在飞书开放平台「事件与回调」页面手动完成以下配置：

1. 在「开发配置 > 事件与回调」页面点击「事件配置」，点击「订阅方式」选择「使用长连接接收事件」，然后点击「添加事件」 输入`im.message.receive_v1`保存
2. 在「开发配置 > 事件与回调」页面点击「回调配置」，点击「订阅方式」选择「使用长连接接收事件」
3. 在「应用发布 > 版本管理与发布」页面进行发布版本

完成后请告知我，我将继续执行后续步骤。

**等待用户确认完成，收到确认后再继续执行 Step 7。**

---

## Step 7：提示用户将机器人加入群组

将下列步骤提示给用户：

1. 打开飞书APP 进入目标群聊 → 右上角「设置」→「群机器人」→「添加机器人」→ 搜索 `OpenClaw` 并添加
2. @机器人发送消息
