xiaomingchen/codex2api: Codex2API 是一个基于 Go + Gin + React/Vite 的 Codex 反向代理与管理后台项目 · GitHub

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

• Demo URL: https://codex2api-latest-vu8j.onrender.com
• Demo password: codex2api

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

Screenshots 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

• Live Demo
• Screenshots
• Sponsors
• Quick Start
• Documentation
• Upgrade and Local Development
• Configuration
• Public API
  • Token Upload and Account Management
• Admin Dashboard
• Core Capabilities
• Project Structure
• Notes
• Disclaimer and License
• Star History
• Links

Want to appear here? Open an issue on GitHub.

For detailed deployment instructions, see DEPLOYMENT.md.

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 codex2api

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

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

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

After startup:

• Admin dashboard: http://localhost:8080/admin/
• Health check: http://localhost:8080/health

Notes:

• Standard and SQLite modes both read .env.
• Before switching deployment modes, replace .env with the matching example file.
• The SQLite lightweight mode runs a single codex2api container and stores data at /data/codex2api.db.
• SQLite compose files bind to 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.
• The image studio library is stored under /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.

Upgrade the standard image deployment:

git pull && docker compose pull && docker compose up -d && docker compose logs -f codex2api

Back up the database before upgrading:

docker exec codex2api-postgres pg_dump -U codex2api codex2api > backup_$(date +%Y%m%d_%H%M%S).sql

Restore from a backup if needed:

docker exec -i codex2api-postgres psql -U codex2api codex2api < backup_xxx.sql

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

Vite proxies /api and /health to the backend. During development, open http://localhost:5173/admin/.

For the full configuration reference, see CONFIGURATION.md.

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, TestConcurrency, ProxyURL, PgMaxConns, RedisPoolSize, AdminSecret, SchedulerMode, and auto-cleanup switches.

Default settings are written automatically on first startup.

• Public API keys come from the database API Keys table. If no key is configured, /v1/* skips API key authentication.
• Admin Secret priority:
  • If ADMIN_SECRET is set in .env, the environment variable wins.
  • Otherwise, the database AdminSecret value is used.
  • After login, the frontend sends X-Admin-Key when calling /api/admin/*.

Pricing: gpt-5.5 is billed at $5.00/M input and $30.00/M output (standard tier). Priority tier: $12.50/M input, $75.00/M output. Other models follow pricing rules in the billing engine.

See API.md for full request formats, response formats, and error codes.

The following admin endpoints require the X-Admin-Key header.

# Single account
curl -X POST http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-account", "refresh_token": "rt_xxxxxxxxxxxx"}'

# Batch import, newline separated, up to 100 tokens per request
curl -X POST http://localhost:8080/api/admin/accounts \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "batch", "refresh_token": "rt_xxx1\nrt_xxx2\nrt_xxx3"}'

# Single AT-only account
curl -X POST http://localhost:8080/api/admin/accounts/at \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-at", "access_token": "eyJhbGciOiJSUzI1NiIs..."}'

# Batch import, newline separated
curl -X POST http://localhost:8080/api/admin/accounts/at \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"access_token": "eyJtoken1...\neyJtoken2...\neyJtoken3..."}'

# Import Refresh Tokens from TXT, one token per line
curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@tokens.txt" \
  -F "format=txt"

# Import Refresh Tokens from JSON
curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@credentials.json" \
  -F "format=json"

# Import Access Tokens from TXT, one token per line
curl -X POST http://localhost:8080/api/admin/accounts/import \
  -H "X-Admin-Key: your-admin-secret" \
  -F "file=@access_tokens.txt" \
  -F "format=at_txt"

Import endpoints deduplicate tokens automatically. Existing tokens are not inserted again.

Codex2API supports acquiring Refresh Tokens through the OAuth PKCE flow, useful when manual token extraction is impractical:

# Step 1: Generate an authorization URL
curl -X POST http://localhost:8080/api/admin/oauth/generate-auth-url \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{}'

# Step 2: Open the returned auth_url in a browser, complete authorization
# Step 3: Exchange the authorization code for a token (auto-creates account)
curl -X POST http://localhost:8080/api/admin/oauth/exchange-code \
  -H "X-Admin-Key: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "...", "code": "...", "state": "..."}'

See API.md for the full OAuth flow and all admin endpoints.

Open /admin/ in a browser.

Codex2API is not just a forwarding proxy. It is a long-running Codex gateway with a full admin dashboard:

• Exposes a unified OpenAI-style API surface.
• Maintains a Refresh Token account pool and Access Token lifecycle.
• Coordinates persistence and runtime state through PostgreSQL + Redis or SQLite + in-memory cache.
• Provides operational observability through the /admin dashboard.

Public request flow:

Client -> Gin RPM limiter -> proxy.Handler API key check -> auth.Store scheduler -> upstream request -> response + usage logging

Admin flow:

Browser -> embedded /admin frontend -> /api/admin/* -> database / account pool / cache layer

The scheduler lives in auth.Store. It evaluates availability, health tier, dynamic concurrency, historical errors, and recent usage before selecting an account.

Runtime state:

• Status: ready, cooldown, error
• HealthTier: healthy, warm, risky, banned
• SchedulerScore: real-time scheduling score based on a baseline of 100
• DynamicConcurrencyLimit: concurrency limit adjusted by health tier

Selection strategy:

1. Filter unavailable accounts, including error, banned, cooldown accounts, and accounts without an Access Token.
2. Recompute health tier, scheduler score, and dynamic concurrency.
3. Exclude accounts that have reached their concurrency limit.
4. Prefer healthy > warm > risky > banned; within the same tier, prefer higher score and lower concurrency.
5. Apply a 15% random shuffle to reduce hotspots and starvation.

Concurrency rules:

Observability:

• GET /api/admin/accounts shows health tier, scheduler score, and penalty details.
• GET /api/admin/ops/overview shows runtime and connection pool state.
• /admin/ops/scheduler provides the scheduler board.

Scheduler mode (scheduler_mode, via Admin Settings):

Credit accounts (per-account flags):

When an account has a credit-based billing model instead of a usage-based Free/Pro plan, you can mark it so the scheduler skips usage-window penalties:

Windowed USD cost: The accounts table displays per-account billed cost over two windows -- the past 5 hours and the past 7 days -- aligned with each account's usage reset boundaries. This shows actual spending per account rather than estimated token costs.

codex2api/
|- main.go                      # Application entrypoint
|- Dockerfile                   # Multi-stage image build
|- docker-compose.yml           # Image deployment template
|- docker-compose.local.yml     # Local source build template
|- .env.example                 # Environment variable example
|- admin/                       # Admin API
|- auth/                        # Account pool, scheduler, token management
|- cache/                       # Redis and cache wrappers
|- config/                      # Environment loading
|- database/                    # Database access layer
|- proxy/                       # Public proxy, forwarding, rate limiting
`- frontend/                    # React + Vite admin dashboard
   |- src/pages/                # Dashboard / Accounts / API Keys / Proxies / Images / Prompt Filter / Ops / Usage / Settings / Docs
   |- src/components/           # UI components
   |- src/locales/              # zh/en locales
   `- vite.config.js            # Vite config

• docker-compose.yml pulls the GHCR image for deployment. docker-compose.local.yml uses build: . for local source builds.
• The frontend base path is fixed at /admin/ for both local development and production.
• Before manually building the Go binary, run npm run build in frontend/.
• .env controls physical runtime settings such as port, database, and Redis. Business settings are stored in the database and managed from the admin dashboard.
• API keys are stored in the database and configured through the admin dashboard.

• This project is for learning, research, and technical discussion only.
• This project is released under the MIT License.
• The project provides no warranty for direct or indirect consequences. Production use is at your own risk.

• LINUX DO