---
title: XCodeClaw 飞书机器人配置指南
---

# XCodeClaw 飞书机器人配置指南

本指南帮助您在飞书开放平台创建并配置机器人应用，完成后将 App ID 和 App Secret 提供给管理员即可开通服务。

> **您只需完成飞书侧配置**，模型配置、服务部署由管理员完成，无需关心。

## 1. 概述

XCodeClaw 是一个 AI 学术助手，通过飞书机器人与您交互。您需要在飞书开放平台创建一个机器人应用，并完成权限和事件订阅的配置。

:::tip 整体流程

1. 在飞书开放平台创建企业自建应用
2. 添加机器人能力
3. 导入权限配置
4. 获取凭证（App ID 和 App Secret），发送给管理员
5. 等待管理员创建服务实例
6. 配置事件订阅与回调（需要服务实例已运行）
7. 发布应用
   :::

:::warning 流程顺序很重要
事件订阅和回调使用「长连接」模式，即由服务端主动与飞书建立 WebSocket 连接。因此必须先让管理员创建服务实例，待服务启动后再配置长连接，否则连接无法建立。
:::

完成以上步骤后，在飞书中搜索您创建的机器人即可开始使用。

## 2. 创建飞书应用

### 第一步：登录飞书开放平台

1. 打开浏览器，访问飞书开放平台：[https://open.feishu.cn/app](https://open.feishu.cn/app)
2. 使用您的飞书账号登录。
3. 点击页面上的「**创建企业自建应用**」按钮：

![创建企业自建应用](../assets/feishu/01-create-app.png)

填写应用信息，包括应用名称、描述和图标，然后点击「**创建**」：

![填写应用信息](../assets/feishu/02-app-info.png)

:::tip 建议
应用名称建议使用易于辨识的名称，如「XCodeClaw 助手」或「AI 学术助手」。
:::

## 3. 添加机器人能力

### 第二步：启用机器人功能

进入刚创建的应用，在左侧菜单中操作：

1. 点击左侧菜单「**应用能力**」→「**机器人**」。
2. 点击「**启用机器人能力**」。
3. 机器人名称会自动填充应用名称，确认即可。

![添加机器人](../assets/feishu/03-add-bot.png)

## 4. 配置权限

### 第三步：批量导入权限

1. 在左侧菜单中点击「**开发配置**」→「**权限管理**」。
2. 点击页面右上角的「**批量开通**」按钮（如下图所示）。
3. 将下方的 JSON 内容完整复制并粘贴到输入框中，点击确认。

![批量导入权限](../assets/feishu/04-import-perms.png)

需要导入的权限 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:contact.base:readonly",
      "contact:user.base:readonly",
      "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": [
      "offline_access",
      "aily:file:read",
      "aily:file:write",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}
```

:::warning 注意
请确保 JSON 内容完整复制，不要遗漏任何权限项。权限不全会导致机器人功能受限。
:::

导入成功后，权限列表应显示如下：

![权限导入完成](../assets/feishu/05-perms-done.png)

下表列出了主要权限的用途说明：

| 权限标识                           | 用途                           |
| :--------------------------------- | :----------------------------- |
| `im:message:send_as_bot`           | 以机器人身份发送消息           |
| `im:message.p2p_msg:readonly`      | 读取私聊消息                   |
| `im:message.group_at_msg:readonly` | 读取群聊中 @机器人 的消息      |
| `im:chat`                          | 管理群聊（创建/更新群信息）    |
| `im:resource`                      | 读取和发送文件、图片等资源     |
| `docs:document.content:read`       | 读取飞书文档内容               |
| `sheets:spreadsheet`               | 读写飞书电子表格               |
| `wiki:wiki:readonly`               | 读取知识库内容                 |
| `cardkit:card:write`               | 发送和更新卡片消息（流式输出） |

## 5. 获取凭证并交给管理员

### 第四步：获取 App ID 和 App Secret

1. 在左侧菜单中点击「**基础信息**」→「**凭证与基础信息**」。
2. 复制以下两个值：
   - **App ID**：格式为 `cli_xxxxxxxxxxxxxxxx`
   - **App Secret**：一串字母数字组合
3. 将这两个值发送给管理员，用于开通您的 XCodeClaw 服务。

:::warning 安全提示
App Secret 是应用的密钥，请妥善保管，不要在公开场合泄露。仅通过安全渠道发送给管理员。
:::

## 6. 等待管理员开通服务

### 第五步：等待服务实例创建

将凭证发送给管理员后，管理员会在后台为您创建服务实例并启动容器。

**请等待管理员确认服务已启动**，然后再进行下一步的事件订阅与回调配置。

:::tip 为什么要等待？
事件订阅和回调使用「长连接」（WebSocket）模式，由服务端主动与飞书建立连接。如果服务实例尚未启动，长连接无法建立，事件订阅将无法正常工作。
:::

## 7. 配置事件订阅与回调

:::warning 前置条件
请确认管理员已通知您服务实例已启动，再进行本步骤的配置。
:::

本步骤包含三个部分：事件订阅、回调配置和安全设置。

### 7.1 事件订阅

#### 第六步 A：配置事件订阅

1. 在左侧菜单中点击「**开发配置**」→「**事件与回调**」。
2. **事件请求方式**：选择「**使用长连接接收事件**」（如下图）。

![选择长连接](../assets/feishu/06-event-longconn.png)

3. 点击「**添加事件**」，搜索并添加以下事件：

| 事件名称     | 事件标识                         |
| :----------- | :------------------------------- |
| 接收消息     | `im.message.receive_v1`          |
| 添加表情回复 | `im.message.reaction.created_v1` |
| 删除表情回复 | `im.message.reaction.deleted_v1` |

![添加事件](../assets/feishu/07-event-subscribe.png)

![事件详情](../assets/feishu/08-event-detail.png)

### 7.2 回调配置

#### 第六步 B：配置回调

1. 在同一页面中，找到「**回调配置**」区域。
2. 回调请求方式同样选择「**使用长连接**」。
3. 点击「**添加回调**」，搜索并添加卡片操作相关回调。

![回调长连接](../assets/feishu/09-callback-longconn.png)

![添加回调](../assets/feishu/10-callback-add.png)

### 7.3 安全设置

#### 第六步 C：启用用户凭证

在「**安全设置**」区域，如果看到「**user_access_token**」开关，请将其**开启**。

如果**没有**看到该开关，说明您的应用已默认启用用户凭证，**无需额外操作**。

![安全设置](../assets/feishu/11-security-token.png)

## 8. 发布应用

### 第七步：创建版本并发布

1. 在左侧菜单中点击「**版本管理与发布**」。
2. 点击「**创建版本**」。

![创建版本](../assets/feishu/12-create-version.png)

3. 填写版本号（如 `1.0.0`）和更新说明，选择可用范围，点击「**保存**」：

![版本信息](../assets/feishu/13-version-info.png)

4. 点击「**申请发布**」，确认发布：

![发布](../assets/feishu/14-publish.png)

:::tip 配置完成 🎉
应用发布后，在飞书中搜索您创建的机器人名称，发送任意消息即可开始使用。

👉 不知道从哪开始？查看 [新用户上手指引](/guide/trial-guide)，5 分钟体验完整学术工作流。
:::

## 9. 授权飞书资源访问

### 第八步：完成飞书授权

机器人上线后，建议立即完成飞书资源授权，以解锁文档读写、表格操作等高级功能。

1. 在飞书中找到您的机器人，发送：`/feishu auth`
2. 机器人会返回一个**授权链接**，点击链接并在弹出页面中同意授权。
3. 授权成功后，机器人即可代您访问飞书文档、多维表格、知识库等资源。

:::tip 授权说明
此授权基于飞书 `user_access_token` 机制，仅在您主动授权后生效。授权范围包括：读取文档内容、操作电子表格、访问知识库等（即前面配置的 user 级权限）。不授权不影响基本的对话功能，但文档相关能力将不可用。
:::

## 10. 配置检查清单

请对照以下清单确认所有配置已完成：

|     | 检查项     | 说明                                       |
| :-: | :--------- | :----------------------------------------- |
|  ☐  | 创建应用   | 已在飞书开放平台创建企业自建应用           |
|  ☐  | 机器人能力 | 已启用机器人能力                           |
|  ☐  | 权限导入   | 已通过 JSON 批量导入全部权限               |
|  ☐  | 获取凭证   | 已复制 App ID 和 App Secret 并发送给管理员 |
|  ☐  | 服务开通   | 管理员已确认服务实例启动                   |
|  ☐  | 事件订阅   | 已添加 3 个事件，使用长连接模式            |
|  ☐  | 回调配置   | 已配置回调，使用长连接模式                 |
|  ☐  | 安全设置   | 已开启 user_access_token 开关              |
|  ☐  | 发布应用   | 已创建版本并发布上线                       |
|  ☐  | 飞书授权   | 已发送 `/feishu auth` 并完成授权           |

## 11. 常见问题

### 机器人没有响应消息

- 确认管理员已开通服务（服务实例已启动）
- 确认应用已发布（状态为「已上线」）
- 确认事件订阅和回调都已配置为「长连接」模式
- 确认权限已全部导入（检查「权限管理」页面）

### 权限批量导入失败

- 检查 JSON 格式是否正确（注意逗号和引号）
- 部分权限可能需要企业管理员审批后才能开通
- 如果批量导入不可用，可手动搜索并逐个添加权限

### 如何在群聊中使用机器人

- 将机器人添加到群聊中
- 在群聊中 @机器人名称 后输入您的问题
- 机器人默认只响应 @它 的消息