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

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

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

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

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

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

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

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

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

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

功能模块	所需权限	权限说明	必选/可选
文档操作	docx:document	文档读写权限（创建/读取/编辑/删除）	必选（需要操作文档时）
知识库操作	wiki:wiki:readonly	读取知识库节点/文档	必选（需要读取知识库时）
知识库操作	wiki:wiki	知识库编辑/成员管理权限	可选（需要修改知识库时）
云空间文件	drive:drive	云空间文件读写/上传/下载/删除	必选（需要操作云文件时）
云空间文件	drive:drive:readonly	云空间文件只读权限	可选（仅需要读取时）
评论操作	drive:drive.comment:write	文档/文件评论的增删改查	可选
权限管理	docs:permission:member:create	添加/修改/删除文档协作者	必选（需要管理权限时）
基础消息能力	im:chat:read	读取群聊信息	必选
基础消息能力	im:chat:update	修改群聊信息	可选
基础消息能力	im:message.group_at_msg:readonly	读取群聊@机器人的消息	必选
基础消息能力	im:message.p2p_msg:readonly	读取私信消息	必选
基础消息能力	im:message.pins:read	读取Pin消息	可选
基础消息能力	im:message.pins:write_only	Pin/Unpin消息	可选
基础消息能力	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	上传/下载消息资源（图片/文件）	必选
用户/通讯录	contact:user.base:readonly	读取用户基本信息（用于@用户、展开用户名称）	可选
用户/通讯录	contact:department.base:readonly	读取部门信息	可选
画板操作	board:board	画板读写/导入Mermaid/PlantUML	可选（需要处理图表时）
电子表格	sheets:spreadsheet	电子表格读写/样式/格式操作	必选（需要操作表格时）
日历操作	calendar:calendar:readonly	读取日历/日程	可选
日历操作	calendar:calendar	创建/编辑/删除日历/日程	可选
任务操作	task:task:read	读取任务/任务列表	可选
任务操作	task:task:write	创建/编辑/完成/删除任务	可选
任务操作	task:tasklist:read	读取任务列表	可选
任务操作	task:tasklist:write	创建/编辑/删除任务列表	可选
搜索能力	需要User Access Token	全局搜索消息/文档/应用	可选

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

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文件则知识库权限正常。

• 常见权限问题排查

错误码	错误信息	原因	解决方法
131003	no permission	应用无对应操作权限	检查飞书开放平台是否申请了对应权限，是否发布生效
131001	node not found	文档/知识库节点不存在	检查文档ID/Token是否正确，是否有权限访问该文档
131002	param err	参数错误	检查App ID/Secret是否配置正确，Token格式是否正确
131004	space not found	知识空间不存在	检查space_id是否正确，应用是否有该空间的访问权限
99991663	App not exist	应用不存在	检查App ID是否正确，应用是否已经发布
10003	Invalid access token	访问令牌无效	检查App Secret是否正确，应用是否被停用
10019	Operation denied	操作被拒绝	你本身没有该资源的操作权限，机器人无法超越你的权限
10020	Request limit exceeded	请求限流	降低操作频率，飞书API默认限流100次/分钟

🛠️ 调试技巧：在命令后添加--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自动转飞书画板
• ✅ 读取/导出飞书表格
• ✅ 搜索云空间文件