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 \
  --model-catalog ~/.codex/codex-relay-models.json

This prints a ready-to-use ~/.codex/config.toml snippet and writes a model catalog containing both Codex's built-in models and every upstream model, so you won't see the "Model metadata … not found" warning. The generated entries inherit version-sensitive instructions and tool formats from the installed Codex CLI. Use --model-template <MODEL> to select a different bundled model as that template.

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

model = "deepseek-chat"
model_provider = "deepseek-relay"
model_catalog_json = "/home/user/.codex/codex-relay-models.json"

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

Recent Codex versions use model_catalog_json; the former [model_properties] config syntax is no longer supported. A custom catalog replaces the built-in catalog, so codex-relay starts with the catalog from your installed Codex version and appends upstream models instead of creating an incomplete replacement.

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 and exit
--model-catalog (none) — With --print-config, write a version-matched full model catalog to this path
--model-template (none) first visible bundled model Bundled Codex model whose instructions and tool formats generated entries inherit
--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:
Latest release

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.8.tar.gz (122.8 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.8-py3-none-win_arm64.whl (2.8 MB view details)

Uploaded Python 3Windows ARM64

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

Uploaded Python 3Windows x86-64

codex_relay-0.5.8-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.8-py3-none-musllinux_1_2_aarch64.whl (3.4 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

codex_relay-0.5.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

codex_relay-0.5.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

codex_relay-0.5.8-py3-none-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

codex_relay-0.5.8-py3-none-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: codex_relay-0.5.8.tar.gz
  • Upload date:
  • Size: 122.8 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.8.tar.gz
Algorithm Hash digest
SHA256 23527cdac6bb9740e6bb6d2b2a8c54c1f85aeb4b0aa8e020e7e16113a8798f6e
MD5 11212871c34506f3ced9ad280004023e
BLAKE2b-256 0f113fac77cbaee072386a02b8444ff2cef02cd3ddc5e96d12cfa37a7f61f23b

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8.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.8-py3-none-win_arm64.whl.

File metadata

  • Download URL: codex_relay-0.5.8-py3-none-win_arm64.whl
  • Upload date:
  • Size: 2.8 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.8-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 16a782b8f696a597439bdcdfe0874df50e441f5be080c9fde1b763fe0b2c1cfa
MD5 02ceb5fbe115ee4f467e715301d65354
BLAKE2b-256 ec7d0e1858026548e11621de8c9faadf4e9c1b0dc1b1b036c15c9b8562c7c4be

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-win_amd64.whl.

File metadata

  • Download URL: codex_relay-0.5.8-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.8-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 f0c3dde0d2b70542e1ab3944fcb8a15c5747ed673d99851b449d1cbbd972ebe0
MD5 b2f3cb35a86e8fa932c89c2aa10a8149
BLAKE2b-256 d02f3d4bb28816d7cc31aa6cbf5ee5868bd6572bca301f63ea888ead8a530c2c

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 183024deeb346a1bd4b2717fdb8b985cfb93ffba2c812696f6f882c5a578e7ea
MD5 f163fe5bbec1164736d5f2eca8a4adb6
BLAKE2b-256 1e1cab042b3e9d73bf10262b51bf31e0b940de66447ce6f40ab0981fa17ef8e6

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1754d3f12bab90b7e3edd394504a78d321e956732c47d06ffbc9426ffe68cffb
MD5 41fb9f6418b5d25be7208d3a16ebda39
BLAKE2b-256 64356e40895fc97482340fcdf18c9f4e4d53f7c82f1c3ddafc450d9c155ddf43

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d493b4fc30cbb3fe99f9c3cc367d44a121d43ae5478f2d9791d7bab11b2c8f9f
MD5 9796b4eef73ca9189baf6511d06a64e4
BLAKE2b-256 82e174e3a0bbb80984ad7911304c249848c1b873b2161569689b9fa51a9a0363

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ec2d0c63145647be0bdd6bb8415c13dbf707ed67a88c17da0eef3e96a6ddf72d
MD5 63413abc7ced3e63230592606f69774d
BLAKE2b-256 a6b37d661f04a5df830e3626488963c74bb64c9882400de4e67d950d7d8c7127

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2bc125ff4a649e63674f8b4fd6316f1cd89482b3ef4fc9aff02bb5cf6cfccb0c
MD5 c4568bed182fc4de369942bd673d01d5
BLAKE2b-256 14f4973243a48fe361f907b1ab4e9c462c587e69808df82f20f2b04e1765ff97

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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.8-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.5.8-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b7aaae61c0069579ba8da06cd4dc6c91814d714f069be412186d0c46c1cb2e30
MD5 ea616bee923036fc22e339a6e5a10bb9
BLAKE2b-256 104447619f7a42dc61efb99317f8e6d913c33645dd2fc5253b0648861c1084c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.5.8-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