back
loading skill details...
飞书开放平台 API 技能。用于:(1) 调用飞书开放 API 完成插件以外的操作(如批量写入、权限管理、文件夹操作等);(2) 实现 OAuth 用户授权流程;(3) 批量数据处理。 当用户提到飞书 API、飞书开放平台、OAuth 授权、user_access_token,或需要批量操作飞书数据(多维表格批量...
---
name: feishu-api
description: |
飞书开放平台 API 技能。用于:(1) 调用飞书开放 API 完成插件以外的操作(如批量写入、权限管理、文件夹操作等);(2) 实现 OAuth 用户授权流程;(3) 批量数据处理。
当用户提到飞书 API、飞书开放平台、OAuth 授权、user_access_token,或需要批量操作飞书数据(多维表格批量写入/删除、权限配置、云文档管理)时触发。
---
# 飞书开放平台 API
本技能提供直接调用飞书开放 API 的能力,作为飞书插件工具的补充。
## 核心概念
### 认证方式
| 类型 | 用途 | 有效期 |
|------|------|--------|
| `tenant_access_token` | 应用身份调用 API | 2小时 |
| `user_access_token` | 代表用户操作 | 有效期短,需刷新 |
**重要**:所有脚本中不得硬编码 `app_id`、`app_secret`、`access_token`。从配置文件读取或使用环境变量。
### 读取凭据
飞书凭据存储在 `~/.openclaw/openclaw.json` 的 `channels.feishu` 下:
```python
import json
with open('/root/.openclaw/openclaw.json') as f:
config = json.load(f)
feishu_cfg = config.get('channels', {}).get('feishu', {})
APP_ID = feishu_cfg.get('appId', '')
APP_SECRET = feishu_cfg.get('appSecret', '')
```
## 典型工作流
### 1. 获取 Token
```python
import ssl, urllib.request, json
def get_app_access_token(app_id, app_secret):
url = 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal'
data = json.dumps({'app_id': app_id, 'app_secret': app_secret}).encode()
req = urllib.request.Request(url, data=data, method='POST')
req.add_header('Content-Type', 'application/json')
ctx = ssl._create_unverified_context()
with urllib.request.urlopen(req, context=ctx, timeout=10) as r:
return json.loads(r.read()).get('tenant_access_token')
```
### 2. 调用 API
```python
def call_feishu_api(url, method, token, payload=None):
ctx = ssl._create_unverified_context()
data = json.dumps(payload, ensure_ascii=False).encode() if payload else None
req = urllib.request.Request(url, data=data, method=method)
req.add_header('Authorization', f'Bearer {token}')
req.add_header('Content-Type', 'application/json')
with urllib.request.urlopen(req, context=ctx, timeout=30) as r:
return json.loads(r.read())
```
### 3. 批量操作多维表格
```python
# 批量创建记录
url = f'https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create'
payload = {'records': [{'fields': {'字段名': '值'}} for item in items]}
result = call_feishu_api(url, 'POST', token, payload)
# 批量删除记录
url = f'https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_delete'
payload = {'records': ['record_id_1', 'record_id_2']}
result = call_feishu_api(url, 'POST', token, payload)
```
### 4. 权限管理
```python
# 添加协作者
url = f'https://open.feishu.cn/open-apis/drive/v1/permissions/{file_token}/members?type=bitable'
payload = {
'member_type': 'openid', # 或 email, userid, unionid
'member_id': 'ou_xxx', # 用户 open_id
'perm': 'edit' # view | edit | full_access
}
result = call_feishu_api(url, 'POST', token, payload)
```
## 常用 API 端点
| 功能 | 端点 |
|------|------|
| 批量创建多维表格记录 | `POST /bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create` |
| 批量删除多维表格记录 | `POST /bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_delete` |
| 更新记录 | `PUT /bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}` |
| 添加权限成员 | `POST /drive/v1/permissions/{file_token}/members?type={type}` |
| 列出权限成员 | `GET /drive/v1/permissions/{file_token}/members?type={type}` |
| 创建文件夹 | `POST /drive/v1/files/create_folder` |
| 移动文件 | `POST /drive/v1/files/{file_token}/move` |
| 上传文件 | `POST /drive/v1/files/upload_all` |
## 详细参考
- **OAuth 授权流程**:参见 [references/oauth.md](references/oauth.md)
- **多维表格 API**:参见 [references/bitable.md](references/bitable.md)
- **云文档管理**:参见 [references/drive.md](references/drive.md)
## 数据安全准则
1. **不硬编码凭据** - 始终从配置文件读取
2. **不输出敏感信息** - 不打印 token、secret 等
3. **最小权限** - 仅申请所需的权限范围
4. **定期刷新** - token 过期前刷新
## 速率限制
- 普通 API:每应用每秒 10 请求
- 上传文件:每应用每分钟 60 次
- 批量接口:每批最大 50 条记录don't have the plugin yet? install it then click "run inline in claude" again.