---
name: codex-feishu-bridge
description: Deploy Codex CLI as a Feishu/Lark chat bot using lark-channel-bridge. Use when the user wants to connect Codex to Feishu, create a Feishu bot that forwards messages to local Codex CLI, patch lark-channel-bridge from Claude Code to Codex, configure macOS launchd background startup, troubleshoot Codex Feishu/Lark bot setup, or ensure the bot does not consume tokens while idle.
---

# Codex Feishu Bridge

## Overview

Use this skill to deploy a local Codex CLI bridge behind a Feishu/Lark bot. The bridge keeps a Feishu WebSocket connection open and only invokes `codex exec` when a message reaches the bot, so idle listening should not consume model tokens.

The bundled script patches `lark-channel-bridge` locally because upstream currently targets Claude Code's `stream-json` protocol. The patch makes the bridge call `codex exec --json` and converts Codex JSONL events into the bridge's internal event stream.

## Prerequisites

Verify these before deployment:

```bash
node -v       # Node.js 20+
npm -v
codex --help # Codex CLI installed and logged in
```

Network access is required for `npm install` and Feishu app registration. On macOS, service installation uses `launchctl` and may require elevated execution approval from the user.

## Deployment Workflow

Run commands from the skill directory, or pass absolute paths to the script.

1. Install and patch the bridge runtime:

```bash
python3 scripts/install_codex_feishu_bridge.py install
```

2. Create the Feishu/Lark app and verify foreground operation:

```bash
python3 scripts/install_codex_feishu_bridge.py run
```

Scan the QR code with Feishu/Lark. After the bridge prints a successful connection line for bot `Codex`, send a private test message to the bot. Stop the foreground process with `Ctrl+C` before installing the background service.

3. Install and start macOS background service:

```bash
python3 scripts/install_codex_feishu_bridge.py service-install
```

4. Check status:

```bash
python3 scripts/install_codex_feishu_bridge.py status
```

## Service Management

Use these commands for an installed macOS service:

```bash
python3 scripts/install_codex_feishu_bridge.py service-stop
python3 scripts/install_codex_feishu_bridge.py service-start
python3 scripts/install_codex_feishu_bridge.py service-uninstall
```

The default service label is `com.<user>.lark-channel-codex`. The default app/runtime directory is `~/.lark-channel-codex`.

## Important Notes

- Do not reuse the same Feishu app for Claude and Codex at the same time; create a separate Codex bot/app.
- Do not run both foreground `run` and the background service simultaneously for the same app.
- Keep Codex CLI on the service `PATH`. The installer writes a LaunchAgent PATH including the directory containing `codex`.
- The patched runtime is local to the target app directory; it does not modify the global `lark-channel-bridge` package.
- If the bridge reports `codex CLI not found`, run `which codex` and reinstall the service so the LaunchAgent environment gets the correct PATH.

## Advanced

Read [references/architecture.md](references/architecture.md) when you need to explain how the patch works, debug upstream bridge version changes, or port the service setup to Linux/systemd.