在 Codex App 中使用飞书 CLI（lark-cli）的完整实践指南：权限、配置与稳定调用方法

在企业自动化和开发工具链中，将“AI 执行环境”（如 Codex App）与“办公系统 API”（如飞书 Lark）打通，是一个典型的生产力集成场景。实际落地过程中，开发者经常会遇到一个核心问题：本地 CLI 能正常使用，但在 Codex / Agent 环境中无法稳定执行或频繁出现权限错误。

本文基于真实操作过程，对 lark-cli 在 Codex App 中的使用问题进行系统性拆解，并给出可复用的工程化解决方案。

一、问题背景：为什么“本地能用，Codex 不能用”

在标准 macOS / Linux 终端中，lark-cli 可以正常运行，例如：

lark-cli --version
# lark-cli version 1.0.32

但当同样命令在 Codex App 中执行时，经常出现：

  • not configured
  • permission denied
  • automatic approval timeout
  • network access blocked
  • auth status unavailable

例如：

{
  "ok": false,
  "error": {
    "type": "config",
    "message": "not configured",
    "hint": "run `lark-cli config init --new`"
  }
}

表面看是配置问题，但本质是三层隔离机制叠加导致的。

二、根本原因分析（关键理解点）

1. Codex Sandbox 文件系统隔离

Codex App 使用沙箱执行模型：

  • 不完全继承 ~/.config
  • 不完全继承 ~/.lark-cli
  • HOME 目录可能重映射

因此即使你在系统终端完成登录：

lark-cli auth login

Codex 内仍可能提示：

not configured

原因：配置文件不可见

2. 环境变量继承不完整

常见缺失：

  • PATH（导致找不到 lark-cli）
  • HOME（导致 profile 路径变化）
  • XDG_CONFIG_HOME（影响 token 存储）

验证方式：

echo $HOME
echo $PATH
which lark-cli

如果 Codex 与本地不一致，就会导致 CLI 行为不同。

3. 网络访问默认受限

飞书 CLI 本质是 HTTP API 调用工具：

  • 创建文档
  • 写入 block
  • 读取 docx / wiki

但 Codex 默认 sandbox：

  • 禁止外网
  • 或需要 approval 才允许网络访问

因此出现：

automatic review timeout

或：

network access blocked

4. 命令执行审批机制（Approval Queue）

Codex 在执行以下行为时会进入审批：

  • 写文件
  • 网络请求
  • 外部 CLI 执行
  • API 调用

当审批未完成或超时，会出现：

自动审核超时

这不是 CLI 错误，而是执行层拦截。

三、正确的配置流程（工程化标准做法）

Step 1：确认 CLI 在 Codex 中可用

在 Codex terminal 执行：

which lark-cli
lark-cli --version

如果失败：

export PATH="/opt/homebrew/bin:$PATH"

Step 2：初始化飞书认证（必须在 Codex 环境中做一次）

lark-cli config init --new

会输出授权 URL，例如：

https://open.feishu.cn/...

在浏览器打开完成授权。

验证：

lark-cli auth status

Step 3：解除网络限制（关键步骤）

在 Codex 中：

/approvals

设置：

Full Access

或至少：

workspace-write + network access enabled

否则飞书 API 无法调用。

Step 4：验证基础 API 调用

lark-cli docs +create \
  --api-version v2 \
  --as user \
  --content '<title>测试文档</title><p></p>'

如果成功，会返回：

{
  "data": {
    "document": {
      "document_id": "doccnxxxx"
    }
  }
}

四、稳定性问题优化方案（关键实践）

方案 1：使用 wrapper 脚本（推荐）

直接封装 CLI，避免 Codex 误判复杂命令。

mkdir -p ~/.local/bin

cat > ~/.local/bin/feishu-doc <<'EOF'
#!/usr/bin/env bash
TITLE="${1:-测试}"

lark-cli docs +create \
  --api-version v2 \
  --as user \
  --content "<title>${TITLE}</title><p></p>"
EOF

chmod +x ~/.local/bin/feishu-doc

使用方式：

feishu-doc "日报"

优势：

  • 避免 HTML/JSON 转义错误
  • 降低 approval 触发概率
  • 提高 Codex 可执行性

方案 2：避免长命令直接执行

在 Codex 中不要直接运行：

lark-cli docs +create --content '<xml>'

原因：

  • 容易触发安全审查
  • 容易 timeout
  • 容易解析失败

推荐：

  • wrapper script
  • 或拆分 API 调用

方案 3：使用 API 模式（更稳定）

lark-cli api POST /open-apis/docx/v1/documents \
  --data '{"title":"测试文档"}'

优点：

  • 更低 CLI 层依赖
  • 更稳定 JSON 结构
  • 更容易 debug

五、Codex + 飞书 CLI 的推荐架构

推荐结构：

Codex App
   ↓
wrapper scripts（稳定层）
   ↓
lark-cli（API封装层）
   ↓
飞书 OpenAPI

不要直接：

Codex → lark-cli → API

而是：

Codex → wrapper → lark-cli → API

六、常见问题 FAQ

Q1：为什么本地正常，Codex 报 not configured？

因为 Codex sandbox 不共享：

  • ~/.config
  • keychain
  • profile 文件

Q2：为什么会自动审核超时？

因为：

  • 网络请求未被批准
  • CLI 写操作被阻断
  • sandbox 未释放执行权限

Q3：是否必须 Full Access？

不一定，但必须满足：

  • network access enabled
  • workspace-write
  • CLI execution allowed

否则飞书 API 不可用。

Q4：最佳实践是什么？

推荐三层策略：

  1. 初始化 config（一次）
  2. wrapper script（长期）
  3. Codex 仅调用封装命令

七、结论

在 Codex App 中使用 lark-cli 的核心不是“命令是否正确”，而是三个系统层的协调：

  • sandbox 文件系统
  • 网络权限控制
  • 命令审批机制

只要这三层没有打通，即使 CLI 本身完全正确，也无法稳定执行。

工程上最可靠的方案是：

不让 Codex 直接调用复杂 CLI，而是通过稳定 wrapper 层统一封装所有飞书操作。

这可以显著降低失败率，并提高可维护性。

如果你下一步要做的是“让 Codex 自动写飞书日报 / 自动生成文档 / 自动通知 IM”，可以继续扩展成一套标准 agent 工作流。