Imported from reason-machines/codex-skills (skills/codex-manager-rust/SKILL.md). Install upstream with npx skills add reason-machines/codex-skills --skill codex-manager-rust. Copyright stays with the author.

Codex Manager Skill

Skill by ara.so — Codex Skills collection.

Overview

Codex Manager is a Rust-based account pool manager and local gateway for Codex CLI. It provides:

• Account Pool Management: Import, organize, and track multiple Codex accounts with usage quotas
• Platform Key Management: Generate and manage API keys bound to specific models and inference levels
• Local Gateway: OpenAI-compatible API gateway for Codex CLI, Gemini CLI, Claude Code, and third-party tools
• Usage Tracking: Monitor 5-hour + 7-day windows, Code Review, Spark quotas, and reset times
• Plugin System: Extensible Rhai-based plugin architecture with built-in and custom markets
• Aggregation API: Manage third-party upstream forwarding for Codex/Claude classification

Installation

Desktop (Recommended)

Download the latest release for your platform:

• Windows: codexmanager_<version>_x64_en-US.msi
• macOS: codexmanager_<version>_x64.dmg or codexmanager_<version>_aarch64.dmg
• Linux: codexmanager_<version>_amd64.AppImage or .deb

Service Mode (Headless)

# Download service binaries
wget https://github.com/qxcnm/Codex-Manager/releases/latest/download/codexmanager-service
wget https://github.com/qxcnm/Codex-Manager/releases/latest/download/codexmanager-web
wget https://github.com/qxcnm/Codex-Manager/releases/latest/download/codexmanager-start

chmod +x codexmanager-*

# Start service + web
./codexmanager-start

Docker

docker pull qxcnm/codexmanager:latest

docker run -d \
  -p 3000:3000 \
  -p 8787:8787 \
  -v ./data:/app/data \
  -e CODEX_MANAGER_PORT=3000 \
  -e CODEX_MANAGER_WEB_PORT=8787 \
  qxcnm/codexmanager:latest

Configuration

Data Directory

Default database locations:

• Windows: %APPDATA%\com.codexmanager.desktop\codexmanager.db
• macOS: ~/Library/Application Support/com.codexmanager.desktop/codexmanager.db
• Linux: ~/.local/share/com.codexmanager.desktop/codexmanager.db

Environment Variables

# Core settings
export CODEX_MANAGER_PORT=3000              # Service port
export CODEX_MANAGER_LISTEN=0.0.0.0         # Listen address
export CODEX_MANAGER_DATABASE_URL=sqlite:///path/to/codexmanager.db

# Proxy configuration
export CODEX_MANAGER_PROXY=http://127.0.0.1:7890

# Timeout settings
export CODEX_MANAGER_REQUEST_TIMEOUT=300    # Total request timeout (seconds)
export CODEX_MANAGER_STREAM_IDLE_TIMEOUT=60 # SSE idle timeout (seconds)
export CODEX_MANAGER_SSE_KEEPALIVE=15       # SSE keepalive interval (seconds)

# Web security
export CODEX_MANAGER_WEB_PASSWORD=your_secure_password
export CODEX_MANAGER_WEB_PORT=8787

# Concurrency
export CODEX_MANAGER_MAX_CONCURRENT_PER_ACCOUNT=3

Configuration File (config.toml)

[server]
port = 3000
listen = "0.0.0.0"
proxy = "http://127.0.0.1:7890"

[database]
url = "sqlite:///path/to/codexmanager.db"

[timeout]
request = 300
stream_idle = 60
sse_keepalive = 15

[concurrency]
max_per_account = 3

[web]
port = 8787
password = "your_secure_password"

Codex CLI Integration (ccswitch)

Setup auth.json

Create ~/.codex/auth.json:

{
  "default_host": "http://127.0.0.1:3000",
  "hosts": {
    "http://127.0.0.1:3000": {
      "access_token": "your-platform-key-from-codexmanager"
    }
  }
}

Setup config.toml

Create ~/.codex/config.toml:

[client]
host = "http://127.0.0.1:3000"

Verify Connection

# Test with ccswitch
ccswitch list

# Or direct curl
curl http://127.0.0.1:3000/v1/models \
  -H "Authorization: Bearer your-platform-key"

Account Management

Import Accounts

Desktop: Navigate to "Account Management" → "Import Accounts"

API (for automation):

curl -X POST http://127.0.0.1:3000/api/accounts/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "accounts": [
      {
        "email": "user@example.com",
        "access_token": "sess-...",
        "session_token": "eyJhbGc...",
        "group": "default",
        "tags": ["prod", "high-quota"]
      }
    ]
  }'

Refresh Usage

# Refresh all accounts
curl -X POST http://127.0.0.1:3000/api/accounts/refresh-all \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

# Refresh specific account
curl -X POST http://127.0.0.1:3000/api/accounts/{account_id}/refresh \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

Export Accounts

# Export all accounts
curl http://127.0.0.1:3000/api/accounts/export \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -o accounts_export.json

# Export by group
curl "http://127.0.0.1:3000/api/accounts/export?group=production" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -o prod_accounts.json

Platform Key Management

Create Platform Key

curl -X POST http://127.0.0.1:3000/api/platform-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "name": "production-key",
    "key": "[REDACTED openai-key]",
    "models": ["gpt-4", "claude-3-opus-20240229"],
    "inference_level": "high",
    "service_level": "fast",
    "enabled": true
  }'

List Platform Keys

curl http://127.0.0.1:3000/api/platform-keys \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

Bind Models

curl -X PATCH http://127.0.0.1:3000/api/platform-keys/{key_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "models": ["gpt-4o", "claude-3-5-sonnet-20241022"],
    "inference_level": "medium"
  }'

Gateway Usage

OpenAI-Compatible Endpoint

# Chat completions
curl http://127.0.0.1:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-platform-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true
  }'

# Image generation
curl http://127.0.0.1:3000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-platform-key" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic cityscape",
    "n": 1,
    "size": "1024x1024"
  }'

Gemini Forwarding

# Gemini requests auto-forward to /v1/responses
curl http://127.0.0.1:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-platform-key" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ]
  }'

With Tools/MCP

curl http://127.0.0.1:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-platform-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Generate an image of a sunset"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "image_generation",
          "description": "Generate images",
          "parameters": {
            "type": "object",
            "properties": {
              "prompt": {"type": "string"}
            }
          }
        }
      }
    ]
  }'

Model Management

Sync Models

# Sync from remote
curl -X POST http://127.0.0.1:3000/api/models/sync \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

# Export cache (desktop auto-syncs to ~/.codex/models_cache.json)
curl http://127.0.0.1:3000/api/models/export \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -o models_cache.json

Add Custom Model

curl -X POST http://127.0.0.1:3000/api/models \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "id": "custom-gpt-4",
    "name": "Custom GPT-4",
    "visibility": "public",
    "supportedInApi": true,
    "maxTokens": 8192
  }'

Aggregation API

Add Upstream

curl -X POST http://127.0.0.1:3000/api/aggregation/upstreams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "name": "VisionCoder",
    "base_url": "https://api.visioncoder.cn/v1",
    "api_key": "${VISIONCODER_API_KEY}",
    "provider": "codex",
    "priority": 1,
    "enabled": true
  }'

Test Upstream

curl -X POST http://127.0.0.1:3000/api/aggregation/upstreams/{id}/test \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

Plugin System

Plugin Directory Structure

plugins/
├── manifest.json       # Plugin metadata
├── main.rhai          # Entry point
├── tasks/             # Background tasks
└── ui/                # Optional UI components

Example Plugin (manifest.json)

{
  "id": "account-auto-refresh",
  "name": "Auto Refresh Accounts",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Automatically refresh account usage every hour",
  "entry": "main.rhai",
  "permissions": ["accounts.read", "accounts.refresh"],
  "tasks": [
    {
      "name": "refresh-task",
      "schedule": "0 */1 * * *",
      "script": "tasks/refresh.rhai"
    }
  ]
}

Example Plugin (main.rhai)

// Access system API via Rhai built-ins
fn on_install() {
    log_info("Plugin installed");
    
    // Get all accounts
    let accounts = system_call("accounts.list", #{});
    log_info(`Found ${accounts.len()} accounts`);
}

fn on_enable() {
    log_info("Plugin enabled");
}

fn on_task_run(task_name) {
    if task_name == "refresh-task" {
        let accounts = system_call("accounts.list", #{});
        
        for account in accounts {
            if account.enabled {
                system_call("accounts.refresh", #{
                    id: account.id
                });
                log_info(`Refreshed account: ${account.email}`);
            }
        }
    }
}

Install Plugin

# Via API
curl -X POST http://127.0.0.1:3000/api/plugins/install \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "source": "file:///path/to/plugin",
    "market": "custom"
  }'

Common Patterns

Account Rotation Strategy

// Rust service-side logic (for reference)
use codexmanager::{AccountPool, SelectionStrategy};

let pool = AccountPool::new(db).await?;

// Select by lowest usage
let account = pool.select_account(SelectionStrategy::LowestUsage {
    model: "gpt-4o",
    inference_level: "high",
}).await?;

// Select by round-robin
let account = pool.select_account(SelectionStrategy::RoundRobin {
    group: "production",
}).await?;

Rate Limiting

# Set per-account concurrency
curl -X PATCH http://127.0.0.1:3000/api/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "max_concurrent_per_account": 2,
    "enable_conservative_backoff": true
  }'

Health Check

# Check service health
curl http://127.0.0.1:3000/health

# Check account pool status
curl http://127.0.0.1:3000/api/accounts/stats \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

Troubleshooting

Service Won't Start

# Check port availability
netstat -an | grep 3000

# Check logs (desktop)
# Windows: %APPDATA%\com.codexmanager.desktop\logs
# macOS: ~/Library/Logs/com.codexmanager.desktop
# Linux: ~/.local/share/com.codexmanager.desktop/logs

# Check logs (service)
./codexmanager-service --log-level debug

Accounts Not Matching

# Check account hit rules
curl http://127.0.0.1:3000/api/accounts/debug-match \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}" \
  -d '{
    "model": "gpt-4o",
    "inference_level": "high"
  }'

Challenge Interception

If accounts are flagged with challenge/captcha:

1. Check proxy configuration: CODEX_MANAGER_PROXY
2. Reduce concurrency: max_concurrent_per_account
3. Enable conservative backoff in settings
4. Manually re-authorize affected accounts via browser

Model Cache Not Syncing

# Force sync to ~/.codex/models_cache.json
curl -X POST http://127.0.0.1:3000/api/models/sync-local \
  -H "Authorization: Bearer ${CODEX_MANAGER_API_KEY}"

# Verify cache location
cat ~/.codex/models_cache.json

macOS Gatekeeper Block

# Allow unsigned app
xattr -dr com.apple.quarantine /Applications/codexmanager.app

# Or use System Preferences → Security & Privacy → Allow

Database Locked

# Stop all instances
pkill codexmanager

# Remove lock file (if exists)
rm ~/.local/share/com.codexmanager.desktop/codexmanager.db-wal
rm ~/.local/share/com.codexmanager.desktop/codexmanager.db-shm

# Restart service
./codexmanager-start

Additional Resources

• Full Documentation
• Deployment Guide
• Environment Variables Reference
• Plugin Development
• Internal API Reference