1. 为什么你的 AI 助手读不了飞书云文档很多人第一次尝试让 AI 助手操作飞书云文档时都会卡在同一个地方助手能聊天、能写代码但一让它「帮我搜一下上周的项目总结文档」它就开始胡言乱语或者干脆报一个missing_scope的错。这不是模型不够聪明而是它手里根本没有一把能打开飞书云文档的钥匙。飞书云文档docx、wiki、知识库、多维表格是一套有严格权限体系的云端服务。任何外部程序想读写它都必须先通过飞书开放平台完成身份认证拿到 access token再按权限范围去调用接口。OpenClaw 作为你的 AI 助手运行框架本身并不内置飞书能力它需要一个「执行器」——lark-cli 就是飞书官方提供的命令行工具专门负责把「搜索文档」「创建文档」「写入段落」这些动作翻译成飞书能听懂的 API 请求。所以整条链路是这样的你在 OpenClaw 里用自然语言下指令OpenClaw 调用 lark-clilark-cli 带着凭证去请求飞书开放平台飞书返回结果再一路回传给你。这条链路里最容易出问题的环节就是凭证配置和权限授权。我见过太多人卡在lark-cli doctor显示token_exists fail或者docs search报missing_scope本质上都是授权没走完。这篇教程要解决的就是这个问题。我会带你从零走完飞书自建应用创建、lark-cli 安装配置、用户扫码授权、OpenClaw 集成调用、读写验证的完整流程每一步都给可复制的命令和配置片段。同时我会在凭证管理环节提到 TaoToken 作为统一 Key/API 通道的用法帮你把多个 AI 服务的密钥收拢到一处减少来回切换的麻烦。适合谁看正在用 OpenClaw 或类似 Agent 框架、想让 AI 真正动手操作飞书文档、又不想在权限配置上反复踩坑的人。2. 前置准备飞书应用凭证与 lark-cli 环境在动手写配置之前先把两样东西准备好飞书自建应用的凭证以及一个能跑 lark-cli 的本地或服务器环境。这一步看起来简单但凭证拿错、环境缺依赖后面会连环报错。2.1 创建飞书自建应用并拿到 App ID / App Secret打开飞书开放平台登录你的飞书账号进入开发者后台。点击「创建应用」选择「自建应用」填一个你记得住的名字比如「我的AI文档助手」描述随便写。创建完成后左侧菜单点「凭证与基础信息」你会看到两个关键值App ID形如cli_xxxxxxxxxxxxxxxx公开的用来标识你的应用。App Secret需要点「查看」才显示完整这是敏感信息泄露了别人就能冒充你的应用调接口。把这两个值复制到一个安全的地方。注意App Secret 只在创建时和手动查看时可见关掉页面后如果没保存就得重新生成。2.2 开通云文档相关权限还是在开发者后台左侧点「权限管理」搜索并开通下面这几个权限。权限名称和 scope 标识要对应上否则后面授权时会报missing_scope权限名称scope 标识用途查看、评论和导出云文档docx:document:readonly读取文档内容创建和编辑云文档docx:document:write写入段落、标题、列表获取文件元信息drive:drive:readonly搜索、列出文件管理云空间中所有文件drive:folder:write创建文件夹、移动文件搜索云文档search:docs:read按关键词搜索文档开通后需要「申请发版」或联系企业管理员审批。个人版飞书通常可以自助通过企业版可能需要管理员点一下。审批通过前部分接口会返回权限不足这是正常的。2.3 开启机器人能力左侧菜单点「应用能力」→「机器人」把开关打开。这一步是为了让应用具备消息收发能力后面如果你想让 AI 把生成的文档链接发到群里会用到这个能力。2.4 安装 lark-clilark-cli 是 Node.js 包先确认你的环境有 Node.js 16 以上版本node -v npm -v然后全局安装npm install -g larksuite/cli安装完成后验证lark-cli --version如果提示command not found检查 npm 全局 bin 目录是否在 PATH 里。Linux/macOS 一般是/usr/local/bin或~/.npm-global/binWindows 是%APPDATA%\npm。2.5 用 TaoToken 统一管理你的 AI 服务密钥在配置 OpenClaw 的过程中你可能会同时用到多个模型的 API Key。如果每个都散落在不同的配置文件里改起来很烦。TaoToken 提供统一 Key/API 通道你可以把模型调用集中到一处管理。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。在后面的 OpenClaw 配置里我会把模型通道和飞书凭证分开处理避免混在一起。3. 可复制配置lark-cli 凭证落地与 OpenClaw 接入这一节是整篇的核心。我会给出 lark-cli 的配置命令、配置文件结构以及 OpenClaw 侧如何声明这个工具。所有片段都可以直接复制路径和字段名保持和官方一致。3.1 lark-cli 交互式配置最省事的方式是交互式配置它会一步步问你 App ID 和 App Secretlark-cli config init --new按提示输入 App ID然后粘贴 App Secret。品牌选feishu如果你用的是国际版 Lark选lark。配置完成后lark-cli 会把凭证写到本地配置目录Linux/macOS 通常在~/.config/lark-cli/config.jsonWindows 在%APPDATA%\lark-cli\config.json。3.2 非交互式配置适合脚本和 Docker如果你在 Docker 或 CI 环境里交互式没法用改用非交互式echo 你的AppSecret | lark-cli config init \ --app-id cli_xxxxxxxxxxxxxxxx \ --app-secret-stdin \ --brand feishu注意--app-secret-stdin表示从标准输入读 Secret不要把 Secret 直接写在命令行参数里否则会留在 shell history 中。3.3 配置文件结构参考配置完成后config.json大致长这样{ app_id: cli_xxxxxxxxxxxxxxxx, app_secret: ************************, brand: feishu, default_as: user, token_store: file }default_as设为user表示默认以用户身份调用这样能访问你个人有权限的文档。token_store设为file是为了兼容 Docker 环境因为容器里通常没有系统 keychain。3.4 验证凭证是否落地lark-cli doctor正常输出会显示app_id、app_secret、token_exists等状态。如果token_exists是fail说明还没做用户授权继续下一节。如果app_secret显示invalid回去检查 Secret 是否复制完整。3.5 OpenClaw 侧声明 lark-cli 工具OpenClaw 通过工具声明来调用外部命令。你需要在 OpenClaw 的配置里加一个 shell 工具指向 lark-cli。以常见的 TOML 配置为例[[tools]] name lark command lark-cli description 飞书云文档操作工具支持搜索、创建、读写文档 args_template [{{subcommand}}, {{args}}] timeout 30如果你用的是 JSON 配置{ tools: [ { name: lark, command: lark-cli, description: 飞书云文档操作工具支持搜索、创建、读写文档, args_template: [{{subcommand}}, {{args}}], timeout: 30 } ] }这样 OpenClaw 在需要操作飞书时就会拼出lark-cli docs search --query ...这样的命令去执行。3.6 模型通道配置可选用 TaoToken 统一 Key如果你希望 OpenClaw 的模型调用也走统一通道可以在 OpenClaw 的模型配置里填 TaoToken 的 API 地址和 Key{ model_providers: [ { name: taotoken, base_url: https://taotoken.net/api, api_key: 你的TaoToken Key, model_id: claude-sonnet-4-20250514 } ] }这里 Base URL、Key、Model ID 三件套要写全缺一个都会导致请求失败。TaoToken 的 Key 在控制台的 API Keys 页面生成具体入口可以走 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4. 用户授权与读写验证让 AI 真正动起来凭证配置好只是第一步飞书的用户级接口需要 OAuth 授权也就是你要用飞书 App 扫码确认一次。这一步做完AI 才能以你的身份读写文档。4.1 发起设备授权lark-cli auth login --no-wait --recommend --json这条命令会返回一段 JSON里面有verification_url和device_code。把verification_url复制到浏览器打开用手机飞书 App 扫码确认。注意手机和浏览器要登录同一个飞书账号。4.2 完成登录扫码确认后回到命令行用拿到的 device_code 完成登录lark-cli auth login --device-code 你获取到的device_code如果提示授权过期重新执行上一步拿新的链接device_code 有效期通常是 10 分钟。4.3 补充搜索权限--recommend只包含常用权限搜索文档需要单独补lark-cli auth login --no-wait --scope search:docs:read --json同样扫码确认再用新的 device_code 完成登录。这一步不做的话docs search会报missing_scope。4.4 验证读取能力lark-cli docs search --query 项目总结 --as user如果返回一个文档列表说明读取和搜索都通了。如果返回空列表可能是你的账号下确实没有匹配文档换个关键词试试。4.5 验证创建与写入能力lark-cli docs create --title 测试文档 --markdown # 你好 这是一段由 lark-cli 创建的测试内容。执行成功会返回新文档的 URL 和 document_id。打开链接你应该能看到标题和正文都写进去了。这一步验证的是docx:document:write权限。4.6 验证日历能力lark-cli calendar agenda --as user返回你今天的日程列表说明日历权限也通了。到这一步lark-cli 的完整能力基本可用。4.7 在 OpenClaw 里下自然语言指令回到 OpenClaw直接说帮我搜一下关于「项目总结」的飞书文档把标题列出来。OpenClaw 会调用lark-cli docs search --query 项目总结 --as user把结果整理后返回给你。再试把这段会议纪要写成飞书文档标题叫「周三产品会纪要」。OpenClaw 会调用lark-cli docs create把内容写进去并返回文档链接。到这里你的 AI 助手就真正具备了读写飞书云文档的能力。5. 常见报错排查401、missing_scope、token_exists fail配置过程中最容易遇到的就是下面这几类报错。我按实际出现的频率排一下每条给出原因和解决动作。5.1token_exists fail或unauthorized这是最常见的。lark-cli doctor显示token_exists fail说明你还没做用户授权或者 token 过期了。解决方式就是重新走一遍第 4.1 到 4.2 的授权流程。token 默认有效期有限过期后 AI 会提示「需要主人授权」你重新扫码即可通常 10 秒搞定。5.2missing_scope或permission denieddocs search报missing_scope说明搜索权限没授权。执行lark-cli auth login --no-wait --scope search:docs:read --json扫码后再用 device_code 完成登录。如果是docx:document:write缺失把 scope 换成对应的标识再授权一次。注意权限要在开发者后台先开通再走用户授权两步缺一不可。5.3invalid_client或app_secret invalid这个报错说明 App Secret 不对。回去开发者后台「凭证与基础信息」重新查看并复制注意不要漏掉字符。如果应用还没发版审批通过部分接口也会返回类似错误先确认应用状态是「已发布」。5.4local proxy failed或连接超时如果你在 OpenClaw 里看到local proxy failed通常是网络层的问题不是飞书凭证的问题。检查你的服务器能否正常访问飞书开放平台域名以及 OpenClaw 的工具超时设置是否太短。把timeout从 30 调到 60 试试。5.5reading choices或模型返回格式错误这个报错一般出现在模型通道配置上比如 Base URL 或 Model ID 写错。检查你的base_url是否以/api结尾model_id是否和通道支持的模型名一致。如果你用 TaoToken 统一通道Base URL 填https://taotoken.net/apiKey 和 Model ID 三件套要完整。5.6 Docker 环境 keychain 不可用容器里没有系统 keychainlark-cli 会报存储失败。解决方式是在配置里把token_store设为file或者重新运行lark-cli config init它会自动降级到文件存储。5.7 授权链接打不开或扫码无反应确保手机装了飞书 App且和浏览器登录的是同一个账号。如果链接过期重新执行lark-cli auth login --no-wait --recommend --json拿新链接。企业版账号如果被管理员限制了第三方应用授权需要联系管理员放开。6. 懒人方式与长期使用建议如果你不想一步步敲命令可以把整个流程交给 AI 助手自己跑。核心原则是你只做两件事——提供 App ID / App Secret以及扫码授权其他安装、配置、验证、轮询全部由 AI 完成。把下面这段提示词复制发给你的 OpenClaw 助手帮我配置飞书云文档能力。请按以下步骤做 1. 安装 lark-clinpm install -g larksuite/cli 2. 运行 lark-cli doctor 检查当前状态 3. 如果缺少凭证问我 App ID 和 App Secret 4. 拿到凭证后执行 lark-cli config init 完成配置 5. 运行 lark-cli auth login --no-wait --recommend --json 把 verification_url 发给我扫码 6. 我扫码后用 device_code 执行 lark-cli auth login --device-code device_code 7. 补充搜索权限lark-cli auth login --no-wait --scope search:docs:read --json 8. 用以下命令验证并告诉我结果 - lark-cli docs search --query 文档 --as user - lark-cli docs create --title 测试文档 --markdown # 你好 - lark-cli calendar agenda --as user长期使用有几个建议。第一App Secret 不要硬编码在脚本里用环境变量或配置文件并且把配置文件权限设为仅本人可读。第二token 会过期AI 提示「需要主人授权」时不要慌重新扫码就行。第三如果你同时用多个 AI 服务把模型 Key 收拢到 TaoToken 统一通道减少配置文件散落。第四定期跑一次lark-cli doctor确认凭证和 token 状态正常。如果你想让 AI 在编码和 Agent 场景里长期稳定运行可以考虑 TaoToken 的 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。模型对话验证可以走 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把这些入口记下来下次配置新环境时能省不少找链接的时间。