OpenAI - Codex Docs Changes 2026-03-07 06:14 UTC → 2026-03-18 00:36 UTC

10 10 

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

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

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

13 14 

14## Sandbox and approvals15## Sandbox and approvals

15 16 

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

42 42 

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

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

44 45 

45---46---

46 47 

2 2 

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

4 4 

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

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

7 7 

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

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

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

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

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

11project directory.13project directory.

12 14 

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

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

17 

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

14 19 

15## Managing tasks20## Managing tasks

16 21 

18 23 

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

20 25 

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

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

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

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

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

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

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

22 33 

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

24 35 

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

31 42 

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

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

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

35 46 

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

38 49 

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

40 51 

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

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

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

44 55 

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

46 57 

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

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

50 50 

51## Deeplinks

52 

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

54 

55| Deeplink | Opens | Supported query parameters |

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

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

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

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

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

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

62 

63For new-thread deeplinks:

64 

65- `prompt` prefills the composer.

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

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

68 

51## See also69## See also

52 70 

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

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

86 86 

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

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

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

90failed build while it works with you.

89 91 

90Common tasks include:92Common tasks include:

91 93 

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

11thread runs.11thread runs.

12 12 

13## Appearance

14 

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

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

17 

18## Notifications13## Notifications

19 14 

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

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

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

29 24 

25## Appearance

26 

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

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

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

30 

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

32 

30## Git33## Git

31 34 

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

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

29```29```

30 30 

31## Native sandbox

32 

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

34 

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

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

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

38 targeted exceptions, or set your [approval policy to

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

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

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

42 

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

32 44 

33### Preferred editor45### Preferred editor

26 26 

27OpenAI 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/).

28 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.29Features that rely on ChatGPT credits, such as [fast mode](https://developers.openai.com/codex/speed), are

30available only when you sign in with ChatGPT. If you sign in with an API key,

31Codex uses standard API pricing instead.

32 

33Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Don't expose Codex execution in untrusted or public environments.

30 34 

31## Secure your Codex cloud account35## Secure your Codex cloud account

32 36 

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

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

5 5 

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

7 7 

8## CLI setup8## CLI setup

9 9 

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

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

49 49 

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

51 

50---52---

51 53 

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

59 61 

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

61 63 

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

63 65 

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

65 67 

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

67 69 

20 20 

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

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

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

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

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

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

46 46 

47## Models and reasoning47## Models and reasoning

48 48 

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

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

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

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

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

54research preview.

50 55 

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

52 57 

68 73 

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

70 75 

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

72 77 

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

79 

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

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

82tokens than comparable single-agent runs.

74 83 

75## Image inputs84## Image inputs

76 85 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

93 93 

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

952. Toggle the features you want (for example, **Multi-agents**), then restart Codex.952. Toggle the features you want, then restart Codex.

96 96 

97Expected: 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.

98 98 

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

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

211 211 

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

213 213 

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

215 215 

22 22 

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

24 24 

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

26 26 

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

28 28 

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

30 30 

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

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

2 2 

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

4 4 

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

6 6 

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

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

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

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

11 11 

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

13 13 

19 19 

20- Build and test commands20- Build and test commands

21- Review expectations21- Review expectations

22- Repo-specific conventions22- repo-specific conventions

23- Directory-specific instructions23- Directory-specific instructions

24 24 

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

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

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

46 46 

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

48 48 

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

50 50 

87 87 

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

89 89 

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

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

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

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

94 94 

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

105## MCP105## MCP

106 106 

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

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

109 109 

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

111 111 

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

113 113 

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

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

129 129 

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

131 131 

132## Multi-agents132## Subagents

133 133 

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

135 135 

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

137 137 

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

139 139 

146 146 

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

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

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

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

1# Subagents

2 

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

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

5 

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

7 

8## Why subagent workflows help

9 

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

11 

12This is often described as:

13 

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

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

16 

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

18 

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

20 

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

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

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

24 

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

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

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

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

29thread.

30 

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

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

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

34conflicts and increase coordination overhead.

35 

36## Core terms

37 

38Codex uses a few related terms in subagent workflows:

39 

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

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

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

43 

44## Triggering subagent workflows

45 

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

47explicitly ask for subagents or parallel agent work.

48 

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

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

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

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

53 

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

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

56return.

57 

58```text

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

60```

61 

62## Choosing models and reasoning

63 

64Different agents need different model and reasoning settings.

65 

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

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

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

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

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

71the agent file.

72 

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

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

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

76remains available in research preview.

77 

78### Model choice

79 

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

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

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

83 

84### Reasoning effort (`model_reasoning_effort`)

85 

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

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

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

89 

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

2 2 

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

4 4 

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

6 6 

7## Profiles7## Profiles

8 8 

91 91 

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

93 93 

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

95 95 

96## Project root detection96## Project root detection

97 97 

190 190 

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

192 192 

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

194 194 

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

196 196 

147 147 

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

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

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

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

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

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

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

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

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

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

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

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

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

15| `agents.<name>.nickname_candidates` | `array<string>` | Optional pool of display nicknames for spawned agents in that role. |

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.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). |17| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

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

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

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

20| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |22| `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. |23| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

34| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |36| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

35| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |37| `check_for_update_on_startup` | `boolean` | Check for Codex updates on startup (set to false only when updates are centrally managed). |

36| `cli_auth_credentials_store` | `file | keyring | auto` | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |38| `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. |

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

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

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

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

41| `experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |

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

43| `features.apply_patch_freeform` | `boolean` | Expose the freeform `apply_patch` tool (experimental). |

44| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |45| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (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). |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). |

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

47| `features.collaboration_modes` | `boolean` | Enable collaboration modes such as plan mode (stable; on by default). |49| `features.collaboration_modes` | `boolean` | Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key. |

48| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default). |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). |

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

55| `features.image_detail_original` | `boolean` | Allow image outputs with `detail = "original"` on supported models (under development). |

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

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

50| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output (defaults to true). |58| `features.powershell_utf8` | `boolean` | Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere. |

51| `features.remote_models` | `boolean` | Refresh remote model list before showing readiness (experimental). |59| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

52| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on 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). |

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

54| `features.search_tool` | `boolean` | Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental). |65| `features.search_tool` | `boolean` | Legacy toggle for an older Apps discovery flow. Current builds do not use it. |

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

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

57| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |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). |

70| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on 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). |

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

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

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

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

66| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |82| `hide_agent_reasoning` | `boolean` | Suppress reasoning events in both the TUI and `codex exec` output. |

67| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |83| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

68| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |84| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

69| `include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

70| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |85| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

71| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |86| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

72| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |87| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

83| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |98| `mcp_servers.<id>.env_http_headers` | `map<string,string>` | HTTP headers populated from environment variables for an MCP HTTP server. |

84| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |99| `mcp_servers.<id>.env_vars` | `array<string>` | Additional environment variables to whitelist for an MCP stdio server. |

85| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |100| `mcp_servers.<id>.http_headers` | `map<string,string>` | Static HTTP headers included with each MCP HTTP request. |

101| `mcp_servers.<id>.oauth_resource` | `string` | Optional RFC 8707 OAuth resource parameter to include during MCP login. |

86| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |102| `mcp_servers.<id>.required` | `boolean` | When true, fail startup/resume if this enabled MCP server cannot initialize. |

103| `mcp_servers.<id>.scopes` | `array<string>` | OAuth scopes to request when authenticating to that MCP server. |

87| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |104| `mcp_servers.<id>.startup_timeout_ms` | `number` | Alias for `startup_timeout_sec` in milliseconds. |

88| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |105| `mcp_servers.<id>.startup_timeout_sec` | `number` | Override the default 10s startup timeout for an MCP server. |

89| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |106| `mcp_servers.<id>.tool_timeout_sec` | `number` | Override the default 60s per-tool timeout for an MCP server. |

106| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |123| `model_providers.<id>.requires_openai_auth` | `boolean` | The provider uses OpenAI authentication (defaults to false). |

107| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |124| `model_providers.<id>.stream_idle_timeout_ms` | `number` | Idle timeout for SSE streams in milliseconds (default: 300000). |

108| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |125| `model_providers.<id>.stream_max_retries` | `number` | Retry count for SSE streaming interruptions (default: 5). |

109| `model_providers.<id>.wire_api` | `chat | responses` | Protocol used by the provider (defaults to `chat` if omitted). |126| `model_providers.<id>.supports_websockets` | `boolean` | Whether that provider supports the Responses API WebSocket transport. |

127| `model_providers.<id>.wire_api` | `responses` | Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted. |

110| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |128| `model_reasoning_effort` | `minimal | low | medium | high | xhigh` | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |

111| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |129| `model_reasoning_summary` | `auto | concise | detailed | none` | Select reasoning summary detail or disable summaries entirely. |

112| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |130| `model_supports_reasoning_summaries` | `boolean` | Force Codex to send or not send reasoning metadata. |

113| `model_verbosity` | `low | medium | high` | Control GPT-5 Responses API verbosity (defaults to `medium`). |131| `model_verbosity` | `low | medium | high` | Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used. |

114| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |132| `notice.hide_full_access_warning` | `boolean` | Track acknowledgement of the full access warning prompt. |

115| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |133| `notice.hide_gpt-5.1-codex-max_migration_prompt` | `boolean` | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |

116| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |134| `notice.hide_gpt5_1_migration_prompt` | `boolean` | Track acknowledgement of the GPT-5.1 migration prompt. |

128| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |146| `otel.exporter.<id>.tls.client-certificate` | `string` | Client certificate path for OTEL exporter TLS. |

129| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |147| `otel.exporter.<id>.tls.client-private-key` | `string` | Client private key path for OTEL exporter TLS. |

130| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |148| `otel.log_user_prompt` | `boolean` | Opt in to exporting raw user prompts with OpenTelemetry logs. |

149| `otel.metrics_exporter` | `none | statsig | otlp-http | otlp-grpc` | Select the OpenTelemetry metrics exporter (defaults to `statsig`). |

131| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |150| `otel.trace_exporter` | `none | otlp-http | otlp-grpc` | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |

132| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |151| `otel.trace_exporter.<id>.endpoint` | `string` | Trace exporter endpoint for OTEL logs. |

133| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |152| `otel.trace_exporter.<id>.headers` | `map<string,string>` | Static headers included with OTEL trace exporter requests. |

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

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

137| `otel.trace_exporter.<id>.tls.client-private-key` | `string` | Client private key 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. |

157| `permissions.network.admin_url` | `string` | Admin endpoint for the managed network proxy. |

158| `permissions.network.allow_local_binding` | `boolean` | Permit local bind/listen operations through the managed proxy. |

159| `permissions.network.allow_unix_sockets` | `array<string>` | Allowlist of Unix socket paths permitted through the managed proxy. |

160| `permissions.network.allow_upstream_proxy` | `boolean` | Allow the managed proxy to chain to another upstream proxy. |

161| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains 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. |

163| `permissions.network.dangerously_allow_non_loopback_admin` | `boolean` | Permit non-loopback bind addresses for the managed proxy admin listener. |

164| `permissions.network.dangerously_allow_non_loopback_proxy` | `boolean` | Permit non-loopback bind addresses for the managed proxy listener. |

165| `permissions.network.denied_domains` | `array<string>` | Denylist of domains blocked by the managed proxy. |

166| `permissions.network.enable_socks5` | `boolean` | Expose a SOCKS5 listener from the managed network proxy. |

167| `permissions.network.enable_socks5_udp` | `boolean` | Allow UDP over the SOCKS5 listener when enabled. |

168| `permissions.network.enabled` | `boolean` | Enable the managed network proxy configuration for subprocesses. |

169| `permissions.network.mode` | `limited | full` | Network proxy mode used for subprocess traffic. |

170| `permissions.network.proxy_url` | `string` | HTTP proxy endpoint used by the managed network proxy. |

171| `permissions.network.socks_url` | `string` | SOCKS5 proxy endpoint used by the managed network proxy. |

138| `personality` | `none | friendly | pragmatic` | Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`. |172| `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. |

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

140| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |175| `profiles.<name>.*` | `various` | Profile-scoped overrides for any of the supported configuration keys. |

141| `profiles.<name>.experimental_use_freeform_apply_patch` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |176| `profiles.<name>.analytics.enabled` | `boolean` | Profile-scoped analytics enablement override. |

142| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |177| `profiles.<name>.experimental_use_unified_exec_tool` | `boolean` | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |

143| `profiles.<name>.include_apply_patch_tool` | `boolean` | Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`. |

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

179| `profiles.<name>.model_instructions_file` | `string (path)` | Profile-scoped replacement for the built-in instruction file. |

145| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |180| `profiles.<name>.oss_provider` | `lmstudio | ollama` | Profile-scoped OSS provider for `--oss` sessions. |

146| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |181| `profiles.<name>.personality` | `none | friendly | pragmatic` | Profile-scoped communication style override for supported models. |

182| `profiles.<name>.plan_mode_reasoning_effort` | `none | minimal | low | medium | high | xhigh` | Profile-scoped Plan-mode reasoning override. |

183| `profiles.<name>.service_tier` | `flex | fast` | Profile-scoped service tier preference for new turns. |

184| `profiles.<name>.tools_view_image` | `boolean` | Enable or disable the `view_image` tool in that profile. |

147| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |185| `profiles.<name>.web_search` | `disabled | cached | live` | Profile-scoped web search mode override (default: `"cached"`). |

186| `profiles.<name>.windows.sandbox` | `unelevated | elevated` | Profile-scoped Windows sandbox mode override. |

148| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |187| `project_doc_fallback_filenames` | `array<string>` | Additional filenames to try when `AGENTS.md` is missing. |

149| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |188| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

150| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |189| `project_root_markers` | `array<string>` | List of project root marker filenames; used when searching parent directories for the project root. |

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

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

157| `sandbox_workspace_write.writable_roots` | `array<string>` | Additional writable roots when `sandbox_mode = "workspace-write"`. |196| `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. |

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

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

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

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

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

170| `tool_output_token_limit` | `number` | Token budget for storing individual tool/function outputs in history. |210| `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`. |

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

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

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

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

216| `tui.model_availability_nux.<model>` | `integer` | Internal startup-tooltip state keyed by model slug. |

175| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |217| `tui.notification_method` | `auto | osc9 | bel` | Notification method for unfocused terminal notifications (default: auto). |

176| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |218| `tui.notifications` | `boolean | array<string>` | Enable TUI notifications; optionally restrict to specific event types. |

177| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |219| `tui.show_tooltips` | `boolean` | Show onboarding tooltips in the TUI welcome screen (default: true). |

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

221| `tui.theme` | `string` | Syntax-highlighting theme override (kebab-case theme name). |

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

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

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

206 249 

207Key250Key

208 251 

252`agents.<name>.nickname_candidates`

253 

254Type / Values

255 

256`array<string>`

257 

258Details

259 

260Optional pool of display nicknames for spawned agents in that role.

261 

262Key

263 

209`agents.job_max_runtime_seconds`264`agents.job_max_runtime_seconds`

210 265 

211Type / Values266Type / Values

238 293 

239Details294Details

240 295 

241Maximum number of agent threads that can be open concurrently.296Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.

242 297 

243Key298Key

244 299 

254 309 

255Key310Key

256 311 

312`analytics.enabled`

313 

314Type / Values

315 

316`boolean`

317 

318Details

319 

320Enable or disable analytics for this machine/profile. When unset, the client default applies.

321 

322Key

323 

257`approval_policy`324`approval_policy`

258 325 

259Type / Values326Type / Values

470 537 

471Key538Key

472 539 

540`commit_attribution`

541 

542Type / Values

543 

544`string`

545 

546Details

547 

548Override the commit co-author trailer text. Set an empty string to disable automatic attribution.

549 

550Key

551 

473`compact_prompt`552`compact_prompt`

474 553 

475Type / Values554Type / Values

518 597 

519Key598Key

520 599 

521`experimental_use_freeform_apply_patch`600`experimental_use_unified_exec_tool`

522 601 

523Type / Values602Type / Values

524 603 

526 605 

527Details606Details

528 607 

529Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.608Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.

530 609 

531Key610Key

532 611 

533`experimental_use_unified_exec_tool`612`features.apps`

534 613 

535Type / Values614Type / Values

536 615 

538 617 

539Details618Details

540 619 

541Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.620Enable ChatGPT Apps/connectors support (experimental).

542 621 

543Key622Key

544 623 

545`features.apply_patch_freeform`624`features.apps_mcp_gateway`

546 625 

547Type / Values626Type / Values

548 627 

550 629 

551Details630Details

552 631 

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

554 633 

555Key634Key

556 635 

557`features.apps`636`features.artifact`

558 637 

559Type / Values638Type / Values

560 639 

562 641 

563Details642Details

564 643 

565Enable ChatGPT Apps/connectors support (experimental).644Enable native artifact tools such as slides and spreadsheets (under development).

566 645 

567Key646Key

568 647 

569`features.apps_mcp_gateway`648`features.child_agents_md`

570 649 

571Type / Values650Type / Values

572 651 

574 653 

575Details654Details

576 655 

577Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental).656Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).

578 657 

579Key658Key

580 659 

581`features.child_agents_md`660`features.collaboration_modes`

582 661 

583Type / Values662Type / Values

584 663 

586 665 

587Details666Details

588 667 

589Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).668Legacy toggle for collaboration modes. Plan and default modes are available in current builds without setting this key.

590 669 

591Key670Key

592 671 

593`features.collaboration_modes`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`

594 685 

595Type / Values686Type / Values

596 687 

598 689 

599Details690Details

600 691 

601Enable collaboration modes such as plan mode (stable; on by default).692Legacy toggle for an earlier elevated Windows sandbox rollout. Current builds do not use it.

602 693 

603Key694Key

604 695 

605`features.multi_agent`696`features.enable_request_compression`

606 697 

607Type / Values698Type / Values

608 699 

610 701 

611Details702Details

612 703 

613Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait`, `close_agent`, and `spawn_agents_on_csv`) (experimental; off by default).704Compress streaming request bodies with zstd when supported (stable; on by default).

705 

706Key

707 

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`

721 

722Type / Values

723 

724`boolean`

725 

726Details

727 

728Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).

729 

730Key

731 

732`features.image_detail_original`

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 

746Type / Values

747 

748`boolean`

749 

750Details

751 

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

614 753 

615Key754Key

616 755 

634 773 

635Details774Details

636 775 

637Force PowerShell UTF-8 output (defaults to true).776Force PowerShell UTF-8 output. Enabled by default on Windows and off elsewhere.

777 

778Key

779 

780`features.prevent_idle_sleep`

781 

782Type / Values

783 

784`boolean`

785 

786Details

787 

788Prevent the machine from sleeping while a turn is actively running (experimental; off by default).

638 789 

639Key790Key

640 791 

646 797 

647Details798Details

648 799 

649Refresh remote model list before showing readiness (experimental).800Legacy toggle for an older remote-model readiness flow. Current builds do not use it.

650 801 

651Key802Key

652 803 

658 809 

659Details810Details

660 811 

661Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).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).

662 837 

663Key838Key

664 839 

682 857 

683Details858Details

684 859 

685Enable `search_tool_bm25` for Apps tool discovery before invoking app MCP tools (experimental).860Legacy toggle for an older Apps discovery flow. Current builds do not use it.

686 861 

687Key862Key

688 863 

694 869 

695Details870Details

696 871 

697Snapshot shell environment to speed up repeated commands (beta).872Snapshot shell environment to speed up repeated commands (stable; on by default).

698 873 

699Key874Key

700 875 

710 885 

711Key886Key

712 887 

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`

901 

902Type / Values

903 

904`boolean`

905 

906Details

907 

908Allow prompting and installing missing MCP dependencies for skills (stable; on by default).

909 

910Key

911 

912`features.sqlite`

913 

914Type / Values

915 

916`boolean`

917 

918Details

919 

920Enable SQLite-backed state persistence (stable; on 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 

934Key

935 

936`features.undo`

937 

938Type / Values

939 

940`boolean`

941 

942Details

943 

944Enable undo support (stable; off by default).

945 

946Key

947 

713`features.unified_exec`948`features.unified_exec`

714 949 

715Type / Values950Type / Values

718 953 

719Details954Details

720 955 

721Use the unified PTY-backed exec tool (beta).956Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).

722 957 

723Key958Key

724 959 

854 1089 

855Key1090Key

856 1091 

857`include_apply_patch_tool`

858 

859Type / Values

860 

861`boolean`

862 

863Details

864 

865Legacy name for enabling freeform apply\_patch; prefer `[features].apply_patch_freeform`.

866 

867Key

868 

869`instructions`1092`instructions`

870 1093 

871Type / Values1094Type / Values

1058 1281 

1059Key1282Key

1060 1283 

1284`mcp_servers.<id>.oauth_resource`

1285 

1286Type / Values

1287 

1288`string`

1289 

1290Details

1291 

1292Optional RFC 8707 OAuth resource parameter to include during MCP login.

1293 

1294Key

1295 

1061`mcp_servers.<id>.required`1296`mcp_servers.<id>.required`

1062 1297 

1063Type / Values1298Type / Values

1070 1305 

1071Key1306Key

1072 1307 

1308`mcp_servers.<id>.scopes`

1309 

1310Type / Values

1311 

1312`array<string>`

1313 

1314Details

1315 

1316OAuth scopes to request when authenticating to that MCP server.

1317 

1318Key

1319 

1073`mcp_servers.<id>.startup_timeout_ms`1320`mcp_servers.<id>.startup_timeout_ms`

1074 1321 

1075Type / Values1322Type / Values

1334 1581 

1335Key1582Key

1336 1583 

1584`model_providers.<id>.supports_websockets`

1585 

1586Type / Values

1587 

1588`boolean`

1589 

1590Details

1591 

1592Whether that provider supports the Responses API WebSocket transport.

1593 

1594Key

1595 

1337`model_providers.<id>.wire_api`1596`model_providers.<id>.wire_api`

1338 1597 

1339Type / Values1598Type / Values

1340 1599 

1341`chat | responses`1600`responses`

1342 1601 

1343Details1602Details

1344 1603 

1345Protocol used by the provider (defaults to `chat` if omitted).1604Protocol used by the provider. `responses` is the only supported value, and it is the default when omitted.

1346 1605 

1347Key1606Key

1348 1607 

1390 1649 

1391Details1650Details

1392 1651 

1393Control GPT-5 Responses API verbosity (defaults to `medium`).1652Optional GPT-5 Responses API verbosity override; when unset, the selected model/preset default is used.

1394 1653 

1395Key1654Key

1396 1655 

1598 1857 

1599Key1858Key

1600 1859 

1860`otel.metrics_exporter`

1861 

1862Type / Values

1863 

1864`none | statsig | otlp-http | otlp-grpc`

1865 

1866Details

1867 

1868Select the OpenTelemetry metrics exporter (defaults to `statsig`).

1869 

1870Key

1871 

1601`otel.trace_exporter`1872`otel.trace_exporter`

1602 1873 

1603Type / Values1874Type / Values

1682 1953 

1683Key1954Key

1684 1955 

1956`permissions.network.admin_url`

1957 

1958Type / Values

1959 

1960`string`

1961 

1962Details

1963 

1964Admin endpoint for the managed network proxy.

1965 

1966Key

1967 

1968`permissions.network.allow_local_binding`

1969 

1970Type / Values

1971 

1972`boolean`

1973 

1974Details

1975 

1976Permit local bind/listen operations through the managed proxy.

1977 

1978Key

1979 

1980`permissions.network.allow_unix_sockets`

1981 

1982Type / Values

1983 

1984`array<string>`

1985 

1986Details

1987 

1988Allowlist of Unix socket paths permitted through the managed proxy.

1989 

1990Key

1991 

1992`permissions.network.allow_upstream_proxy`

1993 

1994Type / Values

1995 

1996`boolean`

1997 

1998Details

1999 

2000Allow the managed proxy to chain to another upstream proxy.

2001 

2002Key

2003 

2004`permissions.network.allowed_domains`

2005 

2006Type / Values

2007 

2008`array<string>`

2009 

2010Details

2011 

2012Allowlist of domains permitted through the managed proxy.

2013 

2014Key

2015 

2016`permissions.network.dangerously_allow_all_unix_sockets`

2017 

2018Type / Values

2019 

2020`boolean`

2021 

2022Details

2023 

2024Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.

2025 

2026Key

2027 

2028`permissions.network.dangerously_allow_non_loopback_admin`

2029 

2030Type / Values

2031 

2032`boolean`

2033 

2034Details

2035 

2036Permit non-loopback bind addresses for the managed proxy admin listener.

2037 

2038Key

2039 

2040`permissions.network.dangerously_allow_non_loopback_proxy`

2041 

2042Type / Values

2043 

2044`boolean`

2045 

2046Details

2047 

2048Permit non-loopback bind addresses for the managed proxy listener.

2049 

2050Key

2051 

2052`permissions.network.denied_domains`

2053 

2054Type / Values

2055 

2056`array<string>`

2057 

2058Details

2059 

2060Denylist of domains blocked by the managed proxy.

2061 

2062Key

2063 

2064`permissions.network.enable_socks5`

2065 

2066Type / Values

2067 

2068`boolean`

2069 

2070Details

2071 

2072Expose a SOCKS5 listener from the managed network proxy.

2073 

2074Key

2075 

2076`permissions.network.enable_socks5_udp`

2077 

2078Type / Values

2079 

2080`boolean`

2081 

2082Details

2083 

2084Allow UDP over the SOCKS5 listener when enabled.

2085 

2086Key

2087 

2088`permissions.network.enabled`

2089