clawrouter-codex

Run OpenAI Codex on any ClawRouter / BlockRun model — Claude, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, GPT and more — paid per request from a wallet (x402 USDC), no API keys.

Codex only speaks the OpenAI Responses API (/v1/responses). BlockRun speaks Chat Completions. This is a local bridge that translates between them and pays per request, so Codex (CLI, IDE, and Desktop) can use BlockRun's models:

Codex ──/v1/responses──▶ clawrouter-codex ──@blockrun/llm──▶ BlockRun   (x402 USDC, default)

By default the bridge pays BlockRun directly via the official @blockrun/llm SDK (plain per-request x402 on Base) — one process, no proxy, and the model list comes live from the source. It's wire-format translation plus a few conveniences (model picker, web search, a dashboard).

Smart routing works in direct mode too: pick blockrun/auto and the request is classified and routed to the cheapest capable model (ClawRouter's local rules engine, reused as a library — <1ms, no extra LLM call), then paid with full messages + tools. Set BLOCKRUN_NO_ROUTING=1 to pin a default model instead.

Two modes. Direct (above) is the default. You can also run in proxy mode — forwarding to a local @blockrun/clawrouter proxy that holds the wallet — with BRIDGE_MODE=proxy (or by pointing CLAWROUTER_PROXY_URL at a running proxy).

Quick start

You need Node ≥ 20 and a funded BlockRun wallet (~/.blockrun/.session, or set BLOCKRUN_WALLET_KEY). Then:

npx @blockrun/clawrouter-codex up       # start the bridge + write the Codex profile + build the catalog
codex --profile clawrouter              # use BlockRun models in the Codex CLI

That's it. up brings up the bridge (direct mode, :8403) and runs setup once it's healthy, then stays running. Want the models in Codex Desktop's picker too? Add:

npx @blockrun/clawrouter-codex desktop on   # restart Codex (Cmd+Q) after

setup writes a profile (~/.codex/clawrouter.config.toml), so your base config — and your ChatGPT-subscription default — is untouched: plain codex still uses it, codex --profile clawrouter uses BlockRun. (start, setup, doctor are still available as separate steps if you prefer.)

No funded wallet yet? It still works — unfunded requests fall back to the free models. Fund USDC on Base to unlock the paid ones (the dashboard shows the address + a QR).

Switches

npx @blockrun/clawrouter-codex desktop on     # show ClawRouter models in the Codex Desktop picker
npx @blockrun/clawrouter-codex websearch on   # enable live web search (BlockRun Exa, wallet-paid)
# …off to revert. Restart Codex (Cmd+Q) after toggling.

• desktop flips the base config so Codex Desktop (and plain codex) default to ClawRouter; off restores the native ChatGPT-subscription default. The CLI --profile works either way.
• websearch lets any model search the web. Codex's built-in web_search is a hosted tool that only OpenAI's backend runs, so the bridge runs web search itself (via BlockRun Exa) and feeds results back — transparently to Codex.

Dashboard

http://localhost:8403/dashboard

A loopback panel: a master Subscription ⇄ ClawRouter switch, wallet balance + Fund (address QR + copy), 7-day spend, the web-search switch, and every model in your picker (click one to set it as the default, or ↻ Update models to refresh after a ClawRouter release). Loopback-only — it reads wallet state and edits Codex config.

Commands

| Command | What it does | |---|---| | start | Bring up the bridge (:8403) in direct mode — pays BlockRun via the SDK, no proxy — and supervise it | | setup | Write the clawrouter profile and generate the model catalog | | doctor | Verify the link end to end (bridge, mode, wallet, catalog, config) | | wallet | Print the full wallet address to fund without opening the dashboard | | gen-catalog | (Re)generate the model catalog from the live model list | | desktop on\|off | Toggle the Codex Desktop picker between BlockRun and native GPT | | websearch on\|off | Toggle live web search | | daemon | Install a macOS LaunchAgent to keep the link up across reboots | | direct | Run only the bridge in direct mode (what start uses) | | bridge | Run only the bridge in proxy mode (forwards to a @blockrun/clawrouter proxy) |

Installed globally (npm i -g @blockrun/clawrouter-codex) the same commands are available as clawrouter-codex <command>.

Codex config it writes

setup writes ~/.codex/clawrouter.config.toml (a Codex profile, layered on top of your base config via --profile clawrouter):

model = "blockrun/auto"
model_provider = "clawrouter"
model_catalog_json = "~/.codex/clawrouter-catalog.json"

[model_providers.clawrouter]
name = "ClawRouter"
base_url = "http://localhost:8403/v1"
wire_api = "responses"
requires_openai_auth = false

Desktop note: the Desktop picker only renders custom models when the provider has requires_openai_auth = true (a quirk of Codex's own UI). desktop on sets that on the base config; the bridge ignores the forwarded ChatGPT token and still pays via the wallet — it's never sent to OpenAI.

Configuration

| Env var | Default | Effect | |---|---|---| | PORT | 8403 | Port the bridge listens on | | BLOCKRUN_WALLET_KEY | — | Raw 0x EVM key for x402 (overrides ~/.blockrun/.session) | | BLOCKRUN_DEFAULT_MODEL | anthropic/claude-opus-4.5 | Model that blockrun/auto resolves to in direct mode | | BLOCKRUN_API_URL | https://blockrun.ai/api | BlockRun endpoint the SDK pays | | proxy mode only | | | | BRIDGE_MODE=proxy | — | Forward to a @blockrun/clawrouter proxy instead of paying directly | | PROXY_PORT | 8404 | Port start launches the proxy on (proxy mode) | | CLAWROUTER_PROXY_URL | http://127.0.0.1:8404/v1 | Proxy upstream to forward to (also enables proxy mode) | | CLAWROUTER_CMD | npx -y @blockrun/clawrouter@latest | Command start uses to launch the proxy |

start auto-discovers ~/.blockrun/.session; on most machines no wallet env is needed.

To see the full funding address from a terminal, even on a remote VPS:

npx @blockrun/clawrouter-codex wallet

Keep it up across reboots (macOS)

npx @blockrun/clawrouter-codex daemon          # install a login LaunchAgent
npx @blockrun/clawrouter-codex daemon uninstall

⚠️ The daemon auto-starts a wallet-signing payment proxy at login that can spend USDC unattended. Install it only on a machine you control.

How the translation works

Request (responsesToChat): instructions → leading system message; input[] items → messages[] (message→{role,content}, function_call→assistant tool_calls, function_call_output→{role:"tool", tool_call_id}, reasoning→dropped); flat Responses tools[] → nested Chat tools.

Response (chatToResponsesEvents): the buffered Chat Completion becomes a Responses SSE sequence — response.created → response.output_item.added → response.output_text.delta → response.output_item.done (message and/or function_call items) → response.completed. Tool calls a model leaks as raw JSON in text are recovered and re-emitted as structured function_calls.

The exact SSE contract was read from the Codex source (codex-rs/codex-api/src/sse/responses.rs).

Limitations

• Streaming is synthesized, not incremental — output arrives as one delta (protocol-correct, not yet token-by-token).
• Reasoning items are dropped — no encrypted-reasoning passthrough.
• Stateless — Codex sends store:false with full input each turn, so no server-side response state is needed.

Tests

npm test     # node --test, zero dependencies

License

MIT © BlockRun