OpenAI - Codex Docs Changes 2026-04-22 18:29 UTC → 2026-04-25 00:42 UTC

103 103 

104For 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 prompts, `request_permissions` prompts, and skill-script approvals.104For 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 prompts, `request_permissions` prompts, and skill-script approvals.

105 105 

106Set `approvals_reviewer = "guardian_subagent"` to route eligible approval reviews through the Guardian reviewer subagent instead of prompting the user directly. Admin requirements can constrain this with `allowed_approvals_reviewers`.106### Automatic approval reviews

107 

108By default, approval requests route to you:

109 

110```toml

111approvals_reviewer = "user"

112```

113 

114Automatic approval reviews apply when approvals are interactive, such as

115`approval_policy = "on-request"` or a granular approval policy. Set

116`approvals_reviewer = "auto_review"` to route eligible approval requests

117through a reviewer agent before Codex runs the request:

118 

119```toml

120approval_policy = "on-request"

121approvals_reviewer = "auto_review"

122```

123 

124The reviewer evaluates only actions that already need approval, such as sandbox

125escalations, network requests, `request_permissions` prompts, or side-effecting

126app and MCP tool calls. Actions that stay inside the sandbox continue without an

127extra review step.

128 

129The reviewer policy checks for data exfiltration, credential probing, persistent

130security weakening, and destructive actions. Low-risk and medium-risk actions

131can proceed when policy allows them. The policy denies critical-risk actions.

132High-risk actions require enough user authorization and no matching deny rule.

133Timeouts, parse failures, and review errors fail closed.

134 

135The [default reviewer policy](https://github.com/openai/codex/blob/main/codex-rs/core/src/guardian/policy.md)

136is in the open-source Codex repository. Enterprises can replace its

137tenant-specific section with `guardian_policy_config` in managed requirements.

138Local `[auto_review].policy` text is also supported, but managed requirements

139take precedence. For setup details, see

140[Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration#configure-automatic-review-policy).

141 

142In the Codex app, these reviews appear as automatic review items with a status such

143as Reviewing, Approved, Denied, Stopped, or Timed out. They can also include a

144risk level for the reviewed request.

145 

146Automatic review uses extra model calls, so it can add to Codex usage. Admins

147can constrain it with `allowed_approvals_reviewers`.

107 148 

108### Common sandbox and approval combinations149### Common sandbox and approval combinations

109 150 

66 66 

67Run commands in each thread and launch repeatable project actions.](https://developers.openai.com/codex/app/features#integrated-terminal)[### In-app browser67Run commands in each thread and launch repeatable project actions.](https://developers.openai.com/codex/app/features#integrated-terminal)[### In-app browser

68 68 

69Open unauthenticated local or public pages and comment on rendered output.](https://developers.openai.com/codex/app/browser)[### Image generation69Open rendered pages, leave comments, or let Codex operate local browser flows.](https://developers.openai.com/codex/app/browser)[### Image generation

70 70 

71Generate or edit images in a thread while you work on the surrounding code and assets.](https://developers.openai.com/codex/app/features#image-generation)[### Automations71Generate or edit images in a thread while you work on the surrounding code and assets.](https://developers.openai.com/codex/app/features#image-generation)[### Automations

72 72 

20 20 

21![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)21![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)

22 22 

23## Browser use

24 

25Browser use lets Codex operate the in-app browser directly. Use it for local

26development servers and file-backed previews when Codex needs to click, type,

27inspect rendered state, take screenshots, or verify a fix in the page.

28 

29To use it, install and enable the Browser plugin. Then ask Codex to use the

30browser in your task, or reference it directly with `@Browser`. The app keeps

31browser use inside the in-app browser and lets you manage allowed and blocked

32websites from settings.

33 

34Example:

35 

36```text

37Use the browser to open http://localhost:3000/settings, reproduce the layout

38bug, and fix only the overflowing controls.

39```

40 

41Codex asks before using a website unless you've allowed it. Removing a site from

42the allowed list means Codex asks again before using it; removing a site from the

43blocked list means Codex can ask again instead of treating it as blocked.

44 

23## Preview a page45## Preview a page

24 46 

251. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).471. Start your app's development server in the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or with a [local environment action](https://developers.openai.com/codex/app/local-environments#actions).

4with built-in worktree support, automations, and Git functionality.4with built-in worktree support, automations, and Git functionality.

5 5 

6Most Codex app features are available on both macOS and Windows.6Most Codex app features are available on both macOS and Windows.

7Platform-specific exceptions are noted below.7The sections below note platform-specific exceptions.

8 8 

9---9---

10 10 

146Use browser comments to mark specific elements or areas on a page, then ask146Use browser comments to mark specific elements or areas on a page, then ask

147Codex to address that feedback.147Codex to address that feedback.

148 148 

149When you want Codex to operate the page directly, use

150[browser use](https://developers.openai.com/codex/app/browser#browser-use) for local development servers and

151file-backed pages. You can manage the Browser plugin, allowed websites, and

152blocked websites from settings.

153 

149![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)154![Codex app showing a browser comment on a local web app preview](/images/codex/app/in-app-browser-light.webp)

150 155 

151## Computer use156## Computer use

225opening separate projects or using worktrees rather than asking Codex to roam230opening separate projects or using worktrees rather than asking Codex to roam

226outside the project root.231outside the project root.

227 232 

233If [automatic review](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)

234is available in your workspace, you can choose it from the permissions selector.

235It keeps the same sandbox boundary but routes eligible approval requests through

236the configured review policy instead of waiting for you.

237 

228For a high-level overview, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For238For a high-level overview, see [sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For

229configuration details, see the239configuration details, see the

230[agent approvals & security documentation](https://developers.openai.com/codex/agent-approvals-security).240[agent approvals & security documentation](https://developers.openai.com/codex/agent-approvals-security).

43also apply to the Codex CLI and IDE extension because the MCP configuration lives in43also apply to the Codex CLI and IDE extension because the MCP configuration lives in

44`config.toml`. See the [Model Context Protocol docs](https://developers.openai.com/codex/mcp) for details.44`config.toml`. See the [Model Context Protocol docs](https://developers.openai.com/codex/mcp) for details.

45 45 

46## Browser use

47 

48Use these settings to install or enable the bundled Browser plugin and manage

49allowlisted and blocklisted websites. Codex asks before using a website

50unless you’ve allowlisted it. Removing a site from the blocklist lets Codex ask

51again before using it in the browser.

52 

53See [In-app browser](https://developers.openai.com/codex/app/browser) for browser preview, comment, and

54browser use workflows.

55 

46## Computer Use56## Computer Use

47 57 

48On macOS, check your Computer Use settings to review desktop-app access and related58On macOS, check your Computer Use settings to review desktop-app access and related

43 43 

44 npm i -g @openai/codex@latestCopy44 npm i -g @openai/codex@latestCopy

45 45 

46The Codex CLI is available on macOS and Linux. Windows support is46The Codex CLI is available on macOS, Windows, and Linux. On Windows, run Codex

47experimental. For the best Windows experience, use Codex in a WSL2 workspace47 natively in PowerShell with the Windows sandbox, or use WSL2 when you need a

48and follow our [Windows setup guide](https://developers.openai.com/codex/windows).48Linux-native environment. For setup details, see the

49[Windows setup guide](https://developers.openai.com/codex/windows).

49 50 

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

51 52 

107 107 

108## Models and reasoning108## Models and reasoning

109 109 

110For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the110For most tasks in Codex, `gpt-5.5` is the recommended model when it is

111industry-leading coding capabilities of `gpt-5.3-codex` to OpenAI’s flagship111available. It is OpenAI's newest frontier model for complex coding, computer

112frontier model, combining frontier coding performance with stronger reasoning,112use, knowledge work, and research workflows, with stronger planning, tool use,

113native computer use, and broader professional workflows. For extra fast tasks,113and follow-through on multi-step tasks. If `gpt-5.5` is not yet available,

114ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in114continue using `gpt-5.4`. For extra fast tasks, ChatGPT Pro subscribers have

115research preview.115access to the GPT-5.3-Codex-Spark model in research preview.

116 116 

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

118 118 

119```bash119```bash

120codex --model gpt-5.4120codex --model gpt-5.5

121```121```

122 122 

123[Learn more about the models available in Codex](https://developers.openai.com/codex/models).123[Learn more about the models available in Codex](https://developers.openai.com/codex/models).

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

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

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

43| [`/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. |43| [`/fast`](#toggle-fast-mode-with-fast) | Toggle Fast mode for supported models. | Turn Fast mode on or off, or check whether the current thread is using it. |

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

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

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

67 67 

68Codex surfaces a startup warning when `bwrap` is missing or when the helper68Codex surfaces a startup warning when `bwrap` is missing or when the helper

69can't create the needed user namespace. On distributions that restrict this69can't create the needed user namespace. On distributions that restrict this

70AppArmor setting, you can enable it with:70AppArmor setting, prefer loading the `bwrap` AppArmor profile so `bwrap` can

71keep working without disabling the restriction globally.

72 

73**Ubuntu AppArmor note:** On Ubuntu 25.04, installing `bubblewrap` from

74 Ubuntu's package repository should work without extra AppArmor setup. The

75 `bwrap-userns-restrict` profile ships in the `apparmor` package at

76 `/etc/apparmor.d/bwrap-userns-restrict`.

77 

78On Ubuntu 24.04, Codex may still warn that it can't create the needed user

79namespace after `bubblewrap` is installed. Copy and load the extra profile:

80 

81```bash

82sudo apt update

83sudo apt install apparmor-profiles apparmor-utils

84sudo install -m 0644 \

85 /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \

86 /etc/apparmor.d/bwrap-userns-restrict

87sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

88```

89 

90`apparmor_parser -r` loads the profile into the kernel without a reboot. You

91can also reload all AppArmor profiles:

92 

93```bash

94sudo systemctl reload apparmor.service

95```

96 

97If that profile is unavailable or does not resolve the issue, you can disable

98the AppArmor unprivileged user namespace restriction with:

71 99 

72```bash100```bash

73sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0101sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

142[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the170[Codex app features](https://developers.openai.com/codex/app/features#approvals-and-sandboxing), and for the

143IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).171IDE-specific settings entry points, see [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings).

144 172 

173Automatic review, when available, doesn't change the sandbox boundary. It

174reviews approval requests, such as sandbox escalations or network access, while

175actions already allowed inside the sandbox run without extra review. See

176[Automatic approval reviews](https://developers.openai.com/codex/agent-approvals-security#automatic-approval-reviews)

177for the policy behavior.

178 

145Platform details live in the platform-specific docs. For native Windows setup,179Platform details live in the platform-specific docs. For native Windows setup,

146behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin180behavior, and troubleshooting, see [Windows](https://developers.openai.com/codex/windows). For admin

147requirements and organization-level constraints on sandboxing and approvals, see181requirements and organization-level constraints on sandboxing and approvals, see

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.4-mini` for fast scans or a higher-effort `gpt-5.4`68`gpt-5.4-mini` for fast scans or a higher-effort `gpt-5.5` configuration for

69configuration for more demanding reasoning. When you want finer control, steer that69more demanding reasoning when that model is available. When you want finer

70choice in your prompt or set `model` and `model_reasoning_effort` directly in70control, steer that choice in your prompt or set `model` and

71the agent file.71`model_reasoning_effort` directly in the agent file.

72 72 

73For most tasks in Codex, start with `gpt-5.4`. Use `gpt-5.4-mini` when you73For most tasks in Codex, start with `gpt-5.5` when it is available. Continue

74want a faster, lower-cost option for lighter subagent work. If you have74 using `gpt-5.4` during the rollout if `gpt-5.5` is not yet available. Use

75ChatGPT Pro and want near-instant text-only iteration, `gpt-5.3-codex-spark`75 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter subagent

76remains available in research preview.76 work. If you have ChatGPT Pro and want near-instant text-only iteration,

77 `gpt-5.3-codex-spark` remains available in research preview.

77 78 

78### Model choice79### Model choice

79 80 

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.5`**: Start here for demanding agents when it is available. It is strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

82- **`gpt-5.4`**: Use this when `gpt-5.5` is not yet available or when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

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.83- **`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.84- **`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 85 

84 84 

85In addition to your user config, Codex reads project-scoped overrides from `.codex/config.toml` files inside your repo. Codex walks from the project root to your current working directory and loads every `.codex/config.toml` it finds. If multiple files define the same key, the closest file to your working directory wins.85In addition to your user config, Codex reads project-scoped overrides from `.codex/config.toml` files inside your repo. Codex walks from the project root to your current working directory and loads every `.codex/config.toml` it finds. If multiple files define the same key, the closest file to your working directory wins.

86 86 

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.87For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores project `.codex/` layers, including `.codex/config.toml`, project-local hooks, and project-local rules. User and system layers remain separate and still load.

88 88 

89Relative paths inside a project config (for example, `model_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`.

90 90 

91## Hooks (experimental)91## Hooks (experimental)

92 92 

93Codex can also load lifecycle hooks from `hooks.json` files that sit next to93Codex can also load lifecycle hooks from either `hooks.json` files or inline

94active config layers.94`[hooks]` tables in `config.toml` files that sit next to active config layers.

95 95 

96In practice, the two most useful locations are:96In practice, the two most useful locations are:

97 97 

98- `~/.codex/hooks.json`98- `~/.codex/hooks.json`

99- `~/.codex/config.toml`

99- `<repo>/.codex/hooks.json`100- `<repo>/.codex/hooks.json`

101- `<repo>/.codex/config.toml`

102 

103Project-local hooks load only when the project `.codex/` layer is trusted.

104User-level hooks remain independent of project trust.

100 105 

101Turn hooks on with:106Turn hooks on with:

102 107 

105codex_hooks = true110codex_hooks = true

106```111```

107 112 

113Inline TOML hooks use the same event structure as `hooks.json`:

114 

115```toml

116[[hooks.PreToolUse]]

117matcher = "^Bash$"

118 

119[[hooks.PreToolUse.hooks]]

120type = "command"

121command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

122timeout = 30

123statusMessage = "Checking Bash command"

124```

125 

126If a single layer contains both `hooks.json` and inline `[hooks]`, Codex loads

127both and warns. Prefer one representation per layer.

128 

108For the current event list, input fields, output behavior, and limitations, see129For the current event list, input fields, output behavior, and limitations, see

109[Hooks](https://developers.openai.com/codex/hooks).130[Hooks](https://developers.openai.com/codex/hooks).

110 131 

230 251 

231You 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.252You 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.

232 253 

233```254Set `approvals_reviewer = "auto_review"` to route eligible interactive approval

255requests through automatic review. This changes the reviewer, not the sandbox

256boundary.

257 

258Use `[auto_review].policy` for local reviewer policy instructions. Managed

259`guardian_policy_config` takes precedence.

260 

261```toml

234approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }262approval_policy = "untrusted" # Other options: on-request, never, or { granular = { ... } }

263approvals_reviewer = "user" # Or "auto_review" for automatic review

235sandbox_mode = "workspace-write"264sandbox_mode = "workspace-write"

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

237 266 

249exclude_slash_tmp = false # Allow /tmp278exclude_slash_tmp = false # Allow /tmp

250writable_roots = ["/Users/YOU/.pyenv/shims"]279writable_roots = ["/Users/YOU/.pyenv/shims"]

251network_access = false # Opt in to outbound network280network_access = false # Opt in to outbound network

281 

282[auto_review]

283policy = """

284Use your organization's automatic review policy.

285"""

252```286```

253 287 

254Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).288Need the complete key list (including profile-scoped overrides and requirements constraints)? See [Configuration Reference](https://developers.openai.com/codex/config-reference) and [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration).

1# Config basics1# Config basics

2 2 

3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project config files only when you trust the project.3Codex reads configuration details from more than one location. Your personal defaults live in `~/.codex/config.toml`, and you can add project overrides with `.codex/config.toml` files. For security, Codex loads project `.codex/` layers only when you trust the project.

4 4 

5## Codex configuration file5## Codex configuration file

6 6 

27 27 

28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.28Use that precedence to set shared defaults at the top level and keep profiles focused on the values that differ.

29 29 

30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers (including `.codex/config.toml`) and falls back to user, system, and built-in defaults.30If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

31 31 

32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).32For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli).

33 33 

46Choose the model Codex uses by default in the CLI and IDE.46Choose the model Codex uses by default in the CLI and IDE.

47 47 

48```toml48```toml

49model = "gpt-5.4"49model = "gpt-5.5"

50```50```

51 51 

52#### Approval prompts52#### Approval prompts

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| `codex_hooks` | false | Under development | Enable lifecycle hooks from `hooks.json`. See [Hooks](https://developers.openai.com/codex/hooks). |151| `codex_hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |152| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |153| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

154| `multi_agent` | true | Stable | Enable subagent collaboration tools |154| `multi_agent` | true | Stable | Enable subagent collaboration tools |

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

156| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |156| `shell_snapshot` | true | Stable | Snapshot your shell environment to speed up repeated commands |

157| `shell_tool` | true | Stable | Enable the default `shell` tool |157| `shell_tool` | true | Stable | Enable the default `shell` tool |

158| `guardian_approval` | false | Experimental | Route eligible approval requests through the guardian reviewer subagent (set `approvals_reviewer = "guardian_subagent"`). |

159| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |158| `unified_exec` | `true` except Windows | Stable | Use the unified PTY-backed exec tool |

160| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |159| `undo` | false | Stable | Enable undo via per-turn git ghost snapshots |

161| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |160| `web_search` | true | Deprecated | Legacy toggle; prefer the top-level `web_search` setting |

24| `approval_policy.granular.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are allowed to surface. |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. |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. |26| `approval_policy.granular.skill_approval` | `boolean` | When `true`, skill-script approval prompts are allowed to surface. |

27| `approvals_reviewer` | `user | guardian_subagent` | Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent. |27| `approvals_reviewer` | `user | auto_review` | Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox. |

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

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

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

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

36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |36| `apps.<id>.tools.<tool>.approval_mode` | `auto | prompt | approve` | Per-tool approval behavior override for a single app tool. |

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

38| `auto_review.policy` | `string` | Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored. |

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

39| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |40| `chatgpt_base_url` | `string` | Override the base URL used during the ChatGPT login flow. |

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

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

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

49| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |50| `features.apps` | `boolean` | Enable ChatGPT Apps/connectors support (experimental). |

50| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` (under development; off by default). |51| `features.codex_hooks` | `boolean` | Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. |

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

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

53| `features.guardian_approval` | `boolean` | Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`. |

54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |54| `features.memories` | `boolean` | Enable [Memories](https://developers.openai.com/codex/memories) (off by default). |

55| `features.multi_agent` | `boolean` | Enable multi-agent collaboration tools (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, and `close_agent`) (stable; on by default). |55| `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.personality` | `boolean` | Enable personality selection controls (stable; on by default). |56| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

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

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

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

73| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

73| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |74| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

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

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

104| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |105| `memories.max_unused_days` | `number` | Maximum days since a memory was last used before it becomes ineligible for consolidation. Defaults to `30` and is clamped to `0`-`365`. |

105| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |106| `memories.min_rollout_idle_hours` | `number` | Minimum idle time before a thread is considered for memory generation. Defaults to `6` and is clamped to `1`-`48`. |

106| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |107| `memories.use_memories` | `boolean` | When `false`, Codex skips injecting existing memories into future sessions. Defaults to `true`. |

107| `model` | `string` | Model to use (e.g., `gpt-5.4`). |108| `model` | `string` | Model to use (e.g., `gpt-5.5`). |

108| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |109| `model_auto_compact_token_limit` | `number` | Token threshold that triggers automatic history compaction (unset uses model defaults). |

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

110| `model_context_window` | `number` | Context window tokens available to the active model. |111| `model_context_window` | `number` | Context window tokens available to the active model. |

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

196| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |197| `project_doc_max_bytes` | `number` | Maximum bytes read from `AGENTS.md` when building project instructions. |

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

198| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers. |199| `projects.<path>.trust_level` | `string` | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules. |

199| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |200| `review_model` | `string` | Optional model override used by `/review` (defaults to the current session model). |

200| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |201| `sandbox_mode` | `read-only | workspace-write | danger-full-access` | Sandbox policy for filesystem and network access during command execution. |

201| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |202| `sandbox_workspace_write.exclude_slash_tmp` | `boolean` | Exclude `/tmp` from writable roots in workspace-write mode. |

409 410 

410Type / Values411Type / Values

411 412 

412`user | guardian_subagent`413`user | auto_review`

413 414 

414Details415Details

415 416 

416Select who reviews eligible approval prompts. Defaults to `user`; `guardian_subagent` routes supported reviews through the Guardian reviewer subagent.417Who reviews eligible approval prompts under `on-request` or granular approval policies. Defaults to `user`; `auto_review` uses the reviewer subagent. This setting doesn't change sandboxing or review actions already allowed inside the sandbox.

417 418 

418Key419Key

419 420 

537 538 

538Key539Key

539 540 

541`auto_review.policy`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

549Local Markdown policy instructions for automatic review. Managed `guardian_policy_config` takes precedence. Blank values are ignored.

550 

551Key

552 

540`background_terminal_max_timeout`553`background_terminal_max_timeout`

541 554 

542Type / Values555Type / Values

689 702 

690Details703Details

691 704 

692Enable lifecycle hooks loaded from `hooks.json` (under development; off by default).705Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.

693 706 

694Key707Key

695 708 

717 730 

718Key731Key

719 732 

720`features.guardian_approval`

721 

722Type / Values

723 

724`boolean`

725 

726Details

727 

728Route eligible approval requests through the guardian reviewer subagent (experimental; off by default). Use with `approvals_reviewer = "guardian_subagent"`.

729 

730Key

731 

732`features.memories`733`features.memories`

733 734 

734Type / Values735Type / Values

957 958 

958Key959Key

959 960 

961`hooks`

962 

963Type / Values

964 

965`table`

966 

967Details

968 

969Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.

970 

971Key

972 

960`instructions`973`instructions`

961 974 

962Type / Values975Type / Values

1373 1386 

1374Details1387Details

1375 1388 

1376Model to use (e.g., `gpt-5.4`).1389Model to use (e.g., `gpt-5.5`).

1377 1390 

1378Key1391Key

1379 1392 

2465 2478 

2466Details2479Details

2467 2480 

2468Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers.2481Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). Untrusted projects skip project-scoped `.codex/` layers, including project-local config, hooks, and rules.

2469 2482 

2470Key2483Key

2471 2484 

2948| Key | Type / Values | Details |2961| Key | Type / Values | Details |

2949| --- | --- | --- |2962| --- | --- | --- |

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

2951| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`). |2964| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

2952| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |2965| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

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

2967| `feature_requirements` | `table` | Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key. |

2968| `feature_requirements.browser_use` | `boolean` | Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`. |

2969| `feature_requirements.computer_use` | `boolean` | Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`. |

2970| `feature_requirements.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`. |

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

2955| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |2972| `features.<name>` | `boolean` | Require a specific canonical feature key to stay enabled or disabled. |

2973| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

2974| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |

2975| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |

2976| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

2977| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |

2978| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |

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

2957| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |2980| `mcp_servers.<id>.identity` | `table` | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |

2958| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |2981| `mcp_servers.<id>.identity.command` | `string` | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |

2959| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |2982| `mcp_servers.<id>.identity.url` | `string` | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |

2960| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |2983| `permissions.filesystem.deny_read` | `array<string>` | Admin-enforced filesystem read denials. Entries can be paths or glob patterns, and users cannot weaken them with local config. |

2984| `remote_sandbox_config` | `array<table>` | Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only. |

2985| `remote_sandbox_config[].allowed_sandbox_modes` | `array<string>` | Allowed sandbox modes to apply when this host-specific entry matches. |

2986| `remote_sandbox_config[].hostname_patterns` | `array<string>` | Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character. |

2961| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |2987| `rules` | `table` | Admin-enforced command rules merged with `.rules` files. Requirements rules must be restrictive. |

2962| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |2988| `rules.prefix_rules` | `array<table>` | List of enforced prefix rules. Each rule must include `pattern` and `decision`. |

2963| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |2989| `rules.prefix_rules[].decision` | `prompt | forbidden` | Required. Requirements rules can only prompt or forbid (not allow). |

2988 3014 

2989Details3015Details

2990 3016 

2991Allowed values for `approvals_reviewer` (for example `user` and `guardian_subagent`).3017Allowed values for `approvals_reviewer`, such as `user` and `auto_review`.

2992 3018 

2993Key3019Key

2994 3020 

3016 3042 

3017Key3043Key

3018 3044 

3045`feature_requirements`

3046 

3047Type / Values

3048 

3049`table`

3050 

3051Details

3052 

3053Alias for `features` in `requirements.toml`. Use it to pin feature values by canonical feature key.

3054 

3055Key

3056 

3057`feature_requirements.browser_use`

3058 

3059Type / Values

3060 

3061`boolean`

3062 

3063Details

3064 

3065Set to `false` in `requirements.toml` to disable Browser Use and Browser Agent availability. You can also set `features.browser_use`.

3066 

3067Key

3068 

3069`feature_requirements.computer_use`

3070 

3071Type / Values

3072 

3073`boolean`

3074 

3075Details

3076 

3077Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows. You can also set `features.computer_use`.

3078 

3079Key

3080 

3081`feature_requirements.in_app_browser`

3082 

3083Type / Values

3084 

3085`boolean`

3086 

3087Details

3088 

3089Set to `false` in `requirements.toml` to disable the in-app browser pane. You can also set `features.in_app_browser`.

3090 

3091Key

3092 

3019`features`3093`features`

3020 3094 

3021Type / Values3095Type / Values

3040 3114 

3041Key3115Key

3042 3116 

3117`guardian_policy_config`

3118 

3119Type / Values

3120 

3121`string`

3122 

3123Details

3124 

3125Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored.

3126 

3127Key

3128 

3129`hooks`

3130 

3131Type / Values

3132 

3133`table`

3134 

3135Details

3136 

3137Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`.

3138 

3139Key

3140 

3141`hooks.<Event>`

3142 

3143Type / Values

3144 

3145`array<table>`

3146 

3147Details

3148 

3149Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.

3150 

3151Key

3152 

3153`hooks.<Event>[].hooks`

3154 

3155Type / Values

3156 

3157`array<table>`

3158 

3159Details

3160 

3161Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

3162 

3163Key

3164 

3165`hooks.managed_dir`

3166 

3167Type / Values

3168 

3169`string (absolute path)`

3170 

3171Details

3172 

3173Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks.

3174 

3175Key

3176 

3177`hooks.windows_managed_dir`

3178 

3179Type / Values

3180 

3181`string (absolute path)`

3182 

3183Details

3184 

3185Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks.

3186 

3187Key

3188 

3043`mcp_servers`3189`mcp_servers`

3044 3190 

3045Type / Values3191Type / Values

3100 3246 

3101Key3247Key

3102 3248 

3249`remote_sandbox_config`

3250 

3251Type / Values

3252 

3253`array<table>`

3254 

3255Details

3256 

3257Host-specific sandbox requirements. The first entry whose `hostname_patterns` match the resolved host name overrides top-level `allowed_sandbox_modes` for that requirements source. Host-specific entries currently override sandbox modes only.

3258 

3259Key

3260 

3261`remote_sandbox_config[].allowed_sandbox_modes`

3262 

3263Type / Values

3264 

3265`array<string>`

3266 

3267Details

3268 

3269Allowed sandbox modes to apply when this host-specific entry matches.

3270 

3271Key

3272 

3273`remote_sandbox_config[].hostname_patterns`

3274 

3275Type / Values

3276 

3277`array<string>`

3278 

3279Details

3280 

3281Case-insensitive host name patterns. Supports `*` for any sequence of characters and `?` for one character.

3282 

3283Key

3284 

3103`rules`3285`rules`

3104 3286 

3105Type / Values3287Type / Values

27# Core Model Selection27# Core Model Selection

28################################################################################28################################################################################

29 29 

30# Primary model used by Codex. Recommended example for most users: "gpt-5.4".30# Primary model used by Codex. Recommended example for most users: "gpt-5.5".

31model = "gpt-5.4"31model = "gpt-5.5"

32 32 

33# Communication style for supported models. Allowed values: none | friendly | pragmatic33# Communication style for supported models. Allowed values: none | friendly | pragmatic

34# personality = "pragmatic"34# personality = "pragmatic"

35 35 

36# Optional model override for /review. Default: unset (uses current session model).36# Optional model override for /review. Default: unset (uses current session model).

37# review_model = "gpt-5.4"37# review_model = "gpt-5.5"

38 38 

39# Provider id selected from [model_providers]. Default: "openai".39# Provider id selected from [model_providers]. Default: "openai".

40model_provider = "openai"40model_provider = "openai"

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

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

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

112# Who reviews eligible approval prompts: user (default) | guardian_subagent112# Who reviews eligible approval prompts: user (default) | auto_review

113# approvals_reviewer = "user"113# approvals_reviewer = "user"

114 114 

115# Example granular policy:115# Example granular policy:

393# multi_agent = true393# multi_agent = true

394# personality = true394# personality = true

395# fast_mode = true395# fast_mode = true

396# guardian_approval = false

397# enable_request_compression = true396# enable_request_compression = true

398# skill_mcp_dependency_install = true397# skill_mcp_dependency_install = true

399# prevent_idle_sleep = false398# prevent_idle_sleep = false

408# use_memories = true407# use_memories = true

409# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search408# disable_on_external_context = false # legacy alias: no_memories_if_mcp_or_web_search

410 409 

410################################################################################

411# Lifecycle hooks can be configured here inline or in a sibling hooks.json.

412################################################################################

413 

414# [hooks]

415# [[hooks.PreToolUse]]

416# matcher = "^Bash$"

417#

418# [[hooks.PreToolUse.hooks]]

419# type = "command"

420# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'

421# timeout = 30

422# statusMessage = "Checking Bash command"

423 

411################################################################################424################################################################################

412# Define MCP servers under this table. Leave empty to disable.425# Define MCP servers under this table. Leave empty to disable.

413################################################################################426################################################################################

139 139 

140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).140Codex Admins can deploy admin-enforced `requirements.toml` policies from the Codex [Policies page](https://chatgpt.com/codex/settings/policies).

141 141 

142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules.142Use this page when you want to apply different local Codex constraints to different groups without distributing device-level files first. The managed policy uses the same `requirements.toml` format described in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), so you can define allowed approval policies, sandbox modes, web search behavior, MCP server allowlists, feature pins, and restrictive command rules. To disable Browser Use, the in-app browser, or Computer Use, see [Disable Codex feature surfaces](https://developers.openai.com/codex/enterprise/managed-configuration#disable-codex-feature-surfaces).

143 143 

144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)144![Codex policies and configurations page](/images/codex/enterprise/policies_and_configurations_page.png)

145 145 

7 7 

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

9 9 

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

11 11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

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

73```73```

74 74 

75### Override sandbox requirements by host

76 

77Use `[[remote_sandbox_config]]` when one managed policy should apply different

78sandbox requirements on different hosts. For example, you can keep a stricter

79default for laptops while allowing workspace writes on matching devboxes or CI

80runners. Host-specific entries currently override `allowed_sandbox_modes` only:

81 

82```toml

83allowed_sandbox_modes = ["read-only"]

84 

85[[remote_sandbox_config]]

86hostname_patterns = ["*.devbox.example.com", "runner-??.ci.example.com"]

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

88```

89 

90Codex compares each `hostname_patterns` entry against the best-effort resolved

91host name. It prefers the fully qualified domain name when available and falls

92back to the local host name. Matching is case-insensitive; `*` matches any

93sequence of characters, and `?` matches one character.

94 

95The first matching `[[remote_sandbox_config]]` entry wins within the same

96requirements source. If no entry matches, Codex keeps the top-level

97`allowed_sandbox_modes`. Hostname matching is for policy selection only; don't

98treat it as authenticated device proof.

99 

75You can also constrain web search mode:100You can also constrain web search mode:

76 101 

77```toml102```toml

91 116 

92Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.117Use the canonical feature keys from `config.toml`'s `[features]` table. Codex normalizes the resulting feature set to meet these pins and rejects conflicting writes to `config.toml` or profile-scoped feature settings.

93 118 

119### Disable Codex feature surfaces

120 

121Admins can use `[feature_requirements]` to disable specific Codex feature

122surfaces for users receiving a managed `requirements.toml`. You can also set

123the same keys in the existing `[features]` table.

124 

125```

126[feature_requirements]

127browser_use = false

128in_app_browser = false

129computer_use = false

130```

131 

132- `in_app_browser = false` disables the in-app browser pane.

133- `browser_use = false` disables Browser Use and Browser Agent availability.

134- `computer_use = false` disables Computer Use availability and related

135 install or enablement flows.

136 

137If omitted, these features are allowed by policy, subject to normal client,

138platform, and rollout availability.

139 

140### Configure automatic review policy

141 

142Use `allowed_approvals_reviewers` to require or allow automatic review. Set it

143to `["auto_review"]` to require automatic review, or include `"user"` when users

144can choose manual approval.

145 

146Set `guardian_policy_config` to replace the tenant-specific section of the

147automatic review policy. Codex still uses the built-in reviewer template and

148output contract. Managed `guardian_policy_config` takes precedence over local

149`[auto_review].policy`.

150 

151```toml

152allowed_approval_policies = ["on-request"]

153allowed_approvals_reviewers = ["auto_review"]

154 

155guardian_policy_config = """

156## Environment Profile

157- Trusted internal destinations include github.com/my-org, artifacts.example.com,

158 and internal CI systems.

159 

160## Tenant Risk Taxonomy and Allow/Deny Rules

161- Treat uploads to unapproved third-party file-sharing services as high risk.

162- Deny actions that expose credentials or private source code to untrusted

163 destinations.

164"""

165```

166 

94### Enforce deny-read requirements167### Enforce deny-read requirements

95 168 

96Admins can deny reads for exact paths or glob patterns with169Admins can deny reads for exact paths or glob patterns with

106```179```

107 180 

108When deny-read requirements are present, Codex constrains local sandbox mode to181When deny-read requirements are present, Codex constrains local sandbox mode to

109`read-only` or `workspace-write` so the requirement can be enforced. On native182`read-only` or `workspace-write` so Codex can enforce them. On native

110Windows, managed `deny_read` applies to direct file tools; shell subprocess183Windows, managed `deny_read` applies to direct file tools; shell subprocess

111reads don’t use this sandbox requirement.184reads don't use this sandbox rule.

185 

186### Enforce managed hooks from requirements

187 

188Admins can also define managed lifecycle hooks directly in `requirements.toml`.

189Use `[hooks]` for the hook configuration itself, and point `managed_dir` at the

190directory where your MDM or endpoint-management tooling installs the referenced

191scripts.

192 

193```toml

194[features]

195codex_hooks = true

196 

197[hooks]

198managed_dir = "/enterprise/hooks"

199windows_managed_dir = 'C:\enterprise\hooks'

200 

201[[hooks.PreToolUse]]

202matcher = "^Bash$"

203 

204[[hooks.PreToolUse.hooks]]

205type = "command"

206command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

207timeout = 30

208statusMessage = "Checking managed Bash command"

209```

210 

211Notes:

212 

213- Codex enforces the hook configuration from `requirements.toml`, but it does

214 not distribute the scripts in `managed_dir`.

215- Deliver those scripts separately with your MDM or device-management solution.

216- Managed hook commands should reference absolute script paths under the

217 configured managed directory.

112 218 

113### Enforce command rules from requirements219### Enforce command rules from requirements

114 220 

1# Hooks1# Hooks

2 2 

3Experimental. Hooks are under active development. Windows support temporarily

4disabled.

5 

6Hooks are an extensibility framework for Codex. They allow3Hooks are an extensibility framework for Codex. They allow

7you to inject your own scripts into the agentic loop, enabling features such as:4you to inject your own scripts into the agentic loop, enabling features such as:

8 5 

23 20 

24- Matching hooks from multiple files all run.21- Matching hooks from multiple files all run.

25- Multiple matching command hooks for the same event are launched concurrently,22- Multiple matching command hooks for the same event are launched concurrently,

26 so one hook can’t prevent another matching hook from starting.23 so one hook cannot prevent another matching hook from starting.

27- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and24- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and

28 `Stop` run at turn scope.25 `Stop` run at turn scope.

29- Hooks are currently disabled on Windows.

30 26 

31## Where Codex looks for hooks27## Where Codex looks for hooks

32 28 

33Codex discovers `hooks.json` next to active config layers.29Codex discovers hooks next to active config layers in either of these forms:

30 

31- `hooks.json`

32- inline `[hooks]` tables inside `config.toml`

34 33 

35In practice, the two most useful locations are:34In practice, the four most useful locations are:

36 35 

37- `~/.codex/hooks.json`36- `~/.codex/hooks.json`

37- `~/.codex/config.toml`

38- `<repo>/.codex/hooks.json`38- `<repo>/.codex/hooks.json`

39- `<repo>/.codex/config.toml`

39 40 

40If more than one `hooks.json` file exists, Codex loads all matching hooks.41If more than one hook source exists, Codex loads all matching hooks.

41Higher-precedence config layers don’t replace lower-precedence hooks.42Higher-precedence config layers do not replace lower-precedence hooks.

43If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

44merges them and warns at startup. Prefer one representation per layer.

45 

46Project-local hooks load only when the project `.codex/` layer is trusted. In

47untrusted projects, Codex still loads user and system hooks from their own

48active config layers.

42 49 

43## Config shape50## Config shape

44 51 

127Notes:134Notes:

128 135 

129- `timeout` is in seconds.136- `timeout` is in seconds.

130- `timeoutSec` is also accepted as an alias.

131- If `timeout` is omitted, Codex uses `600` seconds.137- If `timeout` is omitted, Codex uses `600` seconds.

132- `statusMessage` is optional.138- `statusMessage` is optional.

133- Commands run with the session `cwd` as their working directory.139- Commands run with the session `cwd` as their working directory.

135 relative path such as `.codex/hooks/...`. Codex may be started from a141 relative path such as `.codex/hooks/...`. Codex may be started from a

136 subdirectory, and a git-root-based path keeps the hook location stable.142 subdirectory, and a git-root-based path keeps the hook location stable.

137 143 

144Equivalent inline TOML in `config.toml`:

145 

146```toml

147[features]

148codex_hooks = true

149 

150[[hooks.PreToolUse]]

151matcher = "^Bash$"

152 

153[[hooks.PreToolUse.hooks]]

154type = "command"

155command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'

156timeout = 30

157statusMessage = "Checking Bash command"

158 

159[[hooks.PostToolUse]]

160matcher = "^Bash$"

161 

162[[hooks.PostToolUse.hooks]]

163type = "command"

164command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'

165timeout = 30

166statusMessage = "Reviewing Bash output"

167```

168 

169## Managed hooks from `requirements.toml`

170 

171Enterprise-managed requirements can also define hooks inline under `[hooks]`.

172This is useful when admins want to enforce the hook configuration while

173delivering the actual scripts through MDM or another device-management system.

174 

175```toml

176[features]

177codex_hooks = true

178 

179[hooks]

180managed_dir = "/enterprise/hooks"

181windows_managed_dir = 'C:\enterprise\hooks'

182 

183[[hooks.PreToolUse]]

184matcher = "^Bash$"

185 

186[[hooks.PreToolUse.hooks]]

187type = "command"

188command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

189timeout = 30

190statusMessage = "Checking managed Bash command"

191```

192 

193Notes for managed hooks:

194 

195- `managed_dir` is used on macOS and Linux.

196- `windows_managed_dir` is used on Windows.

197- Codex does not distribute the scripts in `managed_dir`; your enterprise

198 tooling must install and update them separately.

199- Managed hook commands should use absolute script paths under the configured

200 managed directory.

201 

138## Matcher patterns202## Matcher patterns

139 203 

140The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,204The `matcher` field is a regex string that filters when hooks fire. Use `"*"`,

145 209 

146| Event | What `matcher` filters | Notes |210| Event | What `matcher` filters | Notes |

147| --- | --- | --- |211| --- | --- | --- |

148| `PermissionRequest` | tool name | Current Codex runtime only emits `Bash`. |212| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

149| `PostToolUse` | tool name | Current Codex runtime only emits `Bash`. |213| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

150| `PreToolUse` | tool name | Current Codex runtime only emits `Bash`. |214| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

151| `SessionStart` | start source | Current runtime values are `startup` and `resume`. |215| `SessionStart` | start source | Current runtime values are `startup`, `resume`, and `clear` |

152| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event. |216| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

153| `Stop` | not supported | Any configured `matcher` is ignored for this event. |217| `Stop` | not supported | Any configured `matcher` is ignored for this event |

218 

219\*For `apply_patch`, matchers can also use `Edit` or `Write`.

154 220 

155Examples:221Examples:

156 222 

157- `Bash`223- `Bash`

158- `startup|resume`224- `^apply_patch$`

159- `Edit|Write`225- `Edit|Write`

160 226- `mcp__filesystem__read_file`

161That last example is still a valid regex, but current Codex `PreToolUse` and227- `mcp__filesystem__.*`

162`PostToolUse` events only emit `Bash`, so it won’t match anything today.228- `startup|resume|clear`

163 229 

164## Common input fields230## Common input fields

165 231 

238 304 

239### PreToolUse305### PreToolUse

240 306 

241Work in progress307`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

242 308and MCP tool calls. It is still a guardrail rather than a complete enforcement

243Currently `PreToolUse` only supports Bash tool interception. The model can309boundary because Codex can often perform equivalent work through another

244still work around this by writing its own script to disk and then running that310supported tool path.

245script with Bash, so treat this as a useful guardrail rather than a complete

246enforcement boundary

247 311 

248This doesn't intercept all shell calls yet, only the simple ones. The newer312This doesn't intercept all shell calls yet, only the simple ones. The newer

249 `unified_exec` mechanism allows richer streaming stdin/stdout handling of313 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

250shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,314 shell, but interception is incomplete. Similarly, this doesn't intercept

251Write, WebSearch, or other non-shell tool calls.315 `WebSearch` or other non-shell, non-MCP tool calls.

252 316 

253`matcher` is applied to `tool_name`, which currently always equals `Bash`.317`matcher` is applied to `tool_name` and matcher aliases. For file edits through

318`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

319still reports `tool_name: "apply_patch"`.

254 320 

255Fields in addition to [Common input fields](#common-input-fields):321Fields in addition to [Common input fields](#common-input-fields):

256 322 

257| Field | Type | Meaning |323| Field | Type | Meaning |

258| --- | --- | --- |324| --- | --- | --- |

259| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |325| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

260| `tool_name` | `string` | Currently always `Bash` |326| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

261| `tool_use_id` | `string` | Tool-call id for this invocation |327| `tool_use_id` | `string` | Tool-call id for this invocation |

262| `tool_input.command` | `string` | Shell command Codex is about to run |328| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

263 329 

264Plain text on `stdout` is ignored.330Plain text on `stdout` is ignored.

265 331 

293 359 

294### PermissionRequest360### PermissionRequest

295 361 

296Work in progress

297 

298`PermissionRequest` runs when Codex is about to ask for approval, such as a362`PermissionRequest` runs when Codex is about to ask for approval, such as a

299shell escalation or managed-network approval. It can allow the request, deny363shell escalation or managed-network approval. It can allow the request, deny

300the request, or decline to decide and let the normal approval prompt continue.364the request, or decline to decide and let the normal approval prompt continue.

301It doesn't run for commands that don't need approval.365It doesn't run for commands that don't need approval.

302 366 

303`matcher` is applied to `tool_name`, which currently always equals `Bash`.367`matcher` is applied to `tool_name` and matcher aliases. Current canonical

368values include `Bash`, `apply_patch`, and MCP tool names such as

369`mcp__server__tool`; `apply_patch` also matches `Edit` and `Write`.

304 370 

305Fields in addition to [Common input fields](#common-input-fields):371Fields in addition to [Common input fields](#common-input-fields):

306 372 

307| Field | Type | Meaning |373| Field | Type | Meaning |

308| --- | --- | --- |374| --- | --- | --- |

309| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |375| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

310| `tool_name` | `string` | Currently always `Bash` |376| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

311| `tool_input.command` | `string` | Shell command associated with the approval request |377| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

312| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |378| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |

313 379 

314Plain text on `stdout` is ignored.380Plain text on `stdout` is ignored.

350 416 

351### PostToolUse417### PostToolUse

352 418 

353Work in progress419`PostToolUse` runs after supported tools produce output, including Bash,

354 420`apply_patch`, and MCP tool calls. For Bash, it also runs after commands that

355Currently `PostToolUse` only supports Bash tool results. It’s not limited to421exit with a non-zero status. It can't undo side effects from the tool that

356commands that exit successfully: non-interactive `exec_command` calls can still422already ran.

357trigger `PostToolUse` when Codex emits a Bash post-tool payload. It can’t undo

358side effects from the command that already ran.

359 423 

360This doesn't intercept all shell calls yet, only the simple ones. The newer424This doesn't intercept all shell calls yet, only the simple ones. The newer

361 `unified_exec` mechanism allows richer streaming stdin/stdout handling of425 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

362shell, but interception is incomplete. Similarly, this doesn’t intercept MCP,426 shell, but interception is incomplete. Similarly, this doesn't intercept

363Write, WebSearch, or other non-shell tool calls.427 `WebSearch` or other non-shell, non-MCP tool calls.

364 428 

365`matcher` is applied to `tool_name`, which currently always equals `Bash`.429`matcher` is applied to `tool_name` and matcher aliases. For file edits through

430`apply_patch`, matchers can use `apply_patch`, `Edit`, or `Write`; hook input

431still reports `tool_name: "apply_patch"`.

366 432 

367Fields in addition to [Common input fields](#common-input-fields):433Fields in addition to [Common input fields](#common-input-fields):

368 434 

369| Field | Type | Meaning |435| Field | Type | Meaning |

370| --- | --- | --- |436| --- | --- | --- |

371| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |437| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

372| `tool_name` | `string` | Currently always `Bash` |438| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

373| `tool_use_id` | `string` | Tool-call id for this invocation |439| `tool_use_id` | `string` | Tool-call id for this invocation |

374| `tool_input.command` | `string` | Shell command Codex just ran |440| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the args. |

375| `tool_response` | `JSON value` | Bash tool output payload. Today this is usually a JSON string |441| `tool_response` | `JSON value` | Tool-specific output. For MCP tools, this is the MCP call result. |

376 442 

377Plain text on `stdout` is ignored.443Plain text on `stdout` is ignored.

378 444 

16- [Download for Visual Studio Code Insiders](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt)16- [Download for Visual Studio Code Insiders](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt)

17- [Download for JetBrains IDEs](#jetbrains-ide-integration)17- [Download for JetBrains IDEs](#jetbrains-ide-integration)

18 18 

19The Codex VS Code extension is available on macOS and Linux. Windows support19Codex IDE integrations for VS Code-compatible editors and JetBrains IDEs are

20is experimental. For the best Windows experience, use Codex in a WSL220 available on macOS, Windows, and Linux. On Windows, run Codex natively with

21workspace and follow our [Windows setup guide](https://developers.openai.com/codex/windows).21 the Windows sandbox, or use WSL2 when you need a Linux-native environment. For

22setup details, see the [Windows setup guide](https://developers.openai.com/codex/windows).

22 23 

23After you install it, you'll find Codex in your editor sidebar.24After you install it, you'll find Codex in your editor sidebar.

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

24| `chatgpt.commentCodeLensEnabled` | Show CodeLens above to-do comments so you can complete them with Codex. |24| `chatgpt.commentCodeLensEnabled` | Show CodeLens above to-do comments so you can complete them with Codex. |

25| `chatgpt.localeOverride` | Preferred language for the Codex UI. Leave empty to detect automatically. |25| `chatgpt.localeOverride` | Preferred language for the Codex UI. Leave empty to detect automatically. |

26| `chatgpt.openOnStartup` | Focus the Codex sidebar when the extension finishes starting. |26| `chatgpt.openOnStartup` | Focus the Codex sidebar when the extension finishes starting. |

27| `chatgpt.runCodexInWindowsSubsystemForLinux` | Windows only: Run Codex in WSL when Windows Subsystem for Linux (WSL) is available. Recommended for improved sandbox security and better performance. Codex agent mode on Windows currently requires WSL. Changing this setting reloads VS Code to apply the change. |27| `chatgpt.runCodexInWindowsSubsystemForLinux` | Windows only: Run Codex in WSL when Windows Subsystem for Linux (WSL) is available. Use this when your repositories and tooling live in WSL2 or when you need Linux-native tooling. Otherwise, Codex can run natively on Windows with the Windows sandbox. Changing this setting reloads VS Code to apply the change. |

2 2 

3## Recommended models3## Recommended models

4 4 

5![gpt-5.5](/images/api/models/gpt-5.5.jpg)

6 

7gpt-5.5

8 

9OpenAI's newest frontier model for complex coding, computer use, knowledge work, and research workflows in Codex.

10 

11codex -m gpt-5.5

12 

13Copy command

14 

15Capability

16 

17Speed

18 

19Codex CLI & SDK

20 

21Codex app & IDE extension

22 

23Codex Cloud

24 

25ChatGPT Credits

26 

27API Access

28 

5![gpt-5.4](/images/api/models/gpt-5.4.jpg)29![gpt-5.4](/images/api/models/gpt-5.4.jpg)

6 30 

7gpt-5.431gpt-5.4

98 122 

99API Access123API Access

100 124 

101For most tasks in Codex, start with `gpt-5.4`. It combines strong coding,125For most tasks in Codex, start with `gpt-5.5` when it appears in your model

102reasoning, native computer use, and broader professional workflows in one126 picker. It is strongest for complex coding, computer use, knowledge work, and

103model. Use `gpt-5.4-mini` when you want a faster, lower-cost option for127 research workflows. GPT-5.5 is currently available in Codex when you sign in

104lighter coding tasks or subagents. The `gpt-5.3-codex-spark` model is128 with ChatGPT; it isn't available with API-key authentication. During the

105available in research preview for ChatGPT Pro subscribers and is optimized for129 rollout, continue using `gpt-5.4` if `gpt-5.5` is not yet available. Use

106near-instant, real-time coding iteration.130 `gpt-5.4-mini` when you want a faster, lower-cost option for lighter coding

131 tasks or subagents. The `gpt-5.3-codex-spark` model is available in research

132 preview for ChatGPT Pro subscribers and is optimized for near-instant,

133 real-time coding iteration.

107 134 

108## Alternative models135## Alternative models

109 136 

134 161 

135The Codex CLI and IDE extension use the same `config.toml` [configuration file](https://developers.openai.com/codex/config-basic). To specify a model, add a `model` entry to your configuration file. If you don't specify a model, the Codex app, CLI, or IDE Extension defaults to a recommended model.162The Codex CLI and IDE extension use the same `config.toml` [configuration file](https://developers.openai.com/codex/config-basic). To specify a model, add a `model` entry to your configuration file. If you don't specify a model, the Codex app, CLI, or IDE Extension defaults to a recommended model.

136 163 

137```164```toml

138model = "gpt-5.4"165model = "gpt-5.5"

139```166```

140 167 

168If `gpt-5.5` isn't available in your account yet, use `gpt-5.4`.

169 

141### Choosing a different local model temporarily170### Choosing a different local model temporarily

142 171 

143In the Codex CLI, you can use the `/model` command during an active thread to change the model. In the IDE extension, you can use the model selector below the input box to choose your model.172In the Codex CLI, you can use the `/model` command during an active thread to change the model. In the IDE extension, you can use the model selector below the input box to choose your model.

145To start a new Codex CLI thread with a specific model or to specify the model for `codex exec` you can use the `--model`/`-m` flag:174To start a new Codex CLI thread with a specific model or to specify the model for `codex exec` you can use the `--model`/`-m` flag:

146 175 

147```bash176```bash

148codex -m gpt-5.4177codex -m gpt-5.5

149```178```

150 179 

151### Choosing your model for cloud tasks180### Choosing your model for cloud tasks

1# Remote connections1# Remote connections

2 2 

3SSH remote connections are currently in alpha. To enable them today, set3SSH remote connections are currently in alpha. To enable them today, set

4`remote_control = true` in the `[features]` table in `~/.codex/config.toml`.4 `remote_connections = true` in the `[features]` table in

5Availability, setup flows, and supported environments may change as the5 `~/.codex/config.toml`. Availability, setup flows, and supported environments

6feature improves.6 may change as the feature improves.

7 7 

8Remote connections let Codex work with projects that live on another8Remote connections let Codex work with projects that live on another

9SSH-accessible machine. Use them when the codebase, credentials, services, or9SSH-accessible machine. Use them when the codebase, credentials, services, or

48 48 

49```toml49```toml

50[features]50[features]

51remote_control = true51remote_connections = true

52```52```

53 53 

54Remote project threads run commands, read files, and write changes on the54Remote project threads run commands, read files, and write changes on the

6 6 

7## Create a rules file7## Create a rules file

8 8 

91. Create a `.rules` file under `./codex/rules/` (for example, `~/.codex/rules/default.rules`).91. Create a `.rules` file under a `rules/` folder next to an active config layer (for example, `~/.codex/rules/default.rules`).

102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.102. Add a rule. This example prompts before allowing `gh pr view` to run outside the sandbox.

11 11 

12 ```python12 ```python

36 ```36 ```

373. Restart Codex.373. Restart Codex.

38 38 

39Codex scans `rules/` under every [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) location at startup. When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.39Codex scans `rules/` under every active config layer at startup, including [Team Config](https://developers.openai.com/codex/enterprise/admin-setup#team-config) locations and the user layer at `~/.codex/rules/`. Project-local rules under `<repo>/.codex/rules/` load only when the project `.codex/` layer is trusted.

40 

41When you add a command to the allow list in the TUI, Codex writes to the user layer at `~/.codex/rules/default.rules` so future runs can skip the prompt.

40 42 

41When Smart approvals are enabled (the default), Codex may propose a43When Smart approvals are enabled (the default), Codex may propose a

42`prefix_rule` for you during escalation requests. Review the suggested prefix44`prefix_rule` for you during escalation requests. Review the suggested prefix

5Codex offers the ability to increase the speed of the model for increased5Codex offers the ability to increase the speed of the model for increased

6credit consumption.6credit consumption.

7 7 

8Fast mode is currently supported on GPT-5.4. When enabled, speed is increased8Fast mode increases supported model speed by 1.5x and consumes credits at a

9by 1.5x and credits are consumed at a 2x rate.9higher rate than Standard mode. It currently supports GPT-5.5 and GPT-5.4,

10consuming credits at 2.5x the Standard rate for GPT-5.5 and 2x the Standard

11rate for GPT-5.4.

10 12 

11Use `/fast on`, `/fast off`, or `/fast status` in the CLI to change or inspect13Use `/fast on`, `/fast off`, or `/fast status` in the CLI to change or inspect

12the current setting. You can also persist the default with `service_tier = "fast"` plus `[features].fast_mode = true` in `config.toml`. Fast mode is14the current setting. You can also persist the default with `service_tier = "fast"` plus `[features].fast_mode = true` in `config.toml`. Fast mode is

20 22 

21## Codex-Spark23## Codex-Spark

22 24 

23GPT-5.3-Codex-Spark is a separate fast, less-capable Codex model optimized for near-instant, real-time coding iteration. Unlike fast mode, which speeds up GPT-5.4 at a higher credit rate,25GPT-5.3-Codex-Spark is a separate fast, less-capable Codex model optimized for

24Codex-Spark is its own model choice and has its own usage limits.26near-instant, real-time coding iteration. Unlike fast mode, which speeds up a

27supported model at a higher credit rate, Codex-Spark is its own model choice

28and has its own usage limits.

25 29 

26During research preview Codex-Spark is only available for ChatGPT Pro subscribers.30During research preview Codex-Spark is only available for ChatGPT Pro subscribers.