OpenAI - Codex Docs Changes 2026-03-05 18:41 UTC → 2026-03-11 00:31 UTC

1# Agent approvals & security

2 

3Codex helps protect your code and data and reduces the risk of misuse.

4 

5This page covers how to operate Codex safely, including sandboxing, approvals,

6 and network access. If you are looking for Codex Security, the product for

7 scanning connected GitHub repositories, see [Codex Security](https://developers.openai.com/codex/security).

8 

9By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

10 

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

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

13 

14## Sandbox and approvals

15 

16Codex security controls come from two layers that work together:

17 

18- **Sandbox mode**: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.

19- **Approval policy**: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).

20 

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

22 

23- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

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

25 

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

27 

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

29 

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

31 

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

33 

34For Codex cloud, see [agent internet access](https://developers.openai.com/codex/cloud/internet-access) to enable full internet access or a domain allow list.

35 

36For the Codex app, CLI, or IDE Extension, the default `workspace-write` sandbox mode keeps network access turned off unless you enable it in your configuration:

37 

38```toml

39[sandbox_workspace_write]

40network_access = true

41```

42 

43You can also control the [web search tool](https://platform.openai.com/docs/guides/tools-web-search) without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](#common-sandbox-and-approval-combinations), web search defaults to live results. Use `--search` or set `web_search = "live"` to allow live browsing, or set it to `"disabled"` to turn the tool off:

44 

45```toml

46web_search = "cached" # default

47# web_search = "disabled"

48# web_search = "live" # same as --search

49```

50 

51Use caution when enabling network access or web search in Codex. Prompt injection can cause the agent to fetch and follow untrusted instructions.

52 

53## Defaults and recommendations

54 

55- On launch, Codex detects whether the folder is version-controlled and recommends:

56 - Version-controlled folders: `Auto` (workspace write + on-request approvals)

57 - Non-version-controlled folders: `read-only`

58- Depending on your setup, Codex may also start in `read-only` until you explicitly trust the working directory (for example, via an onboarding prompt or `/permissions`).

59- The workspace includes the current directory and temporary directories like `/tmp`. Use the `/status` command to see which directories are in the workspace.

60- To accept the defaults, run `codex`.

61- You can set these explicitly:

62 - `codex --sandbox workspace-write --ask-for-approval on-request`

63 - `codex --sandbox read-only --ask-for-approval on-request`

64 

65### Protected paths in writable roots

66 

67In the default `workspace-write` sandbox policy, writable roots still include protected paths:

68 

69- `<writable_root>/.git` is protected as read-only whether it appears as a directory or file.

70- If `<writable_root>/.git` is a pointer file (`gitdir: ...`), the resolved Git directory path is also protected as read-only.

71- `<writable_root>/.agents` is protected as read-only when it exists as a directory.

72- `<writable_root>/.codex` is protected as read-only when it exists as a directory.

73- Protection is recursive, so everything under those paths is read-only.

74 

75### Run without approval prompts

76 

77You can disable approval prompts with `--ask-for-approval never` or `-a never` (shorthand).

78 

79This option works with all `--sandbox` modes, so you still control Codex's level of autonomy. Codex makes a best effort within the constraints you set.

80 

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

82 

83For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.

84 

85### Common sandbox and approval combinations

86 

87| Intent | Flags | Effect |

88| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

89| Auto (preset) | *no flags needed* or `--full-auto` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

90| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |

91| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` | Codex can only read files; never asks for approval. |

92| Automatically edit but ask for approval to run untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` | Codex can read and edit files but asks for approval before running untrusted commands. |

93| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`) | [Elevated Risk](https://help.openai.com/articles/20001061) No sandbox; no approvals *(not recommended)* |

94 

95`--full-auto` is a convenience alias for `--sandbox workspace-write --ask-for-approval on-request`.

96 

97With `--ask-for-approval untrusted`, Codex runs only known-safe read operations automatically. Commands that can mutate state or trigger external execution paths (for example, destructive Git operations or Git output/config-override flags) require approval.

98 

99#### Configuration in `config.toml`

100 

101For the broader configuration workflow, see [Config basics](https://developers.openai.com/codex/config-basic), [Advanced Config](https://developers.openai.com/codex/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://developers.openai.com/codex/config-reference).

102 

103```toml

104# Always ask for approval mode

105approval_policy = "untrusted"

106sandbox_mode = "read-only"

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

108 

109# Optional: Allow network in workspace-write mode

110[sandbox_workspace_write]

111network_access = true

112 

113# Optional: granular approval prompt auto-rejection

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

115```

116 

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

118 

119```toml

120[profiles.full_auto]

121approval_policy = "on-request"

122sandbox_mode = "workspace-write"

123 

124[profiles.readonly_quiet]

125approval_policy = "never"

126sandbox_mode = "read-only"

127```

128 

129### Test the sandbox locally

130 

131To see what happens when a command runs under the Codex sandbox, use these Codex CLI commands:

132 

133```bash

134# macOS

135codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

136# Linux

137codex sandbox linux [--full-auto] [COMMAND]...

138```

139 

140The `sandbox` command is also available as `codex debug`, and the platform helpers have aliases (for example `codex sandbox seatbelt` and `codex sandbox landlock`).

141 

142## OS-level sandbox

143 

144Codex enforces the sandbox differently depending on your OS:

145 

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

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

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

149 

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

151 

152```json

153{

154 "chatgpt.runCodexInWindowsSubsystemForLinux": true

155}

156```

157 

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

159 

160When running natively on Windows, configure the native sandbox mode in `config.toml`:

161 

162```toml

163[windows]

164sandbox = "unelevated" # or "elevated"

165```

166 

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

168 

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

170 

171In that case, configure your Docker container to provide the isolation you need, then run `codex` with `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag) inside the container.

172 

173## Version control

174 

175Codex works best with a version control workflow:

176 

177- Work on a feature branch and keep `git status` clean before delegating. This keeps Codex patches easier to isolate and revert.

178- Prefer patch-based workflows (for example, `git diff`/`git apply`) over editing tracked files directly. Commit frequently so you can roll back in small increments.

179- Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

180 

181## Monitoring and telemetry

182 

183Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

184 

185### Overview

186 

187- Codex turns off OTel export by default to keep local runs self-contained.

188- When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.

189- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

190 

191### Enable OTel (opt-in)

192 

193Add an `[otel]` block to your Codex configuration (typically `~/.codex/config.toml`), choosing an exporter and whether to log prompt text.

194 

195```toml

196[otel]

197environment = "staging" # dev | staging | prod

198exporter = "none" # none | otlp-http | otlp-grpc

199log_user_prompt = false # redact prompt text unless policy allows

200```

201 

202- `exporter = "none"` leaves instrumentation active but doesn't send data anywhere.

203- To send events to your own collector, pick one of:

204 

205```toml

206[otel]

207exporter = { otlp-http = {

208 endpoint = "https://otel.example.com/v1/logs",

209 protocol = "binary",

210 headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }

211}}

212```

213 

214```toml

215[otel]

216exporter = { otlp-grpc = {

217 endpoint = "https://otel.example.com:4317",

218 headers = { "x-otlp-meta" = "abc123" }

219}}

220```

221 

222Codex batches events and flushes them on shutdown. Codex exports only telemetry produced by its OTel module.

223 

224### Event categories

225 

226Representative event types include:

227 

228- `codex.conversation_starts` (model, reasoning settings, sandbox/approval policy)

229- `codex.api_request` (attempt, status/success, duration, and error details)

230- `codex.sse_event` (stream event kind, success/failure, duration, plus token counts on `response.completed`)

231- `codex.websocket_request` and `codex.websocket_event` (request duration plus per-message kind/success/error)

232- `codex.user_prompt` (length; content redacted unless explicitly enabled)

233- `codex.tool_decision` (approved/denied, source: configuration vs. user)

234- `codex.tool_result` (duration, success, output snippet)

235 

236Associated OTel metrics (counter plus duration histogram pairs) include `codex.api_request`, `codex.sse_event`, `codex.websocket.request`, `codex.websocket.event`, and `codex.tool.call` (with corresponding `.duration_ms` instruments).

237 

238For the full event catalog and configuration reference, see the [Codex configuration documentation on GitHub](https://github.com/openai/codex/blob/main/docs/config.md#otel).

239 

240### Security and privacy guidance

241 

242- Keep `log_user_prompt = false` unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.

243- Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.

244- Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.

245- Review local data retention settings (for example, `history.persistence` / `history.max_bytes`) if you don't want Codex to save session transcripts under `CODEX_HOME`. See [Advanced Config](https://developers.openai.com/codex/config-advanced#history-persistence) and [Configuration Reference](https://developers.openai.com/codex/config-reference).

246- If you run the CLI with network access turned off, OTel export can't reach your collector. To export, allow network access in `workspace-write` mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.

247- Review events periodically for approval/sandbox changes and unexpected tool executions.

248 

249OTel is optional and designed to complement, not replace, the sandbox and approval protections described above.

250 

251## Managed configuration

252 

253Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.

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

42 42 

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

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

44 45 

45---46---

46 47 

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

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

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

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

236 236 

237## Models237## Models

238 238 

724 "requirements": {724 "requirements": {

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

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

727 "featureRequirements": {

728 "personality": true,

729 "unified_exec": false

730 },

727 "network": {731 "network": {

728 "enabled": true,732 "enabled": true,

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

734} }738} }

735```739```

736 740 

737`result.requirements` is `null` when no requirements are configured. When present, the optional `network` object carries managed proxy constraints (domain rules, proxy settings, and unix-socket policy).741`result.requirements` is `null` when no requirements are configured. See the docs on [`requirements.toml`](https://developers.openai.com/codex/config-reference#requirementstoml) for details on supported keys and values.

738 742 

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

740 744 

14session in a specific directory.14session in a specific directory.

15 15 

16If you work in a single repository with two or more apps or packages, split16If you work in a single repository with two or more apps or packages, split

17distinct projects into separate app projects so the [sandbox](https://developers.openai.com/codex/security)17distinct projects into separate app projects so the [sandbox](https://developers.openai.com/codex/agent-approvals-security)

18only includes the files for that project.18only includes the files for that project.

19 19 

20![Codex app showing multiple projects in the sidebar and threads in the main pane](/images/codex/app/multitask-light.webp)20![Codex app showing multiple projects in the sidebar and threads in the main pane](/images/codex/app/multitask-light.webp)

162opening separate projects or using worktrees rather than asking Codex to roam162opening separate projects or using worktrees rather than asking Codex to roam

163outside the project root.163outside the project root.

164 164 

165For details on how Codex handles sandboxing, check out the [security documentation](https://developers.openai.com/codex/security).165For a high-level overview, see [Sandboxing](https://developers.openai.com/codex/concepts/sandboxing). For

166configuration details, see the

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

166 168 

167## MCP support169## MCP support

168 170 

175 177 

176Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex178Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex

177enables web search by default and serves results from a web search cache. If you configure your179enables web search by default and serves results from a web search cache. If you configure your

178sandbox for [full access](https://developers.openai.com/codex/security), web search defaults to live results. See180sandbox for [full access](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. See

179[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the181[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the

180most recent data.182most recent data.

181 183 

24 24 

25Codex agents in the app inherit the same configuration as the IDE and CLI extension.25Codex agents in the app inherit the same configuration as the IDE and CLI extension.

26Use the in-app controls for common settings, or edit `config.toml` for advanced26Use the in-app controls for common settings, or edit `config.toml` for advanced

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

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

29 29 

30## Git30## Git

25the Microsoft Store UI, run:25the Microsoft Store UI, run:

26 26 

27```powershell27```powershell

28winget install --id 9PLM9XGG6VKS28winget install Codex -s msstore

29```29```

30 30 

31## Native sandbox

32 

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

34 

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

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

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

38 targeted exceptions, or set your [approval policy to

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

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

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

42 

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

32 44 

33### Preferred editor45### Preferred editor

26 26 

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

28 28 

29Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Do not expose Codex execution in untrusted or publicly triggerable environments.29Features that rely on ChatGPT credits, such as [fast mode](https://developers.openai.com/codex/speed), are

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

31Codex uses standard API pricing instead.

32 

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

30 34 

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

32 36 

85 89 

86If the active credentials don't match the configured restrictions, Codex logs the user out and exits.90If the active credentials don't match the configured restrictions, Codex logs the user out and exits.

87 91 

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

89 93 

90## Login on headless devices94## Login on headless devices

91 95 

141docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"145docker cp ~/.codex/auth.json MY_CONTAINER:"$CONTAINER_HOME/.codex/auth.json"

142```146```

143 147 

148For a more advanced version of this same pattern on trusted CI/CD runners, see

149[Maintain Codex account auth in CI/CD (advanced)](https://developers.openai.com/codex/auth/ci-cd-auth).

150That guide explains how to let Codex refresh `auth.json` during normal runs and

151then keep the updated file for the next job. API keys are still the recommended

152default for automation.

153 

144### Fallback: Forward the localhost callback over SSH154### Fallback: Forward the localhost callback over SSH

145 155 

146If you can forward ports between your local machine and the remote host, you can use the standard browser-based flow by tunneling Codex's local callback server (default `localhost:1455`).156If you can forward ports between your local machine and the remote host, you can use the standard browser-based flow by tunneling Codex's local callback server (default `localhost:1455`).

1# Maintain Codex account auth in CI/CD (advanced)

2 

3This guide shows how to keep ChatGPT-managed Codex auth working on a trusted

4CI/CD runner without calling the OAuth token endpoint yourself.

5 

6The right way to authenticate automation is with an API key. Use this guide

7only if you specifically need to run the workflow as your Codex account.

8 

9The pattern is:

10 

111. Create `auth.json` once on a trusted machine with `codex login`.

122. Put that file on the runner.

133. Run Codex normally.

144. Let Codex refresh the session when it becomes stale.

155. Keep the refreshed `auth.json` for the next run.

16 

17This is an advanced workflow for enterprise and other trusted private

18automation. API keys are still the recommended option for most CI/CD jobs.

19 

20Treat `~/.codex/auth.json` like a password: it contains access tokens. Don't

21 commit it, paste it into tickets, or share it in chat. Do not use this

22 workflow for public or open-source repositories.

23 

24## Why this works

25 

26Codex already knows how to refresh a ChatGPT-managed session.

27 

28As of the current open-source client:

29 

30- Codex loads the local auth cache from `auth.json`

31- if `last_refresh` is older than about 8 days, Codex refreshes the token

32 bundle before the run continues

33- after a successful refresh, Codex writes the new tokens and a new

34 `last_refresh` back to `auth.json`

35- if a request gets a `401`, Codex also has a built-in refresh-and-retry path

36 

37That means the supported CI/CD strategy is not "call the refresh API yourself."

38It is "run Codex and persist the updated `auth.json`."

39 

40## When to use this

41 

42Use this guide only when all of the following are true:

43 

44- you need ChatGPT-managed Codex auth rather than an API key

45- `codex login` cannot run on the remote runner

46- the runner is trusted private infrastructure

47- you can preserve the refreshed `auth.json` between runs

48- only one machine or serialized job stream will use a given `auth.json` copy

49 

50This guide applies to Codex-managed ChatGPT auth (`auth_mode: "chatgpt"`).

51 

52It does not apply to:

53 

54- API key auth

55- external-token host integrations (`auth_mode: "chatgptAuthTokens"`)

56- generic OAuth clients outside Codex

57 

58If your credentials are stored in the OS keyring, switch to file-backed storage

59first. See [Credential storage](https://developers.openai.com/codex/auth#credential-storage).

60 

61## Seed `auth.json` once

62 

63On a trusted machine where browser login is possible:

64 

651. Configure Codex to store credentials in a file:

66 

67```toml

68cli_auth_credentials_store = "file"

69```

70 

712. Run:

72 

73```bash

74codex login

75```

76 

773. Verify the file looks like managed ChatGPT auth:

78 

79```bash

80AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

81 

82jq '{

83 auth_mode,

84 has_tokens: (.tokens != null),

85 has_refresh_token: ((.tokens.refresh_token // "") != ""),

86 last_refresh

87}' "$AUTH_FILE"

88```

89 

90Continue only if:

91 

92- `auth_mode` is `"chatgpt"`

93- `has_refresh_token` is `true`

94 

95Then place the contents of `auth.json` into your CI/CD secret manager or copy

96it to a trusted persistent runner.

97 

98## Recommended pattern: GitHub Actions on a self-hosted runner

99 

100The simplest fully automated setup is a self-hosted GitHub Actions runner with a

101persistent `CODEX_HOME`.

102 

103Why this pattern works well:

104 

105- the runner can keep `auth.json` on disk between jobs

106- Codex can refresh the file in place

107- later jobs automatically pick up the refreshed tokens

108- you only need the original secret for bootstrap or reseeding

109 

110The critical detail is to seed `auth.json` only if it is missing. If you

111rewrite the file from the original secret on every run, you throw away the

112refreshed tokens that Codex just wrote.

113 

114Example scheduled workflow:

115 

116```yaml

117name: Keep Codex auth fresh

118 

119on:

120 schedule:

121 - cron: "0 9 * * 1"

122 workflow_dispatch:

123 

124jobs:

125 keep-codex-auth-fresh:

126 runs-on: self-hosted

127 steps:

128 - name: Bootstrap auth.json if needed

129 shell: bash

130 env:

131 CODEX_AUTH_JSON: ${{ secrets.CODEX_AUTH_JSON }}

132 run: |

133 export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

134 mkdir -p "$CODEX_HOME"

135 chmod 700 "$CODEX_HOME"

136 

137 if [ ! -f "$CODEX_HOME/auth.json" ]; then

138 printf '%s' "$CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"

139 chmod 600 "$CODEX_HOME/auth.json"

140 fi

141 

142 - name: Run Codex

143 shell: bash

144 run: |

145 codex exec --json "Reply with the single word OK." >/dev/null

146```

147 

148What this does:

149 

150- the first run seeds `auth.json`

151- later runs reuse the same file

152- once the cached session is old enough, Codex refreshes it during the normal

153 `codex exec` step

154- the refreshed file remains on disk for the next workflow run

155 

156A weekly schedule is usually enough because Codex treats the session as stale

157after roughly 8 days in the current open-source client.

158 

159## Ephemeral runners: restore, run Codex, persist the updated file

160 

161If you use GitHub-hosted runners, GitLab shared runners, or any other ephemeral

162environment, the runner filesystem disappears after each job. In that setup,

163you need a round-trip:

164 

1651. restore the current `auth.json` from secure storage

1662. run Codex

1673. write the updated `auth.json` back to secure storage

168 

169Generic GitHub Actions shape:

170 

171```yaml

172name: Run Codex with managed auth

173 

174on:

175 workflow_dispatch:

176 

177jobs:

178 codex-job:

179 runs-on: ubuntu-latest

180 steps:

181 - name: Restore auth.json

182 shell: bash

183 run: |

184 export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

185 mkdir -p "$CODEX_HOME"

186 chmod 700 "$CODEX_HOME"

187 

188 # Replace this with your secret manager or secure storage command.

189 my-secret-cli read codex-auth-json > "$CODEX_HOME/auth.json"

190 chmod 600 "$CODEX_HOME/auth.json"

191 

192 - name: Run Codex

193 shell: bash

194 run: |

195 codex exec --json "summarize the failing tests"

196 

197 - name: Persist refreshed auth.json

198 if: always()

199 shell: bash

200 run: |

201 # Replace this with your secret manager or secure storage command.

202 my-secret-cli write codex-auth-json < "$CODEX_HOME/auth.json"

203```

204 

205The key requirement is that the write-back step stores the refreshed file that

206Codex produced during the run, not the original seed.

207 

208## You do not need a separate refresh command

209 

210Any normal Codex run can refresh the session.

211 

212That means you have two good options:

213 

214- let your existing CI/CD Codex job refresh the file naturally

215- add a lightweight scheduled maintenance job, like the GitHub Actions example

216 above, if your real jobs do not run often enough

217 

218The first Codex run after the session becomes stale is the one that refreshes

219`auth.json`.

220 

221## Operational rules that matter

222 

223- Use one `auth.json` per runner or per serialized workflow stream.

224- Do not share the same file across concurrent jobs or multiple machines.

225- Do not overwrite a persistent runner's refreshed file from the original seed

226 on every run.

227- Do not store `auth.json` in the repository, logs, or public artifact storage.

228- Reseed from a trusted machine if built-in refresh stops working.

229 

230## What to do when refresh stops working

231 

232This flow reduces manual work, but it does not guarantee the same session lasts

233forever.

234 

235Reseed the runner with a fresh `auth.json` if:

236 

237- Codex starts returning `401` and the runner can no longer refresh

238- the refresh token was revoked or expired

239- another machine or concurrent job rotated the token first

240- your secure-storage round trip failed and an old file was restored

241 

242To reseed:

243 

2441. Run `codex login` on a trusted machine.

2452. Replace the stored CI/CD copy of `auth.json`.

2463. Let the next runner job continue using Codex's built-in refresh flow.

247 

248## Verify that the runner is maintaining the session

249 

250Check that the runner still has managed auth tokens and that `last_refresh`

251exists:

252 

253```bash

254AUTH_FILE="${CODEX_HOME:-$HOME/.codex}/auth.json"

255 

256jq '{

257 auth_mode,

258 last_refresh,

259 has_access_token: ((.tokens.access_token // "") != ""),

260 has_id_token: ((.tokens.id_token // "") != ""),

261 has_refresh_token: ((.tokens.refresh_token // "") != "")

262}' "$AUTH_FILE"

263```

264 

265If your runner is persistent, you should see the same file continue to exist

266between runs. If your runner is ephemeral, confirm that your write-back step is

267storing the updated file from the last job.

268 

269## Source references

270 

271If you want to verify this behavior in the open-source client:

272 

273- [`codex-rs/core/src/auth.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/auth.rs)

274 covers stale-token detection, automatic refresh, refresh-on-401 recovery, and

275 persistence of refreshed tokens

276- [`codex-rs/core/src/auth/storage.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/auth/storage.rs)

277 covers file-backed `auth.json` storage

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

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

49 49 

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

51 

50---52---

51 53 

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

105 105 

106## Web search106## Web search

107 107 

108Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.108Codex ships with a first-party web search tool. For local tasks in the Codex CLI, Codex enables web search by default and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/agent-approvals-security), web search defaults to live results. To fetch the most recent data, pass `--search` for a single run or set `web_search = "live"` in [Config basics](https://developers.openai.com/codex/config-basic). You can also set `web_search = "disabled"` to turn the tool off.

109 109 

110You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.110You'll see `web_search` items in the transcript or `codex exec --json` output whenever Codex looks something up.

111 111 

24 24 

25Explore Codex Ambassadors and upcoming community meetups by location.25Explore Codex Ambassadors and upcoming community meetups by location.

26 26 

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

28 

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

30 

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

1# Codex for Open Source Program Terms

2 

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

4 

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

6 

7## 1. Program Overview

8 

9The Program is designed to support maintainers of important open-source software. Approved applicants may receive one or more of the following benefits, as determined by OpenAI in its sole discretion: (i) a limited-duration ChatGPT Pro benefit that includes Codex access; (ii) API credits for eligible open-source maintainer workflows; and (iii) conditional access to Codex Security for qualified repositories or maintainers. Availability, duration, scope, and timing of any benefit may vary by applicant, repository, or use case.

10 

11## 2. Eligibility and Applications

12 

13To be considered for the Program, applicants must have a valid ChatGPT account and provide accurate and complete information about themselves, their repositories, and their role in maintaining or administering those repositories. OpenAI may consider factors such as repository usage, ecosystem importance, evidence of active maintenance, role or permissions, and Program capacity. Submission of an application does not guarantee selection, funding, or access.

14 

15## 3. Selection and Verification

16 

17OpenAI may approve or deny applications in its sole discretion. OpenAI may request additional information to verify identity, repository affiliation, maintainer status, or repository control, and may condition any benefit on successful verification. OpenAI's decisions are final.

18 

19## 4. Benefits

20 

21Unless OpenAI states otherwise in writing, Program benefits are personal, limited, non-transferable, and have no cash value. Program benefits may not be sold, assigned, sublicensed, exchanged, or shared. If OpenAI provides a redemption code, invitation, or activation flow, the recipient must follow the applicable redemption instructions and any additional redemption terms communicated by OpenAI. Benefits may expire if they are not redeemed or activated within the period specified by OpenAI.

22 

23## 5. Additional Conditions for Codex Security and API Credits

24 

25Codex Security access and API credits are optional, additional Program benefits and may require separate review, additional eligibility checks, and/or additional terms. OpenAI may limit Codex Security access to repositories that the applicant owns, maintains, or is otherwise authorized to administer.

26 

27Applicants may not use the Program, including Codex Security, to scan, probe, test, or review repositories, systems, or codebases that they do not own or lack permission to review. OpenAI may require proof of control or authorization before granting or continuing such access and may limit or revoke access at any time if authorization is unclear or no longer valid.

28 

29## 6. Fraud, Abuse, and Revocation

30 

31OpenAI may reject, suspend, or revoke any Program benefit for any reason in its sole discretion, including without limitation if it reasonably believes that an applicant or recipient: (i) provided false, misleading, or incomplete information; (ii) used multiple identities or accounts to obtain more than one benefit; (iii) transferred, resold, or shared a benefit; (iv) violated OpenAI's terms or policies; (v) used the Program in a harmful, abusive, fraudulent, or unauthorized manner; or (vi) otherwise created legal, security, reputational, or operational risk for OpenAI or others.

32 

33## 7. Submission Similarity; No Exclusivity; No Confidentiality

34 

35The applicant acknowledges that OpenAI may currently or in the future develop, receive, review, fund, support, or work with ideas, projects, repositories, workflows, or proposals that are similar or identical to the applicant's submission. Nothing in these Program Terms prevents OpenAI from independently developing, funding, or supporting any such similar or identical work.

36 

37The applicant further acknowledges that OpenAI assumes no obligation of exclusivity with respect to any submission and that any decision to select, fund, or support a project or maintainer is made in OpenAI's sole discretion.

38 

39Except as described in OpenAI's privacy policy or as required by law, applicants should not submit confidential information in connection with the Program, and OpenAI has no duty to treat application materials as confidential.

40 

41## 8. Program Changes

42 

43OpenAI may modify, pause, limit, or discontinue the Program, its eligibility criteria, or any Program benefit at any time. OpenAI may also update these Program Terms from time to time. Continued participation in the Program after an update constitutes acceptance of the revised Program Terms.

44 

45## 9. Taxes and Local Restrictions

46 

47Recipients are responsible for any taxes, reporting obligations, or local legal requirements that may apply to receipt or use of Program benefits. The Program is void where prohibited or restricted by law.

1# Codex for Open Source

2 

3Open-source maintainers do critical work, often behind the scenes, to keep the software ecosystem healthy. Over the past year, the Codex Open Source Fund ($1 million) has supported projects that need API credits, including teams using Codex to power GitHub pull request workflows. OpenAI is grateful to the maintainers who keep that work moving.

4 

5The fund now supports eligible maintainers by offering six months of ChatGPT Pro with Codex and conditional access to Codex Security for core maintainers with write access. Developers should code in the tools they prefer, whether that’s Codex, [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), [OpenClaw](https://github.com/openclaw/openclaw), or something else, and this program supports that work.

6 

7## What the program includes

8 

9- Six months of ChatGPT Pro with Codex for day-to-day coding, triage, review, and maintainer workflows

10- Conditional access to Codex Security for repositories that need deeper security coverage

11- API credits through the Codex Open Source Fund for projects that use Codex in pull request review, maintainer automation, release workflows, or other core OSS work

12 

13Given GPT-5.4’s capabilities, the team reviews Codex Security access case by case to ensure these workflows get the care and diligence they require.

14 

15If you’re a core maintainer or run a widely used public project, apply. If your project doesn’t fit the criteria but it plays an important role in the ecosystem, apply anyway and explain why.

16 

17By submitting an application, you agree to the [Codex for Open Source Program Terms](https://developers.openai.com/codex/codex-for-oss-terms).

18 

19[Apply today!](https://openai.com/form/codex-for-oss/)

1# Sandboxing – Codex

2 

3Sandboxing is the boundary that lets Codex act autonomously without giving it

4unrestricted access to your machine. When Codex runs local commands in the

5**Codex app**, **IDE extension**, or **CLI**, those commands run inside a

6constrained environment instead of running with full access by default.

7 

8That environment defines what Codex can do on its own, such as which files it

9can modify and whether commands can use the network. When a task stays inside

10those boundaries, Codex can keep moving without stopping for confirmation. When

11it needs to go beyond them, Codex falls back to the approval flow.

12 

13Sandboxing and approvals are different controls that work together. The

14 sandbox defines technical boundaries. The approval policy decides when Codex

15 must stop and ask before crossing them.

16 

17## What the sandbox does

18 

19The sandbox applies to spawned commands, not just to Codex's built-in file

20operations. If Codex runs tools like `git`, package managers, or test runners,

21those commands inherit the same sandbox boundaries.

22 

23Codex uses platform-native enforcement on each OS. The implementation differs

24between macOS, Linux, WSL, and native Windows, but the idea is the same across

25surfaces: give the agent a bounded place to work so routine tasks can run

26autonomously inside clear limits.

27 

28## Why it matters

29 

30Sandboxing reduces approval fatigue. Instead of asking you to confirm every

31low-risk command, Codex can read files, make edits, and run routine project

32commands within the boundary you already approved.

33 

34It also gives you a clearer trust model for agentic work. You are not just

35trusting the agent's intentions; you are trusting that the agent is operating

36inside enforced limits. That makes it easier to let Codex work independently

37while still knowing when it will stop and ask for help.

38 

39## How you control it

40 

41Most people start with the permissions controls in the product.

42 

43In the Codex app and IDE, you choose a mode from the permissions selector under

44the composer or chat input. That selector lets you rely on Codex's default

45permissions, switch to full access, or use your custom configuration.

46 

47![Codex app permissions selector showing Default permissions, Full access, and Custom (config.toml)](/images/codex/app/permissions-selector-light.webp)

48 

49In the CLI, use [`/permissions`](https://developers.openai.com/codex/cli/slash-commands#update-permissions-with-permissions)

50to switch modes during a session.

51 

52## Configure defaults

53 

54If you want Codex to start with the same behavior every time, use a custom

55configuration. Codex stores those defaults in `config.toml`, its local settings

56file. [Config basics](https://developers.openai.com/codex/config-basic) explains how it works, and the

57[Configuration reference](https://developers.openai.com/codex/config-reference) documents the exact keys for

58`sandbox_mode`, `approval_policy`, and

59`sandbox_workspace_write.writable_roots`. Use those settings to decide how much

60autonomy Codex gets by default, which directories it can write to, and when it

61should pause for approval.

62 

63At a high level, the common sandbox modes are:

64 

65- `read-only`: Codex can inspect files, but it cannot edit files or run

66 commands without approval.

67- `workspace-write`: Codex can read files, edit within the workspace, and run

68 routine local commands inside that boundary. This is the default low-friction

69 mode for local work.

70- `danger-full-access`: Codex runs without sandbox restrictions. This removes

71 the filesystem and network boundaries and should be used only when you want

72 Codex to act with full access.

73 

74The common approval policies are:

75 

76- `untrusted`: Codex asks before running commands that are not in its trusted

77 set.

78- `on-request`: Codex works inside the sandbox by default and asks when it

79 needs to go beyond that boundary.

80- `never`: Codex does not stop for approval prompts.

81 

82Full access means using `sandbox_mode = "danger-full-access"` together with

83`approval_policy = "never"`. By contrast, `--full-auto` is the lower-risk local

84automation preset: `sandbox_mode = "workspace-write"` and

85`approval_policy = "on-request"`.

86 

87If you need Codex to work across more than one directory, writable roots let

88you extend the places it can modify without removing the sandbox entirely. If

89you need a broader or narrower trust boundary, adjust the default sandbox mode

90and approval policy instead of relying on ad hoc exceptions.

91 

92When a workflow needs a specific exception, use [rules](https://developers.openai.com/codex/rules). Rules

93let you allow, prompt, or forbid command prefixes outside the sandbox, which is

94often a better fit than broadly expanding access. For a higher-level overview

95of approvals and sandbox behavior in the app, see

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

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

98 

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

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

101requirements and organization-level constraints on sandboxing and approvals, see

102[Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security).

190 190 

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

192 192 

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

194 194 

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

196 196 

206network_access = false # Opt in to outbound network206network_access = false # Opt in to outbound network

207```207```

208 208 

209Need 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/security#managed-configuration).209Need 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).

210 210 

211In workspace-write mode, some environments keep `.git/` and `.codex/`211In workspace-write mode, some environments keep `.git/` and `.codex/`

212 read-only even when the rest of the workspace is writable. This is why212 read-only even when the rest of the workspace is writable. This is why

302| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |302| `codex.tool.call` | counter | `tool`, `success` | Tool invocation count by tool name and success/failure. |

303| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |303| `codex.tool.call.duration_ms` | histogram | `tool`, `success` | Tool execution duration in milliseconds by tool name and outcome. |

304 304 

305For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/security#monitoring-and-telemetry).305For more security and privacy guidance around telemetry, see [Security](https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry).

306 306 

307### Metrics307### Metrics

308 308 

11The CLI and IDE extension share the same configuration layers. You can use them to:11The CLI and IDE extension share the same configuration layers. You can use them to:

12 12 

13- Set the default model and provider.13- Set the default model and provider.

14- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/security#sandbox-and-approvals).14- Configure [approval policies and sandbox settings](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals).

15- Configure [MCP servers](https://developers.openai.com/codex/mcp).15- Configure [MCP servers](https://developers.openai.com/codex/mcp).

16 16 

17## Configuration precedence17## Configuration precedence

34On managed machines, your organization may also enforce constraints via34On managed machines, your organization may also enforce constraints via

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

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

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

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

39 39 

40## Common configuration options40## Common configuration options

57approval_policy = "on-request"57approval_policy = "on-request"

58```58```

59 59 

60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations).60For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations).

61 61 

62#### Sandbox level62#### Sandbox level

63 63 

67sandbox_mode = "workspace-write"67sandbox_mode = "workspace-write"

68```68```

69 69 

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

71 71 

72#### Windows sandbox mode72#### Windows sandbox mode

73 73 

81 81 

82#### Web search mode82#### Web search mode

83 83 

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

85 85 

86- `"cached"` (default) serves results from the web search cache.86- `"cached"` (default) serves results from the web search cache.

87- `"live"` fetches the most recent data from the web (same as `--search`).87- `"live"` fetches the most recent data from the web (same as `--search`).

147 147 

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

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

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

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

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

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

6 6 

7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.7User-level configuration lives in `~/.codex/config.toml`. You can also add project-scoped overrides in `.codex/config.toml` files. Codex loads project-scoped config files only when you trust the project.

8 8 

9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).

10 10 

11| Key | Type / Values | Details |11| Key | Type / Values | Details |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

52| `features.request_rule` | `boolean` | Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default). |61| `features.remote_models` | `boolean` | Legacy toggle for an older remote-model readiness flow. Current builds do not use it. |

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

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

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

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

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

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

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

57| `features.unified_exec` | `boolean` | Use the unified PTY-backed exec tool (beta). |69| `features.skill_env_var_dependency_prompt` | `boolean` | Prompt for missing skill environment-variable dependencies (under development). |

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

71| `features.sqlite` | `boolean` | Enable SQLite-backed state persistence (stable; on by default). |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

162| `permissions.network.allowed_domains` | `array<string>` | Allowlist of domains permitted through the managed proxy. |

163| `permissions.network.dangerously_allow_all_unix_sockets` | `boolean` | Allow the proxy to use arbitrary Unix sockets instead of the default restricted set. |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

206 250 

207Key251Key

208 252 

253`agents.<name>.nickname_candidates`

254 

255Type / Values

256 

257`array<string>`

258 

259Details

260 

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

262 

263Key

264 

209`agents.job_max_runtime_seconds`265`agents.job_max_runtime_seconds`

210 266 

211Type / Values267Type / Values

238 294 

239Details295Details

240 296 

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

242 298 

243Key299Key

244 300 

254 310 

255Key311Key

256 312 

313`analytics.enabled`

314 

315Type / Values

316 

317`boolean`

318 

319Details

320 

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

322 

323Key

324 

257`approval_policy`325`approval_policy`

258 326 

259Type / Values327Type / Values

470 538 

471Key539Key

472 540 

541`commit_attribution`

542 

543Type / Values

544 

545`string`

546 

547Details

548 

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

550 

551Key

552 

473`compact_prompt`553`compact_prompt`

474 554 

475Type / Values555Type / Values

518 598 

519Key599Key

520 600 

521`experimental_use_freeform_apply_patch`601`experimental_use_unified_exec_tool`

522 602 

523Type / Values603Type / Values

524 604 

526 606 

527Details607Details

528 608 

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

530 610 

531Key611Key

532 612 

533`experimental_use_unified_exec_tool`613`features.apps`

534 614 

535Type / Values615Type / Values

536 616 

538 618 

539Details619Details

540 620 

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

542 622 

543Key623Key

544 624 

545`features.apply_patch_freeform`625`features.apps_mcp_gateway`

546 626 

547Type / Values627Type / Values

548 628 

550 630 

551Details631Details

552 632 

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

554 634 

555Key635Key

556 636 

557`features.apps`637`features.artifact`

558 638 

559Type / Values639Type / Values

560 640 

562 642 

563Details643Details

564 644 

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

566 646 

567Key647Key

568 648 

569`features.apps_mcp_gateway`649`features.child_agents_md`

570 650 

571Type / Values651Type / Values

572 652 

574 654 

575Details655Details

576 656 

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

578 658 

579Key659Key

580 660 

581`features.child_agents_md`661`features.collaboration_modes`

582 662 

583Type / Values663Type / Values

584 664 

586 666 

587Details667Details

588 668 

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

590 670 

591Key671Key

592 672 

593`features.collaboration_modes`673`features.default_mode_request_user_input`

594 674 

595Type / Values675Type / Values

596 676 

598 678 

599Details679Details

600 680 

601Enable collaboration modes such as plan mode (stable; on by default).681Allow `request_user_input` in default collaboration mode (under development; off by default).

682 

683Key

684 

685`features.elevated_windows_sandbox`

686 

687Type / Values

688 

689`boolean`

690 

691Details

692 

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

694 

695Key

696 

697`features.enable_request_compression`

698 

699Type / Values

700 

701`boolean`

702 

703Details

704 

705Compress streaming request bodies with zstd when supported (stable; on by default).

706 

707Key

708 

709`features.experimental_windows_sandbox`

710 

711Type / Values

712 

713`boolean`

714 

715Details

716 

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

718 

719Key

720 

721`features.fast_mode`

722 

723Type / Values

724 

725`boolean`

726 

727Details

728 

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

730 

731Key

732 

733`features.image_detail_original`

734 

735Type / Values

736 

737`boolean`

738 

739Details

740 

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

742 

743Key

744 

745`features.image_generation`

746 

747Type / Values

748 

749`boolean`

750 

751Details

752 

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

602 754 

603Key755Key

604 756 

634 786 

635Details787Details

636 788 

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

790 

791Key

792 

793`features.prevent_idle_sleep`

794 

795Type / Values

796 

797`boolean`

798 

799Details

800 

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

638 802 

639Key803Key

640 804 

646 810 

647Details811Details

648 812 

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

650 814 

651Key815Key

652 816 

658 822 

659Details823Details

660 824 

661Enable Smart approvals (`prefix_rule` suggestions on escalation requests; stable; on by default).825Legacy toggle for Smart approvals. Current builds include this behavior by default, so most users can leave this unset.

826 

827Key

828 

829`features.responses_websockets`

830 

831Type / Values

832 

833`boolean`

834 

835Details

836 

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

838 

839Key

840 

841`features.responses_websockets_v2`

842 

843Type / Values

844 

845`boolean`

846 

847Details

848 

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

662 850 

663Key851Key

664 852 

682 870 

683Details871Details

684 872 

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

686 874 

687Key875Key

688 876 

694 882 

695Details883Details

696 884 

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

698 886 

699Key887Key

700 888 

710 898 

711Key899Key

712 900 

901`features.skill_env_var_dependency_prompt`

902 

903Type / Values

904 

905`boolean`

906 

907Details

908 

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

910 

911Key

912 

913`features.skill_mcp_dependency_install`

914 

915Type / Values

916 

917`boolean`

918 

919Details

920 

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

922 

923Key

924 

925`features.sqlite`

926 

927Type / Values

928 

929`boolean`

930 

931Details

932 

933Enable SQLite-backed state persistence (stable; on by default).

934 

935Key

936 

937`features.steer`

938 

939Type / Values

940 

941`boolean`

942 

943Details

944 

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

946 

947Key

948 

949`features.undo`

950 

951Type / Values

952 

953`boolean`

954 

955Details

956 

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

958 

959Key

960 

713`features.unified_exec`961`features.unified_exec`

714 962 

715Type / Values963Type / Values

718 966 

719Details967Details

720 968 

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

722 970 

723Key971Key

724 972 

854 1102 

855Key1103Key

856 1104 

857`include_apply_patch_tool`

858 

859Type / Values

860 

861`boolean`

862 

863Details

864 

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

866 

867Key

868 

869`instructions`1105`instructions`

870 1106 

871Type / Values1107Type / Values

1058 1294 

1059Key1295Key

1060 1296 

1297`mcp_servers.<id>.oauth_resource`

1298 

1299Type / Values

1300 

1301`string`

1302 

1303Details

1304 

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

1306 

1307Key

1308 

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

1062 1310 

1063Type / Values1311Type / Values

1070 1318 

1071Key1319Key

1072 1320 

1321`mcp_servers.<id>.scopes`

1322 

1323Type / Values

1324 

1325`array<string>`

1326 

1327Details

1328 

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

1330 

1331Key

1332 

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

1074 1334 

1075Type / Values1335Type / Values

1334 1594 

1335Key1595Key

1336 1596 

1597`model_providers.<id>.supports_websockets`

1598 

1599Type / Values

1600 

1601`boolean`

1602 

1603Details

1604 

1605Whether that provider supports the Responses API WebSocket transport.

1606 

1607Key

1608 

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

1338 1610 

1339Type / Values1611Type / Values

1340 1612 

1341`chat | responses`1613`responses`

1342 1614 

1343Details1615Details

1344 1616 

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

1346 1618 

1347Key1619Key

1348 1620 

1390 1662 

1391Details1663Details