OpenAI - Codex Docs Changes

app-server.md +270 −19

Details

116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.

117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.

118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.

119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `thread/archived`, `thread/unarchived`, `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.

120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.

121 121

122## Initialization122## Initialization

201- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.201- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.

202- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.202- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.

204- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history.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`.

205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters.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.207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

208- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread`.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`.

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

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

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

210- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.212- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

211- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."213- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

223- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.225- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.

224- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.226- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

225- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).227- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).

226- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id).228- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

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

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

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

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

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

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

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

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

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

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

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

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

314 "approvalPolicy": "never",320 "approvalPolicy": "never",

315 "sandbox": "workspaceWrite",321 "sandbox": "workspaceWrite",

316 "personality": "friendly"322 "personality": "friendly",

323 "serviceName": "my_app_server_client"

317} }324} }

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

319 "thread": {326 "thread": {

320 "id": "thr_123",327 "id": "thr_123",

321 "preview": "",328 "preview": "",

329 "ephemeral": false,

322 "modelProvider": "openai",330 "modelProvider": "openai",

323 "createdAt": 1730910000331 "createdAt": 1730910000

324 }332 }

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

327```335```

328 336

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

338

329To 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`:

330 340

331```json341```json

333 "threadId": "thr_123",343 "threadId": "thr_123",

334 "personality": "friendly"344 "personality": "friendly"

335} }345} }

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

337```347```

338 348

339Resuming 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.

352{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }362{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

353```363```

354 364

365When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.

366

355### Read a stored thread (without resuming)367### Read a stored thread (without resuming)

356 368

357Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.369Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.

358 370

359- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.371- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.

372- Returned `thread` objects include runtime `status` (`notLoaded`, `idle`, `systemError`, or `active` with `activeFlags`).

360 373

361```json374```json

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

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

364```377```

365 378

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

400} }413} }

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

402 "data": [415 "data": [

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

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

405 ],418 ],

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

407} }420} }

409 422

410When `nextCursor` is `null`, you have reached the final page.423When `nextCursor` is `null`, you have reached the final page.

411 424

425### Track thread status changes

426

427`thread/status/changed` is emitted whenever a loaded thread's runtime status changes. The payload includes `threadId` and the new `status`.

428

429```json

430{

431 "method": "thread/status/changed",

432 "params": {

433 "threadId": "thr_123",

434 "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }

435 }

436}

437```

438

412### List loaded threads439### List loaded threads

413 440

414`thread/loaded/list` returns thread IDs currently loaded in memory.441`thread/loaded/list` returns thread IDs currently loaded in memory.

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

419```446```

420 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

421### Archive a thread468### Archive a thread

422 469

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

425```json472```json

426{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }473{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }

427{ "id": 22, "result": {} }474{ "id": 22, "result": {} }

475{ "method": "thread/archived", "params": { "threadId": "thr_b" } }

428```476```

429 477

430Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.478Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.

435 483

436```json484```json

437{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }485{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }

438{ "id": 24, "result": { "thread": { "id": "thr_b" } } }486{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }

487{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

439```488```

440 489

441### Trigger thread compaction490### Trigger thread compaction

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

450```499```

451 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

452## Turns510## Turns

453 511

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

478}536}

479```537```

480 538

539On macOS, `includePlatformDefaults: true` appends a curated platform-default Seatbelt policy for restricted-read sessions. This improves tool compatibility without broadly allowing all of `/System`.

540

481Examples:541Examples:

482 542

483```json543```json

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

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

656 716

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

718

719Use `configRequirements/read` to inspect the effective admin requirements loaded from `requirements.toml` and/or MDM.

720

721```json

722{ "method": "configRequirements/read", "id": 52, "params": {} }

723{ "id": 52, "result": {

724 "requirements": {

725 "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],

726 "allowedSandboxModes": ["readOnly", "workspaceWrite"],

727 "network": {

728 "enabled": true,

729 "allowedDomains": ["api.openai.com"],

730 "allowUnixSockets": ["/tmp/example.sock"],

731 "dangerouslyAllowAllUnixSockets": false

732 }

733 }

734} }

735```

736

737`result.requirements` is `null` when no requirements are configured. When present, the optional `network` object carries managed proxy constraints (domain rules, proxy settings, and unix-socket policy).

738

739### Windows sandbox setup (`windowsSandbox/setupStart`)

740

741Custom Windows clients can trigger sandbox setup asynchronously instead of blocking on startup checks.

742

743```json

744{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }

745{ "id": 53, "result": { "started": true } }

746```

747

748App-server starts setup in the background and later emits a completion notification:

749

750```json

751{

752 "method": "windowsSandbox/setupCompleted",

753 "params": { "mode": "elevated", "success": true, "error": null }

754}

755```

756

757Modes:

758

759- `elevated` - run the elevated Windows sandbox setup path.

760- `unelevated` - run the legacy setup/preflight path.

761

657## Events762## Events

658 763

659Event 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`, `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.

660 765

661### Notification opt-out766### Notification opt-out

662 767

674- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.779- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.

675- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.780- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.

676 781

782### Windows sandbox setup events

783

784- `windowsSandbox/setupCompleted` - `{ mode, success, error }` emitted after a `windowsSandbox/setupStart` request finishes.

785

677### Turn events786### Turn events

678 787

679- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.788- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.

689`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:798`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:

690 799

691- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).800- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).

692- `agentMessage` - `{id, text}` containing the accumulated agent reply.801- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).

693- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.802- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.

694- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.803- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.

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

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

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

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

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

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

751Order of messages:861Order of messages:

752 862

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

7542. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, and optional `proposedExecpolicyAmendment`.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.

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

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

868

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.

870

871Codex deduplicates concurrent network approval prompts by destination (`host`, protocol, and port). The app-server may therefore send one prompt that unblocks multiple queued requests to the same destination, while different ports on the same host are treated separately.

757 872

758### File change approvals873### File change approvals

759 874

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

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

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

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

766 897

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

768 899

769App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.900App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. Destructive tool annotations always trigger approval even when the tool also advertises less-privileged hints. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.

770 901

771## Skills902## Skills

772 903

863 994

864## Apps (connectors)995## Apps (connectors)

865 996

866Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state.997Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state. App entries can also include optional `branding`, `appMetadata`, and `labels` fields.

867 998

868```json999```json

869{ "method": "app/list", "id": 50, "params": {1000{ "method": "app/list", "id": 50, "params": {

879 "name": "Demo App",1010 "name": "Demo App",

880 "description": "Example connector for documentation.",1011 "description": "Example connector for documentation.",

881 "logoUrl": "https://example.com/demo-app.png",1012 "logoUrl": "https://example.com/demo-app.png",

1013 "logoUrlDark": null,

1014 "distributionChannel": null,

1015 "branding": null,

1016 "appMetadata": null,

1017 "labels": null,

882 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",1018 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

883 "isAccessible": true,1019 "isAccessible": true,

884 "isEnabled": true1020 "isEnabled": true

904 "name": "Demo App",1040 "name": "Demo App",

905 "description": "Example connector for documentation.",1041 "description": "Example connector for documentation.",

906 "logoUrl": "https://example.com/demo-app.png",1042 "logoUrl": "https://example.com/demo-app.png",

1043 "logoUrlDark": null,

1044 "distributionChannel": null,

1045 "branding": null,

1046 "appMetadata": null,

1047 "labels": null,

907 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",1048 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

908 "isAccessible": true,1049 "isAccessible": true,

909 "isEnabled": true1050 "isEnabled": true

936}1077}

937```1078```

938 1079

1080### Config RPC examples for app settings

1081

1082Use `config/read`, `config/value/write`, and `config/batchWrite` to inspect or update app controls in `config.toml`.

1083

1084Read the effective app config shape (including `_default` and per-tool overrides):

1085

1086```json

1087{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }

1088{ "id": 60, "result": {

1089 "config": {

1090 "apps": {

1091 "_default": {

1092 "enabled": true,

1093 "destructive_enabled": true,

1094 "open_world_enabled": true

1095 },

1096 "google_drive": {

1097 "enabled": true,

1098 "destructive_enabled": false,

1099 "default_tools_approval_mode": "prompt",

1100 "tools": {

1101 "files/delete": { "enabled": false, "approval_mode": "approve" }

1102 }

1103 }

1104 }

1105 }

1106} }

1107```

1108

1109Update a single app setting:

1110

1111```json

1112{

1113 "method": "config/value/write",

1114 "id": 61,

1115 "params": {

1116 "keyPath": "apps.google_drive.default_tools_approval_mode",

1117 "value": "prompt",

1118 "mergeStrategy": "replace"

1119 }

1120}

1121```

1122

1123Apply multiple app edits atomically:

1124

1125```json

1126{

1127 "method": "config/batchWrite",

1128 "id": 62,

1129 "params": {

1130 "edits": [

1131 {

1132 "keyPath": "apps._default.destructive_enabled",

1133 "value": false,

1134 "mergeStrategy": "upsert"

1135 },

1136 {

1137 "keyPath": "apps.google_drive.tools.files/delete.approval_mode",

1138 "value": "approve",

1139 "mergeStrategy": "upsert"

1140 }

1141 ]

1142 }

1143}

1144```

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

939## Auth endpoints1190## Auth endpoints

940 1191

941The 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.

app/automations.md +1 −1

Details

62 62

63If you are in a managed environment, admins can restrict these behaviors using63If you are in a managed environment, admins can restrict these behaviors using

64admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See64admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See

~~65[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~65[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

66 66

67Automations use `approval_policy = "never"` when your organization policy67Automations use `approval_policy = "never"` when your organization policy

68allows it. If `approval_policy = "never"` is disallowed by admin requirements,68allows it. If `approval_policy = "never"` is disallowed by admin requirements,

app/windows.md +69 −0 added

Details

1# Codex app

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

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

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

9## Getting started

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

131. Download and install the Codex app

15 The Codex app is currently only available for macOS.

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

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

202. Open Codex and sign in

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

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

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

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

314. Send your first message

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

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

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.

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

43---

45## Work with the Codex app

47[### Multitask across projects

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

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

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

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

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

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

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

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

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

67---

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

app/worktrees.md +45 −43

Details

1# Worktrees1# Worktrees

2 2

3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don’t conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually.3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually, and use Handoff to move a thread between Local and Worktree.

4 4

5## What's a worktree5## What's a worktree

6 6

10 10

11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.

12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.

13- **Handoff**: The flow that moves a thread between Local and Worktree. Codex handles the Git operations required to move your work safely between them.

13 14

14## Why use a worktree15## Why use a worktree

15 16

~~161. Work in parallel with Codex without breaking each other as you work.~~171. Work in parallel with Codex without disturbing your current Local setup.

~~172. Start a thread unrelated to your current work~~182. Queue up background work while you stay focused on the foreground.

~~18 - Staging area to queue up work you want Codex to start but aren’t ready to test yet.~~193. Move a thread into Local later when you're ready to inspect, test, or collaborate more directly.

19 20

20## Getting started21## Getting started

21 22

313. Submit your prompt323. Submit your prompt

32 33

33 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a ["detached HEAD"](https://git-scm.com/docs/git-checkout#_detached_head).34 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a ["detached HEAD"](https://git-scm.com/docs/git-checkout#_detached_head).

~~344. Verify your changes~~354. Choose where to keep working

35 36

~~36 When you’re ready, follow one of the paths [below](#verifying-and-pushing-workflow-changes)~~37 When you’re ready, you can either keep working directly on the worktree or hand the thread off to your local checkout. Handing off to or from local will move your thread *and* code so you can continue in the other checkout.

~~37 based on your project and flow.~~

38 38

~~39## Verifying and pushing workflow changes~~39## Working between Local and Worktree

40 40

41Worktrees look and feel much like your local checkout. But **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can’t** check it out in your local checkout at the same time, and vice versa.41Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a thread between them.

42 42

~~43Because of this, choose how you want to verify and commit changes Codex made on a worktree:~~43Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.

45In practice, there are two common paths:

44 46

451. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).471. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).

462. [Work in your local checkout](#option-2-working-in-your-local-checkout). Use this when you need to bring changes back into your main checkout, for example because you can run only one instance of your app.482. [Hand the thread off to Local](#option-2-handing-a-thread-off-to-local). Use this when you want to bring the thread into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.

47 49

48### Option 1: Working on the worktree50### Option 1: Working on the worktree

49 51

57 59

58Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.60Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.

59 61

~~60If you plan to keep working on this branch, you can [add it to the sidebar](#adding-a-worktree-to-the-sidebar). Otherwise, archive the thread after you’re done so the worktree can be deleted.~~62### Option 2: Handing a thread off to Local

~~62### Option 2: Working in your local checkout~~

63 63

~~64If you don’t want to verify your changes directly on the worktree and instead check them out on your local checkout, click **Sync with local** in the header of your thread.~~64If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.

65 65

~~66You will be presented with the option of creating a new branch or syncing to an existing branch.~~66This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.

67 67

~~68You can sync with local at any point. To do so, click **Sync with local** in the header again. From here, you can choose which direction to sync (to local or from local) and a sync method:~~68Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

69 69

~~70- **Overwrite**: Makes the destination checkout match the source checkout’s files and commit history.~~70Each thread keeps the same associated worktree over time. If you hand the thread back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.

71- **Apply**: Calculates the source changes since the nearest shared commit and applies that patch onto the destination checkout, preserving destination commit history while bringing over source code changes (not source commits).

72 71

~~73![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-light.webp)~~72![Handoff dialog moving a thread from a worktree to Local](/images/codex/app/handoff-light.webp)

74 73

~~75You can create multiple worktrees and sync them to the same feature branch to split up your work into parallel threads.~~74You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the thread to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.

76 75

77In some cases, changes on your worktree might conflict with changes on your local checkout, for example from testing a previous worktree. In those cases, you can use the **Overwrite local** option to reset the previous changes and cleanly apply your worktree changes.76Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the thread.

78 77

~~79Since this process uses Git operations, any files that are part of the `.gitignore` file won’t be transferred during the sync process.~~78## Advanced details

80 79

~~81## Adding a worktree to the sidebar~~80### Codex-managed and permanent worktrees

82 81

83If you choose option one above (work on the worktree), once you have created a branch on the worktree, an option appears in the header to add the worktree to your sidebar. This promotes the worktree to a permanent home. When you do this, it will never be automatically deleted, and you can even kick off new threads from the same worktree.82By default, threads use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one thread, and Codex returns that thread to the same worktree if you hand it back there later.

84 83

~~85## Advanced details~~84If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees are not automatically deleted, and you can start multiple threads from the same worktree.

86 85

87### How Codex manages worktrees for you86### How Codex manages worktrees for you

88 87

89Codex will create a worktree in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will *not* be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This means you can create several worktrees without polluting your branches.88Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will *not* be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.

90 89

91### Branch limitations90### Branch limitations

92 91

98 97

99To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.98To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.

100 99

101If you plan on checking out the branch locally, try Workflow 2 ([sync with local](#option-2-working-in-your-local-checkout)).100If you plan on checking out the branch locally, use Handoff to move the thread into Local instead of trying to keep the same branch checked out in both places at once.

102 101

103Why this limitation exists102Why this limitation exists

104 103

112 111

113Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.112Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.

114 113

115Worktrees will never be cleaned up if:114By default, Codex keeps your most recent 15 Codex-managed worktrees. You can change this limit or turn off automatic deletion in settings if you prefer to manage disk usage yourself.

116 115

117- A pinned conversation is tied to it116Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:

118- The worktree was added to the sidebar (see above)

119 117

120Worktrees are eligible for cleanup when:118- A pinned conversation is tied to it

119- The thread is still in progress

120- The worktree is a permanent worktree

121 121

122- It’s more than 4 days old122Codex-managed worktrees are deleted automatically when:

123- You have more than 10 worktrees

124 123

125When either of those conditions are met, Codex automatically cleans up a worktree when you archive a thread, or on app startup if it finds a worktree with no associated threads.124- You archive the associated thread

125- Codex needs to delete older worktrees to stay within your configured limit

126 126

127Before cleaning up a worktree, Codex will save a snapshot of the work on it that you can restore at any point in a new worktree. If you open a conversation after its worktree was cleaned up, you’ll see the option to restore it.127Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you'll see the option to restore it.

128 128

129## Frequently asked questions129## Frequently asked questions

130 130

133 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can133 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can

134 manage them consistently.134 manage them consistently.

135 135

136Can I move a session between worktrees?136Can I move a thread between Local and Worktree?

137 137

138Not yet. If you need to change environments, you have to start a new thread in138 Yes. Use **Hand off** in the thread header to move a thread between your local

139the target environment and restate the prompt. You can use the up arrow keys139 checkout and a worktree. Codex handles the Git operations needed to move the

140in the composer to try to recover your prompt.140 thread safely between environments. If you hand a thread back to a worktree

141 later, Codex returns it to the same associated worktree.

141 142

142What happens to threads if a worktree is deleted?143What happens to threads if a worktree is deleted?

143 144

144 Threads can remain in your history even if the underlying worktree directory145 Threads can remain in your history even if the underlying worktree directory

145is cleaned up. However, Codex saves a snapshot of the worktree prior to146 is deleted. For Codex-managed worktrees, Codex saves a snapshot before

146cleaning it up and offers to restore it if you reopen the thread associated147 deleting the worktree and offers to restore it if you reopen the associated

147with it.148 thread. Permanent worktrees are not automatically deleted when you archive

149 their threads.

auth.md +11 −0

Details

9 9

10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.

11 11

12Your sign-in method also determines which admin controls and data-handling policies apply.

14- With sign in with ChatGPT, Codex usage follows your ChatGPT workspace permissions, RBAC, and ChatGPT Enterprise retention and residency settings

15- With an API key, usage follows your API organization's retention and data-sharing settings instead

17For the CLI, Sign in with ChatGPT is the default authentication path when no valid session is available.

12### Sign in with ChatGPT19### Sign in with ChatGPT

13 20

14When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.21When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.

19 26

20OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).

21 28

29Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Do not expose Codex execution in untrusted or publicly triggerable environments.

22## Secure your Codex cloud account31## Secure your Codex cloud account

23 32

24Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).33Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).

43 52

44Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.53Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.

45 54

55For sign in with ChatGPT sessions, Codex refreshes tokens automatically during use before they expire, so active sessions usually continue without requiring another browser login.

46## Credential storage57## Credential storage

47 58

48Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:59Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:

cli/features.md +9 −0

Details

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.

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.

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

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

25 28

83 86

84Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.87Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.

85 88

89## Syntax highlighting and themes

91The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.

93Use `/theme` to open the theme picker, preview themes live, and save your selection to `tui.theme` in `~/.codex/config.toml`. You can also add custom `.tmTheme` files under `$CODEX_HOME/themes` and select them in the picker.

86## Running local code review95## Running local code review

87 96

88Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.97Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.

cli/slash-commands.md +86 −27

Details

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

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

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

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

config-advanced.md +8 −1

Details

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5-codex"

19approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

20 21

21[profiles.deep-review]22[profiles.deep-review]

22model = "gpt-5-pro"23model = "gpt-5-pro"

23model_reasoning_effort = "high"24model_reasoning_effort = "high"

24approval_policy = "never"25approval_policy = "never"

26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

25 27

26[profiles.lightweight]28[profiles.lightweight]

27model = "gpt-4.1"29model = "gpt-4.1"

30 32

31To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.33To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.

32 34

35Profiles can also override `model_catalog_json`. When both the top level and the selected profile set `model_catalog_json`, Codex prefers the profile value.

33## One-off overrides from the CLI37## One-off overrides from the CLI

34 38

35In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:39In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:

188 192

189For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [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).193For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [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).

190 194

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories (sandbox approvals, execpolicy rule prompts, or MCP elicitations) while keeping other prompts interactive.

196

191```197```

192approval_policy = "untrusted" # Other options: on-request, never198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }

193sandbox_mode = "workspace-write"199sandbox_mode = "workspace-write"

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

194 201

195[sandbox_workspace_write]202[sandbox_workspace_write]

196exclude_tmpdir_env_var = false # Allow $TMPDIR203exclude_tmpdir_env_var = false # Allow $TMPDIR

config-basic.md +11 −3

Details

35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or

36 `sandbox_mode = "danger-full-access"`). See [Managed36 `sandbox_mode = "danger-full-access"`). See [Managed

37configuration](https://developers.openai.com/codex/security#managed-configuration) and [Admin-enforced37configuration](https://developers.openai.com/codex/security#managed-configuration) and [Admin-enforced

~~38requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~38 requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

39 39

40## Common configuration options40## Common configuration options

41 41

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

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.

76```toml

77[windows]

78sandbox = "elevated" # Recommended

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

80```

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

config-reference.md +272 −38

Details

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

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

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

16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |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. |

~~17| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |~~19| `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. |

20| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

21| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

22| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

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

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

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

27| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

28| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

30| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

32| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

33| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

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

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

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

73| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

93| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

144| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

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

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

164 182

165Key183Key

166 184

188 206

189Key207Key

190 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

221`agents.max_depth`

222

223Type / Values

224

225`number`

226

227Details

228

229Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

230

231Key

232

191`agents.max_threads`233`agents.max_threads`

192 234

193Type / Values235Type / Values

200 242

201Key243Key

202 244

245`allow_login_shell`

246

247Type / Values

248

249`boolean`

250

251Details

252

253Allow 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.

254

255Key

256

203`approval_policy`257`approval_policy`

204 258

205Type / Values259Type / Values

206 260

207`untrusted | on-request | never`261`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

262

263Details

264

265Controls 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.

266

267Key

268

269`approval_policy.reject.mcp_elicitations`

270

271Type / Values

272

273`boolean`

274

275Details

276

277When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

278

279Key

280

281`approval_policy.reject.rules`

282

283Type / Values

284

285`boolean`

286

287Details

288

289When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

290

291Key

292

293`approval_policy.reject.sandbox_approval`

294

295Type / Values

296

297`boolean`

298

299Details

300

301When `true`, sandbox escalation approval prompts are auto-rejected.

302

303Key

304

305`apps._default.destructive_enabled`

306

307Type / Values

308

309`boolean`

310

311Details

312

313Default allow/deny for app tools with `destructive_hint = true`.

314

315Key

316

317`apps._default.enabled`

318

319Type / Values

320

321`boolean`

322

323Details

324

325Default app enabled state for all apps unless overridden per app.

326

327Key

328

329`apps._default.open_world_enabled`

330

331Type / Values

332

333`boolean`

334

335Details

336

337Default allow/deny for app tools with `open_world_hint = true`.

338

339Key

340

341`apps.<id>.default_tools_approval_mode`

342

343Type / Values

344

345`auto | prompt | approve`

346

347Details

348

349Default approval behavior for tools in this app unless a per-tool override exists.

350

351Key

352

353`apps.<id>.default_tools_enabled`

354

355Type / Values

356

357`boolean`

208 358

209Details359Details

210 360

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.361Default enabled state for tools in this app unless a per-tool override exists.

212 362

213Key363Key

214 364

215`apps.<id>.disabled_reason`365`apps.<id>.destructive_enabled`

216 366

217Type / Values367Type / Values

218 368

219`unknown | user`369`boolean`

220 370

221Details371Details

222 372

223Optional reason attached when an app/connector is disabled.373Allow or block tools in this app that advertise `destructive_hint = true`.

224 374

225Key375Key

226 376

236 386

237Key387Key

238 388

389`apps.<id>.open_world_enabled`

390

391Type / Values

392

393`boolean`

394

395Details

396

397Allow or block tools in this app that advertise `open_world_hint = true`.

398

399Key

400

401`apps.<id>.tools.<tool>.approval_mode`

402

403Type / Values

404

405`auto | prompt | approve`

406

407Details

408

409Per-tool approval behavior override for a single app tool.

410

411Key

412

413`apps.<id>.tools.<tool>.enabled`

414

415Type / Values

416

417`boolean`

418

419Details

420

421Per-tool enabled override for an app tool (for example `repos/list`).

422

423Key

424

425`background_terminal_max_timeout`

426

427Type / Values

428

429`number`

430

431Details

432

433Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

434

435Key

436

239`chatgpt_base_url`437`chatgpt_base_url`

240 438

241Type / Values439Type / Values

404 602

405Key603Key

406 604

407`features.elevated_windows_sandbox`

~~408~~

409Type / Values

~~410~~

411`boolean`

~~412~~

413Details

~~414~~

415Enable the elevated Windows sandbox pipeline (experimental).

~~416~~

417Key

~~418~~

419`features.experimental_windows_sandbox`

~~420~~

421Type / Values

~~422~~

423`boolean`

~~424~~

425Details

~~426~~

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

~~428~~

429Key

~~430~~

431`features.multi_agent`605`features.multi_agent`

432 606

433Type / Values607Type / Values

436 610

437Details611Details

438 612

439Enable 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).

440 614

441Key615Key

442 616

728 902

729Key903Key

730 904

905`mcp_oauth_callback_url`

906

907Type / Values

908

909`string`

910

911Details

912

913Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

914

915Key

916

731`mcp_oauth_credentials_store`917`mcp_oauth_credentials_store`

732 918

733Type / Values919Type / Values

956 1142

957Key1143Key

958 1144

1145`model_catalog_json`

1146

1147Type / Values

1148

1149`string (path)`

1150

1151Details

1152

1153Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1154

1155Key

1156

959`model_context_window`1157`model_context_window`

960 1158

961Type / Values1159Type / Values

1556 1754

1557Key1755Key

1558 1756

1757`profiles.<name>.model_catalog_json`

1758

1759Type / Values

1760

1761`string (path)`

1762

1763Details

1764

1765Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1766

1767Key

1768

1559`profiles.<name>.oss_provider`1769`profiles.<name>.oss_provider`

1560 1770

1561Type / Values1771Type / Values

1832 2042

1833Key2043Key

1834 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

1835`suppress_unstable_features_warning`2057`suppress_unstable_features_warning`

1836 2058

1837Type / Values2059Type / Values

1974 2196

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

1976 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

1977Expand to view all2211Expand to view all

1978 2212

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

1988 2222

1989## `requirements.toml`2223## `requirements.toml`

1990 2224

1991`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).2225`requirements.toml` is an admin-enforced configuration file that constrains security-sensitive settings users can't override. For details, locations, and examples, see [Admin-enforced requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

1992 2226

1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2227For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

1994requirements. See the security page for precedence details.2228requirements. See the security page for precedence details.

1995 2229

1996| Key | Type / Values | Details |2230| Key | Type / Values | Details |

1997| --- | --- | --- |2231| --- | --- | --- |

2000| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2234| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2001| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |2235| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

2020 2254

2021Details2255Details

2022 2256

2023Allowed values for `approval\_policy`.2257Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).

2024 2258

2025Key2259Key

2026 2260

config-sample.md +76 −18

Details

49# model_context_window = 128000 # tokens; default: auto for model49# model_context_window = 128000 # tokens; default: auto for model

50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults

51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex

52# 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)

52# 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

53 56

54################################################################################57################################################################################

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

107# - untrusted: only known-safe read-only commands auto-run; others prompt110# - untrusted: only known-safe read-only commands auto-run; others prompt

108# - on-request: model decides when to ask (default)111# - on-request: model decides when to ask (default)

109# - never: never prompt (risky)112# - never: never prompt (risky)

113# - { reject = { ... } }: auto-reject selected prompt categories

110approval_policy = "on-request"114approval_policy = "on-request"

115# Example granular auto-reject policy:

116# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

117

118# Allow login-shell semantics for shell-based tools when they request `login = true`.

119# Default: true. Set false to force non-login shells and reject explicit login-shell requests.

120allow_login_shell = true

111 121

112# Filesystem/network sandbox policy for tool calls:122# Filesystem/network sandbox policy for tool calls:

113# - read-only (default)123# - read-only (default)

138# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.148# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.

139# mcp_oauth_callback_port = 4321149# mcp_oauth_callback_port = 4321

140 150

151# Optional redirect URI override for MCP OAuth login (for example, remote devbox ingress).

152# Custom callback paths are supported. `mcp_oauth_callback_port` still controls the listener port.

153# mcp_oauth_callback_url = "https://devbox.example.internal/callback"

154

141################################################################################155################################################################################

142# Project Documentation Controls156# Project Documentation Controls

143################################################################################157################################################################################

194# Active profile name. When unset, no profile is applied.208# Active profile name. When unset, no profile is applied.

195# profile = "default"209# profile = "default"

196 210

211################################################################################

212# Agents (multi-agent roles and limits)

213################################################################################

214

215# [agents]

216# Maximum concurrently open agent threads. Default: 6

217# max_threads = 6

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

219# 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

222

223# [agents.reviewer]

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

225# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

226

197################################################################################227################################################################################

198# Skills (per-skill overrides)228# Skills (per-skill overrides)

199################################################################################229################################################################################

200 230

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

202[[skills.config]]232[[skills.config]]

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

204# enabled = false234# enabled = false

205 235

206################################################################################236################################################################################

276# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).306# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).

277# alternate_screen = "auto"307# alternate_screen = "auto"

278 308

279# Ordered list of footer status-line item IDs. Default: null (disabled).309# Ordered list of footer status-line item IDs. When unset, Codex uses:

310# ["model-with-reasoning", "context-remaining", "current-dir"].

311# Set to [] to hide the footer.

280# status_line = ["model", "context-remaining", "git-branch"]312# status_line = ["model", "context-remaining", "git-branch"]

281 313

314# Syntax-highlighting theme (kebab-case). Use /theme in the TUI to preview and save.

315# You can also add custom .tmTheme files under $CODEX_HOME/themes.

316# theme = "catppuccin-mocha"

317

282# Control whether users can submit feedback from `/feedback`. Default: true318# Control whether users can submit feedback from `/feedback`. Default: true

283[feedback]319[feedback]

284enabled = true320enabled = true

301 337

302[features]338[features]

303# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.339# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.

304shell_tool = true340# shell_tool = true

305# apps = false341# apps = false

306# apps_mcp_gateway = false342# apps_mcp_gateway = false

307# Deprecated legacy toggles; prefer the top-level `web_search` setting.

308# web_search = false

309# web_search_cached = false343# web_search_cached = false

310# web_search_request = false344# web_search_request = false

311unified_exec = false345# unified_exec = false

312shell_snapshot = false346# shell_snapshot = false

313apply_patch_freeform = false347# apply_patch_freeform = false

348# multi_agent = false

314# search_tool = false349# search_tool = false

315# personality = true350# personality = true

316request_rule = true351# request_rule = true

317collaboration_modes = true352# collaboration_modes = true

318use_linux_sandbox_bwrap = false353# use_linux_sandbox_bwrap = false

319experimental_windows_sandbox = false354# remote_models = false

320elevated_windows_sandbox = false355# runtime_metrics = false

321remote_models = false356# powershell_utf8 = true

322runtime_metrics = false357# child_agents_md = false

323powershell_utf8 = true

324child_agents_md = false

325 358

326################################################################################359################################################################################

327# Define MCP servers under this table. Leave empty to disable.360# Define MCP servers under this table. Leave empty to disable.

411# model_verbosity = "medium"444# model_verbosity = "medium"

412# personality = "friendly" # or "pragmatic" or "none"445# personality = "friendly" # or "pragmatic" or "none"

413# chatgpt_base_url = "https://chatgpt.com/backend-api/"446# chatgpt_base_url = "https://chatgpt.com/backend-api/"

447# model_catalog_json = "./models.json"

414# experimental_compact_prompt_file = "./compact_prompt.txt"448# experimental_compact_prompt_file = "./compact_prompt.txt"

415# include_apply_patch_tool = false449# include_apply_patch_tool = false

416# experimental_use_unified_exec_tool = false450# experimental_use_unified_exec_tool = false

424 458

425# Optional per-app controls.459# Optional per-app controls.

426[apps]460[apps]

461# [_default] applies to all apps unless overridden per app.

462# [apps._default]

463# enabled = true

464# destructive_enabled = true

465# open_world_enabled = true

466#

427# [apps.google_drive]467# [apps.google_drive]

428# enabled = false468# enabled = false

429# disabled_reason = "user" # or "unknown"469# destructive_enabled = false # block destructive-hint tools for this app

470# default_tools_enabled = true

471# default_tools_approval_mode = "prompt" # auto | prompt | approve

472#

473# [apps.google_drive.tools."files/delete"]

474# enabled = false

475# approval_mode = "approve"

430 476

431################################################################################477################################################################################

432# Projects (trust levels)478# Projects (trust levels)

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

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

479```525```

526

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

528

529# Windows

530

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

532

533[windows]

534

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

536

537sandbox = "unelevated"

enterprise/admin-setup.md +145 −85

Details

2 2

3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.

4 4

5Use this page as the step-by-step rollout guide. It focuses on setup order and decision points. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Security](https://developers.openai.com/codex/security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

5## Enterprise-grade security and privacy7## Enterprise-grade security and privacy

6 8

7Codex supports ChatGPT Enterprise security features, including:9Codex supports ChatGPT Enterprise security features, including:

8 10

9- No training on enterprise data11- No training on enterprise data

~~10- Zero data retention for the CLI and IDE~~12- Zero data retention for the App, CLI, and IDE (code remains in developer environment)

~~11- Residency and retention follow ChatGPT Enterprise policies~~13- Residency and retention that follow ChatGPT Enterprise policies

12- Granular user access controls14- Granular user access controls

~~13- Data encryption at rest (AES 256) and in transit (TLS 1.2+)~~15- Data encryption at rest (AES-256) and in transit (TLS 1.2+)

14 16

~~15For more, see [Security](https://developers.openai.com/codex/security).~~17For security controls and runtime protections, see [Security](https://developers.openai.com/codex/security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.

16 18

17## Local vs. cloud setup19## Local vs. cloud setup

18 20

19Codex operates in two environments: local and cloud.21Codex operates in two environments: local and cloud.

20 22

~~211. Local use includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.~~231. **Codex local** includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.

222. Use in the cloud includes Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack). The agent runs remotely in a hosted container with your codebase.242. **Codex cloud** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

23 25

~~24Use separate permissions and role-based access control (RBAC) to control access to local and cloud features. You can enable local, cloud, or both for all users or for specific groups.~~26You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

25 27

~~26## Codex local setup~~28## Step 0: Owners and rollout decision

27 29

~~28### Enable Codex app, CLI, and IDE extension in workspace settings~~30Ensure you have the following owners:

29 31

30To enable Codex locally for workspace members, go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings). Turn on **Allow members to use Codex Local**. This setting doesn’t require the GitHub connector.32- Workspace owner with access to ChatGPT Enterprise

33- IT management owner for managed configuration

34- Governance owner for analytics / compliance review

31 35

32After you turn this on, users can sign in to use the Codex app, CLI, and IDE extension with their ChatGPT account. If you turn off this setting, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”36A rollout decision:

33 37

~~34## Team Config~~38- Codex local only (Codex app, CLI, and IDE extension)

39- Codex cloud only (Codex web, GitHub code review)

40- Both local + cloud

35 41

~~36Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.~~42Review [authentication](https://developers.openai.com/codex/auth) before rollout:

37 43

~~38| Type | Path | Use it to |~~44- Codex local supports ChatGPT sign-in or API keys. Confirm MFA/SSO requirements and any managed login restrictions in authentication

~~39| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |~~45- Codex cloud requires ChatGPT sign-in

~~40| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |~~

~~41| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |~~

~~42| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |~~

43 46

~~44For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).~~47## Step 1: Enable workspace toggles

49Turn on only the Codex features you plan to roll out in this phase.

51Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

53### Codex local

55Turn on **Allow members to use Codex Local**.

57This enables use of the Codex app, CLI, and IDE extension for allowed users.

45 58

~~46## Codex cloud setup~~59If this toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”

61#### Enable device code authentication for Codex CLI

63Allow developers to sign in with device codes when using Codex CLI in a non-interactive environment. More details in [authentication](https://developers.openai.com/codex/auth/).

65![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)

67### Codex cloud

47 68

48### Prerequisites69### Prerequisites

49 70

57 78

58Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).79Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

59 80

~~60To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**.~~81To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**. Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.

83Note that it may take up to 10 minutes for Codex to appear in ChatGPT.

85#### Allow members to administer Codex

87Allows users to view overall Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics), access [cloud-managed requirements](https://chatgpt.com/codex/settings/managed-configs), and manage Cloud environments (edit and delete).

89Codex cloud not required.

91#### Enable Codex Slack app to post answers on task completion

93Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.

95To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).

97#### Enable Codex agent to access the internet

99By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.

100

101This setting enables users to use an allowlist for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.

61 102

~~62Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.~~103For security implications of internet access and runtime controls, see [Security](https://developers.openai.com/codex/security).

63 104

64![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)105![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)

65 106

~~66After you turn on Codex in your Enterprise workspace settings, it may take up~~107## Step 2: Set up custom roles (RBAC)

~~67to 10 minutes for Codex to appear in ChatGPT.~~

68 108

~~69### Configure the GitHub Connector IP allow list~~109Use RBAC to control which users or groups can access Codex local and Codex cloud.

70 110

~~71To control which IP addresses can connect to your ChatGPT GitHub connector, configure these IP ranges:~~111### What RBAC lets you do

72 112

~~73- [ChatGPT egress IP ranges](https://openai.com/chatgpt-actions.json)~~113Workspace Owners can use RBAC in ChatGPT admin settings to:

~~74- [Codex container egress IP ranges](https://openai.com/chatgpt-agents.json)~~

75 114

~~76These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.~~115- Set a default role for users who are not assigned any custom role

116- Create custom roles with granular permissions

117- Assign one or more custom roles to Groups (including SCIM-synced groups)

118- Manage roles centrally from the Custom Roles tab

77 119

~~78### Allow members to administer Codex~~120Users can inherit multiple roles, and permissions resolve to the maximum allowed across those roles.

79 121

~~80This toggle allows users to view Codex workspace analytics and manage environments (edit and delete).~~122### Important behavior to plan for

81 123

~~82Codex supports role-based access (see [Role-based access (RBAC)](#role-based-access-rbac)), so you can turn on this toggle for a specific subset of users.~~124Users in any custom role group do not use the workspace default permissions.

83 125

~~84### Enable Codex Slack app to post answers on task completion~~126If you are gradually rolling out Codex, one suggestion is to have a “Codex Users” group and a second “Codex Admin” group that has the “Allow members to administer Codex” toggle enabled.

85 127

~~86Codex integrates with Slack. When a user mentions `@Codex` in Slack, Codex starts a cloud task, gets context from the Slack thread, and responds with a link to a PR to review in the thread.~~128For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).

87 129

88To allow the Slack app to post answers on task completion, turn on **Allow Codex Slack app to post answers on task completion**. When enabled, Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.130## Step 3: Configure Codex local managed settings

89 131

~~90To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).~~132For Codex local, set an admin-approved baseline for local behavior before broader rollout.

91 133

~~92### Enable Codex agent to access the internet~~134### Use managed configuration for two different goals

93 135

~~94By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.~~136- **Requirements** (`requirements.toml`): Admin-enforced constraints users cannot override

137- **Managed defaults** (`managed_config.toml`): Starting values applied when Codex launches

95 138

~~96As an admin, you can allow users to enable agent internet access in their environments. To enable it, turn on **Allow Codex agent to access the internet**.~~139### Team Config

97 140

~~98When this setting is on, users can use an allow list for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.~~141Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.

99 142

100### Enable code review with Codex cloud143| Type | Path | Use it to |

144| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

145| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |

146| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |

147| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |

148

149For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).

150

151### Recommended first decisions for local rollout

152

153Define a baseline for your pilot:

154

155- Approval policy posture

156- Sandbox mode posture

157- Web search posture

158- MCP / connectors policy

159- Local logging and telemetry posture

101 160

102To allow Codex to do code reviews, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).161For exact keys, precedence, MDM deployment, and examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Security](https://developers.openai.com/codex/security).

103 162

104Users can specify whether they want Codex to review their pull requests. Users can also configure whether code review runs for all contributors to a repository.163If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

105 164

106Codex supports two types of code reviews:165## Step 4: Configure Codex cloud usage (if enabled)

107 166

1081. Automatically triggered code reviews when a user opens a PR for review.167This step covers repository and environment setup after the Codex cloud workspace toggle is enabled.

1092. Reactive code reviews when a user mentions @Codex to look at issues. For example, “@Codex fix this CI error” or “@Codex address that feedback.”

110 168

111## Role-based access (RBAC)169### Connect Codex cloud to repositories

112 170

113Codex supports role-based access. RBAC is a security and permissions model used to control access to systems or resources based on a user’s role assignments.1711. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**

1722. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT

1733. Install or authorize the ChatGPT GitHub Connector

1744. Choose an installation target for the ChatGPT Connector (typically your main organization)

1755. Allow the repositories you want to connect to Codex

114 176

115To enable RBAC for Codex, navigate to Settings & Permissions → Custom Roles in [ChatGPT’s admin page](https://chatgpt.com/admin/settings) and assign roles to groups created in the Groups tab.177For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).

116 178

117This simplifies permission management for Codex and improves security in your ChatGPT workspace. To learn more, see the [Help Center article](https://help.openai.com/en/articles/11750701-rbac).179Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.

180

181### Configure IP addresses (as needed)

182

183Configure connector / IP allow lists if required by your network policy with these [egress IP ranges](https://openai.com/chatgpt-agents.json).

184

185These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.

186

187### Enable code review with Codex cloud

118 188

119## Set up your first Codex cloud environment189To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).

120 190

1211. Go to Codex cloud and select **Get started**.191Code review can be configured at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details on [GitHub](https://developers.openai.com/codex/integrations/github) integration page.

1222. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven’t already connected GitHub to ChatGPT.

123 - Allow the ChatGPT Connector for your account.

124 - Choose an installation target for the ChatGPT Connector (typically your main organization).

125 - Allow the repositories you want to connect to Codex (a GitHub admin may need to approve this).

1263. Create your first environment by selecting the repository most relevant to your developers, then select **Create environment**.

127 - Add the email addresses of any environment collaborators to give them edit access.

1284. Start a few starter tasks (for example, writing tests, fixing bugs, or exploring code).

129 192

130You have now created your first environment. Users who connect to GitHub can create tasks using this environment. Users who have access to the repository can also push pull requests generated from their tasks.193Additional integration docs for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).

131 194

132### Environment management195## Step 5: Set up governance and observability

133 196

134As a ChatGPT workspace administrator, you can edit and delete Codex environments in your workspace.197Codex gives enterprise teams several options for visibility into adoption and impact. Set up governance early so your team can monitor adoption, investigate issues, and support compliance workflows.

135 198

136### Connect more GitHub repositories with Codex cloud199### Codex governance typically uses

137 200

1381. Select **Environments**, or open the environment selector and select **Manage Environments**.201- Analytics Dashboard for quick, self-serve visibility

1392. Select **Create Environment**.202- Analytics API for programmatic reporting and BI integration

1403. Select the repository you want to connect.203- Compliance API for audit and investigation workflows

1414. Enter a name and description.

1425. Select the environment visibility.

1436. Select **Create Environment**.

144 204

145Codex automatically optimizes your environment setup by reviewing your codebase. Avoid advanced environment configuration until you observe specific performance issues. For more, see [Codex cloud](https://developers.openai.com/codex/cloud).205### Recommended minimum setup

146 206

147### Share setup instructions with users207- Assign an owner for adoption reporting

208- Assign an owner for audit and compliance review

209- Define a review cadence

210- Decide what success looks like

148 211

149You can share these steps with end users:212For details and examples, see [Governance](https://developers.openai.com/codex/enterprise/governance).

150 213

1511. Go to [Codex](https://chatgpt.com/codex) in the left-hand panel of ChatGPT.214## Step 6: Confirm and validate setup

1522. Select **Connect to GitHub** in the prompt composer if you’re not already connected.

153 - Sign in to GitHub.

1543. You can now use shared environments with your workspace or create your own environment.

1554. Try a task in both Ask and Code mode. For example:

156 - Ask: Find bugs in this codebase.

157 - Write code: Improve test coverage following the existing test patterns.

158 215

159## Track Codex usage216### What to verify

160 217

161- For workspaces with rate limits, use [Settings → Usage](https://chatgpt.com/codex/settings/usage) to view workspace metrics for Codex.218- Users can sign in to Codex local (ChatGPT or API key)

162- For more detail on enterprise governance, refer to the [Governance](https://developers.openai.com/codex/enterprise/governance) page.219- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)

163- For enterprise workspaces with flexible pricing, you can see credit usage in the ChatGPT workspace billing console.220- MFA and SSO requirements match your enterprise security policy

221- RBAC and workspace toggles produce the expected access behavior

222- Managed configuration is applied for users

223- Governance data is visible for admins

164 224

165## Zero data retention (ZDR)225For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).

166 226

167Codex supports OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled.227Once your team is confident with setup, you can confidently roll Codex out to additional teams and organizations.

enterprise/governance.md +2 −0

Details

88 88

89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.

90 90

91For Codex usage authenticated through ChatGPT, Compliance API exports provide audit records for Codex activity and can be used in investigations and compliance workflows. These audit logs are retained for up to 30 days. API-key-authenticated Codex usage follows your API organization settings and is not included in Compliance API exports.

91### What you can export93### What you can export

92 94

93#### Activity logs95#### Activity logs

enterprise/managed-configuration.md +180 −0 added

Details

1# Managed configuration

3Enterprise admins can control local Codex behavior in two ways:

5- **Requirements**: admin-enforced constraints that users can't override.

6- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

8## Admin-enforced requirements (requirements.toml)

10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers can be enabled). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced requirement, Codex falls back to a requirements-compatible value and notifies the user. If an `mcp_servers` allowlist is configured, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

12For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).

14### Locations and precedence

16Requirements layers are applied in this order (earlier wins per field):

181. Cloud-managed requirements (ChatGPT Business or Enterprise)

192. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`

203. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)

22Across layers, requirements are merged per field: if an earlier layer sets a field (including an empty list), later layers do not override that field, but lower layers can still fill fields that remain unset.

24For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

26### Cloud-managed requirements

28When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also fetch admin-enforced requirements from the Codex service. This is another source of `requirements.toml`-compatible requirements. This applies across Codex surfaces, including the CLI, App, and IDE Extension.

30#### Configure cloud-managed requirements

32Go to the [Codex managed-config page](https://chatgpt.com/codex/settings/managed-configs).

34Create a new managed requirements file using the same format and keys as `requirements.toml`.

36```toml

37enforce_residency = "us"

38allowed_approval_policies = ["on-request"]

39allowed_sandbox_modes = ["read-only", "workspace-write"]

41[rules]

42prefix_rules = [

43 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entrypoints" },

44]

45```

47Save the configuration. Once saved, the updated managed requirements apply immediately for matching users.

48For more examples, see [Example requirements.toml](#example-requirementstoml).

50#### Assign requirements to groups

52Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.

54If a user matches multiple group-specific rules, the first matching rule applies. Codex does not fill unset requirement fields from later matching group rules.

56For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and does not fill `allowed_approval_policies` from the later rule.

58#### How Codex applies cloud-managed requirements locally

60When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, invalid, or does not match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.

62After cache resolution, managed requirements are enforced as part of the normal requirements layering described above.

64### Example requirements.toml

66This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

68```toml

69allowed_approval_policies = ["untrusted", "on-request"]

70allowed_sandbox_modes = ["read-only", "workspace-write"]

71```

73You can also constrain web search mode:

75```toml

76allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

77```

79`allowed_web_search_modes = []` effectively allows only `"disabled"`.

80For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

82### Enforce command rules from requirements

84Admins can also enforce restrictive command rules from `requirements.toml`

85using a `[rules]` table. These rules merge with regular `.rules` files, and the

86most restrictive decision still wins.

88Unlike `.rules`, requirements rules must specify `decision`, and that decision

89must be `"prompt"` or `"forbidden"` (not `"allow"`).

91```toml

92[rules]

93prefix_rules = [

94 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

95 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

96]

97```

99To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

100

101```toml

102[mcp_servers.docs]

103identity = { command = "codex-mcp" }

104

105[mcp_servers.remote]

106identity = { url = "https://example.com/mcp" }

107```

108

109If `mcp_servers` is present but empty, Codex disables all MCP servers.

110

111## Managed defaults (`managed_config.toml`)

112

113Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

114

115Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

116

117### Precedence and layering

118

119Codex assembles the effective configuration in this order (top overrides bottom):

120

121- Managed preferences (macOS MDM; highest precedence)

122- `managed_config.toml` (system/managed file)

123- `config.toml` (user's base configuration)

124

125CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

126

127Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.

128

129### Locations

130

131- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

132- Windows/non-Unix: `~/.codex/managed_config.toml`

133

134If the file is missing, Codex skips the managed layer.

135

136### macOS managed preferences (MDM)

137

138On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

139

140- Preference domain: `com.openai.codex`

141- Keys:

142 - `config_toml_base64` (managed defaults)

143 - `requirements_toml_base64` (requirements)

144

145Codex parses these “managed preferences” payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above.

146

147### MDM setup workflow

148

149Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

150

1511. Build the managed payload TOML and encode it with `base64` (no wrapping).

1522. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

1533. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

1544. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

155

156Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

157

158### Example managed_config.toml

159

160```toml

161# Set conservative defaults

162approval_policy = "on-request"

163sandbox_mode = "workspace-write"

164

165[sandbox_workspace_write]

166network_access = false # keep network disabled unless explicitly allowed

167

168[otel]

169environment = "prod"

170exporter = "otlp-http" # point at your collector

171log_user_prompt = false # keep prompts redacted

172# exporter details live under exporter tables; see Monitoring and telemetry above

173```

174

175### Recommended guardrails

176

177- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

178- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

179- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

180- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

mcp.md +9 −1

Details

75- `enabled_tools` (optional): Tool allow list.75- `enabled_tools` (optional): Tool allow list.

76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).

77 77

~~78If your OAuth provider requires a static callback URI, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.~~78If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.

80If your MCP OAuth flow must use a specific callback URL (for example, a remote devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on loopback; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

79 81

80#### config.toml examples82#### config.toml examples

81 83

88MY_ENV_VAR = "MY_ENV_VALUE"90MY_ENV_VAR = "MY_ENV_VALUE"

89```91```

90 92

93```toml

94# Optional MCP OAuth callback overrides (used by `codex mcp login`)

95mcp_oauth_callback_port = 5555

96mcp_oauth_callback_url = "https://devbox.example.internal/callback"

97```

91```toml99```toml

92[mcp_servers.figma]100[mcp_servers.figma]

93url = "https://mcp.figma.com/mcp"101url = "https://mcp.figma.com/mcp"

multi-agent.md +198 −18

Details

31 31

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 33

34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.

34To see it in action, try the following prompt on your project:36To see it in action, try the following prompt on your project:

35 37

36```38```

47 49

48- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.50- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.

49- 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).

54## Process CSV batches with sub-agents

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.

58This works well for repeated audits such as:

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

64The tool accepts:

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

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.

74Example prompt:

76```

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

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

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

89Related runtime settings:

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.

50 94

51## Approvals and sandbox controls95## Approvals and sandbox controls

52 96

~~53Sub-agents inherit your current sandbox policy, but they run with~~97Sub-agents inherit your current sandbox policy.

~~54non-interactive approvals. If a sub-agent attempts an action that would require~~98

~~55a new approval, that action fails and the error is surfaced in the parent~~99In interactive CLI sessions, approval requests can surface from inactive agent

~~56workflow.~~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.

57 112

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

59 114

68 123

69Codex ships with built-in roles:124Codex ships with built-in roles:

70 125

~~71- `default`~~126- `default`: general-purpose fallback role.

~~72- `worker`~~127- `worker`: execution-focused role for implementation and fixes.

~~73- `explorer`~~128- `explorer`: read-heavy codebase exploration role.

129- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).

74 130

75Each agent role can override your default configuration. Common settings to override for an agent role are:131Each agent role can override your default configuration. Common settings to override for an agent role are:

76 132

84| --- | --- | --- | --- |140| --- | --- | --- | --- |

90**Notes:**148**Notes:**

91 149

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

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.

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

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

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

95- If Codex can’t load a role config file, agent spawns can fail until you fix the file.156- If Codex can’t load a role config file, agent spawns can fail until you fix the file.

96- Any configuration not set by the agent role will be inherited from the parent session.157- Any configuration not set by the agent role will be inherited from the parent session.

97 158

98### Example agent roles159### Example agent roles

99 160

100Below 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.

101 162

102Example `~/.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`):

103 172

104```173```

105[agents.default]174[agents]

106description = "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"

107 181

108[agents.reviewer]182[agents.reviewer]

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

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

111 185

112[agents.explorer]186[agents.docs_researcher]

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

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

115```189```

116 190

117Example 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`:

118 205

119```206```

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

121model_reasoning_effort = "high"208model_reasoning_effort = "high"

122developer_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"""

123```215```

124 216

125Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):217`agents/docs-researcher.toml`:

126 218

127```219```

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

129model_reasoning_effort = "medium"221model_reasoning_effort = "medium"

130sandbox_mode = "read-only"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"

261```

262

263`agents/explorer.toml`:

264

265```

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

267model_reasoning_effort = "medium"

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.

131```311```

rules.md +1 −1

Details

43carefully before accepting it.43carefully before accepting it.

44 44

45Admins can also enforce restrictive `prefix_rule` entries from45Admins can also enforce restrictive `prefix_rule` entries from

~~46[`requirements.toml`](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~46[`requirements.toml`](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

47 47

48## Understand rule fields48## Understand rule fields

49 49

security.md +20 −159

Details

13 13

14Codex uses different sandbox modes depending on where you run it:14Codex uses different sandbox modes depending on where you run it:

15 15

16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. You can expand access intentionally (for example, to install dependencies or allow specific domains) when needed. Network access is always enabled during the setup phase, which runs before the agent has access to your code.16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

17- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.17- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

18 18

19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.

20 20

21Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.21Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

22 22

~~23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change.~~23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

24 24

25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)

26 26

73 73

74If 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.74If 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.

75 75

76For 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.

76### Common sandbox and approval combinations78### Common sandbox and approval combinations

77 79

95# Always ask for approval mode97# Always ask for approval mode

96approval_policy = "untrusted"98approval_policy = "untrusted"

97sandbox_mode = "read-only"99sandbox_mode = "read-only"

100allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

98 101

99# Optional: Allow network in workspace-write mode102# Optional: Allow network in workspace-write mode

100[sandbox_workspace_write]103[sandbox_workspace_write]

101network_access = true104network_access = true

105

106# Optional: granular approval prompt auto-rejection

107# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

102```108```

103 109

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

130 136

131Codex enforces the sandbox differently depending on your OS:137Codex enforces the sandbox differently depending on your OS:

132 138

133- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected.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.

134- **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`).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.

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

136 142

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

138 144

144 150

145This 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).

146 152

147The 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.

148 161

149When 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.

150 163

230 243

231## Managed configuration244## Managed configuration

232 245

233Enterprise admins can control local Codex behavior in two ways. For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml):246Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.

~~234~~

235- **Requirements**: admin-enforced constraints that users can’t override.

236- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

~~237~~

238### Admin-enforced requirements (requirements.toml)

~~239~~

240Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers you can enable). If a user explicitly selects a disallowed value (via `config.toml`, CLI flags, profiles, or in-session UI), Codex rejects the change. If a value isn’t explicitly set and the default conflicts with requirements, Codex falls back to a requirements-compliant default. If you configure an `mcp_servers` approved list, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex turns it off.

~~241~~

242#### Locations

~~243~~

244- Linux/macOS (Unix): `/etc/codex/requirements.toml`

245- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`

~~246~~

247#### Cloud requirements (Business and Enterprise)

~~248~~

249When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also

250fetch admin-enforced requirements from the Codex service. This applies across

251Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.

~~252~~

253Cloud requirements are currently best-effort. If the fetch fails or times out,

254Codex continues without the cloud layer.

~~255~~

256Requirements layer in this order (higher wins):

~~257~~

258- macOS managed preferences (MDM; highest precedence)

259- Cloud requirements (ChatGPT Business or Enterprise)

260- `/etc/codex/requirements.toml`

~~261~~

262Cloud requirements only fill unset requirement fields, so higher-precedence

263managed layers still win when both specify the same constraint.

~~264~~

265For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

~~266~~

267#### Example requirements.toml

~~268~~

269This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

~~270~~

271```

272allowed_approval_policies = ["untrusted", "on-request"]

273allowed_sandbox_modes = ["read-only", "workspace-write"]

274```

~~275~~

276You can also constrain web search mode:

~~277~~

278```

279allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

280```

~~281~~

282`allowed_web_search_modes = []` effectively allows only `"disabled"`.

283For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

~~284~~

285#### Enforce command rules from requirements

~~286~~

287Admins can also enforce restrictive command rules from `requirements.toml`

288using a `[rules]` table. These rules merge with regular `.rules` files, and the

289most restrictive decision still wins.

~~290~~

291Unlike `.rules`, requirements rules must specify `decision`, and that decision

292must be `"prompt"` or `"forbidden"` (not `"allow"`).

~~293~~

294```

295[rules]

296prefix_rules = [

297 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

298 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

299]

300```

~~301~~

302To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

~~303~~

304```

305[mcp_servers.docs]

306identity = { command = "codex-mcp" }

~~307~~

308[mcp_servers.remote]

309identity = { url = "https://example.com/mcp" }

310```

~~311~~

312If `mcp_servers` is present but empty, Codex disables all MCP servers.

~~313~~

314### Managed defaults (managed\_config.toml)

~~315~~

316Managed defaults merge on top of a user’s local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

~~317~~

318Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

~~319~~

320#### Precedence and layering

~~321~~

322Codex assembles the effective configuration in this order (top overrides bottom):

~~323~~

324- Managed preferences (macOS MDM; highest precedence)

325- `managed_config.toml` (system/managed file)

326- `config.toml` (user’s base configuration)

~~327~~

328CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

~~329~~

330Cloud requirements affect the requirements layer (not managed defaults). See

331[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)

332for their precedence.

~~333~~

334#### Locations

~~335~~

336- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

337- Windows/non-Unix: `~/.codex/managed_config.toml`

~~338~~

339If the file is missing, Codex skips the managed layer.

~~340~~

341#### macOS managed preferences (MDM)

~~342~~

343On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

~~344~~

345- Preference domain: `com.openai.codex`

346- Keys:

347 - `config_toml_base64` (managed defaults)

348 - `requirements_toml_base64` (requirements)

~~349~~

350Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.

~~351~~

352### MDM setup workflow

~~353~~

354Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

~~355~~

3561. Build the managed payload TOML and encode it with `base64` (no wrapping).

3572. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

3583. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

3594. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

~~360~~

361Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

~~362~~

363### Example managed\_config.toml

~~364~~

365```

366# Set conservative defaults

367approval_policy = "on-request"

368sandbox_mode = "workspace-write"

~~369~~

370[sandbox_workspace_write]

371network_access = false # keep network disabled unless explicitly allowed

~~372~~

373[otel]

374environment = "prod"

375exporter = "otlp-http" # point at your collector

376log_user_prompt = false # keep prompts redacted

377# exporter details live under exporter tables; see Monitoring and telemetry above

378```

~~379~~

380### Recommended guardrails

~~381~~

382- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

383- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

384- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

385- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

windows.md +28 −23

Details

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.

9## Windows sandbox

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

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

18How `elevated` mode works:

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.

24### Grant sandbox read access

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

28```text

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

30```

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 sandbox~~109## Troubleshooting and FAQ

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

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

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.

~~94### Grant sandbox read access~~

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

~~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

OpenAI - Codex Docs Changes 2026-02-23 18:27 UTC → 2026-03-04 06:20 UTC