Omnibot Codex Bridge

Self-host this small bridge on a Windows, macOS, or Linux PC that already has the OpenAI Codex CLI installed and logged in. Omnibot connects to the bridge over WebSocket. On macOS/Linux, the bridge first tries to proxy the active Codex desktop app-server socket, then falls back to starting codex app-server locally on the PC.

The bridge also exposes authenticated HTTP helpers used by Omnibot:

• GET /health: check bridge and Codex CLI availability.
• GET /fs/list?path=/abs/path: list remote directories for the in-app cwd picker.
• GET /fs/read?path=/abs/path: read a remote file for preview/editing.
• POST /fs/write: write UTF-8 text back to a remote file.
• POST /fs/delete: delete a remote file or directory.
• POST /fs/move: rename or move a remote file or directory.

Codex sessions are read through the proxied codex app-server protocol, so the app uses the same session list flow for local and remote Codex.

Run

Recommended startup:

npx @thuocean/codex-bridge

The bridge opens a terminal setup flow where you can use Up/Down and Enter to choose the LAN address to listen on and either auto-generate a token, enter a token manually, or disable token auth. Custom values are typed in place on the selected row. Press Esc on later steps to go back and reselect the previous setup item.

When you enter a token manually, the bridge remembers it in ~/.omnibot/codex-bridge.json and reuses it on later launches. If the setup UI opens, the remembered token appears as the default token choice so you can reuse, replace, or forget it without adding flags. Run with --interactive to force this setup UI, or --forget-token to clear the remembered token before setup.

Scripted startup is still supported:

npx @thuocean/codex-bridge --cwd "/Users/you/code/project" --token auto --no-interactive

Windows PowerShell example:

npx @thuocean/codex-bridge --cwd "C:\Users\you\code\project" --token auto --no-interactive

Or install it globally:

npm install -g @thuocean/codex-bridge
codex-bridge

When the bridge starts, it prints a terminal QR code. In Omnibot, tap Settings -> 服务与环境 -> Codex -> 扫码连接 to fill the remote Bridge URL, cwd, and token automatically.

For local development from this repository:

cd tools/codex-bridge
npm install
npm start -- --cwd "/Users/you/code/project" --token auto --no-interactive

If you do not use the QR code, set these values in Omnibot under Settings -> 服务与环境 -> Codex:

• Bridge URL: the printed Quick connect bridge URL, usually ws://<pc-lan-ip>:17321/codex
• Remote cwd: the project path passed with --cwd
• Bridge Token: the printed Bridge token; with --token auto it is generated for this run

For WAN access, put this behind Tailscale, WireGuard, a trusted reverse proxy with TLS, or another private network path. Do not expose the bridge directly to the public internet.

If the printed IP is not reachable from your phone, override the advertised address:

npx @thuocean/codex-bridge --cwd "/Users/you/code/project" --token auto --public-host 192.168.1.20

For unattended scripts or service managers, pass --no-interactive or set OMNIBOT_BRIDGE_INTERACTIVE=0.

CLI Options

• --cwd <path> or positional project-dir: Codex working directory, default current directory
• --token <value|auto>: bearer token; auto generates a random token for this run
• --no-token: disable token auth for trusted private networks
• --host <host>: listen host, default 0.0.0.0
• --port <port>: listen port, default 17321
• --public-host <host>: advertised host/IP used in the QR code
• --codex-bin <path>: Codex executable, default codex
• --codex-home <path>: optional CODEX_HOME override
• --app-server <auto|desktop|stdio>: app-server transport, default auto
• --app-server-socket <path>: desktop Codex app-server Unix socket override
• --config <path>: bridge config path for the remembered manual token
• --forget-token: clear the remembered manual token before setup
• --interactive: force terminal setup prompts
• --no-interactive: start immediately without terminal prompts

Environment

• OMNIBOT_BRIDGE_HOST: listen host, default 0.0.0.0
• OMNIBOT_BRIDGE_PUBLIC_HOST: optional advertised host/IP used in the QR code
• OMNIBOT_BRIDGE_PORT: listen port, default 17321
• OMNIBOT_BRIDGE_TOKEN: optional bearer token; set to auto to generate one
• OMNIBOT_BRIDGE_CWD: default project directory
• OMNIBOT_BRIDGE_APP_SERVER: auto, desktop, or stdio
• OMNIBOT_BRIDGE_INTERACTIVE: set to 0/false to disable prompts, or 1/true to force prompts
• OMNIBOT_BRIDGE_CONFIG: bridge config path, default ~/.omnibot/codex-bridge.json
• OMNIBOT_BRIDGE_MAX_READ_BYTES: max file preview payload, default 12 MiB
• CODEX_BIN: Codex executable, default codex
• CODEX_HOME: optional Codex config directory override
• CODEX_APP_SERVER_SOCKET: desktop Codex app-server Unix socket override

Troubleshooting

If Omnibot can reach the bridge but reports that remote Codex is unavailable, open the printed health check URL:

curl -H "Authorization: Bearer <token>" http://<pc-lan-ip>:17321/health

ready: false usually means the PC cannot run codex --version and no desktop app-server socket was found. Install/login the OpenAI Codex CLI on the PC, make sure codex is on PATH, or start the bridge with an explicit executable:

npx @thuocean/codex-bridge --cwd "/Users/you/code/project" --token auto --codex-bin /absolute/path/to/codex

If you specifically want to attach to the Codex desktop app process and fail when that socket is not available, start with:

npx @thuocean/codex-bridge --cwd "/Users/you/code/project" --token auto --app-server desktop

On Windows, npm usually installs command shims as .cmd files. If the health check still says ready: false, run this in PowerShell:

where.exe codex
codex --version

Then pass the .cmd path printed by where.exe:

npx @thuocean/codex-bridge --cwd "C:\Users\you\code\project" --token auto --codex-bin "C:\Users\you\AppData\Roaming\npm\codex.cmd"