OpenAI - Codex Docs Changes 2026-03-08 18:10 UTC → 2026-03-20 00:35 UTC

10 10 

11For a high-level explanation of how sandboxing works across the Codex app, IDE11For a high-level explanation of how sandboxing works across the Codex app, IDE

12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).12extension, and CLI, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing).

13For a broader enterprise security overview, see the [Codex security white paper](https://trust.openai.com/?itemUid=382f924d-54f3-43a8-a9df-c39e6c959958&source=click).

13 14 

14## Sandbox and approvals15## Sandbox and approvals

15 16 

80 81 

81If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.82If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

82 83 

83For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.84For a middle ground, `approval_policy = { granular = { ... } }` lets you keep specific approval prompt categories interactive while automatically rejecting others. The granular policy covers sandbox approvals, execpolicy-rule prompts, MCP elicitations, `request_permissions` prompts, and skill-script approvals.

84 85 

85### Common sandbox and approval combinations86### Common sandbox and approval combinations

86 87 

110[sandbox_workspace_write]111[sandbox_workspace_write]

111network_access = true112network_access = true

112 113 

113# Optional: granular approval prompt auto-rejection114# Optional: granular approval policy

114# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }115# approval_policy = { granular = {

116# sandbox_approval = true,

117# rules = true,

118# mcp_elicitations = true,

119# request_permissions = false,

120# skill_approval = false

121# } }

115```122```

116 123 

117You can also save presets as profiles, then select them with `codex --profile <name>`:124You can also save presets as profiles, then select them with `codex --profile <name>`:

144Codex enforces the sandbox differently depending on your OS:151Codex enforces the sandbox differently depending on your OS:

145 152 

146- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.153- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

147- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.154- **Linux** uses the bubblewrap pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default bubblewrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes.

148- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.155- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

149 156 

150If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:157If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:

162```toml169```toml

163[windows]170[windows]

164sandbox = "unelevated" # or "elevated"171sandbox = "unelevated" # or "elevated"

172# sandbox_private_desktop = true # default; set false only for compatibility

165```173```

166 174 

167See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.175See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

41- Find and fix bugs in my codebase with minimal, high-confidence changes.41- Find and fix bugs in my codebase with minimal, high-confidence changes.

42 42 

43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).43 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).

44 If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

44 45 

45---46---

46 47 

21Requests include `method`, `params`, and `id`:21Requests include `method`, `params`, and `id`:

22 22 

23```json23```json

24{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.1-codex" } }24{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.4" } }

25```25```

26 26 

27Responses echo the `id` with either `result` or `error`:27Responses echo the `id` with either `result` or `error`:

99 },99 },

100});100});

101send({ method: "initialized", params: {} });101send({ method: "initialized", params: {} });

102send({ method: "thread/start", id: 1, params: { model: "gpt-5.1-codex" } });102send({ method: "thread/start", id: 1, params: { model: "gpt-5.4" } });

103```103```

104 104 

105## Core primitives105## Core primitives

123 123 

124Clients must send a single `initialize` request per transport connection before invoking any other method on that connection, then acknowledge with an `initialized` notification. Requests sent before initialization receive a `Not initialized` error, and repeated `initialize` calls on the same connection return `Already initialized`.124Clients must send a single `initialize` request per transport connection before invoking any other method on that connection, then acknowledge with an `initialized` notification. Requests sent before initialization receive a `Not initialized` error, and repeated `initialize` calls on the same connection return `Already initialized`.

125 125 

126The server returns the user agent string it will present to upstream services. Set `clientInfo` to identify your integration.126The server returns the user agent string it will present to upstream services plus `platformFamily` and `platformOs` values that describe the runtime target. Set `clientInfo` to identify your integration.

127 127 

128`initialize.params.capabilities` also supports per-connection notification opt-out via `optOutNotificationMethods`, which is a list of exact method names to suppress for that connection. Matching is exact (no wildcards/prefixes). Unknown method names are accepted and ignored.128`initialize.params.capabilities` also supports per-connection notification opt-out via `optOutNotificationMethods`, which is a list of exact method names to suppress for that connection. Matching is exact (no wildcards/prefixes). Unknown method names are accepted and ignored.

129 129 

159 },159 },

160 "capabilities": {160 "capabilities": {

161 "experimentalApi": true,161 "experimentalApi": true,

162 "optOutNotificationMethods": [162 "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]

163 "codex/event/session_configured",

164 "item/agentMessage/delta"

165 ]

166 }163 }

167 }164 }

168}165}

204- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.201- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.

205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.202- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.

206- `thread/loaded/list` - list the thread ids currently loaded in memory.203- `thread/loaded/list` - list the thread ids currently loaded in memory.

204- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.

207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.205- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

208- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.206- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.

209- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.207- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

215- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.213- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.

216- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.214- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.

217- `command/exec` - run a single command under the server sandbox without starting a thread/turn.215- `command/exec` - run a single command under the server sandbox without starting a thread/turn.

216- `command/exec/write` - write stdin bytes to a running `command/exec` session or close stdin.

217- `command/exec/resize` - resize a running PTY-backed `command/exec` session.

218- `command/exec/terminate` - terminate a running `command/exec` session.

218- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.219- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.

219- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.220- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

220- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).221- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

221- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).222- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

223- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata.

224- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.

222- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.225- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

223- `skills/config/write` - enable or disable skills by path.226- `skills/config/write` - enable or disable skills by path.

224- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.227- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.

233- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.236- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

234- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.237- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

235- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).238- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

239- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.

236 240 

237## Models241## Models

238 242 

315 319 

316```json320```json

317{ "method": "thread/start", "id": 10, "params": {321{ "method": "thread/start", "id": 10, "params": {

318 "model": "gpt-5.1-codex",322 "model": "gpt-5.4",

319 "cwd": "/Users/me/project",323 "cwd": "/Users/me/project",

320 "approvalPolicy": "never",324 "approvalPolicy": "never",

321 "sandbox": "workspaceWrite",325 "sandbox": "workspaceWrite",

570 "writableRoots": ["/Users/me/project"],574 "writableRoots": ["/Users/me/project"],

571 "networkAccess": true575 "networkAccess": true

572 },576 },

573 "model": "gpt-5.1-codex",577 "model": "gpt-5.4",

574 "effort": "medium",578 "effort": "medium",

575 "summary": "concise",579 "summary": "concise",

576 "personality": "friendly",580 "personality": "friendly",

713- The server rejects empty `command` arrays.717- The server rejects empty `command` arrays.

714- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).718- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).

715- When omitted, `timeoutMs` falls back to the server default.719- When omitted, `timeoutMs` falls back to the server default.

720- Set `tty: true` for PTY-backed sessions, and use `processId` when you plan to follow up with `command/exec/write`, `command/exec/resize`, or `command/exec/terminate`.

721- Set `streamStdoutStderr: true` to receive `command/exec/outputDelta` notifications while the command is running.

716 722 

717### Read admin requirements (`configRequirements/read`)723### Read admin requirements (`configRequirements/read`)

718 724 

773 779 

774- Exact-match only: `item/agentMessage/delta` suppresses only that method.780- Exact-match only: `item/agentMessage/delta` suppresses only that method.

775- Unknown method names are ignored.781- Unknown method names are ignored.

776- Applies to both legacy (`codex/event/*`) and v2 (`thread/*`, `turn/*`, `item/*`, etc.) notifications.782- Applies to the current `thread/*`, `turn/*`, `item/*`, and related v2 notifications.

777- Doesn't apply to requests, responses, or errors.783- Doesn't apply to requests, responses, or errors.

778 784 

779### Fuzzy file search events (experimental)785### Fuzzy file search events (experimental)

2 2 

3Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can combine automations with [skills](https://developers.openai.com/codex/skills) for more complex tasks.3Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can combine automations with [skills](https://developers.openai.com/codex/skills) for more complex tasks.

4 4 

5Automations run locally in the Codex app. The app needs to be running, and the5Automations run in the background in the Codex app. The app needs to be

6selected project needs to be available on disk.6running, and the selected project needs to be available on disk.

7 7 

8In Git repositories, each automation run starts in a new8In Git repositories, you can choose whether an automation runs in your local

9[worktree](https://developers.openai.com/codex/app/worktrees) so it doesn’t interfere with your main9project or on a new [worktree](https://developers.openai.com/codex/app/worktrees). Both options run in the

10checkout. In non-version-controlled projects, automations run directly in the10background. Worktrees keep automation changes separate from unfinished local

11work, while running in your local project can modify files you are still

12working on. In non-version-controlled projects, automations run directly in the

11project directory.13project directory.

12 14 

13![Automation creation form with schedule and prompt fields](/images/codex/app/create-automation-light.webp)15You can also leave the model and reasoning effort on their default settings, or

16choose them explicitly if you want more control over how the automation runs.

17 

18![Automation creation form with schedule and prompt fields](/images/codex/app/codex-automations-light.webp)

14 19 

15## Managing tasks20## Managing tasks

16 21 

18 23 

19The "Triage" section acts as your inbox. Automation runs with findings show up there, and you can filter your inbox to show all automation runs or only unread ones.24The "Triage" section acts as your inbox. Automation runs with findings show up there, and you can filter your inbox to show all automation runs or only unread ones.

20 25 

21When an automation runs in a Git repository, Codex uses a dedicated background [worktree](https://developers.openai.com/codex/app/features#worktree-support). In non-version-controlled projects, automations run directly in the project directory. Consider using Git to enable running on background worktrees. You can have the same automation run on multiple projects.26For Git repositories, each automation can run either in your local project or

27on a dedicated background [worktree](https://developers.openai.com/codex/app/features#worktree-support). Use

28worktrees when you want to isolate automation changes from unfinished local

29work. Use local mode when you want the automation to work directly in your main

30checkout, keeping in mind that it can modify files you are actively editing.

31In non-version-controlled projects, automations run directly in the project

32directory. You can have the same automation run on multiple projects.

22 33 

23Automations use your default sandbox settings. In read-only mode, tool calls fail if they require modifying files, network access, or working with apps on your computer. With full access enabled, background automations carry elevated risk. You can adjust sandbox settings in [Settings](https://developers.openai.com/codex/app/settings) and selectively allowlist commands with [rules](https://developers.openai.com/codex/rules).34Automations use your default sandbox settings. In read-only mode, tool calls fail if they require modifying files, network access, or working with apps on your computer. With full access enabled, background automations carry elevated risk. You can adjust sandbox settings in [Settings](https://developers.openai.com/codex/app/settings) and selectively allowlist commands with [rules](https://developers.openai.com/codex/rules).

24 35 

30first. This helps you confirm:41first. This helps you confirm:

31 42 

32- The prompt is clear and scoped correctly.43- The prompt is clear and scoped correctly.

33- The selected model and tools behave as expected.44- The selected or default model, reasoning effort, and tools behave as expected.

34- The resulting diff is reviewable.45- The resulting diff is reviewable.

35 46 

36When you start scheduling runs, review the first few outputs closely and adjust47When you start scheduling runs, review the first few outputs closely and adjust

38 49 

39## Worktree cleanup for automations50## Worktree cleanup for automations

40 51 

41For Git repositories, automations run in worktrees. Frequent schedules can52If you choose worktrees for Git repositories, frequent schedules can create

42create many worktrees over time. Archive automation runs you no longer need,53many worktrees over time. Archive automation runs you no longer need, and avoid

43and avoid pinning runs unless you intend to keep their worktrees.54pinning runs unless you intend to keep their worktrees.

44 55 

45## Permissions and security model56## Permissions and security model

46 57 

48| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |48| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |

49| `/status` | Show the thread ID, context usage, and rate limits. |49| `/status` | Show the thread ID, context usage, and rate limits. |

50 50 

51## Deeplinks

52 

53The Codex app registers the `codex://` URL scheme so links can open specific parts of the app directly.

54 

55| Deeplink | Opens | Supported query parameters |

56| --- | --- | --- |

57| `codex://settings` | Settings. | None. |

58| `codex://skills` | Skills. | None. |

59| `codex://automations` | Inbox in automation create mode. | None. |

60| `codex://threads/<thread-id>` | A local thread. `<thread-id>` must be a UUID. | None. |

61| `codex://new` | A new thread. | Optional: `prompt`, `originUrl`, `path`. |

62 

63For new-thread deeplinks:

64 

65- `prompt` prefills the composer.

66- `path` must be an absolute path to a local directory and, when valid, makes that directory the active workspace for the new thread.

67- `originUrl` tries to match one of your current workspace roots by Git remote URL. If both `path` and `originUrl` are present, Codex resolves `path` first.

68 

51## See also69## See also

52 70 

53- [Features](https://developers.openai.com/codex/app/features)71- [Features](https://developers.openai.com/codex/app/features)

85pressing <kbd>Cmd</kbd>+<kbd>J</kbd>.85pressing <kbd>Cmd</kbd>+<kbd>J</kbd>.

86 86 

87Use the terminal to validate changes, run scripts, and perform Git operations87Use the terminal to validate changes, run scripts, and perform Git operations

88without leaving the app.88without leaving the app. Codex can also read the current terminal output, so

89it can check the status of a running development server or refer back to a

90failed build while it works with you.

89 91 

90Common tasks include:92Common tasks include:

91 93 

10require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts or prevent sleep while a10require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts or prevent sleep while a

11thread runs.11thread runs.

12 12 

13## Appearance

14 

15Pick a theme, decide whether the window is solid, and adjust UI or code fonts. Font

16choices apply across the app, including the diff review panel and terminal.

17 

18## Notifications13## Notifications

19 14 

20Choose when turn completion notifications appear, and whether the app should prompt for15Choose when turn completion notifications appear, and whether the app should prompt for

27options. See [Codex security](https://developers.openai.com/codex/agent-approvals-security) and22options. See [Codex security](https://developers.openai.com/codex/agent-approvals-security) and

28[config basics](https://developers.openai.com/codex/config-basic) for more detail.23[config basics](https://developers.openai.com/codex/config-basic) for more detail.

29 24 

25## Appearance

26 

27In **Settings**, you can change the Codex app appearance by choosing a base theme,

28adjusting accent, background, and foreground colors, and changing the UI and code

29fonts. You can also share your custom theme with friends.

30 

31![Codex app Appearance settings showing theme selection, color controls, and font options](/images/codex/app/theme-selection-light.webp)

32 

30## Git33## Git

31 34 

32Use Git settings to standardize branch naming and choose whether Codex uses force35Use Git settings to standardize branch naming and choose whether Codex uses force

28winget install Codex -s msstore28winget install Codex -s msstore

29```29```

30 30 

31## Native sandbox

32 

33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.

34 

35Running Codex in full access mode means Codex is not limited to your project

36 directory and might perform unintentional destructive actions that can lead to

37 data loss. Keep sandbox boundaries in place and use [rules](https://developers.openai.com/codex/rules) for

38 targeted exceptions, or set your [approval policy to

39 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

40 Codex attempt to solve problems without asking for escalated permissions,

41 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

42 

31## Customize for your dev setup43## Customize for your dev setup

32 44 

33### Preferred editor45### Preferred editor

91 91 

92These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).92These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

93 93 

94## Login diagnostics

95 

96Direct `codex login` runs write a dedicated `codex-login.log` file under

97your configured log directory. Use it when you need to debug browser-login or

98device-code failures, or when support asks for login-specific logs.

99 

100## Custom CA bundles

101 

102If your network uses a corporate TLS proxy or private root CA, set

103`CODEX_CA_CERTIFICATE` to a PEM bundle before logging in. When

104`CODEX_CA_CERTIFICATE` is unset, Codex falls back to `SSL_CERT_FILE`. The same

105custom CA settings apply to login, normal HTTPS requests, and secure websocket

106connections.

107 

108```shell

109export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem

110codex login

111```

112 

94## Login on headless devices113## Login on headless devices

95 114 

96If you are signing in to ChatGPT with the Codex CLI, there are some situations where the browser-based login UI may not work:115If you are signing in to ChatGPT with the Codex CLI, there are some situations where the browser-based login UI may not work:

3Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected directory.3Codex CLI is OpenAI's coding agent that you can run locally from your terminal. It can read, change, and run code on your machine in the selected directory.

4It's [open source](https://github.com/openai/codex) and built in Rust for speed and efficiency.4It's [open source](https://github.com/openai/codex) and built in Rust for speed and efficiency.

5 5 

6Codex is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans. Learn more about [what’s included](https://developers.openai.com/codex/pricing).6ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).

7 7 

8## CLI setup8## CLI setup

9 9 

47experimental. For the best Windows experience, use Codex in a WSL workspace47experimental. For the best Windows experience, use Codex in a WSL workspace

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).

49 49 

50If you're new to Codex, read the [best practices guide](https://developers.openai.com/codex/learn/best-practices).

51 

50---52---

51 53 

52## Work with the Codex CLI54## Work with the Codex CLI

59 61 

60Attach screenshots or design specs so Codex reads them alongside your prompt.](https://developers.openai.com/codex/cli/features#image-inputs)[### Run local code review62Attach screenshots or design specs so Codex reads them alongside your prompt.](https://developers.openai.com/codex/cli/features#image-inputs)[### Run local code review

61 63 

62Get your code reviewed by a separate Codex agent before you commit or push your changes.](https://developers.openai.com/codex/cli/features#running-local-code-review)[### Use multi-agent64Get your code reviewed by a separate Codex agent before you commit or push your changes.](https://developers.openai.com/codex/cli/features#running-local-code-review)[### Use subagents

63 65 

64Enable experimental multi-agent collaboration and parallelize complex tasks.](https://developers.openai.com/codex/multi-agent)[### Web search66Use subagents to parallelize complex tasks.](https://developers.openai.com/codex/subagents)[### Web search

65 67 

66Use Codex to search the web and get up-to-date information for your task.](https://developers.openai.com/codex/cli/features#web-search)[### Codex Cloud tasks68Use Codex to search the web and get up-to-date information for your task.](https://developers.openai.com/codex/cli/features#web-search)[### Codex Cloud tasks

67 69 

20 20 

21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred color theme.23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred theme.

24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.24- Use `/clear` to wipe the terminal and start a fresh chat, or press <kbd>Ctrl</kbd>+<kbd>L</kbd> to clear the screen without starting a new conversation.

25- Use `/copy` to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.25- Use `/copy` to copy the latest completed Codex output. If a turn is still running, Codex copies the most recent finished output instead of in-progress text.

26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.26- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

46 46 

47## Models and reasoning47## Models and reasoning

48 48 

49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship frontier model, combining frontier coding performance with stronger reasoning, native computer use, and broader professional workflows. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the

50industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship

51frontier model, combining frontier coding performance with stronger reasoning,

52native computer use, and broader professional workflows. For extra fast tasks,

53ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in

54research preview.

50 55 

51Switch models mid-session with the `/model` command, or specify one when launching the CLI.56Switch models mid-session with the `/model` command, or specify one when launching the CLI.

52 57 

68 73 

69`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.74`codex features enable <feature>` and `codex features disable <feature>` write to `~/.codex/config.toml`. If you launch Codex with `--profile`, Codex stores the change in that profile rather than the root configuration.

70 75 

71## Multi-agents (experimental)76## Subagents

72 77 

73Use Codex multi-agent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Multi-agents](https://developers.openai.com/codex/multi-agent).78Use Codex subagent workflows to parallelize larger tasks. For setup, role configuration (`[agents]` in `config.toml`), and examples, see [Subagents](https://developers.openai.com/codex/subagents).

79 

80Codex only spawns subagents when you explicitly ask it to. Because each

81subagent does its own model and tool work, subagent workflows consume more

82tokens than comparable single-agent runs.

74 83 

75## Image inputs84## Image inputs

76 85 

8This guide shows you how to:8This guide shows you how to:

9 9 

10- Find the right built-in slash command for a task10- Find the right built-in slash command for a task

11- Steer an active session with commands like `/model`, `/personality`,11- Steer an active session with commands like `/model`, `/fast`,

12 `/permissions`, `/experimental`, `/agent`, and `/status`12 `/personality`, `/permissions`, `/agent`, and `/status`

13 13 

14## Built-in slash commands14## Built-in slash commands

15 15 

20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

21| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |21| [`/permissions`](#update-permissions-with-permissions) | Set what Codex can do without asking first. | Relax or tighten approval requirements mid-session, such as switching between Auto and Read Only. |

22| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |22| [`/sandbox-add-read-dir`](#grant-sandbox-read-access-with-sandbox-add-read-dir) | Grant sandbox read access to an extra directory (Windows only). | Unblock commands that need to read an absolute directory path outside the current readable roots. |

23| [`/agent`](#switch-agent-threads-with-agent) | Switch the active agent thread. | Inspect or continue work in a spawned sub-agent thread. |23| [`/agent`](#switch-agent-threads-with-agent) | Switch the active agent thread. | Inspect or continue work in a spawned subagent thread. |

24| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |24| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |

25| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a clean slate. |25| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and conversation together when you want a clean slate. |

26| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |26| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

27| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |27| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. |

28| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |28| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |

29| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |29| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |

30| [`/experimental`](#toggle-experimental-features-with-experimental) | Toggle experimental features. | Enable optional features such as sub-agents from the CLI. |30| [`/experimental`](#toggle-experimental-features-with-experimental) | Toggle experimental features. | Enable optional features such as subagents from the CLI. |

31| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |31| [`/feedback`](#send-feedback-with-feedback) | Send logs to the Codex maintainers. | Report issues or share diagnostics with support. |

32| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |32| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

33| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |33| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |

34| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session. |34| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session. |

35| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |35| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |

36| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |36| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between general-purpose models (`gpt-4.1-mini`) and deeper reasoning models before running a task. |

37| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for GPT-5.4. | Turn Fast mode on or off, or check whether the current thread is using it. |

37| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |38| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |

38| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |39| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

39| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |40| [`/ps`](#check-background-terminals-with-ps) | Show experimental background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

63 64 

64Expected: Codex confirms the new model in the transcript. Run `/status` to verify the change.65Expected: Codex confirms the new model in the transcript. Run `/status` to verify the change.

65 66 

67### Toggle Fast mode with `/fast`

68 

691. Type `/fast on`, `/fast off`, or `/fast status`.

702. If you want the setting to persist, confirm the update when Codex offers to save it.

71 

72Expected: Codex reports whether Fast mode is on or off for the current thread. In the TUI footer, you can also show a Fast mode status-line item with `/statusline`.

73 

66### Set a communication style with `/personality`74### Set a communication style with `/personality`

67 75 

68Use `/personality` to change how Codex communicates without rewriting your prompt.76Use `/personality` to change how Codex communicates without rewriting your prompt.

92### Toggle experimental features with `/experimental`100### Toggle experimental features with `/experimental`

93 101 

941. Type `/experimental` and press Enter.1021. Type `/experimental` and press Enter.

952. Toggle the features you want (for example, **Multi-agents**), then restart Codex.1032. Toggle the features you want (for example, Apps or Smart Approvals), then restart Codex if the prompt asks you to.

96 104 

97Expected: Codex saves your feature choices to config and applies them on restart.105Expected: Codex saves your feature choices to config and applies them on restart.

98 106 

22 22 

23 Learn more](https://developers.openai.com/codex/explore) [### Community23 Learn more](https://developers.openai.com/codex/explore) [### Community

24 24 

25Explore Codex Ambassadors and upcoming community meetups by location.25Read community posts, explore meetups, and connect with Codex builders.

26 26 

27 See community](https://developers.openai.com/codex/community/meetups) [### Codex for OSS27 See community](/community) [### Codex for Open Source

28 28 

29Apply or nominate maintainers for API credits, ChatGPT Pro with Codex, and selective Codex Security access.29Apply or nominate maintainers for API credits, ChatGPT Pro with Codex, and selective Codex Security access.

30 30 

31 Learn more](https://developers.openai.com/codex/community/codex-for-oss)31 Learn more](https://developers.openai.com/community/codex-for-oss)

1# Codex for Open Source Program Terms1# Codex for Open Source Program Terms

2 2 

3These Program Terms govern the Codex for Open Source program (the “Program”) offered by OpenAI OpCo, LLC and its affiliates (“OpenAI,” “we,” “our,” or “us”). By submitting an application to the Program or accepting any Program benefit, you agree to these Program Terms.3These Program Terms govern the Codex for OSS program (the "Program") offered by OpenAI OpCo, LLC and its affiliates ("OpenAI," "we," "our," or "us"). By submitting an application to the Program or accepting any Program benefit, you agree to these Program Terms.

4 4 

5These Program Terms supplement, and do not replace, the OpenAI Terms of Use, Privacy Policy, applicable service terms, and OpenAI policies that govern your use of ChatGPT, Codex, the API, and any other OpenAI services made available through the Program. If there is a conflict, these Program Terms control only with respect to the Program.5These Program Terms supplement, and do not replace, the OpenAI Terms of Use, Privacy Policy, applicable service terms, and OpenAI policies that govern your use of ChatGPT, Codex, the API, and any other OpenAI services made available through the Program. If there is a conflict, these Program Terms control only with respect to the Program.

6 6 

7- **Project guidance (`AGENTS.md`)** for persistent instructions7- **Project guidance (`AGENTS.md`)** for persistent instructions

8- **Skills** for reusable workflows and domain expertise8- **Skills** for reusable workflows and domain expertise

9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems9- **[MCP](https://developers.openai.com/codex/mcp)** for access to external tools and shared systems

10- **[Multi-agents](https://developers.openai.com/codex/concepts/multi-agents)** for delegating work to specialized sub-agents10- **[Subagents](https://developers.openai.com/codex/concepts/subagents)** for delegating work to specialized subagents

11 11 

12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.12These are complementary, not competing. `AGENTS.md` shapes behavior, skills package repeatable processes, and [MCP](https://developers.openai.com/codex/mcp) connects Codex to systems outside the local workspace.

13 13 

19 19 

20- Build and test commands20- Build and test commands

21- Review expectations21- Review expectations

22- Repo-specific conventions22- repo-specific conventions

23- Directory-specific instructions23- Directory-specific instructions

24 24 

25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.25When the agent makes incorrect assumptions about your codebase, correct them in `AGENTS.md` and ask the agent to update `AGENTS.md` so the fix persists. Treat it as a feedback loop.

44 - AGENTS.md Global (for you as a developer)44 - AGENTS.md Global (for you as a developer)

45- repo-root/45- repo-root/

46 46 

47 - AGENTS.md Repo-specific (for your team)47 - AGENTS.md repo-specific (for your team)

48 48 

49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)49[Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)

50 50 

87 87 

88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.88Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

89 89 

90| Layer | Global | Repo |90| Layer | Global | repo |

91| :----- | :--------------------- | :--------------------------------------------- |91| :----- | :--------------------- | :--------------------------------------------- |

92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested dirs |92| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |

93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |93| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |

94 94 

95Codex uses progressive disclosure for skills:95Codex uses progressive disclosure for skills:

105## MCP105## MCP

106 106 

107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.107MCP (Model Context Protocol) is the standard way to connect Codex to external tools and context providers.

108It’s especially useful for remotely hosted systems such as Figma, Linear, Jira, GitHub, or internal knowledge services your team depends on.108It's especially useful for remotely hosted systems such as Figma, Linear, GitHub, or internal knowledge services your team depends on.

109 109 

110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.110Use MCP when Codex needs capabilities that live outside the local repo, such as issue trackers, design tools, browsers, or shared documentation systems.

111 111 

112A useful mental model:112One way to think about it:

113 113 

114- **Host**: Codex114- **Host**: Codex

115- **Client**: the MCP connection inside Codex115- **Client**: the MCP connection inside Codex

129 129 

130[Model Context Protocol](https://developers.openai.com/codex/mcp)130[Model Context Protocol](https://developers.openai.com/codex/mcp)

131 131 

132## Multi-agents132## Subagents

133 133 

134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each sub-agent stays focused and uses the right tools for its job.134You can create different agents with different roles and prompt them to use tools differently. For example, one agent might run specific testing commands and configurations, while another has MCP servers that fetch production logs for debugging. Each subagent stays focused and uses the right tools for its job.

135 135 

136[Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents)136[Subagent concepts](https://developers.openai.com/codex/concepts/subagents)

137 137 

138## Skills + MCP together138## Skills + MCP together

139 139 

146 146 

1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.1471. [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) so Codex follows your repo conventions. Add pre-commit hooks and linters to enforce those rules.

1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.1482. [Skills](https://developers.openai.com/codex/skills) so you never have the same conversation twice. Skills can include a `scripts/` directory with CLI scripts or pair with [MCP](https://developers.openai.com/codex/mcp) for external systems.

1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, JIRA, docs servers, design tools).1493. [MCP](https://developers.openai.com/codex/mcp) when workflows need external systems (Linear, GitHub, docs servers, design tools).

1504. [Multi-agents](https://developers.openai.com/codex/multi-agent) when you’re ready to delegate noisy or specialized tasks to sub-agents.1504. [Subagents](https://developers.openai.com/codex/subagents) when you're ready to delegate noisy or specialized tasks to subagents.

1# Subagents

2 

3Codex can run subagent workflows by spawning specialized agents in parallel so

4they can explore, tackle, or analyze work concurrently.

5 

6This page explains the core concepts and tradeoffs. For setup, agent configuration, and examples, see [Subagents](https://developers.openai.com/codex/subagents).

7 

8## Why subagent workflows help

9 

10Even with large context windows, models have limits. If you flood the main conversation (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

11 

12This is often described as:

13 

14- **Context pollution**: useful information gets buried under noisy intermediate output.

15- **Context rot**: performance degrades as the conversation fills up with less relevant details.

16 

17For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).

18 

19Subagent workflows help by moving noisy work off the main thread:

20 

21- Keep the **main agent** focused on requirements, decisions, and final outputs.

22- Run specialized **subagents** in parallel for exploration, tests, or log analysis.

23- Return **summaries** from subagents instead of raw intermediate output.

24 

25They can also save time when the work can run independently in parallel, and

26they make larger-shaped tasks more tractable by breaking them into bounded

27pieces. For example, Codex can split analysis of a multi-million-token

28document into smaller problems and return distilled takeaways to the main

29thread.

30 

31As a starting point, use parallel agents for read-heavy tasks such as

32exploration, tests, triage, and summarization. Be more careful with parallel

33write-heavy workflows, because agents editing code at once can create

34conflicts and increase coordination overhead.

35 

36## Core terms

37 

38Codex uses a few related terms in subagent workflows:

39 

40- **Subagent workflow**: A workflow where Codex runs parallel agents and combines their results.

41- **Subagent**: A delegated agent that Codex starts to handle a specific task.

42- **Agent thread**: The CLI thread for an agent, which you can inspect and switch between with `/agent`.

43 

44## Triggering subagent workflows

45 

46Codex doesn't spawn subagents automatically, and it should only use subagents when you

47explicitly ask for subagents or parallel agent work.

48 

49In practice, manual triggering means using direct instructions such as

50"spawn two agents," "delegate this work in parallel," or "use one agent per

51point." Subagent workflows consume more tokens than comparable single-agent runs

52because each subagent does its own model and tool work.

53 

54A good subagent prompt should explain how to divide the work, whether Codex

55should wait for all agents before continuing, and what summary or output to

56return.

57 

58```text

59Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

60```

61 

62## Choosing models and reasoning

63 

64Different agents need different model and reasoning settings.

65 

66If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup

67that balances intelligence, speed, and price for the task. It may favor

68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.4`

69configuration for more demanding reasoning. When you want finer control, steer that

70choice in your prompt or set `model` and `model_reasoning_effort` directly in

71the agent file.

72 

73For most tasks in Codex, start with `gpt-5.4`. Use `gpt-5.4-mini` when you

74want a faster, lower-cost option for lighter subagent work. If you have

75ChatGPT Pro and want near-instant text-only iteration, `gpt-5.3-codex-spark`

76remains available in research preview.

77 

78### Model choice

79 

80- **`gpt-5.4`**: Start here for most agents. It combines strong coding, reasoning, tool use, and broader workflows. The main agent and agents that coordinate ambiguous or multi-step work fit here.

81- **`gpt-5.4-mini`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

82- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

83 

84### Reasoning effort (`model_reasoning_effort`)

85 

86- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).

87- **`medium`**: A balanced default for most agents.

88- **`low`**: Use when the task is straightforward and speed matters most.

89 

90Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://developers.openai.com/codex/models), [Config basics](https://developers.openai.com/codex/config-basic), and [Configuration Reference](https://developers.openai.com/codex/config-reference).

2 2 

3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).3Use these options when you need more control over providers, policies, and integrations. For a quick start, see [Config basics](https://developers.openai.com/codex/config-basic).

4 4 

5For background on project guidance, reusable capabilities, custom slash commands, multi-agent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).5For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, see [Customization](https://developers.openai.com/codex/concepts/customization). For configuration keys, see [Configuration Reference](https://developers.openai.com/codex/config-reference).

6 6 

7## Profiles7## Profiles

8 8 

74 74 

75For shared defaults, rules, and skills checked into repos or system paths, see [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config).75For shared defaults, rules, and skills checked into repos or system paths, see [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config).

76 76 

77If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set environment variable `OPENAI_BASE_URL` instead of defining a new provider. This overrides the default OpenAI endpoint without a `config.toml` change.77If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, set `openai_base_url` in `config.toml` instead of defining a new provider. This changes the base URL for the built-in `openai` provider without requiring a separate `model_providers.<id>` entry.

78 78 

79```toml79```toml

80export OPENAI_BASE_URL="https://api.openai.com/v1"80openai_base_url = "https://us.api.openai.com/v1"

81codex

82```81```

83 82 

84## Project config files (`.codex/config.toml`)83## Project config files (`.codex/config.toml`)

87 86 

88For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores `.codex/config.toml` files in the project.87For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores `.codex/config.toml` files in the project.

89 88 

90Relative paths inside a project config (for example, `experimental_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.89Relative paths inside a project config (for example, `model_instructions_file`) are resolved relative to the `.codex/` folder that contains the `config.toml`.

91 90 

92## Agent roles (`[agents]` in `config.toml`)91## Agent roles (`[agents]` in `config.toml`)

93 92 

94For multi-agent role configuration (`[agents]` in `config.toml`), see [Multi-agents](https://developers.openai.com/codex/multi-agent).93For subagent role configuration (`[agents]` in `config.toml`), see [Subagents](https://developers.openai.com/codex/subagents).

95 94 

96## Project root detection95## Project root detection

97 96 

190 189 

191Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).190Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

192 191 

193For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).192For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

194 193 

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories, such as sandbox approvals, `execpolicy` rule prompts, or MCP input requests (`mcp_elicitations`), while keeping other prompts interactive.194You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically.

196 195 

197```196```

198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }197approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }

199sandbox_mode = "workspace-write"198sandbox_mode = "workspace-write"

200allow_login_shell = false # Optional hardening: disallow login shells for shell tools199allow_login_shell = false # Optional hardening: disallow login shells for shell tools

201 200 

201# Example granular approval policy:

202# approval_policy = { granular = {

203# sandbox_approval = true,

204# rules = true,

205# mcp_elicitations = true,

206# request_permissions = false,

207# skill_approval = false

208# } }

209 

202[sandbox_workspace_write]210[sandbox_workspace_write]

203exclude_tmpdir_env_var = false # Allow $TMPDIR211exclude_tmpdir_env_var = false # Allow $TMPDIR

204exclude_slash_tmp = false # Allow /tmp212exclude_slash_tmp = false # Allow /tmp

148| Key | Default | Maturity | Description |148| Key | Default | Maturity | Description |

149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |149| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |

150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |150| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

151| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |151| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

152| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |152| `multi_agent` | true | Stable | Enable subagent collaboration tools |

153| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |

154| `personality` | true | Stable | Enable personality selection controls |153| `personality` | true | Stable | Enable personality selection controls |

155| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |154| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |

156| `runtime_metrics` | false | Experimental | Show runtime metrics summaries in TUI turn separators |

157| `request_rule` | true | Stable | Enable Smart approvals (`prefix_rule` suggestions) |

158| `search_tool` | false | Experimental | Enable `search_tool_bm25` so Codex discovers Apps MCP tools via search before tool calls |

159| `shell_snapshot` | false | Beta | Snapshot your shell environment to speed up repeated commands |

160| `shell_tool` | true | Stable | Enable the default `shell` tool |155| `shell_tool` | true | Stable | Enable the default `shell` tool |

161| `use_linux_sandbox_bwrap` | false | Experimental | Use the bubblewrap-based Linux sandbox pipeline |156| `smart_approvals` | false | Experimental | Route eligible approval requests through the guardian reviewer subagent |

162| `unified_exec` | false | Beta | Use the unified PTY-backed exec tool |157| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

163| `undo` | true | Stable | Enable undo via per-turn git ghost snapshots |158| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

164| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |159| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

165| `web_search_cached` | true | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |160| `web_search_cached` | false | Deprecated | Legacy toggle that maps to `web_search = "cached"` when unset |

166| `web_search_request` | true | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |161| `web_search_request` | false | Deprecated | Legacy toggle that maps to `web_search = "live"` when unset |

167 162 

168The Maturity column uses feature maturity labels such as Experimental, Beta,163The Maturity column uses feature maturity labels such as Experimental, Beta,

169 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to164 and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to

18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |18| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset. |

19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |19| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |20| `analytics.enabled` | `boolean` | Enable or disable analytics for this machine/profile. When unset, the client default applies. |

21| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |21| `approval_policy` | `untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

22| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `approval_policy.granular.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected. |

23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |23| `approval_policy.granular.request_permissions` | `boolean` | When `true`, prompts from the `request_permissions` tool are allowed to surface. |

24| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |

25| `approval_policy.granular.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are allowed to surface. |

26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

25| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |27| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

26| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |28| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

27| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |29| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

38| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |40| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |

39| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |41| `commit_attribution` | `string` | Override the commit co-author trailer text. Set an empty string to disable automatic attribution. |

40| `compact_prompt` | `string` | Inline override for the history compaction prompt. |42| `compact_prompt` | `string` | Inline override for the history compaction prompt. |

43| `default_permissions` | `string` | Name of the default permissions profile to apply to sandboxed tool calls. |

41| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |44| `developer_instructions` | `string` | Additional developer instructions injected into the session (optional). |

42| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |45| `disable_paste_burst` | `boolean` | Disable burst-paste detection in the TUI. |

43| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |46| `experimental_compact_prompt_file` | `string (path)` | Load the compaction prompt override from a file (experimental). |

44| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |47| `experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |

45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |48| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

46| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

47| `features.artifact` | `boolean` | Enable native artifact tools such as slides and spreadsheets (under development). |

48| `features.child_agents_md` | `boolean` | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |

49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

50| `features.default_mode_request_user_input` | `boolean` | Allow `request_user_input` in default collaboration mode (under development; off by default). |

51| `features.elevated_windows_sandbox` | `boolean` | Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it. |

52| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |49| `features.enable_request_compression` | `boolean` | Compress streaming request bodies with zstd when supported (stable; on by default). |

53| `features.experimental_windows_sandbox` | `boolean` | Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it. |

54| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |50| `features.fast_mode` | `boolean` | Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default). |

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |51| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |

56| `features.image_generation` | `boolean` | Enable the built-in image generation tool (under development). |

57| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |

58| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |52| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

59| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

60| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |53| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

61| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

62| `features.request_rule` | `boolean` | Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset. |

63| `features.responses_websockets` | `boolean` | Prefer the Responses API WebSocket transport for supported providers (under development). |

64| `features.responses_websockets_v2` | `boolean` | Enable Responses API WebSocket v2 mode (under development). |

65| `features.runtime_metrics` | `boolean` | Show runtime metrics summary in TUI turn separators (experimental). |

66| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

67| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |54| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

68| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |55| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

69| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

70| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |56| `features.skill_mcp_dependency_install` | `boolean` | Allow prompting and installing missing MCP dependencies for skills (stable; on by default). |

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |57| `features.smart_approvals` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). |

72| `features.steer` | `boolean` | Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior. |

73| `features.undo` | `boolean` | Enable undo support (stable; off by default). |58| `features.undo` | `boolean` | Enable undo support (stable; off by default). |

74| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |59| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (stable; enabled by default except on Windows). |

75| `features.use_linux_sandbox_bwrap` | `boolean` | Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default). |

76| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |60| `features.web_search` | `boolean` | Deprecated legacy toggle; prefer the top-level `web_search` setting. |

77| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |61| `features.web_search_cached` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "cached"`. |

78| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |62| `features.web_search_request` | `boolean` | Deprecated legacy toggle. When `web_search` is unset, true maps to `web_search = "live"`. |

137| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |121| `notice.hide_world_writable_warning` | `boolean` | Track acknowledgement of the Windows world-writable directories warning. |

138| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |122| `notice.model_migrations` | `map<string,string>` | Track acknowledged model migrations as old->new mappings. |

139| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |123| `notify` | `array<string>` | Command invoked for notifications; receives a JSON payload from Codex. |

124| `openai_base_url` | `string` | Base URL override for the built-in `openai` model provider. |

140| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |125| `oss_provider` | `lmstudio | ollama` | Default local provider used when running with `--oss` (defaults to prompting if unset). |

141| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |126| `otel.environment` | `string` | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |

142| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |127| `otel.exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry exporter and provide any endpoint metadata. |

155| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |140| `otel.trace_exporter.<id>.tls.ca-certificate` | `string` | CA certificate path for OTEL trace exporter TLS. |

156| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |141| `otel.trace_exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL trace exporter TLS. |

157| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |142| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL trace exporter TLS. |

158| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |143| `permissions.<name>.filesystem` | `table` | Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`. |

159| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |144| `permissions.<name>.filesystem.":project_roots".<subpath>` | `"read" | "write" | "none"` | Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself. |

160| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |145| `permissions.<name>.filesystem.<path>` | `"read" | "write" | "none" | table` | Grant direct access for a path or special token, or scope nested entries under that root. |

161| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |146| `permissions.<name>.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |147| `permissions.<name>.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |148| `permissions.<name>.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

164| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |149| `permissions.<name>.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

165| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |150| `permissions.<name>.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

166| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |151| `permissions.<name>.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

167| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |152| `permissions.<name>.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

168| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |153| `permissions.<name>.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener when this permissions profile enables the managed network proxy. |

169| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |154| `permissions.<name>.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

170| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |155| `permissions.<name>.network.enabled` | `boolean` | Enable network access for this named permissions profile. |

171| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |156| `permissions.<name>.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

172| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |157| `permissions.<name>.network.proxy_url` | `string` | HTTP proxy endpoint used when this permissions profile enables the managed network proxy. |

158| `permissions.<name>.network.socks_url` | `string` | SOCKS5 proxy endpoint used by this permissions profile. |

173| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |159| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |

174| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |160| `plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Plan-mode-specific reasoning override. When unset, Plan mode uses its built-in preset default. |

175| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |161| `profile` | `string` | Default profile applied at startup (equivalent to `--profile`). |

195| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |181| `sandbox_workspace_write.exclude_tmpdir_env_var` | `boolean` | Exclude `$TMPDIR` from writable roots in workspace-write mode. |

196| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |182| `sandbox_workspace_write.network_access` | `boolean` | Allow outbound network access inside the workspace-write sandbox. |

197| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |183| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |

198| `service_tier` | `flex | fast` | Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled. |184| `service_tier` | `flex | fast` | Preferred service tier for new turns. |

199| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |185| `shell_environment_policy.exclude` | `array<string>` | Glob patterns for removing environment variables after the defaults. |

200| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |186| `shell_environment_policy.experimental_use_profile` | `boolean` | Use the user shell profile when spawning subprocesses. |

201| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |187| `shell_environment_policy.ignore_default_excludes` | `boolean` | Keep variables containing KEY/SECRET/TOKEN before other filters run. |

210| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |196| `suppress_unstable_features_warning` | `boolean` | Suppress the warning that appears when under-development feature flags are enabled. |

211| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |197| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |

212| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |198| `tools.view_image` | `boolean` | Enable the local-image attachment tool `view_image`. |

213| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |199| `tools.web_search` | `boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }` | Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location. |

214| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |200| `tui` | `table` | TUI-specific options such as enabling inline desktop notifications. |

215| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |201| `tui.alternate_screen` | `auto | always | never` | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |

216| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |202| `tui.animations` | `boolean` | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |

223| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |209| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

224| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |210| `windows_wsl_setup_acknowledged` | `boolean` | Track Windows onboarding acknowledgement (Windows only). |

225| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |211| `windows.sandbox` | `unelevated | elevated` | Windows-only native sandbox mode when running Codex natively on Windows. |

212| `windows.sandbox_private_desktop` | `boolean` | Run the final sandboxed child process on a private desktop by default on native Windows. Set `false` only for compatibility with the older `Winsta0\\Default` behavior. |

226 213 

227Key214Key

228 215 

326 313 

327Type / Values314Type / Values

328 315 

329`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`316`untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`

330 317 

331Details318Details

332 319 

333Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.320Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

334 321 

335Key322Key

336 323 

337`approval_policy.reject.mcp_elicitations`324`approval_policy.granular.mcp_elicitations`

338 325 

339Type / Values326Type / Values

340 327 

342 329 

343Details330Details

344 331 

345When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.332When `true`, MCP elicitation prompts are allowed to surface instead of being auto-rejected.

346 333 

347Key334Key

348 335 

349`approval_policy.reject.rules`336`approval_policy.granular.request_permissions`

350 337 

351Type / Values338Type / Values

352 339 

354 341 

355Details342Details

356 343 

357When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.344When `true`, prompts from the `request_permissions` tool are allowed to surface.

358 345 

359Key346Key

360 347 

361`approval_policy.reject.sandbox_approval`348`approval_policy.granular.rules`

362 349 

363Type / Values350Type / Values

364 351 

366 353 

367Details354Details

368 355 

369When `true`, sandbox escalation approval prompts are auto-rejected.356When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface.

357 

358Key

359 

360`approval_policy.granular.sandbox_approval`

361 

362Type / Values

363 

364`boolean`

365 

366Details

367 

368When `true`, sandbox escalation approval prompts are allowed to surface.

369 

370Key

371 

372`approval_policy.granular.skill_approval`

373 

374Type / Values

375 

376`boolean`

377 

378Details

379 

380When `true`, skill-script approval prompts are allowed to surface.

370 381 

371Key382Key

372 383 

562 573 

563Key574Key

564 575 

576`default_permissions`

577 

578Type / Values

579 

580`string`

581 

582Details

583 

584Name of the default permissions profile to apply to sandboxed tool calls.

585 

586Key

587 

565`developer_instructions`588`developer_instructions`

566 589 

567Type / Values590Type / Values

622 645 

623Key646Key

624 647 

625`features.apps_mcp_gateway`

626 

627Type / Values

628 

629`boolean`

630 

631Details

632 

633Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).

634 

635Key

636 

637`features.artifact`

638 

639Type / Values

640 

641`boolean`

642 

643Details

644 

645Enable native artifact tools such as slides and spreadsheets (under development).

646 

647Key

648 

649`features.child_agents_md`

650 

651Type / Values

652 

653`boolean`

654 

655Details

656 

657Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

658 

659Key

660 

661`features.collaboration_modes`

662 

663Type / Values

664 

665`boolean`

666 

667Details

668 

669Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

670 

671Key

672 

673`features.default_mode_request_user_input`

674 

675Type / Values

676 

677`boolean`

678 

679Details

680 

681Allow `request_user_input` in default collaboration mode (under development; off by default).

682 

683Key

684 

685`features.elevated_windows_sandbox`

686 

687Type / Values

688 

689`boolean`

690 

691Details

692 

693Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

694 

695Key

696 

697`features.enable_request_compression`648`features.enable_request_compression`

698 649 

699Type / Values650Type / Values

706 657 

707Key658Key

708 659 

709`features.experimental_windows_sandbox`

710 

711Type / Values

712 

713`boolean`

714 

715Details

716 

717Legacy toggle for an earlier Windows sandbox rollout. Current builds do not use it.

718 

719Key

720 

721`features.fast_mode`660`features.fast_mode`

722 661 

723Type / Values662Type / Values

730 669 

731Key670Key

732 671 

733`features.image_detail_original`

734 

735Type / Values

736 

737`boolean`

738 

739Details

740 

741Allow image outputs with `detail = "original"` on supported models (under development).

742 

743Key

744 

745`features.image_generation`

746 

747Type / Values

748 

749`boolean`

750 

751Details

752 

753Enable the built-in image generation tool (under development).

754 

755Key

756 

757`features.multi_agent`672`features.multi_agent`

758 673 

759Type / Values674Type / Values

762 677 

763Details678Details

764 679 

765Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).680Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

766 681 

767Key682Key

768 683 

778 693 

779Key694Key

780 695 

781`features.powershell_utf8`

782 

783Type / Values

784 

785`boolean`

786 

787Details

788 

789Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

790 

791Key

792 

793`features.prevent_idle_sleep`696`features.prevent_idle_sleep`

794 697 

795Type / Values698Type / Values

802 705 

803Key706Key

804 707 

805`features.remote_models`

806 

807Type / Values

808 

809`boolean`

810 

811Details

812 

813Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

814 

815Key

816 

817`features.request_rule`

818 

819Type / Values

820 

821`boolean`

822 

823Details

824 

825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

826 

827Key

828 

829`features.responses_websockets`

830 

831Type / Values

832 

833`boolean`

834 

835Details

836 

837Prefer the Responses API WebSocket transport for supported providers (under development).

838 

839Key

840 

841`features.responses_websockets_v2`

842 

843Type / Values

844 

845`boolean`

846 

847Details

848 

849Enable Responses API WebSocket v2 mode (under development).

850 

851Key

852 

853`features.runtime_metrics`

854 

855Type / Values

856 

857`boolean`

858 

859Details

860 

861Show runtime metrics summary in TUI turn separators (experimental).

862 

863Key

864 

865`features.search_tool`

866 

867Type / Values

868 

869`boolean`

870 

871Details

872 

873Legacy toggle for an older Apps discovery flow. Current builds do not use it.

874 

875Key

876 

877`features.shell_snapshot`708`features.shell_snapshot`

878 709 

879Type / Values710Type / Values

898 729 

899Key730Key

900 731 

901`features.skill_env_var_dependency_prompt`

902 

903Type / Values

904 

905`boolean`

906 

907Details

908 

909Prompt for missing skill environment-variable dependencies (under development).

910 

911Key

912 

913`features.skill_mcp_dependency_install`732`features.skill_mcp_dependency_install`

914 733 

915Type / Values734Type / Values

922 741 

923Key742Key

924 743 

925`features.sqlite`744`features.smart_approvals`

926 745 

927Type / Values746Type / Values

928 747 

930 749 

931Details750Details

932 751 

933Enable SQLite-backed state persistence (stable; on by default).752Route eligible approval requests through the guardian reviewer subagent (experimental; off by default).

934 

935Key

936 

937`features.steer`

938 

939Type / Values

940 

941`boolean`

942 

943Details

944 

945Legacy toggle from an earlier Enter/Tab steering rollout. Current builds always use the current steering behavior.

946 753 

947Key754Key

948 755