Codex CLI is OpenAI's coding agent for the terminal. Start it inside a repository and it can read code, edit files, and run commands. If you're still comparing it with Claude Code, Cline, and others, see how the main AI coding agents compare.
What was tested: install and custom-provider error handling were run on Codex CLI 0.169.0 on November 14, 2026. Everything else follows the official docs as of that date; no full task was run with a real account.
Install Codex CLI
Per-platform details, verification, and fixes for common install errors are in How to Install Codex CLI.
| Method | Install | Upgrade |
|---|---|---|
| Installer (macOS/Linux) | curl -fsSL https://chatgpt.com/codex/install.sh | sh | Rerun it |
| npm | npm install -g @openai/codex | Rerun it |
| Homebrew | brew install --cask codex | brew upgrade --cask codex |
| Windows (PowerShell) | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" | Rerun it |
Check the install:
codex --version
You should see something like codex-cli 0.169.0. In a test on macOS 26.5.2 (Apple Silicon) with a fresh HOME directory, the installer took about 15 seconds.
Sign in
cd /path/to/your/project
codex
On the first run, Codex asks how you want to sign in:
- ChatGPT account: uses a browser sign-in and draws on the usage included in your ChatGPT plan.
codex loginstarts the same flow. - API key: billed per use through your OpenAI Platform account at standard API rates, separate from plan usage.
printenv OPENAI_API_KEY | codex login --with-api-key
codex login statusshows which method is active.codex logoutclears it.- Credentials are cached in
~/.codex/auth.json, a plaintext file, or in your OS credential store. The CLI and the IDE extension share them.
Your first task
The quickstart's first prompt is:
Tell me about this project
After that, ask for a small change or help with an error. This section follows the docs and wasn't run with a real account. The docs recommend a Git checkpoint, such as a commit, before and after each task so you can revert changes.
On launch, Codex checks whether the folder is under version control:
- Version-controlled folders get the Auto preset recommended.
- Other folders get read-only recommended.
- Codex may also start read-only until you explicitly trust the folder.
Approval and sandbox modes
Two separate settings control what Codex can do:
- Approval policy: when it stops to ask you.
- Sandbox: which files it can write and whether it can reach the network.
The docs list these combinations:
| Use case | Flags | Effect |
|---|---|---|
| Auto (preset) | --sandbox workspace-write --ask-for-approval on-request | Reads, edits, and runs commands in the workspace; asks before editing outside it or using the network |
| Read-only browsing | --sandbox read-only --ask-for-approval on-request | Reads files and runs commands inside the read-only sandbox; actions outside it can require approval |
| Read-only, non-interactive (CI) | --sandbox read-only --ask-for-approval never | Same, but never asks |
Change modes mid-session with /permissions. --sandbox danger-full-access removes the sandbox. The docs say to use caution before enabling it.
config.toml settings
User config lives at ~/.codex/config.toml. These are the common settings:
# Needs access on your account; otherwise pick a model you can use
model = "gpt-6.1-sol"
# How much reasoning the model applies
model_reasoning_effort = "medium"
# When Codex stops to ask you
approval_policy = "on-request"
# read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"
# workspace-write has no network access by default
[sandbox_workspace_write]
network_access = true
If an older config still says approval_policy = "untrusted", replace it; that value is retired.
The main layers, highest precedence first:
- CLI flags
- Project
.codex/config.toml - The profile selected with
--profile - Your user config
- Built-in defaults
Cloud-managed defaults and the system config at /etc/codex/config.toml sit between the user config and the built-in defaults.
Project config has two limits:
- It only loads in projects you've trusted.
- For security, it can't change provider or credential settings.
model_provider,model_providers,openai_base_urland a few others are ignored there, with a startup warning.
Put provider settings in ~/.codex/config.toml.
Codex CLI commands
| Command | What it does |
|---|---|
codex | Interactive session |
codex "task" | Interactive session with a first prompt |
codex resume | Reopen a saved session; --last picks the latest one in this directory |
codex exec "task" | Non-interactive run that exits when done (short form codex e) |
codex --search | Live web search for this run |
Slash commands in a session:
| Command | What it does |
|---|---|
/init | Create an AGENTS.md with persistent project instructions |
/status | Model, permissions, and which folders are in the workspace |
/permissions | Change approval and sandbox mode |
/model | Switch model |
/review | Review uncommitted changes |
/diff | Show the Git diff |
/compact | Summarize the conversation to free context |
/exit | Quit (or Ctrl+C) |
Two more shortcuts:
- Type
@to search for a file and add its path to the prompt. - Start a line with
!to run a shell command directly. It still follows your current approval and sandbox settings.
Custom model providers
To send the built-in OpenAI provider through a proxy, the docs use a single key:
openai_base_url = "https://your-proxy.example/v1"
How the key is supplied depends on the proxy; check its docs.
To define a separate provider:
model_provider = "myproxy"
model = "a-model-your-endpoint-serves"
[model_providers.myproxy]
name = "My proxy"
base_url = "https://your-endpoint.example/v1"
wire_api = "responses"
env_key = "MYPROXY_API_KEY"
wire_apionly supportsresponses, which is also the default. The endpoint has to implement the OpenAI Responses API.env_keyis the name of an environment variable. The key itself goes in that variable, not in the file.- Reserved IDs such as
openai,ollama, andlmstudiocan't be reused.
What a wrong key looks like
The example here uses SU8 Codes, the service behind this blog. This test ran codex exec against SU8's gateway with a deliberately invalid key. Codex printed Reconnecting... 1/5 through 5/5, then unexpected status 401 Unauthorized. The error included the URL it actually called, {base_url}/responses.
In this test, the 401 meant the request reached the gateway and the key was rejected. The URL in the error is also a quick way to confirm your base_url.
Example: SU8 Codes
SU8 Codes is an API relay: one key reaches several model providers, and it supports the Responses protocol.
Its Codex CLI setup page (as of November 14, 2026) uses:
base_url = "https://www.su8.codes/v1"wire_api = "responses"- the model
gpt-5.5(model page)
The page says to fully restart Codex after editing the config. It stores the key in auth.json, not through env_key; if you use SU8, follow that page.
FAQ
Is Codex CLI free?
The CLI is open source (Apache-2.0). Model usage comes from your ChatGPT plan or from API-key billing. With a custom provider, that provider's billing applies.
Does Codex CLI work on Windows?
The docs provide a PowerShell installer and support WSL2. WSL1 is unsupported from 0.115 onward. Keep repositories in your Linux home rather than under /mnt/c. Windows wasn't tested for this tutorial; see the WSL page.
My config.toml change did nothing.
Run /status to see what's active, then check:
- If you edited a project
.codex/config.toml, the project must be trusted. - Provider settings are ignored in a project config; put them in your user config.
How do I control permissions in codex exec?
Pass --sandbox explicitly, for example codex exec --sandbox workspace-write "task". Other useful options:
--jsongives machine-readable output.--output-last-message <file>(or-o) saves the final reply to a file.