English | 中文

Codex2API turns a Codex account pool into an observable, schedulable OpenAI / Anthropic compatible gateway. It provides Chat Completions, Responses, Messages, Images, Models and administration endpoints while handling account selection, token refresh, health state, rate-limit recovery and usage records.

This repository is a maintained fork with additional billing, upstream monitoring and responsive usage features. Upstream functionality remains available unless it conflicts with the maintained custom behavior described below.

Custom maintenance

• Upstream multiplier discovery: Accounts connected to Sub2API can opt into multiplier discovery. Manual probing and periodic probing are supported, with strict response validation and the last valid value retained for temporary probe failures.
• Multiplier-aware billing: Normal accounts use the official model price. When a valid upstream multiplier is available, user billing and upstream cost estimation keep the official base price and apply the multiplier separately. The account, API key and usage views expose the multiplier and the related cost details.
• Channel health monitoring: Channel availability, probe status, response time and recent failures can be checked from the administration console without waiting for a user request.
• Mobile usage details: Usage cost details, tooltips and account information remain readable and usable on small screens as well as desktop screens.
• Pricing coverage: The maintained pricing mapping covers current upstream model aliases, standard and long-context boundaries, and the fallback path used when a model is not returned by an upstream pricing probe.

Quick start

For the full deployment guide, see docs/DEPLOYMENT.md.

Deployment modes

Mode	File	Use case
Docker image	docker-compose.yml	Recommended for servers and test environments
Local source build	docker-compose.local.yml	Build and verify the current source
SQLite image	docker-compose.sqlite.yml	Single-node deployment without PostgreSQL or Redis
SQLite source build	docker-compose.sqlite.local.yml	Verify the lightweight SQLite mode
Local development	go run . + npm run dev	Backend and frontend development

Standard deployment

git clone https://github.com/JayHome137/codex2api.git
cd codex2api
cp .env.example .env
docker compose pull
docker compose up -d
docker compose logs -f codex2api

Local source build

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 deployment

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

The SQLite compose files bind to 127.0.0.1 by default. Set BIND_HOST=0.0.0.0 when external access is required. The standard compose files bind to all interfaces by default.

After startup:

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

Named volumes are preserved by docker compose down. Use docker compose down -v only when you intentionally want to remove persisted data.

Upgrade and local development

Upgrade a running image deployment:

git pull
docker compose pull
docker compose up -d

Back up PostgreSQL before an upgrade:

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

The frontend must be built before the first backend run because Go embeds frontend/dist:

cp .env.example .env
cd frontend && npm ci && npm run build && cd ..
go run .

For frontend development:

cd frontend && npm ci && npm run dev

Open http://localhost:5173/admin/ during frontend development.

Configuration

The standard .env.example uses PostgreSQL and Redis. The SQLite mode uses .env.sqlite.example.

Variable	Description
CODEX_PORT	HTTP port, default 8080
BIND_HOST	Listen address, for example 127.0.0.1 or 0.0.0.0
ADMIN_SECRET	Admin dashboard login secret
DATABASE_DRIVER	postgres or sqlite
DATABASE_PATH	SQLite database path when DATABASE_DRIVER=sqlite
DATABASE_HOST / DATABASE_PORT	PostgreSQL connection address
DATABASE_USER / DATABASE_PASSWORD / DATABASE_NAME	PostgreSQL credentials and database
CACHE_DRIVER	redis or memory
REDIS_ADDR	Redis address or URL
TZ	IANA timezone, for example Asia/Shanghai

Business settings such as scheduler mode, request limits and billing options are stored in the database and managed from the admin console. See docs/CONFIGURATION.md for the complete reference.

API and administration

Endpoint	Description
POST /v1/chat/completions	OpenAI-compatible Chat Completions
POST /v1/responses	Responses API
POST /v1/messages	Anthropic Messages API
POST /v1/images/generations	Image generation
GET /v1/models	Available models
GET /health	Health check

The main administration pages are /admin/accounts, /admin/api-keys, /admin/usage, /admin/channel-monitors, /admin/settings and /admin/ops. Public API keys and the admin secret are configured from the administration console.

Pricing uses the model pricing table and the custom multiplier state described in Custom maintenance. A failed or unavailable multiplier probe falls back to the official model price.

Documentation

• Deployment
• Usage
• API reference
• Configuration
• Architecture
• Troubleshooting
• 中文说明

Disclaimer and license

This project is provided for learning, research and technical discussion. Use it only where you have the right to access the upstream services and accept responsibility for your deployment. The project is released under the MIT License without warranty.