Links marked with * are affiliate links. If a purchase is made through such links, we receive a commission.
You installed Codex, typed codex into your terminal, and wondered: "Okay, now what?"
Same here. OpenAI's coding agent evolves quickly. Commands for sessions, plugins, Cloud, and remote control are added while others change. Without a current reference, you lose track fast.
This article lays out every Codex command in one place. Each CLI command, every slash command, all flags, every keyboard shortcut for CLI and App. It's the most thorough Codex reference you'll find in English. If you'd rather compare Codex head-to-head with Claude Code, our in-depth Claude Code vs. OpenAI Codex comparison has you covered.
TL;DRKey Takeaways
This reference covers the current CLI, from codex exec and codex review to session archives, plugins, the app server, and Codex Cloud
Slash commands in the composer control the model, permissions, sessions, plan mode, and other TUI features. The table lists the introduction version for all 53 commands
Three sandbox modes (read-only, workspace-write, danger-full-access) and three approval policies control what Codex can do on your system
Codex Cloud can run work in remote environments. App-server and remote-control are clearly marked experimental
Installing and Starting Codex
Codex CLI installs via npm or Homebrew. On first launch, Codex asks you to sign in with your ChatGPT account or an API key.
# Install via npm
npm install -g @openai/codex
# Or via Homebrew
brew install --cask codex
# Sign in interactively (opens browser for OAuth)
codex login
# Sign in with an API key
echo $OPENAI_API_KEY | codex login --with-api-key
# Check login status
codex login status
# Sign out
codex logout
# Start an interactive TUI session
codex
# Start with an initial prompt
codex "Explain the architecture of this project"
# Run non-interactively (for scripts)
codex exec -s workspace-write -m gpt-5.6-terra "Refactor auth.ts"
# Launch the desktop app
codex app
Tip
Always start Codex inside the right project folder. You can also set the working directory explicitly with --cd /path/to/project.
CLI Commands (Overview)
Codex comes in two flavors. The CLI runs in your terminal. The App is a desktop application for macOS and Windows. The "Example" column shows the typical usage of each command.
Commandcodex
DescriptionStart an interactive TUI session in the terminal
Examplecodex
Commandcodex app
DescriptionLaunch the Codex desktop app (macOS/Windows)
Examplecodex app
Commandcodex agents
DescriptionBrowse agent sessions on the local app-server daemon
Examplecodex agents
Commandcodex app-server
DescriptionExperimental: start the app server for development, debugging, or remote connections
Experimental: start, stop, or pair the remotely controllable app-server daemon
codex remote-control pair
codex queue
Queue a message for an existing local session
codex queue --thread SESSION --message "Continue with the tests"
codex migrate-rollouts
Inspect or migrate older local sessions to paginated thread history
codex migrate-rollouts --verbose
Note
codex exec is the command you'll use most for automation. It runs tasks non-interactively and prints the result to stdout. Perfect for scripts and CI/CD pipelines.
codex exec: Flags for Non-Interactive Execution
codex exec is your workhorse for automated workflows. Set the sandbox and approval policy deliberately, so a scripted run behaves predictably and its access remains clear.
# Standard pattern for automated execution
codex -a never exec -s workspace-write -m gpt-5.6-terra "your prompt"
# Maximum reasoning depth
codex -a on-request exec -s workspace-write -m gpt-5.6-sol \
-c model_reasoning_effort='"xhigh"' "complex task"
# Read-only for analysis (no file changes)
codex exec -s read-only -m gpt-5.6-luna "Analyze the architecture"
Flag--model, -m
DescriptionOverrides the model from your config
Example-m gpt-5.6-terra
Flag--sandbox, -s
DescriptionSandbox mode: read-only, workspace-write, or danger-full-access
Example-s workspace-write
FlagGlobal: --ask-for-approval, -a
DescriptionSets on-request or never and must appear before the exec subcommand
Examplecodex -a on-request exec "..."
Flag--cd, -C
DescriptionSets the working directory for the agent
Example-C /path/to/project
Flag--add-dir
DescriptionGrants additional writable directories
Example--add-dir ../backend
Flag--image, -i
DescriptionAttaches images to the prompt (repeatable)
Bypasses approvals and the sandbox entirely. Use only inside an externally hardened environment.
codex exec --yolo "..."
--approve-for-me
Routes approval requests through automatic review using the workspace-write sandbox
codex exec --approve-for-me "..."
--dangerously-bypass-hook-trust
Runs enabled hooks without persisted trust. Use only for already vetted automation.
codex exec --dangerously-bypass-hook-trust "..."
Warning
--yolo aliases --dangerously-bypass-approvals-and-sandbox. It bypasses both approvals and sandboxing. Use it only inside an externally hardened environment.
Common Patterns
# Attach images (screenshots, design specs)
codex exec -s workspace-write -m gpt-5.6-terra -i screenshot.png "Implement this UI"
# Multiple writable directories
codex exec -s workspace-write -C apps/frontend --add-dir ../backend "Sync API types"
# JSON output for scripts
codex exec -s workspace-write --json "List all TODO comments"
# Save the result to a file
codex exec -s workspace-write -o /tmp/result.txt "Summarize this codebase"
# Structured output with JSON Schema
codex exec -s workspace-write --output-schema schema.json "Extract all API endpoints"
# Pipe the prompt via stdin
cat prompt.txt | codex exec -s workspace-write -
# Use a config profile
codex exec -s workspace-write -p thorough "Thorough analysis"
# Local open-source model (Ollama or LM Studio)
codex exec --oss --local-provider ollama -s workspace-write "Explain this function"
# Strictly validate config before an automated run
codex exec --strict-config -s workspace-write "Check the configuration"
Code Review
codex review analyzes code changes non-interactively and prints the results to stdout. It doesn't modify files.
Flag--uncommitted
DescriptionReviews staged, unstaged, and untracked changes
Examplecodex review --uncommitted
Flag--base
DescriptionReviews changes against a base branch
Examplecodex review --base main
Flag--commit
DescriptionReviews a specific commit
Examplecodex review --commit abc123
Flag--title
DescriptionOptional title for the review summary
Examplecodex review --title "Add auth"
FlagPROMPT
DescriptionCustom review instructions (can also be piped via stdin with -)
Examplecodex review "Focus on security"
Flag
Description
Example
--uncommitted
Reviews staged, unstaged, and untracked changes
codex review --uncommitted
--base
Reviews changes against a base branch
codex review --base main
--commit
Reviews a specific commit
codex review --commit abc123
--title
Optional title for the review summary
codex review --title "Add auth"
PROMPT
Custom review instructions (can also be piped via stdin with -)
codex review "Focus on security"
# Review uncommitted changes (staged + unstaged + untracked)
codex review --uncommitted
# Review changes against a branch (before opening a PR)
codex review --base main
# Review a specific commit
codex review --commit abc123
# Review a commit with a title
codex review --commit abc123 --title "Add auth"
# Review with a custom focus
codex review "Focus on security"
# Review via exec with JSON output
codex exec review --uncommitted --json
Session Management
Codex stores non-ephemeral sessions locally. You can resume, fork, archive, or pick them up non-interactively.
# Interactive: open the session picker
codex resume
# Interactive: resume the most recent session directly
codex resume --last
# Non-interactive: resume the latest session with a new prompt
codex exec resume --last -s workspace-write -m gpt-5.6-terra \
"Now add error handling"
# Resume a specific session by UUID
codex exec resume 7f9f9a2e-1b3c-4c7a... -s workspace-write -m gpt-5.6-terra \
"Implement the plan"
# Fork a session (new thread from existing context)
codex fork --last
# Archive or restore a session
codex archive SESSION
codex unarchive SESSION
# Permanently delete a session
codex delete SESSION
# Apply a diff from a local session
codex apply TASK_ID
# Apply a diff from a cloud task
codex cloud apply TASK_ID
# Apply a specific attempt (when using --attempts N)
codex cloud apply TASK_ID --attempt 2
Tip
Sessions started with --ephemeral aren't saved to disk. Use this for quick one-off questions where you don't need any history.
Codex Cloud
Codex Cloud works with remote environments. Without a subcommand, codex cloud opens a picker. codex cloud exec submits a task directly, and requires --env.
Flag--env
DescriptionRequired: target environment ID for the cloud task
Example--env ENV_ID
Flag--attempts
DescriptionNumber of attempts (best-of-N), default: 1
Attempt number for diff/apply (when using --attempts N)
codex cloud diff TASK_ID --attempt 2
# Submit a task
codex cloud exec --env ENV_ID "Refactor the payment module"
# Best-of-3: run three attempts
codex cloud exec --env ENV_ID --attempts 3 "Fix the flaky test"
# Run on a specific branch
codex cloud exec --env ENV_ID --branch feature/auth "Add OAuth"
# List tasks
codex cloud list
codex cloud list --json --limit 5
# Check the status
codex cloud status TASK_ID
# Show the diff (specific attempt)
codex cloud diff TASK_ID --attempt 2
App Server and Remote Control
App-server, remote connections, and remote-control are experimental. They are for advanced setups and may change between releases. You do not need them for everyday Codex work.
# Start an app server with a WebSocket endpoint
codex app-server --listen ws://127.0.0.1:4500
# Connect the TUI to an app server
codex --remote ws://127.0.0.1:4500
# Manage the remote-control daemon
codex remote-control start
codex remote-control pair
codex remote-control stop
# Diagnose the model catalog and local installation
codex debug models --bundled
codex doctor --summary
Sandbox Modes
The sandbox limits what Codex can do on your system. You pick the mode with -s or --sandbox.
Moderead-only
ReadAnywhere
WriteNowhere
NetworkNo
When to useQuestions, explanations, code analysis
Modeworkspace-write
ReadAnywhere
WriteWorking dir only
NetworkNo
When to useDefault for most tasks
Modedanger-full-access
ReadAnywhere
WriteAnywhere
NetworkYes
When to useOnly when truly needed (e.g., installing packages)
Mode
Read
Write
Network
When to use
read-only
Anywhere
Nowhere
No
Questions, explanations, code analysis
workspace-write
Anywhere
Working dir only
No
Default for most tasks
danger-full-access
Anywhere
Anywhere
Yes
Only when truly needed (e.g., installing packages)
Codex also ships with a codex sandbox command that lets you run any command inside the sandbox without involving the agent:
# Run a command in the current Codex sandbox
codex sandbox -- npm test
# Log denied accesses on macOS
codex sandbox --log-denials -- ./build.sh
# Set a project folder as the working directory
codex sandbox -C apps/frontend -- npm test
Approval Policies
Approval policies control when Codex asks for permission before running a command. Set the global -a or --ask-for-approval flag before the subcommand, for example codex -a on-request exec.
Policyon-request
BehaviorThe model decides when to ask for approval
Policynever
BehaviorNever asks for approval; failures go straight back to the model
Policy
Behavior
on-request
The model decides when to ask for approval
never
Never asks for approval; failures go straight back to the model
Note
Inside the interactive TUI you switch approval mode with /permissions. Three presets are available: Auto (default), Read Only, and Full Access.
MCP Servers (Model Context Protocol)
Codex can connect to MCP servers for extra tools (databases, APIs, GitHub, and more). All management commands are non-interactive.
# List configured servers
codex mcp list
codex mcp list --json
# Show a server's config
codex mcp get my-server
codex mcp get my-server --json
# Add a stdio server
codex mcp add my-server -- npx -y @my/mcp-server
codex mcp add my-server --env API_KEY=sk-123 -- node server.js
# Add an HTTP server
codex mcp add my-server --url https://mcp.example.com/sse
codex mcp add my-server --url https://mcp.example.com \
--bearer-token-env-var MY_TOKEN_VAR
# Remove a server
codex mcp remove my-server
# OAuth login for an MCP server
codex mcp login my-server --scopes "read,write"
codex mcp logout my-server
Tip
With codex mcp-server you can run Codex itself as an MCP server. That makes it possible to plug Codex into other tools that speak MCP.
Slash Commands (CLI and App)
Slash commands are available in the interactive TUI (started with codex) and in the desktop app. Type / in the composer to open the list. While a task is running, you can type a slash command and press Tab to queue it for the next turn.
The CLI TUI has more slash commands than the app. The table lists currently documented commands, parameters, and their introduction versions. Individual commands may be unavailable depending on your platform, model, or enabled features.
I checked more than the release notes for this column. It lists the earliest regular Codex release whose source tree exposes the specific slash command. Renames such as /autoreview to /approve count from the version that introduced the new name.
Command/agents
Parameter
Since version0.149
DescriptionView and switch between all active agent sessions
Command/app
Parameter
Since version0.138
DescriptionOpen the current session in the desktop app
Command/apps
Parameter
Since version0.93
DescriptionBrowse apps and insert one into the prompt
Command/approve
Parameter
Since version0.129
DescriptionApprove one retry after an auto-review denial
Command/archive
Parameter
Since version0.136
DescriptionArchive the current session and exit Codex
Command/cd
Parameteroptional path
Since version0.149
DescriptionChange the current working directory
Command/clear
Parameteroptional name
Since version0.105
DescriptionClear the terminal and start a fresh chat
Command/compact
Parameter
Since version0.11
DescriptionSummarize the visible conversation to free context
Command/copy
Parameter
Since version0.105
DescriptionCopy the latest completed output (also Ctrl+O)
Command/debug-config
Parameter
Since version0.97
DescriptionPrint configuration layers and requirements diagnostics
Command/delete
Parameter
Since version0.140
DescriptionPermanently delete the current session and its child sessions
Command/diff
Parameter
Since version0.2
DescriptionShow the Git diff, including untracked files
Command/exit
Parameter
Since version0.53
DescriptionExit the CLI (alias /quit)
Command/experimental
Parameter
Since version0.74
DescriptionToggle experimental features
Command/export
Parameteroptional destination path
Since version0.148
DescriptionExport the conversation as Markdown
Command/fast
Parameter
Since version0.110
DescriptionToggle the Fast service tier when the active model offers one
Command/feedback
Parameter
Since version0.47
DescriptionSend diagnostic logs to the Codex maintainers
Command/fork
Parameter
Since version0.81
DescriptionFork the current conversation into a new chat
Command/goal
Parametergoal | edit | pause | resume | clear
Since version0.128
DescriptionSet, edit, pause, or clear a task goal
Command/hooks
Parameter
Since version0.129
DescriptionView and manage lifecycle hooks
Command/ide
Parameteroptional text
Since version0.129
DescriptionInclude open files, selection, and IDE context
Command/import
Parameter
Since version0.140
DescriptionImport supported Claude Code or Cursor setup, projects, and chats
Command/init
Parameter
Since version0.14
DescriptionGenerate an AGENTS.md scaffold for project context
Command/keymap
Parameter
Since version0.128
DescriptionRemap TUI keyboard shortcuts
Command/logout
Parameter
Since version0.15
DescriptionSign out of Codex
Command/mcp
Parameterverbose
Since version0.23
DescriptionList configured MCP tools
Command/memories
Parameter
Since version0.121
DescriptionConfigure memory use and generation
Command/mention
Parameterpath
Since version0.21
DescriptionAttach a file or folder to the conversation
Command/model
Parametermodel
Since version0.23
DescriptionChoose the active model and, when available, reasoning effort
Command/new
Parameteroptional name
Since version0.2
DescriptionStart a new chat in the same CLI session
Command/permissions
Parameter
Since version0.89
DescriptionSet what Codex can do without asking first
Command/personality
Parameter
Since version0.92
DescriptionChoose a communication style for responses
Command/pets
Parameter
Since version0.131
DescriptionChoose or hide a terminal pet (alias /pet)
Command/plan
Parameteroptional prompt
Since version0.93
DescriptionSwitch to plan mode
Command/plugins
Parameter
Since version0.117
DescriptionBrowse installed and discoverable plugins
Command/ps
Parameter
Since version0.76
DescriptionShow background terminals and their recent output
Command/pwd
Parameter
Since version0.149
DescriptionShow the current working directory (alias /cwd)
Command/raw
Parameteron | off
Since version0.129
DescriptionToggle raw scrollback mode
Command/rename
Parameteroptional name
Since version0.93
DescriptionRename the current chat
Command/resume
Parameter
Since version0.65
DescriptionResume a saved session from the session picker
Command/review
Parameter
Since version0.39
DescriptionAsk Codex to review the working tree
Command/sandbox-add-read-dir
Parameterabsolute path
Since version0.102
DescriptionGrant sandbox read access to a directory (Windows only)
Command/setup-default-sandbox
Parameter
Since version0.100
DescriptionSet up the elevated default sandbox (Windows only)
Command/side
Parameteroptional text
Since version0.122
DescriptionStart an ephemeral side conversation in a temporary fork (alias /btw)
Command/skills
Parameter
Since version0.65
DescriptionBrowse and use skills
Command/status
Parameter
Since version0.14
DescriptionShow the model, approval policy, writable roots, and token usage
Command/statusline
Parameter
Since version0.99
DescriptionConfigure TUI status-line fields
Command/stop
Parameter
Since version0.115
DescriptionStop all background terminals (alias /clean)
Command/subagents
Parameter
Since version0.115
DescriptionSwitch between this session's subagents
Command/theme
Parameter
Since version0.105
DescriptionChoose a syntax-highlighting theme
Command/title
Parameter
Since version0.117
DescriptionConfigure terminal-title fields
Command/usage
Parameterdaily | weekly | cumulative
Since version0.140
DescriptionView account token usage or request a rate-limit reset
Command/vim
Parameter
Since version0.129
DescriptionToggle Vim mode for the composer
Parameter
Description
/agents
0.149
View and switch between all active agent sessions
/app
0.138
Open the current session in the desktop app
/apps
0.93
Browse apps and insert one into the prompt
/approve
0.129
Approve one retry after an auto-review denial
/archive
0.136
Archive the current session and exit Codex
/cd
optional path
0.149
Change the current working directory
/clear
optional name
0.105
Clear the terminal and start a fresh chat
/compact
0.11
Summarize the visible conversation to free context
/copy
0.105
Copy the latest completed output (also Ctrl+O)
/debug-config
0.97
Print configuration layers and requirements diagnostics
/delete
0.140
Permanently delete the current session and its child sessions
/diff
0.2
Show the Git diff, including untracked files
/exit
0.53
Exit the CLI (alias /quit)
/experimental
0.74
Toggle experimental features
/export
optional destination path
0.148
Export the conversation as Markdown
/fast
0.110
Toggle the Fast service tier when the active model offers one
/feedback
0.47
Send diagnostic logs to the Codex maintainers
/fork
0.81
Fork the current conversation into a new chat
/goal
goal | edit | pause | resume | clear
0.128
Set, edit, pause, or clear a task goal
/hooks
0.129
View and manage lifecycle hooks
/ide
optional text
0.129
Include open files, selection, and IDE context
/import
0.140
Import supported Claude Code or Cursor setup, projects, and chats
/init
0.14
Generate an AGENTS.md scaffold for project context
/keymap
0.128
Remap TUI keyboard shortcuts
/logout
0.15
Sign out of Codex
/mcp
verbose
0.23
List configured MCP tools
/memories
0.121
Configure memory use and generation
/mention
path
0.21
Attach a file or folder to the conversation
/model
model
0.23
Choose the active model and, when available, reasoning effort
/new
optional name
0.2
Start a new chat in the same CLI session
/permissions
0.89
Set what Codex can do without asking first
/personality
0.92
Choose a communication style for responses
/pets
0.131
Choose or hide a terminal pet (alias /pet)
/plan
optional prompt
0.93
Switch to plan mode
/plugins
0.117
Browse installed and discoverable plugins
/ps
0.76
Show background terminals and their recent output
/pwd
0.149
Show the current working directory (alias /cwd)
/raw
on | off
0.129
Toggle raw scrollback mode
/rename
optional name
0.93
Rename the current chat
/resume
0.65
Resume a saved session from the session picker
/review
0.39
Ask Codex to review the working tree
/sandbox-add-read-dir
absolute path
0.102
Grant sandbox read access to a directory (Windows only)
/setup-default-sandbox
0.100
Set up the elevated default sandbox (Windows only)
/side
optional text
0.122
Start an ephemeral side conversation in a temporary fork (alias /btw)
/skills
0.65
Browse and use skills
/status
0.14
Show the model, approval policy, writable roots, and token usage
/statusline
0.99
Configure TUI status-line fields
/stop
0.115
Stop all background terminals (alias /clean)
/subagents
0.115
Switch between this session's subagents
/theme
0.105
Choose a syntax-highlighting theme
/title
0.117
Configure terminal-title fields
/usage
daily | weekly | cumulative
0.140
View account token usage or request a rate-limit reset
/vim
0.129
Toggle Vim mode for the composer
Keyboard Shortcuts: CLI (TUI)
These shortcuts work in the interactive terminal interface (started with codex). You can remap them with /keymap.
ShortcutCtrl+C
DescriptionCancels the current execution
ContextWhile the agent is working
ShortcutCtrl+D
DescriptionCloses the CLI
ContextWhen the input buffer is empty
ShortcutCtrl+G
DescriptionOpens external editor (VISUAL or EDITOR)
ContextFor long prompts
ShortcutCtrl+L
DescriptionClears the screen (without starting a new chat)
ContextWhen the terminal gets too cluttered
ShortcutCtrl+O
DescriptionCopies the last response to the clipboard
ContextAfter a response
ShortcutCtrl+R
DescriptionReverse search through prompt history
ContextIn the composer
ShortcutAlt+,
DescriptionLowers the reasoning depth
ContextDuring the session
ShortcutAlt+.
DescriptionRaises the reasoning depth
ContextDuring the session
ShortcutUp / Down
DescriptionNavigates the draft history in the composer
ContextIn the input field
ShortcutTab
DescriptionQueues follow-up text, slash commands, or shell commands
ContextWhile the agent is working
ShortcutEsc + Esc
DescriptionEdits the previous user message
ContextIn the composer
Shortcut@
DescriptionFuzzy file search for attaching files
ContextIn the input field
Shortcut!
DescriptionRuns a shell command directly
ContextAt the start of the input
Shortcut
Description
Context
Ctrl+C
Cancels the current execution
While the agent is working
Ctrl+D
Closes the CLI
When the input buffer is empty
Ctrl+G
Opens external editor (VISUAL or EDITOR)
For long prompts
Ctrl+L
Clears the screen (without starting a new chat)
When the terminal gets too cluttered
Ctrl+O
Copies the last response to the clipboard
After a response
Ctrl+R
Reverse search through prompt history
In the composer
Alt+,
Lowers the reasoning depth
During the session
Alt+.
Raises the reasoning depth
During the session
Up / Down
Navigates the draft history in the composer
In the input field
Tab
Queues follow-up text, slash commands, or shell commands
While the agent is working
Esc + Esc
Edits the previous user message
In the composer
@
Fuzzy file search for attaching files
In the input field
!
Runs a shell command directly
At the start of the input
Keyboard Shortcuts: Codex App
The desktop app (started with codex app) has its own shortcuts that follow common IDE conventions. On Windows, replace Cmd with Ctrl.
ShortcutCmd+Shift+P / Cmd+K
DescriptionOpens the command palette
ShortcutCmd+,
DescriptionOpens settings
ShortcutCmd+O
DescriptionOpens a folder
ShortcutCmd+N / Cmd+Shift+O
DescriptionNew thread
ShortcutCmd+F
DescriptionFind in thread
ShortcutCmd+B
DescriptionToggle sidebar
ShortcutCmd+Option+B
DescriptionToggle diff panel
ShortcutCmd+J
DescriptionToggle terminal
ShortcutCmd+Shift+[ / ]
DescriptionSwitch to previous / next thread
ShortcutCmd+[ / ]
DescriptionNavigate back / forward
ShortcutCmd++ / Cmd+-
DescriptionIncrease / decrease font size
ShortcutCtrl+L
DescriptionClear terminal
ShortcutCtrl+M
DescriptionStart dictation
Shortcut
Description
Cmd+Shift+P / Cmd+K
Opens the command palette
Cmd+,
Opens settings
Cmd+O
Opens a folder
Cmd+N / Cmd+Shift+O
New thread
Cmd+F
Find in thread
Cmd+B
Toggle sidebar
Cmd+Option+B
Toggle diff panel
Cmd+J
Toggle terminal
Cmd+Shift+[ / ]
Switch to previous / next thread
Cmd+[ / ]
Navigate back / forward
Cmd++ / Cmd+-
Increase / decrease font size
Ctrl+L
Clear terminal
Ctrl+M
Start dictation
Note
The app also supports deeplinks via the codex:// scheme, for example codex://settings for settings or codex://new?prompt=your+prompt for a new thread with a prompt.
Configuration (config.toml)
Codex config lives at ~/.codex/config.toml. You can set defaults and define named profiles.
Settingmodel
DescriptionDefault model for all sessions
Possible values"gpt-5.6-sol", "gpt-5.6-terra", or "gpt-5.6-luna", depending on your access
Settingmodel_reasoning_effort
DescriptionReasoning depth for complex tasks
Possible values"xhigh", "high", "medium", "low"
Settingpersonality
DescriptionCommunication style of the agent
Possible values"pragmatic", "friendly", "none"
Settingweb_search
DescriptionWeb search mode
Possible values"cached" (default), "live", "disabled"
Setting
Description
Possible values
model
Default model for all sessions
"gpt-5.6-sol", "gpt-5.6-terra", or "gpt-5.6-luna", depending on your access
model_reasoning_effort
Reasoning depth for complex tasks
"xhigh", "high", "medium", "low"
personality
Communication style of the agent
"pragmatic", "friendly", "none"
web_search
Web search mode
"cached" (default), "live", "disabled"
# ~/.codex/config.toml
# Default settings
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
# Profile for quick tasks
[profiles.quick]
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
# Profile for thorough work
[profiles.thorough]
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
# Project trust level
[projects."/path/to/project"]
trust_level = "trusted"
# Override a single value
codex exec -s workspace-write -c model='"gpt-5.6-terra"' "Task"
# Set sandbox permissions
codex exec -s workspace-write \
-c 'sandbox_permissions=["disk-full-read-access"]' "Task"
# Load a profile with -p
codex exec -s workspace-write -p quick "Quick question"
Feature Flags
Feature flags control both experimental and stable features. Changes via enable and disable are written permanently to config.toml. Per-run toggles with --enable and --disable only apply to the current run.
# List all feature flags with status and maturity
codex features list
# Permanently enable / disable a feature
codex features enable search_tool
codex features disable shell_snapshot
# Enable for this run only (not persistent)
codex exec -s workspace-write --enable search_tool \
--disable shell_snapshot "Task"
Global Flags
These flags are available on almost every Codex command:
Flag--config, -c
DescriptionOverrides config.toml values. Dotted paths for nesting. Values are parsed as TOML.
Example-c model_reasoning_effort='"high"'
Flag--enable
DescriptionEnables a feature flag for this run (repeatable)
Examplecodex --enable search_tool
Flag--disable
DescriptionDisables a feature flag for this run (repeatable)
Examplecodex --disable search_tool
Flag--model, -m
DescriptionChooses a model for the current run
Examplecodex -m gpt-5.6-terra
Flag--oss / --local-provider
DescriptionUses a local open-source model and chooses LM Studio or Ollama when needed
Examplecodex --oss --local-provider ollama
Flag--remote
DescriptionConnects the TUI, resume, fork, and session archive actions to an app server over WebSocket or a Unix socket
Examplecodex --remote ws://127.0.0.1:4500
Flag--remote-auth-token-env
DescriptionReads a bearer token from an environment variable for --remote
Example--remote-auth-token-env CODEX_REMOTE_TOKEN
Flag--sandbox, -s
DescriptionChooses read-only, workspace-write, or danger-full-access
Example-s workspace-write
Flag--ask-for-approval, -a
DescriptionSets the approval policy to on-request or never
Examplecodex -a on-request
Flag--search
DescriptionSwitches from the default cached search to live web search
Examplecodex --search "Check the current documentation"
Flag--no-alt-screen
DescriptionRuns the TUI inline and preserves terminal scrollback
Examplecodex --no-alt-screen
Flag--strict-config
DescriptionFails on unrecognized config.toml fields
Bypasses approvals and the sandbox. Use only inside an externally hardened environment.
codex --yolo "..."
--dangerously-bypass-hook-trust
Runs enabled hooks without persisted trust. Use only for already vetted automation.
codex --dangerously-bypass-hook-trust "..."
--help, -h
Shows help
codex --help
--version, -V
Shows the version number
codex --version
Troubleshooting
ProblemAuthentication fails
Likely causeStale token or wrong API key
SolutionRun codex logout, then codex login again
ProblemCodex hangs on codex exec
Likely causeThe approval policy requires confirmation in an unattended environment
SolutionFor controlled automation, set -s workspace-write and deliberately use -a never
ProblemCommand blocked in sandbox
Likely causeNetwork access or write access outside the working directory
SolutionFirst consider --add-dir for additional write paths. Use danger-full-access deliberately
ProblemMCP server doesn't connect
Likely causeMissing dependencies or wrong path
SolutionCheck codex mcp get server-name, then remove and add again
ProblemSession won't resume
Likely causeSession was started with --ephemeral
SolutionRestart without --ephemeral so sessions are saved
ProblemCloud task shows no diff
Likely causeTask is still running or has failed
SolutionCheck codex cloud status TASK_ID, then try again
ProblemCodex no longer starts after an update
Likely causeStale or unrecognized fields in config.toml
SolutionRun codex --strict-config and codex doctor --summary
Problem
Likely cause
Solution
Authentication fails
Stale token or wrong API key
Run codex logout, then codex login again
Codex hangs on codex exec
The approval policy requires confirmation in an unattended environment
For controlled automation, set -s workspace-write and deliberately use -a never
Command blocked in sandbox
Network access or write access outside the working directory
First consider --add-dir for additional write paths. Use danger-full-access deliberately
MCP server doesn't connect
Missing dependencies or wrong path
Check codex mcp get server-name, then remove and add again
Session won't resume
Session was started with --ephemeral
Restart without --ephemeral so sessions are saved
Cloud task shows no diff
Task is still running or has failed
Check codex cloud status TASK_ID, then try again
Codex no longer starts after an update
Stale or unrecognized fields in config.toml
Run codex --strict-config and codex doctor --summary
# Diagnose the config layers
# (in the interactive TUI)
/debug-config
# Show available models as JSON
codex debug models
# Show only the bundled model catalog (no API refresh)
codex debug models --bundled
# Validate exec policy rules (before saving)
codex execpolicy check --rules rules.toml -- npm test
# Log sandbox denials (debugging)
codex sandbox macos --log-denials -- ./build.sh
Finn Hillebrandt is the founder of Gradually AI, an SEO and AI expert. He helps online entrepreneurs simplify and automate their processes and marketing with AI. Finn shares his knowledge here on the blog in 50+ articles as well as through the AI Business Club.