All information is accurate as of 2026, based on the latest stable release of @openai/codex. Command names and mode labels may change — the official repository README is always the source of truth.
Starting Codex & signing in
Run codex from inside your project directory to open an interactive terminal session. On the first run, Codex prompts you to choose a sign-in method.
# Navigate into your project, then launch
$ cd ~/my-project
$ codex
# Or sign in explicitly before starting a session
$ codex login # browser OAuth with your ChatGPT account
$ codex login --with-api-key # paste an OpenAI API key
$ codex logout # sign outOption 1: ChatGPT account (browser OAuth)
Run codex login. A browser window opens and you complete the OAuth flow with your ChatGPT account. Once authorised, usage is drawn against your existing Plus or Pro subscription — no per-token billing on top. Best choice if you already have a ChatGPT subscription.
Option 2: API key
Run codex login --with-api-key and paste a key from platform.openai.com. Usage is billed by token against your API account. Good for teams without a ChatGPT subscription or those who need granular cost control.
Do not have both a ChatGPT OAuth session and an OPENAI_API_KEY environment variable set at the same time. The two auth paths conflict and can cause unstable connections. If you see a Reconnecting loop, run codex logout, then unset OPENAI_API_KEY, and re-authenticate with one method only.
Writing your first prompt
Once signed in, Codex opens an interactive session. Describe your task in plain language — Codex can read, change, and run code in the selected directory.
# Type your task in the composer and press Enter
› Add unit tests for the loginUser function in src/api/login.ts
# Codex reads files, edits code, and runs commands
› Find all TODO comments in the project and summarise them
› Do a local code review of my staged changes before I commitA few practical tips for clear prompts:
- Be specific about scope — name the file or function so Codex doesn't guess.
- One task at a time — smaller steps are easier to review and revert if needed.
- Attach screenshots — you can drag images straight into the composer; handy for UI bug reports.
Approval & sandbox modes
Codex safety works in two layers: the sandbox mode controls what Codex is technically allowed to do, and the approval policy determines when it must ask before acting.
Sandbox modes (as of 2026)
| Mode | What Codex can do | When to use it |
|---|---|---|
read-only |
Read files only — no edits, no commands | Exploring an unfamiliar codebase; analysis only |
workspace-write |
Read files, edit within the workspace, run routine local commands (default) | Day-to-day coding: writing code, running tests, tidying files |
danger-full-access |
No sandbox restrictions — any command | Only when you genuinely need to operate outside the workspace |
Approval policy: the Auto preset
The default Auto preset lets Codex read, edit, and run commands in the working directory automatically — it won't stop to ask at every step. If you want to chat without any file changes, switch to read-only via the /permissions slash command:
› /permissions
# Opens the permissions panel — select read-only to disable all writesWhen exploring an unfamiliar repo for the first time, start in read-only mode to let Codex map out the structure. Once you're confident in its understanding, switch to workspace-write and let it make changes.
Project rules with AGENTS.md
AGENTS.md is Codex's equivalent of a project brief — the instructions it reads before every task. Think of it as a concise "team wiki summary for the AI": coding conventions, off-limits files, and preferred commands, so you don't have to repeat them in every prompt.
Where to put it & load order
Codex loads every AGENTS.md it finds while walking from the home directory down to the working directory. All files are combined; entries closer to the working directory take precedence:
~/.codex/AGENTS.md— global rules (personal preferences, universal habits)~/my-project/AGENTS.md— project-root rules~/my-project/src/AGENTS.md— subdirectory rules (if present)
Generate one with /init
Inside any Codex session, run /init. Codex scans the project and writes a starter AGENTS.md — review it and edit to match your actual conventions:
› /init
# Codex scans the project and generates AGENTS.md — edit it afterwardsWhat to put in AGENTS.md
After generating the file, tailor it to your repo. Typical contents include:
# Project overview
Next.js 14 + TypeScript project managed with pnpm.
# Coding conventions
- All new files must be TypeScript — no plain JS
- Component filenames: PascalCase; utility functions: camelCase
- Run pnpm lint and pnpm test before every commit
# Off-limits
- Never modify .env.local
- Never delete files in migrations/
# Common commands
- Start dev server: pnpm dev
- Run tests: pnpm test
- Build: pnpm buildSlash commands
Type / in the Codex composer to see a full autocomplete list. The ones you'll reach for most often:
| Command | What it does |
|---|---|
/model |
Switch the active model (e.g. gpt-5.4, gpt-5.3-codex — as of 2026) |
/approvals / /permissions |
Adjust the approval policy and sandbox mode |
/init |
Generate an AGENTS.md for the current project |
/status |
Show connection state, active model, and config summary |
/feedback |
Submit feedback with request ID and error logs attached |
/fast |
Switch to speed-optimised mode |
/personality |
Adjust Codex's response style |
/agent |
Manage subagents for parallelising tasks |
/raw |
View raw request/response for debugging |
Typing / in the composer shows the full autocomplete list — you don't need to memorise every command.
Non-interactive mode: codex exec
Beyond interactive sessions, codex exec lets you pass a task description directly and have Codex run it non-interactively then exit. Useful for CI/CD pipelines and shell scripts:
# Run all tests and print a summary of failures
$ codex exec "run all unit tests and summarise any failures"
# Good for Makefiles or CI scripts
$ codex exec "check all TypeScript type errors in src/"In CI environments, pair codex exec with an explicit sandbox policy to avoid unintended file changes. Make sure your OPENAI_API_KEY or login credentials are present in the environment before running.
Frequently asked questions
ChatGPT login or API key — which is cheaper?
If you already have a ChatGPT Plus or Pro subscription, use codex login (OAuth). Your usage is covered by the subscription and there is no extra per-token charge on top. Without a subscription, use codex login --with-api-key and pay only for what you use — lower cost for infrequent usage.
Will Codex accidentally trash my codebase?
The default workspace-write sandbox keeps Codex inside your working directory — it won't reach outside. For extra caution, switch to read-only via /permissions for the analysis phase, then switch back when you're ready to let it make changes. Working inside a Git repository is strongly recommended: any unexpected change shows up immediately in git diff and can be reverted with one command.
Does AGENTS.md have to sit in the project root?
No. Codex loads every AGENTS.md it finds from your home directory down to the working directory. Put global preferences in ~/.codex/AGENTS.md, project-wide rules in the project root, and finer-grained overrides in subdirectories. All three layers are combined; the closest file to the working directory wins on conflicts.
Codex keeps showing Reconnecting — what now?
Almost always a network issue. Set HTTPS_PROXY in the same terminal you launch codex from, pointing to a local http proxy. Note that socks5 is not supported — convert it to http. For a full step-by-step checklist, see Stuck on Reconnecting.