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
• optional continue guard for chat-completions models that stop mid-plan
• optional tool approval policy loaded from TOML
• 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 can detect that case while Codex has an active plan and ask Codex to continue the same turn with end_turn = false:

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

The guard is conservative: it only acts when Codex has an active plan, the provider finishes with finish_reason = "stop", no tool call was emitted, and the assistant text looks like it intended to keep working. 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.

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
Destination override	--destination https://provider.example/v1	Quick one-off target without editing provider config.	Only when passed

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-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

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
• non-streaming chat-completions response conversion
• editable TOML provider headers, auth, endpoint paths, model metadata, and tool/request morphs
• opt-in continue guard for premature chat-completions stops during active Codex plans
• 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 namespace tool expansion beyond a simple fallback function
• 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.