Codex Tutorial: Install the CLI, IDE Extension and App; config.toml, AGENTS.md and Common Commands

Step one

Choose a surface: CLI, IDE extension, desktop app or Codex Cloud

All four surfaces run the same Codex agent; they differ in where they run, which files they can reach and how you sign in. The CLI and the IDE extension read the same ~/.codex/config.toml and the same login cache, so signing in once covers both.

If your data lives only on your computer or a lab server, use the CLI or the IDE extension. Codex Cloud tasks can only reach repositories and services in the cloud environment; local files, browser sign-ins and VPN access are not transferred, and large raw datasets do not belong in a GitHub repository.

On a lab server, get the CLI working on the server first, then set up the IDE extension over Remote-SSH. The CLI verifies proxy, certificates and login on its own, which makes extension problems easier to locate.

The Free and Go plans can use GPT-6 Luna in the desktop app only (rolling out). From Plus ($20 per month) Codex is available on the web, in the CLI, in the IDE extension and on iOS, including GPT-6.1 Sol.

Install

Install the Codex CLI and fix failed installs

The official documentation lists four install methods; each uses the same command to update. After installing, run codex --version and codex doctor to confirm the binary, configuration, login and network.

# macOS / Linux: official installer (same command installs and updates)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows: run in a new PowerShell window
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm (Node 16+; in mainland China you can add --registry=https://registry.npmmirror.com)
npm install -g @openai/codex

# Homebrew
brew install --cask codex      # update: brew upgrade --cask codex

# Verify
codex --version                # version checked on this page: codex-cli 0.162.1
codex doctor --summary         # checks install, config, auth, network and sandbox

Sign in

ChatGPT account sign-in versus API key sign-in

Both methods work in the local CLI, IDE extension and desktop app. The choice depends on whether you want to use plan allowances or pay per token, and whether you need Codex Cloud.

Credentials are cached in ~/.codex/auth.json or the OS keychain, controlled by cli_auth_credentials_store (file / keyring / auto / ephemeral). The CLI and IDE extension share this cache; signing out in one signs out both.

Device code sign-in must first be enabled in your ChatGPT security settings (for workspace accounts, by the admin in workspace permissions). If sign-in fails, check codex-login.log in the log directory.

In mainland China, the practical requirements are a stable international connection and a ChatGPT account or an OpenAI API key. Use HTTP proxy variables: a Windows user reported that ChatGPT backend disconnects stopped after switching SOCKS5 proxy variables to HTTP proxy variables and setting NO_PROXY (GitHub #20844). A third-party gateway must support the Responses protocol; services that only offer Chat Completions cannot be connected to the current version. For a comparison of official plans, API relays and domestic models, see /compare/codex-claude-code-china.

codex login                    # browser sign-in with a ChatGPT account
codex login --device-auth      # device code: servers and machines without a browser
printenv OPENAI_API_KEY | codex login --with-api-key   # API key sign-in
codex login status             # exits 0 when signed in; prints Not logged in and exits 1 otherwise
codex logout

# Headless server without device code: forward the callback port, then sign in
ssh -L 1455:localhost:1455 user@server
codex login                    # open the printed URL in your local browser

# Or copy your local login cache (treat auth.json like a password)
ssh user@server 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

# Linux / macOS terminal: use HTTP proxy variables and keep local addresses direct
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

# On macOS the ChatGPT desktop app launched from the Dock ignores shell variables; set them in launchd and restart the app
launchctl setenv HTTPS_PROXY http://127.0.0.1:7890
launchctl setenv HTTP_PROXY http://127.0.0.1:7890

# Corporate proxy or private root CA
export CODEX_CA_CERTIFICATE=/path/to/root-ca.pem   # falls back to SSL_CERT_FILE when unset

# Change only the address of the built-in OpenAI provider (no new provider), in ~/.codex/config.toml
openai_base_url = "https://gateway.example.com/v1"

Configuration

Common ~/.codex/config.toml settings, one by one

Settings apply in this order, earlier entries overriding later ones: command-line flags and -c overrides → project .codex/config.toml files (from the project root down to the current directory, closest wins, trusted projects only) → ~/.codex/<name>.config.toml selected with --profile → ~/.codex/config.toml → system /etc/codex/config.toml → built-in defaults.

# ~/.codex/config.toml  (validated with --strict-config on Codex CLI 0.162.1)
# Root keys must come before the first [table]; after a table they become fields of that table and are ignored
model = "gpt-6.1-sol"              # switch to gpt-6-luna if your account lacks access
model_reasoning_effort = "medium"  # low / medium / high / xhigh, depending on the model
approval_policy = "on-request"     # only on-request and never are accepted
sandbox_mode = "workspace-write"   # read-only / workspace-write / danger-full-access
web_search = "cached"              # cached (default) / live / indexed / disabled
file_opener = "vscode"             # makes file paths in output clickable
project_doc_max_bytes = 65536      # combined AGENTS.md limit, default 32768

[sandbox_workspace_write]
network_access = false             # set to true when pip/conda need the network
writable_roots = []                # extra writable directories, e.g. ["/Users/me/scratch"]

[history]
persistence = "save-all"           # "none" keeps no local session history

# MCP: local stdio server
[mcp_servers.papers]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/papers"]
startup_timeout_sec = 20           # default 10
tool_timeout_sec = 60              # default 60

# MCP: remote HTTP server, disabled for now
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"
enabled = false

# Custom model gateway (Responses protocol only)
[model_providers.mygateway]
name = "My OpenAI-compatible gateway"
base_url = "https://gateway.example.com/v1"
env_key = "MYGATEWAY_API_KEY"      # the variable name, not the key itself
wire_api = "responses"
request_max_retries = 4
stream_idle_timeout_ms = 300000

# Trust a project so its .codex/config.toml is loaded
[projects."/Users/me/research/rnaseq-2026"]
trust_level = "trusted"

# ~/.codex/gateway.config.toml  --  codex -p gateway
model_provider = "mygateway"
model = "gpt-6.1-sol"

# ~/.codex/deep.config.toml  --  codex -p deep
model_reasoning_effort = "high"

# One-off overrides; values are parsed as TOML, so strings need quotes
codex -c model_reasoning_effort='"high"' -s read-only
codex exec -p deep "Review the statistics in scripts/02_model.py"

• After editing, run codex exec --strict-config "hi": fields this version does not recognize produce unknown configuration field with the line number; a valid config starts running normally (and then returns 401 if you are not signed in).
• The config item in codex doctor --all lists ignored fields, for example Codex is ignoring 2 unrecognized configuration settings.
• In an interactive session, /status shows the active model, approval policy, writable roots and remaining context; /debug-config shows which file each config layer comes from.
• A project .codex/config.toml cannot set model_provider, model_providers, openai_base_url, profile and similar keys; they are ignored with a startup warning.
• codex mcp add <name> -- <command> or codex mcp add <name> --url <url> writes to config.toml; codex mcp list shows configured servers and whether they are enabled.

Version changes

Settings from old tutorials that now fail

The Codex CLI changes quickly, and many settings from tutorials written in 2025 and early 2026 no longer work. Every error message below was triggered on this page with Codex CLI 0.162.1.

AGENTS.md

AGENTS.md: where it goes, how files merge, what to write

AGENTS.md is a plain Markdown file that Codex reads at the start of every session and places in the first turn's context. Use it for rules that hold for the whole project: directory conventions, run commands, files that must not change and what counts as done.

This page used codex debug prompt-input to view what is actually injected into the model (Codex CLI 0.162.1, no login needed). Started at the project root, only the global file and the root AGENTS.md were loaded; AGENTS.md files in subdirectories such as analysis/ were not. Started in analysis/deseq/, all four files on the path were loaded; when analysis/ also contained AGENTS.override.md, only the override was used for that directory. After growing the root AGENTS.md to 40 KB, the root file was truncated under the default limit and the rules from analysis/ and deseq/ did not reach the context.

So rules specific to a subdirectory only apply when you start Codex in that subdirectory (codex -C analysis/deseq). Rules that must always apply belong in the root file, which should stay short.

/init writes a draft AGENTS.md in the current directory; trim it to the essential rules before committing. ETH Zürich's evaluation of AGENTS.md (arXiv 2602.11988, ICLR 2026) found that on SWE-bench and similar coding tasks, context files slightly reduced task success overall while raising inference cost by more than 20%; agents follow the instructions faithfully, so unnecessary requirements make tasks harder. The authors recommend human-written files with only minimal requirements. The official pricing documentation also lists "reduce the size of your AGENTS.md" as a way to make usage last longer.

To check which files were loaded, ask "list the instruction files you loaded" in a session, or start with codex -c log_dir=./.codex-log and read codex-tui.log.

# AGENTS.md (at the root of the project repository)

## Directory conventions
- data/raw/: raw data, read-only. Do not modify, move, overwrite or re-encode.
- data/processed/: generated from data/raw by scripts in scripts/; can be deleted and rebuilt.
- scripts/: numbered (01_qc.py, 02_model.R); each script reads only the previous step's output.
- results/<date>_<label>/: one directory per run, holding figures, tables and logs.

## Run requirements
- Environment: conda env rnaseq-2026 (environment.yml). Report missing packages first; do not upgrade existing ones.
- Fix random seeds to 20261010 and record them in the run log.
- Each run writes RUN.md in its results directory: commands, input files with md5, software and package versions, parameters, runtime, list of outputs.
- For statistical tests, state the test, the multiple-testing correction and the thresholds; do not change thresholds mid-run.

## Scope of changes
- Only modify scripts/ and results/. Before changing shared functions, list the scripts affected.
- When results differ from expectations, report the difference; do not change thresholds or drop samples to make results look better.

## Definition of done
- Scripts reproduce the same results from a clean data/processed.
- The reply lists changed files and what I need to check by hand.

1. 01

   Global layer

   If ~/.codex/AGENTS.override.md exists Codex reads only that file; otherwise it reads ~/.codex/AGENTS.md. Put cross-project personal habits here, such as reply language or preferred package manager.

2. 02

   Project layer

   From the project root (by default the directory containing .git; change with project_root_markers) down to the directory where you start Codex, each directory is checked for AGENTS.override.md, AGENTS.md and names in project_doc_fallback_filenames, taking at most one file per directory.

3. 03

   Merge

   Files are concatenated in the order global → root → current directory. Files closer to the current directory come later and take precedence on conflicts. Empty files are skipped.

4. 04

   Limit

   Once the combined size exceeds project_doc_max_bytes (32 KiB by default), content is truncated and files deeper in the path are dropped entirely.

Commands

Common commands, slash commands and shortcuts

Compiled from codex --help and the official Developer commands documentation; only everyday commands are listed.

Non-interactive and sessions

codex exec and resuming sessions

codex exec runs one task and exits. Progress goes to stderr and only the final reply goes to stdout, so you can redirect or pipe it. Three defaults differ from interactive mode; confirm them before writing scripts.

Session records are stored under ~/.codex/sessions. codex resume --last only searches sessions from the current directory; add --all after changing directories. When the saved directory differs from the current one, Codex asks which to use; tui.resume_cwd fixes that choice. Sessions run with --ephemeral are not saved and cannot be resumed.

When you need a fixed result format (for example a QC verdict per sample), use --output-schema schema.json to constrain the final reply to a JSON structure and -o to write it to a file.

# Run one analysis in the project directory; final reply goes to a file (progress goes to stderr)
cd ~/research/rnaseq-2026
codex exec --sandbox workspace-write \
  -o results/2026-10-10_qc/codex_summary.md \
  "Following AGENTS.md, run scripts/01_qc.py, write outputs to results/2026-10-10_qc/ and create RUN.md"

# JSONL events (commands, file changes, token usage)
codex exec --json --sandbox workspace-write "..." > run_events.jsonl

# Continue the previous non-interactive session (--last searches the current directory only)
codex exec resume --last "Change the 01_qc filter to min_counts=10 and rerun"

# Interactive sessions
codex resume              # picker
codex resume --last       # most recent in this directory
codex resume --all        # search all directories
codex fork --last         # copy a session to try another approach

Approvals and sandbox

Approval modes and the sandbox: more permission, costlier mistakes

The sandbox decides what commands can technically do (which directories they can write, whether they can reach the network); the approval policy decides when Codex stops to ask. They are set independently. In the CLI and IDE extension the operating system enforces the sandbox: Seatbelt on macOS, bubblewrap / Landlock on Linux and WSL2, dedicated sandbox users on native Windows.

Some paths stay read-only under workspace-write: .git, .codex and .agents inside the workspace (so git commit needs approval) and home locations such as ~/.cache. Tested on this page with codex sandbox: writing inside the workspace succeeded, while writing to ~/.cache and git commit both returned Operation not permitted, and curl to an external host returned Could not resolve host. Python packages that write caches to ~/.cache fail for this reason; specify in AGENTS.md that cache directories such as MPLCONFIGDIR and HF_HOME point inside the project or to /tmp.

/undo has been removed from the CLI. A maintainer explained in GitHub #9203 that the old implementation caused many problems and would need a redesign. The community workaround is to ask Codex to reverse its last changes with the patch tool, but deleted untracked files cannot be recovered. Committing to git before each task is currently the most reliable way back.

For finer control than sandbox_mode, use permission profiles (beta): set read, write or deny per path under [permissions.<name>] and allow-list network domains. The next section shows how to make raw data read-only.

Research code

Using Codex for research code: protect raw data, keep reproducible records, manage context

Research analysis differs from ordinary software work in three ways: raw data cannot be regenerated, results must trace back to exact commands and parameters, and tasks run long. The steps below address each.

# ~/.codex/config.toml: make data/raw read-only with a permission profile
# Use this block OR sandbox_mode / [sandbox_workspace_write]; if both are present the profile is ignored
default_permissions = "research"

[permissions.research]
extends = ":workspace"              # inherit the default workspace profile (.git/.codex read-only, network off)

[permissions.research.filesystem.":workspace_roots"]
"data/raw" = "read"                 # relative to each workspace root
"**/*.env" = "deny"

# Tested on this page (Codex CLI 0.162.1, macOS arm64, codex sandbox -P research):
#   echo ok > results/out.txt         -> succeeds
#   echo x >> data/raw/counts.csv     -> Operation not permitted
#   rm data/raw/counts.csv            -> Operation not permitted
# Control: with the built-in :workspace profile, appending to data/raw/counts.csv succeeds

1. 01

   Layer 1: make raw data read-only at the OS level

   The simplest option is chmod -R a-w data/raw. A Codex-only option is a permission profile that extends :workspace and sets data/raw to read (code below). Use it instead of sandbox_mode: if any config layer contains sandbox_mode or you pass --sandbox, the profile has no effect.

2. 02

   Layer 2: directory conventions in AGENTS.md

   State which directories are read-only, where generated files go and what counts as done. The agent follows these rules, but rules alone cannot block writes, so combine them with layer 1.

3. 03

   Layer 3: git and per-run directories

   If raw data stays out of git, at least track scripts, configs and RUN.md. Write each run to a new results/<date>_<label>/ directory instead of overwriting old results.

4. 04

   Require a reproducibility record

   Have AGENTS.md require a RUN.md per run: commands, input file md5s, software and package versions (conda env export or sessionInfo()), random seed, parameters, runtime and outputs. When reviewing, read RUN.md before the results.

5. 05

   Prepare the environment first

   workspace-write has no network by default, so pip / conda installs fail. Build the environment yourself before the task, or enable network_access only for the turn that installs packages and turn it off afterwards.

6. 06

   When the context gets long

   Check remaining context with /status. Codex compacts automatically at a threshold (adjust with model_auto_compact_token_limit), or run /compact manually. GitHub #36642 reports that since 0.145 auto-compaction occasionally discards the entire history; it still reproduces on 0.150 and the issue is open. In long tasks, have Codex write progress, confirmed parameters and open items to NOTES.md, and have it read that file first after a failed compaction or in a new session.

Troubleshooting

Common errors and fixes

Read the URL or path in the error first: it shows where the request actually went or which file was refused. Then run codex doctor, which checks login, WebSocket, proxy variables and the sandbox separately.

Chinese community experience

Chinese community experience: proxies, lab servers and config debugging

The following come from posts with original error output or the author's own test record, cross-checked against the official documentation or GitHub issues, with the conditions under which they apply.

Hand it to an agent

Hand this workflow to an agent

Example instruction: "This is my RNA-seq project repository; raw counts are in data/raw. Read AGENTS.md and scripts/ first, run 01_qc through 03_deseq without modifying data/raw, write RUN.md for each step, and finally list how the results differ from the previous run and what I need to check."

Steps the agent performs: in an isolated cloud computer built on Codex, it reads the repository and AGENTS.md; uses the preinstalled pandas, SciPy, statsmodels and scikit-learn environment and installs missing R or Python packages in the workspace; runs the numbered scripts while recording commands, versions and parameters; reviews the results adversarially; keeps running after you close your computer and pauses with its state preserved when idle.

Outputs: modified scripts, a results directory with RUN.md and logs for every run, and a record explaining changes and anomalies.

You still need to check: whether the statistical methods and thresholds fit your study design, whether sample groups and batch information are correct, and the biological interpretation of the results.