配置自建应用

管理员先完成飞书应用配置，再由成员分别授权。已经配置好的团队，可以直接跳到连接自己的飞书账号。

准备好三项信息：当前环境的完整 OAuth 回调地址、需要使用应用的飞书成员范围，以及一篇成员能打开的新版飞书文档和它所在的知识库或云盘目录。不确定回调地址时，先向 EasyXAI 部署管理员确认，再配置飞书。

本页截图来自真实页面；应用名称、Client ID 等填写内容为示例。截图中已省略企业成员和凭证详情。

1. 在飞书创建企业自建应用

1. 打开飞书开发者后台，使用目标企业的飞书账号登录。
2. 切换到企业自建应用页签，点击创建企业自建应用。
3. 填写应用名称、描述和图标，确认后点击创建。本指南从普通企业自建应用入口开始。

图 1：创建表单。示例未提交；实际创建时请使用你们团队的名称和用途说明。

创建成功后，点击应用进入详情，在凭证与基础信息 → 应用凭证中找到 App ID 和 App Secret。

App Secret 通常以星号显示，可通过旁边的复制操作取得。只将它填入 EasyXAI 的 Client Secret 字段；不要放到回调地址、应用描述或文档中。

这里创建的是飞书侧的授权应用。EasyXAI 侧使用应用中心已有的「飞书」入口，再在其「自带授权应用」中登记凭证。飞书官方的网页应用授权示例也说明了凭证与重定向地址的配置位置。

2. 配置重定向 URL

在飞书应用的安全设置 → 重定向 URL中，添加当前 EasyXAI 环境实际使用的 OAuth 回调地址。

1. 在应用左侧菜单点击安全设置，切换到重定向 URL。
2. 将管理员提供的完整地址粘贴到「请填写 HTTP/HTTPS URL」输入框。
3. 点击添加，确认地址出现在下方 URL 列表中。

图 2：测试环境的已配置示例。图中的 dev.easyxai.cn 仅对应这个测试环境，请使用你自己的完整回调地址；API 调试台地址不是 EasyXAI 回调地址。

地址格式如下，需将示例域名替换为部署管理员提供的实际回调域名：

https://<当前环境的回调域名>/v1/asset/integration/oauth/callback

请向 EasyXAI 部署管理员取得完整地址。回调域名由服务部署配置决定，可能与浏览器地址栏中的前端域名不同。协议、域名和路径必须完全一致。

测试和生产环境应分别核对配置；本项目生产接入使用单独的飞书应用，并登记生产环境回调地址。应用详情页地址、资源库地址以及登录首页都不能替代这条回调地址。

这里配置的是 OAuth 登录授权的重定向 URL。飞书的「事件与回调」是另一类配置，不能将本节地址填到事件订阅中。官方说明见配置重定向 URL。

3. 开通用户身份权限

在飞书应用的权限管理中申请所需权限。此接入以授权成员的用户身份访问内容，请确认开通的是相应的用户身份权限。

1. 点击权限管理 → 开通权限。
2. 在弹出的面板中切换到 用户身份权限 user_access_token。
3. 按下表逐项搜索权限标识，勾选尚未开通的权限，再点击确认开通权限。
4. 回到权限列表，确认权限类型为用户身份，并检查其状态。已经开通的项可能无法再次勾选。

图 3：先选择用户身份权限，再搜索权限标识。截图中的知识库权限已配置，按钮状态与新应用可能不同。

如果用途是浏览和预览资源库资料，可按下表配置：

图 4：重点检查 offline_access，它在飞书中的名称为「持续访问已授权的数据」。

如果使用批量处理中的权限导入功能，可以按以下用户身份权限清单准备 JSON。导入前确认当前页面提示，导入后仍要检查权限类型和状态；只做本指南的资源库读取时不需要套用聊天机器人的大范围权限清单。

{
  "scopes": {
    "user": [
      "offline_access",
      "wiki:wiki:readonly",
      "drive:drive:readonly",
      "docx:document:readonly"
    ]
  }
}

飞书官方的知识库导出说明列出了上述文档、知识库和云空间读取权限；EasyXAI 使用成员授权访问，不需要照搬该说明中的机器人接入流程。

offline_access 必须在飞书后台开通并随应用版本发布。EasyXAI 需要飞书返回可刷新的授权；遗漏这一项可能出现「第三方未返回长期授权」。飞书官方 MCP 授权说明也将其列入授权范围示例。

如果还要使用创建或编辑文档等应用能力，应按实际能力要求增加权限，例如 docx:document。上表面向资源库读取，不能保证覆盖所有 MCP 工具的操作。

开通应用权限后，成员还需要在飞书中拥有目标文档和知识库的访问权限；应用权限不会扩大成员原有的文档访问范围。

4. 发布应用并确认可用范围

1. 打开版本管理与发布，点击创建版本。
2. 按页面要求填写版本号与更新说明，例如首次接入所需的用户身份权限和用途。
3. 检查当前版本包含的权限变更，配置应用可用范围，使需要授权的成员或部门在范围内。
4. 保存版本并按页面提示提交发布申请；需要审核时，由企业管理员审批。
5. 返回版本列表，确认目标版本显示已发布，再让成员发起授权。

图 5：完成发布后的状态示例。只保存版本草稿不等于已经发布，版本号不需要与截图一致。

只有保存配置而未发布，可能导致新权限没有生效。以后新增权限时，也需要重新发布，并让受影响的成员重新授权。

管理员如何处理审批、何时可以免审，以企业的审核设置为准，可参考自建应用审核与发布说明。

5. 在 EasyXAI 登记授权应用

本节由 EasyXAI 工作空间管理员操作。飞书应用管理权限与 EasyXAI 工作空间管理权限分别授予；如果看不到「自带授权应用」页签，请先确认当前工作空间和你的角色。

1. 切换到目标工作空间，点击左侧资源库，在侧栏下方的扩展 → 应用中心中打开飞书。
2. 若显示未安装，由工作空间管理员点击安装到本团队。
3. 打开自带授权应用，点击添加应用。
4. 填写以下字段并保存。

图 6：EasyXAI 的授权应用表单。cli_example 是占位示例，Client Secret 在截图中留空；实际首次保存时需填写真实 App ID 和 App Secret。完整权限清单见下方代码块。

仅用于本指南的资源库读取时，权限范围可填写：

offline_access, wiki:wiki:readonly, drive:drive:readonly, docx:document:readonly

权限范围留空会继承应用默认值；填写后会整体替换默认值。 因此要填写完整清单，保留 offline_access；若还需要其他应用能力，也应将其所需权限加入清单，并在飞书侧开通和发布。只在 EasyXAI 输入权限名称不会自动开通飞书权限。

保存后确认授权应用处于启用中。App Secret 仅填入密钥字段；编辑已有配置时，Client Secret 留空表示保留原密钥。

6. 连接自己的飞书账号

1. 在当前工作空间打开应用中心 → 飞书 → 连接账号。
2. 点击连接账号。若有多个授权客户端，选择属于自己企业的那一个。
3. 选择 一键授权。若页面直接显示前往授权，点击该按钮即可；随后使用该企业内、且在应用可用范围中的飞书账号完成授权。
4. 授权成功后会自动返回 EasyXAI，确认页面出现已连接账号。
5. 返回应用中心，切换到我的连接，检查账号名称和状态；需要时点击该账号的验证，应提示「连接正常」。

图 7：本指南选择「一键授权」。授权方式由当前环境的应用配置决定，部分环境也会展示访问令牌入口。

管理员登记 App ID 和 App Secret 后，成员仍需完成这一步。 登记授权应用不会自动生成成员的账号连接。

授权前核对飞书页面显示的企业、应用名称和请求权限。offline_access 允许后续刷新授权，但不代表连接永久有效；连接失效后的处理见重新连接说明。

如果连接显示「需重新授权」或「已失效」，从已有连接的重新连接入口完成授权。遇到异常可查阅常见问题。

7. 验证接入结果

确认账号连接正常后，按资源库同步创建飞书数据源，先选一篇有访问权限的新版飞书文档（docx）完成同步，再分别测试预览正文和打开原文。首次验证先使用新版文档，旧版文档、表格和附件的预览支持不同。

如果准备使用应用能力，再到飞书详情的应用能力中确认该能力已启用，并按页面提示选择账号。账号授权成功与某项能力已可用是两个独立检查项。

接下来可阅读在 EasyXAI 中使用，按用途选择资源库同步或智能体应用能力。需要更多飞书后台说明时，查看官方参考资料。