ClawHub

飞书开放平台 API

Data & APIs

飞书开放平台 API 技能。用于：(1) 调用飞书开放 API 完成插件以外的操作（如批量写入、权限管理、文件夹操作等）；(2) 实现 OAuth 用户授权流程；(3) 批量数据处理。 当用户提到飞书 API、飞书开放平台、OAuth 授权、user_access_token，或需要批量操作飞书数据（多维表格批量写入/删除、权限配置、云文档管理）时触发。

Install

openclaw skills install feishu-api

飞书开放平台 API

本技能提供直接调用飞书开放 API 的能力，作为飞书插件工具的补充。

核心概念

认证方式

类型用途有效期
tenant_access_token应用身份调用 API2小时
user_access_token代表用户操作有效期短，需刷新

重要：所有脚本中不得硬编码 app_id、app_secret、access_token。从配置文件读取或使用环境变量。

读取凭据

飞书凭据存储在 ~/.openclaw/openclaw.json 的 channels.feishu 下：

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

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

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. 批量操作多维表格

# 批量创建记录
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. 权限管理

# 添加协作者
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

详细参考

数据安全准则

  1. 不硬编码凭据 - 始终从配置文件读取
  2. 不输出敏感信息 - 不打印 token、secret 等
  3. 最小权限 - 仅申请所需的权限范围
  4. 定期刷新 - token 过期前刷新

速率限制

  • 普通 API：每应用每秒 10 请求
  • 上传文件：每应用每分钟 60 次
  • 批量接口：每批最大 50 条记录
More in Data & APIs