Codex Warp

Codex Warp is a tiny Rust proxy that lets Codex Desktop, Codex CLI, and other Codex clients talk to OpenAI-compatible providers through a local Responses API surface.

Codex sends Responses-shaped requests with tools, streaming, metadata, and newer tool types such as custom. Many third-party providers only expose /v1/chat/completions, or they expose partial Responses support. Codex Warp translates those requests with editable TOML config so provider quirks can be fixed without recompiling.

Table Of Contents

• What It Does
• Quick Start
• Key Features
• Built-In Gateway Profiles
• Supported Model Families
• More Docs
• Current Scope
• Affiliation
• License

What It Does

Codex Warp sits between Codex and an upstream OpenAI-compatible provider. Codex continues to use the Responses API shape it expects, while Warp adapts the request, model catalog, stream events, and provider-specific fields on the way through.

It is meant for provider compatibility work that should live in config instead of client patches:

• local /v1/responses and /v1/models endpoints for Codex
• one or many upstream OpenAI-compatible gateways
• merged upstream and local model catalogs for Codex model selection
• model-family metadata for reasoning, tools, context windows, modalities, and provider-local auto-review routing
• editable request/tool morphs for chat-completions and Responses backends
• continue guard (enabled by default) for chat-completions models that stop mid-task
• optional tool approval policy loaded from TOML
• optional local Web UI for provider/model toggles, SQLite usage analytics, and log viewing
• sanitized debug logging and upstream User-Agent reporting

Quick Start

Build the proxy:

cargo build

Start it with a provider profile:

export XIAOMI_TOKEN_PLAN_API_KEY="..."
target/debug/codex-warp --config configs/xiaomi-token-plan.toml

For Moonshot KimiCode:

export KIMICODE_API_KEY="..."
target/debug/codex-warp --config configs/moonshot-kimicode.toml

For OpenCode Go:

export OPENCODE_GO_API_KEY="..."
target/debug/codex-warp --config configs/opencode-go.toml

Point Codex at the local proxy:

model_provider = "codex-warp"

[model_providers.codex-warp]
name = "Codex Warp"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
requires_openai_auth = false

[model_providers.codex-warp.auth]
command = "printf"
args = ["codex-warp-local"]
refresh_interval_ms = 0

Codex Warp owns the upstream provider credentials in its gateway config. The Codex-side auth block above is only a local refresh shim so Codex auto-populates models from the proxy.

Confirm the proxy can load models:

curl -sS http://127.0.0.1:8787/v1/models

Key Features

Config-Driven Provider Compatibility

Provider profiles, model-family metadata, request transforms, tool transforms, and tool approval rules are plain TOML under configs/. The baseline codex-warp.toml loads model-family metadata and tool policy rules, but it does not connect to any upstream provider by default.

Merged Model Catalogs

Warp merges upstream /models responses with local catalog entries, then adds the Codex metadata the client needs for model selection. Provider profiles can override exact model metadata when a gateway reports something unusual.

Continue Guard

Some chat-completions providers finish with text like Now let me check... instead of issuing the next tool call. The continue guard detects that case and asks Codex to continue the same turn with end_turn = false, so long agent sessions keep working instead of pausing for a manual continue. The guard is enabled by default across chat-completions providers (SSE and non-stream JSON); use the CLI flags only to tune it for a specific session:

target/debug/codex-warp \
  --config configs/clinepass.toml \
  --continue-guard-mode observe

The guard is conservative: it only acts when the provider finishes with finish_reason = "stop" (or omits / empties finish_reason on a text-only JSON completion), no tool call was emitted, and the assistant text looks like it intended to keep working. A fully completed update_plan suppresses the guard unless later tool work shows the plan snapshot is stale; sessions that never call update_plan are still covered. max_followups limits consecutive text-only stops per session; the counter resets when the last request input item is completed tool work, so mid-task pauses are handled without allowing unproductive loops to run away. See the configuration guide for observe mode and follow-up limits.

Tool Approval Policy

Warp can load tool approval rules from TOML and apply them before tool calls reach Codex. Use this to add approval hints for known-safe commands, force a manual prompt for interactive or sensitive commands, or deny requests that should never be sent to the client.

Notice: tool approval policy can affect what Codex is told to approve, prompt for, or block. Review every rule before enabling it. You are responsible for your own policy configuration and use it at your own risk.

See the tool approval policy guide for the rule format and the configuration guide for deployment examples.

Local Web UI

Warp can serve a lightweight management UI at /ui/ on the same listen address. It is disabled by default; set [webui] enabled = true to turn it on. Use it to add or edit providers and models, toggle them with switches, chart token/session and model usage over time from a local SQLite database, inspect provider and model usage breakdowns, and view or change logging from the Logs tab. See the configuration guide.

Built-In Gateway Profiles

Profile	File	Purpose	Enabled by default
OpenAI-compatible template	configs/openai-compatible.toml	Copy or edit for any provider with OpenAI-style auth and endpoints.	No
ClinePass	configs/clinepass.toml	Ready profile for ClinePass with a local documented model catalog.	No
Moonshot KimiCode	configs/moonshot-kimicode.toml	Ready profile for Moonshot KimiCode subscription keys with a local Kimi model catalog fallback.	No
OpenCode Go	configs/opencode-go.toml	Ready profile for OpenCode Go subscription keys, limited to its OpenAI-compatible chat-completions models.	No
Xiaomi Token Plan	configs/xiaomi-token-plan.toml	Ready profile for https://token-plan-sgp.xiaomimimo.com/v1.	No
OpenRouter	configs/openrouter.toml	Ready profile for OpenRouter; app attribution headers are attached on all upstream requests.	No
Destination override	--destination https://provider.example/v1	Quick one-off target without editing provider config.	Only when passed

OpenRouter App Attribution

Codex Warp automatically attaches OpenRouter app attribution headers on every upstream request — for all configured gateways, models, and API paths (/chat/completions, native /responses, /models, and any other outbound call) — not only when the configs/openrouter.toml profile is the default gateway. OpenRouter documents attribution across all of its API routes and models; Warp always sends the headers so no gateway/model combination can skip them.

• HTTP-Referer: https://github.com/jatmn/Codex-warp
• X-OpenRouter-Title: Codex Warp
• X-Title: Codex Warp (backwards-compatible alias)
• X-OpenRouter-Categories: cli-agent,programming-app

These are Codex Warp's own identity values. To override any of them for a specific provider, set the header under that provider's [provider.headers] or [providers.<id>.headers] section — user-supplied headers always take precedence over the automatic ones.

Note: HTTP-Referer is Codex Warp's public GitHub URL, so traffic sent through OpenRouter is attributed under that identity in OpenRouter's public rankings. To attribute traffic to your own project instead, override HTTP-Referer (and the other headers) under [provider.headers] or [providers.<id>.headers].

Supported Model Families

Parent brand	Catalog	Examples covered
DeepSeek	configs/model-families/deepseek.toml	deepseek-v3.2, deepseek-v3.2-speciale, deepseek-v4-flash, deepseek-v4-pro
MiniMax	configs/model-families/minimax.toml	minimax-m2.5, minimax-m2.7, minimax-m3
Moonshot AI	configs/model-families/moonshot-ai.toml	kimi-k2, kimi-k2-0905, kimi-k2.5, kimi-k2.6, kimi-k2.6-code, kimi-k2.7-code, kimi-k2.7-code-highspeed, kimi-for-coding
Alibaba Cloud	configs/model-families/qwen.toml	qwen3.6-35b-a3b; conservative broad defaults for qwen3.6* and qwen3.7*
xAI	configs/model-families/x-ai.toml	grok-4.3, grok-4.5, grok-build-0.1
Xiaomi	configs/model-families/xiaomi.toml	mimo-v2.5, mimo-v2.5-pro
Z.ai	configs/model-families/z-ai.toml	glm-5, glm-5.1, glm-5.2
Tencent Hunyuan 3 (Hy3)	configs/model-families/hy3.toml	hy3, hy3:free, hicap/hy3, hicap/hy3:free, tencent/hy3, tencent/hy3:free

More Docs

• Quick start
• Contributing
• Configuration guide
• Developer build guide
• Provider catalogs
• Model-family catalogs
• Codex client compatibility
• Tool approval policy
• Live testing
• Legal notices

Current Scope

Implemented now:

• POST /v1/responses and /responses
• GET /v1/models and /models
• streaming chat-completions text to Responses SSE
• streaming chat-completions function calls to Responses function_call output items, including expansion of Codex namespace tools such as multi_agent_v1.spawn_agent into ordinary functions
• non-streaming chat-completions response conversion
• editable TOML provider headers, auth, endpoint paths, model metadata, and tool/request morphs
• continue guard (enabled by default) for premature chat-completions stops
• sanitized debug logging that redacts obvious API keys and provider tokens even when full bodies or raw stream frames are enabled
• opt-in tool approval policy for GitHub CLI approval hints, escalation requests without reusable prefixes, and token-disclosure blocking
• upstream User-Agent reporting as codex-warp/<version>
• GitHub Actions CI for format, tests, build, CLI smoke, and whitespace checks

Still intentionally small:

• no multimodal image/file request translation yet
• no built-in provider profile auto-connects without user config

Affiliation

Codex Warp is an independent project and is not affiliated with, endorsed by, sponsored by, or approved by OpenAI. References to OpenAI, Codex, ChatGPT, the OpenAI API, Responses API, or related product names are for descriptive compatibility purposes only. Those names may be trademarks, service marks, product names, or other protected names owned by OpenAI or its affiliates.

License

Codex Warp is licensed under the Apache License 2.0 with the Commons Clause License Condition v1.0. Personal use, internal business use, modification, and distribution are allowed under the license terms, but selling or reselling the software, including paid hosted services whose value substantially comes from Codex Warp, requires a separate license from jatmn.

See NOTICE for attribution, non-affiliation, and trademark notices.