OpenAI - Codex Docs Changes 2026-03-05 06:22 UTC → 2026-03-23 18:22 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).

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

14 

15## Sandbox and approvals

16 

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

18 

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

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

21 

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

23 

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

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

26 

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

28 

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

30 

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

32 

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

34 

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

36 

37For 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:

38 

39```toml

40[sandbox_workspace_write]

41network_access = true

42```

43 

44You 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:

45 

46```toml

47web_search = "cached" # default

48# web_search = "disabled"

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

50```

51 

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

53 

54## Defaults and recommendations

55 

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

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

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

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

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

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

62- You can set these explicitly:

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

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

65 

66### Protected paths in writable roots

67 

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

69 

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

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

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

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

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

75 

76### Run without approval prompts

77 

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

79 

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

81 

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

83 

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

85 

86### Common sandbox and approval combinations

87 

88| Intent | Flags | Effect |

89| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

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

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

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

95 

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

97 

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

99 

100#### Configuration in `config.toml`

101 

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

103 

104```toml

105# Always ask for approval mode

106approval_policy = "untrusted"

107sandbox_mode = "read-only"

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

109 

110# Optional: Allow network in workspace-write mode

111[sandbox_workspace_write]

112network_access = true

113 

114# Optional: granular approval policy

115# approval_policy = { granular = {

116# sandbox_approval = true,

117# rules = true,

118# mcp_elicitations = true,

119# request_permissions = false,

120# skill_approval = false

121# } }

122```

123 

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

125 

126```toml

127[profiles.full_auto]

128approval_policy = "on-request"

129sandbox_mode = "workspace-write"

130 

131[profiles.readonly_quiet]

132approval_policy = "never"

133sandbox_mode = "read-only"

134```

135 

136### Test the sandbox locally

137 

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

139 

140```bash

141# macOS

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

143# Linux

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

145```

146 

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

148 

149## OS-level sandbox

150 

151Codex enforces the sandbox differently depending on your OS:

152 

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

154- **Linux** uses the bubblewrap pipeline plus `seccomp` by default. `use_legacy_landlock` is available when you need the older path. In managed proxy mode, the default bubblewrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes.

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

156 

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

158 

159```json

160{

161 "chatgpt.runCodexInWindowsSubsystemForLinux": true

162}

163```

164 

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

166 

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

168 

169```toml

170[windows]

171sandbox = "unelevated" # or "elevated"

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

173```

174 

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

176 

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

178 

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

180 

181## Version control

182 

183Codex works best with a version control workflow:

184 

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

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

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

188 

189## Monitoring and telemetry

190 

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

192 

193### Overview

194 

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

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

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

198 

199### Enable OTel (opt-in)

200 

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

202 

203```toml

204[otel]

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

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

207log_user_prompt = false # redact prompt text unless policy allows

208```

209 

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

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

212 

213```toml

214[otel]

215exporter = { otlp-http = {

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

217 protocol = "binary",

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

219}}

220```

221 

222```toml

223[otel]

224exporter = { otlp-grpc = {

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

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

227}}

228```

229 

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

231 

232### Event categories

233 

234Representative event types include:

235 

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

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

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

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

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

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

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

243 

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

245 

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

247 

248### Security and privacy guidance

249 

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

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

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

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

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

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

256 

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

258 

259## Managed configuration

260 

261Enterprise 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 

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

22 22 

23```json23```json

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

25```25```

26 26 

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

99 },99 },

100});100});

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

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

103```103```

104 104 

105## Core primitives105## Core primitives

123 123 

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

125 125 

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

127 127 

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

129 129 

159 },159 },

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

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

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

163 "codex/event/session_configured",

164 "item/agentMessage/delta"

165 ]

166 }163 }

167 }164 }

168}165}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

232- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).235- `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.236- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

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

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

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

236 240 

237## Models241## Models

238 242 

244{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }248{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }

245{ "id": 6, "result": {249{ "id": 6, "result": {

246 "data": [{250 "data": [{

247 "id": "gpt-5.2-codex",251 "id": "gpt-5.4",

248 "model": "gpt-5.2-codex",252 "model": "gpt-5.4",

249 "upgrade": "gpt-5.3-codex",253 "displayName": "GPT-5.4",

250 "displayName": "GPT-5.2 Codex",

251 "hidden": false,254 "hidden": false,

252 "defaultReasoningEffort": "medium",255 "defaultReasoningEffort": "medium",

253 "reasoningEffort": [{256 "supportedReasoningEfforts": [{

254 "effort": "low",257 "reasoningEffort": "low",

255 "description": "Lower latency"258 "description": "Lower latency"

256 }],259 }],

257 "inputModalities": ["text", "image"],260 "inputModalities": ["text", "image"],

264 267 

265Each model entry can include:268Each model entry can include:

266 269 

267- `reasoningEffort` - supported effort options for the model.270- `supportedReasoningEfforts` - supported effort options for the model.

268- `defaultReasoningEffort` - suggested default effort for clients.271- `defaultReasoningEffort` - suggested default effort for clients.

269- `upgrade` - optional recommended upgrade model id for migration prompts in clients.272- `upgrade` - optional recommended upgrade model id for migration prompts in clients.

273- `upgradeInfo` - optional upgrade metadata for migration prompts in clients.

270- `hidden` - whether the model is hidden from the default picker list.274- `hidden` - whether the model is hidden from the default picker list.

271- `inputModalities` - supported input types for the model (for example `text`, `image`).275- `inputModalities` - supported input types for the model (for example `text`, `image`).

272- `supportsPersonality` - whether the model supports personality-specific instructions such as `/personality`.276- `supportsPersonality` - whether the model supports personality-specific instructions such as `/personality`.

315 319 

316```json320```json

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

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

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

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

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

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

571 "networkAccess": true575 "networkAccess": true

572 },576 },

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

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

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

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

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

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

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

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

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

716 722 

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

718 724 

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

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

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

733 "featureRequirements": {

734 "personality": true,

735 "unified_exec": false

736 },

727 "network": {737 "network": {

728 "enabled": true,738 "enabled": true,

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

734} }744} }

735```745```

736 746 

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).747`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 748 

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

740 750 

769 779 

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

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

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

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

774 784 

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

868 878 

869When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.879When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.

870 880 

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

872 882 

873### File change approvals883### File change approvals

874 884 

2 2 

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

4 4 

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

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

7 7 

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

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

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

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

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

11project directory.13project directory.

12 14 

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

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

17 

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

14 19 

15## Managing tasks20## Managing tasks

16 21 

18 23 

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

20 25 

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

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

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

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

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

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

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

22 33 

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

24 35 

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

31 42 

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

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

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

35 46 

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

38 49 

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

40 51 

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

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

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

44 55 

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

46 57 

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

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

50 50 

51## Deeplinks

52 

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

54 

55| Deeplink | Opens | Supported query parameters |

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

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

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

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

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

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

62 

63For new-thread deeplinks:

64 

65- `prompt` prefills the composer.

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

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

68 

51## See also69## See also

52 70 

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

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)

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

86 86 

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

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

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

90failed build while it works with you.

89 91 

90Common tasks include:92Common tasks include:

91 93 

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

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

164 166 

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

168configuration details, see the

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

166 170 

167## MCP support171## MCP support

168 172 

175 179 

176Codex ships with a first-party web search tool. For local tasks in the Codex IDE Extension, Codex180Codex 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 your181enables 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. See182sandbox 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 the183[Config basics](https://developers.openai.com/codex/config-basic) to disable web search or switch to live results that fetch the

180most recent data.184most recent data.

181 185 

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

11thread runs.11thread runs.

12 12 

13## Appearance

14 

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

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

17 

18## Notifications13## Notifications

19 14 

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

24 19 

25Codex agents in the app inherit the same configuration as the IDE and CLI extension.20Codex 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 advanced21Use the in-app controls for common settings, or edit `config.toml` for advanced

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

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

29 24 

25## Appearance

26 

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

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

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

30 

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

32 

30## Git33## Git

31 34 

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

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

93 

94## Login diagnostics

95 

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

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

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

99 

100## Custom CA bundles

101 

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

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

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

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

106connections.

107 

108```shell

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

110codex login

111```

89 112 

90## Login on headless devices113## Login on headless devices

91 114 

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

142```165```

143 166 

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

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

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

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

171default for automation.

172 

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

145 174 

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`).175If 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

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

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

5 5 

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

7 7 

8## CLI setup8## CLI setup

9 9 

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

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

49 49 

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

51 

50---52---

51 53 

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

55 57 

56Run `codex` to start an interactive terminal UI (TUI) session.](https://developers.openai.com/codex/cli/features#running-in-interactive-mode)[### Control model and reasoning58Run `codex` to start an interactive terminal UI (TUI) session.](https://developers.openai.com/codex/cli/features#running-in-interactive-mode)[### Control model and reasoning

57 59 

58Use `/model` to switch between GPT-5.3-Codex and other available models, or adjust reasoning levels.](https://developers.openai.com/codex/cli/features#models-reasoning)[### Image inputs60Use `/model` to switch between GPT-5.4, GPT-5.3-Codex, and other available models, or adjust reasoning levels.](https://developers.openai.com/codex/cli/features#models-reasoning)[### Image inputs

59 61 

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

61 63 

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

63 65 

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

65 67 

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

67 69 

20 20 

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

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

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

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

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

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

46 46 

47## Models and reasoning47## Models and reasoning

48 48 

49For most coding tasks in Codex, `gpt-5.3-codex` is the go-to model. It’s available for ChatGPT-authenticated Codex sessions in the Codex app, CLI, IDE extension, and Codex Cloud. For extra fast tasks, ChatGPT Pro subscribers have access to the GPT-5.3-Codex-Spark model in research preview.49For most tasks in Codex, `gpt-5.4` is the recommended model. It brings the

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

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

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

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

54research preview.

50 55 

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

52 57 

53```bash58```bash

54codex --model gpt-5.3-codex59codex --model gpt-5.4

55```60```

56 61 

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

68 73 

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

70 75 

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

72 77 

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

79 

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

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

82tokens than comparable single-agent runs.

74 83 

75## Image inputs84## Image inputs

76 85 

105 114 

106## Web search115## Web search

107 116 

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.117Codex 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 118 

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

111 120 

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

9 9 

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

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

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

13 13 

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

15 15 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

63 64 

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

65 66 

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

68 

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

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

71 

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

73 

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

67 75 

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

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

93 101 

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

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

96 104 

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

98 106 

22 22 

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

24 24 

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

26 26 

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

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/community/codex-for-oss)

1# Codex for Open Source Program Terms

2 

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

4 

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.

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

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

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

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

11 11 

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

13 13 

19 19 

20- Build and test commands20- Build and test commands

21- Review expectations21- Review expectations

22- Repo-specific conventions22- repo-specific conventions

23- Directory-specific instructions23- Directory-specific instructions

24 24 

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

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

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

46 46 

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

48 48 

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

50 50 

87 87 

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

89 89 

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

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

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

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

94 94 

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

105## MCP105## MCP

106 106 

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

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

109 109 

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

111 111 

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

113 113 

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

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

129 129 

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

131 131 

132## Multi-agents132## Subagents

133 133 

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

135 135 

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

137 137 

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

139 139 

146 146 

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

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

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

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

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

1# Subagents

2 

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

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

5 

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

7 

8## Why subagent workflows help

9 

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

11 

12This is often described as:

13 

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

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

16 

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

18 

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

20 

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

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

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

24 

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

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

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

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

29thread.

30 

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

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

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

34conflicts and increase coordination overhead.

35 

36## Core terms

37 

38Codex uses a few related terms in subagent workflows:

39 

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

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

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

43 

44## Triggering subagent workflows

45 

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

47explicitly ask for subagents or parallel agent work.

48 

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

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

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

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

53 

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

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

56return.

57 

58```text

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

60```

61 

62## Choosing models and reasoning

63 

64Different agents need different model and reasoning settings.

65 

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

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

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

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

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

71the agent file.

72 

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

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

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

76remains available in research preview.

77 

78### Model choice

79 

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

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

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

83 

84### Reasoning effort (`model_reasoning_effort`)

85 

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

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

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

89 

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

2 2 

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

4 4 

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

6 6 

7## Profiles7## Profiles

8 8 

45 45 

46```shell46```shell

47# Dedicated flag47# Dedicated flag

48codex --model gpt-5.248codex --model gpt-5.4

49 49 

50# Generic key/value override (value is TOML, not JSON)50# Generic key/value override (value is TOML, not JSON)

51codex --config model='"gpt-5.2"'51codex --config model='"gpt-5.4"'

52codex --config sandbox_workspace_write.network_access=true52codex --config sandbox_workspace_write.network_access=true

53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'53codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

54```54```

74 74 

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

76 76 

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

78 78 

79```toml79```toml

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

81codex

82```81```

83 82 

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

87 86 

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

89 88 

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

91 90 

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

93 92 

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

95 94 

96## Project root detection95## Project root detection

97 96 

190 189 

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

192 191 

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

194 193 

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