ArkClaw x 飞书云文档（完整权限清单）

本文主要介绍如何使用火山引擎ArkClaw针对飞书云文档进行操作。

• 重点内容1 ：飞书开放平台完整权限清单
• 重点内容2：文档权限开通完整步骤
• 重点内容3：飞书云文档权限验证（文档读取/文档写入/知识库权限）
• 重点内容4：5分钟快速实现飞书文档管理权限（新手友好）

ArkClaw/Openclaw 操作飞书云文档权限管控原则

OpenClaw操作飞书全能力基于飞书开放平台 应用的权限授权，所有操作都遵循最小权限原则：

• 机器人的权限范围 = 飞书开放平台应用申请的权限范围 + 企业管理员审批的权限范围 + 文档/资源本身的权限范围

• 机器人仅能操作用户本身有权限的资源，不会超越用户权限操作

• 所有操作都会留下审计日志，可追溯可回滚

重点内容1 ｜ 飞书开放平台完整权限清单

根据需要使用的功能，对照下表申请对应权限，不需要的权限可以不用申请：

🔑 推荐最简权限配置（仅需要读取+写入文档+发消息）：

im:chat:read、im:message.group_at_msg:readonly、im:message.p2p_msg:readonly、im:message:readonly、im:message:send_as_bot、im:resource、docx:document、docs:permission、drive:drive、wiki:wiki:readonly

---

重点内容2 ｜ 飞文档权限开通完整步骤

1. 打开飞书开放平台：https://open.larkoffice.com/，使用SSO登录，进入你的机器人应用
2. 左侧菜单选择开发配置 > 权限管理
3. 点击批量导入/导出权限按钮，选择导入TAB
4. 粘贴下面的最简权限JSON（需要其他功能自行在上表中添加）：

{
  "scopes": {
    "tenant": [
      "im:chat:read",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "docx:document",
      "wiki:wiki:readonly",
      "drive:drive",
      "docs:permission",
      "contact:user.base:readonly"
    ]
  }
}

5. 点击下一步，然后点击申请开通

6. 填写权限申请说明："用于OpenClaw AI助手自动化操作飞书文档、发送消息，提升工作效率"

7. 提交权限申请，等待审批（内部应用权限大部分免批，1分钟内生效）

8. 发布应用使权限生效,权限申请通过后，需要发布版本才能生效：

9. 点击顶部的创建版本按钮， 填写版本号、更新说明："新增文档/消息操作权限，用于AI助手自动化"

10. 选择权限范围：

• 个人使用：仅选择自己的账号
• 团队使用：选择团队成员/部门
• 全公司使用：选择全企业（需额外审批）

11. 确认提交发布，免批应用会立即生效

12. 发布完成后，左侧菜单选择凭证与基础信息，复制以下两个值备用：

• App ID：格式为cli_xxxxxx
• App Secret：随机字符串，注意保密

---

重点内容3｜ 飞书云文档权限验证（文档读取/文档写入/知识库权限）

配置完成后，按以下步骤验证权限是否正常：

• 基础消息权限验证

给机器人发一条消息：@机器人 你好，如果机器人正常回复则消息权限配置成功。

• 文档读取权限验证

给机器人发一个你有权限的飞书文档链接：

@机器人 读一下这个文档 https://bytedance.larkoffice.com/docx/xxxxxx

如果机器人能正常返回文档内容则文档读取权限正常。

• 文档写入权限验证

执行命令创建测试文档：

feishu-cli doc create --title "权限测试文档"

如果返回文档ID，并且你能在飞书中看到这个文档，则文档写入权限正常。

• 知识库权限验证

执行命令导出知识库文档：

feishu-cli wiki export <知识库node_token> --output /tmp/test.md

如果能正常导出Markdown文件则知识库权限正常。

• 常见权限问题排查

🛠️ 调试技巧：在命令后添加--debug参数可以查看详细的请求和返回信息，方便定位问题：

feishu-cli doc export <doc_id> --debug

重点内容4｜5分钟快速实现飞书文档管理权限（新手友好）

• 最简权限配置（覆盖99%常用场景：消息+文档+知识库+权限管理）

直接在飞书开放平台权限管理页面批量导入这个JSON，无需额外配置：

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docs:document.content:read",
      "docs:permission.member:create",
      "document_ai:document:chunking",
      "docx:document.block:convert",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:version: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",
      "wiki:wiki:readonly"
    ]
  }
}

✅ 配置完成后你能实现：

• ✅ 收发飞书消息（私信/群聊@/表情回复/Pin消息）
• ✅ 读取/写入/创建飞书文档、知识库
• ✅ 自动给文档添加协作者权限
• ✅ 支持Mermaid/PlantUML自动转飞书画板
• ✅ 读取/导出飞书表格
• ✅ 搜索云空间文件