Codex2API Documentation

Codex2API transforms a pool of Codex accounts into an observable, schedulable, and maintainable gateway that is compatible with OpenAI and Anthropic APIs. It acts as a central hub for long-term Codex access rather than a simple proxy layer.

Key Capabilities:

• Unified Compatible Entry Points: Supports OpenAI-style Chat Completions, Responses, Images, and Models, as well as Anthropic Messages and native Codex Responses forwarding. This allows seamless integration with clients like Codex CLI, Claude Code, or any OpenAI SDK by simply changing the Base URL.
• Account Pool Scheduling: Manages account status, health levels, dynamic concurrency, and rate-limit recovery. It supports round_robin and remaining_quota scheduling modes to automatically avoid unavailable accounts.
• Visual Management Dashboard: A built-in React/Vite admin panel for account testing, API key management, proxy pool configuration, image generation (text-to-image and image-to-image), prompt filtering, usage statistics, and system monitoring.
• Flexible Deployment: Supports production-grade setups using PostgreSQL + Redis, or lightweight single-container deployments using SQLite + In-memory cache.
• Observability & Billing: Provides USD cost tracking (5h/7d windows), credit quota support, API key usage tracking, and usage dashboards with request logs and trend charts.

The Codex2API project documentation is organized into several key areas:

• API Documentation: Covers all API endpoints, request/response examples, error codes, authentication methods, and rate limiting.
• Deployment Documentation: Includes deployment mode overviews, Docker deployment guides, local development setup, production configuration, upgrade guides, and backup/recovery procedures.
• Configuration Documentation: Details environment variables, system settings, configuration file examples, and configuration priority.
• Architecture Documentation: Explains system architecture diagrams, core components, data flow, scheduling system design, storage layer design, and security design.
• Troubleshooting Documentation: Provides guidance on service startup, database issues, account pool issues, API request problems, performance, network/proxy issues, log analysis, and diagnostic scripts.
• Contribution Guide: Outlines development environment setup, code standards, commit specifications, Pull Request processes, testing requirements, and documentation updates.

The scheduler core (auth.Store) selects accounts based on availability, priority, health, dynamic concurrency, historical errors, and recent usage.

Account Selection Strategy

1. Filter unavailable accounts (error, banned, cooldown, or no AccessToken).
2. Recalculate health tier, scheduler score, and dynamic concurrency.
3. Exclude accounts that have reached their DynamicConcurrencyLimit.
4. Sort by SchedulerPriority (high to low), then by health tier (healthy > warm > risky > banned). Within the same priority/tier, optimize for scheduler score and current load.
5. Apply a 15% random shuffle to prevent hotspots and starvation.

Dynamic Concurrency Rules

Scheduler Modes

Set the scheduler_mode via the Admin Dashboard:

• round_robin (default): Rotates through available accounts by health tier, weighted by scheduler score.
• remaining_quota: Prioritizes accounts with lower usage; uses rotation if usage is equal.

The scheduler in auth.Store selects accounts based on availability, priority, health, and concurrency.

Selection Strategy

1. Filter: Removes accounts that are in error, banned, or cooldown status, or those lacking an Access Token.
2. Recompute: Updates health tier, scheduler score, and dynamic concurrency.
3. Concurrency Check: Excludes accounts that have reached their DynamicConcurrencyLimit.
4. Prioritize:
   • Higher SchedulerPriority first.
   • Then Health Tier: healthy > warm > risky > banned.
   • Within the same tier/priority, prefer higher SchedulerScore and lower current concurrency.
5. Shuffle: Applies a 15% random shuffle to prevent hotspots.

Concurrency Tiers

Concurrency limits are adjusted dynamically based on the account's health tier:

Scheduler Modes

Configurable via Admin Settings:

• round_robin (default): Round-robin across available accounts per health tier, weighted by dispatch score.
• remaining_quota: Prioritizes accounts with lower usage percentage; uses round-robin for ties.

Codex2API uses a sophisticated scheduling system to manage multiple accounts. It determines which account to use for a request based on its Health Tier and a calculated Scheduler Score.

Health Tiers

Accounts are categorized into four tiers which directly impact their allowed concurrency:

• Healthy: No recent errors. Uses MaxConcurrency.
• Warm: Minor issues. Uses MaxConcurrency / 2.
• Risky: Serious issues. Uses 1 concurrent request.
• Banned: Unauthorized (401). Uses 0 concurrent requests.

Scheduler Scoring

The system calculates a score to prioritize accounts. The formula is: Final Score = BaseScore (100) + ΣRewards - ΣPenalties.

Penalties (P):

• UnauthorizedPenalty (401): -50 (24h decay)
• RateLimitPenalty (429): -22 (1h decay)
• TimeoutPenalty: -18 (15min decay)
• ServerPenalty (5xx): -12 (15min decay)
• FailurePenalty: -6 per consecutive failure (max -24)
• UsagePenalty7d: -8 if usage ≥70%, -40 if usage ≥100%
• LatencyPenalty: -4 if ≥5s, -15 if ≥20s
• SuccessRatePenalty: -8 if <75%, -15 if <50%

Rewards (B):

• SuccessBonus: +2 per consecutive success (max +12)

Selection Logic

When selecting an account, the system:

1. Filters out accounts that are in error, banned, in cooldown, or missing access tokens.
2. Checks if the account has reached its dynamic concurrency limit based on its HealthTier.
3. Sorts candidates by HealthTier (descending), SchedulerScore (descending), and ActiveRequests (ascending).
4. Applies a 15% chance to randomly pick from the top candidates to ensure distribution.

Codex2API implements a three-level security model:

Authentication Levels

1. Transport Layer: Enforces HTTPS/TLS encryption and HSTS headers.
2. API Authentication: Uses API Key Bearer Tokens. Keys are cached for 5 minutes to minimize database load.
3. Admin Authentication: Requires the X-Admin-Key request header. Configuration can be provided via environment variables or the database.

Data Protection

• Token Storage: Sensitive tokens (like access_token) are encrypted before being stored in the database or Redis.
• Log Sanitization: The system automatically scrubs sensitive information from logs using regex patterns to hide token=... and Bearer ... strings.

Rate Limiting and Protection

• Global: RPM (Requests Per Minute) limiting using a token bucket algorithm.
• Account: Dynamic concurrency limits based on health.
• IP: Connection limits to prevent single-IP abuse.
• Application: Request body size limits.

Codex2API implements rate limiting at both the global and account levels.

Global RPM Limiting

Controlled via the global_rpm setting:

• global_rpm = 0: No rate limiting.
• global_rpm > 0: Enables RPM (Requests Per Minute) limiting.

Account-Level Throttling

The system automatically adjusts concurrency based on account health:

• Healthy: Normal concurrency.
• Warm: Concurrency is halved.
• Risky: Fixed at 1 concurrent request.
• Banned: 0 concurrency (not included in scheduling).

Handling Exhausted Account Pools

When the upstream service returns a 429 (quota exhausted), Codex2API rewrites this to HTTP 503 Service Unavailable and includes a Retry-After header.

Example 503 Response:

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

{
  "error": {
    "message": "账号池额度已耗尽，请稍后重试",
    "type": "server_error",
    "code": "account_pool_usage_limit_reached",
    "plan_type": "free",
    "resets_at": 1712345678,
    "resets_in_seconds": 3600
  }
}

Best Practices for Consumers

1. Monitor X-RateLimit-* response headers if provided.
2. Implement an exponential backoff retry strategy.
3. Explicitly handle 429 and 503 status codes by waiting for the duration specified in the Retry-After header.
4. Avoid sending large bursts of requests in short intervals.