Responses API ↔ Chat Completions translation bridge for Codex CLI

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for mingli.yuan from gravatar.com mingli.yuan

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Tags codex , llm , proxy , relay
  • Requires: Python >=3.11
Classifiers
Report project as malware

Project description

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

Supported providers

Provider Base URL Suggested port
DeepSeek https://api.deepseek.com/v1 4446
Kimi (Moonshot) https://api.moonshot.cn/v1 4447
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.

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 — preserves reasoning_content across turns (Kimi k2.6, DeepSeek-R1)
  • 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_UPSTREAM https://openrouter.ai/api/v1 Upstream Chat Completions base URL
CODEX_RELAY_API_KEY (empty) API key forwarded to upstream
CODEX_RELAY_MODEL_MAP (empty) Comma-separated source:target model name translations (e.g., gpt-5.4:deepseek-v4-pro)
RUST_LOG codex_relay=info Log verbosity

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.

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)

License

MIT

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for mingli.yuan from gravatar.com mingli.yuan

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Tags codex , llm , proxy , relay
  • Requires: Python >=3.11
Classifiers

Release history Release notifications | RSS feed

This version

0.2.0

0.1.9

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

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

codex_relay-0.2.0-py3-none-win_amd64.whl (2.6 MB view details)

Uploaded Python 3Windows x86-64

codex_relay-0.2.0-py3-none-manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

codex_relay-0.2.0-py3-none-manylinux_2_28_aarch64.whl (3.1 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ ARM64

codex_relay-0.2.0-py3-none-macosx_11_0_arm64.whl (2.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

codex_relay-0.2.0-py3-none-macosx_10_12_x86_64.whl (3.0 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for codex_relay-0.2.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 a99e34b0f24c48bb7d324d98dca2c0c1e7c89780edf529c7f146cac333279705
MD5 4f5cbff3557019f3130bc536132905d0
BLAKE2b-256 80cdf1c047e66abe02af7d40cc43b0f11ef8e87d500d5b20d318537692fa8796

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.2.0-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.2.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for codex_relay-0.2.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b10f04b63b891274d4d56fc8be9fb03c843c2069c3a74e62fb6a781555959519
MD5 ed636c86a4dd6618154971ec5e33a764
BLAKE2b-256 40205ea0ed9eb2dadf430eb40e4937f76b612aa071ade822e698fe06096a7a00

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.2.0-py3-none-manylinux_2_28_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.2.0-py3-none-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for codex_relay-0.2.0-py3-none-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6b435ea0c3be713c50ac2e5e9b1d0dabe975dd88d389ac052c43dfcdf628493e
MD5 a5379e1e8538f7d88b100ba4c5ed3b0b
BLAKE2b-256 015f5890d3f77ceb34b4542d1a4c48f81de5f7683d0675fd78b00b9bc1f3587a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_relay-0.2.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0ff13596128f01cd646cc5f338e7c6ace39a72ef55b8060745789d2816c63fce
MD5 bd1a5ff4d453f52a155fc8faad5148a1
BLAKE2b-256 9c6c47f98cb87975a20721ce738a8c042ab09da62547ed6e86c5976c191c028e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for codex_relay-0.2.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 30b0fd4fb71944708ff375a9bb72521b9f0af49f195d2bebbec0304ec33b6596
MD5 2344c24e3d48d8780becb9a7598d663a
BLAKE2b-256 daca4dd00767e43b856c7266b5452753d6fe9d4f1b569428707a144e6100f8fd

See more details on using hashes here.

Provenance

The following attestation bundles were made for codex_relay-0.2.0-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 Pingdom Monitoring Sentry Error logging StatusPage Status page