飞书怎么接入 Codex？larksuite/cli 安装与配置指南

飞书接入 Codex 不是填写一个远程 MCP 地址。larksuite/cli 的做法是：在本机安装 lark-cli，再把 lark-doc、lark-sheets、lark-calendar 等 Skills 注册给 Codex。Skill 告诉 Codex 怎样操作，CLI 负责实际调用飞书开放平台。

Codex 需要两样东西

可执行文件

lark-cli 必须能从 PATH 调用。

Agent Skills

Codex 要能发现全局安装的 lark-* 技能目录。

npx @larksuite/cli@latest install
npx skills ls -g

安装结束后重启 Codex。若只从源码装二进制，还要补跑 npx skills add larksuite/cli -y -g，否则 Codex 只看得到命令，看不懂各业务域的调用规则。

重启后先确认技能目录

npx skills ls -g 的列表里应出现 lark-shared、lark-doc、lark-calendar 等名称，并标注 Codex 等已识别的 Agent。若目录存在但当前会话仍不调用，关闭并重新打开 Codex 任务；不要重复安装多份相同 Skill，避免旧版本优先被发现。

配置由用户确认，执行留在本机

1. 运行 lark-cli config init --new 创建或选择飞书应用。
2. 运行 lark-cli auth login --recommend，把授权链接交给本人打开。
3. 用 lark-cli auth status --json --verify 检查身份、token 与 scope。

个人日历、私信、云空间和邮箱通常要用 --as user；机器人通知等应用级操作可用 --as bot。不要为图省事一次授权全部范围，缺哪个业务域再补哪个 scope。权限不足时按错误提示发起增量授权，不必重新创建应用；授权链接与设备码都有时效，过期后重新生成即可。

用只读任务做第一次验收

lark-cli calendar +agenda --as user
lark-cli docs +fetch --doc "<文档URL>"

这两条能成功后，再在 Codex 里说“查看今天日程”或“读取这个飞书文档”。可见的成功标准不是旧式 code == 0，而是 JSON 信封中的 ok == true 或进程退出码 0。正式写入前让 Codex 先做 --dry-run，删除等高风险命令还会要求明确确认。

macOS 沙箱报钥匙串错误怎么办

先退出 Codex 沙箱，在普通 Terminal 中执行 lark-cli config keychain-downgrade，再回到 Codex 重试。该命令把主密钥落到本机文件，换来沙箱可读性，也降低了系统钥匙串的隔离强度；只有确实遇到 Keychain blocked 时再用。接入完成后再做一次 auth status --json --verify，确认当前用户、token 状态和已授予 scope 都与预期一致。