飞书文档权限自动添加

自动为飞书文档添加用户权限。每次创建飞书文档（多维表格/文档/电子表格/文件夹/云空间文件/知识库节点等）后自动添加用户权限，或用户反馈文档无权限时补充添加权限。适用于 OpenClaw Agent。

Security Scan

The skill's instructions, required inputs, and actions are consistent with its stated purpose (automatically adding permissions to Feishu/Lark documents), but it will read and write your OpenClaw config (including app secrets) and perform network requests so you should verify provenance and trust before enabling it.

Purpose & Capability

The skill claims to add permissions for Feishu documents and its instructions explicitly read an OpenClaw config for appId/appSecret, obtain a tenant_access_token from the official open.feishu.cn API, and call the drive permissions API to add members. There are no unrelated credentials, binaries, or installs requested that would contradict the stated purpose.

Instruction Scope

The SKILL.md instructs the agent to read ~/.openclaw/openclaw.json (to obtain appId/appSecret/ownerOpenId), run curl via exec to call Feishu APIs, parse document URLs, and edit the same config to save ownerOpenId. These actions are required for the described function, but they mean the skill will access and may persist secrets (appSecret) and perform network calls — the agent tools 'read', 'exec', and 'edit' must be allowed for it to operate.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so nothing is downloaded or written during installation. That reduces supply-chain risk compared to skills that install packages or fetch archives.

Credentials

The skill declares no environment variables but expects appId/appSecret stored in ~/.openclaw/openclaw.json and will fetch a tenant_access_token from Feishu. Requesting the app secret is proportionate to calling the Feishu API, but users should be aware that the skill reads sensitive credentials from their agent config and will use them to authenticate API calls.

Persistence & Privilege

The skill is not always-enabled and does not request system-wide or cross-skill configuration changes. It does write ownerOpenId into the OpenClaw config (its own config area), which is normal for storing user config. It does not require elevated platform privileges.

Assessment

Before installing: verify the skill's source (README references a GitHub repo and ClawHub but registry homepage is missing). Understand that the skill will read ~/.openclaw/openclaw.json to obtain your Feishu appId and appSecret and will perform HTTP requests to open.feishu.cn to obtain tokens and modify document permissions. Only install if you trust the skill and the repository owner. Consider creating a Feishu application with minimal permissions, rotate the appSecret after testing, and review agent tool permissions (allowing read/exec/edit grants the skill access to config and lets it run curl). If you need higher assurance, ask the publisher for the code repository URL and review the repository or run the skill in a limited test account first.

🎯 一句话总结：飞书应用创建的文档，用户默认无权限。这个 skill 帮你自动添加权限。

---

前置条件

条件	说明
飞书开发者账号	需要有飞书开放平台的开发者权限
企业自建应用	已创建或有权创建飞书应用
应用权限	应用需开通 docs:permission.member:create 权限

---

变量速查表

变量名	来源	用途
$APP_ID	配置文件 channels.feishu.appId	应用标识
$APP_SECRET	配置文件 channels.feishu.appSecret	应用密钥
$OWNER_OPEN_ID	配置文件或会话上下文	权限接收者
$TENANT_TOKEN	API 获取	请求鉴权
$FILE_TOKEN	创建返回或 URL 解析	文档标识
$DOC_TYPE	URL 路径识别	文档类型

---

第一步：检查配置 ⚠️

1.1 读取配置文件

配置文件位置：~/.openclaw/openclaw.json

1.2 检查必需字段

在 channels.feishu 下查找：

字段名	说明	示例值	必需性
appId	飞书应用 ID	cli_xxxxxxxx	✅ 必需
appSecret	飞书应用密钥	xxxxxxxx	✅ 必需
ownerOpenId	用户的 open_id	ou_xxx	⚪ 可选*

*ownerOpenId 在配置文件中可选，但执行时必须有值。若配置文件缺失，从会话上下文提取（格式 user:ou_xxx → ou_xxx）。

配置示例：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxx",
      "appSecret": "xxxxxxxx",
      "ownerOpenId": "ou_xxx"
    }
  }
}

1.3 检查应用权限

使用 feishu_app_scopes() 查询当前飞书应用已开通的权限列表。

检查返回结果中是否包含 docs:permission.member:create：

• ✅ 有 → 权限正常，继续下一步
• ❌ 无 → 跳转到 配置引导流程 C

💡 如检查出有权限，后续可跳过此步骤。

1.4 判断逻辑

根据检查结果，按以下流程处理：

┌─────────────────────────────────────────────────────────┐
│  检查 appId + appSecret                                 │
│     ├─ ❌ 缺失 → [配置引导流程 A]                        │
│     └─ ✅ 完整 ↓                                        │
│  检查应用权限 docs:permission.member:create              │
│     ├─ ❌ 缺失 → [配置引导流程 C]                        │
│     └─ ✅ 完整 ↓                                        │
│  检查 ownerOpenId                                       │
│     ├─ ✅ 配置文件有 → 进入第二步                        │
│     ├─ ✅ 会话上下文有 → 提取使用，进入第二步             │
│     └─ ❌ 都没有 → [配置引导流程 B]                      │
└─────────────────────────────────────────────────────────┘

---

工具调用映射 🛠️

明确每个步骤应使用的工具，确保 Agent 能正确执行

步骤	操作	工具	说明
1.1	读取配置文件	read	读取 ~/.openclaw/openclaw.json
1.3	检查应用权限	feishu_app_scopes	查询已开通权限列表
2.2	获取 tenant_access_token	exec	执行 curl 命令请求 API
2.3	解析文档 token	内置逻辑	从 URL 或返回值中提取
2.4	添加用户权限	exec	执行 curl 命令请求 API
配置写入	保存 ownerOpenId	edit	更新 openclaw.json

工具调用示例：

# 读取配置文件
read("~/.openclaw/openclaw.json")

# 检查应用权限
feishu_app_scopes()

# 获取 tenant_access_token
exec('curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" ...')

# 添加权限
exec('curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/permissions/..." ...')

# 保存配置
edit("~/.openclaw/openclaw.json", oldText, newText)

---

第二步：执行权限添加 📋

前置条件：第一步检查全部通过

2.1 读取配置

工具：read

APP_ID="读取到的appId"
APP_SECRET="读取到的appSecret"
OWNER_OPEN_ID="读取到的ownerOpenId"

2.2 获取 tenant_access_token

工具：exec

进度提示：[1/4] 获取访问令牌...

请求：

curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d "{
    \"app_id\": \"$APP_ID\",
    \"app_secret\": \"$APP_SECRET\"
  }"

成功返回：

{
  "code": 0,
  "msg": "ok",
  "tenant_access_token": "xxxx",
  "expire": 5535
}

失败返回：

{
  "code": 10003,
  "msg": "app id or app secret is invalid"
}

处理：

• ✅ 成功：提取 tenant_access_token，继续下一步
• ❌ 失败：提示用户检查 App ID 和 App Secret 是否正确

token 缓存策略：

token 类型	有效期	缓存建议
tenant_access_token	约 2 小时	缓存至会话变量，过期前 5 分钟刷新

缓存实现：

• 使用会话级变量存储：CACHED_TENANT_TOKEN, TOKEN_EXPIRE_TIME
• 每次请求前检查：若 now < TOKEN_EXPIRE_TIME - 300，直接使用缓存

2.3 获取云文档 token

进度提示：[2/4] 解析文档 token...

来源：

1. 创建飞书文档后返回的 token 或文档 URL
2. 从用户提供的文档链接解析

URL 解析规则：

文档类型	URL 示例
文件夹	https://xxx.feishu.cn/drive/folder/【token】
文件	https://xxx.feishu.cn/file/【token】
旧版文档	https://xxx.feishu.cn/docs/【token】
新版文档	https://xxx.feishu.cn/docx/【token】
电子表格	https://xxx.feishu.cn/【token】
多维表格	https://xxx.feishu.cn/base/【token】
知识空间	https://xxx.feishu.cn/wiki/settings/【token】
知识库节点	https://xxx.feishu.cn/wiki/【token】

⚠️ 复制 URL 时注意删除末尾多余的 # 符号。

自动识别 doc_type：

URL 路径特征	doc_type
/drive/folder/	folder
/file/	file
/docs/	doc
/docx/	docx
/base/	bitable
/wiki/	wiki
其他（根路径）	sheet

识别逻辑：

1. 从 URL 提取 token（最后一个路径段，去除 ? 和 # 后的内容）
2. 根据 URL 路径匹配 doc_type
3. 若无法匹配，提示用户提供文档类型

变量定义：

• FILE_TOKEN = 获取到的云文档 token
• DOC_TYPE = 识别到的文档类型

2.4 添加用户权限

工具：exec

进度提示：[3/4] 添加用户权限...

请求：

curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/permissions/{FILE_TOKEN}/members/batch_create?type={DOC_TYPE}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {tenant_access_token}" \
  -d "{
    \"members\": [{
      \"member_type\": \"openid\",
      \"member_id\": \"$OWNER_OPEN_ID\",
      \"perm\": \"full_access\"
    }]
  }"

参数说明：

参数	来源	示例
{FILE_TOKEN}	创建文档时返回或 URL 解析	xxxxx
{DOC_TYPE}	URL 路径自动识别	bitable
{tenant_access_token}	上一步获取	t-xxx
$OWNER_OPEN_ID	ownerOpenId	ou_xxx

doc_type 可选值：

值	文档类型
bitable	多维表格
docx	新版文档
doc	旧版文档
sheet	电子表格
folder	文件夹
file	云空间文件
wiki	知识库节点

成功返回：

{
  "code": 0,
  "msg": "Success",
  "data": {
    "members": [{
      "member_id": "xxxx",
      "member_type": "openid",
      "perm": "full_access"
    }]
  }
}

2.5 执行结果反馈

进度提示：[4/4] 完成！

成功时：

✅ 权限添加成功！

📄 文档：{文档标题或 token}
🔗 链接：{文档 URL}
👤 权限：完整权限 (full_access)
你现在可以直接访问和编辑这个文档了。
如果配置文件中没有ownerOpenId 并询问 是否需要将 ownerOpenId 写入配置文件中

失败时：

❌ 权限添加失败

原因：{错误信息}
解决方案：{具体步骤}

需要帮助？请提供以上信息。

---

使用示例 📝

示例 1：创建多维表格后自动添加权限

用户：帮我创建一个多维表格叫「项目进度追踪」

Agent 执行流程：

[1/3] 创建多维表格...
      → 调用 feishu_bitable_create_app(name="项目进度追踪")
      → 返回 app_token: "bascnxxx"

[2/3] 添加用户权限...
      → 触发 feishu-perm-auto skill
      → 检查配置：appId ✓ appSecret ✓ ownerOpenId ✓
      → 获取 tenant_access_token
      → 调用权限 API 添加 full_access

[3/3] 完成！

Agent 回复：

✅ 多维表格「项目进度追踪」已创建！

🔗 链接：https://xxx.feishu.cn/base/bascnxxx
🔐 已自动为你添加完整权限，可直接访问和编辑

---

示例 2：用户反馈文档无权限

用户：这个文档我打不开，提示没权限 https://xxx.feishu.cn/docx/doxcnxxx

Agent 执行流程：

[1/3] 解析文档信息...
      → URL 解析：token=doxcnxxx, doc_type=docx

[2/3] 检查配置并添加权限...
      → 检查配置：appId ✓ appSecret ✓ ownerOpenId ✓
      → 获取 tenant_access_token
      → 调用权限 API 添加 full_access

[3/3] 完成！

Agent 回复：

✅ 权限添加成功！

📄 文档：doxcnxxx
🔗 链接：https://xxx.feishu.cn/docx/doxcnxxx
👤 权限：完整权限 (full_access)

你现在可以直接访问和编辑这个文档了。

---

示例 3：首次使用，配置缺失

用户：帮我创建一个飞书文档

Agent 执行流程：

[1/2] 检查配置...
      → 读取 ~/.openclaw/openclaw.json
      → 发现 channels.feishu.appId 缺失

[2/2] 引导配置...

Agent 回复：

⚠️ 还没配置飞书应用凭证，需要先设置一下：

📱 获取飞书应用凭证：

1. 打开浏览器，访问：https://open.feishu.cn/app
2. 登录你的飞书账号
3. 点击「创建企业自建应用」或选择已有应用
4. 在左侧菜单找到「凭证与基础信息」
5. 复制以下内容：
   - App ID（cli_ 开头的字符串）
   - App Secret（点击「查看」后显示）

请把 App ID 和 App Secret 发给我，格式如下：
appId: cli_xxxxxxxx
appSecret: xxxxxxxx

用户回复后：

用户：appId: cli_aabbccdd
      appSecret: 1234567890abcdef

Agent：
[1/2] 验证凭证...
      → 获取 tenant_access_token 成功 ✓

[2/2] 保存配置...
      → 更新 ~/.openclaw/openclaw.json

Agent 回复：

✅ 飞书应用配置成功！

现在可以正常使用飞书功能了。需要我帮你创建文档吗？

---

示例 4：权限已存在（幂等处理）

用户：给这个文档加权限 https://xxx.feishu.cn/base/bascnxxx

Agent 执行流程：

[1/3] 解析文档信息...
      → token=bascnxxx, doc_type=bitable

[2/3] 添加权限...
      → 调用 API 返回错误码 99991661（成员已存在）

[3/3] 幂等处理...
      → 视为成功，无需重复添加

Agent 回复：

✅ 权限已存在！

📄 文档：bascnxxx
🔗 链接：https://xxx.feishu.cn/base/bascnxxx
👤 权限：完整权限 (full_access)

你已经有这个文档的完整权限了。

---

配置引导流程 🔧

当第一步检查发现配置缺失时，按以下流程引导用户配置。

A. 获取 App ID 和 App Secret

📱 获取飞书应用凭证：

1. 打开浏览器，访问：https://open.feishu.cn/app
2. 登录你的飞书账号
3. 点击「创建企业自建应用」或选择已有应用
4. 在左侧菜单找到「凭证与基础信息」
5. 复制以下内容：
   - App ID（cli_ 开头的字符串）
   - App Secret（点击「查看」后显示）

请把 App ID 和 App Secret 发给我，格式如下：
appId: cli_xxxxxxxx
appSecret: xxxxxxxx

B. 获取 ownerOpenId

优先从会话上下文提取：若上下文中出现 user:ou_xxx 格式，直接提取 ou_xxx 使用。

否则引导用户获取：

1. 登录 API 调试台，找到发送消息接口
2. 在「查询参数」页签，将 user_id_type 设置为 open_id
3. 点击「快速复制 open_id」

详见：https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-openid

用户回复后：

1. 验证格式是否正确（以 ou_ 开头）
2. 在当前会话中使用此 ownerOpenId

C. 配置应用权限

⚠️ 在使用前，还需要给应用添加权限：

1. 在飞书开放平台，点击左侧「权限管理」
2. 搜索并开通以下权限：
   - docs:permission.member:create (添加云文档协作者)

3. 点击「发布版本」使权限生效

如果权限显示「待确认」，需要联系企业管理员审批。

---

权限级别说明 🔐

权限值	中文名	能做什么	适用场景
view	只读	只能查看，不能修改	分享给他人查看
edit	可编辑	可以修改内容，不能管理权限	协作编辑
full_access	完整权限	可以编辑、管理权限、删除	文档所有者（推荐）

💡 建议：给用户添加 full_access 权限，这样用户可以完全控制文档。

权限选择建议：

场景	推荐权限	原因
用户自己的文档	full_access	完全控制
协作编辑	edit	避免误删
只读分享	view	安全最小化

💡 默认使用 full_access，但可在执行时询问用户需求。

---

错误处理大全 ⚠️

错误码	错误信息	原因	解决方案	处理动作
10003	app id or app secret is invalid	App ID 或 App Secret 错误	检查配置，确保复制正确	重新配置后重试
99991661	成员已存在	用户已有权限	视为成功，无需处理	直接返回成功
99991663	Invalid access token	token 过期或无效	重新获取 tenant_access_token	重新执行 2.2
99991664	Permission denied	应用没有权限	引导配置应用权限	跳转配置引导 C
99991600	token not found	文档 token 不存在	检查 file_token 是否正确	确认后重试

---

最佳实践 💡

配置管理

• ✅ 首次使用时引导用户配置
• ✅ 配置保存后，后续自动读取
• ⚠️ 不要在日志中输出 App Secret

错误处理

• ✅ 每一步都要检查返回的 code
• ✅ 失败时给出清晰的错误原因
• ✅ 提供具体的解决方案和处理动作

用户体验

• ✅ 每步输出进度提示 [1/4] [2/4] [3/4] [4/4]
• ✅ 成功后返回文档链接
• ✅ 告诉用户权限已添加
• ✅ 提示用户可以直接访问
• ✅ 成功后询问用户是否需要将 ownerOpenId 写入配置文件

安全考虑

• ⚠️ App Secret 不要硬编码在 skill 中
• ⚠️ 不要在回复中显示完整的 App Secret（只显示前4位 + ***）
• ⚠️ token 有效期约 2 小时，建议缓存避免频繁请求

敏感信息脱敏：

信息类型	原始值	脱敏后
App Secret	abc123xyz789	abc1***
tenant_access_token	t-xxx123456	t-xxx***
ownerOpenId	ou_abc123	ou_abc***

脱敏实现：

def mask_secret(s, show=4):
    return s[:show] + '***' if len(s) > show else '***'

---

相关链接 📎

资源	链接
飞书开放平台	https://open.feishu.cn/app
权限配置指南	https://open.feishu.cn/document/docs/permission/permission-member/batch_create
获取 Open ID	https://open.feishu.cn/document/faq/trouble-shooting/how-to-obtain-openid

---

快速参考卡片 📌

┌─────────────────────────────────────────────────────────┐
│  飞书权限添加快速参考                                    │
├─────────────────────────────────────────────────────────┤
│  1. 检查配置：~/.openclaw/openclaw.json                 │
│     - appId (必需)                                      │
│     - appSecret (必需)                                  │
│     - ownerOpenId (可选，会话上下文补充)                  │
│     - 应用权限: docs:permission.member:create (必需)     │
├─────────────────────────────────────────────────────────┤
│  2. 获取 tenant_access_token：                           │
│     POST /auth/v3/tenant_access_token/internal          │
│     Body: {app_id, app_secret}                          │
├─────────────────────────────────────────────────────────┤
│  3. 获取云文档 token：                                   │
│     创建时返回 或 从 URL 解析                            │
│     自动识别 doc_type: /base/→bitable, /docx/→docx...   │
├─────────────────────────────────────────────────────────┤
│  4. 添加权限：                                          │
│     POST /drive/v1/permissions/{token}/members          │
│     Header: Authorization: Bearer {token}               │
│     Body: {members: [{member_type, member_id, perm}]}   │
├─────────────────────────────────────────────────────────┤
│  文档类型：                                             │
│    bitable | docx | doc | sheet | folder | file | wiki │
│  权限级别：view | edit | full_access                    │
└─────────────────────────────────────────────────────────┘