CodexManager
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.
Sponsors
This project is open to sponsorship partnerships, with pricing negotiable. Sponsors may display their brand logo, introduction, and official link in the README and in-project sponsor areas. Exact wording, placement, display period, and launch time are agreed upon by both parties. Partnerships should be relevant to developers or the AI tooling ecosystem and comply with applicable laws and regulations.
Partnership contact: Reach out via WeChat, Telegram, or email at [email protected]; when adding on WeChat, please note “Sponsorship”.
Thanks to the following friends and partners for supporting CodexManager.
Thanks to PatewayAI for sponsoring this project!
PatewayAI focuses on high-quality official model API relay services, with full support for Claude and Codex series models, transparent billing, and enterprise-grade service.
Economy mode starts as low as 5% of standard rates. Register through this link to receive trial credits, join occasional promotions for free credits, and earn up to $150 in two-way referral rewards.
Other supporters: 呆头呆脑, Wonderdch, suxinwl, Hermit, Suifeng023, HK-hub
☕ Support the Project
If this project has helped you, donations are welcome!
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 |
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.
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
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 |
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
Contact
- WeChat public account: 七线牛马
- WeChat: add
ProsperGao to join the group and state your purpose
- Telegram group: CodexManager TG group
