Claude 操作飞书文档、表格和群聊的完整流程总结

这次测试的目标是验证：

Claude 能否通过飞书机器人创建文档、创建表格、给群聊授权、往表格写入数据、再把结果发到群里。

最终结果是：

可以实现。

完整链路如下：

Claude
  ↓
本地脚本 / MCP Server / 后端服务
  ↓
飞书 OpenAPI
  ↓
飞书文档 / 飞书表格 / 飞书群聊

---

一、整体原理

Claude 本身并不会直接登录飞书，也不会像人一样点网页按钮。

真正的执行者是：

飞书自建应用 / 机器人

Claude 只是调用你暴露给它的工具，例如：

create_doc()
create_sheet()
grant_permission()
write_sheet_values()
send_group_message()

这些工具内部使用：

App ID + App Secret

获取飞书访问令牌：

tenant_access_token

然后调用飞书 OpenAPI 完成操作。

所以本质原理是：

Claude 负责理解任务和生成调用逻辑
飞书机器人负责持有权限
OpenAPI 负责真正执行操作

---

二、准备飞书自建应用

进入飞书开放平台：

https://open.feishu.cn/

创建或使用已有的企业自建应用。

你需要准备：

App ID
App Secret

例如本次测试使用的是：

App ID: cli_xxx
App Secret: xxxxxx

注意：博客里不要写真实 Secret。

---

三、开启应用权限

如果只想发群消息，需要消息权限。

如果要操作文档、表格和权限，需要额外开通云文档、电子表格、权限管理相关 Scope。

本次测试涉及的能力包括：

获取 tenant_access_token
创建飞书文档
创建飞书表格
给群聊授权
写入飞书表格内容
发送群消息

建议开启的权限包括：

im:message
docx:document
drive:drive
drive:file
drive:permission:member
drive:permission:member:create
sheets:spreadsheet
sheets:spreadsheet:create

不同飞书后台显示可能是中文名称，可以搜索：

消息
云文档
文档
云空间
权限
协作者
电子表格
Sheets

开启权限后必须：

保存配置
发布新版本
管理员审批通过

否则接口仍然会提示无权限。

---

四、获取 tenant_access_token

Claude 调用飞书 OpenAPI 前，首先要用 App ID 和 App Secret 获取应用身份令牌。

接口：

POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal

请求体：

{
  "app_id": "cli_xxx",
  "app_secret": "你的 App Secret"
}

成功返回：

{
  "code": 0,
  "msg": "ok",
  "tenant_access_token": "t-xxxx"
}

后续所有接口请求都带上：

Authorization: Bearer tenant_access_token

---

五、创建飞书文档

接口：

POST https://open.feishu.cn/open-apis/docx/v1/documents

请求体：

{
  "title": "Claude 测试文档"
}

返回示例：

{
  "code": 0,
  "data": {
    "document": {
      "document_id": "MfFmdctcOomIHExABGncvFaFnue",
      "revision_id": 1,
      "title": "Claude 群授权测试文档"
    }
  },
  "msg": "success"
}

文档链接可以拼成：

https://feishu.cn/docx/{document_id}

例如：

https://feishu.cn/docx/MfFmdctcOomIHExABGncvFaFnue

---

六、创建飞书表格

接口：

POST https://open.feishu.cn/open-apis/sheets/v3/spreadsheets

请求体：

{
  "title": "Claude 测试表格"
}

成功返回：

{
  "code": 0,
  "data": {
    "spreadsheet": {
      "spreadsheet_token": "WkJhsA6srh5amCtuO3dcLFOWnwe",
      "title": "Claude 群授权测试表格",
      "url": "https://xxx.feishu.cn/sheets/WkJhsA6srh5amCtuO3dcLFOWnwe"
    }
  },
  "msg": "success"
}

表格链接：

https://xxx.feishu.cn/sheets/{spreadsheet_token}

---

七、为什么创建后人打不开？

用：

tenant_access_token

创建的文档或表格，默认是：

应用身份创建

不是你个人账号创建。

所以你本人不一定默认有权限打开。

也就是说：

应用有权限 ≠ 人有权限

这时需要调用云文档权限接口，把你、群聊或部门加入协作者。

---

八、给群聊授权

本次测试把文档和表格授权给群聊：

oc_xxx

使用的接口：

POST https://open.feishu.cn/open-apis/drive/v1/permissions/{file_token}/members?type={file_type}&need_notification=false

1. 给文档授权

文档的 file_token 是：

document_id

文档类型：

docx

接口示例：

POST https://open.feishu.cn/open-apis/drive/v1/permissions/MfFmdctcOomIHExABGncvFaFnue/members?type=docx&need_notification=false

请求体：

{
  "member_type": "openchat",
  "member_id": "oc_xxx",
  "perm": "full_access"
}

2. 给表格授权

表格的 file_token 是：

spreadsheet_token

表格类型：

sheet

接口示例：

POST https://open.feishu.cn/open-apis/drive/v1/permissions/WkJhsA6srh5amCtuO3dcLFOWnwe/members?type=sheet&need_notification=false

请求体：

{
  "member_type": "openchat",
  "member_id": "oc_xxx",
  "perm": "full_access"
}

---

九、关键坑：群聊 member_type 不是 chat

一开始我用了：

{
  "member_type": "chat"
}

结果接口报错：

field validation failed
member_type options: [email, openid, unionid, openchat, opendepartmentid, userid, groupid, wikispaceid, appid]

正确写法是：

{
  "member_type": "openchat"
}

也就是说：

飞书群聊授权时，member_type 要用 openchat

不是：

chat

---

十、新增一个工作表

在创建好的电子表格中新增一个工作表，表名为当前日期。

接口：

POST https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/sheets_batch_update

请求体：

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "2026-06-23",
          "index": 0
        }
      }
    }
  ]
}

成功返回：

{
  "code": 0,
  "data": {
    "replies": [
      {
        "addSheet": {
          "properties": {
            "index": 0,
            "sheetId": "1vjYk0",
            "title": "2026-06-23"
          }
        }
      }
    ]
  },
  "msg": "success"
}

这里需要保存：

sheetId

后面写入数据时要用它。

---

十一、写入表格数据

写入单元格使用：

PUT https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values

请求体格式：

{
  "valueRange": {
    "range": "1vjYk0!A1:J13",
    "values": [
      ["员工信息管理表", "", "", "", "", "", "", "", "", ""],
      ["序号", "员工姓名", "所属部门", "入职日期", "岗位", "基本工资", "绩效工资", "社保公积金", "实发工资", "备注"],
      [1, "张三", "技术部", "2022-03-15", "后端开发工程师", "¥8,000.00", "¥3,000.00", "¥1,200.00", "¥9,800.00", "转正"]
    ]
  }
}

本次实际写入：

范围：1vjYk0!A1:J13
行数：13
列数：10
单元格数：130

接口返回：

{
  "code": 0,
  "data": {
    "updatedCells": 130,
    "updatedColumns": 10,
    "updatedRange": "1vjYk0!A1:J13",
    "updatedRows": 13
  },
  "msg": "success"
}

---

十二、发送群消息

接口：

POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id

请求体：

{
  "receive_id": "oc_xxx",
  "msg_type": "text",
  "content": "{\"text\":\"Claude 已完成飞书表格写入\"}"
}

注意这里的 content 是一个 JSON 字符串，不是 JSON 对象。

也就是说，实际构造时通常是：

json.dumps({
    "text": "Claude 已完成飞书表格写入"
}, ensure_ascii=False)

成功后返回：

{
  "code": 0,
  "msg": "success",
  "data": {
    "message_id": "om_xxx"
  }
}

---

十三、完整 Python 示例

下面是一个简化版完整流程：

import json
import time
import urllib.request

APP_ID = "cli_xxx"
APP_SECRET = "不要写真实 Secret"
CHAT_ID = "oc_xxx"

def post_json(url, token=None, payload=None):
    data = json.dumps(payload or {}, ensure_ascii=False).encode("utf-8")
    headers = {"Content-Type": "application/json; charset=utf-8"}
    if token:
        headers["Authorization"] = f"Bearer {token}"

    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read().decode("utf-8"))

def put_json(url, token=None, payload=None):
    data = json.dumps(payload or {}, ensure_ascii=False).encode("utf-8")
    headers = {"Content-Type": "application/json; charset=utf-8"}
    if token:
        headers["Authorization"] = f"Bearer {token}"

    req = urllib.request.Request(url, data=data, headers=headers, method="PUT")
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read().decode("utf-8"))

# 1. 获取 tenant_access_token
token_resp = post_json(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    payload={
        "app_id": APP_ID,
        "app_secret": APP_SECRET
    }
)

tenant_token = token_resp["tenant_access_token"]

# 2. 创建文档
doc_resp = post_json(
    "https://open.feishu.cn/open-apis/docx/v1/documents",
    token=tenant_token,
    payload={
        "title": "Claude 测试文档"
    }
)

doc_id = doc_resp["data"]["document"]["document_id"]
doc_url = f"https://feishu.cn/docx/{doc_id}"

# 3. 创建表格
sheet_resp = post_json(
    "https://open.feishu.cn/open-apis/sheets/v3/spreadsheets",
    token=tenant_token,
    payload={
        "title": "Claude 测试表格"
    }
)

spreadsheet_token = sheet_resp["data"]["spreadsheet"]["spreadsheet_token"]
sheet_url = sheet_resp["data"]["spreadsheet"]["url"]

# 4. 给文档授权给群聊
post_json(
    f"https://open.feishu.cn/open-apis/drive/v1/permissions/{doc_id}/members?type=docx&need_notification=false",
    token=tenant_token,
    payload={
        "member_type": "openchat",
        "member_id": CHAT_ID,
        "perm": "full_access"
    }
)

# 5. 给表格授权给群聊
post_json(
    f"https://open.feishu.cn/open-apis/drive/v1/permissions/{spreadsheet_token}/members?type=sheet&need_notification=false",
    token=tenant_token,
    payload={
        "member_type": "openchat",
        "member_id": CHAT_ID,
        "perm": "full_access"
    }
)

# 6. 新增工作表
today = time.strftime("%Y-%m-%d")

add_sheet_resp = post_json(
    f"https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/sheets_batch_update",
    token=tenant_token,
    payload={
        "requests": [
            {
                "addSheet": {
                    "properties": {
                        "title": today,
                        "index": 0
                    }
                }
            }
        ]
    }
)

sheet_id = add_sheet_resp["data"]["replies"][0]["addSheet"]["properties"]["sheetId"]

# 7. 写入数据
values = [
    ["员工信息管理表", "", "", "", "", "", "", "", "", ""],
    ["序号", "员工姓名", "所属部门", "入职日期", "岗位", "基本工资", "绩效工资", "社保公积金", "实发工资", "备注"],
    [1, "张三", "技术部", "2022-03-15", "后端开发工程师", "¥8,000.00", "¥3,000.00", "¥1,200.00", "¥9,800.00", "转正"],
    [2, "李四", "市场部", "2021-07-20", "市场专员", "¥6,000.00", "¥2,500.00", "¥900.00", "¥7,600.00", ""],
    [3, "王五", "财务部", "2020-11-05", "会计", "¥7,000.00", "¥2,000.00", "¥1,000.00", "¥8,000.00", "资深"],
]

put_json(
    f"https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values",
    token=tenant_token,
    payload={
        "valueRange": {
            "range": f"{sheet_id}!A1:J{len(values)}",
            "values": values
        }
    }
)

# 8. 发群消息
post_json(
    "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id",
    token=tenant_token,
    payload={
        "receive_id": CHAT_ID,
        "msg_type": "text",
        "content": json.dumps({
            "text": f"Claude 已完成飞书测试\n文档：{doc_url}\n表格：{sheet_url}"
        }, ensure_ascii=False)
    }
)

---

十四、本次踩坑记录

坑 1：只开文档权限不能创建表格

第一次创建表格失败，提示缺少：

drive:drive
sheets:spreadsheet
sheets:spreadsheet:create

解决方法：

去飞书开放平台补充 Sheets 相关权限
发布新版本
管理员审批

---

坑 2：应用创建的文档，人不一定能打开

原因：

tenant_access_token 是应用身份
不是用户身份

解决方法：

创建后调用权限 API，把用户、群聊或部门加入协作者

---

坑 3：群聊授权 member_type 不是 chat

错误：

{
  "member_type": "chat"
}

正确：

{
  "member_type": "openchat"
}

---

坑 4：发送消息的 content 要是字符串

错误理解：

{
  "content": {
    "text": "hello"
  }
}

正确：

{
  "content": "{\"text\":\"hello\"}"
}

也就是：

"content": json.dumps({"text": "hello"}, ensure_ascii=False)

---

坑 5：样式接口比写值接口更容易踩格式问题

本次写入数据成功：

updatedCells: 130

但尝试设置合并单元格、列宽、冻结行时返回：

request body is wrong

所以如果只是做自动化数据写入，建议先跑通：

创建表格
授权
新增工作表
写入 values
发送消息

再单独研究样式 API。

---

十五、推荐的博客结论

可以这样总结：

Claude 操作飞书的核心不是 Claude 拥有飞书能力，而是我们给 Claude 接入了一个拥有飞书 OpenAPI 权限的工具层。

具体来说：

飞书自建应用负责鉴权和权限
tenant_access_token 代表应用身份
OpenAPI 负责创建文档、创建表格、写入数据、发送消息
Claude 负责理解用户意图并调用对应工具

最小可行闭环是：

1. 创建飞书自建应用
2. 开启文档、表格、消息、权限相关 Scope
3. 发布应用并通过审批
4. 用 App ID + App Secret 获取 tenant_access_token
5. 调用 OpenAPI 创建文档和表格
6. 调用 Drive 权限 API 授权给群聊
7. 调用 Sheets API 写入数据
8. 调用 IM API 把链接发到群里

最终效果：

用户在群里说需求
Claude 理解需求
Claude 调用工具
工具调用飞书 OpenAPI
飞书文档/表格被自动创建和更新
机器人把结果发回群聊

---

十六、安全建议

不要在博客、代码仓库、聊天记录里暴露：

App Secret
tenant_access_token
user_access_token

建议使用环境变量：

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxxx"

代码里读取：

import os

APP_ID = os.environ["FEISHU_APP_ID"]
APP_SECRET = os.environ["FEISHU_APP_SECRET"]

并且把敏感文件加入：

.gitignore

例如：

.env
*.secret

如果 Secret 已经暴露，应立即去飞书开放平台重置。