Codex Guide

Codex is an AI Agent tool designed for code generation, modification, and review.

This test covered only the CLI request with a regular key described above. Codex App, CC-Switch import, auth.json authentication, WebSocket, and remote compaction were not tested in this run.

Installation

Choose an installation method based on your workflow.

Codex App is suitable for users who prefer a graphical interface.

Choose the installer for your system:

• Codex App for Windows
• Codex App for macOS (Apple Silicon)
• Codex App for macOS (Intel)

After downloading, follow the system prompts to install and launch it.

Codex CLI is recommended for terminal usage.

Installation:

npm install -g @openai/codex

Verify installation:

codex --help

If the command prints help information, installation succeeded.

Without global installation, you can run Codex on demand with npx.

npx @openai/codex

On first run, npx downloads and executes Codex automatically. This is useful when:

• You do not want to modify the global environment.
• You only need to run it once on a machine.
• You want to test whether the CLI meets your needs.

If you use it frequently later, global installation is recommended for faster startup.

Connect to TokenFlux

After installation, choose one of the following methods to connect Codex to TokenFlux.

Using CC-Switch is recommended for centralized configuration.

Steps:

1. Follow Create API Key to generate an API key.
2. In the key list, click "More" on that key and choose "Import to CCS", then confirm the import in the CC-Switch window. See CC-Switch for details.
3. Enable the imported TokenFlux provider on the Codex page in CC-Switch.
4. Restart Codex or Codex App.

Step 1: Locate the config directory

The local config directory for Codex is:

• Windows: %userprofile%\.codex
• macOS / Linux: ~/.codex

Codex CLI and official IDE extensions share the config.toml configuration layer. When using Codex via Zed's external Agent, configuration loading depends on the installed integration version.

Start Codex or Codex App once first so it can initialize the config directory automatically.

Step 2: Write config.toml

Use gpt-6-astra or gpt-6.1-sol, depending on the models supported by your key’s group. The example below uses gpt-6-astra.

Create or edit config.toml in the config directory, and make sure the following content is near the top of the file:

model_provider = "tokenflux"
model = "gpt-6-astra"
review_model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

[model_providers.tokenflux]
name = "OpenAI"
base_url = "https://tokenflux.dev/v1"
wire_api = "responses"
requires_openai_auth = true

Step 3: Write auth.json

Create or edit auth.json in the same directory:

{
  "OPENAI_API_KEY": "YOUR_TOKENFLUX_API_KEY"
}

Replace YOUR_TOKENFLUX_API_KEY with your actual API key.

WebSocket version (optional)

To use WebSocket, merge supports_websockets = true into the existing [model_providers.tokenflux] table and enable responses_websockets_v2 under [features]. The following shows the merged provider configuration; keep only one copy of each table in the file.

[model_providers.tokenflux]
name = "OpenAI"
base_url = "https://tokenflux.dev/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true

[features]
responses_websockets_v2 = true

Sandbox network access (optional)

If you use the workspace-write sandbox and need commands inside it to access the network, set the following in the [sandbox_workspace_write] table in config.toml:

[sandbox_workspace_write]
network_access = true

This controls network access for sandboxed commands, not Codex's own connection to the model API. See the official configuration reference for other sandbox modes and network settings.

About Remote Compaction

Codex compacts conversation history when a long session approaches the context limit. The compaction method depends on the client version, provider capability settings, and server support.

This guide retains name = "OpenAI" for compatibility with existing configurations. Some versions use that name to select default capabilities; current versions also support explicit provider capability settings, so the display name alone does not determine whether compaction is remote. The remote protocol also changes between versions: the 0.162 series includes an implementation that sends compaction_trigger through Responses requests.

If compaction fails, record the Codex version, group, model, and full error, then follow How to Report a Problem. Provider capability fields are listed in the official configuration reference.

About codex-auto-review

The ChatGPT, ChatGPT (Azure), and ChatGPT (不稳定) groups currently redirect codex-auto-review to gpt-6.1-sol by default.

To use another model, configure a model redirect for your key on the API keys page. The target model must be available in the selected group; check its price in the model marketplace.