Documentation 2026-09-01 07:57 UTC to 2026-09-02 22:59 UTC

28 href: "/codex/enterprise/admin-setup",28 href: "/codex/enterprise/admin-setup",

29 icon: "users",29 icon: "users",

30 },30 },

31 ],

32 },

33 {

34 title: "ChatGPT Work",

35 description:

36 "Review the ChatGPT Work overview and administration reference.",

37 pages: [

31 {38 {

32 title: "ChatGPT Work Overview",39 title: "ChatGPT Work Overview",

33 description:40 description:

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/rollback` - deprecated; drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

320- `turn/start` - add user input 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`.

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

852 852 

853If the thread already has an active turn, the command runs as an auxiliary action on that turn and its formatted output is injected into the turn's message stream. If the thread is idle, app-server starts a standalone turn for the shell command.853If the thread already has an active turn, the command runs as an auxiliary action on that turn and its formatted output is injected into the turn's message stream. If the thread is idle, app-server starts a standalone turn for the shell command.

854 854 

855Set `timeoutMs` to limit execution time in milliseconds. Omitting it or passing

856`null` uses the one-hour default. `0` requests an immediate timeout; negative

857values are rejected. The timeout doesn't delay the immediate RPC acknowledgement.

858 

855```json859```json

856{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }860{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short", "timeoutMs": 10000 } }

857{ "id": 26, "result": {} }861{ "id": 26, "result": {} }

858```862```

859 863 

984{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }988{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

985```989```

986 990 

991To start a turn with output from a tool your client ran, pass `toolOutput`

992with a nonempty `name`, an optional `namespace`, and an `output` string or

993array of content items. Set `input` to an empty array; you can't combine

994`toolOutput` with nonempty user input.

995 

996```json

997{

998 "method": "turn/start",

999 "id": 31,

1000 "params": {

1001 "threadId": "thr_123",

1002 "input": [],

1003 "toolOutput": {

1004 "name": "run_tests",

1005 "namespace": null,

1006 "output": "All 42 tests passed."

1007 }

1008 }

1009}

1010```

1011 

1012The output remains tool output in the conversation and appears as a

1013`functionCallOutput` item in notifications and persisted history. If a regular

1014turn is already active, Codex queues the output for that turn.

1015 

987### Inject items into a thread1016### Inject items into a thread

988 1017 

989Use `thread/inject_items` to append prebuilt Responses API items to a loaded thread's prompt history without starting a user turn. These items are persisted to the rollout and included in subsequent model requests.1018Use `thread/inject_items` to append prebuilt Responses API items to a loaded thread's prompt history without starting a user turn. These items are persisted to the rollout and included in subsequent model requests.

1289`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:1318`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:

1290 1319 

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

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

1292- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).1322- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).

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

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

253 description:253 description:

254 "Load the compaction prompt override from a file (experimental).",254 "Load the compaction prompt override from a file (experimental).",

255 },255 },

256 {

257 key: "skills.max_context_tokens",

258 type: "integer (positive)",

259 description:

260 "Token budget for the available-skills catalog. Defaults to 2% of the model's context window. Explicit values are capped at `10000` tokens.",

261 },

256 {262 {

257 key: "skills.config",263 key: "skills.config",

258 type: "array<object>",264 type: "array<object>",

427 key: "hooks.<Event>",433 key: "hooks.<Event>",

428 type: "array<table>",434 type: "array<table>",

429 description:435 description:

430 "Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.",436 "Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `Stop`, or `Interrupt`.",

431 },437 },

432 {438 {

433 key: "hooks.<Event>[].hooks",439 key: "hooks.<Event>[].hooks",

459 description:465 description:

460 "Enable [Memories](https://learn.chatgpt.com/docs/customization/memories) (off by default).",466 "Enable [Memories](https://learn.chatgpt.com/docs/customization/memories) (off by default).",

461 },467 },

468 {

469 key: "mcp_optional_startup_grace_ms",

470 type: "integer (milliseconds)",

471 description:

472 "Shared wait for optional MCP servers when building the initial tool catalog. Defaults to `1000`. Set to `0` to wait for each server's `startup_timeout_sec` instead.",

473 },

462 {474 {

463 key: "mcp_servers.<id>.command",475 key: "mcp_servers.<id>.command",

464 type: "string",476 type: "string",

525 type: "map<string,string>",537 type: "map<string,string>",

526 description: "Static HTTP headers included with each MCP HTTP request.",538 description: "Static HTTP headers included with each MCP HTTP request.",

527 },539 },

540 {

541 key: "mcp_servers.<id>.http_headers_helper",

542 type: "string (command)",

543 description:

544 "Local command that prints a JSON object of HTTP header names and values. Supported only for locally connected HTTP MCP servers. Explicit bearer tokens and OAuth credentials take precedence over helper-provided Authorization headers.",

545 },

528 {546 {

529 key: "mcp_servers.<id>.env_http_headers",547 key: "mcp_servers.<id>.env_http_headers",

530 type: "map<string,string>",548 type: "map<string,string>",

582 description:600 description:

583 "Per-tool approval behavior override for one MCP tool on this server.",601 "Per-tool approval behavior override for one MCP tool on this server.",

584 },602 },

603 {

604 key: "mcp_servers.<id>.tools.<tool>.output_token_limit",

605 type: "integer (positive)",

606 description:

607 "Token budget for one MCP tool's output, before the standard 20% serialization allowance. Overrides the model's default output truncation budget for that tool.",

608 },

585 {609 {

586 key: "mcp_servers.<id>.scopes",610 key: "mcp_servers.<id>.scopes",

587 type: "array<string>",611 type: "array<string>",

253 description:253 description:

254 "Load the compaction prompt override from a file (experimental).",254 "Load the compaction prompt override from a file (experimental).",

255 },255 },

256 {

257 key: "skills.max_context_tokens",

258 type: "integer (positive)",

259 description:

260 "Token budget for the available-skills catalog. Defaults to 2% of the model's context window. Explicit values are capped at `10000` tokens.",

261 },

256 {262 {

257 key: "skills.config",263 key: "skills.config",

258 type: "array<object>",264 type: "array<object>",

427 key: "hooks.<Event>",433 key: "hooks.<Event>",

428 type: "array<table>",434 type: "array<table>",

429 description:435 description:

430 "Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.",436 "Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `Stop`, or `Interrupt`.",

431 },437 },

432 {438 {

433 key: "hooks.<Event>[].hooks",439 key: "hooks.<Event>[].hooks",

459 description:465 description:

460 "Enable [Memories](https://learn.chatgpt.com/docs/customization/memories) (off by default).",466 "Enable [Memories](https://learn.chatgpt.com/docs/customization/memories) (off by default).",

461 },467 },

468 {

469 key: "mcp_optional_startup_grace_ms",

470 type: "integer (milliseconds)",

471 description:

472 "Shared wait for optional MCP servers when building the initial tool catalog. Defaults to `1000`. Set to `0` to wait for each server's `startup_timeout_sec` instead.",

473 },

462 {474 {

463 key: "mcp_servers.<id>.command",475 key: "mcp_servers.<id>.command",

464 type: "string",476 type: "string",

525 type: "map<string,string>",537 type: "map<string,string>",

526 description: "Static HTTP headers included with each MCP HTTP request.",538 description: "Static HTTP headers included with each MCP HTTP request.",

527 },539 },

540 {

541 key: "mcp_servers.<id>.http_headers_helper",

542 type: "string (command)",

543 description:

544 "Local command that prints a JSON object of HTTP header names and values. Supported only for locally connected HTTP MCP servers. Explicit bearer tokens and OAuth credentials take precedence over helper-provided Authorization headers.",

545 },

528 {546 {

529 key: "mcp_servers.<id>.env_http_headers",547 key: "mcp_servers.<id>.env_http_headers",

530 type: "map<string,string>",548 type: "map<string,string>",

582 description:600 description:

583 "Per-tool approval behavior override for one MCP tool on this server.",601 "Per-tool approval behavior override for one MCP tool on this server.",

584 },602 },

603 {

604 key: "mcp_servers.<id>.tools.<tool>.output_token_limit",

605 type: "integer (positive)",

606 description:

607 "Token budget for one MCP tool's output, before the standard 20% serialization allowance. Overrides the model's default output truncation budget for that tool.",

608 },

585 {609 {

586 key: "mcp_servers.<id>.scopes",610 key: "mcp_servers.<id>.scopes",

587 type: "array<string>",611 type: "array<string>",

225 225 

226mcp_oauth_credentials_store = "auto"226mcp_oauth_credentials_store = "auto"

227 227 

228# Shared wait for optional MCP servers before building the initial tool catalog.

229 

230# Default: 1000 ms. Set to 0 to wait for each server's startup_timeout_sec instead.

231 

232# mcp_optional_startup_grace_ms = 1000

233 

228# Optional global fixed port for MCP OAuth callback: 1-65535. Default: unset.234# Optional global fixed port for MCP OAuth callback: 1-65535. Default: unset.

229 235 

230# A server-specific oauth.callback_port overrides this global listener port.236# A server-specific oauth.callback_port overrides this global listener port.

377 383 

378################################################################################384################################################################################

379 385 

386# Token budget for the available-skills catalog. Default: 2% of the model context

387 

388# window. Explicit values must be positive and are capped at 10000 tokens.

389 

390# [skills]

391 

392# max_context_tokens = 2000

393 

380# Disable or re-enable a specific skill without deleting it.394# Disable or re-enable a specific skill without deleting it.

381 395 

382[[skills.config]]396[[skills.config]]

837 851 

838# oauth_resource = "https://docs.example.com/" # optional OAuth resource852# oauth_resource = "https://docs.example.com/" # optional OAuth resource

839 853 

854# [mcp_servers.docs.tools.search]

855 

856# output_token_limit = 30000 # positive token budget, before the 20% serialization allowance

857 

840# --- Example: Streamable HTTP transport ---858# --- Example: Streamable HTTP transport ---

841 859 

842# [mcp_servers.github]860# [mcp_servers.github]

853 871 

854# env_http_headers = { "X-Auth" = "AUTH_ENV" } # optional headers populated from env vars872# env_http_headers = { "X-Auth" = "AUTH_ENV" } # optional headers populated from env vars

855 873 

874# http_headers_helper = "company-auth mcp-headers" # local command that prints a JSON header map

875 

856# startup_timeout_sec = 10.0 # optional876# startup_timeout_sec = 10.0 # optional

857 877 

858# tool_timeout_sec = 60.0 # optional878# tool_timeout_sec = 60.0 # optional

23| When | Hooks |23| When | Hooks |

24| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |24| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |

25| During a turn | `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStop`, `Stop` |25| During a turn | `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStop`, `Stop` |

26| When you interrupt an active turn | `Interrupt` (doesn't run for subagents) |

26| When a session or subagent starts | `SessionStart`, `SubagentStart` |27| When a session or subagent starts | `SessionStart`, `SubagentStart` |

27| When the main thread ends | `SessionEnd` (doesn't run for subagents) |28| When the main thread ends | `SessionEnd` (doesn't run for subagents) |

28 29 

180 doesn't change which hooks run.181 doesn't change which hooks run.

181- `timeout` is in seconds.182- `timeout` is in seconds.

182- If `timeout` is omitted, Codex uses `600` seconds for most hooks.183- If `timeout` is omitted, Codex uses `600` seconds for most hooks.

183 - `SessionEnd` uses `1` second by default and supports up to `3` seconds.184 - `SessionEnd` and `Interrupt` use `1` second by default and support up to `3` seconds.

184- `statusMessage` is optional.185- `statusMessage` is optional.

185- `additionalContextLimit` sets how much `additionalContext` a command hook can186- `additionalContextLimit` sets how much `additionalContext` a command hook can

186 send to the model before Codex saves the full text to disk and sends a shorter187 send to the model before Codex saves the full text to disk and sends a shorter

420| `SubagentStop` | subagent type | Values depend on the subagent that stops |421| `SubagentStop` | subagent type | Values depend on the subagent that stops |

421| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |422| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

422| `Stop` | not supported | Any configured `matcher` is ignored for this event |423| `Stop` | not supported | Any configured `matcher` is ignored for this event |

424| `Interrupt` | not supported | Any configured `matcher` is ignored for this event |

423 425 

424\*For `apply_patch`, `matcher` values can also use `Edit` or `Write`.426\*For `apply_patch`, `matcher` values can also use `Edit` or `Write`.

425 427 

473event-specific tables.475event-specific tables.

474 476 

475`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,477`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,

476`UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop` also include478`UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop`, and `Interrupt` also include

477`permission_mode`, which describes the current permission mode as `default`,479`permission_mode`, which describes the current permission mode as `default`,

478`acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.480`acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.

479 481 

602Background hooks use the same input, matcher, trust review, timeout, and604Background hooks use the same input, matcher, trust review, timeout, and

603[large-output handling](#large-hook-output) as synchronous command hooks. As605[large-output handling](#large-hook-output) as synchronous command hooks. As

604with other command hooks, `timeout` is measured in seconds and defaults to606with other command hooks, `timeout` is measured in seconds and defaults to

605`600`.607`600`. `Interrupt` hooks use a one-second default and a three-second maximum,

608including when they run in the background.

606 609 

607### How background hooks run610### How background hooks run

608 611 

1086If any matching `Stop` hook returns `continue: false`, that takes precedence1089If any matching `Stop` hook returns `continue: false`, that takes precedence

1087over continuation decisions from other matching `Stop` hooks.1090over continuation decisions from other matching `Stop` hooks.

1088 1091 

1092### Interrupt

1093 

1094`Interrupt` runs when you interrupt an active turn on the main thread. Use it

1095to record the interruption or clean up work started by a hook. It doesn't run

1096for idle threads or subagents, and any configured `matcher` is ignored.

1097 

1098In addition to [Common input fields](#common-input-fields), the event includes

1099`turn_id`, the interrupted turn's id, and `permission_mode`.

1100 

1101Command hooks default to a one-second timeout. Configured timeouts are

1102limited to one through three seconds. Hook output can't prevent the

1103interruption or restart the turn. Exit `0` with no output, or return JSON with

1104an optional `systemMessage` to surface a warning. Plain text output is invalid

1105for this event.

1106 

1107```json

1108{ "systemMessage": "Saved the interrupted turn to the local audit log." }

1109```

1110 

1089## Schemas1111## Schemas

1090 1112 

1091The linked `main` branch schemas may include hook fields that are not in the1113The linked `main` branch schemas may include hook fields that are not in the

168- `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.168- `bearer_token_env_var` (optional): Environment variable name for a bearer token to send in `Authorization`.

169- `http_headers` (optional): Map of header names to static values.169- `http_headers` (optional): Map of header names to static values.

170- `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).170- `env_http_headers` (optional): Map of header names to environment variable names (values pulled from the environment).

171- `http_headers_helper` (optional): Local command that prints a JSON object of

172 header names and string values, such as `{"X-Auth": "temporary-token"}`.

173 Supported for HTTP MCP connections made from the local environment; not for

174 stdio servers or connections made through a remote execution environment.

175 

176Codex caches helper headers for the connection. After a same-origin POST

177returns `401` or `403`, it refreshes the headers once and retries only if the

178helper returns changed values. Explicit bearer tokens and OAuth credentials

179take precedence over a helper-provided `Authorization` header.

180An OAuth `403` response that reports insufficient scope doesn't trigger a

181helper refresh.

171 182 

172If no credential source resolves, Codex can connect to the server without183If no credential source resolves, Codex can connect to the server without

173authentication. Run `codex mcp login <server-name>` separately to start an MCP184authentication. Run `codex mcp login <server-name>` separately to start an MCP

185 tools from this server. Supported values are `auto`, `prompt`, `writes`, and196 tools from this server. Supported values are `auto`, `prompt`, `writes`, and

186 `approve`. The `writes` mode prompts for tools that aren't marked read-only.197 `approve`. The `writes` mode prompts for tools that aren't marked read-only.

187- `tools.<tool>.approval_mode` (optional): Per-tool approval behavior override.198- `tools.<tool>.approval_mode` (optional): Per-tool approval behavior override.

199- `tools.<tool>.output_token_limit` (optional): Positive token budget for one

200 tool's output, before the standard 20% serialization allowance. Overrides the

201 model's default output truncation budget for that tool.

202 

203The top-level `mcp_optional_startup_grace_ms` setting controls how long Codex

204waits for optional MCP servers when building the initial tool catalog. It

205defaults to `1000` milliseconds. Set it to `0` to wait for each server's

206`startup_timeout_sec` instead. Required servers still use their startup

207timeouts.

188 208 

189#### OAuth client registration and callbacks209#### OAuth client registration and callbacks

190 210 

356 376 

357[mcp_servers.chrome_devtools.tools.open]377[mcp_servers.chrome_devtools.tools.open]

358approval_mode = "approve"378approval_mode = "approve"

379output_token_limit = 30000

359```380```

360 381 

361### Plugin-provided MCP servers382### Plugin-provided MCP servers