qxcnm/Codex-Manager

README

CodexManager

_{Website ·
Sponsors}

_{English

中文

Русский

한국어}

_Community

CodexManager manages Codex CLI account pools and provides a local OpenAI-compatible gateway, with a desktop app and a browser-based Service edition.

Interface language: New installations default to Auto-detect, following the language reported by the desktop WebView or browser. Chinese, English, Russian, and Korean are supported; unsupported or unavailable language information falls back to English. You can choose a fixed language in the header or Settings, and saved choices are preserved.

CodexManager has joined the Xuanwu Community, a Rust technical community incubated and operated by the OpenAtom Foundation.

Source Code Note
_{This product was built under my direction with AI: Codex (98%) and Gemini (2%). If you encounter a problem, please communicate respectfully. I do not have enough environments to validate every package and can guarantee only the Windows desktop build. For other platforms, test thoroughly before opening an Issue. Thank you to everyone who reports platform-specific problems and helps with testing.}

Disclaimer
_{This project is intended solely for learning and development; users must comply with the terms of service of the relevant platforms, including OpenAI and Anthropic; the author does not provide or distribute accounts, API keys, or proxy services and is not responsible for specific uses of this software; do not use this project to circumvent rate limits or service restrictions.}

☕ Support the Project

If this project has helped you, donations are welcome!

Alipay	WeChat Pay

Star History

Home Navigation

What you want to do	Go directly to
First launch, deployment, Docker, or macOS allowlisting	Runtime and Deployment Guide
Configure Codex CLI / ccswitch, `auth.json`, and `config.toml`	Runtime and Deployment Guide
Import an account from ChatGPT `/api/auth/session` without logging in through Codex	Chinese guide: Import ChatGPT auth session
Configure ports, proxy, database, Web password, and environment variables	Environment and Runtime Configuration
Troubleshoot account routing, import failures, challenge interception, or request errors	FAQ and Account Routing Rules
Understand why background jobs skip, disable, or deactivate accounts	Background Task Account Skip Notes
Manage models, pricing, routes, instructions policy, and Codex model catalogs	Chinese guide: Model Catalog V2 Management and Billing
Minimal plugin center integration and quick onboarding	Plugin Center Minimal Integration
Integrate with the plugin center, view interfaces, marketplace modes, and Rhai APIs	Plugin Center Integration and Interfaces
View every internal integration interface	System Internal Interface Inventory
Build, package, release, or call scripts locally	Build, Release, and Script Guide

Feature Overview

Account pool management: groups, tags, ordering, notes, ban recognition, and ban filtering.
Batch import/export: multi-file import, recursive JSON folder import on desktop, and per-account single-file export.
Usage display: standard 5-hour + 7-day windows, 7-day-only accounts, and official additional buckets such as Code Review / Spark; refresh shows remaining percentages and reset times consistently.
Quota reset warmup (Chinese guide): enabled by default, sends a short warmup message after an exhausted 5-hour window resets. Enable or disable it per account or in bulk to reduce the wait for the next quota refresh.
Account authorization: chatgpt.com browser OAuth and Device Code login; browser OAuth also supports manually pasting the callback URL.
Platform keys: random or custom fixed keys, disabling, deletion, model binding, reasoning tier, and service tier (follow request / Standard / Fast / Ultrafast / Flex). Keys can be bound to custom account groups and intersected with plan filters so rotation stays inside the authorized pool.
Model management: Model Catalog V2 is the sole runtime source of truth. It supports builtin/custom models, integer input/output/cached-input rates and long-context pricing tiers, account-pool and aggregate-API routes, instructions policy, local JSON preview/commit, and applying selected models to Codex through model_catalog_json.
The current catalog contains 12 built-in rows. gpt-6.1-sol, gpt-6-astra, gpt-6-sol, gpt-6-luna, the three GPT-5.6 models, gpt-5.5, gpt-image-2, and the two Image 2.5 variants make up the 11 models visible by default; only codex-auto-review is hidden.
gpt-5.4 and gpt-5.4-mini retired from Codex with ChatGPT sign-in on August 31, 2026, and gpt-5.2 is also deprecated for that sign-in path; the general API model is not removed by this cleanup. Revision 9 removes their untouched built-ins, while user edits, price tiers, non-default routes, and permission/API-key associations are preserved as custom models. API-key users can also add the same slugs explicitly as custom models.
Aggregate API: manage minimal third-party upstreams, including create, edit, balance, and connectivity tests against configured V2 routes. It does not auto-discover provider models; administrators fetch and selectively link models to Catalog V2, with no legacy provider model pool.
Plugin center: /plugins/ supports built-in curated, enterprise private, and custom source marketplace modes, plus manifests, tasks, logs, and Rhai interfaces.
Skills and plugins: /skills/ separates Skills Installation from Codex Plugin Installation. Skills support built-in and custom GitHub repositories, repository refresh, individual Skill installation, skills.sh search and installation, ZIP/directory import, and installed-item management. Codex plugins retain the full native Marketplace installation flow; .system Skills remain read-only.
Desktop project launcher: bookmark local directories; Windows and macOS open them in the ChatGPT Codex App, while Sessions opens the resume selector in a new terminal with the local CodexManager profile.
Settings: includes a system-derived settings button, per-account concurrency, upstream proxy, total and stream-idle timeouts, SSE keepalive settings and interval, and conservative high-concurrency degradation. Keepalive is enabled by default; disable it with CODEXMANAGER_SSE_KEEPALIVE_ENABLED=0 (or false). Experimental upstream WebSocket is disabled by default; enable it with CODEXMANAGER_USE_WEBSOCKET_UPSTREAM=1.
System internal interface inventory: all desktop/service commands, RPC methods, and built-in plugin functions.
Local service: automatic startup with configurable port and listen address.
Local gateway: one OpenAI-compatible endpoint for Codex CLI, Gemini CLI, Claude Code, and third-party tools; supports Gemini to /v1/responses, SSE, tools, MCP, skills, and request/stream timeouts.
Image generation: injects the official Codex image_generation tool for /v1/responses by default, passes explicitly provided tools through, and provides /v1/images/generations and /v1/images/edits; the Images API compatibility main model defaults to gpt-6-luna, while the injected image tool remains gpt-image-2 and the two Image 2.5 variants are available for explicit selection.

Screenshots

Quick Start

Download a package for your platform from GitHub Releases, launch the desktop app, and click Start Service.
Open Account Management and choose browser authorization or Device Code login for chatgpt.com.
If the browser callback fails, paste the callback URL to complete parsing manually.
Refresh usage and verify account status.

Default Data Directory

The desktop app stores its SQLite database in the application data directory as codexmanager.db.
Windows: %APPDATA%\\com.codexmanager.desktop\\codexmanager.db
macOS: ~/Library/Application Support/com.codexmanager.desktop/codexmanager.db
Linux: ~/.local/share/com.codexmanager.desktop/codexmanager.db
Before first initialization after an upgrade, a codexmanager.db.pre-<version>.bak snapshot is retained in the same directory; retries for the same version do not overwrite it.
Desktop Diagnostics can enable Debug mode, disable ordinary file logs, and open the log directory. Runtime logs are capped at 512 KB; request logs and token/cost statistics are unaffected.
If the UI cannot start, use CodexManager.exe --debug (CodexManager --debug on macOS/Linux). Startup failures display the reason and write startup-error.log to the shown log directory.
For database, proxy, listen-address, and other settings, see Environment and Runtime Configuration.
The Service edition optionally supports SeaORM MySQL/PostgreSQL backends when built with the corresponding driver. Existing SQLite data can be exported read-only and transactionally imported into an empty target database; see the Chinese database switching and offline import guide. Validation with isolated local databases does not establish production acceptance; see the Chinese migration evidence and scope.
Docker defaults to TZ=Asia/Shanghai; Compose inherits the deployment TZ or falls back to Asia/Shanghai. Use the appropriate IANA time zone elsewhere.

Product Views

Desktop

Account Management: import, export, refresh accounts and usage, with low-quota/ban filters and reset times.
Platform Key: bind keys by model, reasoning tier, and service tier, and inspect request logs.
Codex Connection: connect directly through an OpenAI account, directly through an aggregate API that can safely map to Responses, or through the CodexManager local gateway. Account connections write auth.json to switch accounts. Aggregate API and gateway connections preserve auth.json and update only config.toml; the provider field experimental_bearer_token holds the selected aggregate API key for direct aggregate connections or the CodexManager platform key for gateway connections. Direct aggregate-API connections bypass the local gateway and do not appear in gateway request logs.
Model Management: desktop and Web do not write or download ~/.codex/models_cache.json; direct accounts follow the official catalog, while the local gateway uses an independent managed catalog.
Plugin Center: /plugins/ provides marketplace switching, installation, enable/disable, tasks, logs, and Rhai integration.
Skills and Plugins: /skills/ separates Skills and Codex plugins, with repository/skills.sh install, ZIP/directory import, safe uninstall, native Marketplace flow, and read-only system Skills.
Project Launcher: desktop bookmarks local folders; Windows/macOS open them in the ChatGPT Codex App, Sessions uses the local CLI, and Web/Docker do not access device directories.
Settings: manage port, listen address, proxy, timeouts, SSE keepalive, theme, updates, and background behavior.
The local gateway supports existing ChatGPT or API key authentication (auth_mode = "chatgpt" or "apikey") without requiring a particular sign-in method. Gateway setup updates only config.toml, preserves any existing auth.json byte for byte, and does not create an auth file or require ChatGPT login tokens. The cm provider always uses name = "cm" and requires_openai_auth = true, with the platform key in experimental_bearer_token.

Service Edition

codexmanager-service: local OpenAI-compatible gateway.
codexmanager-web: browser management page plus /api/runtime and /api/rpc proxies.
codexmanager-start: starts service + web together.

Common Documentation

Version history: CHANGELOG.md
Contribution guidelines: CONTRIBUTING.md
Architecture: ARCHITECTURE.md
Testing baseline: TESTING.md
Security: SECURITY.md
Model Catalog V2: Chinese guide
Documentation index: Chinese documentation index

Topic Pages

Page	Contents
Runtime and Deployment Guide	First launch, Docker, Service edition, and macOS allowlisting
Environment and Runtime Configuration	Application settings, proxy, listen address, database, and Web security
FAQ and Account Routing Rules	Account routing, challenge interception, import/export, and common errors
Chinese guide: Import ChatGPT auth session	Copy ChatGPT session JSON and batch-import it into the account pool
Background Task Account Skip Notes	Background filtering, disabled accounts, and workspace deactivation
Minimal Troubleshooting Guide	Service startup, request forwarding, and model refresh failures
Plugin Center Integration and Interfaces	Routes, marketplace modes, Tauri/RPC interfaces, manifest fields, and Rhai functions
Build, Release, and Script Guide	Local builds, Tauri packaging, workflows, and script parameters
Release and Artifacts	Platform artifacts, naming, and pre-release behavior
Script and Release Responsibility Matrix	Script responsibilities and usage scenarios
Gateway vs Codex Headers and Params	Gateway forwarding compared with Codex headers and parameters
System Internal Interface Inventory	Desktop, service, and plugin-center interfaces
CHANGELOG.md	Releases, unreleased changes, and full history

Directory Structure

.
├─ apps/                # Frontend and Tauri desktop app
│  ├─ src/
│  ├─ src-tauri/
│  └─ out/
├─ crates/              # Rust core/service
│  ├─ core
│  ├─ service
│  ├─ start              # Starts service + web
│  └─ web                # Service Web UI and /api/rpc proxy
├─ docs/                # Official documentation
├─ scripts/             # Build and release scripts
└─ README.md

Acknowledgements and Reference Projects

Codex (OpenAI): referenced for request flows, login semantics, and upstream-compatible source structure https://github.com/openai/codex
CLIProxyAPI (CPA): referenced for Responses request conversion and tool-call conventions https://github.com/router-for-me/CLIProxyAPI

Contact

WeChat public account: 七线牛马
WeChat: add ProsperGao to join the group and state your purpose
Telegram group: CodexManager TG group