Openclaw Feishu Docs Perm Auto

飞书文档权限自动添加

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

前置条件

变量速查表

第一步：检查配置 ⚠️

1.1 读取配置文件

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

1.2 检查必需字段

在 channels.feishu 下查找：

*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 能正确执行

工具调用示例：

# 读取配置文件
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 缓存策略：

缓存实现：

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

2.3 获取云文档 token

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

来源：

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

URL 解析规则：

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

自动识别 doc_type：

识别逻辑：

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\"
    }]
  }"

参数说明：

doc_type 可选值：

成功返回：

{
  "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. 点击「发布版本」使权限生效

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

权限级别说明 🔐

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

权限选择建议：

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

错误处理大全 ⚠️

最佳实践 💡

配置管理

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

错误处理

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

用户体验

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

安全考虑

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

敏感信息脱敏：

脱敏实现：

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

相关链接 📎

快速参考卡片 📌

┌─────────────────────────────────────────────────────────┐
│  飞书权限添加快速参考                                    │
├─────────────────────────────────────────────────────────┤
│  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                    │
└─────────────────────────────────────────────────────────┘