Codex: keep official login and history with third-party APIs

Use a BetterToken API Key for model requests while keeping official Codex sign-in. Manual configuration and CC Switch use the same principle: keep official login credentials separate from third-party model credentials.

For API Key file authentication in CLI/App, follow the Codex setup guide. The configuration on this page is a separate alternative for preserving the official login; do not replace its login credentials with the API Key JSON.

Before you begin

Sign in officially in Codex App, Codex CLI, or Extension. Prepare a BetterToken API Key and a full Model ID from the model plaza. CLI, App, and Extension share configuration only when they use the same CODEX_HOME.

BetterToken API Key · model plaza

Configuration methods

Manual configuration

Keep official credentials

Fully quit Codex and back up existing configuration privately. Official credentials may be in auth.json or the OS credential store; keep the current storage mode and do not replace them with API Key JSON. Do not create a fake login file if no file exists.

Edit config.toml

Open user-level config.toml: default ~/.codex/config.toml on macOS / Linux or %USERPROFILE%\.codex\config.toml on Windows; use your custom CODEX_HOME if set. Merge these settings, placing root keys before all TOML tables and avoiding duplicate tables. Replace YOUR_API_KEY locally with your BetterToken API Key.

model_provider = "bettertoken"
model = "gpt-6-astra"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "YOUR_API_KEY"
supports_websockets = false

Keep the credentials created by official sign-in; do not replace them with API Key JSON. requires_openai_auth = true uses the official authentication flow; the current provider’s experimental_bearer_token supplies the third-party Key for model requests. With the former enabled, Codex ignores env_key, so do not directly substitute it for the Bearer Key. Do not share config files containing keys.

Configuration parameters

Parameter	Purpose and location	Defaults and examples
model_provider	User config root; selects the provider ID defined below.	Defaults to openai; this guide uses bettertoken.
model	Root; the full Model ID from the model plaza.	Example: gpt-6-astra; replace as needed.
name	Provider table; a display name only.	BetterToken is not a Model ID.
base_url	Provider table; the model API Base URL.	Use https://bettertoken.ai/v1; Codex appends /responses.
wire_api	Provider table; the request protocol.	Only responses is currently supported; it is also the default.
requires_openai_auth	Provider table; uses OpenAI authentication and its credential store.	Defaults to false; this guide uses true. It is not a switch that preserves login files.
experimental_bearer_token	Provider table; the Bearer Key for third-party requests.	Use your BetterToken API Key; it does not rewrite the official login cache. Supported, but stored as plaintext in config.
supports_websockets	Provider table; Responses WebSocket support.	Defaults to false; this guide keeps HTTP/SSE transport.

Optional model and connection settings

These two settings belong at the root of config.toml. Use them as needed; neither is required to preserve sign-in.

review_model = "gpt-6-astra"
model_reasoning_effort = "high"

Parameter	Purpose and location	Defaults and examples
review_model	Root; the model used by /review.	Optional; defaults to the current session model.
model_reasoning_effort	Root; the model’s reasoning effort.	Example: high; supported levels and defaults depend on the model.

These three settings are optional tuning, not connection requirements. Merge them into the existing [model_providers.bettertoken] table when needed; do not create a duplicate table.

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000

Parameter	Purpose and location	Defaults and examples
request_max_retries	Provider table; maximum HTTP request retries.	Default: 4; adjust for your connection.
stream_max_retries	Provider table; reconnection retries after a stream interruption.	Default: 5; 8 is an optional custom value.
stream_idle_timeout_ms	Provider table; stream inactivity timeout in milliseconds.	Default: 300000; this is an idle timeout, not a total task deadline.

CC Switch configuration

1. In current CC Switch, switch to OpenAI Official, start Codex, and complete official account sign-in.

2. Open Settings → App config → Codex and enable Keep official login for direct switches. This controls direct switching; login stays preserved during routing takeover.

3. Add or activate BetterToken in CC Switch’s Codex page. Use Base URL https://bettertoken.ai/v1, OpenAI Responses API, your BetterToken API Key, and Model ID. BetterToken supports Responses directly; protocol conversion and routing takeover are not required.

4. Save and activate the configuration. The third-party Key goes in the provider settings in config.toml, not official auth.json.

Unified history (optional)

Unified Codex session history affects only the CLI resume list. Current desktop Codex already shows all sessions; desktop-only users do not need the switch. Choose whether to migrate existing history when prompted; CC Switch backs it up first. Continuing across providers can fail because of incompatible encrypted_content; start a new session after switching.

Restart and verify

1. Fully quit and restart the Codex client you use, then start a new session.

2. Confirm official sign-in remains; check plugins or Remote Control in a client that supports those features.

3. Send a short test prompt, confirm the selected Model ID, and check the request in BetterToken usage logs. The displayed account alone does not identify who bills model requests.

Configuration layers and legacy keys

Do not put model or reasoning settings inside [projects."<path>"]. Project-specific models can use root keys in a trusted project’s .codex/config.toml; provider and authentication settings remain in user config. Current named profiles use NAME.config.toml under CODEX_HOME, selected with codex --profile NAME, not legacy [profiles.NAME] tables or the root profile selector.

Troubleshooting

Symptom	Action
401, 403, or a sign-in prompt	Check active CODEX_HOME, official sign-in, and the provider’s third-party Key; do not overwrite official credentials with API Key JSON.
Settings ignored or model unchanged	Place root model keys before all TOML tables, not in [projects."<path>"]. Check CLI, profile, and project overrides.
disable_response_storage or windows_wsl_setup_acknowledged	Remove these legacy keys; do not use them for current setup.
features.code_mode_tool_description_first	If the warning comes from session-flags, check and update the client supplying startup flags. Do not add this switch to user config.
features.guardianv2.thread_context	Remove this key, including profile overrides, while keeping other Guardian settings. Thread context is always enabled.
History visible but continuation across providers fails	Start a new session or use the provider that originally created it.

References

• Codex config.toml
• CC Switch
• OpenAI: configuration reference
• OpenAI: authentication
• CC Switch: official login
• CC Switch v4.0.11