Home

codex-switch Wiki

codex-switch is the multi-account manager for OpenAI Codex CLI. It stores multiple local file-backed Codex logins, monitors quota, selects the best account for the next session, and offers CLI, TUI, daemon, import, warmup, reset-card, and self-update workflows.

Canonical documentation lives in the main repository. Wiki pages are curated entry points and should not be treated as a second implementation specification.

Using codex-switch

• Getting started — install, add an account, and open the dashboard.
• Testing development releases — install the rolling dev build, verify it, and return to stable.
• Feature guide — understand the supported workflows and safety boundaries.
• Troubleshooting — diagnose common failures and recover a profile.
• FAQ — concise answers to user and project questions.

中文读者可以从中文指南开始；详细行为仍以英文主文档为准。

Developing codex-switch

• Architecture overview — understand state ownership and module flow.
• Developer onboarding — prepare a development environment and find the right change boundary.
• Contributing — tests, pull request expectations, and documentation rules.

Important prerequisite

Codex must use its file credential store because codex-switch switches $CODEX_HOME/auth.json. Set this in $CODEX_HOME/config.toml:

cli_auth_credentials_store = "file"

Do not publish auth files, profile files, tokens, unredacted debug output, proxy credentials, account IDs, email addresses, or workspace names.