codex-relay

A lightweight Rust proxy that translates the OpenAI Responses API (used by Codex CLI) into the Chat Completions API, letting Codex work with any OpenAI-compatible provider — DeepSeek, Kimi, Qwen, Mistral, Groq, xAI, OpenRouter, and more.

Why

Codex CLI speaks the OpenAI Responses API, which is an OpenAI-proprietary stateful protocol. Every other provider exposes the standard Chat Completions API. codex-relay sits between Codex and your chosen provider, translating on the fly — no code changes to Codex required.

Install

# From PyPI — prebuilt binary for your platform
pip install codex-relay

# From crates.io
cargo install codex-relay

Quick start

1. Start the relay

CODEX_RELAY_UPSTREAM=https://api.deepseek.com/v1 \
CODEX_RELAY_API_KEY=$DEEPSEEK_API_KEY \
CODEX_RELAY_PORT=4446 \
codex-relay

On startup, the relay logs the available upstream models and prints a hint:

ℹ upstream models: deepseek-chat, deepseek-reasoner
⚠  To configure Codex with model metadata, run:  codex-relay --print-config --upstream ...

2. Generate your Codex config

codex-relay --print-config \
  --upstream https://api.deepseek.com/v1 \
  --api-key $DEEPSEEK_API_KEY

This prints a ready-to-use ~/.codex/config.toml snippet that includes model_properties for every upstream model, so Codex knows model capabilities and you won't see the "Model metadata … not found" warning.

If you prefer to write the config by hand, here is the minimal form:

model = "deepseek-chat"
model_provider = "deepseek-relay"

[model_providers.deepseek-relay]
name = "DeepSeek"
base_url = "http://127.0.0.1:4446/v1"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"

[model_properties."deepseek-chat"]
context_window = 262144
max_context_window = 1048576
supports_parallel_tool_calls = true
supports_reasoning_summaries = false
input_modalities = ["text"]

⚠️ Without model_properties, Codex CLI defaults to fallback metadata for any model it doesn't recognize natively. This can degrade performance, tool-call reliability, and context-window management. The relay logs a reminder at startup and offers --print-config to eliminate this class of problem entirely.

3. Use Codex normally — it routes through the relay transparently.

CLI reference

Flag Env var Default Description
--port CODEX_RELAY_PORT 4444 Listen port
--bind CODEX_RELAY_BIND 127.0.0.1 IP address to bind the listener to (e.g. 0.0.0.0 to accept remote connections)
--upstream CODEX_RELAY_UPSTREAM https://openrouter.ai/api/v1 Upstream Chat Completions base URL
--api-key CODEX_RELAY_API_KEY (empty) API key forwarded to upstream
--upstream-extra-params CODEX_RELAY_UPSTREAM_EXTRA_PARAMS (empty) JSON object merged into each upstream Chat Completions request
--drop-upstream-params CODEX_RELAY_DROP_PARAMS (empty) JSON array of top-level upstream request parameters to remove
--model-map CODEX_RELAY_MODEL_MAP (empty) Comma-separated source:target model name translations
--print-config (none) — Print a Codex config snippet with model_properties and exit
--record-corpus CODEX_RELAY_RECORD_CORPUS (off) Append the conversation flow of every completed turn to daily JSONL files (OpenAI messages format) in this directory
--session-ttl-hours CODEX_RELAY_SESSION_TTL_HOURS 168 Retain idle previous_response_id history and reasoning state for this many hours
--max-sessions CODEX_RELAY_MAX_SESSIONS 256 Maximum completed response histories retained for continuation
--max-session-memory-mb CODEX_RELAY_MAX_SESSION_MEMORY_MB 512 Approximate memory budget for retained session/reasoning state

Supported providers

Provider Base URL Suggested port
DeepSeek https://api.deepseek.com/v1 4446
Kimi (Moonshot) https://api.moonshot.cn/v1 4447
GLM (Zhipu) https://open.bigmodel.cn/api/coding/paas/v4 4453
Qwen https://dashscope.aliyuncs.com/compatible-mode/v1 4448
Mistral https://api.mistral.ai/v1 4449
Groq https://api.groq.com/openai/v1 4450
xAI https://api.x.ai/v1 4451
OpenRouter https://openrouter.ai/api/v1 4452

Any OpenAI-compatible endpoint works.

Upstream request parameters

Some providers expose non-standard Chat Completions parameters. You can merge top-level JSON fields into every upstream request, and optionally drop generated top-level fields before the merge. For example, to disable DeepSeek V4 thinking/reasoning mode:

CODEX_RELAY_UPSTREAM_EXTRA_PARAMS='{"thinking":{"type":"disabled"}}' \
CODEX_RELAY_DROP_PARAMS='["reasoning_effort"]' \
codex-relay --upstream https://api.deepseek.com/v1 --api-key "$DEEPSEEK_API_KEY"

Features

  • Streaming — full SSE streaming with correct event sequencing
  • Tool calls — accumulates streaming deltas and emits structured function_call items
  • Parallel tool calls — consecutive function_call input items merged into one assistant message
  • Reasoning models — streams reasoning_content (or the reasoning alias) as Responses reasoning summaries and preserves it across turns (Kimi k2.6, DeepSeek-R1, GLM). For GLM/Zhipu models the relay automatically sends thinking: {"type": "enabled"}, since GLM otherwise suppresses reasoning under Codex's system prompt
  • Model catalog — proxies /v1/models from the upstream provider
  • Auto-config — --print-config generates a complete Codex config with model metadata

Configuration

Variable Default Description
CODEX_RELAY_PORT 4444 Port to listen on
CODEX_RELAY_BIND 127.0.0.1 IP address to bind the listener to (e.g. 0.0.0.0 to accept remote connections)
CODEX_RELAY_UPSTREAM https://openrouter.ai/api/v1 Upstream Chat Completions base URL
CODEX_RELAY_API_KEY (empty) API key forwarded to upstream
CODEX_RELAY_UPSTREAM_EXTRA_PARAMS (empty) JSON object merged into each upstream Chat Completions request body
CODEX_RELAY_DROP_PARAMS (empty) JSON array of top-level upstream request parameter names to remove before forwarding
CODEX_RELAY_MODEL_MAP (empty) Comma-separated source:target model name translations (e.g., gpt-5.4:deepseek-v4-pro)
CODEX_RELAY_TOOL_DENYLIST (empty) Comma-separated tool names to remove before forwarding tools to the upstream model
CODEX_RELAY_DISABLE_QUIRKS (empty) Comma-separated platform quirk names to disable (e.g. dsml_heal,glm_thinking)
CODEX_RELAY_SESSION_TTL_HOURS 168 Retain idle session/reasoning state for this many hours
CODEX_RELAY_MAX_SESSIONS 256 Maximum completed response histories retained for previous_response_id
CODEX_RELAY_MAX_SESSION_MEMORY_MB 512 Approximate memory budget for retained session/reasoning state
CODEX_RELAY_HISTORY_STORE memory Retained history backend: memory or disk
CODEX_RELAY_HISTORY_DIR .codex-relay-history Directory for disk-backed history records
CODEX_RELAY_RECORD_CORPUS (off) Directory to append per-turn conversation records (OpenAI messages JSONL); off unless set
RUST_LOG codex_relay=info Log verbosity

Platform quirks

Some providers need workarounds that are not part of the Responses ⇄ Chat Completions translation itself. These are registered as named quirks (see src/quirks.rs for the full registry, triggers, and removal criteria):

Quirk Kind What it does
glm_thinking request-shaping Sends thinking: enabled for GLM/Zhipu models so they emit reasoning_content (issue #26)
dsml_heal response-healing Parses DeepSeek V4's intermittently leaked DSML tool-call markup in text content back into structured tool calls
missing_done response-healing Treats a cleanly closed SSE stream without [DONE] as complete when a full turn was received (issue #31)

Response-healing quirks activate only when the anomaly is detected and log a quirk <name> fired warning each time, so you can tell from the logs whether a workaround is still needed. Once the platform fixes the underlying bug, disable a quirk immediately with:

CODEX_RELAY_DISABLE_QUIRKS=dsml_heal codex-relay

Python API

from codex_relay import start

proc = start(port=4446, upstream="https://api.deepseek.com/v1", api_key="sk-...")
# ... use Codex ...
proc.terminate()

Testing

Two layers — offline tests pin behavior against captured Codex wire-shape; live tests pin behavior against real provider APIs.

Debugging tool round-trips

For tool-routing issues, enable debug logs:

RUST_LOG=codex_relay=debug codex-relay

The relay logs tool names only, never tool arguments or message content:

  • response tools=... — tools received from Codex's Responses API request
  • upstream tools=... — tools forwarded to the Chat Completions upstream
  • upstream function_calls=... — function calls returned by a blocking upstream response
  • upstream stream function_calls=... — function calls returned by a streaming upstream response

These lines are useful for checking whether a tool such as spawn_agent was preserved by the relay, and whether the failure happened before or after the model selected that tool.

Disk-backed history

By default, codex-relay keeps retained previous_response_id histories and reasoning lookups in memory. For longer-running processes or deeper debugging, you can opt into an inspectable on-disk store:

CODEX_RELAY_HISTORY_STORE=disk \
CODEX_RELAY_HISTORY_DIR=.codex-relay-history \
codex-relay

The disk backend writes JSON records under:

.codex-relay-history/
  sessions/
  reasoning/
  turns/

Session records contain the translated Chat Completions messages retained for a response id. Reasoning records keep call-id and turn-fingerprint lookups used to round-trip provider reasoning content. The relay keeps only an in-memory index for disk-backed entries and loads payloads on demand.

Treat this directory as sensitive: records may contain prompts, tool outputs, and other conversation data. The same TTL/count/byte retention knobs apply to disk-backed records, and evicted entries are removed from disk.

Corpus recording

For building datasets, --record-corpus <dir> continuously appends the conversation flow to daily-sharded JSONL files in OpenAI messages format:

codex-relay --record-corpus ./corpus \
  --upstream https://api.deepseek.com/v1 --api-key "$DEEPSEEK_API_KEY"

This is off by default and is a separate subsystem from the retention cache above: the corpus is an append-only archive that is never evicted, whereas the session store is an evictable continuation cache.

Each line is an incremental turn event — only the messages new to that turn are written, so the same conversation is reconstructed by concatenating the messages of every event that shares a conversation_id:

corpus/
  corpus-2026-04-04.jsonl

{
  "conversation_id": "resp_abc…",
  "response_id": "resp_def…",
  "parent_response_id": "resp_abc…",
  "timestamp_unix_ms": 1783447750503,
  "model": "deepseek-chat",
  "messages": [ { "role": "user", "content": "…" }, { "role": "assistant", "content": "…" } ]
}

The messages payload uses the standard OpenAI schema and preserves tool_calls, role: "tool" outputs (tool_call_id), and assistant reasoning_content (a widely-used non-standard field that training frameworks ignore if unknown). The first event of a conversation includes the system prompt; subsequent events omit it. Isolated spawn_agent child requests start their own conversation_id.

To fold the turn events back into whole-conversation OpenAI records:

jq -s 'group_by(.conversation_id)[]
       | {messages: (map(.messages) | add)}' corpus/*.jsonl

⚠️ Records contain prompts, tool call arguments, and tool outputs — more than the debug logs ever emit. Treat the directory as sensitive, especially when combined with --bind on a non-loopback address.

Subagent tool routing

Codex subagent tools such as spawn_agent, wait_agent, and close_agent are runtime tools. The relay can preserve them in the tool schema and round-trip the model's selected function call, but it cannot reliably detect whether the local Codex app-server daemon is new enough to execute those calls.

If Codex shows unsupported call: spawn_agent, first verify that the Codex CLI and app-server daemon versions match. A stale daemon can expose a newer tool schema to the model while lacking the handler that executes the returned call. Also check your Codex config: [features] subagents = true is not recognized; use [features] multi_agent = true only if you need to override the default.

As an escape hatch for affected runtimes, remove unsupported tools before they reach the upstream model:

CODEX_RELAY_TOOL_DENYLIST=spawn_agent,wait_agent,close_agent codex-relay

The denylist matches the tool name forwarded to Chat Completions. Namespaced MCP tools use their flattened name, for example mcp__codex_apps__github-_fetch_issue.

Offline (always green, default cargo test)

Replays Codex CLI fixtures through the translation layer and asserts role/tool/reasoning behavior. Each fixture pins a Codex CLI version under tests/fixtures/codex_<major>_<minor>_<patch>/.

cargo test

Live (gated on provider API key, #[ignore] by default)

Spawns the relay binary on a random port, points it at the real provider, and exercises /v1/models, blocking + streaming, tool calls, and (for thinking models) the reasoning_content round-trip via an in-process recording proxy.

DEEPSEEK_API_KEY=sk-... cargo test --test compat_deepseek_live -- --ignored --test-threads=1

Regenerating fixtures after a Codex upgrade

  1. Add a debug dump to the relay (write body bytes from handle_responses to a file before parsing).
  2. Run a real codex exec against it; copy inbound_*.json to a new tests/fixtures/codex_<major>_<minor>_<patch>/ folder.
  3. Trim each payload down to the smallest one that exercises the feature you want to lock in.
  4. Add a row to tests/fixtures/VERSIONS.md and a test pointing at the new directory.

The old fixture directory stays as a regression net so the relay keeps working with the previous Codex CLI release.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by OpenAI. "Codex" refers to OpenAI Codex CLI, an open-source project licensed under Apache-2.0. codex-relay is an independent, community-built translation proxy.

Contributors

  • myk5010 — system/developer message ordering fix and model name mapping (#4)
  • qcnhy — streaming usage, MCP namespace bug reports, namespace tool-routing analysis, and independent verification (#5, #6, #17)
  • JasonC93 — subagent tool-routing and spawned-agent context isolation reports (#10, #12)
  • ma-buting — namespace tool-name separator fix (#19)
  • SaladDay — prompt-cache accounting debug logs (#22)
  • Cherno76 — prompt-cache hit tokens in Responses API usage (#23)

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.5.8)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mingli.yuan from gravatar.com mingli.yuan

License

MIT License (MIT)

Requires

Python >=3.11

Tags

codex llm proxy relay

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codex_relay-0.5.6.tar.gz (116.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

codex_relay-0.5.6-py3-none-win_arm64.whl (2.7 MB view details)

Uploaded Python 3Windows ARM64

codex_relay-0.5.6-py3-none-win_amd64.whl (2.9 MB view details)

Uploaded Python 3Windows x86-64

codex_relay-0.5.6-py3-none-musllinux_1_2_x86_64.whl (3.5 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

codex_relay-0.5.6-py3-none-musllinux_1_2_aarch64.whl (3.4 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

codex_relay-0.5.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

codex_relay-0.5.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

codex_relay-0.5.6-py3-none-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

codex_relay-0.5.6-py3-none-macosx_10_12_x86_64.whl (3.1 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file codex_relay-0.5.6.tar.gz.

File metadata

  • Download URL: codex_relay-0.5.6.tar.gz
  • Upload date:
  • Size: 116.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for codex_relay-0.5.6.tar.gz
Algorithm Hash digest
SHA256 f2757fd2a9aac63da77024e3e6255fc2b853633e525a7c386440f69beb37d4cb
MD5 1375e55f010d67bfb80fd4003f64e0b0
BLAKE2b-256 1f47c84d56a1c7fc3bbe0812f7deb6b4681cb3bd404430738b6f73746ea8a410

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6.tar.gz:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-win_arm64.whl.

File metadata

  • Download URL: codex_relay-0.5.6-py3-none-win_arm64.whl
  • Upload date:
  • Size: 2.7 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for codex_relay-0.5.6-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 e24feefe42e8f8fdaf9b16abe94880d39fc49f05cf68c405323b5af2408acb21
MD5 c2ad4af6bd2943f2197d2a01178d3e7e
BLAKE2b-256 e968e3889b9317cecc08961be047bdf1ab4cd82818b8058749e29efb9bd4b5ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-win_arm64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-win_amd64.whl.

File metadata

  • Download URL: codex_relay-0.5.6-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.9 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for codex_relay-0.5.6-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 53189f54b3d9f75840e64a1d9a2f1bd9a1175931437e32290aa6cd7200a1c4ed
MD5 f95e1a4ef46c192a38f7fc5ca39cf2d9
BLAKE2b-256 3ce1fb51315853c1943ada5d47f1a449e0b99d7eef2a567523d4c73833eb6950

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-win_amd64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a08ff36e6d9114e3b73aadaf9d8a13cde1e005698ea27a2adedde685220074a3
MD5 f29c7fb17e14080e991b36ac12d73963
BLAKE2b-256 ea6e5a00d3db86b13bf52b4f92675d6c82e310911ef0956b28227c503f0e574f

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-musllinux_1_2_x86_64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 61ccf660d38426ce0509719c8cd2bcf385878475924e71f2afb2ff101ccf6b99
MD5 e3c6dee7d65c07a85f82463957d2fd18
BLAKE2b-256 42dd092ec5d14b8813535e8d4b468dda7bf4b9a9dd2c5b920ae283673afcad50

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-musllinux_1_2_aarch64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5b7a93df1ea94212d0831eb498abfa04a3766b789681c98c7a98a21728630ade
MD5 c6c9b1d18fc81ea091cb02733712fdaf
BLAKE2b-256 c235abfeb9a4777ec0673391a60a324849db3542c8204410af0fff93c9fcf169

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 dc4499b0376b1ed1e7264ce42b6078f85ff6f3f4730ff90f68c6a9e785ed9028
MD5 ffff1b87a1690e978911cabb9c263bea
BLAKE2b-256 532eb4730b30d82fda077e0f3c5db09dffca2a758b6f111059fd1ce9c71b47db

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2bce18217485639d2ac584c006684629f81b9af5b796ccd9d59bc4a581326af1
MD5 682347c69857d0f299b5241a2cb67efc
BLAKE2b-256 58756ad86b74ecf46c7c482b251a920bcaac8779361d0c72b4e7f7f45c1ea226

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-macosx_11_0_arm64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codex_relay-0.5.6-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.6-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ddedbcffc64f2fbf07d17142e95d2478c037977b7e9908b99a7d3d3a96dca737
MD5 d248936f8d17c3a85ad0f70fdca7bc67
BLAKE2b-256 61acb79198ec814375eb4659afc2907fd39393c06bdf7c3dfe074adf811c55ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.6-py3-none-macosx_10_12_x86_64.whl:

Publisher: publish.yml on MetaFARS/codex-relay

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page