# Feishu Codex Bridge

> Run local Codex CLI from Feishu/Lark chat with sessions, attachments, and background service support

- Skill: `aradotso/feishu-codex-bridge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aradotso/feishu-codex-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aradotso/feishu-codex-bridge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aradotso (https://skillmd.com/u/aradotso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aradotso/feishu-codex-bridge

---


# Feishu Codex Bridge

> Skill by [ara.so](https://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

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

### First-Time Setup

```bash
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:
```text
/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

```bash
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

```json
{
  "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`:

```json
{
  "preferences": {
    "codexReasoningEffort": "xhigh"
  }
}
```

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

### Access Control

Restrict bot access in `config.json`:

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

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

## Chat Commands

### Status and Control

```text
/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

```text
/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

```text
/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:
```text
/cd ~/projects/api-server
/ws save api-server
/cd ~/projects/frontend
/ws save frontend
/ws list
/ws use api-server
```

### Configuration

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

## Background Service

### Install and Manage (macOS launchd)

```bash
# 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

```bash
# 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):

```bash
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

```bash
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

```bash
npx pnpm@10.20.0 typecheck
npx pnpm@10.20.0 test
```

## Troubleshooting

### Bot is Silent

```bash
# 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

```bash
# 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:

```bash
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:

```bash
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

```text
# 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:

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

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

### Log Analysis

```bash
# 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

```typescript
// 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

```text
# List recent sessions in current directory
/resume

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

### Per-Chat Reasoning Effort

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

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

### Access Control Setup

```json
{
  "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

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

# Codex will analyze recent logs and suggest fixes
```

## Architecture

```text
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