Codex2API 是一个基于 Go + Gin + React/Vite 的 Codex 反向代理和管理后台项目
English | 中文
Turn a Codex account pool into an observable, schedulable, operations-ready OpenAI / Anthropic compatible gateway. Codex2API is not a thin forwarding proxy. It is a long-running Codex access hub: it exposes /v1/chat/completions, /v1/responses, /v1/messages, Images, Videos (Grok Imagine), and Models endpoints while managing Refresh Token / Access Token accounts, health scoring, dynamic concurrency, rate-limit recovery, usage tracking, and admin operations behind the scenes.
Run it as a full PostgreSQL + Redis production stack or as a single-container SQLite + in-memory cache deployment. Point Codex CLI, Claude Code, the OpenAI SDK, or any compatible client at one Base URL, then manage accounts, proxies, API keys, prompt filtering, image workflows, and runtime settings from the built-in dashboard.
| One compatible gateway | OpenAI-style Chat Completions / Responses / Images, Anthropic Messages, prefixless compatibility routes, and native Codex Responses forwarding are all exposed through one service. |
| Account-pool scheduler | Selection is driven by account status, health tier, scheduler score, dynamic concurrency, cooldown recovery, and recent usage so unhealthy accounts are avoided automatically. Supports round_robin and remaining_quota modes, with per-account credit billing flags. |
| Visual admin console | The embedded React / Vite dashboard covers account import and testing, API keys, proxy pools, image studio (text-to-image + image-to-image), prompt filtering, usage analytics, operations, scheduler board, and system settings. |
| Two deployment shapes | Use PostgreSQL + Redis for production or SQLite + Memory for lightweight single-node deployments; Docker images, source builds, local development, and the interactive deploy script are ready to use. SQLite mode binds to 127.0.0.1 by default for security. |
| Billing and observability | Per-account 5h/7d windowed USD cost tracking, credit quota support, API key usage tracking, OAuth PKCE token acquisition, prompt filtering, and a usage dashboard with request logs and trend charts. |
| Quality check | Compare selected accounts, models, and reasoning effort with an editable pelican-on-a-bicycle HTML/SVG animation challenge. Run up to three background tests across accounts, keep persistent test history, and review isolated animation previews, source, timing/token metrics, and HTML downloads. |
codex2apiThe demo is only for trying the admin dashboard and basic UI flows. Do not upload real Refresh Tokens, Access Tokens, API keys, or any other sensitive data.
More admin dashboard screenshotsScreenshots use demo data. The actual dashboard depends on your account pool, request logs, and runtime environment.
| Accounts | Dashboard Trends |
|---|---|
| Image Studio | Prompt Filter |
|---|---|
| Operations | Usage |
|---|---|
| Usage Guide | API Reference |
|---|---|
For detailed deployment instructions, see DEPLOYMENT.md.
| Mode | File | Use Case |
|---|---|---|
| Docker image deployment | docker-compose.yml |
Recommended for servers and test environments using the prebuilt image |
| Local source container build | docker-compose.local.yml |
Full container verification after local source changes |
| SQLite lightweight deployment | docker-compose.sqlite.yml |
Single-node deployment without PostgreSQL or Redis |
| SQLite local source build | docker-compose.sqlite.local.yml |
Local source verification for the lightweight SQLite mode |
| Local development | go run . + npm run dev |
Backend and frontend development |
Standard image mode:
git clone https://github.com/james-6-23/codex2api.git
cd codex2api
cp .env.example .env
docker compose pull
docker compose up -d
docker compose logs -f codex2apiStandard local build mode:
cp .env.example .env
docker compose -f docker-compose.local.yml up -d --build
docker compose -f docker-compose.local.yml logs -f codex2apiSQLite image mode:
cp .env.sqlite.example .env
docker compose -f docker-compose.sqlite.yml pull
docker compose -f docker-compose.sqlite.yml up -d
docker compose -f docker-compose.sqlite.yml logs -f codex2apiSQLite local build mode:
cp .env.sqlite.example .env
docker compose -f docker-compose.sqlite.local.yml up -d --build
docker compose -f docker-compose.sqlite.local.yml logs -f codex2apiAfter startup:
http://localhost:8080/admin/http://localhost:8080/healthNotes:
.env..env with the matching example file.codex2api container and stores data at /data/codex2api.db.127.0.0.1 by default for security. To expose the SQLite service on all interfaces, set BIND_HOST=0.0.0.0 in .env or override the port binding in the compose file. The standard compose files bind to 0.0.0.0 by default./data/images; uploaded admin backgrounds are stored under /data/backgrounds; Docker configurations persist /data.docker compose down does not delete named volumes by default. Data is removed only by commands such as docker compose down -v, docker volume rm, or docker volume prune.Antigravity accounts are managed as a dedicated Google channel with browser/imported OAuth credentials and an optional Google API Key credential shape. Admin tooling includes secret-bearing JSON/ZIP credential export plus sanitized state, explicit control-plane sync, and bounded capability probing. OAuth requests use the Cloud Code v1internal adapter. API Key requests target the Generative Language v1beta/interactions endpoint, but ordinary API-key dispatch is fail-closed by default and requires ANTIGRAVITY_ENABLE_EXPERIMENTAL_INTERACTIONS=true. The opt-in real-upstream integration test has not succeeded in this environment, so this path remains experimental rather than production-certified. See docs/ANTIGRAVITY.md for endpoints, test instructions, models, channel restrictions, plaintext credential-storage risk, and the certification checklist.
| Document | Description | Path |
|---|---|---|
| Chinese README | Main Chinese project overview | README.zh-CN.md |
| Usage Guide | Client setup, SDK examples, media workflows, and troubleshooting | docs/USAGE.md |
| API Documentation | API endpoints, request and response examples, error codes | docs/API.md |
| Antigravity Integration | Google OAuth and experimental API Key channel, models, risks, and protocol status | docs/ANTIGRAVITY.md |
| Deployment Guide | Deployment modes, upgrade guide, backup and restore | docs/DEPLOYMENT.md |
| Configuration Guide | Environment variables, system settings, configuration priority | docs/CONFIGURATION.md |
| Architecture | System architecture, scheduling algorithm, storage design | docs/ARCHITECTURE.md |
| Troubleshooting | Common issues, diagnostic scripts, fixes | docs/TROUBLESHOOTING.md |
| Contributing | Development rules, PR workflow, code standards | docs/CONTRIBUTING.md |
Upgrade the standard image deployment:
git pull && docker compose pull && docker compose up -d && docker compose logs -f codex2apiBack up the database before upgrading:
docker exec codex2api-postgres pg_dump -U codex2api codex2api > backup_$(date +%Y%m%d_%H%M%S).sqlRestore from a backup if needed:
docker exec -i codex2api-postgres psql -U codex2api codex2api < backup_xxx.sqlUnless you explicitly need to recreate resources, avoid docker compose down during upgrades. pull + up -d keeps existing containers and named volumes.
Backend:
cp .env.example .env
cd frontend && npm ci && npm run build && cd ..
go run .The frontend must be built before the first backend run because Go embeds frontend/dist through go:embed.
Frontend dev server:
cd frontend && npm ci && npm run devVite proxies /api and /health to the backend. During development, open http://localhost:5173/admin/.
For the full configuration reference, see CONFIGURATION.md.
| Variable | Description |
|---|---|
CODEX_PORT |
HTTP port, default 8080 |
CODEX_MAX_REQUEST_BODY_SIZE_MB |
HTTP request body limit in MB, default 48 |
ADMIN_SECRET |
Admin dashboard secret. When set, /admin prompts for authentication |
DATABASE_DRIVER |
Database driver: postgres or sqlite |
DATABASE_PATH |
SQLite database file path, used when DATABASE_DRIVER=sqlite |
DATABASE_HOST |
PostgreSQL host |
DATABASE_PORT |
PostgreSQL port, default 5432 |
DATABASE_USER |
PostgreSQL user |
DATABASE_PASSWORD |
PostgreSQL password |
DATABASE_NAME |
PostgreSQL database name |
DATABASE_SSLMODE |
PostgreSQL SSL mode, default disable |
CACHE_DRIVER |
Cache driver: redis or memory |
REDIS_ADDR |
Redis address, for example redis:6379, redis://default:pass@host:6379/0, or rediss://default:pass@host:6379/0 |
REDIS_USERNAME |
Optional Redis ACL username |
REDIS_PASSWORD |
Redis password |
REDIS_DB |
Redis database number |
REDIS_TLS |
Enable TLS for host:port Redis addresses |
REDIS_INSECURE_SKIP_VERIFY |
Skip Redis TLS certificate verification, default false |
TZ |
Timezone, for example Asia/Shanghai |
Cloud Redis providers such as Aiven and Upstash often require TLS. Prefer a rediss://... URL when your provider gives one.
The standard .env.example declares DATABASE_DRIVER=postgres and CACHE_DRIVER=redis. For the lightweight SQLite mode, use .env.sqlite.example.
Runtime business settings are stored in the database SystemSettings table and can be updated from the admin settings page.
Examples include MaxConcurrency, GlobalRPM, TestModel, TestContent, TestConcurrency, ProxyURL, PgMaxConns, RedisPoolSize, AdminSecret, SchedulerMode, and auto-cleanup switches.
Default settings are written automatically on first startup.
Locally reconstructed HTTP Responses continuations that use previous_response_id are protecte
暂无开放 Issues，或尚未同步最近议题。