Codex Install & Usage Guide (2026):GPT-5.5-Codex Complete Guide

In 2026, OpenAI redefined Codex from its historical role as a code-completion model into a full programming agent platform: the Codex CLI runs in your local terminal, reads repos, edits files, and executes commands; GPT-5.5-Codex is the software-engineering model variant tuned for that work. This article is the English site's authoritative install + usage landing page — covering three install methods, ChatGPT login, config.toml, approval sandboxing, /model switching, and your first acceptance-ready task. If you are still weighing how Codex relates to Claude Code and Cursor, the structured comparison and scenario matrix below will help.

1. Why install Codex CLI separately in 2026?

ChatGPT on the web can write code, but engineering teams face a real gap: suggestions in a chat window do not automatically become auditable git diffs; they cannot reliably run test loops; they cannot plug into CI. Codex CLI solves the execution boundary — it puts the GPT-5.5 family inside a directory you choose and lets the agent edit files and run shell commands under sandbox and approval policies.

Unlike the 2021 “Codex completion API,” 2026 Codex is an open-source terminal agent written in Rust (repo: openai/codex), tied to ChatGPT subscriptions, and extended to IDE extensions, a desktop app, and Codex Cloud async jobs. The real dividing line is not “OpenAI vs Anthropic who is stronger” — it is whether you are willing to delegate tasks to a terminal agent.

2. How to classify Codex's four entry points

This install guide focuses on Codex CLI, but the full platform has four surfaces sharing the ~/.codex/ config directory:

The main path in this article is CLI first: once the CLI works, IDE extensions and the App usually need only the same account login to reuse your configuration.

3. Core comparison: Codex vs Claude Code vs Cursor

Plain-language pricing first: all three start around $20/month, but you are not buying the same thing —

• Codex and Claude Code: like a mobile data plan — allowance resets every few hours; asking AI to edit many files in one session burns through quota fast.
• Cursor: like a gym membership — a fixed $20/month, best value if you live in the IDE eight hours a day, and the easiest bill to predict.

The green-highlighted column in the table below is about how you are charged and whether month-end bills surprise you — that is what matters most when choosing a tool. Capability differences sit in the left columns; pricing behavior is in the green column.

For a deeper IDE comparison see Claude Code vs Cursor 2026; for the Anthropic vs OpenAI agent narrative see the Claude Code era.

4. How to choose by scenario

5. Recommended stacks (2026 engineering)

• Solo developer — Codex CLI (GPT-5.5-Codex) + your existing IDE for small edits; open codex on weekends for larger delegated tasks.
• Full-stack + iOS — business code locally with Codex/Cursor; Xcode builds and signing on Cloud Mac or a GitHub Runner execution node.
• Team CI — codex exec or Codex Cloud produces patches → Actions compile and test → humans review PRs. Isolate runners with one job, one workspace.
• Knowledge-dense repos — Codex MCP for issue tracking + optional CodeGraph; rules in project .codex/config.toml and AGENTS.md.

6. Before you install

• Account — ChatGPT Plus / Pro / Business / Edu / Enterprise (includes Codex), or a working OpenAI API Key.
• OS — macOS and Linux are first-class; Windows via native PowerShell or WSL2.
• Git repo — validate in a real project root, not an empty folder.
• Node.js 18+ — required only for npm install -g @openai/codex.

uname -a
git --version
node -v   # check if using npm path
which codex # should be empty before install

7. Three install methods (2026 official paths)

# for non-interactive CI images, set first
export CODEX_NON_INTERACTIVE=1

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

npm install -g @openai/codex@latest
codex --version
# on EACCES: npm config set prefix ~/.npm-global, add ~/.npm-global/bin to PATH

8. Login and authentication

First run of codex opens the interactive TUI. Choose:

• Sign in with ChatGPT (recommended) — browser OAuth; usage counts against your ChatGPT plan.
• API Key — for automation and per-token accounting; never commit keys to git.

Config and credentials live in ~/.codex/. On shared machines watch file permissions; in CI inject API keys via a secrets manager, not the repository.

9. GPT-5.5-Codex: model switching and config.toml

GPT-5.5 is the general flagship; GPT-5.5-Codex is optimized for code tasks (read repos, apply patches, tool-chain reasoning). Default to the Codex variant for software engineering; switch back to gpt-5.5 for general Q&A.

In-session switch: in the TUI type /model, select gpt-5.5-codex, and adjust reasoning level.

Persistent default: edit user config ~/.codex/config.toml (project-level .codex/config.toml requires trusting that project):

# default programming model
model = "gpt-5.5-codex"

# approval: on-request = ask when agent needs elevated access (recommended)
approval_policy = "on-request"

# sandbox: start read-only, widen to workspace-write after you trust the flow
sandbox_mode = "read-only"

# reasoning effort (tune per task)
model_reasoning_effort = "medium"

Config precedence (later overrides earlier): built-in defaults → ~/.codex/config.toml → project .codex/config.toml → Profile (codex --profile ci) → CLI flags. See official Config basics.

10. Daily use: TUI, approvals, MCP, and scripting

Interactive mode

cd your-repo
codex
# or a one-line task
codex "run npm test and fix failing cases; do not change package-lock"

Approval modes (safety baseline)

For rm, production config changes, or secret files, always approve manually. Enterprise setups may block never or danger-full-access sandbox via requirements.toml.

MCP extensions

Codex supports the Model Context Protocol. Declare MCP servers in config.toml to pull GitHub, databases, and other external context. Configuration philosophy is similar to Claude Code — different host — see our MCP setup guide for PAT least-privilege principles.

Scripted exec and Cloud

• codex exec "..." — headless execution for cron / CI pre-checks.
• Subagents — split large tasks into parallel child agents (enable in TUI).
• Local code review — independent agent reviews diffs before commit.
• Codex Cloud — launch cloud tasks from terminal, pull patches, apply locally.

11. Common mistakes

1. Treating Codex like ChatGPT on the web — without CLI install and diff review, you never close the engineering loop.
2. Starting with sandbox_mode = danger-full-access — saves clicks but accidental deletes are irreversible; begin read-only, then widen.
3. Launching codex in a subdirectory — the agent only sees cwd context; in monorepos start at the correct package root.
4. Ignoring Windows path differences — native PowerShell and WSL repo paths are not the same filesystem; pick one path and stick to it.
5. Comparing models but not entry points — GPT-5.5-Codex is strong, but if you need Tab completion, prefer Cursor + Codex extension over forcing pure TUI.

12. 7-step rollout checklist

1. Install CLI — run official install.sh or npm i -g @openai/codex; verify codex --version.
2. Sign in — ChatGPT OAuth or API Key; confirm ~/.codex/ was created.
3. Write config.toml — model = "gpt-5.5-codex", approval_policy = "on-request", sandbox_mode = "read-only".
4. Pick a repo — cd into a familiar mid-size project; git status clean or on a feature branch.
5. Smoke task — codex "explain src directory structure and draw a tree"; verify it reads the right files.
6. Closed-loop task — codex "run tests with [your test cmd] and fix failures"; confirm it actually runs shell.
7. Wire team stack — for 24/7 builds put runners on Cloud Mac; add MCP when you need a code graph.

13. FAQ

Which is cheapest — Codex, Claude Code, or Cursor?

All start around $20/month on paper — there is no universal “cheapest.” If you already pay for ChatGPT, Codex is effectively included; same for Claude Pro and Claude Code. Starting from zero and wanting one predictable monthly charge, Cursor is easiest to estimate. Heavy usage where AI edits many files at once may push either side to $100–$200 — see the comparison table above.

Does Codex cost extra?

Usually not. ChatGPT Plus ($20/month) includes Codex. You can also use your own API Key and pay per token, but you lose member-only features like cloud code review. See OpenAI's Codex in ChatGPT article for current limits.

What is the difference between GPT-5.5 and GPT-5.5-Codex?

GPT-5.5 is general-purpose; GPT-5.5-Codex is fine-tuned for software engineering — better at reading code, writing patches, and following tool chains. Default to the Codex variant for coding.

Can I install Codex and Claude Code together?

Yes. Config directories differ (~/.codex/ vs ~/.claude.json); use each per scenario in the same repo. Align formatting rules so two agents do not fight over style.

command not found after install?

Restart your shell or add the install path to PATH. Homebrew users check /opt/homebrew/bin; npm users check ~/.npm-global/bin.

How do I upgrade Codex?

npm install -g @openai/codex@latest or re-run the official install script; Homebrew: brew upgrade codex.

14. Summary

A 2026 Codex install guide is really about wiring OpenAI's programming agent to your filesystem and terminal. Three commands install the CLI; sign in with ChatGPT; default to gpt-5.5-codex in config.toml with on-request approvals as your safety line — and you have a reproducible, scriptable, Cloud-ready coding workflow. Codex competes with Claude Code for the terminal-agent entry point and with Cursor for who drives daily coding; most teams end up dual- or triple-wielding rather than betting on one brand.

For readers who need real macOS builds: no matter how fast the agent writes code, Xcode and runners still need Apple hardware. Cloud Mac pairs with local Codex edits and remote compile — split “write” from “verify” and shorten your path to release.