Documentation — Spybara

agent-approvals-security.md +2 −32

Details

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

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

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

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

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

298 299

299### Run without approval prompts300### Run without approval prompts

365| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |366| Auto-review mode | `--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"` | Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user. |

367 368

368For non-interactive runs, use `codex exec --sandbox workspace-write`; Codex keeps older `codex exec --full-auto` invocations as a deprecated compatibility path and prints a warning.369For non-interactive runs, use `codex exec --sandbox workspace-write`.

369 370

370#### Configuration in `config.toml`371#### Configuration in `config.toml`

371 372

455 456

456If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.457If your host cannot run the Linux sandbox directly, or if your organization already standardizes on containerized development, run Codex with Dev Containers and let Docker provide the outer isolation boundary. This works with Visual Studio Code Dev Containers and compatible tools.

457 458

458Use the [Codex secure devcontainer example](https://github.com/openai/codex/tree/main/.devcontainer) as a reference implementation. The example installs Codex, common development tools, `bubblewrap`, and firewall-based outbound controls.

~~459~~

460Devcontainers provide substantial protection, but they do not prevent every459Devcontainers provide substantial protection, but they do not prevent every

461 attack. If you run Codex with `--sandbox danger-full-access` or460 attack. If you run Codex with `--sandbox danger-full-access` or

462 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious461 `--dangerously-bypass-approvals-and-sandbox` inside the container, a malicious

464 Codex credentials. Use this pattern only with trusted repositories, and463 Codex credentials. Use this pattern only with trusted repositories, and

465 monitor Codex activity as you would in any other elevated environment.464 monitor Codex activity as you would in any other elevated environment.

466 465

467The reference implementation includes:

~~468~~

469- an Ubuntu 24.04 base image with Codex and common development tools installed;

470- an allowlist-driven firewall profile for outbound access;

471- VS Code settings and extension recommendations for reopening the workspace in a container;

472- persistent mounts for command history and Codex configuration;

473- `bubblewrap`, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

~~474~~

475To try it:

~~476~~

4771. Install Visual Studio Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

4782. Copy the Codex example `.devcontainer` setup into your repository, or start from the Codex repository directly.

4793. In VS Code, run `Dev Containers: Open Folder in Container...` and select `.devcontainer/devcontainer.secure.json`.

4804. After the container starts, open a terminal and run `codex`.

~~481~~

482You can also start the container from the CLI:

~~483~~

484```bash

485devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

486```

~~487~~

488The example has three main pieces:

~~489~~

490- `.devcontainer/devcontainer.secure.json` controls container settings, capabilities, mounts, environment variables, and VS Code extensions.

491- `.devcontainer/Dockerfile.secure` defines the Ubuntu-based image and installed tools.

492- `.devcontainer/init-firewall.sh` applies the outbound network policy.

~~493~~

494The reference firewall is intentionally a starting point. If you depend on domain allowlisting for isolation, implement DNS rebinding and DNS refresh protections that fit your environment, such as TTL-aware refreshes or a DNS-aware firewall.

~~495~~

496Inside the container, choose one of these modes:466Inside the container, choose one of these modes:

497 467

498- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.468- Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for `bwrap` to create the inner sandbox.

agent-configuration/subagents.md +41 −25

Details

54 54

55Ask Codex in an interactive CLI session to use subagents. Codex can also follow55Ask Codex in an interactive CLI session to use subagents. Codex can also follow

56applicable `AGENTS.md` or skill instructions that request delegation. Use56applicable `AGENTS.md` or skill instructions that request delegation. Use

~~57`/agent` to inspect and switch between agent threads while they run. The main~~57`/subagents` to inspect and switch between agent threads while they run. The main

58thread collects the subagent results into its final response.58thread collects the subagent results into its final response.

59 59

60</ContentModeSwitch>60</ContentModeSwitch>

262 262

263<ContentModeSwitch group="codex-surface" id="cli">263<ContentModeSwitch group="codex-surface" id="cli">

264 264

265- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.265- Use `/subagents` in the CLI to switch between active agent threads and inspect the ongoing thread.

266- Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.266- Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.

267 267

268</ContentModeSwitch>268</ContentModeSwitch>

311action that needs new approval fails and Codex surfaces the error back to the311action that needs new approval fails and Codex surfaces the error back to the

312parent workflow.312parent workflow.

313 313

314Codex also reapplies the parent turn's live runtime overrides when it spawns a314Subagents inherit the parent turn's current sandbox and approval settings,

315child. That includes sandbox and approval choices you set interactively during315including changes made with `/permissions` or `--yolo`. A custom agent file

316the session, such as `/permissions` changes or `--yolo`, even if the selected316can't replace those settings.

317custom agent file sets different defaults.

318 317

319</ContentModeSwitch>318</ContentModeSwitch>

320 319

327 326

328<ContentModeSwitch group="codex-surface" ids="app,cli,ide">327<ContentModeSwitch group="codex-surface" ids="app,cli,ide">

329 328

330You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.329Set sandbox and approval controls on the parent session. Custom agent

330instructions can ask an agent to avoid edits, but they don't create a separate

331read-only sandbox.

331 332

332## Custom agents333## Custom agents

333 334

341`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped342`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped

342agents.343agents.

343 344

344Each file defines one custom agent. Codex loads these files as configuration345Each file defines one custom agent. Custom agents can change model settings and

345layers for spawned sessions, so custom agents can override the same settings as346instructions or disable supported capabilities. They inherit the parent's

346a normal Codex session config. That can feel heavier than a dedicated agent347permissions, provider, and MCP servers; a custom agent file can't override those

347manifest, and the format may evolve as authoring and sharing mature.348settings.

348 349

349Every standalone custom agent file must define:350Every standalone custom agent file must define:

350 351

360that model's default effort. A custom agent file that sets only `model`361that model's default effort. A custom agent file that sets only `model`

361preserves this previously resolved effort. Set `model_reasoning_effort` in the362preserves this previously resolved effort. Set `model_reasoning_effort` in the

362file too if the selected model doesn't support that effort or you want a363file too if the selected model doesn't support that effort or you want a

363different one. Other session settings, such as `sandbox_mode`, `mcp_servers`,364different one. Skills inherit from the parent, and a custom agent can disable

364and `skills.config`, inherit from the parent when the custom agent file omits365individual skills with `skills.config`.

365them.

366 366

367### Global settings367### Global settings

368 368

394 394

395You can also include other supported `config.toml` keys in a custom agent file, such as `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.395Use `model`, `model_reasoning_effort`, `model_reasoning_summary`, and

396`model_verbosity` to customize model behavior.

397See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for their

398accepted values.

399

400To reduce a custom agent's capabilities, set supported feature keys to `false`:

401`features.shell_tool`, `features.apps`, `features.plugins`,

402`features.memories`, or `features.request_permissions_tool`. Disable individual

403skills with `skills.config` or bundled skills with

404`skills.bundled.enabled = false`. Set `skills.include_instructions = false` to

405omit the automatic skills instructions block. Managed requirements still apply.

406

407Other session settings, including `sandbox_mode`, `approval_policy`,

408`model_provider`, and `mcp_servers`, don't override the parent configuration

409when placed in a custom agent file. The service tier also follows the root

410session's preference. Configure MCP servers in the parent session so the agent

411can use them.

396 412

397Codex identifies the custom agent by its `name` field. Matching the filename to413Codex identifies the custom agent by its `name` field. Matching the filename to

398the agent name is the simplest convention, but the `name` field is the source414the agent name is the simplest convention, but the `name` field is the source

421```toml437```toml

422[agents]438[agents]

423max_concurrent_threads_per_session = 8439max_concurrent_threads_per_session = 8

440

441[mcp_servers.openaiDeveloperDocs]

442url = "https://developers.openai.com/mcp"

424```443```

425 444

426`.codex/agents/pr-explorer.toml`:445`.codex/agents/pr-explorer.toml`:

430description = "Read-only codebase explorer for gathering evidence before changes are proposed."449description = "Read-only codebase explorer for gathering evidence before changes are proposed."

431model = "gpt-6-luna"450model = "gpt-6-luna"

432model_reasoning_effort = "high"451model_reasoning_effort = "high"

433sandbox_mode = "read-only"

434developer_instructions = """452developer_instructions = """

435Stay in exploration mode.453Stay in exploration mode.

454Do not edit files.

436Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.455Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

437Prefer fast search and targeted file reads over broad scans.456Prefer fast search and targeted file reads over broad scans.

438"""457"""

445description = "PR reviewer focused on correctness, security, and missing tests."464description = "PR reviewer focused on correctness, security, and missing tests."

446model = "gpt-6.1-sol"465model = "gpt-6.1-sol"

447model_reasoning_effort = "medium"466model_reasoning_effort = "medium"

448sandbox_mode = "read-only"

449developer_instructions = """467developer_instructions = """

450Review code like an owner.468Review code like an owner.

469Do not edit files.

451Prioritize correctness, security, behavior regressions, and missing test coverage.470Prioritize correctness, security, behavior regressions, and missing test coverage.

452Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.471Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

453"""472"""

461description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."480description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

462model = "gpt-6-luna"481model = "gpt-6-luna"

463model_reasoning_effort = "high"482model_reasoning_effort = "high"

464sandbox_mode = "read-only"

465developer_instructions = """483developer_instructions = """

466Use the docs MCP server to confirm APIs, options, and version-specific behavior.484Use the docs MCP server to confirm APIs, options, and version-specific behavior.

467Return concise answers with links or exact references when available.485Return concise answers with links or exact references when available.

468Do not make code changes.486Do not make code changes.

469"""487"""

470 488

471[mcp_servers.openaiDeveloperDocs]

472url = "https://developers.openai.com/mcp"

473```489```

474 490

475This setup works well for prompts like:491This setup works well for prompts like:

487```toml503```toml

488[agents]504[agents]

489max_concurrent_threads_per_session = 6505max_concurrent_threads_per_session = 6

506

507[mcp_servers.chrome_devtools]

508url = "http://localhost:3000/mcp"

509startup_timeout_sec = 20

490```510```

491 511

492`.codex/agents/code-mapper.toml`:512`.codex/agents/code-mapper.toml`:

496description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."516description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

497model = "gpt-6-luna"517model = "gpt-6-luna"

498model_reasoning_effort = "high"518model_reasoning_effort = "high"

499sandbox_mode = "read-only"

500developer_instructions = """519developer_instructions = """

501Map the code that owns the failing UI flow.520Map the code that owns the failing UI flow.

521Do not edit files.

502Identify entry points, state transitions, and likely files before the worker starts editing.522Identify entry points, state transitions, and likely files before the worker starts editing.

503"""523"""

504```524```

510description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."530description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

511model = "gpt-6.1-sol"531model = "gpt-6.1-sol"

512model_reasoning_effort = "medium"532model_reasoning_effort = "medium"

513sandbox_mode = "workspace-write"

514developer_instructions = """533developer_instructions = """

515Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.534Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

516Use browser tooling for screenshots, console output, and network evidence.535Use browser tooling for screenshots, console output, and network evidence.

517Do not edit application code.536Do not edit application code.

518"""537"""

519[mcp_servers.chrome_devtools]

520url = "http://localhost:3000/mcp"

521startup_timeout_sec = 20

522```538```

523 539

524 540

app-server.md +91 −41

Details

296- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.296- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.

297- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.297- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

298- `thread/fork` - fork a thread into a new thread id by copying stored history. Pass `lastTurnId` to copy history through that turn and omit later turns, or `ephemeral: true` to create an in-memory fork. Emits `thread/started` for the new thread; returned threads include `forkedFromId` when available.298- `thread/fork` - fork a thread into a new thread id by copying stored history. Pass `lastTurnId` to copy history through that turn and omit later turns, or `ephemeral: true` to create an in-memory fork. Emits `thread/started` for the new thread; returned threads include `forkedFromId` when available.

299- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.299- `thread/read` - read stored thread metadata by id without resuming it. Use `thread/turns/list` and `thread/items/list` to load history. Returned `thread` objects include runtime `status`.

300- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filters. Returned `thread` objects include runtime `status`.300- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filters. Returned `thread` objects include runtime `status`.

301- `thread/turns/list` - experimental; page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.301- `thread/turns/list` - page through a stored thread's turn history without resuming it. `itemsView` controls whether turn items are omitted, summarized, or fully loaded.

302- `thread/items/list` - experimental; page through persisted thread items, optionally restricted to one `turnId`. The active thread store must support item pagination.302- `thread/items/list` - page through persisted thread items, optionally restricted to one `turnId`. The active thread store must support item pagination.

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

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

305- `thread/goal/set` - set the goal for a thread; emits `thread/goal/updated`.305- `thread/goal/set` - set the goal for a thread; emits `thread/goal/updated`.

316- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).316- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).

317- `thread/backgroundTerminals/list` - list running background terminals for a loaded thread (experimental; requires `capabilities.experimentalApi`).317- `thread/backgroundTerminals/list` - list running background terminals for a loaded thread (experimental; requires `capabilities.experimentalApi`).

318- `thread/backgroundTerminals/terminate` - terminate one running background terminal by app-server `processId` (experimental; requires `capabilities.experimentalApi`).318- `thread/backgroundTerminals/terminate` - terminate one running background terminal by app-server `processId` (experimental; requires `capabilities.experimentalApi`).

319- `thread/rollback` - deprecated; drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.319- `thread/revert` - remove a specified turn and every later turn from a persistent paginated thread's history; returns updated metadata and history cursors, then emits `thread/reverted`.

320- `turn/start` - add user input or standalone tool output to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."320- `turn/start` - add user input or standalone tool output to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

321- `thread/inject_items` - append raw Responses API items to a loaded thread's model-visible history without starting a user turn.321- `thread/inject_items` - append raw Responses API items to a loaded thread's model-visible history without starting a user turn.

322- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.322- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.

360- `mcpServer/elicitation/request` (server request) - ask the client for structured form input or confirmation of a URL flow requested by an MCP server.360- `mcpServer/elicitation/request` (server request) - ask the client for structured form input or confirmation of a URL flow requested by an MCP server.

361- `item/permissions/requestApproval` (server request) - ask the client to grant a subset of network or filesystem permissions requested by the built-in `request_permissions` tool.361- `item/permissions/requestApproval` (server request) - ask the client to grant a subset of network or filesystem permissions requested by the built-in `request_permissions` tool.

362- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.362- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

363- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources.363- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources. Pass `serverName` to discover one server; with `threadId`, the request reuses that thread's MCP connection.

364- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.364- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.

365- `mcpServer/tool/call` - call a tool on a thread's configured MCP server.365- `mcpServer/tool/call` - call a tool on a thread's configured MCP server.

366- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread.366- `mcpServer/startupStatus/updated` (notify) - emitted when a configured MCP server's startup status changes for a loaded thread.

408 "description": "Balances speed and reasoning depth for everyday tasks"408 "description": "Balances speed and reasoning depth for everyday tasks"

409 }],409 }],

410 "inputModalities": ["text", "image"],410 "inputModalities": ["text", "image"],

411 "supportsPersonality": true,411 "supportsPersonality": false,

412 "isDefault": true412 "isDefault": true

413 }],413 }],

414 "nextCursor": null414 "nextCursor": null

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

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

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

426- `supportsPersonality` - whether the model supports personality-specific instructions such as `/personality`.426- `supportsPersonality` - deprecated compatibility field; always `false`. Models no longer support personality selection.

427- `isDefault` - whether the model is the recommended default.427- `isDefault` - whether the model is the recommended default.

428 428

429By default, `model/list` returns picker-visible models only. Set `includeHidden: true` if you need the full list and want to filter on the client side using `hidden`.429By default, `model/list` returns picker-visible models only. Set `includeHidden: true` if you need the full list and want to filter on the client side using `hidden`.

471 471

472## Threads472## Threads

473 473

474- `thread/read` reads a stored thread without subscribing to it; set `includeTurns` to include turns.474- `thread/read` reads stored thread metadata without subscribing to it.

475- `thread/turns/list` is experimental and pages through a stored thread's turn history without475- `thread/turns/list` pages through a stored thread's turn history without

476 resuming it. Use `itemsView` to choose whether turn items are omitted,476 resuming it. Use `itemsView` to choose whether turn items are omitted,

477 summarized, or fully loaded.477 summarized, or fully loaded.

478- `thread/items/list` is experimental and pages through persisted thread items, optionally restricted to one turn.478- `thread/items/list` pages through persisted thread items, optionally restricted to one turn.

479- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filtering.479- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, `isPinned`, `cwd`, `useStateDbOnly`, `searchTerm`, and experimental `parentThreadId` or `ancestorThreadId` filtering.

480- `thread/loaded/list` returns the thread IDs currently in memory.480- `thread/loaded/list` returns the thread IDs currently in memory.

481- `thread/archive` moves the thread's persisted JSONL log into the archived directory and attempts to archive spawned descendant thread logs that aren't already archived.481- `thread/archive` moves the thread's persisted JSONL log into the archived directory and attempts to archive spawned descendant thread logs that aren't already archived.

484- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.484- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed` after an inactivity grace period.

485- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.485- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.

486- `thread/compact/start` triggers compaction and returns `{}` immediately.486- `thread/compact/start` triggers compaction and returns `{}` immediately.

487- `thread/rollback` is deprecated. It drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.487- `thread/revert` removes a specified turn and every later turn from a persistent paginated thread's history. It doesn't change local files.

488- `thread/inject_items` appends raw Responses API items to a loaded thread's model-visible history without starting a user turn.488- `thread/inject_items` appends raw Responses API items to a loaded thread's model-visible history without starting a user turn.

489 489

490### Start or resume a thread490### Start or resume a thread

497 "cwd": "/Users/me/project",497 "cwd": "/Users/me/project",

498 "approvalPolicy": "never",498 "approvalPolicy": "never",

499 "sandbox": "workspaceWrite",499 "sandbox": "workspaceWrite",

500 "personality": "friendly",

501 "serviceName": "my_app_server_client"500 "serviceName": "my_app_server_client"

502} }501} }

503{ "id": 10, "result": {502{ "id": 10, "result": {

521its source environment's native absolute syntax, including for remote520its source environment's native absolute syntax, including for remote

522environments.521environments.

523 522

524Experimental clients can set `historyMode` on `thread/start` to `"legacy"`523New persistent local threads use paginated history by default. Load history

525(the default) or `"paginated"`. Paginated thread creation isn't supported yet524with `thread/turns/list` and `thread/items/list`. Explicitly setting

526and returns JSON-RPC error `-32601`. App-server can list and read summaries for525`historyMode` to `"legacy"` or `"paginated"` on `thread/start` is

527existing paginated records, but full-history reads, turn pagination, and resume526experimental and requires `capabilities.experimentalApi = true`.

528fail closed until paginated history is supported.

529 527

530Beta clients that opt into `capabilities.experimentalApi` can pass a named528Beta clients that opt into `capabilities.experimentalApi` can pass a named

531permission-profile id in `permissions` instead of the legacy `sandbox` field.529permission-profile id in `permissions` instead of the legacy `sandbox` field.

538of the root they came from. Clients should read the session id from536of the root they came from. Clients should read the session id from

539`thread.sessionId` instead of deriving it from the thread id.537`thread.sessionId` instead of deriving it from the thread id.

540 538

541To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:539To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. Pass `excludeTurns: true` to return thread metadata and live session state, then load history with the pagination methods:

542 540

543```json541```json

544{ "method": "thread/resume", "id": 11, "params": {542{ "method": "thread/resume", "id": 11, "params": {

545 "threadId": "thr_123",543 "threadId": "thr_123",

546 "personality": "friendly"544 "excludeTurns": true

547} }545} }

548{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }546{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

549```547```

550 548

549For paginated threads, full-history responses from `thread/resume` and

550`thread/fork` are deprecated and emit `deprecationNotice`. Both methods accept

551`excludeTurns: true` without the experimental API opt-in. A `thread/resume` response

552can also return `turnsBackwardsCursor` and `itemsBackwardsCursor`. Pass each to

553its matching pagination method with `sortDirection: "desc"`; the first page

554includes the cursor's anchor.

555

551Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.556Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.

552 557

553If you mark an enabled MCP server as `required` in config and that server fails to initialize, `thread/start` and `thread/resume` fail instead of continuing without it.558If you mark an enabled MCP server as `required` in config and that server fails to initialize, `thread/start` and `thread/resume` fail instead of continuing without it.

599turns:604turns:

600 605

601```json606```json

602{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }607{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456", "excludeTurns": true } }

603{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }608{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }

604{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }609{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

605```610```

617 "id": 13,622 "id": 13,

618 "params": {623 "params": {

619 "threadId": "thr_123",624 "threadId": "thr_123",

620 "ephemeral": true625 "ephemeral": true,

626 "excludeTurns": true

621 }627 }

622}628}

623{629{

633}639}

634```640```

635 641

636Ephemeral forks of paginated threads also require `excludeTurns: true`. That642Ephemeral forks of paginated threads require `excludeTurns: true`.

637field is experimental and requires `capabilities.experimentalApi = true`.

638 643

639When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.644When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, and `thread/unarchive` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.

640 645

641### Read a stored thread (without resuming)646### Read a stored thread (without resuming)

642 647

643Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.648Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.

644 649

645- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.650- `includeTurns` - when `false` or omitted, returns the thread summary only. Setting it to `true` loads full history, which is deprecated for paginated threads and emits `deprecationNotice`. Use the pagination methods instead.

646- Returned `thread` objects include runtime `status` (`notLoaded`, `idle`, `systemError`, or `active` with `activeFlags`).651- Returned `thread` objects include runtime `status` (`notLoaded`, `idle`, `systemError`, or `active` with `activeFlags`).

647 652

648```json653```json

649{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }654{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123" } }

650{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }655{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

651```656```

652 657

654 659

655### List thread turns660### List thread turns

656 661

657`thread/turns/list` is experimental. Use it to page a stored thread's turn history without resuming it. Results default to newest-first so clients can fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.662Use `thread/turns/list` to page a stored thread's turn history without resuming it. Results default to newest-first so clients can fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` with the opposite `sortDirection` to reverse direction. This includes the anchor turn again so you can catch updates to it.

658 663

659`itemsView` controls how much turn-item data the response includes:664`itemsView` controls how much turn-item data the response includes:

660 665

676} }681} }

677```682```

678 683

679`thread/items/list` is also experimental. It pages persisted items without684### List thread items

685

686`thread/items/list` pages persisted items without

680resuming the thread. Pass `turnId` to restrict results to one turn, or omit it687resuming the thread. Pass `turnId` to restrict results to one turn, or omit it

681to page items across the thread. The active thread store must support item688to page items across the thread. Results default to oldest-first

682pagination; otherwise, the server returns an unsupported-method error.689(`sortDirection: "asc"`). The active thread store must support item pagination;

690otherwise, the server returns an unsupported-method error.

691

692Pass an opaque `nextCursor` from a previous response to continue paging. To

693start after a known item, pass an item anchor and a non-empty `turnId`:

694

695```json

696{ "method": "thread/items/list", "id": 21, "params": {

697 "threadId": "thr_123",

698 "turnId": "turn_456",

699 "cursor": { "type": "item", "itemId": "item_123" },

700 "sortDirection": "asc",

701 "limit": 50

702} }

703{ "id": 21, "result": {

704 "data": [],

705 "nextCursor": null,

706 "backwardsCursor": null

707} }

708```

709

710Item anchors exclude the anchor itself: ascending order returns newer items,

711and descending order returns older items. The item must belong to the

712requested turn's visible history. Missing `turnId`, an empty item ID, or an

713unknown or out-of-scope item returns invalid params (`-32602`). Continue with

714the returned string `nextCursor`. Each result entry contains `turnId`, `item`,

715and optional recorded start and completion timestamps.

683 716

684### List threads (with pagination & filters)717### List threads (with pagination & filters)

685 718

904{ "id": 29, "result": { "terminated": true } }937{ "id": 29, "result": { "terminated": true } }

905```938```

906 939

907### Roll back recent turns940### Revert thread history

908 941

909`thread/rollback` is deprecated and will be removed. It removes the last942Use `thread/revert` to remove `beforeTurnId` and every later turn from a

910`numTurns` entries from the in-memory context and persists a rollback marker in943persistent paginated thread's conversation history. It doesn't revert local

911the rollout log. The returned `thread` includes `turns` populated after the944file changes. Resume the thread first if it isn't loaded. Ephemeral threads

912rollback.945and threads with legacy history aren't supported.

913 946

914```json947```json

915{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }948{ "method": "thread/revert", "id": 30, "params": { "threadId": "thr_b", "beforeTurnId": "turn_456" } }

916{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }949{ "id": 30, "result": {

950 "thread": { "id": "thr_b", "ephemeral": false, "turns": [] },

951 "turnsBackwardsCursor": "retained-turn-cursor-or-null",

952 "itemsBackwardsCursor": "retained-item-cursor-or-null"

953} }

954{ "method": "thread/reverted", "params": { "threadId": "thr_b" } }

917```955```

918 956

957The returned `thread.turns` is always empty. Use the returned cursors with

958`thread/turns/list` or `thread/items/list` and `sortDirection: "desc"` to load

959retained history, including the cursor's anchor.

960

961`thread/rollback` has been removed and returns an unknown-method error.

962Existing rollback markers in older saved threads remain readable.

963

919## Turns964## Turns

920 965

921The `input` field accepts a list of items:966The `input` field accepts a list of items:

924- `{ "type": "image", "url": "https://.../design.png" }`969- `{ "type": "image", "url": "https://.../design.png" }`

925- `{ "type": "localImage", "path": "/tmp/screenshot.png" }`970- `{ "type": "localImage", "path": "/tmp/screenshot.png" }`

926 971

927You can override configuration settings per turn (model, effort, personality, `cwd`, sandbox policy, summary). When specified, these settings become the defaults for later turns on the same thread. `outputSchema` applies only to the current turn. For `sandboxPolicy.type = "externalSandbox"`, set `networkAccess` to `restricted` or `enabled`; for `workspaceWrite`, `networkAccess` remains a boolean.972You can override configuration settings per turn (model, effort, `cwd`, sandbox policy, summary). When specified, these settings become the defaults for later turns on the same thread. `outputSchema` applies only to the current turn. For `sandboxPolicy.type = "externalSandbox"`, set `networkAccess` to `restricted` or `enabled`; for `workspaceWrite`, `networkAccess` remains a boolean.

928 973

929For `turn/start.collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode" rather than clearing mode instructions.974For `turn/start.collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode" rather than clearing mode instructions.

930 975

1088- `commit` (review a specific commit)1133- `commit` (review a specific commit)

1089- `custom` (free-form instructions)1134- `custom` (free-form instructions)

1090 1135

1091Use `delivery: "inline"` (default) to run the review on the existing thread, or `delivery: "detached"` to fork a new review thread.1136Use `delivery: "inline"` (default) to run the review on the existing thread.

1137For a separate review thread, call `thread/start` and then run an inline

1138review on the new thread.

1092 1139

1093Example request/response:1140Example request/response:

1094 1141

1111} }1158} }

1112```1159```

1113 1160

1114For a detached review, use `"delivery": "detached"`. The response is the same shape, but `reviewThreadId` will be the id of the new review thread (different from the original `threadId`). The server also emits a `thread/started` notification for that new thread before streaming the review turn.1161`delivery: "detached"` is deprecated, emits `deprecationNotice`, and isn't

1162supported for paginated parent threads. If a separate review needs the

1163existing conversation history, use `thread/fork` followed by `turn/start`

1164with your review instructions.

1115 1165

1116Codex streams the usual `turn/started` notification followed by an `item/started` with an `enteredReviewMode` item:1166Codex streams the usual `turn/started` notification followed by an `item/started` with an `enteredReviewMode` item:

1117 1167

1325 1375

1326- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).1376- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).

1327- `functionCallOutput` - `{id, name, namespace, output}` for standalone tool output supplied through `turn/start.toolOutput`. `namespace` can be `null`.1377- `functionCallOutput` - `{id, name, namespace, output}` for standalone tool output supplied through `turn/start.toolOutput`. `namespace` can be `null`.

1328- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).1378- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `partial_answer`, `final_answer`). A `partial_answer` is stable answer text that may be followed by more output or tools.

1329- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.1379- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.

1330- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.1380- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.

1331- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.1381- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.

build-skills.md +5 −2

Details

34Codex start with each skill's name and description, then load the full34Codex start with each skill's name and description, then load the full

35`SKILL.md` instructions when they decide to use that skill.35`SKILL.md` instructions when they decide to use that skill.

36 36

~~37In Codex, the initial list also includes each skill's file path. To avoid~~37In Codex, the initial list also includes each skill's file path. By default,

~~38crowding out the rest of the prompt, this list uses at most 2% of the model's~~38this list uses at most 2% of the model's

39context window, or 8,000 characters when the context window is unknown. If many39context window, or 8,000 characters when the context window is unknown. If many

40skills are installed, Codex shortens skill descriptions first. For large skill40skills are installed, Codex shortens skill descriptions first. For large skill

41sets, Codex may omit some skills from the initial list and show a warning.41sets, Codex may omit some skills from the initial list and show a warning.

42 42

43Use [`skills.max_context_tokens`](https://learn.chatgpt.com/docs/config-file/config-reference) to set a

44different budget, up to 10,000 tokens.

43This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.46This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.

44 47

45A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.48A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.

codex-sdk.md +20 −0

Details

66console.log(result2.finalResponse);66console.log(result2.finalResponse);

67```67```

68 68

69### Configuration overrides

71Pass `config` to set structured Codex configuration. For keys that can't be

72expressed as dotted paths, use `configOverrides` to pass raw TOML strings as

73separate `--config` arguments:

75```ts

76const codex = new Codex({

77 config: { default_permissions: "audit" },

78 configOverrides: [

79 'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',

80 ],

81});

82```

84Raw overrides take precedence over structured `config`. The SDK applies

85managed settings such as `baseUrl` and thread-specific options afterward, so

86they take precedence over both. These overrides don't change your Codex configuration

87files.

69For more details, check out the [TypeScript repo](https://github.com/openai/codex/tree/main/sdk/typescript).89For more details, check out the [TypeScript repo](https://github.com/openai/codex/tree/main/sdk/typescript).

70 90

71## Python library91## Python library

concepts/subagents.md +41 −25

Details

54 54

55Ask Codex in an interactive CLI session to use subagents. Codex can also follow55Ask Codex in an interactive CLI session to use subagents. Codex can also follow

56applicable `AGENTS.md` or skill instructions that request delegation. Use56applicable `AGENTS.md` or skill instructions that request delegation. Use

~~57`/agent` to inspect and switch between agent threads while they run. The main~~57`/subagents` to inspect and switch between agent threads while they run. The main

58thread collects the subagent results into its final response.58thread collects the subagent results into its final response.

59 59

60</ContentModeSwitch>60</ContentModeSwitch>

262 262

263<ContentModeSwitch group="codex-surface" id="cli">263<ContentModeSwitch group="codex-surface" id="cli">

264 264

267 267

268</ContentModeSwitch>268</ContentModeSwitch>

311action that needs new approval fails and Codex surfaces the error back to the311action that needs new approval fails and Codex surfaces the error back to the

312parent workflow.312parent workflow.

313 313

314Codex also reapplies the parent turn's live runtime overrides when it spawns a314Subagents inherit the parent turn's current sandbox and approval settings,

315child. That includes sandbox and approval choices you set interactively during315including changes made with `/permissions` or `--yolo`. A custom agent file

316the session, such as `/permissions` changes or `--yolo`, even if the selected316can't replace those settings.

317custom agent file sets different defaults.

318 317

319</ContentModeSwitch>318</ContentModeSwitch>

320 319

327 326

328<ContentModeSwitch group="codex-surface" ids="app,cli,ide">327<ContentModeSwitch group="codex-surface" ids="app,cli,ide">

329 328

330instructions can ask an agent to avoid edits, but they don't create a separate

331read-only sandbox.

331 332

332## Custom agents333## Custom agents

333 334

341`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped342`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped

342agents.343agents.

343 344

344Each file defines one custom agent. Codex loads these files as configuration345Each file defines one custom agent. Custom agents can change model settings and

345layers for spawned sessions, so custom agents can override the same settings as346instructions or disable supported capabilities. They inherit the parent's

346a normal Codex session config. That can feel heavier than a dedicated agent347permissions, provider, and MCP servers; a custom agent file can't override those

347manifest, and the format may evolve as authoring and sharing mature.348settings.

348 349

349Every standalone custom agent file must define:350Every standalone custom agent file must define:

350 351

360that model's default effort. A custom agent file that sets only `model`361that model's default effort. A custom agent file that sets only `model`

361preserves this previously resolved effort. Set `model_reasoning_effort` in the362preserves this previously resolved effort. Set `model_reasoning_effort` in the

362file too if the selected model doesn't support that effort or you want a363file too if the selected model doesn't support that effort or you want a

363different one. Other session settings, such as `sandbox_mode`, `mcp_servers`,364different one. Skills inherit from the parent, and a custom agent can disable

364and `skills.config`, inherit from the parent when the custom agent file omits365individual skills with `skills.config`.

365them.

366 366

367### Global settings367### Global settings

368 368

394 394

396`model_verbosity` to customize model behavior.

397See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for their

398accepted values.

399

400To reduce a custom agent's capabilities, set supported feature keys to `false`:

401`features.shell_tool`, `features.apps`, `features.plugins`,

402`features.memories`, or `features.request_permissions_tool`. Disable individual

403skills with `skills.config` or bundled skills with

404`skills.bundled.enabled = false`. Set `skills.include_instructions = false` to

405omit the automatic skills instructions block. Managed requirements still apply.

406

407Other session settings, including `sandbox_mode`, `approval_policy`,

408`model_provider`, and `mcp_servers`, don't override the parent configuration

409when placed in a custom agent file. The service tier also follows the root

410session's preference. Configure MCP servers in the parent session so the agent

411can use them.

396 412

397Codex identifies the custom agent by its `name` field. Matching the filename to413Codex identifies the custom agent by its `name` field. Matching the filename to

398the agent name is the simplest convention, but the `name` field is the source414the agent name is the simplest convention, but the `name` field is the source

421```toml437```toml

422[agents]438[agents]

423max_concurrent_threads_per_session = 8439max_concurrent_threads_per_session = 8

440

441[mcp_servers.openaiDeveloperDocs]

442url = "https://developers.openai.com/mcp"

424```443```

425 444

426`.codex/agents/pr-explorer.toml`:445`.codex/agents/pr-explorer.toml`:

431model = "gpt-6-luna"450model = "gpt-6-luna"

432model_reasoning_effort = "high"451model_reasoning_effort = "high"

433sandbox_mode = "read-only"

434developer_instructions = """452developer_instructions = """

435Stay in exploration mode.453Stay in exploration mode.

454Do not edit files.

437Prefer fast search and targeted file reads over broad scans.456Prefer fast search and targeted file reads over broad scans.

438"""457"""

445description = "PR reviewer focused on correctness, security, and missing tests."464description = "PR reviewer focused on correctness, security, and missing tests."

446model = "gpt-6.1-sol"465model = "gpt-6.1-sol"

447model_reasoning_effort = "medium"466model_reasoning_effort = "medium"

448sandbox_mode = "read-only"

449developer_instructions = """467developer_instructions = """

450Review code like an owner.468Review code like an owner.

469Do not edit files.

451Prioritize correctness, security, behavior regressions, and missing test coverage.470Prioritize correctness, security, behavior regressions, and missing test coverage.

453"""472"""

462model = "gpt-6-luna"481model = "gpt-6-luna"

463model_reasoning_effort = "high"482model_reasoning_effort = "high"

464sandbox_mode = "read-only"

465developer_instructions = """483developer_instructions = """

466Use the docs MCP server to confirm APIs, options, and version-specific behavior.484Use the docs MCP server to confirm APIs, options, and version-specific behavior.

467Return concise answers with links or exact references when available.485Return concise answers with links or exact references when available.

468Do not make code changes.486Do not make code changes.

469"""487"""

470 488

471[mcp_servers.openaiDeveloperDocs]

472url = "https://developers.openai.com/mcp"

473```489```

474 490

475This setup works well for prompts like:491This setup works well for prompts like:

487```toml503```toml

488[agents]504[agents]

489max_concurrent_threads_per_session = 6505max_concurrent_threads_per_session = 6

506

507[mcp_servers.chrome_devtools]

508url = "http://localhost:3000/mcp"

509startup_timeout_sec = 20

490```510```

491 511

492`.codex/agents/code-mapper.toml`:512`.codex/agents/code-mapper.toml`:

497model = "gpt-6-luna"517model = "gpt-6-luna"

498model_reasoning_effort = "high"518model_reasoning_effort = "high"

499sandbox_mode = "read-only"

500developer_instructions = """519developer_instructions = """

501Map the code that owns the failing UI flow.520Map the code that owns the failing UI flow.

521Do not edit files.

503"""523"""

504```524```

511model = "gpt-6.1-sol"531model = "gpt-6.1-sol"

512model_reasoning_effort = "medium"532model_reasoning_effort = "medium"

513sandbox_mode = "workspace-write"

514developer_instructions = """533developer_instructions = """

516Use browser tooling for screenshots, console output, and network evidence.535Use browser tooling for screenshots, console output, and network evidence.

517Do not edit application code.536Do not edit application code.

518"""537"""

519[mcp_servers.chrome_devtools]

520url = "http://localhost:3000/mcp"

521startup_timeout_sec = 20

522```538```

523 539

524 540

config-advanced.md +8 −6

Details

378[Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) and378[Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) and

379[Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).379[Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).

380 380

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

382 read-only even when the rest of the workspace is writable. This is why382 `.codex/`, and `.aws/` read-only even when the rest of the workspace is

383 commands like `git commit` may still require approval to run outside the383 writable. This is why commands like `git commit` may still require approval to

384 sandbox. If you want Codex to skip specific commands (for example, block `git384 run outside the sandbox. If you want Codex to skip specific commands (for

385 commit` outside the sandbox), use385 example, block `git commit` outside the sandbox), use

386 [rules](https://learn.chatgpt.com/docs/agent-configuration/rules).386 [rules](https://learn.chatgpt.com/docs/agent-configuration/rules).

387 387

388Disable sandboxing entirely (use only if your environment already isolates processes):388Disable sandboxing entirely (use only if your environment already isolates processes):

502 502

503By default, Codex periodically sends a small amount of anonymous usage and health data back to OpenAI. This helps detect when Codex isn't working correctly and shows what features and configuration options are being used, so the Codex team can focus on what matters most. These metrics don't contain any personally identifiable information (PII). Metrics collection is independent of OTel log/trace export.503By default, Codex periodically sends a small amount of anonymous usage and health data back to OpenAI. This helps detect when Codex isn't working correctly and shows what features and configuration options are being used, so the Codex team can focus on what matters most. These metrics don't contain any personally identifiable information (PII). Metrics collection is independent of OTel log/trace export.

504 504

505If you want to disable metrics collection entirely across the ChatGPT desktop app, Codex CLI, and IDE extension on a machine, set the analytics flag in your config:505To disable analytics and metrics collection in Codex CLI, set the analytics flag in your config:

506 506

507```toml507```toml

508[analytics]508[analytics]

509enabled = false509enabled = false

510```510```

511 511

512This also disables custom OTLP metrics exporters in Codex CLI.

513

512Each metric includes its own fields plus the default context fields below.514Each metric includes its own fields plus the default context fields below.

513 515

514#### Default context fields (applies to every event/metric)516#### Default context fields (applies to every event/metric)

config-basic.md +10 −8

Details

84sandbox_mode = "workspace-write"84sandbox_mode = "workspace-write"

85```85```

86 86

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

88 88

89#### Permission profiles89#### Permission profiles

90 90

133 133

134#### Communication style134#### Communication style

135 135

136Set a default communication style for supported models.136To omit the built-in personality instructions, set:

137 137

138```toml138```toml

139personality = "friendly" # or "pragmatic" or "none"139personality = "none"

140```140```

141 141

142You can override this later in an active session with `/personality` or per thread/turn when using the app-server APIs.142This removes the `Personality` section from the model's built-in instructions.

143It doesn't change explicit custom base instructions. The older `friendly` and

144`pragmatic` values no longer select a style. Codex no longer provides the

145`/personality` command.

143 146

144#### TUI keymap147#### TUI keymap

145 148

198### Common feature flags201### Common feature flags

199 202

200| Key | Default | Maturity | Description |203| Key | Default | Maturity | Description |

201| -------------------- | :-------------------: | ------------ | ---------------------------------------------------------------------------------------- |204| -------------------- | :-----: | ------------ | ---------------------------------------------------------------------------------------- |

config-file/config-advanced.md +8 −6

Details

378[Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) and378[Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) and

379[Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).379[Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).

380 380

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

382 read-only even when the rest of the workspace is writable. This is why382 `.codex/`, and `.aws/` read-only even when the rest of the workspace is

383 commands like `git commit` may still require approval to run outside the383 writable. This is why commands like `git commit` may still require approval to

384 sandbox. If you want Codex to skip specific commands (for example, block `git384 run outside the sandbox. If you want Codex to skip specific commands (for

385 commit` outside the sandbox), use385 example, block `git commit` outside the sandbox), use

386 [rules](https://learn.chatgpt.com/docs/agent-configuration/rules).386 [rules](https://learn.chatgpt.com/docs/agent-configuration/rules).

387 387

388Disable sandboxing entirely (use only if your environment already isolates processes):388Disable sandboxing entirely (use only if your environment already isolates processes):

502 502

504 504

506 506

507```toml507```toml

508[analytics]508[analytics]

509enabled = false509enabled = false

510```510```

511 511

512This also disables custom OTLP metrics exporters in Codex CLI.

513

512Each metric includes its own fields plus the default context fields below.514Each metric includes its own fields plus the default context fields below.

513 515

514#### Default context fields (applies to every event/metric)516#### Default context fields (applies to every event/metric)

config-file/config-basic.md +10 −8

Details

84sandbox_mode = "workspace-write"84sandbox_mode = "workspace-write"

85```85```

86 86

88 88

89#### Permission profiles89#### Permission profiles

90 90

133 133

134#### Communication style134#### Communication style

135 135

136Set a default communication style for supported models.136To omit the built-in personality instructions, set:

137 137

138```toml138```toml

139personality = "friendly" # or "pragmatic" or "none"139personality = "none"

140```140```

141 141

143It doesn't change explicit custom base instructions. The older `friendly` and

144`pragmatic` values no longer select a style. Codex no longer provides the

145`/personality` command.

143 146

144#### TUI keymap147#### TUI keymap

145 148

198### Common feature flags201### Common feature flags

199 202

200| Key | Default | Maturity | Description |203| Key | Default | Maturity | Description |

config-file/config-reference.md +57 −9

Details

316 key: "analytics.enabled",316 key: "analytics.enabled",

317 type: "boolean",317 type: "boolean",

318 description:318 description:

319 "Enable or disable analytics for this machine/profile. When unset, the client default applies.",319 "Enable or disable analytics for this machine/profile. In Codex CLI, `false` also disables custom OTLP metrics exporters. When unset, the client default applies.",

320 },320 },

321 {321 {

322 key: "instructions",322 key: "instructions",

357 key: "personality",357 key: "personality",

358 type: "none | friendly | pragmatic",358 type: "none | friendly | pragmatic",

359 description:359 description:

360 "Default communication style for models that advertise `supportsPersonality`; can be overridden per thread/turn or via `/personality`.",360 "Deprecated compatibility setting. `friendly` and `pragmatic` no longer select a style. `none` omits the built-in Personality section from model instructions; explicit instruction overrides are unchanged.",

361 },361 },

362 {362 {

363 key: "service_tier",363 key: "service_tier",

638 description:638 description:

639 "Pre-registered OAuth client ID used for authorization and token exchange with this MCP server.",639 "Pre-registered OAuth client ID used for authorization and token exchange with this MCP server.",

640 },640 },

641 {

642 key: "mcp_servers.<id>.oauth.client_secret",

643 type: "string",

644 description:

645 "OAuth client secret for token exchange with a pre-registered client. Requires a nonempty `oauth.client_id`; the secret must also be nonempty. Stored in configuration.",

646 },

641 {647 {

642 key: "mcp_servers.<id>.oauth.callback_url",648 key: "mcp_servers.<id>.oauth.callback_url",

643 type: "string",649 type: "string",

875 key: "features.unified_exec",881 key: "features.unified_exec",

876 type: "boolean",882 type: "boolean",

877 description:883 description:

878 "Use the unified PTY-backed exec tool (stable; enabled by default except on Windows).",884 "Use resumable command execution (stable; enabled on all platforms). User opt-outs are ignored. Managed requirements can disable resumable processes and `write_stdin`, leaving one-shot `exec_command` available.",

879 },885 },

880 {886 {

881 key: "features.shell_snapshot",887 key: "features.shell_snapshot",

904 key: "features.personality",910 key: "features.personality",

905 type: "boolean",911 type: "boolean",

906 description:912 description:

907 "Enable personality selection controls (stable; on by default).",913 "Removed feature flag. Accepted for compatibility and ignored.",

908 },914 },

909 {915 {

910 key: "features.network_proxy",916 key: "features.network_proxy",

997 {1003 {

998 key: "features.shell_tool",1004 key: "features.shell_tool",

999 type: "boolean",1005 type: "boolean",

1000 description:1006 description: "Enable command execution tools (stable; on by default).",

1001 "Enable the default `shell` tool for running commands (stable; on by default).",

1002 },1007 },

1003 {1008 {

1004 key: "features.enable_request_compression",1009 key: "features.enable_request_compression",

1016 key: "features.fast_mode",1021 key: "features.fast_mode",

1017 type: "boolean",1022 type: "boolean",

1018 description:1023 description:

1019 "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).",1024 "Enable Fast mode controls advertised by the active model (stable; on by default), independently of `features.ultrafast_mode`. Availability still depends on the model and account.",

1025 },

1026 {

1027 key: "features.ultrafast_mode",

1028 type: "boolean",

1029 description:

1030 "Enable Ultrafast mode controls (stable; on by default), independently of `features.fast_mode`. Availability still depends on the model and account.",

1020 },1031 },

1021 {1032 {

1022 key: "features.prevent_idle_sleep",1033 key: "features.prevent_idle_sleep",

1046 type: "string",1057 type: "string",

1047 description: "API base URL for the model provider.",1058 description: "API base URL for the model provider.",

1048 },1059 },

1060 {

1061 key: "model_providers.<id>.model_catalog_url",

1062 type: "string",

1063 description:

1064 "Full URL for a Codex-native model catalog. Omit to keep the provider's default model discovery.",

1065 },

1066 {

1067 key: "model_providers.<id>.capabilities.external_web_access",

1068 type: "boolean",

1069 description:

1070 "Whether the provider's hosted web search can access the live web. Omit to keep provider defaults; model and turn settings may restrict access further.",

1071 },

1072 {

1073 key: "model_providers.<id>.capabilities.remote_compaction",

1074 type: "unsupported | v2",

1075 description:

1076 "Provider compaction protocol. `unsupported` uses local compaction; `v2` sends compaction triggers through Responses. Omit to keep provider defaults; model and turn settings may restrict support further.",

1077 },

1049 {1078 {

1050 key: "model_providers.<id>.env_key",1079 key: "model_providers.<id>.env_key",

1051 type: "string",1080 type: "string",

1303 key: "otel.metrics_exporter",1332 key: "otel.metrics_exporter",

1305 description:1334 description:

1306 "Select the OpenTelemetry metrics exporter (defaults to `statsig`).",1335 "Select the OpenTelemetry metrics exporter (defaults to `statsig`). In Codex CLI, `analytics.enabled = false` disables this exporter, including custom OTLP exporters. Set to `none` to disable metrics export independently.",

1307 },1336 },

1308 {1337 {

1309 key: "otel.log_user_prompt",1338 key: "otel.log_user_prompt",

1442 description:1471 description:

1443 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",1472 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",

1444 },1473 },

1474 {

1475 key: "tui.disable_paste_burst",

1476 type: "boolean",

1477 description:

1478 "Disable burst-paste detection in the TUI (default: false). Takes precedence over the legacy top-level `disable_paste_burst` setting.",

1479 },

1445 {1480 {

1446 key: "tui.alternate_screen",1481 key: "tui.alternate_screen",

1447 type: "auto | always | never",1482 type: "auto | always | never",

1472 description:1507 description:

1473 "Show onboarding tooltips in the TUI welcome screen (default: true).",1508 "Show onboarding tooltips in the TUI welcome screen (default: true).",

1474 },1509 },

1510 {

1511 key: "tui.auto_recap",

1512 type: "boolean",

1513 description:

1514 "Generate automatic conversation recaps while the terminal is unfocused (default: true). Set to `false` to disable automatic recaps; `/recap` remains available.",

1515 },

1516 {

1517 key: "tui.show_server_version_notice",

1518 type: "boolean",

1519 description:

1520 "Show informational notices about connected app-server version differences (default: true). Does not hide compatibility errors or version status.",

1521 },

1475 {1522 {

1476 key: "tui.status_line",1523 key: "tui.status_line",

1477 type: "array<string> | null",1524 type: "array<string> | null",

1581 {1628 {

1582 key: "disable_paste_burst",1629 key: "disable_paste_burst",

1583 type: "boolean",1630 type: "boolean",

1584 description: "Disable burst-paste detection in the TUI.",1631 description:

1632 "Legacy fallback for `tui.disable_paste_burst`. Prefer the setting under `[tui]`.",

1585 },1633 },

1586 {1634 {

1587 key: "windows_wsl_setup_acknowledged",1635 key: "windows_wsl_setup_acknowledged",

config-file/config-sample.md +49 −13

Details

45 45

46model = "gpt-6.1-sol"46model = "gpt-6.1-sol"

47 47

~~48# Communication style for supported models. Allowed values: none | friendly | pragmatic~~48# Omit the built-in Personality section from model instructions. Default: unset.

49 49

~~50# personality = "pragmatic"~~50# Legacy friendly and pragmatic values are accepted but no longer select a style.

52# personality = "none"

51 53

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

53 55

313 315

314show_raw_agent_reasoning = false316show_raw_agent_reasoning = false

315 317

316# Disable burst-paste detection in the TUI. Default: false

~~317~~

318disable_paste_burst = false

~~319~~

320# Track Windows onboarding acknowledgement (Windows only). Default: false318# Track Windows onboarding acknowledgement (Windows only). Default: false

321 319

322windows_wsl_setup_acknowledged = false320windows_wsl_setup_acknowledged = false

601 599

602[tui]600[tui]

603 601

602# Disable burst-paste detection. Default: false.

603

604# Overrides the legacy top-level disable_paste_burst setting.

605

606disable_paste_burst = false

607

604# Desktop notifications from the TUI: boolean or filtered list. Default: true608# Desktop notifications from the TUI: boolean or filtered list. Default: true

605 609

606# Examples: false | ["agent-turn-complete", "approval-requested"]610# Examples: false | ["agent-turn-complete", "approval-requested"]

623 627

624show_tooltips = true628show_tooltips = true

625 629

630# Generate automatic recaps while the terminal is unfocused. Default: true.

631

632# /recap remains available when this is false.

633

634# auto_recap = true

635

636# Show informational server-version notices. Default: true.

637

638# Does not hide compatibility errors or version status.

639

640# show_server_version_notice = true

641

626# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).642# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).

627 643

628# alternate_screen = "auto"644# alternate_screen = "auto"

683 699

684# "gpt-6.1-sol" = 1700# "gpt-6.1-sol" = 1

685 701

686# Enable or disable analytics for this machine. When unset, Codex uses its default behavior.702# Enable or disable analytics. When unset, the client default applies.

703

704# In Codex CLI, false also disables custom OTLP metrics exporters.

687 705

688[analytics]706[analytics]

689enabled = true707enabled = true

731 749

732# hooks = false750# hooks = false

733 751

734# unified_exec = true752# Resumable execution is enabled on all platforms. Only managed requirements can disable it.

735 753

736# shell_snapshot = true754# shell_snapshot = true

737 755

739 757

740# remote_plugin = true758# remote_plugin = true

741 759

742# personality = true

~~743~~

744# network_proxy = true # required to enforce permission-profile domain rules760# network_proxy = true # required to enforce permission-profile domain rules

745 761

746# fast_mode = true762# fast_mode = true

747 763

764# ultrafast_mode = true # independent of fast_mode; model and account access still apply

765

748# enable_request_compression = true766# enable_request_compression = true

749 767

750# skill_mcp_dependency_install = true768# skill_mcp_dependency_install = true

901 919

902# client_id = "my-pre-registered-client" # OAuth client registered with the provider920# client_id = "my-pre-registered-client" # OAuth client registered with the provider

903 921

922# client_secret = "<client-secret>" # optional confidential client secret; stored in config

923

904# callback_url = "http://127.0.0.1/callback" # saved registered callback for this client924# callback_url = "http://127.0.0.1/callback" # saved registered callback for this client

905 925

906# callback_port = 4321 # server-specific listener port; overrides the global setting926# callback_port = 4321 # server-specific listener port; overrides the global setting

995 1015

996# wire_api = "responses"1016# wire_api = "responses"

997 1017

1018# model_catalog_url = "https://proxy.example.com/codex-models.json" # full Codex-native catalog URL

1019

1020# Optional provider capability overrides. Omit to keep provider defaults.

1021

1022# Model and turn settings may restrict these capabilities further.

1023

1024# [model_providers.proxy.capabilities]

1025

1026# external_web_access = false # whether hosted web search can access the live web

1027

1028# remote_compaction = "unsupported" # unsupported (local compaction) | v2

1029

998#1030#

999 1031

1000# [model_providers.proxy.auth]1032# [model_providers.proxy.auth]

1113 1145

1114# model_verbosity = "medium"1146# model_verbosity = "medium"

1115 1147

1116# personality = "pragmatic" # or "friendly" or "none"1148# personality = "none" # omit the built-in Personality section

1117 1149

1118# chatgpt_base_url = "https://chatgpt.com/backend-api/"1150# chatgpt_base_url = "https://chatgpt.com/backend-api/"

1119 1151

1125 1157

1126# tools_view_image = true1158# tools_view_image = true

1127 1159

1128# features = { unified_exec = false }1160# features = { shell_snapshot = false }

1129 1161

1130################################################################################1162################################################################################

1131 1163

1153 1185

1154################################################################################1186################################################################################

1155 1187

1156# OpenTelemetry (OTEL) - disabled by default1188# OpenTelemetry (OTEL)

1157 1189

1158################################################################################1190################################################################################

1159 1191

1177 1209

1179 1211

1212# Default: statsig. In Codex CLI, analytics.enabled = false disables all metrics exporters.

1213

1214# Set to none to disable metrics export.

1215

1180metrics_exporter = "statsig"1216metrics_exporter = "statsig"

1181 1217

1182# Example OTLP/HTTP exporter configuration1218# Example OTLP/HTTP exporter configuration

config-reference.md +57 −9

Details

316 key: "analytics.enabled",316 key: "analytics.enabled",

317 type: "boolean",317 type: "boolean",

318 description:318 description:

320 },320 },

321 {321 {

322 key: "instructions",322 key: "instructions",

357 key: "personality",357 key: "personality",

358 type: "none | friendly | pragmatic",358 type: "none | friendly | pragmatic",

359 description:359 description:

361 },361 },

362 {362 {

363 key: "service_tier",363 key: "service_tier",

638 description:638 description:

640 },640 },

641 {

642 key: "mcp_servers.<id>.oauth.client_secret",

643 type: "string",

644 description:

645 "OAuth client secret for token exchange with a pre-registered client. Requires a nonempty `oauth.client_id`; the secret must also be nonempty. Stored in configuration.",

646 },

641 {647 {

642 key: "mcp_servers.<id>.oauth.callback_url",648 key: "mcp_servers.<id>.oauth.callback_url",

643 type: "string",649 type: "string",

875 key: "features.unified_exec",881 key: "features.unified_exec",

876 type: "boolean",882 type: "boolean",

877 description:883 description:

879 },885 },

880 {886 {

881 key: "features.shell_snapshot",887 key: "features.shell_snapshot",

904 key: "features.personality",910 key: "features.personality",

905 type: "boolean",911 type: "boolean",

906 description:912 description:

907 "Enable personality selection controls (stable; on by default).",913 "Removed feature flag. Accepted for compatibility and ignored.",

908 },914 },

909 {915 {

910 key: "features.network_proxy",916 key: "features.network_proxy",

997 {1003 {

998 key: "features.shell_tool",1004 key: "features.shell_tool",

999 type: "boolean",1005 type: "boolean",

1000 description:1006 description: "Enable command execution tools (stable; on by default).",

1001 "Enable the default `shell` tool for running commands (stable; on by default).",

1002 },1007 },

1003 {1008 {

1004 key: "features.enable_request_compression",1009 key: "features.enable_request_compression",

1016 key: "features.fast_mode",1021 key: "features.fast_mode",

1017 type: "boolean",1022 type: "boolean",

1018 description:1023 description:

1025 },

1026 {

1027 key: "features.ultrafast_mode",

1028 type: "boolean",

1029 description:

1030 "Enable Ultrafast mode controls (stable; on by default), independently of `features.fast_mode`. Availability still depends on the model and account.",

1020 },1031 },

1021 {1032 {

1022 key: "features.prevent_idle_sleep",1033 key: "features.prevent_idle_sleep",

1046 type: "string",1057 type: "string",

1047 description: "API base URL for the model provider.",1058 description: "API base URL for the model provider.",

1048 },1059 },

1060 {

1061 key: "model_providers.<id>.model_catalog_url",

1062 type: "string",

1063 description:

1064 "Full URL for a Codex-native model catalog. Omit to keep the provider's default model discovery.",

1065 },

1066 {

1067 key: "model_providers.<id>.capabilities.external_web_access",

1068 type: "boolean",

1069 description:

1070 "Whether the provider's hosted web search can access the live web. Omit to keep provider defaults; model and turn settings may restrict access further.",

1071 },

1072 {

1073 key: "model_providers.<id>.capabilities.remote_compaction",

1074 type: "unsupported | v2",

1075 description:

1077 },

1049 {1078 {

1050 key: "model_providers.<id>.env_key",1079 key: "model_providers.<id>.env_key",

1051 type: "string",1080 type: "string",

1303 key: "otel.metrics_exporter",1332 key: "otel.metrics_exporter",

1305 description:1334 description:

1307 },1336 },

1308 {1337 {

1309 key: "otel.log_user_prompt",1338 key: "otel.log_user_prompt",

1442 description:1471 description:

1443 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",1472 "Enable terminal animations (welcome screen, shimmer, spinner) (default: true).",

1444 },1473 },

1474 {

1475 key: "tui.disable_paste_burst",

1476 type: "boolean",

1477 description:

1478 "Disable burst-paste detection in the TUI (default: false). Takes precedence over the legacy top-level `disable_paste_burst` setting.",

1479 },

1445 {1480 {

1446 key: "tui.alternate_screen",1481 key: "tui.alternate_screen",

1447 type: "auto | always | never",1482 type: "auto | always | never",

1472 description:1507 description:

1473 "Show onboarding tooltips in the TUI welcome screen (default: true).",1508 "Show onboarding tooltips in the TUI welcome screen (default: true).",

1474 },1509 },

1510 {

1511 key: "tui.auto_recap",

1512 type: "boolean",

1513 description:

1514 "Generate automatic conversation recaps while the terminal is unfocused (default: true). Set to `false` to disable automatic recaps; `/recap` remains available.",

1515 },

1516 {

1517 key: "tui.show_server_version_notice",

1518 type: "boolean",

1519 description:

1520 "Show informational notices about connected app-server version differences (default: true). Does not hide compatibility errors or version status.",

1521 },

1475 {1522 {

1476 key: "tui.status_line",1523 key: "tui.status_line",

1477 type: "array<string> | null",1524 type: "array<string> | null",

1581 {1628 {

1582 key: "disable_paste_burst",1629 key: "disable_paste_burst",

1583 type: "boolean",1630 type: "boolean",

1584 description: "Disable burst-paste detection in the TUI.",1631 description:

1632 "Legacy fallback for `tui.disable_paste_burst`. Prefer the setting under `[tui]`.",

1585 },1633 },

1586 {1634 {

1587 key: "windows_wsl_setup_acknowledged",1635 key: "windows_wsl_setup_acknowledged",

config-sample.md +49 −13

Details

45 45

46model = "gpt-6.1-sol"46model = "gpt-6.1-sol"

47 47

~~48# Communication style for supported models. Allowed values: none | friendly | pragmatic~~48# Omit the built-in Personality section from model instructions. Default: unset.

49 49

~~50# personality = "pragmatic"~~50# Legacy friendly and pragmatic values are accepted but no longer select a style.

52# personality = "none"

51 53

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

53 55

313 315

314show_raw_agent_reasoning = false316show_raw_agent_reasoning = false

315 317

316# Disable burst-paste detection in the TUI. Default: false

~~317~~

318disable_paste_burst = false

~~319~~

320# Track Windows onboarding acknowledgement (Windows only). Default: false318# Track Windows onboarding acknowledgement (Windows only). Default: false

321 319

322windows_wsl_setup_acknowledged = false320windows_wsl_setup_acknowledged = false

601 599

602[tui]600[tui]

603 601

602# Disable burst-paste detection. Default: false.

603

604# Overrides the legacy top-level disable_paste_burst setting.

605

606disable_paste_burst = false

607

604# Desktop notifications from the TUI: boolean or filtered list. Default: true608# Desktop notifications from the TUI: boolean or filtered list. Default: true

605 609

606# Examples: false | ["agent-turn-complete", "approval-requested"]610# Examples: false | ["agent-turn-complete", "approval-requested"]

623 627

624show_tooltips = true628show_tooltips = true

625 629

630# Generate automatic recaps while the terminal is unfocused. Default: true.

631

632# /recap remains available when this is false.

633

634# auto_recap = true

635

636# Show informational server-version notices. Default: true.

637

638# Does not hide compatibility errors or version status.

639

640# show_server_version_notice = true

641

626# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).642# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).

627 643

628# alternate_screen = "auto"644# alternate_screen = "auto"

683 699

684# "gpt-6.1-sol" = 1700# "gpt-6.1-sol" = 1

685 701

686# Enable or disable analytics for this machine. When unset, Codex uses its default behavior.702# Enable or disable analytics. When unset, the client default applies.

703

704# In Codex CLI, false also disables custom OTLP metrics exporters.

687 705

688[analytics]706[analytics]

689enabled = true707enabled = true

731 749

732# hooks = false750# hooks = false

733 751

734# unified_exec = true752# Resumable execution is enabled on all platforms. Only managed requirements can disable it.

735 753

736# shell_snapshot = true754# shell_snapshot = true

737 755

739 757

740# remote_plugin = true758# remote_plugin = true

741 759

742# personality = true

~~743~~

744# network_proxy = true # required to enforce permission-profile domain rules760# network_proxy = true # required to enforce permission-profile domain rules

745 761

746# fast_mode = true762# fast_mode = true

747 763

764# ultrafast_mode = true # independent of fast_mode; model and account access still apply

765

748# enable_request_compression = true766# enable_request_compression = true

749 767

750# skill_mcp_dependency_install = true768# skill_mcp_dependency_install = true

901 919

902# client_id = "my-pre-registered-client" # OAuth client registered with the provider920# client_id = "my-pre-registered-client" # OAuth client registered with the provider

903 921

922# client_secret = "<client-secret>" # optional confidential client secret; stored in config

923

904# callback_url = "http://127.0.0.1/callback" # saved registered callback for this client924# callback_url = "http://127.0.0.1/callback" # saved registered callback for this client

905 925

906# callback_port = 4321 # server-specific listener port; overrides the global setting926# callback_port = 4321 # server-specific listener port; overrides the global setting

995 1015

996# wire_api = "responses"1016# wire_api = "responses"

997 1017

1018# model_catalog_url = "https://proxy.example.com/codex-models.json" # full Codex-native catalog URL

1019

1020# Optional provider capability overrides. Omit to keep provider defaults.

1021

1022# Model and turn settings may restrict these capabilities further.

1023

1024# [model_providers.proxy.capabilities]

1025

1026# external_web_access = false # whether hosted web search can access the live web

1027

1028# remote_compaction = "unsupported" # unsupported (local compaction) | v2

1029

998#1030#

999 1031

1000# [model_providers.proxy.auth]1032# [model_providers.proxy.auth]

1113 1145

1114# model_verbosity = "medium"1146# model_verbosity = "medium"

1115 1147

1116# personality = "pragmatic" # or "friendly" or "none"1148# personality = "none" # omit the built-in Personality section

1117 1149

1118# chatgpt_base_url = "https://chatgpt.com/backend-api/"1150# chatgpt_base_url = "https://chatgpt.com/backend-api/"

1119 1151

1125 1157

1126# tools_view_image = true1158# tools_view_image = true

1127 1159

1128# features = { unified_exec = false }1160# features = { shell_snapshot = false }

1129 1161

1130################################################################################1162################################################################################

1131 1163

1153 1185

1154################################################################################1186################################################################################

1155 1187

1156# OpenTelemetry (OTEL) - disabled by default1188# OpenTelemetry (OTEL)

1157 1189

1158################################################################################1190################################################################################

1159 1191

1177 1209

1179 1211

1212# Default: statsig. In Codex CLI, analytics.enabled = false disables all metrics exporters.

1213

1214# Set to none to disable metrics export.

1215

1180metrics_exporter = "statsig"1216metrics_exporter = "statsig"

1181 1217

1182# Example OTLP/HTTP exporter configuration1218# Example OTLP/HTTP exporter configuration

enterprise/managed-configuration.md +5 −1

Details

617 617

618```toml618```toml

619[features]619[features]

620personality = true620hooks = true

621unified_exec = false621unified_exec = false

622 622

623# Disable surface-specific features when needed.623# Disable surface-specific features when needed.

634pins and rejects conflicting writes to `config.toml` or profile file feature634pins and rejects conflicting writes to `config.toml` or profile file feature

635settings.635settings.

636 636

637A managed `unified_exec = false` keeps command execution available, but disables

638resumable processes and the `write_stdin` tool. User configuration can't disable

639this feature.

640

637<a id="disable-codex-feature-surfaces"></a>641<a id="disable-codex-feature-surfaces"></a>

638 642

639- `in_app_browser = false` disables the built-in browser pane.643- `in_app_browser = false` disables the built-in browser pane.

extend/mcp.md +11 −0

Details

227codex mcp add example --url https://mcp.example.com --oauth-client-id my-client227codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

228```228```

229 229

230For a confidential client, also pass `--oauth-client-secret`. Read the secret

231from an environment variable:

232

233```bash

234codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

235```

236

237This option requires a nonempty client ID and secret. Codex saves the secret as

238`mcp_servers.example.oauth.client_secret` in `config.toml`. Keep that file

239private and out of version control.

240

230Codex displays the complete callback URL to register with your provider:241Codex displays the complete callback URL to register with your provider:

231 242

232```text243```text

hooks.md +8 −5

Details

416Only some current Codex events honor `matcher`:416Only some current Codex events honor `matcher`:

417 417

419| ------------------- | ---------------------- | ------------------------------------------------------------ |419| ------------------- | ---------------------- | -------------------------------------------------------------- |

439- `Edit|Write`439- `Edit|Write`

440- `mcp__filesystem__read_file`440- `mcp__filesystem__read_file`

441- `mcp__filesystem__.*`441- `mcp__filesystem__.*`

443- `manual|auto`443- `manual|auto`

444 444

445### Tool coverage445### Tool coverage

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

653 653

655| -------- | -------- | ------------------------------------------------------------------- |655| -------- | -------- | --------------------------------------------------------------------------- |

657

658A forked thread uses `source: "fork"`. Resuming a thread with supplied history

659still uses `source: "resume"`.

657 660

658Plain text on `stdout` is added as extra developer context.661Plain text on `stdout` is added as extra developer context.

659 662

mcp.md +11 −0

Details

227codex mcp add example --url https://mcp.example.com --oauth-client-id my-client227codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

228```228```

229 229

230For a confidential client, also pass `--oauth-client-secret`. Read the secret

231from an environment variable:

232

233```bash

234codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

235```

236

237This option requires a nonempty client ID and secret. Codex saves the secret as

238`mcp_servers.example.oauth.client_secret` in `config.toml`. Keep that file

239private and out of version control.

240

230Codex displays the complete callback URL to register with your provider:241Codex displays the complete callback URL to register with your provider:

231 242

232```text243```text

non-interactive-mode.md +3 −1

Details

57 57

58Use `danger-full-access` only in a controlled environment (for example, an isolated CI runner or container).58Use `danger-full-access` only in a controlled environment (for example, an isolated CI runner or container).

59 59

~~60Codex keeps `codex exec --full-auto` as a deprecated compatibility flag and prints a warning. Prefer the explicit `--sandbox workspace-write` flag in new scripts.~~60`--full-auto` is no longer supported. Update scripts to use

61`--sandbox workspace-write`, or use `--approve-for-me` to route approval

62requests through automatic review with the workspace-write sandbox.

61 63

62Use `--ignore-user-config` when you need a run that doesn't load `$CODEX_HOME/config.toml`, and `--ignore-rules` when you need to skip user and project execpolicy `.rules` files for a controlled automation environment.64Use `--ignore-user-config` when you need a run that doesn't load `$CODEX_HOME/config.toml`, and `--ignore-rules` when you need to skip user and project execpolicy `.rules` files for a controlled automation environment.

63 65

noninteractive.md +3 −1

Details

57 57

59 59

61`--sandbox workspace-write`, or use `--approve-for-me` to route approval

62requests through automatic review with the workspace-write sandbox.

61 63

63 65

open-source.md +5 −1

Details

2 2

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4

~~5OpenAI develops key parts of Codex in the open. That work lives on GitHub so you can follow progress, report issues, and contribute improvements.~~5OpenAI develops key parts of Codex in the open. That work lives on GitHub so you can follow progress, report issues, and request improvements.

6 6

7If you maintain a widely used open-source project or want to nominate maintainers stewarding important projects, you can also [apply to the Codex for OSS program](https://developers.openai.com/community/codex-for-oss) for API credits, ChatGPT Pro with Codex, and selective access to Codex Security.7If you maintain a widely used open-source project or want to nominate maintainers stewarding important projects, you can also [apply to the Codex for OSS program](https://developers.openai.com/community/codex-for-oss) for API credits, ChatGPT Pro with Codex, and selective access to Codex Security.

8 8

30- Discussion forum: [openai/codex/discussions](https://github.com/openai/codex/discussions)30- Discussion forum: [openai/codex/discussions](https://github.com/openai/codex/discussions)

31 31

32When you file an issue, include which component you are using (CLI, SDK, IDE extension, Codex cloud, or Codex Security) and the version where possible.32When you file an issue, include which component you are using (CLI, SDK, IDE extension, Codex cloud, or Codex Security) and the version where possible.

34The `openai/codex` repository accepts community contributions through issues,

35including bug reports, reproduction steps, and root-cause analysis. It doesn't

36accept external code contributions or pull requests. Read its [contribution guidelines](https://github.com/openai/codex/blob/main/docs/contributing.md) for details.

permissions.md +10 −10

Details

138Use `extends` when a profile is mostly the same as a built-in or another named138Use `extends` when a profile is mostly the same as a built-in or another named

139profile. Prefer extending a built-in profile over starting from scratch so139profile. Prefer extending a built-in profile over starting from scratch so

140baseline protections carry forward. Extending `:workspace`, for example, keeps140baseline protections carry forward. Extending `:workspace`, for example, keeps

141the workspace root's `.codex` directory read-only unless you explicitly141the workspace root's `.git`, `.agents`, `.codex`, and `.aws` paths read-only

142override it. Set the parent once, then add or override only the rules that142unless you explicitly override those rules. Set the parent once, then add or

143differ.143override only the rules that differ.

144 144

145```toml145```toml

146default_permissions = "project-edit"146default_permissions = "project-edit"

512 be enforced by the platform sandbox, Codex refuses to run the command instead512 be enforced by the platform sandbox, Codex refuses to run the command instead

513 of silently running it unsandboxed.513 of silently running it unsandboxed.

514- On Linux and WSL, Codex uses [bubblewrap](https://github.com/containers/bubblewrap)514- On Linux and WSL, Codex uses [bubblewrap](https://github.com/containers/bubblewrap)

515 and [seccomp](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html),515 and [seccomp](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)

516 with Landlock available for compatibility fallback paths. The strongest516 to enforce filesystem restrictions. The legacy Landlock option can't isolate

517 enforcement path depends on user namespaces and kernel support; restricted517 app-server Unix sockets and is rejected for filesystem-restricted policies.

518 container hosts can force compatibility paths, and unsupported split policies518 Disable `features.use_legacy_landlock` when upgrading. Hosts that block the

519 are refused.519 required bubblewrap operations can't run these policies.

520- On Windows, MXC uses process isolation for filesystem and network permissions.520- On Windows, MXC uses process isolation for filesystem and network permissions.

521 Review [MXC compatibility](https://learn.chatgpt.com/docs/windows/windows-sandbox#mxc-compatibility)521 Review [MXC compatibility](https://learn.chatgpt.com/docs/windows/windows-sandbox#mxc-compatibility)

522 before enabling it. The legacy `elevated` fallback uses dedicated lower-privilege522 before enabling it. The legacy `elevated` fallback uses dedicated lower-privilege

563 563

564[permissions.workspace-only]564[permissions.workspace-only]

565# By extending the :workspace profile, you get Codex's safeguards to ensure565# By extending the :workspace profile, you get Codex's safeguards to ensure

566# subfolders such as .codex/ and .git/ within a workspace root are read-only566# paths such as .git/, .agents/, .codex/, and .aws/ within a workspace root

567# while the rest of the folder is writable.567# are read-only while the rest of the folder is writable.

568extends = ":workspace"568extends = ":workspace"

569 569

570[permissions.workspace-only.filesystem]570[permissions.workspace-only.filesystem]

sdk.md +20 −0

Details

66console.log(result2.finalResponse);66console.log(result2.finalResponse);

67```67```

68 68

69### Configuration overrides

71Pass `config` to set structured Codex configuration. For keys that can't be

72expressed as dotted paths, use `configOverrides` to pass raw TOML strings as

73separate `--config` arguments:

75```ts

76const codex = new Codex({

77 config: { default_permissions: "audit" },

78 configOverrides: [

79 'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',

80 ],

81});

82```

84Raw overrides take precedence over structured `config`. The SDK applies

85managed settings such as `baseUrl` and thread-specific options afterward, so

86they take precedence over both. These overrides don't change your Codex configuration

87files.

70 90

71## Python library91## Python library

skills.md +5 −2

Details

34Codex start with each skill's name and description, then load the full34Codex start with each skill's name and description, then load the full

35`SKILL.md` instructions when they decide to use that skill.35`SKILL.md` instructions when they decide to use that skill.

36 36

~~37In Codex, the initial list also includes each skill's file path. To avoid~~37In Codex, the initial list also includes each skill's file path. By default,

~~38crowding out the rest of the prompt, this list uses at most 2% of the model's~~38this list uses at most 2% of the model's

39context window, or 8,000 characters when the context window is unknown. If many39context window, or 8,000 characters when the context window is unknown. If many

40skills are installed, Codex shortens skill descriptions first. For large skill40skills are installed, Codex shortens skill descriptions first. For large skill

41sets, Codex may omit some skills from the initial list and show a warning.41sets, Codex may omit some skills from the initial list and show a warning.

42 42

43Use [`skills.max_context_tokens`](https://learn.chatgpt.com/docs/config-file/config-reference) to set a

44different budget, up to 10,000 tokens.

44 47

subagents.md +41 −25

Details

54 54

55Ask Codex in an interactive CLI session to use subagents. Codex can also follow55Ask Codex in an interactive CLI session to use subagents. Codex can also follow

56applicable `AGENTS.md` or skill instructions that request delegation. Use56applicable `AGENTS.md` or skill instructions that request delegation. Use

~~57`/agent` to inspect and switch between agent threads while they run. The main~~57`/subagents` to inspect and switch between agent threads while they run. The main

58thread collects the subagent results into its final response.58thread collects the subagent results into its final response.

59 59

60</ContentModeSwitch>60</ContentModeSwitch>

262 262

263<ContentModeSwitch group="codex-surface" id="cli">263<ContentModeSwitch group="codex-surface" id="cli">

264 264

267 267

268</ContentModeSwitch>268</ContentModeSwitch>

311action that needs new approval fails and Codex surfaces the error back to the311action that needs new approval fails and Codex surfaces the error back to the

312parent workflow.312parent workflow.

313 313

314Codex also reapplies the parent turn's live runtime overrides when it spawns a314Subagents inherit the parent turn's current sandbox and approval settings,

315child. That includes sandbox and approval choices you set interactively during315including changes made with `/permissions` or `--yolo`. A custom agent file

316the session, such as `/permissions` changes or `--yolo`, even if the selected316can't replace those settings.

317custom agent file sets different defaults.

318 317

319</ContentModeSwitch>318</ContentModeSwitch>

320 319

327 326

328<ContentModeSwitch group="codex-surface" ids="app,cli,ide">327<ContentModeSwitch group="codex-surface" ids="app,cli,ide">

329 328

330instructions can ask an agent to avoid edits, but they don't create a separate

331read-only sandbox.

331 332

332## Custom agents333## Custom agents

333 334

341`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped342`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped

342agents.343agents.

343 344

344Each file defines one custom agent. Codex loads these files as configuration345Each file defines one custom agent. Custom agents can change model settings and

345layers for spawned sessions, so custom agents can override the same settings as346instructions or disable supported capabilities. They inherit the parent's

346a normal Codex session config. That can feel heavier than a dedicated agent347permissions, provider, and MCP servers; a custom agent file can't override those

347manifest, and the format may evolve as authoring and sharing mature.348settings.

348 349

349Every standalone custom agent file must define:350Every standalone custom agent file must define:

350 351

360that model's default effort. A custom agent file that sets only `model`361that model's default effort. A custom agent file that sets only `model`

361preserves this previously resolved effort. Set `model_reasoning_effort` in the362preserves this previously resolved effort. Set `model_reasoning_effort` in the

362file too if the selected model doesn't support that effort or you want a363file too if the selected model doesn't support that effort or you want a

363different one. Other session settings, such as `sandbox_mode`, `mcp_servers`,364different one. Skills inherit from the parent, and a custom agent can disable

364and `skills.config`, inherit from the parent when the custom agent file omits365individual skills with `skills.config`.

365them.

366 366

367### Global settings367### Global settings

368 368

394 394

396`model_verbosity` to customize model behavior.

397See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) for their

398accepted values.

399

400To reduce a custom agent's capabilities, set supported feature keys to `false`:

401`features.shell_tool`, `features.apps`, `features.plugins`,

402`features.memories`, or `features.request_permissions_tool`. Disable individual

403skills with `skills.config` or bundled skills with

404`skills.bundled.enabled = false`. Set `skills.include_instructions = false` to

405omit the automatic skills instructions block. Managed requirements still apply.

406

407Other session settings, including `sandbox_mode`, `approval_policy`,

408`model_provider`, and `mcp_servers`, don't override the parent configuration

409when placed in a custom agent file. The service tier also follows the root

410session's preference. Configure MCP servers in the parent session so the agent

411can use them.

396 412

397Codex identifies the custom agent by its `name` field. Matching the filename to413Codex identifies the custom agent by its `name` field. Matching the filename to

398the agent name is the simplest convention, but the `name` field is the source414the agent name is the simplest convention, but the `name` field is the source

421```toml437```toml

422[agents]438[agents]

423max_concurrent_threads_per_session = 8439max_concurrent_threads_per_session = 8

440

441[mcp_servers.openaiDeveloperDocs]

442url = "https://developers.openai.com/mcp"

424```443```

425 444

426`.codex/agents/pr-explorer.toml`:445`.codex/agents/pr-explorer.toml`:

431model = "gpt-6-luna"450model = "gpt-6-luna"

432model_reasoning_effort = "high"451model_reasoning_effort = "high"

433sandbox_mode = "read-only"

434developer_instructions = """452developer_instructions = """

435Stay in exploration mode.453Stay in exploration mode.

454Do not edit files.

437Prefer fast search and targeted file reads over broad scans.456Prefer fast search and targeted file reads over broad scans.

438"""457"""

445description = "PR reviewer focused on correctness, security, and missing tests."464description = "PR reviewer focused on correctness, security, and missing tests."

446model = "gpt-6.1-sol"465model = "gpt-6.1-sol"

447model_reasoning_effort = "medium"466model_reasoning_effort = "medium"

448sandbox_mode = "read-only"

449developer_instructions = """467developer_instructions = """

450Review code like an owner.468Review code like an owner.

469Do not edit files.

451Prioritize correctness, security, behavior regressions, and missing test coverage.470Prioritize correctness, security, behavior regressions, and missing test coverage.

453"""472"""

462model = "gpt-6-luna"481model = "gpt-6-luna"

463model_reasoning_effort = "high"482model_reasoning_effort = "high"

464sandbox_mode = "read-only"

465developer_instructions = """483developer_instructions = """

466Use the docs MCP server to confirm APIs, options, and version-specific behavior.484Use the docs MCP server to confirm APIs, options, and version-specific behavior.

467Return concise answers with links or exact references when available.485Return concise answers with links or exact references when available.

468Do not make code changes.486Do not make code changes.

469"""487"""

470 488

471[mcp_servers.openaiDeveloperDocs]

472url = "https://developers.openai.com/mcp"

473```489```

474 490

475This setup works well for prompts like:491This setup works well for prompts like:

487```toml503```toml

488[agents]504[agents]

489max_concurrent_threads_per_session = 6505max_concurrent_threads_per_session = 6

506

507[mcp_servers.chrome_devtools]

508url = "http://localhost:3000/mcp"

509startup_timeout_sec = 20

490```510```

491 511

492`.codex/agents/code-mapper.toml`:512`.codex/agents/code-mapper.toml`:

497model = "gpt-6-luna"517model = "gpt-6-luna"

498model_reasoning_effort = "high"518model_reasoning_effort = "high"

499sandbox_mode = "read-only"

500developer_instructions = """519developer_instructions = """

501Map the code that owns the failing UI flow.520Map the code that owns the failing UI flow.

521Do not edit files.

503"""523"""

504```524```

511model = "gpt-6.1-sol"531model = "gpt-6.1-sol"

512model_reasoning_effort = "medium"532model_reasoning_effort = "medium"

513sandbox_mode = "workspace-write"

514developer_instructions = """533developer_instructions = """

516Use browser tooling for screenshots, console output, and network evidence.535Use browser tooling for screenshots, console output, and network evidence.

517Do not edit application code.536Do not edit application code.

518"""537"""

519[mcp_servers.chrome_devtools]

520url = "http://localhost:3000/mcp"

521startup_timeout_sec = 20

522```538```

523 539

524 540

Documentation 2026-10-12 23:01 UTC to 2026-10-13 23:01 UTC