SU8 Codes
< Back to blog
Official article Updated 7 min read

Codex CLI Tutorial: Install, Configure, Use

Install Codex CLI, sign in, run a first task, set approvals and sandbox in config.toml, learn the daily commands, and add a custom model provider. Install tested on 0.169.0.

#codex#tutorial
Codex CLI Tutorial: Install, Configure, Use

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.

MethodInstallUpgrade
Installer (macOS/Linux)curl -fsSL https://chatgpt.com/codex/install.sh | shRerun it
npmnpm install -g @openai/codexRerun it
Homebrewbrew install --cask codexbrew 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 login starts 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 status shows which method is active.
  • codex logout clears 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 caseFlagsEffect
Auto (preset)--sandbox workspace-write --ask-for-approval on-requestReads, 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-requestReads 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 neverSame, 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:

  1. CLI flags
  2. Project .codex/config.toml
  3. The profile selected with --profile
  4. Your user config
  5. 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_url and a few others are ignored there, with a startup warning.

Put provider settings in ~/.codex/config.toml.

Codex CLI commands

CommandWhat it does
codexInteractive session
codex "task"Interactive session with a first prompt
codex resumeReopen 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 --searchLive web search for this run

Slash commands in a session:

CommandWhat it does
/initCreate an AGENTS.md with persistent project instructions
/statusModel, permissions, and which folders are in the workspace
/permissionsChange approval and sandbox mode
/modelSwitch model
/reviewReview uncommitted changes
/diffShow the Git diff
/compactSummarize the conversation to free context
/exitQuit (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_api only supports responses, which is also the default. The endpoint has to implement the OpenAI Responses API.
  • env_key is the name of an environment variable. The key itself goes in that variable, not in the file.
  • Reserved IDs such as openai, ollama, and lmstudio can'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:

  • --json gives machine-readable output.
  • --output-last-message <file> (or -o) saves the final reply to a file.