288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
---
|
||
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. 点击页面上的「**创建企业自建应用**」按钮：
|
||
|
||
|
||
|
||
填写应用信息，包括应用名称、描述和图标，然后点击「**创建**」：
|
||
|
||
|
||
|
||
:::tip 建议
|
||
应用名称建议使用易于辨识的名称，如「XCodeClaw 助手」或「AI 学术助手」。
|
||
:::
|
||
|
||
## 3. 添加机器人能力
|
||
|
||
### 第二步：启用机器人功能
|
||
|
||
进入刚创建的应用，在左侧菜单中操作：
|
||
|
||
1. 点击左侧菜单「**应用能力**」→「**机器人**」。
|
||
2. 点击「**启用机器人能力**」。
|
||
3. 机器人名称会自动填充应用名称，确认即可。
|
||
|
||
|
||
|
||
## 4. 配置权限
|
||
|
||
### 第三步：批量导入权限
|
||
|
||
1. 在左侧菜单中点击「**开发配置**」→「**权限管理**」。
|
||
2. 点击页面右上角的「**批量开通**」按钮（如下图所示）。
|
||
3. 将下方的 JSON 内容完整复制并粘贴到输入框中，点击确认。
|
||
|
||
|
||
|
||
需要导入的权限 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 内容完整复制，不要遗漏任何权限项。权限不全会导致机器人功能受限。
|
||
:::
|
||
|
||
导入成功后，权限列表应显示如下：
|
||
|
||
|
||
|
||
下表列出了主要权限的用途说明：
|
||
|
||
| 权限标识 | 用途 |
|
||
| :--------------------------------- | :----------------------------- |
|
||
| `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. **事件请求方式**：选择「**使用长连接接收事件**」（如下图）。
|
||
|
||
|
||
|
||
3. 点击「**添加事件**」，搜索并添加以下事件：
|
||
|
||
| 事件名称 | 事件标识 |
|
||
| :----------- | :------------------------------- |
|
||
| 接收消息 | `im.message.receive_v1` |
|
||
| 添加表情回复 | `im.message.reaction.created_v1` |
|
||
| 删除表情回复 | `im.message.reaction.deleted_v1` |
|
||
|
||
|
||
|
||
|
||
|
||
### 7.2 回调配置
|
||
|
||
#### 第六步 B：配置回调
|
||
|
||
1. 在同一页面中，找到「**回调配置**」区域。
|
||
2. 回调请求方式同样选择「**使用长连接**」。
|
||
3. 点击「**添加回调**」，搜索并添加卡片操作相关回调。
|
||
|
||
|
||
|
||
|
||
|
||
### 7.3 安全设置
|
||
|
||
#### 第六步 C：启用用户凭证
|
||
|
||
在「**安全设置**」区域，如果看到「**user_access_token**」开关，请将其**开启**。
|
||
|
||
如果**没有**看到该开关，说明您的应用已默认启用用户凭证，**无需额外操作**。
|
||
|
||
|
||
|
||
## 8. 发布应用
|
||
|
||
### 第七步：创建版本并发布
|
||
|
||
1. 在左侧菜单中点击「**版本管理与发布**」。
|
||
2. 点击「**创建版本**」。
|
||
|
||
|
||
|
||
3. 填写版本号（如 `1.0.0`）和更新说明，选择可用范围，点击「**保存**」：
|
||
|
||
|
||
|
||
4. 点击「**申请发布**」，确认发布：
|
||
|
||
|
||
|
||
:::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 格式是否正确（注意逗号和引号）
|
||
- 部分权限可能需要企业管理员审批后才能开通
|
||
- 如果批量导入不可用，可手动搜索并逐个添加权限
|
||
|
||
### 如何在群聊中使用机器人
|
||
|
||
- 将机器人添加到群聊中
|
||
- 在群聊中 @机器人名称 后输入您的问题
|
||
- 机器人默认只响应 @它 的消息
|