Using Feishu CLI (lark-cli) Inside Codex App: A Practical Guide to Permissions, Sandbox Limits, and Stable Integration

Integrating AI execution environments (such as Codex App) with enterprise productivity platforms (such as Feishu / Lark) is a common requirement in modern automation workflows. In practice, however, developers often encounter a recurring issue:

A CLI tool works perfectly in a local terminal but fails, becomes unstable, or loses authentication inside Codex App.

This article explains the real technical causes behind these issues when using lark-cli in Codex, and provides a structured, production-ready approach to make the integration reliable.

The content is based on real execution scenarios involving Feishu document creation, sandbox restrictions, approval timeouts, and network permission constraints.

1. Problem Overview: Why lark-cli Works Locally but Fails in Codex

In a standard macOS or Linux terminal, lark-cli typically works without issues:

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

However, when the same command is executed inside Codex App, common errors appear:

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

Example error response:

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

At first glance, this looks like a configuration issue. In reality, it is caused by environment isolation inside Codex sandbox execution.

2. Root Cause Analysis

2.1 Sandbox File System Isolation

Codex App executes commands inside a sandboxed environment. This means:

  • User home directory may be remapped
  • ~/.config may not be accessible
  • lark-cli profile storage may not exist in Codex runtime

Even if authentication is completed locally:

lark-cli auth login

Codex may still report:

not configured

Because the configuration file is not visible inside the sandbox.

2.2 Incomplete Environment Variable Inheritance

Codex may not fully inherit the host environment, including:

  • PATH
  • HOME
  • XDG_CONFIG_HOME

This leads to two types of issues:

  1. CLI not found
  2. CLI found but using a different configuration path

Verification commands:

echo $HOME
echo $PATH
which lark-cli

If values differ between local terminal and Codex, execution behavior will diverge.

2.3 Network Access Restrictions

Feishu CLI relies on HTTP API calls for:

  • Creating documents
  • Writing blocks
  • Accessing Drive / Wiki resources

However, Codex sandbox often:

  • Blocks outbound network access by default
  • Requires explicit approval for API calls

This leads to errors such as:

automatic review timeout

or:

network access blocked

2.4 Command Approval Queue (Execution Guardrails)

Codex includes a safety mechanism that intercepts certain operations:

  • External API calls
  • File writes
  • System-level command execution

When approval is delayed or not granted, execution fails with:

automatic approval timeout

This is not a CLI failure—it is a sandbox execution constraint.

3. Correct Setup Workflow for lark-cli in Codex

Step 1: Verify CLI Availability Inside Codex

Run inside Codex terminal:

which lark-cli
lark-cli --version

If not found, adjust PATH:

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

Step 2: Initialize Authentication Inside Codex

Authentication must be performed within the Codex runtime:

lark-cli config init --new

This returns an authorization URL:

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

Open it in a browser and complete login.

Then verify:

lark-cli auth status

Step 3: Enable Network Access

Inside Codex, open approval settings:

/approvals

Set execution mode to:

Full Access

or at minimum:

  • workspace-write
  • network access enabled

Without network access, Feishu API calls cannot succeed.

Step 4: Validate Document Creation

Run a test command:

lark-cli docs +create \
  --api-version v2 \
  --as user \
  --content '<title>Test Document</title><p></p>'

Successful response:

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

4. Stability Improvements for Production Use

4.1 Use Wrapper Scripts (Recommended)

Direct CLI execution inside Codex is fragile. A wrapper script improves reliability.

mkdir -p ~/.local/bin

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

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

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

Usage:

feishu-doc "Daily Report"

Benefits:

  • Avoids JSON/HTML escaping issues
  • Reduces approval triggers
  • Simplifies Codex execution logic

4.2 Avoid Complex Inline Commands

Avoid executing long CLI commands directly in Codex, such as:

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

Issues include:

  • Higher chance of sandbox rejection
  • Parsing errors
  • Approval timeout delays

4.3 Prefer API Mode for Reliability

An alternative is using the generic API interface:

lark-cli api POST /open-apis/docx/v1/documents \
  --data '{"title":"Test Document"}'

Advantages:

  • More explicit request structure
  • Easier debugging
  • Reduced CLI abstraction complexity

5. Recommended Architecture

A stable integration pattern looks like this:

Codex App
   ↓
Wrapper Script Layer
   ↓
lark-cli (API abstraction layer)
   ↓
Feishu OpenAPI

Avoid direct coupling:

Codex → lark-cli → Feishu API

Instead use:

Codex → wrapper → lark-cli → Feishu API

This reduces failure points significantly.

6. Frequently Asked Questions (FAQ)

Why does lark-cli work locally but not in Codex?

Because Codex uses a sandboxed environment that does not share:

  • configuration files (~/.config)
  • authentication tokens
  • system environment variables

Why do I see “automatic approval timeout”?

This happens when:

  • network access is not approved
  • sandbox execution is blocked
  • CLI command requires external API access

Do I always need Full Access mode?

Not always, but you must ensure:

  • network access is enabled
  • command execution is permitted
  • workspace write access is available

Without these, Feishu API calls will fail.

What is the most stable way to use lark-cli in Codex?

The recommended approach is:

  1. Initialize authentication once inside Codex
  2. Enable network access via approvals
  3. Use wrapper scripts for all Feishu operations
  4. Avoid direct complex CLI commands

7. Conclusion

The challenges of using lark-cli inside Codex App are not caused by the CLI itself, but by the execution environment.

Three key constraints define behavior:

  • sandbox file system isolation
  • network access restrictions
  • command approval mechanisms

Once these are properly configured, Feishu CLI can be reliably used for:

  • document creation
  • automated reporting
  • messaging workflows
  • enterprise automation pipelines

For production usage, the most stable pattern is to avoid direct CLI invocation and instead introduce a wrapper layer that standardizes all Feishu operations.

This architecture significantly improves reliability, maintainability, and execution consistency in AI-driven automation environments.