企业官网建设流程全解析

OpenClaw 飞书（Feishu）协作者与权限管理技能 feishu-perm：feishu_perm 工具配置与使用指南

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

本文围绕 OpenClaw 项目中飞书插件自带的feishu-perm技能（extensions/feishu/skills/feishu-perm/SKILL.md）展开，系统讲解如何通过feishu_perm工具对飞书云文档（文档、表格、多维表格、知识库、幻灯片、文件夹等）进行协作者查看、添加与移除操作。读完本文，你将掌握feishu_perm的三种 action（list/add/remove）的完整参数含义、工具默认关闭的原因、如何在channels.feishu.tools.perm中开启它，以及如何在日常 Agent 协作中安全地执行“查看协作者 → 变更访问权限”的完整流程。

一、技能定位：为什么权限管理需要单独一个技能

在 OpenClaw 的飞书插件中，Agent 可以操作文档、聊天、知识库、云盘、多维表格等多种能力，分别对应feishu_doc、feishu_chat、feishu_wiki、feishu_drive、feishu_bitable等工具。其中，权限管理被拆分为独立的feishu-perm技能，核心原因是它直接改变用户数据（文档/资源的访问权限），属于敏感操作。

从插件配置 extensions/feishu/openclaw.plugin.json 可以看到，feishu_perm与其他飞书工具一样，注册在插件工具列表中，并声明了配置信号：需要channels.feishu下（或 accounts 覆盖层中）的appId与appSecret才能生效。

技能本身定位明确：当用户明确要求查看或修改飞书文档的分享、权限或协作者时激活。它把所有操作收敛到单一工具feishu_perm及其当前 action schema 中，避免权限变更散落在多个工具里难以审计。

二、工具默认关闭：先看懂channels.feishu.tools.perm

feishu_perm默认是关闭的。原因在 extensions/feishu/src/tools-config.ts 的默认配置注释中写得很清楚：

// perm: disabled by default (sensitive operation) const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = { doc: true, chat: true, wiki: true, drive: true, perm: false, // 权限管理：默认关闭（敏感操作） scopes: true, bitable: true, };

也就是说，doc、chat、wiki、drive、scopes、bitable默认开启，唯独perm默认false。这是刻意的安全设计：权限变更会影响他人对数据的访问能力，因此需要运维者显式放行。

开启方式

在 OpenClaw 配置文件的飞书渠道配置中加入：

channels: feishu: appId: "cli_xxxxxxxx" appSecret: "xxxxxxxxxxxxxxxx" tools: perm: true # 显式启用权限管理工具

配置项定义在 extensions/feishu/src/config-schema.ts 的FeishuToolsConfigSchema中，注释为perm: z.boolean().optional() // Permission management (default: false, sensitive)。该 schema 同时注明了两条依赖关系：

• wiki依赖doc（知识库内容通过文档工具编辑）；
• perm可以独立工作，但通常与drive配合使用。

tools配置既可以在飞书渠道顶层设置，也可以在**每个账号（accounts 覆盖层）**下单独设置——extensions/feishu/src/types.ts 中FeishuToolsConfig的全部字段都是可选的，未设置的字段会回退到顶层配置与默认值。

未开启时会发生什么

如果perm未启用，工具注册函数 extensions/feishu/src/perm.ts 中的registerFeishuPermTools会在注册阶段直接返回null，即该工具根本不会暴露给 Agent：

api.registerTool( (ctx) => { const cfg = ctx.runtimeConfig ?? ctx.config ?? api.config; if (!cfg || !resolveAnyEnabledFeishuToolsConfig(cfg).perm) { return null; // perm 未开启 → 不注册工具 } ... }, { name: "feishu_perm" }, );

此时如果用户请求查看/修改协作者，Agent 应当向用户说明：需要先在配置中启用channels.feishu.tools.perm。这也是技能文档里明确的兜底行为：“if it is unavailable, explain thatchannels.feishu.tools.permmust be enabled”。

在多账号场景下，账号路由逻辑位于 extensions/feishu/src/tool-account.ts 的resolveImplicitToolAccountId：它会优先使用调用参数中的显式accountId，其次使用 Agent 上下文默认账号、顶层defaultAccount，最后遍历所有启用且已配置、且其tools.perm开启的账号；若没有任何账号开启 perm 工具，会抛出No usable Feishu account has Perm tools enabled。路由测试 extensions/feishu/src/tool-account-routing.test.ts 覆盖了feishu_perm的多种账号路由场景。

三、feishu_perm工具的动作与参数详解

feishu_perm暴露三个动作：list、add、remove。参数 schema 定义在 extensions/feishu/src/perm-schema.ts，实现位于 extensions/feishu/src/perm.ts，底层调用飞书开放平台drive.permissionMember系列接口（list/create/delete）。

3.1 通用参数

所有动作都需要两个公共参数：

type支持的类型（TokenType）包括：doc、docx、sheet、bitable、folder、file、wiki、mindnote。其中list在实现层额外兼容minutes、slides等类型（见perm.ts中的ListTokenType），而CreateTokenType还包含slides与minutes。

3.2list：查看当前协作者

在修改任何权限之前，先list查看现状，这是技能工作流的第一步。调用示例：

{ "action": "list", "token": "doccnxxxxxxxxxxxxxxxx", "type": "docx" }

底层实现listMembers调用client.drive.permissionMember.list，返回每个协作者的：

• member_type：协作者类型（见下节）；
• member_id：协作者 ID；
• perm：当前权限级别；
• name：协作者名称。

返回结构：

{ "members": [ { "member_type": "openid", "member_id": "ou_xxx", "perm": "edit", "name": "张三" } ] }

3.3add：添加协作者并授予权限

add在list之外还需要三个参数：

调用示例：

{ "action": "add", "token": "doccnxxxxxxxxxxxxxxxx", "type": "docx", "member_type": "email", "member_id": "colleague@example.com", "perm": "view" }

底层addMember调用client.drive.permissionMember.create，并固定传need_notification: false（不发送通知），返回{ success: true, member }。

MemberType支持：email、openid、userid、unionid、openchat、opendepartmentid（schema 层面）；实现层 perm.ts 的类型定义还包含groupid与wikispaceid，覆盖了群组与知识库空间的协作者类型。

3.4remove：移除协作者

remove需要member_type与member_id来精确定位要移除的协作者：

{ "action": "remove", "token": "doccnxxxxxxxxxxxxxxxx", "type": "docx", "member_type": "openid", "member_id": "ou_xxxxxxxx" }

底层removeMember调用client.drive.permissionMember.delete，成功返回{ success: true }。

3.5 错误处理

三个动作的实现都包裹在try/catch中：当飞书 API 返回非 0 的code时抛出res.msg，最终通过toolExecutionErrorResult返回错误结果，确保 Agent 能感知失败原因而非静默失败。

四、官方工作流：安全地完成一次权限变更

技能文档定义了 5 步工作流，是 Agent 操作权限的权威流程：

1. 解析精确的 file token 与 type：先确认目标资源的 token 及类型（文档/表格/多维表格/知识库等），token 错误将直接导致 API 调用失败；
2. 变更前先list检查当前协作者：任何add/remove之前必须先查看现状，避免重复添加或误删；
3. add时解析协作者精确标识，并选择满足请求的最低权限：能用view就不用edit，能用edit就不用full_access，遵循最小权限原则；
4. remove时在请求含糊或范围过大的情况下，先确认精确的协作者与文件：避免误伤同名协作者或错误文件；
5. 汇报变更结果，但不暴露无关协作者数据：只报告本次变更涉及的信息，list得到的其他协作者数据不外泄。

身份解析的硬性约束

技能文档特别强调：绝不允许仅凭显示名称推断 email、用户 ID、部门或群聊。member_id必须是精确的标识符（邮箱、open_id、user_id、union_id、chat_id 等），这是防止 Agent 张冠李戴、把权限授予错误对象的关键安全红线。

五、最小权限与安全最佳实践

• 默认关闭，按需开启：perm是飞书渠道中唯一默认关闭的工具族。仅在确有协作者管理需求、且运行环境可信时开启。
• 最低权限授予：添加协作者时按需选择view→edit→full_access，不要把full_access作为默认值。
• 先查后改：严格遵循list→add/remove的顺序，任何变更都基于真实现状而非猜测。
• 多账号路由：多账号部署时，feishu_perm会按“显式 accountId → Agent 上下文账号 → 顶层 defaultAccount → 启用且开启 perm 的账号”顺序解析，运维者应确保只有目标账号开启了perm。
• 结果最小化汇报：向用户汇报时只描述“哪个协作者被添加/移除、权限级别变为多少”，不附带无关协作者列表。

六、与其它飞书技能的分工

feishu-perm技能位于 extensions/feishu/skills/ 目录，与以下技能共同构成飞书文档协作能力矩阵：

从 config-schema.ts 的依赖注释可知：权限管理“可以独立工作但通常与 drive 配合使用”——例如先通过feishu_drive定位/确认文件 token，再通过feishu_perm调整其协作者。技能文件通过 openclaw.plugin.json 的"skills": ["./skills"]声明加载，即该目录下所有技能随插件一并提供给 Agent。

七、快速上手 Checklist

1. 确认飞书应用已配置appId/appSecret；
2. 在channels.feishu.tools中显式设置perm: true并重启/重载配置；
3. 向 Agent 提出明确请求，如“把doccnxxx的编辑权限授给 colleague@example.com”；
4. Agent 依工作流先list查看现状，再执行add或remove，最后汇报结果；
5. 若工具不可用，检查配置中channels.feishu.tools.perm是否已开启、账号是否启用且已配置。

通过以上配置与流程，你可以放心地让 OpenClaw 的飞书 Agent 承担协作者管理这类敏感操作，同时借助默认关闭、最小权限、先查后改等机制把误操作风险降到最低。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw