飞书多维表格 CRUD Skill / Feishu Bitable CRUD

教会 OpenClaw Agent 正确操作飞书（Lark）多维表格，避免常见的 token 混淆错误。

为什么需要这个 Skill？

OpenClaw 内置的 feishu_bitable_* 工具已经支持多维表格 CRUD，但 Agent 常常犯一个错误： 直接把飞书链接中的 token 当作 app_token 使用，导致 91402 NOTEXIST 错误。

这在飞书知识库（wiki）嵌入的多维表格中尤其常见 — wiki URL 中的 token 是 node_token，不是 bitable 的 app_token。

这个 Skill 教会 Agent：

1. 始终先调用 feishu_bitable_get_meta 解析 URL，获取真实的 app_token
2. 再用解析得到的 app_token 执行后续 CRUD 操作

安装

clawhub install feishu-bitable-crud

或手动复制到 ~/.openclaw/workspace/skills/feishu-bitable/。

前提条件

1. 飞书插件已启用 — openclaw.json 中配置了飞书 channel（appId + appSecret）
2. 应用权限 — 在飞书开放平台后台开通以下权限：
   • bitable:app — 管理多维表格
   • bitable:app:readonly — 读取多维表格
   • wiki:wiki:readonly — 读取知识库（wiki URL 解析需要）
3. 资源权限 — 在飞书多维表格的「分享」设置中，将你的应用添加为协作者

核心规则

当用户给出包含 /wiki/ 的飞书链接时，必须先用 feishu_bitable_get_meta 解析出真实的 app_token，再进行后续操作。绝对不能直接把 wiki 的 node_token 当作 app_token 使用。

URL 格式说明

飞书多维表格有两种链接格式：

1. Base 格式（直链）：https://xxx.feishu.cn/base/AppToken123?table=tblXXX
   • AppToken123 就是 app_token，可直接使用
2. Wiki 格式（知识库嵌入）：https://xxx.feishu.cn/wiki/NodeToken456
   • NodeToken456 是 wiki 的 node_token，不是 bitable 的 app_token
   • 必须先调用 feishu_bitable_get_meta 解析

标准操作流程

第一步：解析 URL，获取 app_token 和 table_id

无论用户给的是 wiki 还是 base 链接，都先调用 feishu_bitable_get_meta：

feishu_bitable_get_meta({ url: "用户给的完整URL" })

返回值包含：

• app_token：真实的多维表格 token（后续所有操作都用这个）
• table_id：如果 URL 带 ?table= 参数则有
• tables：表格列表（如果没指定 table_id）

重要：记住返回的 app_token，后续所有操作都使用它，不要再用 URL 里的 token。

第二步：获取表结构（字段列表）

feishu_bitable_list_fields({ app_token: "上一步获取的app_token", table_id: "table_id" })

返回每个字段的 field_name、type、type_name，写入数据时字段名必须与此一致。

第三步：执行操作

写入记录

feishu_bitable_create_record({
  app_token: "app_token",
  table_id: "table_id",
  fields: {
    "字段名1": "文本值",
    "字段名2": 123,
    "字段名3": { text: "显示文本", link: "https://example.com" }
  }
})

查询记录

feishu_bitable_list_records({
  app_token: "app_token",
  table_id: "table_id",
  page_size: 100
})

更新记录

feishu_bitable_update_record({
  app_token: "app_token",
  table_id: "table_id",
  record_id: "recXXX",
  fields: { "字段名": "新值" }
})

创建新表格

feishu_bitable_create_app({ name: "表格名称" })

创建字段

feishu_bitable_create_field({
  app_token: "app_token",
  table_id: "table_id",
  field_name: "新字段名",
  field_type: 1
})

字段类型对照

常见错误及解决

完整示例：用户给 wiki 链接，写入数据

用户：把数据写入 https://xxx.feishu.cn/wiki/Abc123Def

Step 1: feishu_bitable_get_meta({ url: "https://xxx.feishu.cn/wiki/Abc123Def" })
        → { app_token: "RealToken789", tables: [{ table_id: "tbl001", name: "Sheet1" }] }

Step 2: feishu_bitable_list_fields({ app_token: "RealToken789", table_id: "tbl001" })
        → { fields: [{ field_name: "标题", type: 1 }, { field_name: "链接", type: 15 }] }

Step 3: feishu_bitable_create_record({
          app_token: "RealToken789",
          table_id: "tbl001",
          fields: {
            "标题": "示例数据",
            "链接": { text: "点击查看", link: "https://example.com" }
          }
        })