Skip to content

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 /model to switch models (such as the default gpt-6.2-sol), and /status to check session status and usage
  • Review changes with /diff and /review, compress long conversations with /compact, and pick old sessions back up with codex 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 ChatGPTCodex CLI
Code into contextYou copy and paste manuallyIt reads your local repository itself
Editing codeGives you snippets, you paste them back yourselfEdits files directly, /diff viewable
VerificationYou run commands yourselfIt runs tests in the sandbox, reads errors, and fixes them itself
BillingChat quotaCodex 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):

FormOne-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 extensionVS Code, Cursor, Windsurf sidebar (extension openai.chatgpt; Xcode and JetBrains have separate integrations)
Desktop appcodex app Launch the ChatGPT desktop app from the terminal (macOS/Windows), pick Codex in the app to start chatting
Codex WebOpen 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:

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

Windows users (run in a newly opened PowerShell window):

powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Option B: Package manager ​

bash
npm install -g @openai/codex
bash
brew install --cask codex

Verify after installation:

bash
codex --version

You 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 --version prints 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.

bash
cd /path/to/your/project
codex

The 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:

bash
codex login status

You 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):

bash
printenv OPENAI_API_KEY | codex login --with-api-key

Two 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 status shows 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.

text
Tell me about this project

How to phrase a few common kinds of tasks:

TaskWhat you say
Understand the projectTell me about this project (official example)
Make a small changeState clearly which file to change, what it should become, and what counts as done
Fix a bugPaste 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:

text
/permissions

You 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 modeMeaning
read-onlyLook only: editing files and running commands both require approval
workspace-writeFree read/write within the workspace and run routine commands (the official low-friction default)
danger-full-accessNo 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) or sudo dnf install bubblewrap (Fedora)

  • Quick check: /permissions opens 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:

text
/model

You 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:

bash
codex --model gpt-6.2-sol

Switch 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:

text
/status

You 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.

ScenarioActionEffect
See what it changed/diffGit diff, including new files Git hasn't tracked yet
Have it self-review/reviewSummarizes workspace issues (behavior changes, missing tests) without touching your files
Conversation gets slow when too long/compactCompresses history into a summary, freeing up context
Run a shell command directly! git statusOutput 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 tomorrowafter exiting codex resumeReopens 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 /diff and resumed a session with codex resume

Checkpoint ✅ ​

  • codex --version prints the version number, and codex login status shows I'm logged in
  • I started codex in 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 /permissions to switch approval presets, and I know the officially recommended combo is workspace-write + on-request
  • I can use /model to switch models (e.g. gpt-6.2-sol) and /status to check status; I know gpt-5.5 has been retired
  • I review changes with /diff; long conversations get /compact; sessions are resumed with codex 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:

bash
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

codex 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:

OperationHow to do itNotes
Installcurl -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 inRun codex and choose Sign in with ChatGPTCheck status with codex login status
Assign a taskJust type a description of the taskOfficial first task: Tell me about this project
Configure permissions/permissionsThree sandbox levels + two approval levels
Switch models/model or codex --model gpt-6.2-soldefault Sol, use gpt-6.2-astra for hard problems; gpt-5.5 is retired
Check status/statusModel, approval policy, writable directories, token usage
View changes/diff, /reviewIncludes new files untracked by Git
Resume a sessioncodex resumeReopens 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
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.