Table of Contents
- TypeScript to Rust: The GPT-5 Codex CLI Transition
- GPT-5 Codex CLI Installation and Initial Authentication
- config.toml Deep Dive and GPT-5 Codex Sandbox Policies
- Codex CLI Execution Modes: TUI, exec, MCP Server
- GPT-5 Codex CLI Guide: Model Family Selection
- Reasoning Effort and Cost Optimization Strategy
- Practical Considerations and Limitations
- Next Steps for GPT-5 Codex: MCP Integration and Agent Pipelines
Many sources still say “just install Codex CLI with npm like before,” but as of 2026, that information is outdated. The original TypeScript-based CLI has been entirely replaced by a Rust implementation, and the configuration file format has changed from JSON to TOML. Following guides written for the previous version can lead to config files not being recognized or sandbox policies not applying as intended. This guide covers the Rust-based Codex CLI’s installation, config.toml setup, sandbox policies, model family selection, and MCP server integration as of 2026.
TypeScript to Rust: The GPT-5 Codex CLI Transition
The first thing to address is the change in the CLI runtime. The original TypeScript CLI has been replaced by a Rust implementation, and accordingly, the configuration file format has shifted from JSON to TOML (~/.codex/config.toml). Any existing .codexrc.json or similar JSON configuration files are no longer read by the CLI.
This transition isn’t a simple refactoring — it’s a breaking change. Leaving old JSON config files in place means Codex CLI falls back to defaults, potentially ignoring intended sandbox policies or model specifications. For existing users, configuration migration is mandatory.
# config.toml
sandbox_mode = "workspace-write"Place this TOML configuration at ~/.codex/config.toml. Key-value pairs from the old JSON config need to be converted to TOML syntax. Since TOML has different quoting rules and nested table syntax compared to JSON, check the Codex Rust CLI README for the supported key list.
JSON-format config files used with the TypeScript CLI are not recognized by the Rust CLI. A new file must be created at
~/.codex/config.toml. Leaving old config files in place won’t break anything, but removing them after backup is recommended to avoid confusion.
GPT-5 Codex CLI Installation and Initial Authentication
Installation itself is straightforward. Two methods are supported: npm global install or Homebrew cask install.
npm install -g @openai/codex
# 또는
brew install --cask codexOn first launch after installation, logging in with a ChatGPT account is recommended. An account subscribed to one of the Plus, Pro, Business, Edu, or Enterprise plans is required. API key authentication is also supported separately. Account login proceeds through a browser-based OAuth flow, while API key authentication involves specifying the key via environment variable or directly in config.toml.
For personal development environments, ChatGPT account login is the most convenient option. For CI/CD pipelines or server environments without a browser, API key authentication is necessary. When both methods are configured simultaneously, the API key may take priority, so sticking with one method is advisable.
One thing to note: as mentioned in the Codex CLI GitHub repository README, the npm package name is scoped as @openai/codex. The name may be similar to unofficial packages from the past, so always verify the @openai scope.
config.toml Deep Dive and GPT-5 Codex Sandbox Policies
The core of Codex CLI’s behavior control lies in the ~/.codex/config.toml file. Sandbox policies are divided into three tiers, each with different filesystem access scopes.
| Sandbox Mode | File Read | File Write | Suitable For |
|---|---|---|---|
| read-only (default) | Entire project | Not allowed | Code review, analysis, Q&A |
| workspace-write | Entire project | Within workspace | Code generation, refactoring, test writing |
| danger-full-access | Entire system | Entire system | System config changes, package install automation |
The fact that the default is read-only is important. Running Codex without additional configuration means there’s no file modification permission, so code generation requests may trigger “permission denied” errors. For regular code generation work, setting sandbox_mode to workspace-write in config.toml is the common practice.
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
# model = "gpt-5.3-codex" danger-full-access is exactly what the name implies — a dangerous mode. It grants write access to the entire system, so it should be avoided on production servers or shared development environments. Safe usage is limited to specific cases like package install automation on a local development machine.
config.toml Key Structure
The full list of configuration keys supported by config.toml is not officially documented. The currently confirmed key is sandbox_mode, and for additional configuration keys, the Codex Rust CLI README should be referenced directly. Configuration keys introduced in unofficial blogs may not actually work, so the TOML examples in the README are the most reliable reference.
The default path for the configuration file is
~/.codex/config.toml. Whether this path can be overridden via environment variable is not specified in the official documentation. If the directory doesn’t exist, run mkdir -p ~/.codex manually before creating the file.
Codex CLI Execution Modes: TUI, exec, MCP Server
The Rust-based Codex CLI provides three execution modes. Each mode has a distinct purpose, so selecting the right one for the task type improves efficiency.
Interactive TUI Mode
Running the codex command without arguments opens a terminal-based interactive interface (TUI). This mode supports real-time back-and-forth code generation, modification, and review — ideal for exploratory work. When executed from a project directory, it recognizes that directory as the workspace.
Non-Interactive Execution Mode (codex exec)
For automation pipelines or scripts, the codex exec mode is the right choice.
codex exec "Summarize this" --ephemeral
codex --sandbox workspace-writeThe --ephemeral flag runs a one-off execution without saving the conversation context. This mode is useful for CI/CD environments where tasks like automated code review, commit message generation, or test code writing are bundled into scripts. The --sandbox flag on the command line can directly specify the sandbox mode, serving as an override for config.toml settings.
MCP Server Mode
Running codex mcp-server starts Codex itself as an MCP server. This mode allows other MCP clients (e.g., IDE extensions, other agents) to invoke Codex’s code generation capabilities as a tool.
The MCP server management commands are:
codex mcp add— Register an external MCP servercodex mcp list— List registered serverscodex mcp get— View details of a specific servercodex mcp remove— Unregister a server
This MCP integration feature didn’t exist in the TypeScript CLI and was added alongside the Rust transition. The ability to place Codex as a node within an agent chain rather than using it as a standalone tool significantly broadens its applicability.
GPT-5 Codex CLI Guide: Model Family Selection
Under the GPT-5 Codex umbrella, several model variants actually exist. Selecting the appropriate model based on task type and requirements is essential for balancing cost and performance.
GPT-5-Codex is a GPT-5 variant optimized for agentic coding. A notable point is that this model is only available through the Responses API. It cannot be called via the legacy Chat Completions API, so endpoint changes are required for API integration.
GPT-5.2-Codex adds reasoning effort control on top of that. Inference depth can be adjusted across four levels — low, medium, high, and xhigh — with support for function calling, structured output, streaming, and prompt caching. Using low for simple code formatting and high or above for complex architecture design optimizes costs effectively.
GPT-5.4 is the latest frontier model that integrates GPT-5.3-Codex’s coding capabilities with general-purpose reasoning. It supports a 1M token context window and is accessible as gpt-5.4 across ChatGPT, API, and Codex.
| Model | Key Features | Recommended Use | API Access |
|---|---|---|---|
| GPT-5-Codex | Optimized for agentic coding | Code generation/modification agents | Responses API only |
| GPT-5.2-Codex | 4-level reasoning effort | Coding tasks requiring cost optimization | Responses API |
| GPT-5.3-Codex | High-performance coding-specific | Large codebase analysis and refactoring | Responses API |
| GPT-5.4 | Coding + general reasoning, 1M context | Mixed coding and general tasks | ChatGPT, API, and Codex |
| GPT-5.4-mini | Lightweight model | Simple tasks, cost reduction | API |
OpenAI’s model documentation recommends gpt-5.3-codex for coding-specific tasks and gpt-5.4-mini for lightweight tasks. However, detailed specs (exact pricing, token limits, rate limits) are difficult to verify from the source as of April 2026 due to access restrictions on certain documentation pages, so the latest information should be reconfirmed before production deployment.
The GPT-5-Codex family operates only through the Responses API, not the legacy Chat Completions API. If existing code uses the
POST /v1/chat/completions endpoint, the API call structure needs to change. The request/response schema differs, so client code modifications are required during migration.
Reasoning Effort and Cost Optimization Strategy
The four reasoning effort levels provided by GPT-5.2-Codex serve as a practical cost reduction mechanism. Using high or xhigh for every request causes token consumption to spike, so adjusting the level based on task complexity is the key.
Recommended Task Types by Level
low — Suited for tasks that require almost no reasoning, such as code formatting, variable renaming, or simple string replacement. Response speed is also the fastest. Setting this as the default in frequently executed CI automation scripts yields significant token savings.
medium — Appropriate for tasks requiring moderate context understanding, such as function-level refactoring, test case generation, or straightforward bug fixes. This level is often sufficient for tasks like recognizing existing patterns in a codebase and generating new code in a consistent style.
high — For tasks demanding deep reasoning: multi-file refactoring, architecture change proposals, or complex algorithm implementations. Also suitable when tracking cross-file dependencies or reverse-engineering the intent behind legacy code. Token consumption increases noticeably at this tier.
xhigh — The highest reasoning depth level. Detailed benchmarks are not available in official documentation, so the actual performance difference compared to high needs to be evaluated through direct testing. This level is used experimentally for design reviews or security audits where maximum quality is required.
The baseline cost optimization strategy is to “set the default to medium and selectively apply high only for complex tasks.” For automated code reviews in CI/CD pipelines, low is often sufficient, and combining it with prompt caching can further reduce costs for repeated requests.
Function calling and structured output features are also supported in GPT-5.2-Codex. When building agent pipelines that receive Codex output as a JSON schema to pass to the next stage, structured output reduces parsing errors. Streaming support is also useful for shortening perceived response times during large-scale code generation.
Practical Considerations and Limitations
An often-overlooked aspect of any GPT-5 Codex CLI guide is the real-world constraints during actual deployment. Some areas remain unverifiable through official documentation, and failing to recognize these can cause problems in production adoption.
Official Documentation Access Restrictions
As of April 2026, some documentation pages on platform.openai.com return 403 responses and cannot be accessed directly. This makes it difficult to verify detailed API specs (exact pricing, token limits, context window sizes) from the original source. Guide pages on help.openai.com are similarly inaccessible for confirming plan-specific pricing and rate limits.
Distinguishing Unverified Information
Details like GPT-5-Codex being Responses API-only and GPT-5.4’s 1M token context window have been identified from API references but haven’t been fully verified due to restricted direct access to source documentation. Before production deployment, model availability and limitations must be confirmed through the OpenAI dashboard or direct API calls.
Common Error Patterns
The most frequently encountered errors when using Codex CLI are permission errors and model access restrictions. A permission denied error signals that sandbox_mode needs to be checked. A model not found or 403 response often means the model isn’t supported under the current plan or is Responses API-only. Checking whether the OPENAI_API_KEY environment variable is set and whether the current plan supports the target model — in that order — resolves most issues.
IDE Extension Configuration
The configuration method for Codex IDE extensions (VS Code, etc.) has not been directly verified in official documentation. Whether the CLI and IDE extension share the same configuration system or the same config.toml requires separate confirmation.
Lack of Localized Guides
No official localized guides exist. All official documentation is in English, so configuration keys and error messages must be referenced from the original English source.
Some config.toml keys introduced in blog posts or community forums may not actually work. Since the full list of supported keys isn’t officially documented, the recommended approach is to use the GitHub README examples as the baseline and remove any keys that don’t function as expected.
Next Steps for GPT-5 Codex: MCP Integration and Agent Pipelines
Beyond using Codex CLI as a standalone tool, the next direction is expanding into MCP integration and agent pipelines.
Codex CLI’s MCP server mode opens the possibility of placing a code generation agent as a node within a larger automation pipeline. By starting Codex with codex mcp-server and having other MCP clients call it as a tool, it becomes possible to compose an agent chain covering the full flow from code generation → test execution → review → deployment. This is arguably the most practical extension path after installing OpenAI Codex CLI.
Comparing GPT-5.3-Codex vs GPT-5.4 is another important topic in practice. The performance difference between a coding-specific model and a general-purpose model needs to be verified through benchmarks for specific task types to establish a basis for model selection. Whether the 1M token context window makes a meaningful difference in large-scale codebase analysis is also an area requiring validation.
Advanced config.toml configuration is another next step. Patterns like applying different sandbox policies per project or dynamically adjusting reasoning effort in codex exec automation scripts are central to balancing cost and quality in CI/CD integration. An optimization strategy combining GPT-5 Codex reasoning effort settings with prompt caching is a topic worth exploring in depth separately.
Related Posts
- Gmail Gemini Data Security — Complete Guide to Policy Differences Between Personal and Workspace Accounts – Gemini integrated into Gmail has entirely different data handling policies depending on the account type. Personal accounts vs. Workspace, Gemini API…