Documentation — Spybara

agent-approvals-security.md +36 −8

Details

14Codex CLI, and IDE extension, see [sandboxing](https://learn.chatgpt.com/docs/sandboxing).14Codex CLI, and IDE extension, see [sandboxing](https://learn.chatgpt.com/docs/sandboxing).

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

16 16

17## Migrate from the retired `untrusted` approval policy

19Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.

20The retired setting can prevent either client from starting. Remove it from

21user or project configuration, profile files, startup scripts, and managed

22defaults. For interactive, read-only use:

24```toml

25sandbox_mode = "read-only"

26approval_policy = "on-request"

27```

29Or run `codex --sandbox read-only --ask-for-approval on-request`.

31With `on-request`, commands allowed by the sandbox can run without approval,

32read accessible files, and use network access if enabled.

34To preserve the stricter command-approval rule, omit an explicit

35`approval_policy` and add a project entry to your user-level

36`~/.codex/config.toml`:

38```toml

39[projects."/path/to/project"]

40trust_level = "untrusted"

41```

43Commands then require approval unless an execution-policy rule allows them.

44This also disables project-local configuration. Explicitly setting `on-request`

45overrides the project-derived policy; managed `allowed_approval_policies` must

46include `untrusted` to permit it.

17## Sandbox and approvals48## Sandbox and approvals

18 49

19Codex security controls come from two layers that work together:50Codex security controls come from two layers that work together:

313### Common sandbox and approval combinations344### Common sandbox and approval combinations

314 345

316| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |347| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

317| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |348| Auto (preset) | _no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request` | Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network. |

318| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network. |349| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` | Codex can read files and run commands within the read-only sandbox. Actions outside the sandbox can require approval. |

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

321| 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. |351| 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. |

323 353

324For 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.354For 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.

325 355

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

~~327~~

328#### Configuration in `config.toml`356#### Configuration in `config.toml`

329 357

330For the broader configuration workflow, see [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), [Advanced Config](https://learn.chatgpt.com/docs/config-file/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).358For the broader configuration workflow, see [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), [Advanced Config](https://learn.chatgpt.com/docs/config-file/config-advanced#approval-policies-and-sandbox-modes), and the [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).

331 359

332```toml360```toml

333# Always ask for approval mode361# Interactive approvals with a read-only sandbox

334approval_policy = "untrusted"362approval_policy = "on-request"

335sandbox_mode = "read-only"363sandbox_mode = "read-only"

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

337 365

auth.md +10 −3

Details

248Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:248Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:

249 249

250```toml250```toml

252cli_auth_credentials_store = "keyring"252cli_auth_credentials_store = "keyring"

253```253```

254 254

255- `file` stores credentials in `auth.json` under `CODEX_HOME` (defaults to `~/.codex`).255- `file` stores credentials in `auth.json` under `CODEX_HOME` (defaults to `~/.codex`).

256- `keyring` stores credentials in your operating system credential store.256- `keyring` stores credentials in your operating system credential store and fails if it is unavailable.

257- `auto` uses the OS credential store when available, otherwise falls back to `auth.json`.257- `auto` uses the OS credential store when available, otherwise falls back to `auth.json`.

258- `ephemeral` keeps credentials in memory only for the current process.

258 259

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

260`config.toml` schema.261`config.toml` schema.

261 262

263Admins can enforce `cli_auth_credentials_store` and `chatgpt_base_url` through

264[local authentication requirements](https://learn.chatgpt.com/docs/enterprise/managed-configuration#manage-authentication-locally).

265Users can't override those requirements through `config.toml` or CLI overrides.

266

262If you use file-based storage, treat `~/.codex/auth.json` like a password: it267If you use file-based storage, treat `~/.codex/auth.json` like a password: it

263 contains access tokens. Don't commit it, paste it into tickets, or share it in268 contains access tokens. Don't commit it, paste it into tickets, or share it in

264 chat.269 chat.

277 282

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

279 284

280These settings are commonly applied via managed configuration rather than per-user setup. See [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).285These settings can also be supplied through legacy managed configuration.

286For admin-enforced login restrictions, see

287[Manage authentication locally](https://learn.chatgpt.com/docs/enterprise/managed-configuration#manage-authentication-locally).

281 288

282</ContentModeSwitch>289</ContentModeSwitch>

283 290

concepts/sandboxing.md +5 −2

Details

227 227

228The common approval policies are:228The common approval policies are:

229 229

230- `untrusted`: The agent asks before running commands that aren't in its trusted

231 set.

232- `on-request`: The agent works inside the sandbox by default and asks when it230- `on-request`: The agent works inside the sandbox by default and asks when it

233 needs to go beyond that boundary.231 needs to go beyond that boundary.

234- `never`: The agent doesn't stop for approval prompts.232- `never`: The agent doesn't stop for approval prompts.

235 233

234Codex and ChatGPT Work no longer support `untrusted` as a selectable approval

235policy. If an existing configuration uses that value, see [Migrate from the

236retired `untrusted` approval

237policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy).

238

236When approvals are interactive, you can also choose who reviews them with239When approvals are interactive, you can also choose who reviews them with

237`approvals_reviewer`:240`approvals_reviewer`:

238 241

config-advanced.md +5 −1

Details

303 303

304For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), [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).304For operational details to keep in mind while editing `config.toml`, see [Common sandbox and approval combinations](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), [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).

305 305

306Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`. See

307[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)

308for supported settings and stricter project-derived approvals.

309

306For beta permission profiles that configure filesystem and network access together, see [Permissions](https://learn.chatgpt.com/docs/permissions).310For beta permission profiles that configure filesystem and network access together, see [Permissions](https://learn.chatgpt.com/docs/permissions).

307 311

308You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically.312You can also use a granular approval policy (`approval_policy = { granular = { ... } }`) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such as `request_permissions` or skill-script prompts, to fail closed automatically.

315`guardian_policy_config` takes precedence.319`guardian_policy_config` takes precedence.

316 320

317```toml321```toml

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

319approvals_reviewer = "user" # Or "auto_review" for automatic review323approvals_reviewer = "user" # Or "auto_review" for automatic review

320sandbox_mode = "workspace-write"324sandbox_mode = "workspace-write"

321allow_login_shell = false # Optional hardening: disallow login shells for shell tools325allow_login_shell = false # Optional hardening: disallow login shells for shell tools

config-basic.md +8 −3

Details

242. Project config files: `.codex/config.toml`, ordered from the project root down to your current working directory (closest wins; trusted projects only)242. Project config files: `.codex/config.toml`, ordered from the project root down to your current working directory (closest wins; trusted projects only)

253. [Profile](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles) files selected with `--profile profile-name` (`~/.codex/profile-name.config.toml`)253. [Profile](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles) files selected with `--profile profile-name` (`~/.codex/profile-name.config.toml`)

264. User config: `~/.codex/config.toml`264. User config: `~/.codex/config.toml`

~~275. System config (if present): `/etc/codex/config.toml` on Unix~~275. Cloud-managed `config.toml` defaults, when delivered for the signed-in workspace

~~286. Built-in defaults~~286. System config (if present): `/etc/codex/config.toml` on Unix

297. Built-in defaults

29 30

30Use that precedence to set shared defaults in `config.toml` and keep [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles) focused on the values that differ.31Use that precedence to set shared defaults in `config.toml` and keep [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles) focused on the values that differ.

31 32

33Cloud-managed and system configuration can define plugin marketplaces and set

34whether plugins are enabled by default. These are separate from enforced `requirements.toml`

35policies. See [Configure plugin marketplaces and defaults](https://learn.chatgpt.com/docs/enterprise/managed-configuration#configure-plugin-marketplaces-and-defaults).

32If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.37If you mark a project as untrusted, Codex skips project-scoped `.codex/` layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules.

33 38

34For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://learn.chatgpt.com/docs/config-file/config-advanced#one-off-overrides-from-the-cli).39For one-off overrides via `-c`/`--config` (including TOML quoting rules), see [Advanced Config](https://learn.chatgpt.com/docs/config-file/config-advanced#one-off-overrides-from-the-cli).

60approval_policy = "on-request"65approval_policy = "on-request"

61```66```

62 67

63For behavior differences between `untrusted`, `on-request`, and `never`, see [Run without approval prompts](https://learn.chatgpt.com/docs/agent-approvals-security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations).68For behavior differences between `on-request` and `never`, see [Run without approval prompts](https://learn.chatgpt.com/docs/agent-approvals-security#run-without-approval-prompts) and [Common sandbox and approval combinations](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations). If an existing configuration uses `approval_policy = "untrusted"`, see [Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy).

64 69

65#### Sandbox level70#### Sandbox level

66 71

config-file/config-reference.md +70 −7

Details

21 21

22For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [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). For beta permission profiles, see [Permissions](https://learn.chatgpt.com/docs/permissions).22For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [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). For beta permission profiles, see [Permissions](https://learn.chatgpt.com/docs/permissions).

23 23

24Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.

25Remove the setting or choose a supported policy. Project entries with

26`trust_level = "untrusted"` in user-level `~/.codex/config.toml` remain supported. See

27[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)

28for examples and approval tradeoffs.

24<ConfigTable30<ConfigTable

25 options={[31 options={[

26 {32 {

76 },82 },

77 {83 {

78 key: "approval_policy",84 key: "approval_policy",

~~79 type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",~~85 type: "on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",

80 description:86 description:

81 "Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.",87 "Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { granular = { ... } }` to allow or auto-reject specific prompt categories while keeping other prompts interactive. `untrusted` is unsupported, and `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.",

82 },88 },

83 {89 {

84 key: "approval_policy.granular.sandbox_approval",90 key: "approval_policy.granular.sandbox_approval",

1419 description:1425 description:

1420 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.",1426 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.",

1421 },1427 },

1428 {

1429 key: "marketplaces.<name>.source_type",

1430 type: "git | local",

1431 description:

1432 "Source kind for a configured plugin marketplace. Marketplaces can be defined in system, cloud-managed, user, or trusted-project config.toml.",

1433 },

1434 {

1435 key: "marketplaces.<name>.source",

1436 type: "string",

1437 description:

1438 "Git repository location or local marketplace root directory. Use an absolute path for a local source; the directory contains .agents/plugins/marketplace.json.",

1439 },

1440 {

1441 key: "marketplaces.<name>.ref",

1442 type: "string",

1443 description: "Optional Git branch, tag, or commit for the marketplace.",

1444 },

1445 {

1446 key: "marketplaces.<name>.sparse_paths",

1447 type: "array<string>",

1448 description:

1449 "Optional sparse checkout paths for a Git marketplace. Include the marketplace catalog and any local plugin directories it references.",

1450 },

1451 {

1452 key: "plugins.<plugin>.enabled",

1453 type: "boolean",

1454 description:

1455 "Enable or disable a local-marketplace plugin using a `plugin-name@marketplace-name` key. Read from the effective merged config; trusted-project settings can override user, cloud-managed, and system defaults. Marketplace refresh can install or refresh configured plugins even when disabled. This does not override workspace-managed enabled states.",

1456 },

1422 {1457 {

1423 key: "plugins.<plugin>.mcp_servers.<server>.enabled",1458 key: "plugins.<plugin>.mcp_servers.<server>.enabled",

1424 type: "boolean",1459 type: "boolean",

1483 },1518 },

1484 {1519 {

1485 key: "cli_auth_credentials_store",1520 key: "cli_auth_credentials_store",

1487 description:1522 description: "Control where the CLI stores cached credentials.",

1488 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",

1489 },1523 },

1490 {1524 {

1491 key: "mcp_oauth_credentials_store",1525 key: "mcp_oauth_credentials_store",

1748deployments, use `allowed_permission_profiles` with managed1782deployments, use `allowed_permission_profiles` with managed

1749`default_permissions`.1783`default_permissions`.

1750 1784

1785An `untrusted` entry in `allowed_approval_policies` is still valid for the

1786stricter approval behavior Codex derives when a project uses

1787`trust_level = "untrusted"`. It does not permit explicitly setting

1788`approval_policy = "untrusted"`.

1789

1751The `[models.new_thread]` table supplies managed defaults, not enforcement.1790The `[models.new_thread]` table supplies managed defaults, not enforcement.

1752Explicit launch choices from dedicated CLI flags or `--config` overrides take1791Explicit launch choices from dedicated CLI flags or `--config` overrides take

1753precedence. An explicit model or reasoning-effort override skips both managed1792precedence. An explicit model or reasoning-effort override skips both managed

1792 type: "boolean",1831 type: "boolean",

1793 description: "Enforce whether shell tools can start a login shell.",1832 description: "Enforce whether shell tools can start a login shell.",

1794 },1833 },

1834 {

1835 key: "allowed_login_methods",

1836 type: "array<string>",

1837 description:

1838 "Allow `chatgpt`, `api`, or both. If omitted, this setting doesn't restrict login methods. If set, the list must contain at least one method. `api` permits API authentication, including Amazon Bedrock. Set through the local system requirements file or macOS MDM. Cloud-managed values are ignored.",

1839 },

1840 {

1841 key: "allowed_chatgpt_workspaces",

1842 type: "array<string>",

1843 description:

1844 "Restrict ChatGPT login, including Codex access tokens, to the listed workspace IDs. An empty list disables ChatGPT login; API authentication remains available when permitted. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.",

1845 },

1846 {

1847 key: "cli_auth_credentials_store",

1848 type: "file | keyring | auto | ephemeral",

1849 description:

1850 "Enforce the CLI credential store before authentication loads. `file` uses `CODEX_HOME/auth.json`; `keyring` requires the OS credential store; `auto` falls back to a file if the credential store is unavailable; `ephemeral` keeps credentials in memory for the current process. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.",

1851 },

1852 {

1853 key: "chatgpt_base_url",

1854 type: "string",

1855 description:

1856 "Enforce the ChatGPT service base URL before authentication and cloud-policy retrieval. This doesn't configure every Codex network destination. Set through the local system requirements file or macOS MDM; cloud-managed values are ignored.",

1857 },

1795 {1858 {

1796 key: "feedback",1859 key: "feedback",

1797 type: "table",1860 type: "table",

1807 key: "allowed_approval_policies",1870 key: "allowed_approval_policies",

1808 type: "array<string>",1871 type: "array<string>",

1809 description:1872 description:

1810 "Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`).",1873 "Allowed approval policies, such as `on-request`, `never`, and `granular`. Include `untrusted` to permit the stricter policy derived from an untrusted project; it cannot be selected directly with `approval_policy`.",

1811 },1874 },

1812 {1875 {

1813 key: "allowed_approvals_reviewers",1876 key: "allowed_approvals_reviewers",

2566 key: "marketplaces.restrict_to_allowed_sources",2629 key: "marketplaces.restrict_to_allowed_sources",

2567 type: "boolean",2630 type: "boolean",

2568 description:2631 description:

2569 "When `true`, require user-configured marketplace sources to match `allowed_sources` for marketplace add, plugin install, and configured Git marketplace refresh operations. Codex-managed OpenAI marketplaces remain allowed when their reserved source and name match. This doesn't filter already configured user marketplaces at runtime.",2632 "When `true`, require configured marketplace sources to match `allowed_sources` for marketplace add, plugin install, refresh, and runtime loading. OpenAI-curated Git catalogs, including the API-key catalog, must also match the allowlist. Bundled and remotely installed workspace plugins are separate from this curated Git source policy.",

2570 },2633 },

2571 {2634 {

2572 key: "marketplaces.allowed_sources",2635 key: "marketplaces.allowed_sources",

config-reference.md +70 −7

Details

21 21

23 23

24Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.

25Remove the setting or choose a supported policy. Project entries with

26`trust_level = "untrusted"` in user-level `~/.codex/config.toml` remain supported. See

27[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)

28for examples and approval tradeoffs.

24<ConfigTable30<ConfigTable

25 options={[31 options={[

26 {32 {

76 },82 },

77 {83 {

78 key: "approval_policy",84 key: "approval_policy",

80 description:86 description:

82 },88 },

83 {89 {

84 key: "approval_policy.granular.sandbox_approval",90 key: "approval_policy.granular.sandbox_approval",

1419 description:1425 description:

1421 },1427 },

1428 {

1429 key: "marketplaces.<name>.source_type",

1430 type: "git | local",

1431 description:

1432 "Source kind for a configured plugin marketplace. Marketplaces can be defined in system, cloud-managed, user, or trusted-project config.toml.",

1433 },

1434 {

1435 key: "marketplaces.<name>.source",

1436 type: "string",

1437 description:

1438 "Git repository location or local marketplace root directory. Use an absolute path for a local source; the directory contains .agents/plugins/marketplace.json.",

1439 },

1440 {

1441 key: "marketplaces.<name>.ref",

1442 type: "string",

1443 description: "Optional Git branch, tag, or commit for the marketplace.",

1444 },

1445 {

1446 key: "marketplaces.<name>.sparse_paths",

1447 type: "array<string>",

1448 description:

1449 "Optional sparse checkout paths for a Git marketplace. Include the marketplace catalog and any local plugin directories it references.",

1450 },

1451 {

1452 key: "plugins.<plugin>.enabled",

1453 type: "boolean",

1454 description:

1456 },

1422 {1457 {

1423 key: "plugins.<plugin>.mcp_servers.<server>.enabled",1458 key: "plugins.<plugin>.mcp_servers.<server>.enabled",

1424 type: "boolean",1459 type: "boolean",

1483 },1518 },

1484 {1519 {

1485 key: "cli_auth_credentials_store",1520 key: "cli_auth_credentials_store",

1487 description:1522 description: "Control where the CLI stores cached credentials.",

1488 "Control where the CLI stores cached credentials (file-based auth.json vs OS keychain).",

1489 },1523 },

1490 {1524 {

1491 key: "mcp_oauth_credentials_store",1525 key: "mcp_oauth_credentials_store",

1748deployments, use `allowed_permission_profiles` with managed1782deployments, use `allowed_permission_profiles` with managed

1749`default_permissions`.1783`default_permissions`.

1750 1784

1785An `untrusted` entry in `allowed_approval_policies` is still valid for the

1786stricter approval behavior Codex derives when a project uses

1787`trust_level = "untrusted"`. It does not permit explicitly setting

1788`approval_policy = "untrusted"`.

1789

1751The `[models.new_thread]` table supplies managed defaults, not enforcement.1790The `[models.new_thread]` table supplies managed defaults, not enforcement.

1752Explicit launch choices from dedicated CLI flags or `--config` overrides take1791Explicit launch choices from dedicated CLI flags or `--config` overrides take

1753precedence. An explicit model or reasoning-effort override skips both managed1792precedence. An explicit model or reasoning-effort override skips both managed

1792 type: "boolean",1831 type: "boolean",

1793 description: "Enforce whether shell tools can start a login shell.",1832 description: "Enforce whether shell tools can start a login shell.",

1794 },1833 },

1834 {

1835 key: "allowed_login_methods",

1836 type: "array<string>",

1837 description:

1839 },

1840 {

1841 key: "allowed_chatgpt_workspaces",

1842 type: "array<string>",

1843 description:

1845 },

1846 {

1847 key: "cli_auth_credentials_store",

1848 type: "file | keyring | auto | ephemeral",

1849 description:

1851 },

1852 {

1853 key: "chatgpt_base_url",

1854 type: "string",

1855 description:

1857 },

1795 {1858 {

1796 key: "feedback",1859 key: "feedback",

1797 type: "table",1860 type: "table",

1807 key: "allowed_approval_policies",1870 key: "allowed_approval_policies",

1808 type: "array<string>",1871 type: "array<string>",

1809 description:1872 description:

1811 },1874 },

1812 {1875 {

1813 key: "allowed_approvals_reviewers",1876 key: "allowed_approvals_reviewers",

2566 key: "marketplaces.restrict_to_allowed_sources",2629 key: "marketplaces.restrict_to_allowed_sources",

2567 type: "boolean",2630 type: "boolean",

2568 description:2631 description:

2570 },2633 },

2571 {2634 {

2572 key: "marketplaces.allowed_sources",2635 key: "marketplaces.allowed_sources",

config-sample.md +0 −2

Details

139 139

140# When to ask for command approval:140# When to ask for command approval:

141 141

142# - untrusted: only known-safe read-only commands auto-run; others prompt

~~143~~

144# - on-request: model decides when to ask (default)142# - on-request: model decides when to ask (default)

145 143

146# - never: never prompt (risky)144# - never: never prompt (risky)

enterprise/apps-and-connectors.md +27 −27

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

~~5Plugins package reusable workflows and can include skills and apps that connect~~5Plugins package reusable workflows and can include skills and MCP servers that connect

6to other tools. ChatGPT and Codex use the same public plugin directory on6to other tools. ChatGPT and Codex use the same public plugin directory on

7supported surfaces, while admins decide which plugins are available in their workspace.7supported surfaces, while admins decide which plugins are available in their workspace.

8Learn more about [plugins](https://learn.chatgpt.com/docs/plugins),8Learn more about [plugins](https://learn.chatgpt.com/docs/plugins),

9[skills](https://learn.chatgpt.com/docs/skills-and-plugins), and9[skills](https://learn.chatgpt.com/docs/skills-and-plugins), and

~~10[apps and connectors](https://help.openai.com/en/articles/11487775).~~10[connected services](https://help.openai.com/en/articles/11487775).

11 11

~~12A member can use a connector-backed capability only when the plugin and app are~~12A member can use an MCP server's capabilities only when the plugin and MCP server are

13available to their role and they have access to the connected service.13available to their role and they have access to the connected service.

14 14

15Plugins work in Chat and Work across ChatGPT on the web, desktop, and mobile,15Plugins work in Chat and Work across ChatGPT on the web, desktop, and mobile,

24A plugin can span these control layers:24A plugin can span these control layers:

25 25

27| ----------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |27| ----------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |

28| Availability | Whether the plugin bundle is available to the user | [Workspace settings](https://chatgpt.com/admin/settings) for supported web and desktop surfaces; the CLI plugin browser for CLI |28| Availability | Whether the plugin bundle is available to the user | [Workspace settings](https://chatgpt.com/admin/settings) for supported web and desktop surfaces; the CLI plugin browser for CLI |

31| Actions and permissions | Which actions users can run and when ChatGPT asks before using the connector | The connector's Action control and App permissions in [Workspace apps](https://chatgpt.com/admin/ca) |31| Actions and permissions | Which actions users can run and when ChatGPT asks before using its tools | The connection's **Action control** and **App permissions** in [Workspace apps](https://chatgpt.com/admin/ca) |

34 34

50 50

51Eligible ChatGPT Enterprise workspace owners and admins can download a CSV of51Eligible ChatGPT Enterprise workspace owners and admins can download a CSV of

52the public plugins available to their workspace. Use the export to review52the public plugins available to their workspace. Use the export to review

~~53plugin, app, and skill metadata before changing plugin availability.~~53plugin, MCP server, and skill metadata before changing plugin availability.

54 54

551. Open [Admin > Plugins](https://chatgpt.com/admin/plugins).551. Open [Admin > Plugins](https://chatgpt.com/admin/plugins).

562. Select **Public**.562. Select **Public**.

60 60

61- Plugin metadata: `Plugin Name`, `Plugin Description`, `Date Added (UTC)`,61- Plugin metadata: `Plugin Name`, `Plugin Description`, `Date Added (UTC)`,

62 `OpenAI Verified`, `Developer Name`, and `Version`.62 `OpenAI Verified`, `Developer Name`, and `Version`.

~~63- App metadata: `App Name(s)` and `App Description(s)`.~~63- MCP server metadata: `App Name(s)` and `App Description(s)`.

64- Chat skill metadata: `Skill Name(s)` and `Skill Description(s)`.64- Chat skill metadata: `Skill Name(s)` and `Skill Description(s)`.

65 65

~~66When a plugin includes more than one app or skill, semicolons separate the~~66When a plugin includes more than one MCP server or skill, semicolons separate the

67corresponding values. The export uses a public-catalog snapshot that can be up67corresponding values. The export uses a public-catalog snapshot that can be up

68to 48 hours old,68to 48 hours old,

69includes only public plugins visible to the current workspace, and does not69includes only public plugins visible to the current workspace, and does not

73## Step 2: Manage capabilities73## Step 2: Manage capabilities

74 74

75<WarningTip>75<WarningTip>

~~76 Making an app or plugin available in ChatGPT doesn't grant access to files,~~76 Making an MCP server or plugin available in ChatGPT doesn't grant access to

~~77 records, or actions in the connected service. Before troubleshooting or~~77 files, records, or actions in the connected service. Before troubleshooting or

78 expanding access, check the member's workspace role and approved action78 expanding access, check the member's workspace role and approved action

79 settings. Then confirm the authenticated account or shared connection has the79 settings. Then confirm the authenticated account or shared connection has the

80 expected permissions in the connected service.80 expected permissions in the connected service.

81</WarningTip>81</WarningTip>

82 82

~~83Plugins in ChatGPT and Codex can include connectors that search, retrieve, sync,~~83Plugins in ChatGPT and Codex can include MCP server connections that search, retrieve, sync,

84or act on external systems. Plugin availability and the access and actions84or act on external systems. Plugin availability and the access and actions

~~85granted to each connector are separate controls.~~85granted to each connection are separate controls.

86 86

~~87Manage connector-backed capabilities from~~87Manage MCP server capabilities from

88[Workspace apps](https://chatgpt.com/admin/ca) and88[Workspace apps](https://chatgpt.com/admin/ca) and

89[Permissions & roles](https://chatgpt.com/admin/settings). Available controls89[Permissions & roles](https://chatgpt.com/admin/settings). Available controls

90let admins:90let admins:

91 91

~~92- Enable apps or connectors and assign access by workspace role.~~92- Enable MCP server connections and assign access by workspace role.

~~93- For connectors that support Action control, allow read-only actions or an~~93- For connections that support **Action control**, allow read-only actions or an

94 approved custom set, including how the workspace handles newly added actions.94 approved custom set, including how the workspace handles newly added actions.

~~95- Set App permissions that determine when ChatGPT asks before using an app.~~95- Set **App permissions** that determine when ChatGPT asks before using a connection.

96- Keep access within the scopes and permissions granted by each connected96- Keep access within the scopes and permissions granted by each connected

97 service and authenticated user.97 service and authenticated user.

98 98

120and capabilities across supported ChatGPT and Codex surfaces.120and capabilities across supported ChatGPT and Codex surfaces.

121 121

122Whatever the initial set, start with read actions. Before enabling write122Whatever the initial set, start with read actions. Before enabling write

123actions, identify the plugin owner, review connector scopes and service123actions, identify the plugin owner, review MCP server scopes and service

124permissions, confirm data access, and document external effects and a recovery124permissions, confirm data access, and document external effects and a recovery

125path.125path.

126 126

127## Understand data flow and security127## Understand data flow and security

128 128

129When ChatGPT uses an app or connector included with a plugin, it sends a request129When ChatGPT uses an MCP server included with a plugin, it sends a request

130to the connected service and returns data or action results allowed by the130to the connected service and returns data or action results allowed by the

131authenticated user's permissions in that service.131authenticated user's permissions in that service.

132 132

133ChatGPT handles connected app data in two ways:133ChatGPT handles data from connected services in two ways:

134 134

135- **Non-synced:** ChatGPT processes data from Chat and deep research transiently135- **Non-synced:** ChatGPT processes data from Chat and deep research transiently

136 and doesn't index it.136 and doesn't index it.

137- **Synced:** ChatGPT indexes selected connected content in advance. You can see137- **Synced:** ChatGPT indexes selected connected content in advance. You can see

138 whether an app supports sync on its plugin page.138 whether a connection supports sync on its plugin page.

139 139

140The mode changes how ChatGPT indexes connected content; it doesn't replace140The mode changes how ChatGPT indexes connected content; it doesn't replace

141normal chat-retention controls. ChatGPT conversations that use apps remain141normal chat-retention controls. ChatGPT conversations that use these connections remain

142available through the Compliance API.142available through the Compliance API.

143 143

144OpenAI's app guidance documents encryption in transit and at rest, per-user144OpenAI's connected-service guidance documents encryption in transit and at rest, per-user

145authorization, role and action controls, restricted network access for145authorization, role and action controls, restricted network access for

146conversations that use apps, and no model training on information accessed146conversations that use these connections, and no model training on information accessed

147through apps for Business, Enterprise, and Edu customers. When a request reaches147through these connections for Business, Enterprise, and Edu customers. When a request reaches

148a connected service, that service's scopes, retention, data residency, and other148a connected service, that service's scopes, retention, data residency, and other

149policies also apply.149policies also apply.

150 150

151See [app security and compliance](https://help.openai.com/en/articles/11509118)151See [security and compliance for connected services](https://help.openai.com/en/articles/11509118)

152and [apps with sync](https://help.openai.com/en/articles/10847137) for current152and [connections with sync](https://help.openai.com/en/articles/10847137) for current

153data-handling details. For locally configured MCP servers in the ChatGPT desktop153data-handling details. For locally configured MCP servers in the ChatGPT desktop

154app, Codex CLI, or IDE extension, see154app, Codex CLI, or IDE extension, see

155[Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp).155[Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp).

enterprise/managed-configuration.md +92 −10

Details

4 4

5Managed configuration controls supported local runtime behavior for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension. Supported requirements can differ by client and version. Managed configuration doesn't grant ChatGPT workspace access, assign seats, or replace workspace role-based access control (RBAC). Use [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions) for workspace feature access and this page for local runtime policy.5Managed configuration controls supported local runtime behavior for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension. Supported requirements can differ by client and version. Managed configuration doesn't grant ChatGPT workspace access, assign seats, or replace workspace role-based access control (RBAC). Use [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions) for workspace feature access and this page for local runtime policy.

6 6

~~7Enterprise admins can control supported local client behavior in two ways:~~7Enterprise admins can control supported local client behavior with:

8 8

9- **Requirements**: admin-enforced constraints that users can't override.9- **Requirements**: admin-enforced constraints that users can't override.

~~10- **Managed defaults**: starting values applied when a supported client launches. Users can still change settings during a run; the client reapplies managed defaults the next time it starts.~~10- **Configuration defaults**: system or cloud-managed `config.toml` settings that users can override.

11- **Legacy managed defaults**: `managed_config.toml` starting values applied when a supported client launches. Users can still change settings during a run; the client reapplies these defaults the next time it starts.

13## Configure plugin marketplaces and defaults

15Define local or Git marketplaces and plugin defaults in system `config.toml`

16or the `config.toml` section of [Managed configuration](https://chatgpt.com/codex/settings/managed-configs).

17These settings are defaults, not enforced policy.

19See [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference) for configuration keys,

20[Configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence)

21for overrides, and [repo plugin settings](https://developers.openai.com/plugins/build/plugins#enable-or-disable-a-plugin-for-a-repo)

22for project-level configuration. [Workspace GitHub import and

23sync](https://learn.chatgpt.com/docs/enterprise/plugin-management) is separate.

11 24

12## Admin-enforced requirements (requirements.toml)25## Admin-enforced requirements (requirements.toml)

13 26

14Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, which MCP servers users can enable, and which user-configured plugin marketplace sources they can add, install from, or refresh). When resolving configuration (for example from `config.toml`, [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, the local client falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, the client enables an MCP server only when both its name and identity match an approved entry; otherwise, the client disables it.27Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, which MCP servers users can enable, and which plugin marketplace sources they can use). When resolving configuration (for example from `config.toml`, [profile files](https://learn.chatgpt.com/docs/config-file/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, the local client falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, the client enables an MCP server only when both its name and identity match an approved entry; otherwise, the client disables it.

15 28

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

17 30

22 35

23For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).36For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml).

24 37

38### Migrate the retired `untrusted` approval policy

40Codex and ChatGPT Work no longer support `approval_policy = "untrusted"`.

41Remove it from managed defaults, legacy `managed_config.toml`, and any user,

42project, profile, or startup configuration that sets it.

44For interactive, read-only use, select `approval_policy = "on-request"` with a

45read-only sandbox or permission profile allowed by your managed requirements.

46Commands allowed by that sandbox can run without approval.

48To keep stricter command approvals, omit an explicit `approval_policy`, set

49`trust_level = "untrusted"` in the project's entry in user-level

50`~/.codex/config.toml`, and keep `untrusted` in `allowed_approval_policies`.

51This also disables project-local configuration. Setting `on-request` explicitly

52overrides that policy. See

53[Migrate from the retired `untrusted` approval policy](https://learn.chatgpt.com/docs/agent-approvals-security#migrate-from-the-retired-untrusted-approval-policy)

54for examples and security tradeoffs.

25### Locations and precedence56### Locations and precedence

26 57

27Each supported local client composes requirements from lower to higher precedence:58Each supported local client composes requirements from lower to higher precedence:

51When a user signs in with ChatGPT on a supported plan, supported local clients82When a user signs in with ChatGPT on a supported plan, supported local clients

52can receive admin-enforced requirements associated with the workspace. This is83can receive admin-enforced requirements associated with the workspace. This is

53a delivery channel for `requirements.toml`-compatible policy. It doesn't grant84a delivery channel for `requirements.toml`-compatible policy. It doesn't grant

~~54workspace access or replace workspace RBAC.~~85workspace access or replace workspace RBAC. Authentication requirements must be

86[managed locally](#manage-authentication-locally).

55 87

56Open [Managed configuration](https://chatgpt.com/codex/settings/managed-configs)88Open [Managed configuration](https://chatgpt.com/codex/settings/managed-configs)

57to create and assign cloud-managed requirements. For example, this policy limits89to create and assign cloud-managed requirements. For example, this policy limits

111in the supported client rather than assuming a workspace role or group alone143in the supported client rather than assuming a workspace role or group alone

112enforces the local restriction.144enforces the local restriction.

113 145

146### Manage authentication locally

147

148Set `allowed_login_methods`, `allowed_chatgpt_workspaces`,

149`cli_auth_credentials_store`, and `chatgpt_base_url` in the local system

150`requirements.toml` or macOS MDM requirements. Codex ignores these four fields

151in cloud-managed requirements. Local authentication requirements apply before

152credentials load and before Codex retrieves cloud policy.

153

154To require ChatGPT login to an approved workspace and store credentials in the

155OS credential store, use:

156

157```toml

158allowed_login_methods = ["chatgpt"]

159allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]

160cli_auth_credentials_store = "keyring"

161```

162

163`allowed_login_methods` accepts `chatgpt`, `api`, or both. If omitted, this setting

164doesn't restrict login methods. If set, the list must contain at least one method.

165`api` permits API authentication, including Amazon Bedrock.

166The workspace restriction also applies to

167[Codex access tokens](https://learn.chatgpt.com/docs/enterprise/access-tokens).

168

169User-configured `forced_login_method` and `forced_chatgpt_workspace_id` must

170follow the requirements. When a user selects a workspace, it must also appear

171in the managed workspace allowlist. If no workspaces match, ChatGPT login is

172unavailable. API authentication remains available when permitted. If no login method

173is available, Codex refuses to start.

174

175See the [requirements reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml)

176for credential storage modes and service URL configuration.

177

114### Example requirements.toml178### Example requirements.toml

115 179

116This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):180This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

120allowed_sandbox_modes = ["read-only", "workspace-write"]184allowed_sandbox_modes = ["read-only", "workspace-write"]

121```185```

122 186

187Here, `untrusted` preserves the stricter approval behavior derived from

188`trust_level = "untrusted"`; it does not make `approval_policy = "untrusted"` a

189supported explicit setting.

190

123### Disable Appshots191### Disable Appshots

124 192

125To disable Appshots for managed users, set the top-level `allow_appshots` requirement:193To disable Appshots for managed users, set the top-level `allow_appshots` requirement:

642 710

643### Restrict plugin marketplace sources711### Restrict plugin marketplace sources

644 712

645To restrict operations on user-configured marketplace sources, set713To restrict plugin marketplace sources, set

646`restrict_to_allowed_sources = true` and define one or more source rules:714`restrict_to_allowed_sources = true` and define one or more source rules:

647 715

648```toml716```toml

670for the full schema and merge behavior.738for the full schema and merge behavior.

671 739

672These requirements reject unmatched marketplace add, plugin install, and740These requirements reject unmatched marketplace add, plugin install, and

673configured Git marketplace refresh operations for user-configured sources.741configured Git marketplace refresh operations. They also filter configured

674Codex-managed OpenAI marketplaces remain available when their source and742marketplaces and their plugins at runtime.

675reserved name match. The requirements don't filter already configured user743

676marketplaces or their plugins at runtime.744The OpenAI-curated Git marketplaces, including the API-key catalog, must also

745match the source allowlist. To allow them, include the following Git source

746without a `ref` constraint:

747

748```toml

749[marketplaces.allowed_sources.openai_curated]

750source = "git"

751url = "https://github.com/openai/plugins.git"

752```

753

754To exclude the curated catalogs, omit that source and ensure no broader host

755rule allows it. Bundled plugins and remotely installed workspace plugins are

756separate from this curated Git source policy.

677 757

678These source restrictions apply only where a local client supports plugin758These source restrictions apply only where a local client supports plugin

679marketplace operations: ChatGPT and Codex in the desktop app, and Codex CLI.759marketplace operations: ChatGPT and Codex in the desktop app, and Codex CLI.

707 787

708CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.788CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

709 789

710Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.790Cloud `config.toml` uses [normal configuration precedence](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence),

791not the legacy ordering above. Cloud `requirements.toml` uses

792[requirements precedence](#locations-and-precedence).

711 793

712### Locations794### Locations

713 795

enterprise/plugin-management.md +6 −0

Details

6 6

7Workspace admins can import a plugin marketplace from GitHub and keep its plugins up to date from the repository. A marketplace is a JSON catalog that lists the plugins to import.7Workspace admins can import a plugin marketplace from GitHub and keep its plugins up to date from the repository. A marketplace is a JSON catalog that lists the plugins to import.

8 8

9This page covers workspace import and sync. To configure marketplaces directly

10on local clients through cloud-managed or system `config.toml`, see

11[Configure plugin marketplaces and defaults](https://learn.chatgpt.com/docs/enterprise/managed-configuration#configure-plugin-marketplaces-and-defaults).

12To enable or disable plugins for a specific project, see [Enable or disable a plugin for a

13repo](https://developers.openai.com/plugins/build/plugins#enable-or-disable-a-plugin-for-a-repo).

9Use a GitHub account that can read the marketplace repository and any other repositories it references. Public and private GitHub repositories are supported. Complete any GitHub organization approval required for your repository access before importing.15Use a GitHub account that can read the marketplace repository and any other repositories it references. Public and private GitHub repositories are supported. Complete any GitHub organization approval required for your repository access before importing.

10 16

11Review the repository content before importing. New plugins start with **Available** installation and authentication on install. New marketplaces have automatic daily sync enabled. Import processes all valid entries, and future syncs automatically add any new plugins in the repository.17Review the repository content before importing. New plugins start with **Available** installation and authentication on install. New marketplaces have automatic daily sync enabled. Import processes all valid entries, and future syncs automatically add any new plugins in the repository.

guides/agents-sdk.md +1 −1

Details

32| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |32| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |

plugins.md +21 −20

Details

5## Overview5## Overview

6 6

7Plugins bundle capabilities into reusable workflows in ChatGPT and Codex. They7Plugins bundle capabilities into reusable workflows in ChatGPT and Codex. They

~~8can include skills, connectors, or both. Both products use one universal plugin~~8can include skills, MCP servers, and lifecycle hooks. Both products use one universal plugin

9directory, so the same public plugins are discoverable from their supported9directory, so the same public plugins are discoverable from their supported

10surfaces.10surfaces.

11 11

15 15

16On mobile, you can use plugins available to your account in Chat or Work.16On mobile, you can use plugins available to your account in Chat or Work.

17 17

18Plugins marked **Desktop only** require the ChatGPT desktop app. You can discover these plugins on the web,

19but you must open the ChatGPT desktop app to install and use them. They aren't

20available on mobile.

18<ContentModeSwitch group="codex-surface" id="app">22<ContentModeSwitch group="codex-surface" id="app">

19 23

20Open the **Plugins** tab to browse and install plugins. After installation, you24Open the **Plugins** tab to browse and install plugins. After installation, you

21can use plugins in Chat or Work in ChatGPT, or in Codex. Installed plugins can25can use plugins in Chat or Work in ChatGPT, or in Codex. Installed plugins can

~~22add skills, connectors, and MCP tools to new chats.~~26add skills and MCP tools to new chats.

23 27

24</ContentModeSwitch>28</ContentModeSwitch>

25 29

64- **Skills:** reusable instructions for specific kinds of work. ChatGPT and68- **Skills:** reusable instructions for specific kinds of work. ChatGPT and

65 Codex can load them when needed so they follow the right steps and use the69 Codex can load them when needed so they follow the right steps and use the

66 right references or helper scripts for a task.70 right references or helper scripts for a task.

~~67- **Connectors:** connections to tools like GitHub, Slack, or Google Drive, so~~71- **MCP servers:** services that connect ChatGPT and Codex to tools and

~~68 ChatGPT and Codex can read information from those tools and take actions in~~72 information in systems such as GitHub, Slack, or Google Drive. They define

~~69 them. Connectors expose tools and can optionally include custom UI.~~73 tools, enforce authentication, return structured data, and perform actions

~~70- **MCP servers:** services that give ChatGPT and Codex access to more tools or~~74 against external systems. They can optionally include custom UI.

~~71 shared information, often from systems outside your local project. They're~~

~~72 also the services behind connectors. They define tools, enforce auth, return~~

~~73 structured data, and perform actions against external systems.~~

74- **Browser extensions:** browser capabilities that a plugin needs for its75- **Browser extensions:** browser capabilities that a plugin needs for its

75 workflow.76 workflow.

~~76- **Hooks:** commands that run at configured lifecycle points. Review and trust~~77- **Hooks:** commands that run at configured lifecycle points in the Codex

~~77 plugin hooks before you enable them.~~78 runtime, including ChatGPT Work and Codex. Hook scripts must be

~~78- **Scheduled task templates:** reusable starting points for recurring tasks~~79 available in the execution environment; installing a plugin on the web doesn't

~~79 where scheduled tasks are available.~~80 deploy those scripts. Enterprise admins can deploy required scripts through

81 mobile device management (MDM). Review and trust plugin hooks before they run.

82 See [Hooks](https://learn.chatgpt.com/docs/hooks) for setup and managed-hook policies.

80 83

81You can share plugins by publishing them through a marketplace source, such as a84You can share plugins by publishing them through a marketplace source, such as a

82repo marketplace for a project or team. See [Build plugins](https://developers.openai.com/plugins/build/plugins)85repo marketplace for a project or team. See [Build plugins](https://developers.openai.com/plugins/build/plugins)

135 138

1361. Search or browse for a plugin, then open its details.1391. Search or browse for a plugin, then open its details.

1372. Select the plus button to install the plugin.1402. Select the plus button to install the plugin.

1383. If the plugin needs a connector, connect it when prompted. Some plugins1413. If the plugin needs an MCP server connection, connect it when prompted. Some plugins

139 ask you to authenticate during install. Others wait until the first time you142 ask you to authenticate during install. Others wait until the first time you

140 use them.143 use them.

1414. After installation, start a new chat and ask ChatGPT or Codex to use the1444. After installation, start a new chat and ask ChatGPT or Codex to use the

316<ContentModeSwitch group="codex-surface" id="web">319<ContentModeSwitch group="codex-surface" id="web">

317 320

318In ChatGPT on the web, Chat and Work use the workspace permissions and tools321In ChatGPT on the web, Chat and Work use the workspace permissions and tools

319available to that chat. Connectors still require their own sign-in and access.322available to that chat. MCP servers still require their own sign-in and access.

320 323

321</ContentModeSwitch>324</ContentModeSwitch>

322 325

331 334

332- Bundled skills become available when you start a new chat or CLI session335- Bundled skills become available when you start a new chat or CLI session

333 after installation.336 after installation.

334- If a plugin includes connectors, the active product may prompt you to install

335 or sign in to those connectors during setup or the first time you use them.

336- If a plugin includes MCP servers, they may require extra setup or337- If a plugin includes MCP servers, they may require extra setup or

337 authentication before you can use them.338 authentication before you can use them.

338- When ChatGPT sends data through a bundled connector, that service's terms and privacy339- When ChatGPT sends data through an MCP server, that service's terms and privacy

339 policy apply.340 policy apply.

340 341

341### Remove a plugin342### Remove a plugin

346them instead.347them instead.

347 348

348Uninstalling a plugin removes the plugin bundle from that ChatGPT or Codex349Uninstalling a plugin removes the plugin bundle from that ChatGPT or Codex

349environment, but bundled connectors stay connected until you manage them in350environment. Separately connected MCP server integrations remain connected in

350ChatGPT.351ChatGPT until you disconnect them there.

351 352

352## Build your own plugin353## Build your own plugin

353 354

plugins/build.md +13 −9

Details

51Add it to a personal marketplace so I can test it locally.51Add it to a personal marketplace so I can test it locally.

52```52```

53 53

~~54The skill creates the required `.codex-plugin/plugin.json` manifest, organizes~~54The skill creates a supported `.codex-plugin/plugin.json` compatibility

~~55the plugin folder, and can add the plugin to a local marketplace.~~55manifest, organizes the plugin folder, and can add the plugin to a local

56marketplace. This scaffold differs from the portable root `plugin.json` format

57used in the manual example. See the [scaffold layout](https://developers.openai.com/plugins/build/plugins#plugin-creator-output)

58for optional files and directories.

56 59

57 60

58 61

77 80

78## Create a skills-only plugin manually81## Create a skills-only plugin manually

79 82

~~80A minimal plugin contains a manifest and at least one skill:~~83A minimal portable Agent Plugins package contains a root manifest and at least

84one skill:

81 85

82```text86```text

83meeting-follow-up/87meeting-follow-up/

~~84├── .codex-plugin/~~88├── plugin.json

~~85│ └── plugin.json~~

86└── skills/89└── skills/

87 └── meeting-follow-up/90 └── meeting-follow-up/

88 └── SKILL.md91 └── SKILL.md

89```92```

90 93

~~91Create `.codex-plugin/plugin.json`:~~94Create `plugin.json` at the plugin root:

92 95

93```json96```json

94{97{

98 "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",

95 "name": "meeting-follow-up",99 "name": "meeting-follow-up",

96 "version": "1.0.0",100 "version": "1.0.0",

~~97 "description": "Turn meeting notes into decisions and next steps",~~101 "description": "Turn meeting notes into decisions and next steps"

~~98 "skills": "./skills/"~~

99}102}

100```103```

101 104

102Then add `skills/meeting-follow-up/SKILL.md`:105Portable packages discover skills in `skills/` automatically. Add

106`skills/meeting-follow-up/SKILL.md`:

103 107

104```md108```md

105---109---

skills-and-plugins.md +6 −5

Details

12 12

13- A **skill** packages instructions and supporting resources for a specific13- A **skill** packages instructions and supporting resources for a specific

14 task or workflow.14 task or workflow.

~~15- A **plugin** is an installable bundle that can include skills, connectors, or~~15- A **plugin** is an installable bundle that can include skills and Model Context

~~16 both. Connectors are backed by Model Context Protocol (MCP) servers and can~~16 Protocol (MCP) servers. MCP servers expose tools and can optionally include

~~17 optionally include custom ChatGPT UI.~~17 custom ChatGPT UI. Plugins can also include [lifecycle hooks](https://learn.chatgpt.com/docs/hooks)

18 for the Codex runtime, including ChatGPT Work and Codex.

18 19

19## Use skills for repeatable work20## Use skills for repeatable work

20 21

79## Use plugins for tools and shared workflows80## Use plugins for tools and shared workflows

80 81

81Plugins make reusable capabilities easier to install and share. A plugin can82Plugins make reusable capabilities easier to install and share. A plugin can

~~82combine skills with connectors for services such as GitHub, Google Drive, or~~83combine skills with MCP servers for tools and context from services such as

~~83Slack, and can include MCP servers for additional tools and context.~~84GitHub, Google Drive, or Slack.

84 85

85ChatGPT and Codex share one universal plugin directory. Browse it when you want86ChatGPT and Codex share one universal plugin directory. Browse it when you want

86to add an existing workflow instead of building one yourself. After installing87to add an existing workflow instead of building one yourself. After installing

use-cases/automation-bug-triage.md +9 −1

Details

129 129

130 130

131 131

132 ## Phase 2: Make the report useful132

133

134![A Codex prompt that mentions Slack, Linear, and GitHub plugins and lists the exact sources to check for a bug triage sweep](<https://developers.openai.com/images/codex/use-cases/bug-automation-light.png>)

135

136

137

138

139

140## Phase 2: Make the report useful

133 141

134Before you automate, make sure the report is useful enough to read every day.142Before you automate, make sure the report is useful enough to read every day.

135 143

Documentation 2026-09-04 19:59 UTC to 2026-09-09 21:01 UTC