feishu-codex-bridge

Feishu Codex Bridge

Skill by ara.so — Codex Skills collection.

A local bridge that connects Feishu/Lark chat to your local Codex CLI. Send messages in Feishu/Lark and the bridge runs codex exec on your machine, streaming results back to chat with session persistence, file attachments, and background service support.

What It Does

• Chat-to-CLI Bridge: Converts Feishu/Lark messages into local codex exec commands
• Session Management: Maps each chat/topic to a persistent Codex session
• Attachment Support: Downloads images and files for Codex to process
• Workspace Management: Switch between named project directories
• Background Service: Runs as a macOS launchd service
• Access Control: Allowlist users, chats, and admin commands
• Lark-CLI Integration: Gives Codex API access to Lark messages, docs, calendars

Installation

Global NPM Install

npm i -g feishu-codex-bridge
feishu-codex-bridge --version

First-Time Setup

feishu-codex-bridge start

This interactive setup will:

1. Find or install Codex CLI (@openai/codex)
2. Check codex login status and prompt if needed
3. Show a QR code for Feishu/Lark app creation
4. Create PersonalAgent app and save config
5. Install and initialize lark-cli with the same App ID
6. Start listening for chat events

After setup, test in Feishu/Lark DM:

/status
Help me inspect this repo

Requirements

• Node.js >= 20
• Network access to npm, OpenAI/Codex, and Feishu/Lark platform
• Terminal for QR scan and login prompts

Custom Codex Binary

export CODEX_BIN="/path/to/codex"

Bridge checks these locations in order:

1. $CODEX_BIN
2. codex in $PATH
3. ~/.feishu-codex-bridge/codex-cli
4. /Applications/Codex.app/Contents/Resources/codex (macOS)

Configuration

Directory Structure

~/.feishu-codex-bridge/
├── config.json              # App config and preferences
├── secrets.enc              # Encrypted App Secret store
├── sessions.json            # Chat-to-session mapping
├── workspaces.json          # Named workspaces
├── processes.json           # Live process registry
├── service.log              # Service stdout
├── service.err.log          # Service stderr
├── logs/YYYY-MM-DD.log      # Daily structured logs
├── media/<chatId>/          # Downloaded attachments (24h TTL)
├── codex-cli/               # Private Codex CLI install
└── lark-cli/                # Private Lark CLI install

config.json Structure

{
  "appId": "cli_a1234567890abcde",
  "tenant": "feishu",
  "preferences": {
    "codexReasoningEffort": "high",
    "timeout": 300,
    "replyMode": "stream",
    "allowedUsers": [],
    "allowedChats": [],
    "admins": []
  }
}

Reasoning Effort

Set globally in config.json or per-chat via /config:

{
  "preferences": {
    "codexReasoningEffort": "xhigh"
  }
}

Values: minimal, low, medium, high, xhigh. Omit to inherit from ~/.codex/config.toml.

Access Control

Restrict bot access in config.json:

{
  "preferences": {
    "allowedUsers": ["ou_1234567890abcdef"],
    "allowedChats": ["oc_9876543210fedcba"],
    "admins": ["ou_1234567890abcdef"]
  }
}

Find IDs from logs:

grep '"event":"enter"' ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log | tail -5

Chat Commands

Status and Control

/status                      # Show cwd, session, agent, reasoning effort
/help                        # Show help card with all commands
/stop                        # Stop current Codex run
/reconnect                   # Reconnect WebSocket
/ps                          # List bridge processes
/exit <id|#>                 # Stop a bridge process (admin)
/doctor [description]        # Diagnose bridge issues with Codex

Session Management

/new                         # Reset current chat's session
/reset                       # Alias for /new
/resume [N]                  # List and resume recent sessions in cwd
/timeout [N|off|default]     # Set idle timeout for current session

Workspace Management

/cd <path>                   # Change working directory (resets session)
/ws list                     # List named workspaces
/ws save <name> [path]       # Save workspace (defaults to current cwd)
/ws use <name>               # Switch to workspace
/ws remove <name>            # Delete workspace

Example workspace workflow:

/cd ~/projects/api-server
/ws save api-server
/cd ~/projects/frontend
/ws save frontend
/ws list
/ws use api-server

Configuration

/config                      # Open interactive config menu
/account                     # View or change Feishu/Lark app (admin)

Background Service

Install and Manage (macOS launchd)

# Complete foreground setup first
feishu-codex-bridge start
# Test with /status in chat, then Ctrl+C

# Install service
feishu-codex-bridge service install launchd

# Check status
feishu-codex-bridge service status

# View logs
feishu-codex-bridge service logs --follow

# Restart
feishu-codex-bridge service restart

# Uninstall
feishu-codex-bridge service uninstall

Service Logs

# Stdout
tail -f ~/.feishu-codex-bridge/service.log

# Stderr
tail -f ~/.feishu-codex-bridge/service.err.log

# Structured daily logs
tail -f ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log

Platform Configuration

After QR setup, configure in Feishu/Lark Developer Console:

Required Permission Scopes

• im:message
• im:message:send_as_bot
• im:resource
• im:chat (for group creation)
• drive:drive (for cloud-doc comments)

Event Subscriptions (Long-Connection Mode)

• im.message.receive_v1
• card.action.trigger
• drive.notice.comment_add_v1 (for @bot in docs)
• im.message.reaction.created_v1 (optional)
• im.message.reaction.deleted_v1 (optional)
• im.chat.member.bot.added_v1 (optional)

Important: Bridge and lark-cli must use the same App ID. Do not run lark-cli config init --new after bridge setup.

User OAuth

Required only for accessing personal resources (user's docs, calendar, chat history):

export PATH="$HOME/.feishu-codex-bridge/lark-cli/node_modules/.bin:$PATH"
lark-cli auth login --recommend

Bot identity works for tenant/bot APIs. User OAuth needed for personal resource access.

Development

From Source

git clone https://github.com/QQQingyu/feishu-codex-bridge.git
cd feishu-codex-bridge
npx pnpm@10.20.0 install
npx pnpm@10.20.0 build
node bin/feishu-codex-bridge.mjs --help

Type Checking and Tests

npx pnpm@10.20.0 typecheck
npx pnpm@10.20.0 test

Troubleshooting

Bot is Silent

# Check process state
feishu-codex-bridge ps
feishu-codex-bridge service status

# Follow logs
feishu-codex-bridge service logs --follow

# Check today's structured logs
tail -f ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log

If process is running but bot doesn't respond, verify:

• Permission scopes in Developer Console
• Event subscriptions are enabled
• Long-connection mode is active

Codex CLI Issues

# Auto-diagnose
feishu-codex-bridge doctor

# Rerun setup
feishu-codex-bridge start

Common fixes:

• Codex not in PATH: Bridge auto-installs to ~/.feishu-codex-bridge/codex-cli
• Not logged in: Setup prompts for codex login
• App mismatch: Ensure bridge and lark-cli use same App ID

Lark CLI Path Issues

Add to shell profile for direct terminal usage:

export PATH="$HOME/.feishu-codex-bridge/lark-cli/node_modules/.bin:$PATH"

For Codex runs, bridge handles PATH automatically.

App ID Mismatch

If lark-cli was initialized with a different app:

feishu-codex-bridge start
# Follow prompt to switch lark-cli back to bridge app

Never run lark-cli config init --new after bridge setup.

Hanging Codex Runs

# In chat:
/stop

# Set idle timeout globally
/config
# Or for current session only:
/timeout 10

Process Conflicts

Only one bridge instance per Feishu/Lark app. Stop foreground before installing service:

# Stop all bridge processes
feishu-codex-bridge ps
feishu-codex-bridge exit <id>

# Or kill directly
pkill -f feishu-codex-bridge

Log Analysis

# Recent events
grep '"event":"enter"' ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log | tail -10

# Errors
grep '"level":"error"' ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log | tail -10

# Specific chat
grep '"chatId":"oc_..."' ~/.feishu-codex-bridge/logs/$(date +%Y-%m-%d).log

Common Patterns

Multi-Project Workspace Setup

// Save workspaces for quick switching
/cd ~/work/backend-api
/ws save backend
/cd ~/work/frontend-app
/ws save frontend
/cd ~/work/docs
/ws save docs

// Switch between projects
/ws use backend
Help me add rate limiting to the auth endpoint

/ws use frontend
Update the login form to show better errors

/ws use docs
Generate API docs from the OpenAPI spec

Session Resume After Restart

# List recent sessions in current directory
/resume

# Resume specific session (shows last 10)
/resume 3

Per-Chat Reasoning Effort

# High effort for complex refactoring
/config
# Select "Reasoning Effort" > "xhigh"

# In different chat, use default
/config
# Select "Reasoning Effort" > "default"

Access Control Setup

{
  "preferences": {
    "allowedUsers": [
      "ou_dev_team_member_1",
      "ou_dev_team_member_2"
    ],
    "allowedChats": [
      "oc_dev_team_group"
    ],
    "admins": [
      "ou_dev_team_member_1"
    ]
  }
}

Debugging Bridge Behavior

# In chat:
/doctor The bot isn't responding to file attachments

# Codex will analyze recent logs and suggest fixes

Architecture

Feishu/Lark Chat
  ↓ WebSocket
Bridge Process
  ↓ spawn
codex exec/resume
  ↓ optional
lark-cli API calls
  ↓
Streaming Card Reply

Responsibilities:

• Bridge: Event handling, session mapping, attachment downloads, card rendering, process lifecycle
• Codex CLI: Code reasoning, file editing, command execution, session resume
• Lark CLI: API tool for messages, docs, calendars, groups, OAuth

License

MIT