OpenAI - Codex Docs Changes 2026-02-24 00:33 UTC → 2026-03-03 18:20 UTC

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

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

207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.207- `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`.

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

209- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.210- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

210- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.211- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

227- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.228- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

228- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).229- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

229- `config/read` - fetch the effective configuration on disk after resolving configuration layering.230- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

231- `externalAgentConfig/detect` - detect migratable external-agent artifacts with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

232- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).

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

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

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

301- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.304- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.

302- `thread/loaded/list` returns the thread IDs currently in memory.305- `thread/loaded/list` returns the thread IDs currently in memory.

303- `thread/archive` moves the thread's persisted JSONL log into the archived directory.306- `thread/archive` moves the thread's persisted JSONL log into the archived directory.

307- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed`.

304- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.308- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.

305- `thread/compact/start` triggers compaction and returns `{}` immediately.309- `thread/compact/start` triggers compaction and returns `{}` immediately.

306- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.310- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.

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

316 "approvalPolicy": "never",320 "approvalPolicy": "never",

317 "sandbox": "workspaceWrite",321 "sandbox": "workspaceWrite",

318 "personality": "friendly"322 "personality": "friendly",

323 "serviceName": "my_app_server_client"

319} }324} }

320{ "id": 10, "result": {325{ "id": 10, "result": {

321 "thread": {326 "thread": {

322 "id": "thr_123",327 "id": "thr_123",

323 "preview": "",328 "preview": "",

329 "ephemeral": false,

324 "modelProvider": "openai",330 "modelProvider": "openai",

325 "createdAt": 1730910000331 "createdAt": 1730910000

326 }332 }

328{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }334{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

329```335```

330 336 

337`serviceName` is optional. Set it when you want app-server to tag thread-level metrics with your integration's service name.

338 

331To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:339To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:

332 340 

333```json341```json

335 "threadId": "thr_123",343 "threadId": "thr_123",

336 "personality": "friendly"344 "personality": "friendly"

337} }345} }

338{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes" } } }346{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

339```347```

340 348 

341Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.349Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.

365 373 

366```json374```json

367{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }375{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }

368{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "status": { "type": "notLoaded" }, "turns": [] } } }376{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

369```377```

370 378 

371Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.379Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.

405} }413} }

406{ "id": 20, "result": {414{ "id": 20, "result": {

407 "data": [415 "data": [

408 { "id": "thr_a", "preview": "Create a TUI", "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },416 { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },

409 { "id": "thr_b", "preview": "Fix tests", "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }417 { "id": "thr_b", "preview": "Fix tests", "ephemeral": true, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }

410 ],418 ],

411 "nextCursor": "opaque-token-or-null"419 "nextCursor": "opaque-token-or-null"

412} }420} }

437{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }445{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

438```446```

439 447 

448### Unsubscribe from a loaded thread

449 

450`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:

451 

452- `unsubscribed` when the connection was subscribed and is now removed.

453- `notSubscribed` when the connection was not subscribed to that thread.

454- `notLoaded` when the thread is not loaded.

455 

456If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.

457 

458```json

459{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }

460{ "id": 22, "result": { "status": "unsubscribed" } }

461{ "method": "thread/status/changed", "params": {

462 "threadId": "thr_123",

463 "status": { "type": "notLoaded" }

464} }

465{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

466```

467 

440### Archive a thread468### Archive a thread

441 469 

442Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.470Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.

470{ "id": 25, "result": {} }498{ "id": 25, "result": {} }

471```499```

472 500 

501### Roll back recent turns

502 

503Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.

504 

505```json

506{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }

507{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

508```

509 

473## Turns510## Turns

474 511 

475The `input` field accepts a list of items:512The `input` field accepts a list of items:

724 761 

725## Events762## Events

726 763 

727Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/status/changed`, `turn/*`, and `item/*` notifications.764Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `thread/status/changed`, `turn/*`, `item/*`, and `serverRequest/resolved` notifications.

728 765 

729### Notification opt-out766### Notification opt-out

730 767 

767- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.804- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.

768- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.805- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.

769- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.806- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.

807- `dynamicToolCall` - `{id, tool, arguments, status, contentItems?, success?, durationMs?}` for client-executed dynamic tool invocations.

770- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.808- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.

771- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.809- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.

772- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.810- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.

823Order of messages:861Order of messages:

824 862 

8251. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.8631. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.

8262. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, and optional `networkApprovalContext`.8642. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, optional `networkApprovalContext`, and optional `availableDecisions`. When `initialize.params.capabilities.experimentalApi = true`, the payload can also include experimental `additionalPermissions` describing requested per-command sandbox access. Any filesystem paths inside `additionalPermissions` are absolute on the wire.

8273. Client responds with one of the command execution approval decisions above.8653. Client responds with one of the command execution approval decisions above.

8284. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.8664. `serverRequest/resolved` confirms that the pending request has been answered or cleared.

8675. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.

829 868 

830When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.869When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.

831 870 

8381. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.8771. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.

8392. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.8782. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.

8403. Client responds with one of the file change approval decisions above.8793. Client responds with one of the file change approval decisions above.

8414. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.8804. `serverRequest/resolved` confirms that the pending request has been answered or cleared.

8815. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.

882 

883### `tool/requestUserInput`

884 

885When the client responds to `item/tool/requestUserInput`, app-server emits `serverRequest/resolved` with `{ threadId, requestId }`. If the pending request is cleared by turn start, turn completion, or turn interruption before the client answers, the server emits the same notification for that cleanup.

886 

887### Dynamic tool calls (experimental)

888 

889`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.

890 

891When a dynamic tool is invoked during a turn, app-server emits:

892 

8931. `item/started` with `item.type = "dynamicToolCall"`, `status = "inProgress"`, plus `tool` and `arguments`.

8942. `item/tool/call` as a server request to the client.

8953. The client response payload with returned content items.

8964. `item/completed` with `item.type = "dynamicToolCall"`, the final `status`, and any returned `contentItems` or `success` value.

842 897 

843### MCP tool-call approvals (apps)898### MCP tool-call approvals (apps)

844 899 

1088}1143}

1089```1144```

1090 1145 

1146### Detect and import external agent config

1147 

1148Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.

1149 

1150Detection example:

1151 

1152```json

1153{ "method": "externalAgentConfig/detect", "id": 63, "params": {

1154 "includeHome": true,

1155 "cwds": ["/Users/me/project"]

1156} }

1157{ "id": 63, "result": {

1158 "items": [

1159 {

1160 "itemType": "AGENTS_MD",

1161 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",

1162 "cwd": "/Users/me/project"

1163 },

1164 {

1165 "itemType": "SKILLS",

1166 "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",

1167 "cwd": null

1168 }

1169 ]

1170} }

1171```

1172 

1173Import example:

1174 

1175```json

1176{ "method": "externalAgentConfig/import", "id": 64, "params": {

1177 "migrationItems": [

1178 {

1179 "itemType": "AGENTS_MD",

1180 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",

1181 "cwd": "/Users/me/project"

1182 }

1183 ]

1184} }

1185{ "id": 64, "result": {} }

1186```

1187 

1188Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports do not overwrite existing skill directories.

1189 

1091## Auth endpoints1190## Auth endpoints

1092 1191 

1093The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.1192The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.

1# Codex app

2 

3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.

4 

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

6 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)

8 

9## Getting started

10 

11The Codex app is available on macOS (Apple Silicon).

12 

131. Download and install the Codex app

14 

15 The Codex app is currently only available for macOS.

16 

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

18 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)

202. Open Codex and sign in

21 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

23 

24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.

253. Select a project

26 

27 Choose a project folder that you want Codex to work in.

28 

29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.

30 

314. Send your first message

32 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.

34 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:

36 

37- Tell me about this project

38- Build a classic Snake game in this repo.

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

40 

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

42 

43---

44 

45## Work with the Codex app

46 

47[### Multitask across projects

48 

49Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools

50 

51Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks

52 

53Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support

54 

55Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations

56 

57Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal

58 

59Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments

60 

61Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension

62 

63Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support

64 

65Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)

66 

67---

68 

69Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).

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

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.

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

25- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.27- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

26 28 

1# Slash commands in Codex CLI1# Slash commands in Codex CLI

2 2 

3Slash commands give you fast, keyboard-first control over Codex. Type `/` in the composer to open the slash popup, choose a command, and Codex will perform actions such as switching models, adjusting permissions, or summarizing long conversations without leaving the terminal.3Slash commands give you fast, keyboard-first control over Codex. Type `/` in

4the composer to open the slash popup, choose a command, and Codex will perform

5actions such as switching models, adjusting permissions, or summarizing long

6conversations without leaving the terminal.

4 7 

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

6 9 

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

8- Steer an active session with commands like `/model`, `/personality`, `/permissions`, `/experimental`, `/agent`, and `/status`11- Steer an active session with commands like `/model`, `/personality`,

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

9 13 

10## Built-in slash commands14## Built-in slash commands

11 15 

12Codex ships with the following commands. Open the slash popup and start typing the command name to filter the list.16Codex ships with the following commands. Open the slash popup and start typing

17the command name to filter the list.

13 18 

14| Command | Purpose | When to use it |19| Command | Purpose | When to use it |

15| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |20| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

17| [`/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. |

18| [`/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 sub-agent thread. |

19| [`/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. |

20| [`/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. |

21| [`/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. |

22| [`/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. |

23| [`/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 sub-agents from the CLI. |

39| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |46| [`/debug-config`](#inspect-config-layers-with-debug-config) | Print config layer and requirements diagnostics. | Debug precedence and policy requirements, including experimental network constraints. |

40| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |47| [`/statusline`](#configure-footer-items-with-statusline) | Configure TUI status-line fields interactively. | Pick and reorder footer items (model/context/limits/git/tokens/session) and persist in config.toml. |

41 48 

42`/quit` and `/exit` both exit the CLI. Use them only after you have saved or committed any important work.49`/quit` and `/exit` both exit the CLI. Use them only after you have saved or

50committed any important work.

43 51 

44The `/approvals` command still works as an alias, but it no longer appears in the slash popup list.52The `/approvals` command still works as an alias, but it no longer appears in the slash popup list.

45 53 

621. In an active conversation, type `/personality` and press Enter.701. In an active conversation, type `/personality` and press Enter.

632. Choose a style from the popup.712. Choose a style from the popup.

64 72 

65Expected: Codex confirms the new style in the transcript and uses it for later responses in the thread.73Expected: Codex confirms the new style in the transcript and uses it for later

74responses in the thread.

66 75 

67Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none` to disable personality instructions.76Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`

77to disable personality instructions.

68 78 

69If the active model doesn't support personality-specific instructions, Codex hides this command.79If the active model doesn't support personality-specific instructions, Codex hides this command.

70 80 

71### Switch to plan mode with `/plan`81### Switch to plan mode with `/plan`

72 82 

731. Type `/plan` and press Enter to switch the active conversation into plan mode.831. Type `/plan` and press Enter to switch the active conversation into plan

84 mode.

742. Optional: provide inline prompt text (for example, `/plan Propose a migration plan for this service`).852. Optional: provide inline prompt text (for example, `/plan Propose a migration plan for this service`).

753. You can paste content or attach images while using inline `/plan` arguments.863. You can paste content or attach images while using inline `/plan` arguments.

76 87 

85 96 

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

87 98 

99### Clear the terminal and start a new chat with `/clear`

100 

1011. Type `/clear` and press Enter.

102 

103Expected: Codex clears the terminal, resets the visible transcript, and starts

104a fresh chat in the same CLI session.

105 

106Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new conversation.

107 

108<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current

109chat. Codex disables both actions while a task is in progress.

110 

88### Update permissions with `/permissions`111### Update permissions with `/permissions`

89 112 

901. Type `/permissions` and press Enter.1131. Type `/permissions` and press Enter.

912. Select the approval preset that matches your comfort level, for example `Auto` for hands-off runs or `Read Only` to review edits.1142. Select the approval preset that matches your comfort level, for example

115 `Auto` for hands-off runs or `Read Only` to review edits.

92 116 

93Expected: Codex announces the updated policy. Future actions respect the new approval mode until you change it again.117Expected: Codex announces the updated policy. Future actions respect the

118updated approval mode until you change it again.

119 

120### Copy the latest response with `/copy`

121 

1221. Type `/copy` and press Enter.

123 

124Expected: Codex copies the latest completed Codex output to your clipboard.

125 

126If a turn is still running, `/copy` uses the latest completed output instead of

127the in-progress response. The command is unavailable before the first completed

128Codex output and immediately after a rollback.

94 129 

95### Grant sandbox read access with `/sandbox-add-read-dir`130### Grant sandbox read access with `/sandbox-add-read-dir`

96 131 

991. Type `/sandbox-add-read-dir C:\absolute\directory\path` and press Enter.1341. Type `/sandbox-add-read-dir C:\absolute\directory\path` and press Enter.

1002. Confirm the path is an existing absolute directory.1352. Confirm the path is an existing absolute directory.

101 136 

102Expected: Codex refreshes the Windows sandbox policy and grants read access to that directory for later commands that run in the sandbox.137Expected: Codex refreshes the Windows sandbox policy and grants read access to

138that directory for later commands that run in the sandbox.

103 139 

104### Inspect the session with `/status`140### Inspect the session with `/status`

105 141 

1061. In any conversation, type `/status`.1421. In any conversation, type `/status`.

1072. Review the output for the active model, approval policy, writable roots, and current token usage.1432. Review the output for the active model, approval policy, writable roots, and current token usage.

108 144 

109Expected: You see a summary like what `codex status` prints in the shell, confirming Codex is operating where you expect.145Expected: You see a summary like what `codex status` prints in the shell,

146confirming Codex is operating where you expect.

110 147 

111### Inspect config layers with `/debug-config`148### Inspect config layers with `/debug-config`

112 149 

1131. Type `/debug-config`.1501. Type `/debug-config`.

1142. Review the output for config layer order (lowest precedence first), on/off state, and policy sources.1512. Review the output for config layer order (lowest precedence first), on/off

152 state, and policy sources.

115 153 

116Expected: Codex prints layer diagnostics plus policy details such as `allowed_approval_policies`, `allowed_sandbox_modes`, `mcp_servers`, `rules`, `enforce_residency`, and `experimental_network` when configured.154Expected: Codex prints layer diagnostics plus policy details such as

155`allowed_approval_policies`, `allowed_sandbox_modes`, `mcp_servers`, `rules`,

156`enforce_residency`, and `experimental_network` when configured.

117 157 

118Use this output to debug why an effective setting differs from `config.toml`.158Use this output to debug why an effective setting differs from `config.toml`.

119 159 

1221. Type `/statusline`.1621. Type `/statusline`.

1232. Use the picker to toggle and reorder items, then confirm.1632. Use the picker to toggle and reorder items, then confirm.

124 164 

125Expected: The footer status line updates immediately and persists to `tui.status_line` in `config.toml`.165Expected: The footer status line updates immediately and persists to

166`tui.status_line` in `config.toml`.

126 167 

127Available status-line items include model, model+reasoning, context stats, rate limits, git branch, token counters, session id, current directory/project root, and Codex version.168Available status-line items include model, model+reasoning, context stats, rate

169limits, git branch, token counters, session id, current directory/project root,

170and Codex version.

128 171 

129### Check background terminals with `/ps`172### Check background terminals with `/ps`

130 173 

1311. Type `/ps`.1741. Type `/ps`.

1322. Review the list of background terminals and their status.1752. Review the list of background terminals and their status.

133 176 

134Expected: Codex shows each background terminal’s command plus up to three recent, non-empty output lines so you can gauge progress at a glance.177Expected: Codex shows each background terminal's command plus up to three

178recent, non-empty output lines so you can gauge progress at a glance.

135 179 

136Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.180Background terminals appear when `unified_exec` is in use; otherwise, the list may be empty.

137 181 

1401. After a long exchange, type `/compact`.1841. After a long exchange, type `/compact`.

1412. Confirm when Codex offers to summarize the conversation so far.1852. Confirm when Codex offers to summarize the conversation so far.

142 186 

143Expected: Codex replaces earlier turns with a concise summary, freeing context while keeping critical details.187Expected: Codex replaces earlier turns with a concise summary, freeing context

188while keeping critical details.

144 189 

145### Review changes with `/diff`190### Review changes with `/diff`

146 191 

1471. Type `/diff` to inspect the Git diff.1921. Type `/diff` to inspect the Git diff.

1482. Scroll through the output inside the CLI to review edits and added files.1932. Scroll through the output inside the CLI to review edits and added files.

149 194 

150Expected: Codex shows changes you’ve staged, changes you haven’t staged yet, and files Git hasn’t started tracking, so you can decide what to keep.195Expected: Codex shows changes you've staged, changes you haven't staged yet,

196and files Git hasn't started tracking, so you can decide what to keep.

151 197 

152### Highlight files with `/mention`198### Highlight files with `/mention`

153 199 

160 206 

1611. Type `/new` and press Enter.2071. Type `/new` and press Enter.

162 208 

163Expected: Codex starts a fresh conversation in the same CLI session, so you can switch tasks without leaving your terminal.209Expected: Codex starts a fresh conversation in the same CLI session, so you

210can switch tasks without leaving your terminal.

211 

212Unlike `/clear`, `/new` does not clear the current terminal view first.

164 213 

165### Resume a saved conversation with `/resume`214### Resume a saved conversation with `/resume`

166 215 

1671. Type `/resume` and press Enter.2161. Type `/resume` and press Enter.

1682. Choose the session you want from the saved-session picker.2172. Choose the session you want from the saved-session picker.

169 218 

170Expected: Codex reloads the selected conversation’s transcript so you can pick up where you left off, keeping the original history intact.219Expected: Codex reloads the selected conversation's transcript so you can pick

220up where you left off, keeping the original history intact.

171 221 

172### Fork the current conversation with `/fork`222### Fork the current conversation with `/fork`

173 223 

1741. Type `/fork` and press Enter.2241. Type `/fork` and press Enter.

175 225 

176Expected: Codex clones the current conversation into a new thread with a fresh ID, leaving the original transcript untouched so you can explore an alternative approach in parallel.226Expected: Codex clones the current conversation into a new thread with a fresh

227ID, leaving the original transcript untouched so you can explore an alternative

228approach in parallel.

177 229 

178If you need to fork a saved session instead of the current one, run `codex fork` in your terminal to open the session picker.230If you need to fork a saved session instead of the current one, run

231`codex fork` in your terminal to open the session picker.

179 232 

180### Generate `AGENTS.md` with `/init`233### Generate `AGENTS.md` with `/init`

181 234 

1821. Run `/init` in the directory where you want Codex to look for persistent instructions.2351. Run `/init` in the directory where you want Codex to look for persistent instructions.

1832. Review the generated `AGENTS.md`, then edit it to match your repository conventions.2362. Review the generated `AGENTS.md`, then edit it to match your repository conventions.

184 237 

185Expected: Codex creates an `AGENTS.md` scaffold you can refine and commit for future sessions.238Expected: Codex creates an `AGENTS.md` scaffold you can refine and commit for

239future sessions.

186 240 

187### Ask for a working tree review with `/review`241### Ask for a working tree review with `/review`

188 242 

1891. Type `/review`.2431. Type `/review`.

1902. Follow up with `/diff` if you want to inspect the exact file changes.2442. Follow up with `/diff` if you want to inspect the exact file changes.

191 245 

192Expected: Codex summarizes issues it finds in your working tree, focusing on behavior changes and missing tests. It uses the current session model unless you set `review_model` in `config.toml`.246Expected: Codex summarizes issues it finds in your working tree, focusing on

247behavior changes and missing tests. It uses the current session model unless

248you set `review_model` in `config.toml`.

193 249 

194### List MCP tools with `/mcp`250### List MCP tools with `/mcp`

195 251 

2031. Type `/apps`.2591. Type `/apps`.

2042. Pick an app from the list.2602. Pick an app from the list.

205 261 

206Expected: Codex inserts the app mention into the composer as `$app-slug`, so you can immediately ask Codex to use it.262Expected: Codex inserts the app mention into the composer as `$app-slug`, so

263you can immediately ask Codex to use it.

207 264 

208### Switch agent threads with `/agent`265### Switch agent threads with `/agent`

209 266 

2101. Type `/agent` and press Enter.2671. Type `/agent` and press Enter.

2112. Select the thread you want from the picker.2682. Select the thread you want from the picker.

212 269 

213Expected: Codex switches the active thread so you can inspect or continue that agent’s work.270Expected: Codex switches the active thread so you can inspect or continue that

271agent's work.

214 272 

215### Send feedback with `/feedback`273### Send feedback with `/feedback`

216 274 

2171. Type `/feedback` and press Enter.2751. Type `/feedback` and press Enter.

2182. Follow the prompts to include logs or diagnostics.2762. Follow the prompts to include logs or diagnostics.

219 277 

220Expected: Codex collects the requested diagnostics and submits them to the maintainers.278Expected: Codex collects the requested diagnostics and submits them to the

279maintainers.

221 280 

222### Sign out with `/logout`281### Sign out with `/logout`

223 282 

69 69 

70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).

71 71 

72#### Windows sandbox mode

73 

74When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you do not have administrator permissions or if elevated setup fails.

75 

76```toml

77[windows]

78sandbox = "elevated" # Recommended

79# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

80```

81 

72#### Web search mode82#### Web search mode

73 83 

74Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:84Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

140| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |150| `apply_patch_freeform` | false | Experimental | Include the freeform `apply_patch` tool |

141| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |151| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

142| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |152| `apps_mcp_gateway` | false | Experimental | Route Apps MCP calls through `https://api.openai.com/v1/connectors/mcp/` instead of legacy routing |

143| `elevated_windows_sandbox` | false | Experimental | Use the elevated Windows sandbox pipeline |

144| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |153| `collaboration_modes` | true | Stable | Enable collaboration modes such as plan mode |

145| `experimental_windows_sandbox` | false | Experimental | Use the Windows restricted-token sandbox |

146| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |154| `multi_agent` | false | Experimental | Enable multi-agent collaboration tools |

147| `personality` | true | Stable | Enable personality selection controls |155| `personality` | true | Stable | Enable personality selection controls |

148| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |156| `remote_models` | false | Experimental | Refresh remote model list before showing readiness |

12| --- | --- | --- |12| --- | --- | --- |

13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |13| `agents.<name>.config_file` | `string (path)` | Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role. |

14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |14| `agents.<name>.description` | `string` | Role guidance shown to Codex when choosing and spawning that agent type. |

15| `agents.job_max_runtime_seconds` | `number` | Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker. |

15| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |16| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

16| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |17| `agents.max_threads` | `number` | Maximum number of agent threads that can be open concurrently. |

17| `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. |18| `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. |

44| `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). |45| `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). |

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

46| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |47| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |

47| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |48| `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). |

48| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |

49| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default). |

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

51| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |50| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |

52| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |51| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |

166| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |165| `skills.config` | `array<object>` | Per-skill enablement overrides stored in config.toml. |

167| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |166| `skills.config.<index>.enabled` | `boolean` | Enable or disable the referenced skill. |

168| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |167| `skills.config.<index>.path` | `string (path)` | Path to a skill folder containing `SKILL.md`. |

168| `sqlite_home` | `string (path)` | Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state. |

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

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

171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |171| `tools.web_search` | `boolean` | Deprecated legacy toggle for web search; prefer the top-level `web_search` setting. |

178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |178| `tui.status_line` | `array<string> | null` | Ordered list of TUI footer status-line item identifiers. `null` disables the status line. |

179| `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. |179| `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. |

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

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

181 182 

182Key183Key

183 184 

205 206 

206Key207Key

207 208 

209`agents.job_max_runtime_seconds`

210 

211Type / Values

212 

213`number`

214 

215Details

216 

217Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.

218 

219Key

220 

208`agents.max_depth`221`agents.max_depth`

209 222 

210Type / Values223Type / Values

589 602 

590Key603Key

591 604 

592`features.elevated_windows_sandbox`

593 

594Type / Values

595 

596`boolean`

597 

598Details

599 

600Enable the elevated Windows sandbox pipeline (experimental).

601 

602Key

603 

604`features.experimental_windows_sandbox`

605 

606Type / Values

607 

608`boolean`

609 

610Details

611 

612Run the Windows restricted-token sandbox (experimental).

613 

614Key

615 

616`features.multi_agent`605`features.multi_agent`

617 606 

618Type / Values607Type / Values

621 610 

622Details611Details

623 612 

624Enable multi-agent collaboration tools (`spawn\_agent`, `send\_input`, `resume\_agent`, `wait`, and `close\_agent`) (experimental; off by default).613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).

625 614 

626Key615Key

627 616 

2053 2042 

2054Key2043Key

2055 2044 

2045`sqlite_home`

2046 

2047Type / Values

2048 

2049`string (path)`

2050 

2051Details

2052 

2053Directory where Codex stores the SQLite-backed state DB used by agent jobs and other resumable runtime state.

2054 

2055Key

2056 

2056`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`

2057 2058 

2058Type / Values2059Type / Values

2195 2196 

2196Track Windows onboarding acknowledgement (Windows only).2197Track Windows onboarding acknowledgement (Windows only).

2197 2198 

2199Key

2200 

2201`windows.sandbox`

2202 

2203Type / Values

2204 

2205`unelevated | elevated`

2206 

2207Details

2208 

2209Windows-only native sandbox mode when running Codex natively on Windows.

2210 

2198Expand to view all2211Expand to view all

2199 2212 

2200You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2213You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override

53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"

55# sqlite_home = "/absolute/path/to/codex-state" # optional SQLite-backed runtime state directory

55 56 

56################################################################################57################################################################################

57# Reasoning & Verbosity (Responses API capable models)58# Reasoning & Verbosity (Responses API capable models)

216# max_threads = 6217# max_threads = 6

217# Maximum nested spawn depth. Root session starts at depth 0. Default: 1218# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

218# max_depth = 1219# max_depth = 1

220# Default timeout per worker for spawn_agents_on_csv jobs. When unset, the tool defaults to 1800 seconds.

221# job_max_runtime_seconds = 1800

219 222 

220# [agents.reviewer]223# [agents.reviewer]

221# description = "Find security, correctness, and test risks in code."224# description = "Find security, correctness, and test risks in code."

227 230 

228# Disable or re-enable a specific skill without deleting it.231# Disable or re-enable a specific skill without deleting it.

229[[skills.config]]232[[skills.config]]

230# path = "/path/to/skill"233# path = "/path/to/skill/SKILL.md"

231# enabled = false234# enabled = false

232 235 

233################################################################################236################################################################################

348# request_rule = true351# request_rule = true

349# collaboration_modes = true352# collaboration_modes = true

350# use_linux_sandbox_bwrap = false353# use_linux_sandbox_bwrap = false

351# experimental_windows_sandbox = false

352# elevated_windows_sandbox = false

353# remote_models = false354# remote_models = false

354# runtime_metrics = false355# runtime_metrics = false

355# powershell_utf8 = true356# powershell_utf8 = true

522# client-certificate = "/etc/codex/certs/client.pem"523# client-certificate = "/etc/codex/certs/client.pem"

523# client-private-key = "/etc/codex/certs/client-key.pem"524# client-private-key = "/etc/codex/certs/client-key.pem"

524```525```

526 

527################################################################################

528 

529# Windows

530 

531################################################################################

532 

533[windows]

534 

535# Native Windows sandbox mode (Windows only): unelevated | elevated

536 

537sandbox = "unelevated"

51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.

52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).

53 53 

54## Process CSV batches with sub-agents

55 

56Use `spawn_agents_on_csv` when you have many similar tasks that can be expressed as one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.

57 

58This works well for repeated audits such as:

59 

60- reviewing one file, package, or service per row

61- checking a list of incidents, PRs, or migration targets

62- generating structured summaries for many similar inputs

63 

64The tool accepts:

65 

66- `csv_path` for the source CSV

67- `instruction` for the worker prompt template, using `{column_name}` placeholders

68- `id_column` when you want stable item ids from a specific column

69- `output_schema` when each worker should return a JSON object with a fixed shape

70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 

72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, that row is marked as failed in the exported CSV.

73 

74Example prompt:

75 

76```

77Create /tmp/components.csv with columns path,owner and one row per frontend component.

78 

79Then call spawn_agents_on_csv with:

80- csv_path: /tmp/components.csv

81- id_column: path

82- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."

83- output_csv_path: /tmp/components-review.csv

84- output_schema: an object with required string fields path, risk, summary, and follow_up

85```

86 

87When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.

88 

89Related runtime settings:

90 

91- `agents.max_threads` caps how many agent threads can stay open concurrently.

92- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.

93- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.

94 

54## Approvals and sandbox controls95## Approvals and sandbox controls

55 96 

56Sub-agents inherit your current sandbox policy, but they run with97Sub-agents inherit your current sandbox policy.

57non-interactive approvals. If a sub-agent attempts an action that would require98 

58a new approval, that action fails and the error is surfaced in the parent99In interactive CLI sessions, approval requests can surface from inactive agent

59workflow.100threads even while you are looking at the main thread. The approval overlay

101shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.

103 

104In non-interactive flows, or whenever a run cannot surface a fresh approval,

105an action that needs new approval fails and the error is surfaced back to the

106parent workflow.

107 

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a

109child. That includes sandbox and approval choices you set interactively during

110the session, such as `/approvals` changes or `--yolo`, even if the selected

111agent role loads a config file with different defaults.

60 112 

61You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.113You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.

62 114 

88| --- | --- | --- | --- |140| --- | --- | --- | --- |

89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |141| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |

90| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |142| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |

143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |144| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |

92| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |

93| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

96 149 

97- Unknown fields in `[agents.<name>]` are rejected.150- Unknown fields in `[agents.<name>]` are rejected.

98- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.151- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

152- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.153- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.

100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.154- `agents.<name>.config_file` is validated at config load time and must point to an existing file.

101- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.155- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

104 158 

105### Example agent roles159### Example agent roles

106 160 

107Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.161The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

108 162 

109Example `~/.codex/config.toml`:163#### Example 1: PR review team

164 

165This pattern splits review into three focused roles:

166 

167- `explorer` maps the codebase and gathers evidence.

168- `reviewer` looks for correctness, security, and test risks.

169- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

170 

171Project config (`.codex/config.toml`):

110 172 

111```173```

112[agents.default]174[agents]

113description = "General-purpose helper."175max_threads = 6

176max_depth = 1

177 

178[agents.explorer]

179description = "Read-only codebase explorer for gathering evidence before changes are proposed."

180config_file = "agents/explorer.toml"

114 181 

115[agents.reviewer]182[agents.reviewer]

116description = "Find security, correctness, and test risks in code."183description = "PR reviewer focused on correctness, security, and missing tests."

117config_file = "agents/reviewer.toml"184config_file = "agents/reviewer.toml"

118 185 

119[agents.explorer]186[agents.docs_researcher]

120description = "Fast codebase explorer for read-heavy tasks."187description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

121config_file = "agents/custom-explorer.toml"188config_file = "agents/docs-researcher.toml"

122```189```

123 190 

124Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):191`agents/explorer.toml`:

192 

193```

194model = "gpt-5.3-codex-spark"

195model_reasoning_effort = "medium"

196sandbox_mode = "read-only"

197developer_instructions = """

198Stay in exploration mode.

199Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

200Prefer fast search and targeted file reads over broad scans.

201"""

202```

203 

204`agents/reviewer.toml`:

125 205 

126```206```

127model = "gpt-5.3-codex"207model = "gpt-5.3-codex"

128model_reasoning_effort = "high"208model_reasoning_effort = "high"

129developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."209sandbox_mode = "read-only"

210developer_instructions = """

211Review code like an owner.

212Prioritize correctness, security, behavior regressions, and missing test coverage.

213Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

214"""

215```

216 

217`agents/docs-researcher.toml`:

218 

219```

220model = "gpt-5.3-codex-spark"

221model_reasoning_effort = "medium"

222sandbox_mode = "read-only"

223developer_instructions = """

224Use the docs MCP server to confirm APIs, options, and version-specific behavior.

225Return concise answers with links or exact references when available.

226Do not make code changes.

227"""

228 

229[mcp_servers.openaiDeveloperDocs]

230url = "https://developers.openai.com/mcp"

231```

232 

233This setup works well for prompts like:

234 

235```

236Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

237```

238 

239#### Example 2: frontend integration debugging team

240 

241This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

242 

243Project config (`.codex/config.toml`):

244 

245```

246[agents]

247max_threads = 6

248max_depth = 1

249 

250[agents.explorer]

251description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

252config_file = "agents/explorer.toml"

253 

254[agents.browser_debugger]

255description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

256config_file = "agents/browser-debugger.toml"

257 

258[agents.worker]

259description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

260config_file = "agents/worker.toml"

130```261```

131 262 

132Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):263`agents/explorer.toml`:

133 264 

134```265```

135model = "gpt-5.3-codex-spark"266model = "gpt-5.3-codex-spark"

136model_reasoning_effort = "medium"267model_reasoning_effort = "medium"

137sandbox_mode = "read-only"268sandbox_mode = "read-only"

269developer_instructions = """

270Map the code that owns the failing UI flow.

271Identify entry points, state transitions, and likely files before the worker starts editing.

272"""

273```

274 

275`agents/browser-debugger.toml`:

276 

277```

278model = "gpt-5.3-codex"

279model_reasoning_effort = "high"

280sandbox_mode = "workspace-write"

281developer_instructions = """

282Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

283Use browser tooling for screenshots, console output, and network evidence.

284Do not edit application code.

285"""

286 

287[mcp_servers.chrome_devtools]

288url = "http://localhost:3000/mcp"

289startup_timeout_sec = 20

290```

291 

292`agents/worker.toml`:

293 

294```

295model = "gpt-5.3-codex"

296model_reasoning_effort = "medium"

297developer_instructions = """

298Own the fix once the issue is reproduced.

299Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

300"""

301 

302[[skills.config]]

303path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

304enabled = false

305```

306 

307This setup works well for prompts like:

308 

309```

310Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.

138```311```

138 138 

139- **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.139- **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.

140- **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.140- **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.

141- **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, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.141- **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.

142 142 

143If 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:143If 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:

144 144 

150 150 

151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).

152 152 

153The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.153When running natively on Windows, configure the native sandbox mode in `config.toml`:

154 

155```

156[windows]

157sandbox = "unelevated" # or "elevated"

158```

159 

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

154 161 

155When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.162When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.

156 163 

2 2 

3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 4 

5When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).5When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).

6 6 

7Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.7If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.

8 

9## Windows sandbox

10 

11Native Windows sandbox support includes two modes that you can configure in `config.toml`:

12 

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

17 

18How `elevated` mode works:

19 

20- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

21- Runs commands as a dedicated Windows Sandbox User.

22- Limits network access by installing Windows Firewall rules.

23 

24### Grant sandbox read access

25 

26When a command fails because the Windows sandbox can't read a directory, use:

27 

28```text

29/sandbox-add-read-dir C:\absolute\directory\path

30```

31 

32The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

8 33 

9## Windows Subsystem for Linux34## Windows Subsystem for Linux

10 35 

81 ```106 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.107- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 108 

84## Windows experimental sandbox109## Troubleshooting and FAQ

85 

86The Windows sandbox support is experimental. How it works:

87 

88- Launches commands inside a restricted token derived from an AppContainer profile.

89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.

90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.

91 

92Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.

93 

94### Grant sandbox read access

95 

96When a command fails because the Windows sandbox can't read a directory, use:

97 

98```text

99/sandbox-add-read-dir C:\absolute\directory\path

100```

101 

102The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

103 

104### Troubleshooting and FAQ

105 110 

106#### Installed extension, but it’s unresponsive111#### Installed extension, but it’s unresponsive

107 112