我把 Codex 接上了飞书文档:从只能写代码,到能写回团队知识库-夜雨聆风

我把 Codex 接上了飞书文档:从只能写代码,到能写回团队知识库

过去一段时间，我一直在尝试把 AI Coding Agent 接进真实工作流，而不是只把它当成“帮我写一段代码”的工具。

代码仓库只是工作现场的一部分。需求、接口说明、评审结论、排期、复盘、运维方案，很多都沉在飞书文档和知识库里。如果 AI 只能看本地代码，它就会天然缺少团队上下文；如果它产出的方案还要我手动复制到飞书，它也没有真正进入协作流程。

最近我做了一次完整验证：让 Codex 通过本地 CLI 读写飞书文档。最后跑通了两条链路：

tenant 模式：可以用应用/机器人身份创建文档，但创建者显示为机器人。
user 模式：通过 OAuth 授权后，可以用我的用户身份创建和写入文档，创建者显示为我本人。

最终效果是：我可以直接让 Codex 创建飞书文档、写入标题和正文块、读取文档块结构，并把操作结果返回给我。本文记录完整过程，包括我选了哪个开源仓库、装了哪个 skill、遇到了哪些权限坑，以及最后是怎么跑通的。

一、为什么要把 Codex 接入飞书？

只让 Codex 看代码仓库，它能做很多工程内的事情：

读代码、改代码、跑测试
排查报错、分析日志、查数据库
总结模块结构、解释接口逻辑
生成脚本、补测试、做 CR

但真实工作不会只发生在 IDE 里。

需求在飞书文档里，接口说明在知识库里，会议结论在多人协作文档里，故障复盘也要沉淀回文档。这里有一个明显断点：

🌈

AI 明明能理解和执行，但它拿不到团队上下文，也不能把结果写回团队系统。

所以我想要的不是“复制一段飞书内容给 Codex”，而是让 Codex 自己具备访问飞书的能力：

需要背景资料时，直接读取飞书文档
产出方案时，直接创建或更新飞书文档
做调研时，把结果沉淀成团队可见文档
做复盘时，把过程、结论和后续动作整理成结构化内容

这一步的意义不只是“多接了一个工具”，而是让 AI 从本地助手变成能进入协作系统的 Agent。

二、我选的方案：Feishu-MCP + Feishu-Skill

一开始我没有自己写飞书 SDK 封装，而是先查了市面上已有的 MCP / Skill。

最后选的是这两个开源项目：

Feishu-MCP：https://github.com/cso1z/Feishu-MCP
Feishu-Skill：https://github.com/cso1z/Feishu-Skill
Feishu-MCP 配置说明：https://github.com/cso1z/Feishu-MCP/blob/main/FEISHU_CONFIG.md

Feishu-MCP 提供 MCP Server 和一个独立 CLI：feishu-tool。它封装了飞书文档、云盘、知识库、任务、用户查询等能力。文档部分包括：

下面几张截图来自 Feishu-MCP 仓库。公众号正式发布时，建议下载后重新上传到公众号素材库，避免 GitHub raw 图片在部分网络环境下加载不稳定。

创建飞书文档
获取文档信息
获取文档块结构
批量创建块
批量更新文本块
删除块
搜索文档
创建表格
上传图片
读取白板内容

Feishu-Skill 则是给 Agent 用的说明书。它告诉 Codex / Claude Code 这类 Agent：

调用前如何检查 feishu-tool
如何检查配置
user 模式下如何检查授权
每个工具应该传什么 JSON 参数
文档、任务、成员分别看哪份参考说明

我最终采用的链路是：

Codex  ↓Feishu-Skill（告诉 Codex 怎么用工具）  ↓feishu-tool CLI  ↓Feishu-MCP 内部封装  ↓飞书开放平台 API  ↓飞书文档 / 云盘 / 知识库

这个方案的好处是边界很清楚：Codex 不需要直接理解飞书开放平台 API，也不需要我在业务项目里写一套 SDK；只要本机 feishu-tool 能跑，Codex 就可以按 CLI 方式调用。

三、安装 Feishu-Skill

我先把 Feishu-Skill 安装到了本机 Codex 的 skills 目录。

这个 skill 来自 cso1z/Feishu-Skill 仓库。它不是 npm 包，而是给 Codex 这类 Agent 读取的本地说明书：告诉 Agent 应该如何检查 feishu-tool、如何判断授权状态、不同飞书工具分别该读哪份参数文档。

安装后路径是：

~/.codex/skills/feishu-skill

目录里主要有这些文件：

SKILL.mdreference/document.mdreference/cli.mdreference/task.mdreference/member.md

其中 SKILL.md 是入口说明，reference/document.md 记录文档相关工具的参数，比如：

create_feishu_document
get_feishu_document_info
get_feishu_document_blocks
batch_create_feishu_blocks
batch_update_feishu_block_text
search_feishu_documents

这一步很关键。没有 skill，Codex 也许能调用 CLI，但每次都要临时猜工具参数，很容易出错；有了 skill，它会先读对应参考文档，再按工具签名执行。

四、安装 feishu-tool

feishu-tool 来自 feishu-mcp npm 包。我本机安装方式是：

npm install -g feishu-mcp@latest

安装完成后验证：

command -v feishu-toolfeishu-tool --help

我当时看到的工具列表包括：

create_feishu_documentget_feishu_document_infoget_feishu_document_blockssearch_feishu_documentsbatch_update_feishu_block_textbatch_create_feishu_blocksdelete_feishu_document_blocksget_feishu_image_resourceupload_and_bind_image_to_blockcreate_feishu_tableget_feishu_whiteboard_contentfill_whiteboard_with_plantumlget_feishu_root_folder_infoget_feishu_folder_filescreate_feishu_folder

这说明 CLI 已经装好，后面的问题就主要是飞书应用权限和授权模式。

这里有一个小细节：安装时如果出现 EBADENGINE warning，不一定代表安装失败，可以先看 feishu-tool --help 是否能正常输出。但长期使用建议按包声明使用 Node 20.x，避免后续依赖兼容性问题。

五、配置飞书应用

接下来要在飞书开放平台创建企业自建应用，拿到：

App ID
App Secret

飞书开放平台入口是：

https://open.feishu.cn/app

创建应用的流程可以参考 Feishu-MCP 仓库里的截图。先创建企业自建应用：

然后在应用凭证页拿到 App ID 和 App Secret：

然后写入 feishu-tool 全局配置：

feishu-tool config set FEISHU_APP_ID <your-app-id>feishu-tool config set FEISHU_APP_SECRET <your-app-secret>feishu-tool config set FEISHU_ENABLED_MODULES document

配置会保存到：

~/.cache/feishu-mcp/.env

这点比每个项目单独放 .env 更适合本地 Agent 工作流。飞书密钥不应该进代码仓库，也不应该散落在多个业务项目里。

我一开始只启用了 document 模块，而不是 all：

feishu-tool config set FEISHU_ENABLED_MODULES document

原因很简单：先把文档链路跑通。任务、成员、日历这些能力以后再扩展。否则权限面太大，排查时也会混在一起。

六、权限和授权：这一步不要跳过

这次接入最容易踩坑的不是 CLI，也不是 Codex，而是飞书开放平台权限。

飞书这套权限至少要分成四层看：

应用凭证：App ID / App Secret
应用权限：文档、云盘、搜索、知识库等 API 权限
OAuth 安全设置：重定向 URL
用户授权：user 模式下用户本人同意授权

很多人会误以为“有了 App ID 和 App Secret 就能调接口”。实际上这只说明你有一个应用身份，不代表这个应用已经被允许访问文档，也不代表某个用户已经把自己的权限授权给它。

1. 应用权限

如果只是验证飞书文档读写，最小范围可以先围绕文档和云盘能力开权限，比如：

获取云盘根目录或文件夹信息
创建云文档
读取云文档信息
读取云文档块
创建和更新云文档块
搜索云文档

如果后面要写图片、表格、知识库、白板，再按需补对应权限。不要一开始就开一个特别大的权限集合，否则授权页会很吓人，出问题也不好定位。

Feishu-MCP 仓库里也给了导入权限和补齐权限的示意图：

2. OAuth 重定向 URL

如果要用 user 模式，必须配置重定向 URL。feishu-tool 默认监听的是：

http://localhost:3333/callback

这个地址要填到：

飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL

这里有两个注意点：

地址要完全一致，协议、端口、路径都要一致。
改完重定向 URL 后，要发布新版本并通过审批，否则授权时仍然会失败。

3. offline_access

user 模式还需要一个很关键的权限：offline_access。

飞书授权页会显示成：

持续访问已授权的数据：offline_access

我一开始就在这里卡住了，页面提示错误码 20027。这个权限的意思不是“离线访问你的电脑”，而是允许应用拿到 refresh token。没有它，用户 token 过期后就不能自动刷新，长期使用会不断要求重新授权。

所以如果你希望 Codex 稳定读写飞书，而不是每隔一段时间重新走登录授权，offline_access 基本是必须开的。

4. 发布应用版本

飞书开放平台里，权限和安全设置不是改完就立刻生效。新增权限、修改重定向 URL 后，都要发布应用版本。

如果你的企业开启了审批，还要等管理员审批通过。很多“我明明已经配置了，为什么授权还是失败”的问题，最后都是卡在这里。

5. 调试时的 scope validation

feishu-tool 会做权限预检查。调试阶段如果只是想先验证主链路，可以临时加：

FEISHU_SCOPE_VALIDATION=false

但这只能作为调试手段，不应该当成生产绕过方案。正式使用时，应该把实际要用的 API 权限补齐。

七、tenant 模式：能创建，但创建者是机器人

feishu-tool 支持两种认证模式：

feishu-tool config set FEISHU_AUTH_TYPE tenantfeishu-tool config set FEISHU_AUTH_TYPE user

我先试的是 tenant 模式。

tenant 模式用的是应用身份，也就是机器人身份。这个模式适合服务端自动化任务，比如定时同步、后台批处理、机器人代发消息。

我用 tenant 模式创建了一篇测试文档，并成功写入内容。但打开飞书一看，创建者显示的是我的机器人，不是我自己。

这其实是符合预期的：tenant_access_token 代表应用，不代表某个用户。

所以这里得到第一个结论：

🌈

如果你希望文档创建者显示为机器人，用 tenant 模式；如果你希望创建者显示为你本人，用 user 模式。

八、user 模式：创建者显示为本人

为了让创建者显示为我自己，我切到了 user 模式：

feishu-tool config set FEISHU_AUTH_TYPE userfeishu-tool auth

一开始 feishu-tool auth 返回的是未授权：

{"authType":"user","isValid":false,"isExpired":true,"canRefresh":false}

这说明本地还没有用户 token，需要走 OAuth 授权。

触发授权的方式很简单，调用任意需要飞书访问的工具即可：

FEISHU_SCOPE_VALIDATION=false feishu-tool get_feishu_root_folder_info '{}'

工具会打开飞书授权页，并监听本地回调地址。

最终我按前面第六节补齐 OAuth 回调地址、offline_access 和应用发布后，重新走一次授权，feishu-tool auth 才变成有效：

{"authType":"user","isValid":true,"isExpired":false,"canRefresh":true}

到这里，user 模式就真正跑通了。

九、权限预检查和实际权限不是一回事

还有一个很现实的坑：feishu-tool 默认会做 scope validation。

它会检查当前启用模块需要的完整权限。如果权限没开齐，可能会提前报错。比如我只想创建普通 docx 文档，但工具预检查会提示还缺一些表格、白板、知识库相关权限。

实际测试时，普通 docx 创建和写入已经可以成功。为了先验证主链路，我临时关闭了权限预检查：

FEISHU_SCOPE_VALIDATION=false feishu-tool get_feishu_root_folder_info '{}'

这不是说权限可以乱配，而是说：

调试阶段可以先绕过预检查，验证真实 API 能否调用。
正式使用时，应该按实际功能补齐权限。
不要一上来就开 all，否则权限问题更难定位。

十、真实跑通的命令

下面这些命令是我联调阶段的真实用法，所以带了 FEISHU_SCOPE_VALIDATION=false。正式长期使用时，更推荐补齐实际权限后去掉这个环境变量。

user 授权成功后，我先获取根云盘信息：

FEISHU_SCOPE_VALIDATION=false feishu-tool get_feishu_root_folder_info '{}'

返回里可以看到根目录 token：

{"root_folder":{"token":"..."}}

然后创建文档：

FEISHU_SCOPE_VALIDATION=false feishu-tool create_feishu_document '{  "title": "Codex 飞书 user 模式联调测试文档",  "folderToken": "<root-folder-token>"}'

返回文档 ID：

{"document":{"document_id":"...","revision_id":1,"title":"Codex 飞书 user 模式联调测试文档"}}

再写入正文块：

FEISHU_SCOPE_VALIDATION=false feishu-tool batch_create_feishu_blocks '{  "documentId": "<document-id>",  "parentBlockId": "<document-id>",  "index": 0,  "blocks": [    {      "blockType": "heading",      "options": {        "heading": {          "level": 1,          "content": "Codex user 模式联调测试"        }      }    },    {      "blockType": "text",      "options": {        "text": {          "textStyles": [            {              "text": "这篇文档由 Codex 通过 feishu-tool 的 user 模式创建。"            }          ]        }      }    }  ]}'

写入成功后会返回：

{"totalBlocksCreated":2,"document_revision_id":2}

最后读取文档块结构确认内容：

FEISHU_SCOPE_VALIDATION=false feishu-tool get_feishu_document_blocks '{  "documentId": "<document-id>"}'

这个过程确认了三件事：

feishu-tool 可以通过 user token 访问我的飞书云盘。
Codex 可以通过 CLI 创建飞书文档。
Codex 可以批量写入飞书文档块。

十一、让 Codex 学会稳定调用工具

跑通 CLI 之后，下一步就是让 Codex 稳定使用它，而不是每次靠临时提示词猜。

这里 Feishu-Skill 的作用就体现出来了。它在 SKILL.md 里规定了执行流程：

先检查 feishu-tool --help
再检查 feishu-tool config
user 模式下检查 feishu-tool auth
根据工具类型读取参考文档
用 feishu-tool <tool-name> '<json-params>' 调用

文档工具会读：

reference/document.md

任务工具会读：

reference/task.md

用户工具会读：

reference/member.md

也就是说，我不需要每次告诉 Codex “创建文档的参数是什么”。它应该先查 skill，再决定怎么调用。

这就是 skill 的价值：把经验和规则固化下来，让 Agent 的工具调用从“临场发挥”变成“可重复流程”。

十二、飞书文档不是 Markdown，而是 block

接入过程中还有一个重要认知：飞书文档不是一个 Markdown 文件。

飞书文档底层是块结构：

标题是 heading block
正文是 text block
代码是 code block
表格是 table block
图片是 image block
白板是 whiteboard block

所以修改文档时，不应该简单理解为“覆盖全文”。更稳妥的方式是：

先调用 get_feishu_document_blocks
找到目标 block id
再用 batch_update_feishu_block_text 更新指定块

新增内容时，也要明确 parentBlockId 和 index：

根级写入时，parentBlockId = documentId

这点和传统 Markdown 文件编辑不一样，需要在 skill 里明确约束。

十三、我现在能怎么用

现在我可以直接对 Codex 说：

写一篇教程发到飞书上。

Codex 会做这些事：

检查当前是不是 user 模式
检查 user token 是否有效
获取根云盘 folder token
创建新飞书文档
批量写入标题、正文、代码块
读取文档信息确认写入成功
返回飞书链接

这次我就用这个链路创建了一篇教程文档，确认文档创建、内容写入和读取校验都成功。

再进一步，还可以做这些场景：

把一次技术调研整理成飞书文档
把 CR 结论整理成团队知识沉淀
把接口设计说明写成规范文档
从飞书文档读取需求，再回到代码仓库实现
实现后把变更说明写回飞书

这才是 Agent 真正进入工作流的开始。

十四、边界：这还不是“在飞书里指挥 Codex”

这里要说清楚一个边界。

现在跑通的是：

在 Codex 里操作飞书

还不是：

在飞书里直接指挥 Codex

如果想在飞书群里 @机器人，然后让 Codex 自动执行任务，还需要再做一层 bridge：

飞书机器人消息  ↓事件订阅 / Webhook  ↓本地或服务器上的 bridge 服务  ↓Codex CLI / OpenAI API / Agent Worker  ↓执行结果回写飞书

这会涉及消息事件权限、回调验签、用户白名单、危险操作确认、长任务状态回传等问题。

所以本次先解决第一步：让 Codex 能稳定读写飞书文档。等这个链路稳定后，再考虑“飞书指挥 Codex”的机器人入口。

十五、安全建议

把 Codex 接入飞书之后，它就具备了读写协作文档的能力，安全边界必须提前想清楚。

我的建议是：

不要把 App Secret 写进代码仓库
不要把本地 ~/.cache/feishu-mcp/.env 提交到任何项目
先只启用 document 模块，任务、成员后续按需开启
先在测试文档或测试文件夹验证
修改已有重要文档前，让 Codex 先输出变更计划
删除块、批量更新这类操作要二次确认
user 模式 token 等同于用户授权能力，要保护好本机环境

这里特别要注意：一旦 user 模式授权成功，Codex 不是“只能写测试文档”。只要权限允许，它可以读取和修改你有权限访问的文档。所以授权范围和操作流程要谨慎设计。

结语

这次把 Codex 和飞书文档打通之后，我最大的感受是：Agent 的价值不只在模型能力，而在它能不能接入真实工具。

只会回答问题的 AI，还是一个聊天窗口。

能读代码、跑命令、查数据库、读文档、写回知识库的 AI，才更接近一个可以协作的工作伙伴。

这次验证之后，Codex 已经不只是“帮我改代码”的工具了。它开始能把产出写回团队协作系统，进入真实工作流。

下一步，我更想尝试的是飞书机器人入口：让我在飞书里发一条消息，就能触发一个受控的 Codex 任务。那时就不只是“Codex 操作飞书”，而是“飞书成为 Agent 的工作入口”。