OpenAI - Codex Docs Changes 2026-03-17 00:33 UTC → 2026-03-26 18:27 UTC

81 81 

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

83 83 

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

85 85 

86### Common sandbox and approval combinations86### Common sandbox and approval combinations

87 87 

111[sandbox_workspace_write]111[sandbox_workspace_write]

112network_access = true112network_access = true

113 113 

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

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

116# sandbox_approval = true,

117# rules = true,

118# mcp_elicitations = true,

119# request_permissions = false,

120# skill_approval = false

121# } }

116```122```

117 123 

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

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

146 152 

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

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

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

150 156 

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

163```toml169```toml

164[windows]170[windows]

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

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

166```173```

167 174 

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

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

22 22 

23```json23```json

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

25```25```

26 26 

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

99 },99 },

100});100});

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

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

103```103```

104 104 

105## Core primitives105## Core primitives

123 123 

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

125 125 

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

127 127 

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

129 129 

159 },159 },

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

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

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

163 "codex/event/session_configured",

164 "item/agentMessage/delta"

165 ]

166 }163 }

167 }164 }

168}165}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

236 240 

237## Models241## Models

238 242 

315 319 

316```json320```json

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

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

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

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

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

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

571 "networkAccess": true575 "networkAccess": true

572 },576 },

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

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

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

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

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

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

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

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

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

716 722 

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

718 724 

773 779 

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

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

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

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

778 784 

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

91 91 

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

93 93 

94## Login diagnostics

95 

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

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

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

99 

100## Custom CA bundles

101 

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

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

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

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

106connections.

107 

108```shell

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

110codex login

111```

112 

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

95 114 

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

46 46 

47## Models and reasoning47## Models and reasoning

48 48 

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

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

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

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

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

54research preview.

50 55 

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

52 57 

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

9 9 

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

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

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

13 13 

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

15 15 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

63 64 

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

65 66 

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

68 

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

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

71 

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

73 

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

67 75 

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

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

93 101 

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

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

96 104 

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

98 106 

209Expected: Codex starts a fresh conversation in the same CLI session, so you217Expected: Codex starts a fresh conversation in the same CLI session, so you

210can switch tasks without leaving your terminal.218can switch tasks without leaving your terminal.

211 219 

212Unlike `/clear`, `/new` doesn’t clear the current terminal view first.220Unlike `/clear`, `/new` does not clear the current terminal view first.

213 221 

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

215 223 

22 22 

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

24 24 

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

26 26 

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

28 28 

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

30 30 

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

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

2 2 

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

4 4 

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

6 6 

1# Subagents1# Subagents

2 2 

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

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

5 5 

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

7 7 

65 65 

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

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

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

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

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

71the agent file.71the agent file.

72 72 

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

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

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

76remains available in research preview.

75 77 

76### Model choice78### Model choice

77 79 

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

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

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

80 83 

81### Reasoning effort (`model_reasoning_effort`)84### Reasoning effort (`model_reasoning_effort`)

82 85 

74 74 

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

76 76 

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

78 78 

79```toml79```toml

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

81codex

82```81```

83 82 

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

87 86 

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

89 88 

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

91 90 

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

93 92 

192 191 

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

194 193 

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

196 195 

197```196```

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

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

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

201 200 

201# Example granular approval policy:

202# approval_policy = { granular = {

203# sandbox_approval = true,

204# rules = true,

205# mcp_elicitations = true,

206# request_permissions = false,

207# skill_approval = false

208# } }

209 

202[sandbox_workspace_write]210[sandbox_workspace_write]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

166 162 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

225 213 

226Key214Key

227 215 

325 313 

326Type / Values314Type / Values

327 315 

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

329 317 

330Details318Details

331 319 

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

333 321 

334Key322Key

335 323 

336`approval_policy.reject.mcp_elicitations`324`approval_policy.granular.mcp_elicitations`

337 325 

338Type / Values326Type / Values

339 327 

341 329 

342Details330Details

343 331 

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

345 333 

346Key334Key

347 335 

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

349 337 

350Type / Values338Type / Values

351 339 

353 341 

354Details342Details

355 343 

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

357 345 

358Key346Key

359 347 

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

361 349 

362Type / Values350Type / Values

363 351 

365 353 

366Details354Details

367 355 

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

357 

358Key

359 

360`approval_policy.granular.sandbox_approval`

361 

362Type / Values

363 

364`boolean`

365 

366Details

367 

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

369 

370Key

371 

372`approval_policy.granular.skill_approval`

373 

374Type / Values

375 

376`boolean`

377 

378Details

379 

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

369 381 

370Key382Key

371 383 

561 573 

562Key574Key

563 575 

576`default_permissions`

577 

578Type / Values

579 

580`string`

581 

582Details

583 

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

585 

586Key

587 

564`developer_instructions`588`developer_instructions`

565 589 

566Type / Values590Type / Values

621 645 

622Key646Key

623 647 

624`features.apps_mcp_gateway`

625 

626Type / Values

627 

628`boolean`

629 

630Details

631 

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

633 

634Key

635 

636`features.artifact`

637 

638Type / Values

639 

640`boolean`

641 

642Details

643 

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

645 

646Key

647 

648`features.child_agents_md`

649 

650Type / Values

651 

652`boolean`

653 

654Details

655 

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

657 

658Key

659 

660`features.collaboration_modes`

661 

662Type / Values

663 

664`boolean`

665 

666Details

667 

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

669 

670Key

671 

672`features.default_mode_request_user_input`

673 

674Type / Values

675 

676`boolean`

677 

678Details

679 

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

681 

682Key

683 

684`features.elevated_windows_sandbox`

685 

686Type / Values

687 

688`boolean`

689 

690Details

691 

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

693 

694Key

695 

696`features.enable_request_compression`648`features.enable_request_compression`

697 649 

698Type / Values650Type / Values

705 657 

706Key658Key

707 659 

708`features.experimental_windows_sandbox`

709 

710Type / Values

711 

712`boolean`

713 

714Details

715 

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

717 

718Key

719 

720`features.fast_mode`660`features.fast_mode`

721 661 

722Type / Values662Type / Values

729 669 

730Key670Key

731 671 

732`features.image_detail_original`672`features.multi_agent`

733 

734Type / Values

735 

736`boolean`

737 

738Details

739 

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

741 

742Key

743 

744`features.image_generation`

745 673 

746Type / Values674Type / Values

747 675 

749 677 

750Details678Details

751 679 

752Enable the built-in image generation tool (under development).680Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default).

753 681 

754Key682Key

755 683 

765 693 

766Key694Key

767 695 

768`features.powershell_utf8`

769 

770Type / Values

771 

772`boolean`

773 

774Details

775 

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

777 

778Key

779 

780`features.prevent_idle_sleep`696`features.prevent_idle_sleep`

781 697 

782Type / Values698Type / Values

789 705 

790Key706Key

791 707 

792`features.remote_models`

793 

794Type / Values

795 

796`boolean`

797 

798Details

799 

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

801 

802Key

803 

804`features.request_rule`

805 

806Type / Values

807 

808`boolean`

809 

810Details

811 

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

813 

814Key

815 

816`features.responses_websockets`

817 

818Type / Values

819 

820`boolean`

821 

822Details

823 

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

825 

826Key

827 

828`features.responses_websockets_v2`

829 

830Type / Values

831 

832`boolean`

833 

834Details

835 

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

837 

838Key

839 

840`features.runtime_metrics`

841 

842Type / Values

843 

844`boolean`

845 

846Details

847 

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

849 

850Key

851 

852`features.search_tool`

853 

854Type / Values

855 

856`boolean`

857 

858Details

859 

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

861 

862Key

863 

864`features.shell_snapshot`708`features.shell_snapshot`

865 709 

866Type / Values710Type / Values

885 729 

886Key730Key

887 731 

888`features.skill_env_var_dependency_prompt`

889 

890Type / Values

891 

892`boolean`

893 

894Details

895 

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

897 

898Key

899 

900`features.skill_mcp_dependency_install`732`features.skill_mcp_dependency_install`

901 733 

902Type / Values734Type / Values

909 741 

910Key742Key

911 743 

912`features.sqlite`744`features.smart_approvals`

913 745 

914Type / Values746Type / Values

915 747 

917 749 

918Details750Details

919 751 

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

921 

922Key

923 

924`features.steer`

925 

926Type / Values

927 

928`boolean`

929 

930Details

931 

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

933 753 

934Key754Key

935 755 

957 777 

958Key778Key

959 779 

960`features.use_linux_sandbox_bwrap`

961 

962Type / Values

963 

964`boolean`

965 

966Details

967 

968Use the bubblewrap-based Linux sandbox pipeline (experimental; off by default).

969 

970Key

971 

972`features.web_search`780`features.web_search`

973 781 

974Type / Values782Type / Values

1737 1545 

1738Key1546Key

1739 1547 

1548`openai_base_url`

1549 

1550Type / Values

1551 

1552`string`

1553 

1554Details

1555 

1556Base URL override for the built-in `openai` model provider.

1557 

1558Key

1559 

1740`oss_provider`1560`oss_provider`

1741 1561 

1742Type / Values1562Type / Values

1953 1773 

1954Key1774Key

1955 1775 

1956`permissions.network.admin_url`1776`permissions.<name>.filesystem`

1957 1777 

1958Type / Values1778Type / Values

1959 1779 

1960`string`1780`table`

1961 1781 

1962Details1782Details

1963 1783 

1964Admin endpoint for the managed network proxy.1784Named filesystem permission profile. Each key is an absolute path or special token such as `:minimal` or `:project_roots`.

1965 1785 

1966Key1786Key

1967 1787 

1968`permissions.network.allow_local_binding`1788`permissions.<name>.filesystem.":project_roots".<subpath>`

1969 1789 

1970Type / Values1790Type / Values

1971 1791 

1972`boolean`1792`"read" | "write" | "none"`

1973 1793 

1974Details1794Details

1975 1795 

1976Permit local bind/listen operations through the managed proxy.1796Scoped filesystem access relative to the detected project roots. Use `"."` for the root itself.

1977 1797 

1978Key1798Key

1979 1799 

1980`permissions.network.allow_unix_sockets`1800`permissions.<name>.filesystem.<path>`

1981 1801 

1982Type / Values1802Type / Values

1983 1803 

1984`array<string>`1804`"read" | "write" | "none" | table`

1985 1805 

1986Details1806Details

1987 1807 

1988Allowlist of Unix socket paths permitted through the managed proxy.1808Grant direct access for a path or special token, or scope nested entries under that root.

1989 1809 

1990Key1810Key

1991 1811 

1992`permissions.network.allow_upstream_proxy`1812`permissions.<name>.network.allow_local_binding`

1993 1813 

1994Type / Values1814Type / Values

1995 1815 

1997 1817 

1998Details1818Details

1999 1819 

2000Allow the managed proxy to chain to another upstream proxy.1820Permit local bind/listen operations through the managed proxy.

2001 1821 

2002Key1822Key

2003 1823 

2004`permissions.network.allowed_domains`1824`permissions.<name>.network.allow_unix_sockets`

2005 1825 

2006Type / Values1826Type / Values

2007 1827 

2009 1829 

2010Details1830Details

2011 1831 

2012Allowlist of domains permitted through the managed proxy.1832Allowlist of Unix socket paths permitted through the managed proxy.

2013 1833 

2014Key1834Key

2015 1835 

2016`permissions.network.dangerously_allow_all_unix_sockets`1836`permissions.<name>.network.allow_upstream_proxy`

2017 1837 

2018Type / Values1838Type / Values

2019 1839 

2021 1841 

2022Details1842Details

2023 1843 

2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.1844Allow the managed proxy to chain to another upstream proxy.

2025 1845 

2026Key1846Key

2027 1847 

2028`permissions.network.dangerously_allow_non_loopback_admin`1848`permissions.<name>.network.allowed_domains`

1849 

1850Type / Values

1851 

1852`array<string>`

1853 

1854Details

1855 

1856Allowlist of domains permitted through the managed proxy.

1857 

1858Key

1859 

1860`permissions.<name>.network.dangerously_allow_all_unix_sockets`

2029 1861 

2030Type / Values1862Type / Values

2031 1863 

2033 1865 

2034Details1866Details

2035 1867 

2036Permit non-loopback bind addresses for the managed proxy admin listener.1868Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2037 1869 

2038Key1870Key

2039 1871 

2040`permissions.network.dangerously_allow_non_loopback_proxy`1872`permissions.<name>.network.dangerously_allow_non_loopback_proxy`

2041 1873 

2042Type / Values1874Type / Values

2043 1875 

2049 1881 

2050Key1882Key

2051 1883 

2052`permissions.network.denied_domains`1884`permissions.<name>.network.denied_domains`

2053 1885 

2054Type / Values1886Type / Values

2055 1887 

2061 1893 

2062Key1894Key

2063 1895 

2064`permissions.network.enable_socks5`1896`permissions.<name>.network.enable_socks5`

2065 1897 

2066Type / Values1898Type / Values

2067 1899 

2069 1901 

2070Details1902Details

2071 1903 

2072Expose a SOCKS5 listener from the managed network proxy.1904Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.

2073 1905 

2074Key1906Key

2075 1907 

2076`permissions.network.enable_socks5_udp`1908`permissions.<name>.network.enable_socks5_udp`

2077 1909 

2078Type / Values1910Type / Values

2079 1911 

2085 1917 

2086Key1918Key

2087 1919 

2088`permissions.network.enabled`1920`permissions.<name>.network.enabled`

2089 1921 

2090Type / Values1922Type / Values

2091 1923 

2093 1925 

2094Details1926Details

2095 1927 

2096Enable the managed network proxy configuration for subprocesses.1928Enable network access for this named permissions profile.

2097 1929 

2098Key1930Key

2099 1931 

2100`permissions.network.mode`1932`permissions.<name>.network.mode`

2101 1933 

2102Type / Values1934Type / Values

2103 1935 

2109 1941 

2110Key1942Key

2111 1943 

2112`permissions.network.proxy_url`1944`permissions.<name>.network.proxy_url`

2113 1945 

2114Type / Values1946Type / Values

2115 1947 

2117 1949 

2118Details1950Details

2119 1951 

2120HTTP proxy endpoint used by the managed network proxy.1952HTTP proxy endpoint used when this permissions profile enables the managed network proxy.

2121 1953 

2122Key1954Key

2123 1955 

2124`permissions.network.socks_url`1956`permissions.<name>.network.socks_url`

2125 1957 

2126Type / Values1958Type / Values

2127 1959 

2129 1961 

2130Details1962Details

2131 1963 

2132SOCKS5 proxy endpoint used by the managed network proxy.1964SOCKS5 proxy endpoint used by this permissions profile.

2133 1965 

2134Key1966Key

2135 1967 

2441 2273 

2442Details2274Details

2443 2275 

2444Preferred service tier for new turns. `fast` is honored only when the `features.fast_mode` gate is enabled.2276Preferred service tier for new turns.

2445 2277 

2446Key2278Key

2447 2279 

2617 2449 

2618Type / Values2450Type / Values

2619 2451 

2620`boolean`2452`boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }`

2621 2453 

2622Details2454Details

2623 2455 

2624Deprecated legacy toggle for web search; prefer the top-level `web_search` setting.2456Optional web search tool configuration. The legacy boolean form is still accepted, but the object form lets you set search context size, allowed domains, and approximate user location.

2625 2457 

2626Key2458Key

2627 2459 

2767 2599 

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

2769 2601 

2602Key

2603 

2604`windows.sandbox_private_desktop`

2605 

2606Type / Values

2607 

2608`boolean`

2609 

2610Details

2611 

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

2613 

2770Expand to view all2614Expand to view all

2771 2615 

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

2791 2635 

2792| Key | Type / Values | Details |2636| Key | Type / Values | Details |

2793| --- | --- | --- |2637| --- | --- | --- |

2794| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`). |2638| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

2795| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2639| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

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

2797| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |2641| `features` | `table` | Pinned feature values keyed by the canonical names from `config.toml`'s `[features]` table. |

2818 2662 

2819Details2663Details

2820 2664 

2821Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).2665Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).

2822 2666 

2823Key2667Key

2824 2668 

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

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

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

110# - { reject = { ... } }: auto-reject selected prompt categories110# - { granular = { ... } }: allow or auto-reject selected prompt categories

111approval_policy = "on-request"111approval_policy = "on-request"

112# Example granular auto-reject policy:112# Example granular policy:

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

114# sandbox_approval = true,

115# rules = true,

116# mcp_elicitations = true,

117# request_permissions = false,

118# skill_approval = false

119# } }

114 120 

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

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

132# Base URL for ChatGPT auth flow (not OpenAI API).138# Base URL for ChatGPT auth flow (not OpenAI API).

133chatgpt_base_url = "https://chatgpt.com/backend-api/"139chatgpt_base_url = "https://chatgpt.com/backend-api/"

134 140 

141# Optional base URL override for the built-in OpenAI provider.

142# openai_base_url = "https://us.api.openai.com/v1"

143 

135# Restrict ChatGPT login to a specific workspace id. Default: unset.144# Restrict ChatGPT login to a specific workspace id. Default: unset.

136# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"145# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

137 146 

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

352# shell_tool = true361# shell_tool = true

353# apps = false362# apps = false

354# apps_mcp_gateway = false363# unified_exec = true

355# unified_exec = false364# shell_snapshot = true

356# shell_snapshot = false365# multi_agent = true

357# personality = true366# personality = true

358# use_linux_sandbox_bwrap = false

359# runtime_metrics = true

360# powershell_utf8 = true

361# child_agents_md = false

362# sqlite = true

363# fast_mode = true367# fast_mode = true

368# smart_approvals = false

364# enable_request_compression = true369# enable_request_compression = true

365# image_generation = false

366# skill_mcp_dependency_install = true370# skill_mcp_dependency_install = true

367# skill_env_var_dependency_prompt = false

368# default_mode_request_user_input = false

369# artifact = false

370# prevent_idle_sleep = false371# prevent_idle_sleep = false

371# responses_websockets = false

372# responses_websockets_v2 = false

373# image_detail_original = false

374 372 

375################################################################################373################################################################################

376# Define MCP servers under this table. Leave empty to disable.374# Define MCP servers under this table. Leave empty to disable.

20is experimental. For the best Windows experience, use Codex in a WSL workspace20is experimental. For the best Windows experience, use Codex in a WSL workspace

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

22 22 

23After you install it, you’ll find the extension in your left sidebar next to your other extensions.23After you install it, you'll find Codex in your editor sidebar.

24In VS Code, Codex opens in the right sidebar by default.

24If you're using VS Code, restart the editor if you don't see Codex right away.25If you're using VS Code, restart the editor if you don't see Codex right away.

25 26 

26If you're using Cursor, the activity bar displays horizontally by default. Collapsed items can hide Codex, so you can pin it and reorganize the order of the extensions.27If you're using Cursor, the activity bar displays horizontally by default. Collapsed items can hide Codex, so you can pin it and reorganize the order of the extensions.

35 36 

36### Move Codex to the right sidebar37### Move Codex to the right sidebar

37 38 

38In VS Code, you can drag the Codex icon to the right of your editor to move it to the right sidebar.39In VS Code, Codex appears in the right sidebar automatically.

40If you prefer it in the primary (left) sidebar, drag the Codex icon back to the left activity bar.

39 41