XCodeClaw 飞书机器人配置指南
本指南帮助您在飞书开放平台创建并配置机器人应用，完成后将 App ID 和 App Secret 提供给管理员即可开通服务。
您只需完成飞书侧配置，模型配置、服务部署由管理员完成，无需关心。
1. 概述
XCodeClaw 是一个 AI 学术助手，通过飞书机器人与您交互。您需要在飞书开放平台创建一个机器人应用，并完成权限和事件订阅的配置。
整体流程
- 在飞书开放平台创建企业自建应用
- 添加机器人能力
- 导入权限配置
- 获取凭证（App ID 和 App Secret），发送给管理员
- 等待管理员创建服务实例
- 配置事件订阅与回调（需要服务实例已运行）
- 发布应用
流程顺序很重要
事件订阅和回调使用「长连接」模式，即由服务端主动与飞书建立 WebSocket 连接。因此必须先让管理员创建服务实例，待服务启动后再配置长连接，否则连接无法建立。
完成以上步骤后，在飞书中搜索您创建的机器人即可开始使用。
2. 创建飞书应用
第一步：登录飞书开放平台
- 打开浏览器，访问飞书开放平台：https://open.feishu.cn/app
- 使用您的飞书账号登录。
- 点击页面上的「创建企业自建应用」按钮：
填写应用信息，包括应用名称、描述和图标，然后点击「创建」：
建议
应用名称建议使用易于辨识的名称，如「XCodeClaw 助手」或「AI 学术助手」。
3. 添加机器人能力
第二步：启用机器人功能
进入刚创建的应用，在左侧菜单中操作：
- 点击左侧菜单「应用能力」→「机器人」。
- 点击「启用机器人能力」。
- 机器人名称会自动填充应用名称，确认即可。
4. 配置权限
第三步：批量导入权限
- 在左侧菜单中点击「开发配置」→「权限管理」。
- 点击页面右上角的「批量开通」按钮（如下图所示）。
- 将下方的 JSON 内容完整复制并粘贴到输入框中，点击确认。
需要导入的权限 JSON：
json
{
"scopes": {
"tenant": [
"contact:contact.base:readonly",
"docx:document:readonly",
"im:chat:read",
"im:chat:update",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message.pins:read",
"im:message.pins:write_only",
"im:message.reactions:read",
"im:message.reactions:write_only",
"im:message:readonly",
"im:message:recall",
"im:message:send_as_bot",
"im:message:send_multi_users",
"im:message:send_sys_msg",
"im:message:update",
"im:resource",
"application:application:self_manage",
"cardkit:card:write",
"cardkit:card:read"
],
"user": [
"contact:user.employee_id:readonly",
"offline_access","base:app:copy",
"base:field:create",
"base:field:delete",
"base:field:read",
"base:field:update",
"base:record:create",
"base:record:delete",
"base:record:retrieve",
"base:record:update",
"base:table:create",
"base:table:delete",
"base:table:read",
"base:table:update",
"base:view:read",
"base:view:write_only",
"base:app:create",
"base:app:update",
"base:app:read",
"sheets:spreadsheet.meta:read",
"sheets:spreadsheet:read",
"sheets:spreadsheet:create",
"sheets:spreadsheet:write_only",
"docs:document:export",
"docs:document.media:upload",
"board:whiteboard:node:create",
"board:whiteboard:node:read",
"calendar:calendar:read",
"calendar:calendar.event:create",
"calendar:calendar.event:delete",
"calendar:calendar.event:read",
"calendar:calendar.event:reply",
"calendar:calendar.event:update",
"calendar:calendar.free_busy:read",
"contact:contact.base:readonly",
"contact:user.base:readonly",
"contact:user:search",
"docs:document.comment:create",
"docs:document.comment:read",
"docs:document.comment:update",
"docs:document.media:download",
"docs:document:copy",
"docx:document:create",
"docx:document:readonly",
"docx:document:write_only",
"drive:drive.metadata:readonly",
"drive:file:download",
"drive:file:upload",
"im:chat.members:read",
"im:chat:read",
"im:message",
"im:message.group_msg:get_as_user",
"im:message.p2p_msg:get_as_user",
"im:message:readonly",
"search:docs:read",
"search:message",
"space:document:delete",
"space:document:move",
"space:document:retrieve",
"task:comment:read",
"task:comment:write",
"task:task:read",
"task:task:write",
"task:task:writeonly",
"task:tasklist:read",
"task:tasklist:write",
"wiki:node:copy",
"wiki:node:create",
"wiki:node:move",
"wiki:node:read",
"wiki:node:retrieve",
"wiki:space:read",
"wiki:space:retrieve",
"wiki:space:write_only"
]
}
}注意
请确保 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
- 在左侧菜单中点击「基础信息」→「凭证与基础信息」。
- 复制以下两个值：
- App ID：格式为
cli_xxxxxxxxxxxxxxxx - App Secret：一串字母数字组合
- App ID：格式为
- 将这两个值发送给管理员，用于开通您的 XCodeClaw 服务。
安全提示
App Secret 是应用的密钥，请妥善保管，不要在公开场合泄露。仅通过安全渠道发送给管理员。
6. 等待管理员开通服务
第五步：等待服务实例创建
将凭证发送给管理员后，管理员会在后台为您创建服务实例并启动容器。
请等待管理员确认服务已启动，然后再进行下一步的事件订阅与回调配置。
为什么要等待？
事件订阅和回调使用「长连接」（WebSocket）模式，由服务端主动与飞书建立连接。如果服务实例尚未启动，长连接无法建立，事件订阅将无法正常工作。
7. 配置事件订阅与回调
前置条件
请确认管理员已通知您服务实例已启动，再进行本步骤的配置。
本步骤包含三个部分：事件订阅、回调配置和安全设置。
7.1 事件订阅
第六步 A：配置事件订阅
- 在左侧菜单中点击「开发配置」→「事件与回调」。
- 事件请求方式：选择「使用长连接接收事件」（如下图）。
- 点击「添加事件」，搜索并添加以下事件：
| 事件名称 | 事件标识 |
|---|---|
| 接收消息 | im.message.receive_v1 |
| 添加表情回复 | im.message.reaction.created_v1 |
| 删除表情回复 | im.message.reaction.deleted_v1 |
7.2 回调配置
第六步 B：配置回调
- 在同一页面中，找到「回调配置」区域。
- 回调请求方式同样选择「使用长连接」。
- 点击「添加回调」，搜索并添加卡片操作相关回调。
7.3 安全设置
第六步 C：启用用户凭证
在「安全设置」区域，如果看到「user_access_token」开关，请将其开启。
如果没有看到该开关，说明您的应用已默认启用用户凭证，无需额外操作。
8. 发布应用
第七步：创建版本并发布
- 在左侧菜单中点击「版本管理与发布」。
- 点击「创建版本」。
- 填写版本号（如
1.0.0）和更新说明，选择可用范围，点击「保存」：
- 点击「申请发布」，确认发布：
9. 授权飞书资源访问
第八步：完成飞书授权
机器人上线后，建议立即完成飞书资源授权，以解锁文档读写、表格操作等高级功能。
- 在飞书中找到您的机器人，发送：
/feishu auth - 机器人会返回一个授权链接，点击链接并在弹出页面中同意授权。
- 授权成功后，机器人即可代您访问飞书文档、多维表格、知识库等资源。
授权说明
此授权基于飞书 user_access_token 机制，仅在您主动授权后生效。授权范围包括：读取文档内容、操作电子表格、访问知识库等（即前面配置的 user 级权限）。不授权不影响基本的对话功能，但文档相关能力将不可用。
10. 配置检查清单
请对照以下清单确认所有配置已完成：
| 检查项 | 说明 | |
|---|---|---|
| ☐ | 创建应用 | 已在飞书开放平台创建企业自建应用 |
| ☐ | 机器人能力 | 已启用机器人能力 |
| ☐ | 权限导入 | 已通过 JSON 批量导入全部权限 |
| ☐ | 获取凭证 | 已复制 App ID 和 App Secret 并发送给管理员 |
| ☐ | 服务开通 | 管理员已确认服务实例启动 |
| ☐ | 事件订阅 | 已添加 3 个事件，使用长连接模式 |
| ☐ | 回调配置 | 已配置回调，使用长连接模式 |
| ☐ | 安全设置 | 已开启 user_access_token 开关 |
| ☐ | 发布应用 | 已创建版本并发布上线 |
| ☐ | 飞书授权 | 已发送 /feishu auth 并完成授权 |
11. 常见问题
机器人没有响应消息
- 确认管理员已开通服务（服务实例已启动）
- 确认应用已发布（状态为「已上线」）
- 确认事件订阅和回调都已配置为「长连接」模式
- 确认权限已全部导入（检查「权限管理」页面）
权限批量导入失败
- 检查 JSON 格式是否正确（注意逗号和引号）
- 部分权限可能需要企业管理员审批后才能开通
- 如果批量导入不可用，可手动搜索并逐个添加权限
如何在群聊中使用机器人
- 将机器人添加到群聊中
- 在群聊中 @机器人名称 后输入您的问题
- 机器人默认只响应 @它 的消息