Omnibot Codex Bridge

Self-host this small bridge on a Windows, macOS, or Linux PC that already has the OpenAI Codex CLI and/or Claude Code CLI installed. Omnibot connects to the bridge over WebSocket. On macOS/Linux, Codex sessions first try to proxy the active Codex desktop app-server socket, then fall back to starting codex app-server locally on the PC. Claude sessions run claude --input-format stream-json through the same bridge pipe.

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/upload: upload a binary attachment (base64) into the bridge workspace; returns the PC-side absolute path so remote Codex/Claude can read images and files inserted from the phone.
• POST /fs/upload-binary: stream attachment bytes with a SHA-256 upload key. Bridge 0.1.13+ deduplicates concurrent/retried uploads and avoids base64 memory amplification.
• POST /fs/delete: delete a remote file or directory.
• POST /fs/move: rename or move a remote file or directory.
• GET /tasks: list remote scheduled Codex/Claude tasks stored on this bridge.
• POST /tasks: create or update a 5-field cron task.
• POST /tasks/run: trigger a task immediately.
• POST /tasks/delete: delete a task.
• GET /task-results: read recent task results.

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.

Bridge 0.1.13+ acknowledges each stdin envelope after it has been accepted by the desktop socket or child process. Omnibot uses this acknowledgement to distinguish a definite send failure from an interrupted response whose execution state must be reconciled before retrying.

When Omnibot supplies a dynamic relay configuration, Bridge retains Codex history under ~/.omnibot/codex-homes/ so remote threads can be reopened and resumed. Bridge 0.1.11 and later uses one shared rollout history for all dynamic Responses relays, which allows an existing remote thread to switch relays without becoming a new thread. On first use it imports rollout files from the older per-relay directories. Each connection keeps relay credentials in its own temporary Codex config home and removes that home on disconnect; protect the shared directory because it still contains chat history. Older per-relay directories may still contain credentials and can be removed after the shared history has been verified.

Run

Recommended startup:

npx @lwz762/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 @lwz762/codex-bridge --cwd "/Users/you/code/project" --token auto --no-interactive

Windows PowerShell example:

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

Or install it globally:

npm install -g @lwz762/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

Publishing

Maintainer releases are published from GitHub Actions with npm Trusted Publishing. Update the version in package.json and package-lock.json, commit the change, then push the matching tag:

git tag bridge-v0.1.11
git push origin bridge-v0.1.11

The tag must exactly match bridge-v<package version>. The hosted workflow uses npm OIDC and does not require a long-lived npm token.

The self-hosted APK release workflow also compares this package version with npm. When npm is behind, it dispatches the small GitHub-hosted publishing workflow automatically; when the versions match, no hosted runner is started.

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

Claude and Scheduled Tasks

Claude remote sessions require Claude Code CLI on the bridge host:

npm install -g @anthropic-ai/claude-code

Remote scheduled tasks are executed by the bridge host with codex exec when agent:"codex" is set, or claude -p when agent:"claude" is set. They remain active while the phone is offline. Task definitions are stored in ~/.omnibot/scheduled-tasks.json; recent results are stored in ~/.omnibot/task-results.json. Bridge 0.1.9 and later also pushes completed results over connected Omnibot sessions so Android can show a notification immediately, while periodic result polling remains the offline fallback.

Codex tasks may include a codexConfig object with baseUrl, model, reasoningEffort, relayProfileId, apiKey, and wireApi:"responses". Omnibot fills this from the selected Codex relay when it creates tasks through the app or from a live remote Codex session, so scheduled Codex tasks do not need a separate codex login on the bridge host. Bridge 0.1.10 and later also persist the task-level relayProfileId, requested model, and reasoning effort so the Android editor can restore the exact selection. Claude tasks may include an env object with ANTHROPIC_* variables; Omnibot fills these from the selected Anthropic relay for Claude tasks.

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 @lwz762/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 @lwz762/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 @lwz762/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 @lwz762/codex-bridge --cwd "C:\Users\you\code\project" --token auto --codex-bin "C:\Users\you\AppData\Roaming\npm\codex.cmd"