icebear0828/codex-proxy

Codex Proxy – 本地 AI 编程助手的中转站

What it is – A lightweight local server that turns the Codex Desktop programming‑assistant API into standard OpenAI, Anthropic, Gemini, and Ollama‑compatible endpoints. It lets any client that speaks those protocols (Cursor, Claude Code, Continue, Pi, etc.) use the Codex model without changing the client.

Key capabilities

• Protocol translation – Accepts /v1/chat/completions (OpenAI), /v1/messages (Anthropic), Gemini, Codex /v1/responses, and optional Ollama /api/chat. Handles SSE streaming, WebSocket fallback, function‑calling/tool‑calls and structured‑output formats.
• Account pool & smart routing – OAuth PKCE login, multiple ChatGPT accounts, automatic rotation (least‑used, round‑robin, sticky), plan‑aware routing, token refresh, usage tracking, ban detection and a configurable fallback API key.
• Proxy pool – Per‑account upstream proxy configuration, health‑checks, automatic exclusion of unreachable proxies.
• Anti‑detection / fingerprinting – Rust native TLS addon (reqwest + rustls) reproduces the exact request headers and TLS fingerprint of the official Codex desktop client, with per‑account device IDs and cookie replay.
• Model catalogue – Exposes the full list of Codex models (e.g., gpt-5.6-sol, gpt-6-astra, open‑source gpt-oss-120b) with plan‑based routing, suffixes for inference level (-fast, -high, -ultra), and rich metadata.
• Image generation – Via the image_generation tool on the /v1/responses endpoint, forwarding to the internal gpt-image-2 model.

How to get it

• Desktop installer – Download a platform‑specific .exe, .dmg or AppImage from the Releases page, run, log in with a ChatGPT account, then open http://localhost:8080.
• No‑Node “lite” bundle – A zip that contains the same backend but expects you to have Node 20+. Run the provided codex‑proxy.exe/codex‑proxy.sh (or use --mode=server for headless operation).
• npm‑style package – Download the offline zip, run node install.mjs, then start with the codex‑proxy command (requires Node 22+).
• Docker – One‑liner:

  docker run -d --name codex-proxy -p 127.0.0.1:8080:8080 \
    -v codex-proxy-data:/app/data -v codex-proxy-config:/app/config \
    ghcr.io/icebear0828/codex-proxy:latest-lite
  

  A compose file is also provided for more options (memory limits, Watchtower auto‑updates, Ollama bridge, etc.).
• From source – git clone … && npm install && cd web && npm install && npm run dev (development) or npm run build && npm start (production). Rust toolchain is needed to compile the native TLS addon, but the Docker and binary releases ship pre‑built binaries.

Typical usage

# after logging in, obtain the proxy API key from the web UI
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your‑proxy‑key>" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"Hello!"}],"stream":true}'

The response streams just like a normal OpenAI endpoint.

Client integration examples

• Claude Code (CLI) – Set ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY to point at the proxy.
• Codex CLI – Add a provider entry in ~/.codex/config.toml with base_url = "http://localhost:8080/v1" and wire_api = "responses".
• Claude Desktop – Enable developer mode and configure a third‑party inference gateway pointing to http://127.0.0.1:8080 with the proxy key.
• Any OpenAI‑compatible SDK – Just point the SDK’s base URL to http://localhost:8080/v1 and use the supplied key.

Why it matters

• Gives you a single local gateway for many AI‑coding tools, avoiding the need for each client to manage its own ChatGPT login.
• Keeps traffic on‑device and lets you control which accounts are used, which can help stay within free‑tier limits or balance load across multiple paid accounts.
• The Rust TLS fingerprinting makes the proxy indistinguishable from the official Codex desktop client, reducing the chance of upstream blocks.

License – Non‑commercial only (as indicated by the badge).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.