Codex Usage: OpenAI's local coding agent
In the previous lesson we got Claude Code to feel "second nature"; in this 12-minute lesson, we'll get Codex, the OpenAI camp's counterpart tool, to feel just as natural: install it, sign in with a ChatGPT account, assign your first task, keep an eye on its permissions, switch models, and review changes to wrap up. This Codex tutorial focuses on the CLI, its main form—officially positioned as "a coding agent that runs locally on your computer"; the IDE extension, desktop app, and web version, three other forms, share the same account, and we'll cover them all together at the end. (Fact-checked 2026-11-05; commands and features change with versions, so the official docs prevail.)
What you'll be able to do after this lesson
- Install Codex CLI on macOS, Linux, or Windows, and sign in with your ChatGPT account
- Assign tasks in your project directory: have it explain the project, make small changes, fix bugs—it reads files on its own and runs commands in the sandbox
- Keep an eye on its hands with
/permissions: know the three sandbox levels and the approval policies, and it asks you first before going out of bounds - Use
/modelto switch models (such as the defaultgpt-6.2-sol), and/statusto check session status and usage - Review changes with
/diffand/review, compress long conversations with/compact, and pick old sessions back up withcodex resume
Your current struggles
- Chatting about code in the web version of ChatGPT: you copy every file in, paste it back after edits, and the back-and-forth wears your hands out
- You installed Codex but got stuck at sign-in: ChatGPT account vs. API key, two paths, and you don't know which to pick or whether your subscription even includes Codex
- It keeps stopping to ask "should I approve this command," which gets annoying; but leaving everything open makes you worry it will wreck your project
When to use this move
When you need to:
- Let OpenAI's models read your project, edit files, and run commands directly on your computer—changes stay local, viewable and revertible at any time
- Drive a coding agent with your existing ChatGPT subscription (Plus / Pro / Business / Edu / Enterprise), without buying API separately
- Clear boundaries: the sandbox fences off the files and network it can touch, and out-of-bounds actions need approval first
And you don't want to:
- Copy-paste code and errors back and forth in a web chat box
- Give an AI full control of your computer
- Relearn a whole new set of concepts just because you switched tools—the previous lesson's mindset of "explain one thing clearly, like delegating a task" applies here unchanged
🎒 Preparation before you start
- Read the Daily Use guide, and know that this page covers Codex (OpenAI camp) among the four tools
- A ChatGPT account: the official recommendation is to sign in with a Plus / Pro / Business / Edu / Enterprise subscription; see price comparison for each tier's pricing and inclusions (the free tier's capabilities are per the official page)
- A practice project directory, ideally a git repository—the official advice is to create Git checkpoints before and after tasks, making full rollback easy
- 12 minutes of uninterrupted time
💡 The previous lesson is not a prerequisite
This lesson only requires that you've read the Daily Use guide. Claude Code Usage and this lesson are independent of each other, but the "task delegation" mindset is universal, and reading them side by side gives you a better feel.
Core idea
Codex CLI's official positioning in one sentence: a coding agent from OpenAI that runs locally on your computer. It works against your local repository: inspecting files, making changes, running the tools already installed on your machine—not a chat box where "you paste code and it gives answers," but an agent where "you assign the task and it gets it done."
The fundamental difference from the web version of ChatGPT:
| Web ChatGPT | Codex CLI | |
|---|---|---|
| Code into context | You copy and paste manually | It reads your local repository itself |
| Editing code | Gives you snippets, you paste them back yourself | Edits files directly, /diff viewable |
| Verification | You run commands yourself | It runs tests in the sandbox, reads errors, and fixes them itself |
| Billing | Chat quota | Codex usage from your ChatGPT subscription, or pay-as-you-go with an API key |
Four forms, one account. The CLI is this lesson's main thread; the other three forms use the same ChatGPT account (cloud tasks must be signed in with a ChatGPT account; the CLI and IDE extension also share the same local login credentials):
| Form | One-sentence positioning |
|---|---|
| CLI, terminal (this lesson's main thread) | Run codex in your project directory: read code, edit files, run commands without leaving the terminal |
| IDE extension | VS Code, Cursor, Windsurf sidebar (extension openai.chatgpt; Xcode and JetBrains have separate integrations) |
| Desktop app | codex app Launch the ChatGPT desktop app from the terminal (macOS/Windows), pick Codex in the app to start chatting |
| Codex Web | Open chatgpt.com/codex in a browser: a cloud agent that runs tasks in the cloud, so they keep going even while your computer sleeps |
The security model in one sentence: sandbox containment + approval gating. The sandbox decides which files and networks it can touch; the approval policy decides whether it stops to ask you before crossing a boundary. Start with Ask for approval in daily use; the official low-friction combo is --sandbox workspace-write --ask-for-approval on-request—work freely inside the workspace, report first when stepping outside.
How to choose and combine it with last lesson's Claude Code? Both follow the same "local agent" idea; the differences are mainly the underlying models and subscriptions: Claude Code runs on Claude models + an Anthropic subscription, while Codex runs on GPT models + a ChatGPT subscription. Using them together is entirely feasible—both have a project instruction file mechanism (see AGENTS.md and CLAUDE.md), and Codex's /import can even migrate Claude Code's configuration and chat history directly. See pricing comparison for the full cost table.
Follow along
Step 1: Install the Codex CLI
Why: The Codex CLI is a standalone command-line tool—install it first, since everything after depends on it. The official install script gets it done in one command.
Option A: Official install script (recommended)
macOS / Linux users:
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows users (run in a newly opened PowerShell window):
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Option B: Package manager
npm install -g @openai/codexbrew install --cask codexVerify after installation:
codex --versionYou should see: the terminal prints a version number.
To update later: rerun the install command from Option A; brew users can use brew upgrade --cask codex; the CLI also has a built-in codex update self-update check.
- Quick check:
codex --versionprints a version number
Step 2: Sign in to Codex with a ChatGPT account
Why: The official recommendation is to sign in with a ChatGPT account—you use the Codex quota included in your Plus / Pro / Business / Edu / Enterprise subscription directly, with no need to buy an API key separately.
cd /path/to/your/project
codexThe first run asks you to pick a sign-in method; choose Sign in with ChatGPT: the browser opens the OpenAI login page, and after signing in the credentials return to the terminal automatically.
After signing in, check the status:
codex login statusYou should see: info about the currently signed-in account. This command exits with code 0 when credentials exist, which also makes it handy for scripting login-state checks.
💡 Another route: pay-as-you-go with an API key
No subscription? There's still a way: sign in with an OpenAI API key and pay at standard API rates (the official README notes this route requires extra setup):
printenv OPENAI_API_KEY | codex login --with-api-keyTwo things to keep in mind: the API key route has no cloud features (GitHub automated code review, Slack integration, etc.), and model availability follows your key; for subscribers, ChatGPT sign-in is still the recommended daily choice.
- Quick check:
codex login statusshows you're signed in
Step 3: Codex tutorial core: how do you assign work? Explain a task clearly, like briefing a colleague
Why: Just like last lesson's Claude Code, the agent's output quality depends on how clearly you explain. The official choice for the first task is a good one—have it walk you through the project; this is practice, and its answer also shows how well it understands the project.
Tell me about this projectHow to phrase a few common kinds of tasks:
| Task | What you say |
|---|---|
| Understand the project | Tell me about this project (official example) |
| Make a small change | State clearly which file to change, what it should become, and what counts as done |
| Fix a bug | Paste the error message verbatim and explain how it was triggered |
| Explain a piece of code | @ Reference a file path and have it focus on that file |
You should see: Codex reads files on its own, lists the project structure, or starts editing; when verification is needed it runs commands in the sandbox, takes the output in, and continues.
Official advice: create a Git checkpoint before and after each task so you can roll back everything if things break.
- Quick check: I assigned one concrete task and saw Codex read files, edit files, or run commands on its own
Step 4: Watch its hands—configure permissions and the sandbox with /permissions
Why: The agent runs commands on your computer, so the boundaries must be clear. Codex uses two gates: the sandbox decides which files and networks it can touch, and approval decides whether it asks you first before crossing a boundary.
In the session, type:
/permissionsYou should see: the permission picker pops up, letting you switch approval presets—for example, Auto to let it run freely, or Read Only for strict read-only control.
Three sandbox levels (the sandbox_mode field in the config file ~/.codex/config.toml):
| Sandbox mode | Meaning |
|---|---|
read-only | Look only: editing files and running commands both require approval |
workspace-write | Free read/write within the workspace and run routine commands (the official low-friction default) |
danger-full-access | No sandbox restrictions; use only when you explicitly want everything open |
Two approval policy levels: on-request (default, asks only when crossing boundaries) and never (never asks).
Platform differences to know ahead of time:
macOS: works out of the box (the system ships with the Seatbelt framework)
Windows: uses the native Windows sandbox in PowerShell; under WSL2 it uses the Linux sandbox
Linux: install bubblewrap first—
sudo apt install bubblewrap(Ubuntu/Debian) orsudo dnf install bubblewrap(Fedora)Quick check:
/permissionsopens the picker, and I know which sandbox level is currently active
Step 5: Switch models and check status—/model and /status
Why: Different tasks call for different firepower: use a stronger model to think harder on tricky bugs, and a faster model on batch small tasks to save quota. Starting with 0.171.0 (2026-11-20), the model catalog adds GPT-6.2 Sol and GPT-6.2 Astra, with Sol as the default choice. Official recommendation: use Sol for everyday coding, and Astra for the hardest jobs like cross-service bug hunting. Be careful not to write old model names—GPT-5.5 was retired from "ChatGPT-sign-in Codex" on 2026-10-14.
Switch models in the session:
/modelYou should see: a list of models available to your account pops up (e.g. gpt-6.2-sol, gpt-6.2-astra, gpt-6-luna); once you pick one, the switch is confirmed in the conversation. Both GPT-6.2 models are available on Plus, Pro, Business, Enterprise, and Edu (Enterprise / Edu requires an admin to enable them first).
You can also specify it directly at launch:
codex --model gpt-6.2-solSwitch to Astra for hard problems: codex -m gpt-6.2-astra. For which model to pick for which kind of task, see How to choose a model.
Check session status:
/statusYou should see: the current model, approval policy, writable directories, and token usage. The official docs say: to check your remaining quota in an active CLI session, use it.
💡 Watch your usage
In a session, run /usage to see your account's token activity (daily / weekly / cumulative); the web usage dashboard is at chatgpt.com/codex/settings/usage, and the official recommendation is to check it every week or two so you have a sense of your own pace.
- Quick check: I can see the current model and approval policy in
/status
Step 6: Review changes and wrap up sessions — /diff and codex resume
Why: code changed by AI should be reviewed before it goes into the repo; session management determines whether you'll want to open it again the next day.
| Scenario | Action | Effect |
|---|---|---|
| See what it changed | /diff | Git diff, including new files Git hasn't tracked yet |
| Have it self-review | /review | Summarizes workspace issues (behavior changes, missing tests) without touching your files |
| Conversation gets slow when too long | /compact | Compresses history into a summary, freeing up context |
| Run a shell command directly | ! git status | Output goes into the conversation and it responds automatically |
| Reference a file | @src/... | Puts the file path into the prompt |
| Pick up where you left off tomorrow | after exiting codex resume | Reopens the most recent session in the current repo, and can also search earlier ones |
You should see: /diff lists changed files and additions/deletions; codex resume brings you back with the previous conversation context.
- Quick check: I reviewed changes with
/diffand resumed a session withcodex resume
Checkpoint ✅
codex --versionprints the version number, andcodex login statusshows I'm logged in- I started
codexin my project directory, assigned it its first task, and watched it read files on its own and run commands in the sandbox - I can use
/permissionsto switch approval presets, and I know the officially recommended combo isworkspace-write+on-request - I can use
/modelto switch models (e.g.gpt-6.2-sol) and/statusto check status; I knowgpt-5.5has been retired - I review changes with
/diff; long conversations get/compact; sessions are resumed withcodex resume
Pitfall reminders
❌ Your model name still says gpt-5.5 — it's been retired
GPT-5.5 was retired from "ChatGPT-sign-in Codex" on 2026-10-14 (API key sessions are unaffected). The official retirement notice gives these replacements: gpt-6.1-sol for Plus / Pro / Business / Enterprise / Edu tiers; gpt-6-luna in the desktop App for Free / Go tiers. As of Codex 0.171.0, the default is already gpt-6.2-sol, so Plus and above can switch to it directly; when the configuration is shared with the IDE extension, the official advice is to pick a model available on every client, such as gpt-6.1-sol. Update old model names in workspace defaults, saved model settings, custom agents, scheduled tasks, and scripts as well.
❌ A sandbox warning pops up on startup on Linux
Cause: the Linux sandbox depends on bubblewrap (bwrap); if it isn't installed or can't create user namespaces, Codex warns at startup. The right fix: sudo apt install bubblewrap (Ubuntu/Debian) or sudo dnf install bubblewrap (Fedora); on Ubuntu 24.04, if the warning persists after installing, follow the official docs to install the bwrap-userns-restrict AppArmor profile into /etc/apparmor.d/ and then load it.
❌ Taking a shortcut and turning on danger-full-access
The official security guidance is blunt: --dangerously-bypass-approvals-and-sandbox should only be used in controlled environments like a dedicated sandbox VM. Stay on workspace-write for everyday work; to let it write to directories outside the workspace, specify them with --add-dir instead of opening everything up. Also remember: handing approvals to automatic review (Approve for me) does not expand the sandbox — it just reviews out-of-bounds requests for you; the boundary stays the same.
❌ Treating login credentials as ordinary files
Codex caches login credentials in ~/.codex/auth.json (or the system credential store), and the official docs explicitly say to "treat them like passwords": don't commit them to repos, don't paste them into tickets, don't send them in group chats. For API key login, use the official pipe method printenv OPENAI_API_KEY | codex login --with-api-key rather than typing the key in plaintext on the command line.
Advanced tips (optional)
Leave a "manual" for your project. Run /init in a session, and Codex generates an AGENTS.md scaffold in the current directory — write down verification commands, conventions, and pitfalls, and it will read it first in every session. For a detailed guide on how to write it, see AGENTS.md and CLAUDE.md: leaving a project manual for AI.
Use Codex as a Unix tool. In scripts and CI, use non-interactive mode codex exec, which exits automatically when done, with output you can pipe straight to other tools:
codex exec "generate release notes for the last 10 commits" | tee release-notes.mdcodex exec runs in a read-only sandbox by default; to let it modify files, add --sandbox workspace-write. Starting with 0.169.0 (2026-11-13), in untrusted directories, codex exec disables project configuration and MCP servers, even with --sandbox workspace-write added; to explicitly save project trust, add --trust to codex exec or codex review.
Migrate your config from Claude Code. Run /import in a session, choose Claude Code (or Cursor), and import your config, project files, and recent chat history — the official docs say it finds up to 50 chats from the last 30 days.
Let it work even with your computer off. Open chatgpt.com/codex to hand tasks to the cloud: each task gets its own workspace and keeps running while your computer sleeps; later, review changes and submit PRs from the web, mobile, or desktop app. In the terminal, codex cloud lets you browse and submit cloud tasks.
Keep using it in your IDE. Install the openai.chatgpt extension in VS Code, Cursor, or Windsurf; files open in the editor and selected code go straight into the prompt; on desktop, a single codex app launches it.
Lesson summary
✅ The daily routine of the Codex tutorial = install the CLI → log in with your ChatGPT account → enter a directory and assign work → /permissions to watch the boundaries → /model to adjust the firepower → /diff to review, codex resume to resume. Once these six steps are turning, it's your on-call OpenAI coding agent in the terminal.
✅ It's an agent, not a chat box: it reads your local repo, edits files, and runs commands in the sandbox on its own — you're responsible for saying clearly "what to do, and what the result should look like".
✅ Four forms, one account: CLI (this lesson), IDE extension, desktop app (codex app), and Codex Web (chatgpt.com/codex cloud tasks).
✅ Two safety gates: sandbox (read-only / workspace-write / danger-full-access) + approvals (on-request / never); the everyday combo is workspace-write + on-request.
✅ Don't use the old model name: gpt-5.5 was retired on 2026-10-14; switch to gpt-6.2-sol (the default since 0.171.0) or gpt-6-luna (Free / Go).
Key operations recap:
| Operation | How to do it | Notes |
|---|---|---|
| Install | curl -fsSL https://chatgpt.com/codex/install.sh | sh (macOS/Linux); PowerShell install command (Windows) | Alternatives: npm, brew; re-run the install command to update |
| Sign in | Run codex and choose Sign in with ChatGPT | Check status with codex login status |
| Assign a task | Just type a description of the task | Official first task: Tell me about this project |
| Configure permissions | /permissions | Three sandbox levels + two approval levels |
| Switch models | /model or codex --model gpt-6.2-sol | default Sol, use gpt-6.2-astra for hard problems; gpt-5.5 is retired |
| Check status | /status | Model, approval policy, writable directories, token usage |
| View changes | /diff, /review | Includes new files untracked by Git |
| Resume a session | codex resume | Reopens the most recent chat in the current repository |
Next lesson preview
Once you're comfortable with Codex, the next lesson covers OpenCode from the open-source camp: OpenCode Usage: an open-source agent that works with any Chinese domestic model.
You will learn:
- What OpenCode is: an open-source AI coding agent not tied to any single model provider
- How to connect domestic models: DeepSeek, Kimi, Zhipu, and others are all in the official model catalog
- How to choose between OpenCode, Codex, and Claude Code, and how to use them together
- For a full cost table of all four tools, see price comparison