sususu/xcodecli-shells

Private

Public Access

Fork 0

Files

zwang 134e64d1d5 feat: 增加飞书权限

2026-03-13 21:57:48 +08:00

9.8 KiB

Raw Blame History

title

title
XCodeClaw 飞书机器人配置指南

XCodeClaw 飞书机器人配置指南

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

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

1. 概述

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

:::tip 整体流程

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

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

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

2. 创建飞书应用

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

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

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

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

3. 添加机器人能力

第二步：启用机器人功能

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

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

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: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

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

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

6. 等待管理员开通服务

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

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

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

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

7. 配置事件订阅与回调

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

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

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）和更新说明，选择可用范围，点击「保存」：

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

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

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

9. 授权飞书资源访问

第八步：完成飞书授权

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

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

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

10. 配置检查清单

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

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

11. 常见问题

机器人没有响应消息

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

权限批量导入失败

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

如何在群聊中使用机器人

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

9.8 KiB Raw Blame History Unescape Escape