codex-cc 0.1.0

A lightweight local bridge that translates OpenAI Responses API calls to DeepSeek Chat Completions API — enabling Codex CLI and other OpenAI-compatible tools to use DeepSeek models.

codex-cc

A lightweight local bridge that translates OpenAI Responses API calls to DeepSeek Chat Completions API — enabling Codex CLI, Claude Code, and other OpenAI-compatible tools to use DeepSeek models.

---

Why codex-cc?

The problem: Codex CLI, Claude Code, and many AI coding tools speak the OpenAI Responses API protocol. DeepSeek, like most open-source model providers, exposes a Chat Completions API — these two protocols are incompatible.

The solution: codex-cc runs a local adapter at 127.0.0.1:8787 that translates between the two protocols transparently. Your tools talk to it as if it were OpenAI; it talks to DeepSeek in the background.

  Codex CLI / Claude Code / OpenAI SDK
         │
         │ OpenAI Responses API (SSE streaming)
         ▼
  ┌─────────────────────────┐
  │       codex-cc          │     127.0.0.1:8787
  │                         │
  │  Responses ↔ Chat       │
  │  Protocol Translation   │
  └──────────┬──────────────┘
             │
             │ DeepSeek Chat Completions API
             ▼
       api.deepseek.com

---

Quick Start

1. Install

pip install codex-cc

2. Configure

codex-cc setup

The interactive wizard will ask for:

• DeepSeek API Key — get one at platform.deepseek.com
• Bridge API Key — auto-generated (used by your tools to authenticate)
• Port — defaults to 8787
• Host — defaults to 127.0.0.1 (local only)

3. Run

codex-cc run

You should see:

🚀  codex-cc v0.1.0 starting...
    Listening: http://127.0.0.1:8787
    Model:     deepseek-v4-flash
    Health:    http://127.0.0.1:8787/healthz

4. Verify

# Health check
curl http://127.0.0.1:8787/healthz

# Send a test request
curl -X POST http://127.0.0.1:8787/v1/responses \
  -H "Authorization: Bearer YOUR_BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello, what is 2+2?", "model": "deepseek-v4-flash"}'

5. Connect Your Tool

Codex CLI: Set your OpenAI base URL to http://127.0.0.1:8787/v1 and API key to your bridge key.

Claude Code: Configure the model provider to use http://127.0.0.1:8787/v1 as the Responses API endpoint.

Any OpenAI SDK: Point base_url to http://127.0.0.1:8787/v1.

---

CLI Reference

Command	Description
codex-cc run	Start the bridge server
codex-cc setup	Interactive configuration wizard
codex-cc status	Check if the bridge is running
codex-cc diagnose	Check environment and troubleshoot issues
codex-cc update	Check for new versions
codex-cc --version	Show version

codex-cc setup

Interactive configuration stored in ~/.codex-cc/.env:

🧙  codex-cc setup — Interactive Configuration

Step 1/4: DeepSeek API Key
  DeepSeek API Key: [your-key-here]

Step 2/4: Bridge API Key
  Bridge API Key [auto-generated]:

Step 3/4: Port
  Port [8787]:

Step 4/4: Host
  Host [127.0.0.1]:

Setup also validates your API key by connecting to DeepSeek.

codex-cc diagnose

Runs 5 checks to identify common issues:

🔍  codex-cc diagnostics

  [1/5] Python      ✅  Python 3.12.2
  [2/5] Config      ✅  C:\Users\you\.codex-cc\.env
  [3/5] DeepSeek Key ✅  sk-abc1****f9x
  [4/5] Port 8787   ✅  Available
  [5/5] DeepSeek API ✅  Connected. Models: deepseek-v4-flash, deepseek-v4-pro

---

Configuration

All configuration is stored in ~/.codex-cc/.env. You can also set these as environment variables.

Variable	Default	Description
DEEPSEEK_API_KEY	—	Your DeepSeek API key (required)
CODEX_CC_BRIDGE_KEY	auto-generated	Key clients use to authenticate
CODEX_CC_HOST	127.0.0.1	Bind address
CODEX_CC_PORT	8787	Listen port
DEEPSEEK_MODEL	deepseek-v4-flash	Default model name
DEEPSEEK_FORCE_MODEL	true	Override client's model name
DEEPSEEK_BASE_URL	https://api.deepseek.com/v1	DeepSeek API endpoint
STREAM_TIMEOUT_SEC	600	Streaming request timeout
CODEX_CC_CORS_ORIGINS	—	Comma-separated allowed CORS origins (empty = no CORS)

Legacy support: codex-cc also reads the older env var names (DEEPSEEK_BRIDGE_API_KEY, BRIDGE_HOST, BRIDGE_PORT, DEEPSEEK_MODEL) if the new names are not set. No migration needed if you're upgrading from the original bridge.

---

API Endpoints

GET /healthz

Returns the bridge status and configuration summary.

POST /v1/responses

The main proxy endpoint. Accepts standard OpenAI Responses API requests and translates them to DeepSeek Chat Completions.

Supports:

• Text generation
• Streaming (SSE)
• Tool / Function calling
• Reasoning content
• Instructions / system prompts

POST /v1/responses/compact

Context compaction endpoint for long-running Codex sessions. Summarizes the conversation history to fit within context limits.

---

Security

• Bound to 127.0.0.1 by default — not exposed to the network.
• Bridge API key required for all requests to /v1/responses.
• API key sanitization — error messages are scrubbed of potential key leaks.
• No CORS by default — browser-based cross-origin access is disabled unless explicitly enabled via CODEX_CC_CORS_ORIGINS.
• File permissions — .env file is created with owner-only read/write on Unix systems.
• Log rotation — logs are capped at 10 MB with 3 backup files.

Warning: If you set CODEX_CC_HOST=0.0.0.0, the bridge will be accessible to anyone on your local network. Use a firewall or restrict access appropriately.

---

Troubleshooting

Problem	Likely Cause	Solution
Connection refused	Bridge not running	Run codex-cc run
401 Unauthorized	Wrong bridge key	Run codex-cc setup to regenerate
502 Bad Gateway	DeepSeek API unreachable	Check your network / API key / proxy settings
Port 8787 already in use	Another service on that port	codex-cc setup to change port, or kill the other process
Antivirus flags the binary	PyInstaller false positive	Use pip install codex-cc instead of the binary

Run codex-cc diagnose for an automated environment check.

---

Comparison with Similar Projects

Project	Language	Focus
codex-cc	Python	Minimal, auditable DeepSeek bridge — ~200 LOC core
AI Adapter	Rust	High-performance proxy for Codex CLI
Responses Proxy	Rust	Bidirectional Responses ↔ Chat proxy
LLM-Rosetta	Python	Universal protocol translation library
LiteLLM	Python	Enterprise API gateway (100+ models)

codex-cc prioritizes simplicity and auditability over feature breadth. It does one thing — bridge DeepSeek and OpenAI protocols — and does it transparently.

---

Development

# Clone and install in dev mode
git clone https://github.com/your-username/codex-cc
cd codex-cc
pip install -e ".[dev]"

# Run tests
pytest tests/

# Build package
pip install build
python -m build

---

License

MIT — see LICENSE.

---

🌏 中文指南 / Chinese Guide

codex-cc 是一个轻量级的本地桥接工具，将 OpenAI Responses API 协议转换为 DeepSeek Chat Completions 协议，让 Codex CLI、Claude Code 等 AI 编码工具可以使用 DeepSeek 模型。

快速开始

# 1. 安装
pip install codex-cc

# 2. 配置（会引导你输入 API Key）
codex-cc setup

# 3. 一键启动桥接 + Codex
codex-cc launch

配置要求

• DeepSeek API Key — 在 platform.deepseek.com 注册获取
• Python 3.10+ — 建议使用 Python 3.12

中文环境

如果你是 Codex 桌面版用户且希望使用中文界面，运行项目提供的脚本：

# Windows PowerShell
powershell -File scripts/codex-zh.ps1

该脚本会自动设置 ELECTRON_LOCALE=zh-CN 环境变量并启动 Codex 中文版。

常见问题

问题	原因	解决
codex-cc launch 找不到 Codex	Codex 未安装	先手动安装 Codex 桌面版
CC-Switch 用户切换模型	自动注册	codex-cc setup 或 launch 会自动在 CC-Switch 中注册提供商
连接 DeepSeek 超时	网络问题	检查是否需要配置代理
Windows 杀软误报	PyInstaller 打包特征	改用 pip install codex-cc

完整命令参考

codex-cc run        # 前台启动桥接
codex-cc start      # 后台启动桥接
codex-cc stop       # 停止后台桥接
codex-cc setup      # 配置向导
codex-cc status     # 查看状态
codex-cc diagnose   # 环境诊断
codex-cc launch     # 一键启动（桥接 + Codex）
codex-cc update     # 检查更新

项目地址

GitHub: github.com/gtbwpkwjnb-alt/codex-cc

如有问题或建议，欢迎提交 Issue 或 Pull Request。