openai-codex

어떤 스킬인가요?

OpenAI Codex (CLI / IDE / cloud) の公式リファレンス。 codex CLI, codex exec, AGENTS.md, rules, subagents, prompting, approvals, sandbox, permission profiles, auto-review, config.toml, profiles, MCP 設定, 環境変数, GitHub Action, Codex SDK, Agents SDK 連携, cloud 委譲, administration, roles, provisioning, analytics API, compliance API, Codex Security 脆弱性スキャン, deep scan, triage, findings, SARIF export, threat model, security hardening, cloud / local / worktree 環境, git worktrees, Record & Replay, GitHub / Linear / Slack 連携。

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Access tokens

Create and manage Codex access tokens — ChatGPT workspace credentials scoped to Codex permissions — for programmatic, non-interactive Codex workflows.

## Overview

Codex access tokens authenticate trusted non-interactive local workflows (Codex CLI, app-server-based automation) with a ChatGPT workspace identity. Currently supported for ChatGPT Business and Enterprise workspaces. Created at [Access tokens](https://chatgpt.com/admin/access-tokens); tied to the creating user and their workspace.

Use a Workspace Agent access token (not a Codex access token) to trigger published ChatGPT workspace agents via the Workspace Agents API.

## Signature / Usage

```bash
export CODEX_ACCESS_TOKEN="<access-token>"
codex exec --json "review this repository and summarize the top risks"
```

Persistent local login:

```bash
printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
codex exec "summarize the last release diff"
```

## Enable, expire, create, rotate

1. **Enable creation**: Workspace Settings > Permissions & roles > Access tokens > **Allow users to create access tokens**. Also enable **Allow members to use Codex Local** if the workflow needs desktop app / CLI / IDE extension access.
2. **Set expiration limit**: Workspace Settings > Permissions & roles > Codex Local > **Access token expiration limit** (applies to new tokens only).
3. **Create**: [Access tokens](https://chatgpt.com/admin/access-tokens) > Create > name it (e.g. `release-ci`) > choose expiration (prefer finite, e.g. 7/30/60/90 days; shortest is 1 day) > copy immediately (not retrievable later).
4. **Rotate**: create replacement > update secret in runner/scheduler > smoke test > revoke old token.

## Permission model

| Capability | Owners/admins | Member with token permission | Member without |
|------------|----------------|-------------------------------|-----------------|
| Open Access tokens page | Yes | Yes | No |
| Create access tokens | Yes (own identity) | Yes (own identity) | No |
| List access tokens | Workspace-wide | Only own | No |
| Revoke from Access tokens page | Any workspace token | Only own | No page access |
| Grant/remove access token permission | Yes | No | No |

## Notes

- The access token permission controls token creation only — it doesn't grant desktop app / CLI / IDE extension access, and doesn't change seat type, workspace role, or local permission profile.
- Main risks: leaked secrets, untrusted CI runners exposing tokens, shared identities, stale long-lived credentials, using the wrong credential type (use Platform API keys for general API calls, Workspace Agent tokens to trigger agents).
- `codex app-server` can use the same `CODEX_ACCESS_TOKEN` credential for OpenAI requests, but that is separate from client-to-app-server transport authentication (see App server docs for the remote WebSocket bearer/capability token).

## Related

- [Authentication](./authentication.md)
- [Admin rollout guide](./admin-rollout-guide.md)
- [Groups and provisioning](./groups-and-provisioning.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Governance](./governance.md)

# Admin rollout guide

Plan, configure, and verify a ChatGPT Enterprise rollout across workspace and developer surfaces, in eight sequential steps.

## Signature / Usage

Rollout boundaries covered:

- Workspace access
- Local runtime policy for the ChatGPT desktop app, Codex CLI, and IDE extension
- Codex cloud
- Platform API access
- Plugins and connector access
- Permissions in connected systems

## Steps

| Step | Focus |
|------|-------|
| 1. Assign owners and choose a rollout | Owners for workspace access, local runtime policy, Codex cloud, connected systems, reporting/compliance |
| 2. Configure workspace access and identity | Membership, seats, groups, RBAC; test with a representative member first |
| 3. Configure local runtime requirements | Deliver `requirements.toml`; prefer permission profiles over legacy sandbox-mode restrictions |
| 4. Standardize repository configuration | `.codex` / `.agents` config, rules, skills per repository |
| 5. Configure Codex cloud | Grant access, install source-system integration, limit repo access, configure environments/secrets/internet access |
| 6. Configure plugins and connected capabilities | Review plugin/skill/connector-backed capability, test with non-sensitive data, least access first |
| 7. Set up governance and observability | Choose Workspace analytics, Analytics API, Compliance API, or usage limits per the question being asked |
| 8. Verify and maintain the rollout | Verify every boundary with representative identities; record owners and procedural sources |

## Notes

- In workspace settings, **Codex Local** is a grouping label for local access and access-token controls, not a separate product. **Allow members to use Codex Local** covers the ChatGPT desktop app, Codex CLI, and IDE extension.
- Managed configuration is a separate policy layer that constrains supported runtime behavior for those clients.
- Repository configuration (Step 4) can supply defaults and reusable workflows, but can't grant workspace, model, Platform API, or connected-system access.
- Codex cloud (Step 5) respects the repository permissions exposed by the connected source system; workspace access doesn't bypass those controls.
- Disabling a connector-backed capability (Step 6) doesn't necessarily uninstall the plugin or its bundled skills. Plugins are available with ChatGPT Work on web, with ChatGPT Work and Codex in the desktop app, and through the Codex CLI plugin browser — not in Chat, the IDE extension, or mobile.
- Use authenticated API references (not this guide) for current access requirements, schemas, and request behavior when building integrations.

## Related

- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Managed configuration](./managed-configuration.md)
- [Governance](./governance.md)
- [Groups and provisioning](./groups-and-provisioning.md)

# Administration

Entry point for ChatGPT/Codex admin docs: access and policy boundaries across ChatGPT, Codex developer tools, APIs, plugins, and connected systems.

## Overview

The administration section covers six key areas: workspace access, local runtime policies (desktop app / CLI / IDE extension), Codex cloud eligibility, Platform API permissions, plugin availability, and connector permissions.

## Documentation Structure

1. **Getting Started** — rollout planning and foundational setup (see [Admin rollout guide](./admin-rollout-guide.md))
2. **Identity and Authentication** — sign-in methods and credential management (see [Authentication](./authentication.md))
3. **Workspace Access, Policy, and Models** — user provisioning and capability controls (see [Roles and workspace permissions](./roles-and-workspace-permissions.md), [Groups and provisioning](./groups-and-provisioning.md), [Workspace model availability](./workspace-model-availability.md))
4. **Plugin and Connector Controls** — third-party integration management (see [Plugin controls](./plugin-controls.md), [Skill controls](./skill-controls.md))
5. **Usage, Governance, and Compliance** — analytics and audit capabilities (see [Governance](./governance.md), [Workspace analytics](./workspace-analytics.md), [Analytics API](./analytics-api.md), [Compliance API and audit events](./compliance-api.md), [ChatGPT usage limits and spend controls](./usage-limits.md))
6. **Deployment and Model Providers** — app distribution and external model configuration (see [Manage app updates](./manage-app-updates.md), [Deploy the Windows app](./windows-deployment.md), [Managed configuration](./managed-configuration.md))

## Notes

- Each numbered category above maps to a set of reference pages in this directory.
- For approvals, sandboxing, and other agent security mechanisms, see the security-automation reference scope instead.

## Related

- [Admin rollout guide](./admin-rollout-guide.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [ChatGPT Work admin FAQ](./work-admin-faq.md)

# Analytics API

Understand the purpose and administration boundary of the Codex Analytics API — programmatic, aggregated Codex usage/activity metrics for a ChatGPT workspace.

## Overview

Use the Analytics API to join aggregated Codex metrics with internal organizational data, or to automate recurring reporting (data warehouses, business intelligence, internal reporting) without depending on an interactive dashboard. It is not a raw audit-log interface — use the Compliance API for auditable activity records.

## Authentication and scope

Requests authenticate with a Platform organization API key; the key's organization must align with the workspace's associated organization. Results are limited to a single ChatGPT workspace.

## Notes

- The authenticated [Codex Analytics API reference](https://chatgpt.com/codex/cloud/settings/apireference) is the source of truth for access requirements, routes, schemas, and pagination — this page doesn't duplicate that contract.

## Related

- [Workspace analytics](./workspace-analytics.md)
- [Compliance API and audit events](./compliance-api.md)
- [Governance](./governance.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# Authentication

Sign-in methods for ChatGPT web and Codex clients (desktop app, CLI, IDE extension) and how sign-in method determines applicable admin controls and data-handling policy.

## Overview

Codex supports two sign-in methods for local work: **ChatGPT sign-in** (subscription access, browser flow) and **API key** (usage-based access). The desktop app, Codex CLI, and IDE extension support both; Codex cloud requires ChatGPT sign-in.

- ChatGPT sign-in: usage follows ChatGPT workspace permissions, RBAC, and ChatGPT Enterprise retention/residency settings.
- API key: usage follows the API organization's own retention/data-sharing settings and is billed at standard API rates through the Platform account.

## Signature / Usage

```shell
# Codex CLI: browser-based ChatGPT sign-in
codex login

# Codex CLI: API key sign-in
printenv OPENAI_API_KEY | codex login --with-api-key

# Codex CLI: enterprise access token sign-in
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

# check / clear
codex login status
codex logout
```

## Credential storage

```toml
# file | keyring | auto
cli_auth_credentials_store = "keyring"
```

`file` writes `auth.json` under `CODEX_HOME` (default `~/.codex`); `keyring` uses the OS credential store; `auto` prefers the OS store, falling back to `auth.json`.

## Enforce a login method or workspace

```toml
forced_login_method = "chatgpt" # or "api"
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"
```

Mismatched credentials cause Codex to log the user out and exit. Typically applied via [managed configuration](./managed-configuration.md).

## Headless / device login

Preferred: device code authentication (beta) — enable in ChatGPT security settings or workspace permissions, then `codex login --device-auth`. Fallbacks: copy `~/.codex/auth.json` to the headless machine (via `scp` or a Docker `cp`), or forward the localhost OAuth callback over SSH (`ssh -L 1455:localhost:1455 user@remote`).

## Notes

- API key authentication supports local Codex workflows, but some ChatGPT-workspace/cloud-dependent features are limited or unavailable; some OpenAI-curated plugins requiring OAuth aren't available under API-key auth.
- Codex cloud requires MFA. Social-login (Google/Microsoft/Apple) users aren't required to enable MFA on the ChatGPT account itself but can via the provider; SSO organizations should enforce MFA at the IdP; email/password login requires MFA before Codex cloud access.
- Treat `~/.codex/auth.json` like a password — it contains access tokens; never commit, paste into tickets, or share in chat.
- Enterprise admins can grant the access-token permission for trusted non-interactive automation instead of browser sign-in — see [Access tokens](./access-tokens.md).

## Related

- [Access tokens](./access-tokens.md)
- [Groups and provisioning](./groups-and-provisioning.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Managed configuration](./managed-configuration.md)

# Compliance API and audit events

Understand the purpose and administration boundary of the Compliance API — auditable records for security, legal, governance, and investigation workflows.

## Overview

Use the Compliance API to export supported records into an audit/investigation system, apply organizational retention and legal-hold processes, correlate Codex activity with other security/identity data, and support approved investigations. It is not a productivity dashboard — don't use it to infer code quality or individual performance; use [Workspace analytics](./workspace-analytics.md) or the [Analytics API](./analytics-api.md) for adoption reporting instead.

## Get started

1. Open the [Admin API reference](https://chatgpt.com/admin/api-reference) and confirm your admin role can access the needed compliance resources.
2. Use the append-only compliance log stream for ongoing collection.
3. Test ingestion into a non-production SIEM system or data lake.
4. Schedule continuous collection and apply your organization's access/retention/legal-hold controls to exported records — don't assume the source retention window replaces your own retention policy.

## Notes

- The authenticated [Admin API reference](https://chatgpt.com/admin/api-reference) owns current routes, event coverage, schemas, filters, retention behavior, and request mechanics — this page doesn't duplicate that contract.
- Compliance coverage follows the ChatGPT workspace and products represented in the current authenticated reference. Platform API organization data follows its own separate administration controls.

## Related

- [Workspace analytics](./workspace-analytics.md)
- [Admin rollout guide](./admin-rollout-guide.md)
- [Governance](./governance.md)
- [Analytics API](./analytics-api.md)

# Governance

Choose the appropriate analytics, usage, and audit surface for each administration question.

## Overview

Governance for Codex activity spans interactive analytics, programmatic reporting, related ChatGPT usage controls, and audit records. Analytics and compliance data serve different purposes.

## Signature / Usage

| If you need to | Start with |
|-----------------|------------|
| Understand adoption across ChatGPT | [Workspace analytics](./workspace-analytics.md) |
| Review Codex adoption/activity interactively | Codex analytics dashboard |
| Load aggregated Codex reporting into another system | [Analytics API](./analytics-api.md) |
| Export records for audit or investigation | [Compliance API and audit events](./compliance-api.md) |
| Review plan-dependent ChatGPT workspace credit controls | [ChatGPT usage limits and spend controls](./usage-limits.md) |

## Administration surfaces

- [Workspace analytics](https://chatgpt.com/admin/usage) — interactive workspace reporting
- Authenticated [Codex Analytics API reference](https://chatgpt.com/codex/cloud/settings/apireference) — scheduled, programmatic reporting
- Authenticated [Admin API reference](https://chatgpt.com/admin/api-reference) — audit and investigation integrations

## Notes

- ChatGPT workspace analytics covers broad adoption/engagement; Codex analytics focuses on Codex activity. Both are interactive reporting, not raw audit logs — don't build a durable reporting contract from dashboard labels or downloaded report fields.
- ChatGPT workspace usage controls (credits) are separate from analytics and don't configure feature entitlements; eligible Codex activity can consume workspace credits and exhausted limits can pause access to eligible features.

## Related

- [Admin rollout guide](./admin-rollout-guide.md)
- [Workspace analytics](./workspace-analytics.md)
- [Analytics API](./analytics-api.md)
- [Compliance API and audit events](./compliance-api.md)

# Groups and provisioning

Understand group membership sources and their workspace access boundary.

## Overview

Groups organize ChatGPT workspace access for members and support custom roles. Group membership is separate from local runtime policy and permissions in connected systems.

## Membership management options

| Approach | Best for |
|----------|----------|
| Manually managed groups | Small, temporary groups, or groups not managed through directory sync |
| Identity-provider-managed groups (SCIM) | Membership that should follow the organization's directory and member-removal process |

## Notes

- SCIM provisioning doesn't grant permissions in GitHub, Google Drive, Slack, or another connected system, and doesn't replace local runtime requirements.
- Workspace RBAC and local runtime requirements are distinct control systems — group order doesn't imply permission precedence. See [Managed configuration](./managed-configuration.md) for documented delivery/precedence rules.

## Related

- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Admin rollout guide](./admin-rollout-guide.md)
- [Access tokens](./access-tokens.md)

# Manage app updates

Control how your organization updates the ChatGPT desktop app on macOS and Windows.

## Overview

The ChatGPT desktop app normally self-updates. Organizations that need to review releases before rollout can turn off the built-in updater via managed configuration and deploy approved versions through their device-management platform. Turning off the in-app updater doesn't stop the Microsoft Store, Intune, MDM, or package managers from installing updates.

## Signature / Usage

Disable the desktop app's own updater via a managed policy:

```toml
[features]
in_app_updates = false
```

Set this in [Managed configuration](https://chatgpt.com/codex/settings/managed-configs) > Add policy > Targets (Groups/Users/Platforms) > Raw TOML > `requirements.toml` editor. To restore normal updates, remove `in_app_updates = false` from every applicable policy/MDM profile and have users fully quit and reopen the app.

## Verification

Settings > General > **In-app updates** should show **Managed** with "Your organization has turned off in-app updates." The **Check for Updates** menu item can remain visible even when blocked — trust the **Managed** indicator instead.

## Notes

- After disabling, the organization is responsible for promptly deploying new releases and security fixes; older versions don't receive separate patches or extended support.
- The setting must be in `requirements.toml`, not `config.toml`.
- Applies only to the ChatGPT desktop app on macOS/Windows — not mobile apps, Codex CLI, or the IDE extension.
- If the app can't reach the policy-delivery service (auth/connection/timeout issues), the built-in updater can remain enabled — don't assume updates are blocked unless **Managed** appears.

## Related

- [Managed configuration](./managed-configuration.md)
- [Deploy the Windows app](./windows-deployment.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# Managed configuration

Enforce runtime requirements across supported local clients (ChatGPT desktop app, Codex CLI, IDE extension) and distribute managed defaults.

## Overview

Managed configuration controls supported local runtime behavior. It doesn't grant ChatGPT workspace access, assign seats, or replace workspace RBAC — use [Roles and workspace permissions](./roles-and-workspace-permissions.md) for that. Two mechanisms:

- **Requirements** (`requirements.toml`) — admin-enforced constraints users can't override.
- **Managed defaults** (`managed_config.toml`) — starting values applied at launch; users can still change settings during a run, but the client reapplies managed defaults next launch.

## Signature / Usage

Allow only read-only and workspace permission profiles (Codex 0.138.0+):

```toml
default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" omitted -> denied
```

Block never-approve / full-access sandbox modes (legacy):

```toml
allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
```

Enforce command rules:

```toml
[rules]
prefix_rules = [
  { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },
]
```

## Options / Requirement keys

| Key | Controls |
|-----|----------|
| `allowed_approval_policies` / `allowed_approvals_reviewers` | Which approval policies/reviewers (e.g. `auto_review`) users can select |
| `allowed_sandbox_modes` | Legacy sandbox-mode allowlist (`read-only`, `workspace-write`, `danger-full-access`) |
| `allowed_permission_profiles` / `default_permissions` | Permission-profile allowlist (Codex 0.138.0+; preferred over sandbox modes) |
| `allow_appshots` | Enable/disable Appshots |
| `allow_remote_control` | Enable/disable device remote control (not SSH remote connections) |
| `[[remote_sandbox_config]]` | Per-hostname sandbox-mode overrides |
| `allowed_web_search_modes` | Web search mode allowlist |
| `[experimental_network]` | Centrally defined network access rules (experimental; limited Windows support) |
| `[features]` | Pin feature flags (e.g. `in_app_updates`, `browser_use`, `computer_use`, `hooks`) |
| `[computer_use].allow_locked_computer_use` | Restrict Computer Use after a managed Mac locks |
| `guardian_policy_config` | Replace tenant-specific automatic-review policy text |
| `[permissions.filesystem].deny_read` | Deny-read paths/globs users can't override |
| `[hooks]` + `managed_dir` | Enforce managed lifecycle hooks; `allow_managed_hooks_only = true` skips user/project/session/plugin hooks |
| `[rules].prefix_rules` | Enforced command rules (`decision` must be `prompt` or `forbidden`) |
| `[mcp_servers.<name>].identity` | Restrict which MCP servers a client can enable, by command or URL |
| `features.plugins = false` | Disable plugins entirely |
| `[marketplaces]` | Restrict user-configured plugin marketplace sources |

## Locations and precedence

Requirements (low to high precedence): system `requirements.toml` (`/etc/codex/requirements.toml` or `%ProgramData%\OpenAI\Codex\requirements.toml`) → enterprise-managed requirements (cloud config bundle) → legacy `managed_config.toml` fields reinterpreted as requirements → macOS MDM (`com.openai.codex:requirements_toml_base64`).

Managed defaults (top overrides bottom): macOS MDM preferences → `managed_config.toml` (`/etc/codex/managed_config.toml` Unix, `~/.codex/managed_config.toml` Windows) → user's `config.toml`. CLI `--config` overrides apply to the base but managed layers still win.

## Notes

- Permission-profile allowlists require Codex 0.138.0+; earlier clients ignore `allowed_permission_profiles` and managed `default_permissions`.
- `[experimental_network]` is experimental — validate on target client versions/OSes before broad rollout; Windows support is limited.
- Don't deploy managed custom permission profiles until the whole fleet is upgraded to a supporting release.
- macOS MDM setup: base64-encode TOML into `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements) under the `com.openai.codex` preference domain; compatible with Jamf Pro, Fleet, Kandji.

## Related

- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Manage app updates](./manage-app-updates.md)
- [Workspace model availability](./workspace-model-availability.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# Plugin controls

Understand plugin availability, connector-backed capabilities, actions, and connected-system access.

## Overview

Workspace administrators govern plugin availability and connector access in ChatGPT and Codex through six distinct layers.

## Control layers

| Layer | Governs |
|-------|---------|
| Plugin availability | Whether plugins are accessible to users |
| Bundled skills | Reusable instructions shipped with installed plugins |
| Connector access | Whether connector-backed capabilities can be used |
| Connector actions | Which operations users can perform (read-only vs. custom vs. all) |
| Source authorization | External data access through authenticated identities in the connected service |
| Runtime permissions | Agent capabilities during execution |

## Management locations

- Workspace settings (web and desktop surfaces)
- CLI plugin browser (command-line installations)
- Workspace apps / Permissions & Roles sections

## Notes

- For an initial rollout, start with everyday plugin categories (email, calendar, file/document systems such as Google Drive or Notion), read-only actions before write access, and review ownership/scopes/data impact first.
- Connectors operate transiently for non-synced use and respect per-user authorization; chats that use plugins remain available through the Compliance API regardless of sync status.
- Business, Enterprise, and Edu customer data isn't used for model training through plugin connectors.

## Related

- [Skill controls](./skill-controls.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# administration

| Name | Description | Path |
|------|-------------|------|
| Administration | Overview and index of the six administration control boundaries | [administration.md](./administration.md) |
| Admin rollout guide | Plan, configure, and verify a ChatGPT Enterprise rollout in eight steps | [admin-rollout-guide.md](./admin-rollout-guide.md) |
| ChatGPT Work admin FAQ | Access, data, governance, observability, usage, and incident controls for ChatGPT Work | [work-admin-faq.md](./work-admin-faq.md) |
| ChatGPT usage limits and spend controls | Workspace credit controls affecting plan-dependent Codex usage | [usage-limits.md](./usage-limits.md) |
| Groups and provisioning | Group membership sources (manual vs. SCIM) and their access boundary | [groups-and-provisioning.md](./groups-and-provisioning.md) |
| Roles and workspace permissions | Canonical map of the six administration control boundaries | [roles-and-workspace-permissions.md](./roles-and-workspace-permissions.md) |
| Access tokens | Create, rotate, and revoke Codex access tokens for automation | [access-tokens.md](./access-tokens.md) |
| Analytics API | Programmatic, aggregated Codex usage/activity metrics | [analytics-api.md](./analytics-api.md) |
| Compliance API and audit events | Auditable records for security, legal, governance, investigation | [compliance-api.md](./compliance-api.md) |
| Governance | Choosing the right analytics/usage/audit surface per question | [governance.md](./governance.md) |
| Workspace analytics | Comparing workspace analytics, Codex analytics, Analytics API, Compliance API | [workspace-analytics.md](./workspace-analytics.md) |
| Workspace model availability | Model access boundaries across ChatGPT, Codex clients, Codex cloud, API Platform | [workspace-model-availability.md](./workspace-model-availability.md) |
| Plugin controls | Plugin availability, connector-backed capabilities, and action controls | [plugin-controls.md](./plugin-controls.md) |
| Skill controls | Comparing ChatGPT workspace, local filesystem, and plugin skill controls | [skill-controls.md](./skill-controls.md) |
| Managed configuration | Admin-enforced requirements and managed defaults for local Codex clients | [managed-configuration.md](./managed-configuration.md) |
| Manage app updates | Turning off/on the ChatGPT desktop app's built-in updater | [manage-app-updates.md](./manage-app-updates.md) |
| Deploy the Windows app | Enterprise installation and update paths for the Windows desktop app | [windows-deployment.md](./windows-deployment.md) |
| Authentication | ChatGPT sign-in vs. API key sign-in, credential storage, headless login | [authentication.md](./authentication.md) |

# Roles and workspace permissions

Separate ChatGPT workspace access from local runtime, API, plugin, and source-system controls. The canonical map of administration boundaries.

## Overview

Administration spans six control boundaries. Granting access at one boundary doesn't grant access at another.

## Control boundaries

| Boundary | Controls | Doesn't control | Current source |
|----------|----------|------------------|-----------------|
| ChatGPT workspace | Membership, seats, built-in admin roles, role-based access to workspace features | Local agent permissions, Platform API org access, connected-service permissions | ChatGPT workspace access / RBAC (Help Center) |
| Local clients | Runtime behavior for the ChatGPT desktop app, Codex CLI, IDE extension: approvals, filesystem/network access, permission profiles, allowed integrations | A ChatGPT seat, feature/model entitlement, external data access | [Managed configuration](./managed-configuration.md), Permissions |
| Codex cloud | Eligibility for hosted Codex workflows and available cloud environments | Local runtime policy, source-system repo permissions | Cloud environments |
| Platform API | Org/project membership, API keys, model access, usage, billing | ChatGPT workspace membership, local-client access, Codex cloud access | OpenAI API Platform |
| Plugins | Plugin availability/installation, bundled skills, connector access, supported connector actions | Authorization in the connected service, broader local/cloud runtime permissions | [Plugin controls](./plugin-controls.md) |
| Connected systems | Which repos/files/messages/actions the authenticated account can access | ChatGPT workspace, plugin, Codex cloud, Platform API entitlement | The connected service's own admin controls |

## Notes

- A request must pass every applicable boundary. Workspace access can make a plugin available, but the connected service still decides which data the signed-in account can read.
- In workspace settings, **Codex Local** is a grouping label for local access and access-token controls, not a separate product; **Allow members to use Codex Local** covers the ChatGPT desktop app, Codex CLI, and IDE extension.
- Managed configuration is a separate layer constraining supported runtime behavior — it doesn't change seat, workspace role, model entitlement, or external-system permissions.

## Related

- [Admin rollout guide](./admin-rollout-guide.md)
- [Groups and provisioning](./groups-and-provisioning.md)
- [Workspace model availability](./workspace-model-availability.md)
- [Access tokens](./access-tokens.md)
- [Managed configuration](./managed-configuration.md)
- [Authentication](./authentication.md)

# Skill controls

Compare ChatGPT workspace, local filesystem, and plugin skill controls.

## Overview

Skills are reusable workflows made from instructions and supporting resources. ChatGPT workspace Skills, filesystem skills used by local clients (desktop app / CLI / IDE extension), and plugins that package skills each have separate lifecycle and access controls.

## Distribution models

| Distribution model | Use it for | Administration boundary |
|---------------------|-------------|--------------------------|
| ChatGPT workspace Skill | Sharing/installing an approved workflow through ChatGPT workspace features | ChatGPT workspace skill permissions and lifecycle controls |
| Local filesystem skill | Loading an installed workflow from a repository, user, admin, or bundled location | Filesystem distribution, local client configuration, runtime permissions |
| Plugin | Packaging one or more skills with optional connectors, MCP servers, hooks, metadata | Plugin availability/installation + separate controls for every bundled capability |

## Notes

- Moving a skill between distribution models doesn't transfer ChatGPT workspace ownership, sharing, role assignments, plugin installation state, or connector authorization — configure each capability through the control surface that owns it.
- Plugins are available with ChatGPT Work on the web, with ChatGPT Work and Codex in the desktop app, and through the Codex CLI plugin browser — not in Chat, the IDE extension, or mobile. Public plugins are drawn from one universal directory shared by ChatGPT and Codex.

## Related

- [Plugin controls](./plugin-controls.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# ChatGPT usage limits and spend controls

Understand when ChatGPT workspace credit controls can affect plan-dependent Codex usage.

## Overview

These controls apply to "eligible activity under the plan for the workspace" — potentially including some Codex usage, depending on the subscription tier — when an organization uses shared or purchased ChatGPT workspace credits. They operate independently from OpenAI API Platform billing.

## Notes

- Usage controls don't determine feature entitlement or permissions, though exhausted limits may restrict access to features.
- They don't govern permissions in source systems or affect Platform API usage.
- Enterprise and Education plans, and Business plans, have separate dedicated management/credit-and-spend procedures — check current Help Center guidance for the applicable plan type.

## Related

- [Admin rollout guide](./admin-rollout-guide.md)
- [Governance](./governance.md)
- [Workspace analytics](./workspace-analytics.md)
- [ChatGPT Work admin FAQ](./work-admin-faq.md)

# Deploy the Windows app

Choose an enterprise installation and update path for the ChatGPT desktop app on Windows.

## Overview

Users can self-install via the web installer, or IT can deploy centrally with Microsoft Intune or another MDM/software-deployment platform. The app is Store-signed but users don't need to browse the Microsoft Store.

## Signature / Usage

Command-line install:

```powershell
winget install --id 9PLM9XGG6VKS -s msstore
```

Enterprise MDM deployment: search "ChatGPT from OpenAI" in the Store app flow, or use Store product ID `9PLM9XGG6VKS`.

## Install without Microsoft distribution services

Download the Store-signed MSIX per architecture and, if required, the offline license file, then ingest into your MDM/software-deployment platform:

| Device architecture | Package |
|----------------------|---------|
| x64 | `ChatGPT-x64.msix` |
| Arm64 | `ChatGPT-arm64.msix` |

## Notes

- This deployment path supports x64/Arm64 initial installation in restricted environments but doesn't provide a standalone MSI or non-Store EXE.
- After initial install, devices that can reach `persistent.oaistatic.com` update automatically unless [managed configuration](./managed-configuration.md) disables the built-in updater.
- See [Manage app updates](./manage-app-updates.md) for turning off/on the in-app updater and deploying approved versions.

## Related

- [Manage app updates](./manage-app-updates.md)
- [Admin rollout guide](./admin-rollout-guide.md)

# ChatGPT Work admin FAQ

Manage access, data, governance, observability, usage, and incident controls for ChatGPT Work (the Codex-powered, longer multi-step task mode inside ChatGPT).

## Overview

ChatGPT Work lets users delegate longer, multi-step tasks: it gathers context from chats, files, workspace resources, and connected systems, uses approved tools, and creates review-ready outputs. Launched July 9, 2026; for Enterprise/Edu, web and mobile access is off by default during a two-week preview (admins can enable it; explicit opt-outs persist). Desktop access is governed separately through Codex Local permissions and managed configuration.

## Core administrative controls

| Layer | Governs |
|-------|---------|
| Access to the enterprise workspace | SSO, domain verification, SCIM provisioning, user lifecycle, identity-group sync, MFA (Global Admin Console) |
| Access to ChatGPT Work within the workspace | ChatGPT Work access control + RBAC |
| Group membership | SCIM/identity-provider group sync (see [Groups and provisioning](./groups-and-provisioning.md)) |
| Workspace and member roles | Built-in Owner/Admin/Member roles + custom roles (see [Roles and workspace permissions](./roles-and-workspace-permissions.md)) |
| Plugins and connectors | Plugin policy, connector access/action controls (see [Plugin controls](./plugin-controls.md)) |
| Source-system permissions | Native application account/connection permissions |
| Approval and action restrictions | Per-connector action control (all / read-only / custom) |
| Credits | Per-user monthly limits (workspace default, group defaults, overrides) (see [ChatGPT usage limits and spend controls](./usage-limits.md)) |
| Analytics and reporting | Global Admin Console, workspace analytics, Compliance API, Codex reporting (see [Governance](./governance.md)) |

## Action risk categories

- **Read** — access/search/summarize without changing data
- **Draft** — prepare content for human review
- **Write** — create/update/delete records in connected systems
- **Share** — send/publish to more people/systems
- **Scheduled** — recurring/future-triggered tasks
- **Execute** — run code, shell commands, browser automation

## Incident and revocation controls

- Remove workspace/group access (SCIM-managed users: remove at the identity provider)
- Disable/restrict the relevant plugin or connector
- Revoke a shared connection, bot, service account, or Codex access token
- Remove/unpublish a Workspace Agent
- Disable the relevant schedule or trigger
- Revoke Codex access token, repository connection, and cloud-environment access individually — managed configuration is not a revocation mechanism

## Notes

- Governance spans three separate layers: ChatGPT Work access controls, Workspace Agent controls, and Codex managed configuration — they are not one uniform policy surface.
- The Compliance Logs Platform covers user prompts and agent responses (not files, actions, or tool calls) and retains data for 30 days; export continuously for longer retention.
- For Codex activity specifically, local runs execute on the user's machine under OS sandboxing and approval policies; Codex cloud runs in isolated OpenAI-managed environments.

## Related

- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Groups and provisioning](./groups-and-provisioning.md)
- [Governance](./governance.md)
- [ChatGPT usage limits and spend controls](./usage-limits.md)
- [Managed configuration](./managed-configuration.md)

# Workspace analytics

Compare ChatGPT workspace analytics, Codex analytics, reporting APIs, and audit records.

## Overview

Use ChatGPT workspace analytics for broad workspace adoption, Codex analytics for Codex-focused reporting, the Analytics API for programmatic aggregates, and the Compliance API for auditable records. These reporting surfaces don't grant product access or set runtime policy.

## Reporting surfaces

| Surface | Use it for | Contract owner |
|---------|-------------|-----------------|
| ChatGPT workspace analytics | Interactive, workspace-wide adoption/engagement reporting | Help Center guidance |
| Codex analytics | Interactive Codex adoption/activity reporting | Authenticated Codex analytics dashboard |
| Analytics API | Programmatic, aggregated Codex reporting | Authenticated Codex Analytics API reference |
| Compliance API | Audit, security, legal, and investigation records | Authenticated Admin API reference |

## Notes

- Treat downloaded reports as identifiable organizational data; apply the organization's access/storage/retention policy rather than assuming export privacy matches an aggregated dashboard.
- Dashboard categories, fields, filters, and export formats can change independently of this page — use the authenticated API references for automated/programmatic reporting.
- Analytics describes activity; it doesn't grant access or change runtime permissions.

## Related

- [Analytics API](./analytics-api.md)
- [Compliance API and audit events](./compliance-api.md)
- [Governance](./governance.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [ChatGPT usage limits and spend controls](./usage-limits.md)

# Workspace model availability

Separate model access across ChatGPT, Codex in the ChatGPT desktop app, Codex CLI, the IDE extension, Codex cloud, and the OpenAI API Platform.

## Overview

Model availability depends on the product surface and authentication boundary. A ChatGPT workspace model setting isn't a universal model switch for Codex across every surface.

## Model boundaries

| Boundary | Model access follows |
|----------|------------------------|
| ChatGPT workspace | Workspace plan, member access, workspace settings, role permissions |
| Codex in desktop app / CLI / IDE extension (ChatGPT sign-in) | Models supported by the client + access of the signed-in ChatGPT identity |
| Codex cloud | Models supported by hosted Codex workflows + signed-in identity access |
| Codex in desktop app / CLI / IDE extension (API-key auth) | OpenAI API organization and project associated with the key |

## GPT-5.4 retirement (August 31, 2026)

GPT-5.4 and GPT-5.4 mini retire from Codex for ChatGPT-signed-in users. Update workspace defaults, saved model settings, managed configurations, custom agents, and scheduled tasks:

- Replace `gpt-5.4` with `gpt-5.6-terra`
- Replace `gpt-5.4-mini` with `gpt-5.6-luna`

The OpenAI API and Codex authenticated with your own API key aren't affected.

## Notes

- A permission profile can't grant model access; model access also can't weaken sandbox, approval policy, network controls, or source-system permissions.
- To troubleshoot missing models: confirm product surface + sign-in method, confirm workspace/org/project, review current access controls for that boundary, and check client/Codex cloud support for the model.

## Related

- [Admin rollout guide](./admin-rollout-guide.md)
- [Groups and provisioning](./groups-and-provisioning.md)
- [Roles and workspace permissions](./roles-and-workspace-permissions.md)
- [Managed configuration](./managed-configuration.md)
- [Authentication](./authentication.md)

# Custom Instructions with AGENTS.md

Codex reads `AGENTS.md` files before doing any work, layering global guidance with project-specific overrides so every task starts with consistent expectations.

## Signature / Usage

```md
# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
```

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

## How Codex discovers guidance

Codex builds an instruction chain once per run (once per TUI session), in this precedence order:

1. **Global scope**: in the Codex home directory (`~/.codex`, or `$CODEX_HOME`), Codex reads `AGENTS.override.md` if present, otherwise `AGENTS.md`. Only the first non-empty file at this level is used.
2. **Project scope**: starting at the project root (typically the Git root), Codex walks down to the current working directory. In each directory it checks `AGENTS.override.md`, then `AGENTS.md`, then any names in `project_doc_fallback_filenames`, including at most one file per directory.
3. **Merge order**: files are concatenated from the root downward, joined by blank lines. Files closer to the current directory override earlier guidance because they appear later in the combined prompt.

Codex skips empty files and stops adding files once the combined size reaches `project_doc_max_bytes` (32 KiB by default).

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `project_doc_max_bytes` | number (config.toml) | Byte limit for the combined instruction chain (default 32 KiB). |
| `project_doc_fallback_filenames` | string[] (config.toml) | Alternate filenames (e.g. `TEAM_GUIDE.md`) treated as instructions files when `AGENTS.md` is absent. |
| `CODEX_HOME` | env var | Overrides the Codex home directory (default `~/.codex`), enabling alternative profiles. |
| `AGENTS.override.md` | file | Takes precedence over `AGENTS.md` in the same directory; useful for temporary overrides. |

## Notes

- Add a `## Code Review Rules` section to the `AGENTS.md` closest to the governed code to customize [Codex code review in GitHub](https://learn.chatgpt.com/docs/third-party/github); keep rules concise with a stated safe path/exception and leave formatting/lint checks to CI.
- Set `CODEX_HOME` to point Codex at a different home directory (e.g. a project-specific automation profile).
- Verify the active chain with `codex --ask-for-approval never "Summarize the current instructions."`, or audit loaded files via `codex -c log_dir=./.codex-log` and `./.codex-log/codex-tui.log`.
- If instructions look stale, restart Codex in the target directory; there is no manual cache since the chain rebuilds every run.

## Related

- [Rules](./rules.md)
- [Subagents](./subagents.md)
- [Prompting](./prompting.md)

# Hooks

Extensibility framework that lets you inject your own scripts into the agentic loop — logging/analytics, blocking accidental secret pastes, auto-summarizing chats, validating a turn before it stops, or customizing prompting per directory. Hooks are enabled by default.

## Signature / Usage

```json
// ~/.codex/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}
```

Equivalent inline TOML in `config.toml`:

```toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `PreToolUse` / `PostToolUse` | event | Before/after a tool call (Bash, `apply_patch`, MCP tools, other local function tools). `PreToolUse` can deny or rewrite (`updatedInput`) a supported call; `PostToolUse` can't undo side effects but can replace the model-visible result. |
| `PermissionRequest` | event | Runs when Codex is about to ask for approval; can `allow`/`deny` the request or defer to the normal approval prompt. |
| `SessionStart` / `SessionEnd` | event | Session begins (`startup`/`resume`/`clear`/`compact`) / ends (main thread only, not subagents). |
| `SubagentStart` / `SubagentStop` | event | A subagent starts/stops; `matcher` filters on `agent_type`. |
| `UserPromptSubmit` | event | Before a user prompt is sent; can add context or block it. |
| `PreCompact` / `PostCompact` | event | Before/after Codex compacts the chat (`matcher` on `manual`/`auto`). |
| `Stop` | event | The turn is about to end; `decision: "block"` continues the turn with `reason` as a new prompt. |
| `matcher` | regex string | Filters when a hook fires (tool name, compaction trigger, subagent type, etc., depending on event). `"*"`, `""`, or omitted matches every occurrence. |
| `type` | `"command"` | Only supported handler type today; `prompt` and `agent` are parsed but skipped. |
| `command` / `commandWindows` | string | Shell command to run; `commandWindows` (or `command_windows` in TOML) overrides on Windows. |
| `timeout` | number (seconds) | Default `600`; `SessionEnd` defaults to `1`, max `3`. |
| `additionalContextLimit` | number | Approximate token threshold before oversized `additionalContext` is spilled to disk (`hook_outputs/<session_id>/<uuid>.txt`) and replaced with a preview. Default `2500`; `0` passes full output. |

## Notes

- Codex discovers hooks next to active config layers: `~/.codex/hooks.json`, `~/.codex/config.toml`, `<repo>/.codex/hooks.json`, `<repo>/.codex/config.toml`, plus managed `requirements.toml` (`[hooks]`, `managed_dir`) and plugin-bundled `hooks/hooks.json`. Project-local hooks load only when the project `.codex/` layer is trusted.
- Before a non-managed command hook runs, Codex requires you to review and trust its exact definition (hash-based); use `/hooks` in the CLI to inspect, trust, or disable hooks. Managed hooks (system/MDM/cloud/`requirements.toml`) are trusted by policy and can't be disabled from the user browser.
- Turn hooks off with `[features] hooks = false` (`codex_hooks` is a deprecated alias); pin `[features].hooks = true` in `requirements.toml` to force-enable managed hooks, or `allow_managed_hooks_only = true` to skip all non-managed hook sources.
- Shell wrappers with only plain words joined by `&&`/`||`/`;`/`|` are split per-command before `PreToolUse`/`PostToolUse` evaluation; scripts using redirection, substitution, env vars, wildcards, or control flow run as one opaque `["bash", "-lc", "<script>"]` call.
- Inline `[hooks]` tables as a `config.toml` surface (with an example `PreToolUse` block) are also summarized in the config category — see `../config/config-advanced.md`; this page is the full lifecycle/event/matcher/schema reference.
- **Codex hook event names (`PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`) are identical to Claude Code's hook events, and Codex even sets `CLAUDE_PLUGIN_ROOT`/`CLAUDE_PLUGIN_DATA` for plugin compatibility — but the two systems are not interchangeable.** Codex hooks live in `~/.codex/hooks.json` / inline `[hooks]` in `config.toml`; Claude Code hooks are configured in `.claude/settings.json`. Wire formats, plugin manifests, and trust models differ despite the shared event vocabulary.

## Related

- [Rules](./rules.md)
- [Subagents](./subagents.md)
- Advanced Configuration (`../config/config-advanced.md`)

# Prompting

General guidance for writing effective prompts across Chat, ChatGPT Work, and Codex, plus Codex-specific prompting workflows (explain a codebase, fix a bug, write a test, code review, delegate to cloud).

## Signature / Usage

```text
Bug: Clicking "Save" on the settings screen sometimes shows "Saved" but doesn't persist the change.

Repro:
1) Start the app: npm run dev
2) Go to /settings
3) Toggle "Enable alerts"
4) Click Save
5) Refresh the page: the toggle resets

Constraints:
- Do not change the API shape.
- Keep the fix minimal and add a regression test if feasible.

Start by reproducing the bug locally, then propose a patch and run checks.
```

## Options / Props

| Name | Description |
|------|-------------|
| Goal | What Codex should do. |
| Context | Information/sources that help (files via `@`/`/mention`, repro steps, constraints). |
| Output | Format, length, level of detail needed. |
| Boundaries | What must stay unchanged; what to avoid or confirm before acting. |

## Notes

- A useful Codex prompt names the target behavior, points to relevant code or reproduction steps, states constraints, and says how to verify the change.
- `/plan` (app composer) asks Codex to investigate and propose an approach before editing a multi-step task; `/goal` sets a persistent goal once Goal mode is available.
- The IDE extension automatically includes open files as context; in the CLI, mention paths explicitly or attach files with `/mention` and `@` path autocomplete.
- Codex runs local commands inside a sandbox limiting file/network access; crossing that boundary requires following the approval policy.
- Steering vs queuing a follow-up while Codex is working: **Steer** injects the message into the current run (CLI: `Enter`); **Queue** saves it for the next run (CLI: `Tab`).
- `/review` runs a local code review of the working tree (optionally with focus instructions, e.g. `/review Focus on edge cases and security issues`); `@codex review` triggers review from a GitHub PR comment.
- Documented Codex workflows: explain a codebase, fix a bug, write a test, prototype from a screenshot, iterate on UI with live updates, delegate a refactor to the cloud, do a local code review, review a GitHub pull request, update documentation — each pairs an IDE and/or CLI workflow with context notes and a verification step.

## Related

- [Custom Instructions with AGENTS.md](./agents-md.md)
- [Subagents](./subagents.md)

# Agent Configuration

| Name | Description | Path |
|------|-------------|------|
| Custom Instructions with AGENTS.md | Codex reads `AGENTS.md` files before doing any work, layering global guidance with project-specific overrides so every task starts with consistent expectations. | [agents-md.md](./agents-md.md) |
| Hooks | Extensibility framework that lets you inject your own scripts into the agentic loop — logging/analytics, blocking accidental secret pastes, auto-summarizing chats, validating a turn before it stops, or customizing prompting per directory. Hooks are enabled by default. | [hooks.md](./hooks.md) |
| Prompting | General guidance for writing effective prompts across Chat, ChatGPT Work, and Codex, plus Codex-specific prompting workflows (explain a codebase, fix a bug, write a test, code review, delegate to cloud). | [prompting.md](./prompting.md) |
| Rules | Rules control which commands Codex can run outside the sandbox. Rules are experimental and may change. | [rules.md](./rules.md) |
| Speed | Fast mode and Codex-Spark increase Codex's effective throughput, trading credit consumption for lower latency. | [speed.md](./speed.md) |
| Subagents | ChatGPT Work and Codex can run subagent workflows: spawning specialized agents in parallel and collecting their results into one response, useful for highly parallel tasks like codebase exploration or multi-step feature plans. In local Codex clients you can also define custom agents with distinct models and instructions. | [subagents.md](./subagents.md) |

# Rules

Rules control which commands Codex can run outside the sandbox. Rules are experimental and may change.

## Signature / Usage

```python
# ~/.codex/rules/default.rules
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
        "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
        "gh pr --repo openai/codex view 7888",
    ],
)
```

```shell
codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `pattern` | list (required) | Command prefix to match; each element is a literal string or a union of literals (e.g. `["view", "list"]`) to match alternatives at that position. |
| `decision` | `"allow"` \| `"prompt"` \| `"forbidden"` (default `"allow"`) | Action when the rule matches. Codex applies the most restrictive decision when multiple rules match (`forbidden` > `prompt` > `allow`). |
| `justification` | string (optional) | Human-readable reason surfaced in approval prompts or rejection messages; recommend an alternative when using `forbidden`. |
| `match` / `not_match` | list (default `[]`) | Example commands Codex validates when loading the rules file, to catch authoring mistakes. |

## Notes

- Create a `.rules` file under a `rules/` folder next to an active config layer (e.g. `~/.codex/rules/default.rules`); restart Codex to load changes.
- Codex scans `rules/` under every active config layer at startup, including Team Config locations and `~/.codex/rules/`. Project-local rules under `<repo>/.codex/rules/` load only when the project `.codex/` layer is trusted.
- Allow-listing a command in the TUI writes to `~/.codex/rules/default.rules`. With Smart approvals enabled (default), Codex may propose a `prefix_rule` during escalation requests — review the suggested prefix before accepting.
- Admins can enforce restrictive `prefix_rule` entries from `requirements.toml` (managed configuration).
- Shell wrappers (`bash -lc`, `zsh -c`, etc.) containing only plain words joined by safe operators (`&&`, `||`, `;`, `|`) are parsed with tree-sitter and split into individual commands before rule evaluation, so the most restrictive per-command result wins (e.g. `git add . && rm -rf /` is not auto-allowed just because `git add` is allowed). Scripts using redirection, substitution, env vars, wildcards, or control flow are NOT split and are evaluated as a single `["bash", "-lc", "<full script>"]` invocation.
- The `.rules` file format uses Starlark (Python-like syntax, side-effect free).

## Related

- [Custom Instructions with AGENTS.md](./agents-md.md)
- [Subagents](./subagents.md)

# Speed

Fast mode and Codex-Spark increase Codex's effective throughput, trading credit consumption for lower latency.

## Signature / Usage

```text
/fast on
/fast off
/fast status
```

```toml
# config.toml
service_tier = "fast"
[features]
fast_mode = true
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `/fast on` \| `/fast off` \| `/fast status` | CLI command | Change or inspect the current Fast mode setting. |
| `service_tier = "fast"` | config.toml | Persists Fast mode as the default. |
| `[features].fast_mode` | boolean (config.toml) | Enables Fast mode alongside `service_tier`. |

## Notes

- Fast mode increases supported model speed by 1.5x and consumes credits at a higher rate than Standard mode. It currently supports GPT-5.6, GPT-5.5, and GPT-5.4: GPT-5.6/5.5 consume credits at 2.5x the Standard rate, GPT-5.4 at 2x.
- Fast mode is available in the ChatGPT desktop app, Codex CLI, and IDE extension when signed in with ChatGPT. It is a ChatGPT credit feature; with an API key, Codex uses API token pricing instead and ChatGPT credit multipliers don't apply. API Priority processing has its own billing rate (2x Standard API token rate for GPT-5.6).
- Codex-Spark (`gpt-5.3-codex-spark`) is a separate, less-capable model optimized for near-instant, real-time coding iteration — distinct from Fast mode, with its own usage limits. During research preview it is available only to ChatGPT Pro subscribers.
- ChatGPT Work and Codex share the same pricing, credits, and usage limits.

## Related

- [Subagents](./subagents.md)

# Subagents

ChatGPT Work and Codex can run subagent workflows: spawning specialized agents in parallel and collecting their results into one response, useful for highly parallel tasks like codebase exploration or multi-step feature plans. In local Codex clients you can also define custom agents with distinct models and instructions.

## Signature / Usage

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

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
```

## Options / Props

Custom agent file (required fields): `name`, `description`, `developer_instructions`. Optional: any supported `config.toml` key, e.g. `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config`.

| Field | Type | Required | Purpose |
|-------|------|----------|---------|
| `agents.enabled` | boolean | No | Enable or disable multi-agent tools (default `true`). |
| `agents.max_concurrent_threads_per_session` | number | No | Cap concurrently open spawned-agent threads, excluding the primary (legacy alias: `agents.max_threads`). |
| `agents.default_subagent_model` | string | No | Default model for spawned agents. |
| `agents.default_subagent_reasoning_effort` | string | No | Default reasoning effort for spawned agents. |
| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted (default `true`). |
| `name` (agent file) | string | Yes | Agent name used when spawning or referring to this agent. |
| `description` (agent file) | string | Yes | Human-facing guidance for when Codex should use this agent. |
| `developer_instructions` (agent file) | string | Yes | Core instructions defining the agent's behavior. |

## Notes

- Built-in agents: `default` (general-purpose fallback), `worker` (execution-focused implementation/fixes), `explorer` (read-heavy codebase exploration). Custom agents are defined as standalone TOML files under `~/.codex/agents/` (personal) or `.codex/agents/` (project-scoped); a custom agent name matching a built-in name takes precedence.
- Setting resolution: an explicit spawn value wins, then the corresponding `[agents]` default, then the parent's value; other session settings (`sandbox_mode`, `mcp_servers`, `skills.config`) inherit from the parent when the custom agent file omits them.
- Model guidance: `gpt-5.6` for demanding, ambiguous multi-step work; `gpt-5.6-terra` for read-heavy/parallel workers returning distilled results; `gpt-5.6-luna` for fast, narrowly scoped, high-volume work. Reasoning effort ranges `low` → `medium` → `high` → `xhigh`/`max` → `ultra`.
- Trigger subagents with direct instructions ("spawn two agents", "delegate this work in parallel"); local Codex clients (app/CLI/IDE) also delegate when applicable `AGENTS.md` or skill instructions request it. In the CLI, use `/agent` to inspect and switch between agent threads.
- Subagents inherit the current sandbox policy / permission mode of the parent turn (app/CLI/IDE); ChatGPT Work runs subagents in its hosted environment without a local sandbox control. Override the sandbox per custom agent (e.g. `sandbox_mode = "read-only"`).
- Subagent workflows consume more tokens than comparable single-agent runs because each subagent does its own model and tool work. Favor parallel agents for read-heavy tasks (exploration, tests, triage, summarization); be careful with parallel write-heavy workflows due to edit conflicts.
- This is OpenAI Codex's own agent-configuration mechanism (`~/.codex/agents/`, `.codex/agents/*.toml`, `AGENTS.md`) and is unrelated to Claude Code's `.claude/` directory structure (subagent definitions, skills, rules) — the two are not interchangeable, despite similar terminology ("subagent", "agent").

## Related

- [Custom Instructions with AGENTS.md](./agents-md.md)
- [Rules](./rules.md)
- [Speed](./speed.md)

# Amazon Bedrock

Configure local ChatGPT Work and Codex surfaces (desktop app, CLI, IDE extension, SDK) to use OpenAI models through Amazon Bedrock instead of the OpenAI-hosted Responses API. The local client sends model requests to Bedrock using AWS-managed authentication; ChatGPT sign-in and `OPENAI_API_KEY` are not used for this provider.

## Signature / Usage

```toml
# ~/.codex/config.toml
model_provider = "amazon-bedrock"
```

```bash
export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>
export AWS_REGION=us-east-2
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `model_provider = "amazon-bedrock"` | config.toml | Selects the Amazon Bedrock Mantle path in supported commercial AWS Regions (not AWS GovCloud). |
| Bedrock API key | env vars | `AWS_BEARER_TOKEN_BEDROCK` + `AWS_REGION` (Region is required with this auth path). Checked first. |
| AWS SDK credential chain | fallback | Shared `aws configure` files, `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`, `aws login`, `aws sso login --profile <name>` + `AWS_PROFILE`, or a federated identity via `credential_process`. |

## Notes

- Desktop app and IDE extension may not inherit shell environment variables — put `AWS_BEARER_TOKEN_BEDROCK`/`AWS_REGION` in `~/.codex/.env` and restart the app/extension.
- Verify with `/status` in the CLI (confirms the `amazon-bedrock` provider) or by starting a new task after restarting the desktop app/IDE extension.
- Supported model IDs (Bedrock-side, exact strings): `openai.gpt-5.6-sol`, `openai.gpt-5.6-terra`, `openai.gpt-5.6-luna`, `openai.gpt-5.5`, `openai.gpt-5.4`; availability varies by AWS Region.
- Fast Mode is unavailable (Bedrock supports on-demand inference only, not priority processing). Also unavailable: Codex cloud, ChatGPT Work on the web, image generation/voice dictation/web search, GitHub/Slack/Linear cloud integrations, workspace SSO/RBAC/SCIM/analytics/compliance API. Local features (sandboxing, permission controls, `requirements.toml`, MCP, subagents, Codex Security plugin/CLI, scheduled tasks, worktrees) remain available.
- Troubleshooting checklist: exact model ID, Region where the model is available, valid/non-expired Bedrock API key or AWS credentials, IAM permission for the selected model. AWS credential/quota/billing/regional-availability issues go to the customer's AWS administrator, not OpenAI Support.
- A brief `[model_providers.amazon-bedrock.aws]` (`profile`/`region`) form also appears among the generic custom-provider examples in `config-advanced.md`; this page is the dedicated Bedrock setup guide (auth options, verification, feature-availability matrix).

## Related

- Advanced Configuration (`./config-advanced.md`)
- Environment variables (`./environment-variables.md`)
- Models (`../getting-started/models.md`)

# Advanced Configuration

More advanced `config.toml` options for providers, policies, and integrations.

## Profiles

Profiles are named configuration layers switched from the CLI. `--profile profile-name` loads `~/.codex/config.toml`, then overlays `~/.codex/profile-name.config.toml`. Names may contain letters, numbers, hyphens, underscores.

```toml
# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"
```

```shell
codex --profile deep-review
codex exec --profile deep-review "review this change"
```

A profile file only needs the values that differ from the base user config (it sits above user config, below project/CLI config).

In Codex 0.134.0+, `--profile` no longer reads `[profiles.profile-name]` from `config.toml`; move legacy profile settings into `~/.codex/profile-name.config.toml` and drop the top-level `profile = "profile-name"` selector.

## One-off overrides from the CLI

```shell
# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
```

- Keys use dot notation for nested values (e.g. `mcp_servers.context7.enabled=false`).
- `--config` values parse as TOML; quote them so the shell doesn't split on spaces.
- Unparseable values are treated as strings.

## Config and state locations

`CODEX_HOME` (default `~/.codex`) holds `config.toml`, `auth.json` (or OS keychain), `history.jsonl`, logs, caches.

```toml
openai_base_url = "https://us.api.openai.com/v1"
```

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

Codex walks from the project root to cwd loading every `.codex/config.toml`; closest file wins on key conflicts. Loaded only when the project is trusted. Relative paths (e.g. `model_instructions_file`) resolve relative to the containing `.codex/` folder.

Project-local config cannot override: `openai_base_url`, `chatgpt_base_url`, `apps_mcp_product_sku`, `model_provider`, `model_providers`, `notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, `otel` (Codex warns and ignores these). Set those in user-level config; select profiles with `--profile`.

## Hooks

Hooks load from `hooks.json` or inline `[hooks]` next to active config layers: `~/.codex/hooks.json`, `~/.codex/config.toml`, `<repo>/.codex/hooks.json`, `<repo>/.codex/config.toml`. Project-local hooks load only for trusted projects.

```toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"
```

If a layer has both `hooks.json` and inline `[hooks]`, Codex loads both and warns.

## Agent roles

`[agents]` in `config.toml` configures subagent roles (see the Subagents docs, out of this scope).

## Project root detection

```toml
# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]
```

Default marker is `.git`. Set `project_root_markers = []` to skip parent search and use cwd as root.

## Custom model providers

A provider defines base URL, wire API, auth, and headers. Custom providers cannot reuse reserved IDs `openai`, `ollama`, `lmstudio`.

```toml
model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
```

```toml
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true
```

Add headers:

```toml
[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
```

Command-backed bearer token auth:

```toml
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000
```

Don't combine `[model_providers.<id>.auth]` with `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.

### Amazon Bedrock provider

```toml
model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"
```

### OSS mode (local providers)

```toml
oss_provider = "ollama" # or "lmstudio"
```

### Azure provider

```toml
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000
```

To change the base URL of the built-in `openai` provider, use `openai_base_url` — don't define `[model_providers.openai]`.

## Approval policies and sandbox modes

```toml
approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

[sandbox_workspace_write]
exclude_tmpdir_env_var = false
exclude_slash_tmp = false
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false

[auto_review]
policy = """
Use your organization's automatic review policy.
"""
```

Granular policy allows/auto-rejects individual prompt categories: `sandbox_approval`, `rules`, `mcp_elicitations`, `request_permissions`, `skill_approval`.

Disable sandboxing entirely (only if the environment already isolates processes):

```toml
sandbox_mode = "danger-full-access"
```

Named permission profiles (built-ins and custom `[permissions.<name>]` tables) are documented separately under Permissions (security-automation scope in this skill).

## Shell environment policy

```toml
[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"
```

Order: automatic exclusions -> custom exclusions -> `set` values -> include-pattern allowlist. `inherit`: `all` | `core` | `none`. Legacy `exclude`/`include_only` arrays remain supported but cannot combine with `filters` in the same layer.

## MCP servers

See [Model Context Protocol](./mcp-config.md) for MCP server configuration details.

## Observability and telemetry (OTel)

```toml
[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled
```

```toml
[otel]
exporter = { otlp-http = { endpoint = "https://otel.example.com/v1/logs", protocol = "binary", headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } } }
```

Disable anonymous usage metrics collection:

```toml
[analytics]
enabled = false
```

Disable `/feedback` submission:

```toml
[feedback]
enabled = false
```

Suppress or surface reasoning output:

```toml
hide_agent_reasoning = true
show_raw_agent_reasoning = true
```

## Notifications

```toml
notify = ["python3", "/path/to/notify.py"]
```

The script receives one JSON argument with fields: `type` (`agent-turn-complete`), `thread-id`, `turn-id`, `cwd`, `input-messages`, `last-assistant-message`.

`notify` runs an external program; `tui.notifications` is built into the TUI (optionally filtered by event type); `tui.notification_method` picks `auto`/`osc9`/`bel`; `tui.notification_condition` picks `unfocused`/`always`.

## History persistence

```toml
[history]
persistence = "none"     # disable local history
max_bytes = 104857600    # 100 MiB cap; oldest entries dropped when exceeded
```

## Clickable citations

```toml
file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none
```

## Project instructions discovery

- `project_doc_max_bytes`: bytes read from each `AGENTS.md`.
- `project_doc_fallback_filenames`: fallback filenames when `AGENTS.md` is missing.

## Desktop custom file handlers

User-level only, ChatGPT desktop app:

```toml
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]
```

| Field | Required | Description |
|-------|----------|-------------|
| `label` | Yes | Display name in the app. |
| `icon` | Yes | Bundled icon, base64 `data:image/...`, `file:` URI, or absolute path. |
| `command` | Yes | Executable path or command name. |
| `args` | No | Args inserted between command and file input. Default `[]`. |
| `input` | No | `path` \| `json_argument` \| `json_stdin`. Default `path`. |
| `supports_ssh` | No | Offer handler for files in SSH workspaces. Default `false`. |

## TUI options

`[tui]` keys include `notifications`, `notification_method`, `notification_condition`, `animations`, `alternate_screen`, `show_tooltips`. See [Configuration Reference](./config-reference.md) for the full list.

## Notes

- For the full config key table (all sections above condensed into one searchable list), see [Configuration Reference](./config-reference.md).

## Related

- [Config basics](./config-basics.md)
- [Configuration Reference](./config-reference.md)
- [Model Context Protocol](./mcp-config.md)

# Config basics

Codex reads configuration from multiple layered locations. User defaults live in `~/.codex/config.toml`; project overrides live in `.codex/config.toml` (loaded only for trusted projects).

## Signature / Usage

```toml
# ~/.codex/config.toml
model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

Open the file from the Codex IDE extension via the gear icon > **Codex Settings > Open config.toml**.

## Configuration precedence

Highest to lowest precedence:

1. CLI flags and `--config` overrides
2. Project config files: `.codex/config.toml`, root to cwd (closest wins; trusted projects only)
3. [Profile](./config-advanced.md) files selected with `--profile profile-name` (`~/.codex/profile-name.config.toml`)
4. User config: `~/.codex/config.toml`
5. System config (if present): `/etc/codex/config.toml` on Unix
6. Built-in defaults

On managed machines, `requirements.toml` can additionally constrain security-sensitive settings (for example disallowing `approval_policy = "never"`). See [Configuration Reference](./config-reference.md).

If a project is marked untrusted, Codex skips project-scoped `.codex/` layers (config, hooks, rules); user/system config and hooks/rules still load.

## Common configuration options

| Key | Example | Description |
|-----|---------|-------------|
| `model` | `model = "gpt-5.6"` | Default model. |
| `approval_policy` | `approval_policy = "on-request"` | `untrusted` \| `on-request` \| `never` \| granular table. |
| `sandbox_mode` | `sandbox_mode = "workspace-write"` | `read-only` \| `workspace-write` \| `danger-full-access`. |
| `default_permissions` | `default_permissions = ":workspace"` | Named permission profile (`:read-only`, `:workspace`, `:danger-full-access`, or a custom `[permissions.<name>]`). |
| `[windows] sandbox` | `sandbox = "elevated"` | Native Windows sandbox mode: `elevated` (recommended) or `unelevated`. |
| `web_search` | `web_search = "cached"` | `cached` (default) \| `indexed` \| `live` \| `disabled`. |
| `model_reasoning_effort` | `model_reasoning_effort = "high"` | Reasoning effort for supported models. |
| `personality` | `personality = "friendly"` | `friendly` \| `pragmatic` \| `none`; overridable with `/personality`. |
| `[tui.keymap.*]` | see below | Customize TUI shortcuts. |
| `[shell_environment_policy]` | see below | Control env vars forwarded to spawned commands. |
| `log_dir` | `log_dir = "/path/to/codex-logs"` | Log directory; also enables `codex-tui.log`. |

```toml
[tui.keymap.global]
open_transcript = "ctrl-t"

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"
```

`shell_environment_policy.ignore_default_excludes` defaults to `true` (skips filtering `KEY`/`SECRET`/`TOKEN` variable names); set `false` to enable that automatic filtering.

`shell_environment_policy.filters` (`map<string, "include" | "exclude">`) is the canonical, current form for pattern-based variable filtering; include entries create an allowlist and can't restore excluded values. The legacy `shell_environment_policy.exclude` / `include_only` arrays still work but are superseded by `filters` — don't combine the legacy arrays with `filters` in the same config layer.

## Feature flags

Use `[features]` to toggle optional/experimental capabilities.

| Key | Default | Maturity | Description |
|-----|---------|----------|-------------|
| `apps` | true | Stable | Enable app (connector) integrations |
| `goals` | true | Stable | Persisted goals and automatic continuation |
| `hooks` | true | Stable | Lifecycle hooks from `hooks.json` or inline `[hooks]` |
| `fast_mode` | true | Stable | Fast mode selection / `service_tier = "fast"` |
| `memories` | false | Experimental | Enable Memories |
| `multi_agent` | true | Stable | Subagent collaboration tools |
| `personality` | true | Stable | Personality selection controls |
| `remote_plugin` | true | Stable | Remote plugin catalog |
| `shell_snapshot` | true | Stable | Snapshot shell env to speed up repeated commands |
| `shell_tool` | true | Stable | Default `shell` tool |
| `unified_exec` | true (not Windows) | Stable | Unified PTY-backed exec tool |
| `web_search` / `web_search_cached` / `web_search_request` | — | Deprecated | Prefer top-level `web_search` |

Enable via `[features]` table (`feature_name = true`) or CLI: `codex --enable feature_name` (repeatable). Omit keys to keep defaults.

## Notes

- The CLI and IDE extension share the same configuration layers.
- For one-off `-c`/`--config` overrides and TOML quoting rules, see [Advanced Config](./config-advanced.md).

## Related

- [Advanced Configuration](./config-advanced.md)
- [Configuration Reference](./config-reference.md)
- [Sample Configuration](./config-sample.md)
- [Environment variables](./environment-variables.md)

# Configuration Reference

Complete searchable key reference for `config.toml` and `requirements.toml`. For conceptual guidance, start with [Config basics](./config-basics.md) and [Advanced Config](./config-advanced.md).

## Signature / Usage

```toml
# ~/.codex/config.toml
#:schema https://developers.openai.com/codex/config-schema.json
model = "gpt-5.5"
approval_policy = "on-request"
```

User-level config lives at `~/.codex/config.toml`; project overrides live in `.codex/config.toml` (trusted projects only). Install the "Even Better TOML" VS Code/Cursor extension and add the `#:schema` line above for autocompletion.

Project-scoped config cannot override machine-local provider/auth/notification/telemetry keys: `openai_base_url`, `chatgpt_base_url`, `apps_mcp_product_sku`, `model_provider`, `model_providers`, `notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, `otel`.

`experimental_instructions_file` is deprecated; use `model_instructions_file`.

## `config.toml` key groups

### Model & provider

| Key | Type | Description |
|-----|------|-------------|
| `model` | string | Model to use (e.g. `gpt-5.5`). |
| `review_model` | string | Optional `/review` model override. |
| `model_provider` | string | Provider id from `model_providers` (default `openai`). |
| `openai_base_url` | string | Base URL override for the built-in `openai` provider. |
| `model_context_window` | number | Context window tokens. |
| `model_auto_compact_token_limit` | number | Auto-compaction threshold. |
| `model_auto_compact_token_limit_scope` | `total` \| `body_after_prefix` | Scope of the auto-compaction threshold. |
| `model_catalog_json` | path | JSON model catalog loaded at startup; overridable per profile. |
| `oss_provider` | `lmstudio` \| `ollama` | Default local provider for `--oss`. |
| `model_providers.<id>` | table | Custom provider definition (`openai`/`ollama`/`lmstudio` reserved). |
| `model_providers.<id>.{name,base_url,env_key,env_key_instructions,experimental_bearer_token,requires_openai_auth,wire_api,query_params,http_headers,env_http_headers,request_max_retries,stream_max_retries,stream_idle_timeout_ms,supports_websockets,supports_standalone_web_search}` | mixed | Provider connection/auth/retry settings. |
| `model_providers.<id>.auth.{command,args,timeout_ms,refresh_interval_ms,cwd}` | mixed | Command-backed bearer token auth. |
| `model_providers.amazon-bedrock.aws.{profile,region}` | string | Built-in Amazon Bedrock provider tuning. |
| `model_reasoning_effort` | `minimal`\|`low`\|`medium`\|`high`\|`xhigh` | Reasoning effort (Responses API). |
| `plan_mode_reasoning_effort` | `none`\|`minimal`\|`low`\|`medium`\|`high`\|`xhigh` | Plan-mode-specific override. |
| `model_reasoning_summary` | `auto`\|`concise`\|`detailed`\|`none` | Reasoning summary detail. |
| `model_verbosity` | `low`\|`medium`\|`high` | GPT-5 Responses API verbosity override. |
| `model_supports_reasoning_summaries` | boolean | Force reasoning metadata on/off. |
| `service_tier` | string | Preferred service tier (e.g. `fast`). |

### Approvals & sandbox

| Key | Type | Description |
|-----|------|-------------|
| `approval_policy` | `untrusted`\|`on-request`\|`never`\|granular table | When Codex pauses for approval. `on-failure` deprecated. |
| `approval_policy.granular.{sandbox_approval,rules,mcp_elicitations,request_permissions,skill_approval}` | boolean | Per-category granular approval toggles. |
| `approvals_reviewer` | `user`\|`auto_review` | Who reviews eligible prompts. |
| `auto_review.policy` | string | Local Markdown auto-review policy (managed `guardian_policy_config` takes precedence). |
| `allow_login_shell` | boolean | Allow login-shell semantics for shell tools (default `true`). |
| `sandbox_mode` | `read-only`\|`workspace-write`\|`danger-full-access` | Filesystem/network sandbox policy. |
| `sandbox_workspace_write.{writable_roots,network_access,exclude_tmpdir_env_var,exclude_slash_tmp}` | mixed | Workspace-write mode tuning. |
| `windows.sandbox` | `unelevated`\|`elevated` | Native Windows sandbox mode. |
| `windows.sandbox_private_desktop` | boolean | Run sandboxed child on a private desktop. |
| `default_permissions` | string | Default named permission profile (`:read-only`, `:workspace`, `:danger-full-access`, or custom). Don't combine with `sandbox_mode`/`[sandbox_workspace_write]`. |
| `permissions.<name>.*` | mixed | Custom permission profile fields (`description`, `extends`, `workspace_roots`, `filesystem.*`, `network.*`) — see the Permissions guide. |

### MCP servers

| Key | Type | Description |
|-----|------|-------------|
| `mcp_servers.<id>.command` / `.args` / `.env` / `.env_vars` / `.cwd` | mixed | STDIO server launch config. |
| `mcp_servers.<id>.url` | string | Streamable HTTP server endpoint. |
| `mcp_servers.<id>.auth` | `oauth`\|`chatgpt` | Auth fallback after bearer tokens/headers. |
| `mcp_servers.<id>.bearer_token_env_var` / `.http_headers` / `.env_http_headers` | mixed | HTTP auth/headers. |
| `mcp_servers.<id>.enabled` / `.required` | boolean | Enable/disable; fail startup if required server can't init. |
| `mcp_servers.<id>.startup_timeout_sec` (`_ms` alias) / `.tool_timeout_sec` | number | Timeouts (defaults 10s / 60s). |
| `mcp_servers.<id>.enabled_tools` / `.disabled_tools` | array<string> | Allow/deny list. |
| `mcp_servers.<id>.default_tools_approval_mode` / `.tools.<tool>.approval_mode` | `auto`\|`prompt`\|`writes`\|`approve` | Approval mode defaults/overrides. |
| `mcp_servers.<id>.scopes` / `.oauth_resource` | mixed | OAuth scopes / RFC 8707 resource. |
| `mcp_servers.<id>.experimental_environment` | `local`\|`remote` | Run stdio via remote executor (experimental). |
| `mcp_oauth_credentials_store` | `auto`\|`file`\|`keyring` | Preferred MCP OAuth credential store. |
| `mcp_oauth_callback_port` / `mcp_oauth_callback_url` | mixed | OAuth callback listener overrides. |
| `plugins.<plugin>.mcp_servers.<server>.*` | mixed | Enable/tune MCP servers bundled by an installed plugin. |

See [Model Context Protocol](./mcp-config.md) for setup walkthroughs.

### Agents, skills, apps

| Key | Type | Description |
|-----|------|-------------|
| `agents.enabled` | boolean | Enable/disable multi-agent tools (default `true`). |
| `agents.max_concurrent_threads_per_session` (legacy alias `max_threads`) | number | Max concurrent spawned-agent threads. |
| `agents.default_subagent_model` / `.default_subagent_reasoning_effort` | string | Defaults for spawned agents. |
| `agents.interrupt_message` | boolean | Record message on interrupted agent turn (default `true`). |
| `agents.<name>.description` / `.config_file` | mixed | Custom subagent role declaration. |
| `skills.config[].{path,enabled}` | mixed | Per-skill enablement overrides. |
| `apps.<id>.enabled` / `.destructive_enabled` / `.open_world_enabled` | boolean | Per-app connector controls. |
| `apps._default.*` / `apps.<id>.approvals_reviewer` / `.default_tools_approval_mode` | mixed | Default vs per-app tool approval behavior. |
| `apps.<id>.tools.<tool>.enabled` / `.approval_mode` | mixed | Per-tool overrides. |
| `tool_suggest.discoverables` / `.disabled_tools` | array<table> | Tool suggestion allow/deny list (`{type, id}`). |

### Features

| Key | Type | Description |
|-----|------|-------------|
| `features.apps` / `.hooks` / `.unified_exec` / `.shell_snapshot` / `.multi_agent` / `.goals` / `.remote_plugin` / `.personality` / `.fast_mode` / `.shell_tool` / `.enable_request_compression` / `.skill_mcp_dependency_install` / `.prevent_idle_sleep` | boolean | Stable/experimental feature toggles (see [Config basics](./config-basics.md) table for defaults). |
| `features.code_mode.enabled` / `.excluded_tool_namespaces` / `.direct_only_tool_namespaces` | mixed | Code mode config (under development). |
| `features.rollout_budget.enabled` / `.limit_tokens` / `.reminder_interval_tokens` / `.sampling_token_weight` / `.prefill_token_weight` | mixed | Rollout budget tracking (under development). |
| `features.network_proxy` | boolean \| table | Sandboxed networking (experimental). |
| `features.network_proxy.{domains,unix_sockets,allow_local_binding,enable_socks5,enable_socks5_udp,allow_upstream_proxy,dangerously_allow_non_loopback_proxy,dangerously_allow_all_unix_sockets,proxy_url,socks_url}` | mixed | Sandboxed networking policy fields. |
| `features.memories` | boolean | Enable Memories (off by default). |
| `features.web_search` / `.web_search_cached` / `.web_search_request` | boolean | Deprecated; prefer top-level `web_search`. |
| `suppress_unstable_features_warning` | boolean | Suppress the under-development feature warning. |

### Hooks

| Key | Type | Description |
|-----|------|-------------|
| `hooks.<Event>` | array<table> | Matcher groups: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `Stop`. |
| `hooks.<Event>[].hooks[]` | table | Handler; command hooks supported (prompt/agent hooks parsed but skipped). |
| `hooks.<Event>[].hooks[].additionalContextLimit` | integer | Token threshold before oversized `additionalContext` is saved to disk (default `2500`; `0` = full context inline). |
| `hooks.<Event>[].hooks[].commandWindows` (alias `command_windows`) | string | Windows-only command override. |

### Memories

| Key | Type | Description |
|-----|------|-------------|
| `memories.generate_memories` / `.use_memories` | boolean | Toggle memory generation/injection (default `true`). |
| `memories.disable_on_external_context` (legacy `no_memories_if_mcp_or_web_search`) | boolean | Exclude threads using MCP/web-search from memory gen. |
| `memories.max_raw_memories_for_consolidation` / `.max_unused_days` / `.max_rollout_age_days` / `.max_rollouts_per_startup` / `.min_rollout_idle_hours` / `.min_rate_limit_remaining_percent` | number | Consolidation tuning. |
| `memories.extract_model` / `.consolidation_model` | string | Model overrides for memory jobs. |

### Shell / environment / execution

| Key | Type | Description |
|-----|------|-------------|
| `shell_environment_policy.inherit` | `all`\|`core`\|`none` | Baseline env inheritance for subprocesses. |
| `shell_environment_policy.ignore_default_excludes` | boolean | Keep `KEY`/`SECRET`/`TOKEN` vars before filters run (default `true`). |
| `shell_environment_policy.filters` | map<string, `include`\|`exclude`> | Canonical env-var pattern filters. |
| `shell_environment_policy.exclude` / `.include_only` | array<string> | Legacy filter arrays (don't combine with `filters`). |
| `shell_environment_policy.set` | map<string,string> | Explicit env values applied after exclusions. |
| `shell_environment_policy.experimental_use_profile` | boolean | Use the user shell profile when spawning subprocesses. |
| `background_terminal_max_timeout` | number | Max ms for empty `write_stdin` polls (default `300000`). |
| `tool_output_token_limit` | number | Token budget per stored tool output. |
| `tools.web_search` | boolean \| table | Web search tool config (`context_size`, `allowed_domains`, `location`). |
| `tools.view_image` | boolean | Enable `view_image` local-image tool. |
| `web_search` | `disabled`\|`cached`\|`indexed`\|`live` | Web search mode (default `cached`). |
| `experimental_use_unified_exec_tool` | boolean | Legacy; prefer `[features].unified_exec`. |

### Instructions & project docs

| Key | Type | Description |
|-----|------|-------------|
| `instructions` | string | Reserved; prefer `model_instructions_file` or `AGENTS.md`. |
| `developer_instructions` | string | Additional injected developer instructions. |
| `model_instructions_file` | path | Replaces built-in base instructions. |
| `compact_prompt` / `experimental_compact_prompt_file` | mixed | History-compaction prompt override (inline or file). |
| `project_root_markers` | array<string> | Project root marker filenames (default `[".git"]`). |
| `project_doc_max_bytes` | number | Bytes read from each `AGENTS.md`. |
| `project_doc_fallback_filenames` | array<string> | Fallback filenames when `AGENTS.md` is missing. |
| `projects.<path>.trust_level` | `trusted`\|`untrusted` | Per-project trust marking. |

### History, logging, telemetry

| Key | Type | Description |
|-----|------|-------------|
| `history.persistence` | `save-all`\|`none` | Save session transcripts to `history.jsonl`. |
| `history.max_bytes` | number | Cap history file size (drops oldest entries). |
| `log_dir` | path | Log directory (default `$CODEX_HOME/log`); also enables `codex-tui.log`. |
| `sqlite_home` | path | SQLite-backed runtime state directory. |
| `notify` | array<string> | External notification command (JSON payload argument). |
| `check_for_update_on_startup` | boolean | Check for updates on startup. |
| `feedback.enabled` | boolean | Enable `/feedback` submission (default `true`). |
| `analytics.enabled` | boolean | Enable/disable anonymous usage analytics. |
| `hide_agent_reasoning` / `show_raw_agent_reasoning` | boolean | Suppress / surface reasoning output. |
| `otel.environment` / `.exporter` / `.trace_exporter` / `.metrics_exporter` / `.log_user_prompt` | mixed | OpenTelemetry export config (`none`\|`otlp-http`\|`otlp-grpc`; metrics also `statsig`). |
| `otel.exporter.<id>.{endpoint,protocol,headers,tls.*}` / `otel.trace_exporter.<id>.{...}` | mixed | Per-exporter endpoint/TLS settings. |

### Auth & login

| Key | Type | Description |
|-----|------|-------------|
| `chatgpt_base_url` | string | Override ChatGPT login flow base URL. |
| `cli_auth_credentials_store` | `file`\|`keyring`\|`auto` | Where the CLI stores cached credentials. |
| `forced_login_method` | `chatgpt`\|`api` | Restrict to one auth method. |
| `forced_chatgpt_workspace_id` | string (uuid) | Limit ChatGPT login to one workspace. |

### UI (TUI / desktop)

| Key | Type | Description |
|-----|------|-------------|
| `tui.notifications` | boolean \| array<string> | Enable/filter TUI notifications. |
| `tui.notification_method` | `auto`\|`osc9`\|`bel` | Terminal notification mechanism. |
| `tui.notification_condition` | `unfocused`\|`always` | When notifications fire. |
| `tui.animations` / `.show_tooltips` | boolean | Welcome/status animations and tooltips. |
| `tui.alternate_screen` | `auto`\|`always`\|`never` | Alternate screen usage. |
| `tui.resume_cwd` | `current`\|`session` | Working directory on resume/fork. |
| `tui.vim_mode_default` / `.raw_output_mode` | boolean | Composer vim mode / raw scrollback mode. |
| `tui.status_line` / `.terminal_title` | array<string> \| null | Footer / title item ids. |
| `tui.theme` | string | Syntax-highlighting theme (kebab-case). |
| `tui.keymap.<context>.<action>` | string \| array<string> | Keybinding; contexts: `global`, `chat`, `composer`, `editor`, `vim_normal`, `vim_operator`, `vim_text_object`, `pager`, `list`, `approval`. `[]` unbinds. |
| `file_opener` | `vscode`\|`vscode-insiders`\|`windsurf`\|`cursor`\|`none` | Citation link scheme. |
| `disable_paste_burst` | boolean | Disable burst-paste detection. |
| `windows_wsl_setup_acknowledged` | boolean | Windows onboarding acknowledgement. |
| `desktop.custom_file_handlers.<id>.*` | mixed | ChatGPT desktop app custom "Open in" handlers (user-level only). |
| `notice.*` | mixed | In-product notice acknowledgement flags (mostly auto-managed). |
| `computer_use.windows.always_allowed_app_ids` | array<string> | Windows apps Computer Use can open without prompting. |

## `requirements.toml`

Admin-enforced configuration that constrains security-sensitive settings users can't override. Precedence: cloud-fetched requirements can also apply for ChatGPT Business/Enterprise. Omitted keys remain unconstrained; some keys enforce an exact value (not just an allowlist).

| Key | Type | Description |
|-----|------|-------------|
| `sqlite_home` / `log_dir` / `model_catalog_json` / `check_for_update_on_startup` / `allow_login_shell` | mixed | Enforce the corresponding `config.toml` value. |
| `feedback.enabled` | boolean | Enforce feedback availability. |
| `allowed_approval_policies` / `allowed_approvals_reviewers` | array<string> | Allowed values for `approval_policy` / `approvals_reviewer`. |
| `guardian_policy_config` | string | Managed auto-review policy (overrides local `[auto_review].policy`). |
| `allowed_permission_profiles.<name>` | boolean | Allow/deny a permission profile (omitted/`false` = denied). |
| `default_permissions` | string | Managed default permission profile (must be allowed). |
| `enforce_residency` | string | Require a data residency (currently `us`). |
| `models.new_thread.{model,model_reasoning_effort,service_tier}` | mixed | Managed defaults for new threads (explicit user choice takes precedence for model/effort). |
| `permissions.<name>` | table | Admin-defined permission profile (same schema as `config.toml`). |
| `allowed_sandbox_modes` | array<string> | Allowed `sandbox_mode` values. |
| `windows.allowed_sandbox_implementations` / `.sandbox_private_desktop` | mixed | Windows native sandbox constraints. |
| `remote_sandbox_config[].{hostname_patterns,allowed_sandbox_modes}` | mixed | Host-specific sandbox mode overrides. |
| `allowed_web_search_modes` | array<string> | Allowed `web_search` values (`disabled` always allowed). |
| `allow_managed_hooks_only` | boolean | Skip user/project/session/plugin hooks; keep managed hooks only. |
| `allow_appshots` / `allow_remote_control` | boolean | Disable Appshots / device remote control. |
| `features.<name>` | boolean | Pin a runtime/app feature (`apps`, `in_app_updates`, `in_app_browser`, `browser_use*`, `fast_mode`, `guardian_approval`, `memories`, `multi_agent`, `plugins`, `remote_plugin`, `computer_use`, `workspace_dependencies`, `plugin_sharing`). |
| `computer_use.allow_locked_computer_use` | boolean | Allow Computer Use after a managed macOS device locks. |
| `experimental_network.*` | mixed | Sandboxed networking requirements, independent of `features.network_proxy`: `enabled`, `http_port`, `socks_port`, `allow_upstream_proxy`, `dangerously_allow_non_loopback_proxy`, `dangerously_allow_all_unix_sockets`, `domains`, `allowed_domains`, `denied_domains`, `managed_allowed_domains_only`, `unix_sockets`, `allow_local_binding`. |
| `hooks.managed_dir` / `.windows_managed_dir` / `.{Event}` | mixed | Admin-enforced managed hooks (absolute directory required). |
| `permissions.filesystem.deny_read` | array<string> | Admin-enforced filesystem read denials (paths/globs). |
| `mcp_servers.<id>.identity.{command,url}` | mixed | MCP server allowlist by exact command/URL or matcher (`exact`\|`prefix`\|`regex`). |
| `plugins.<plugin>.mcp_servers.<server>.identity.*` | mixed | Same identity allowlist scoped to a plugin's bundled servers. |
| `marketplaces.restrict_to_allowed_sources` / `.allowed_sources.<name>.*` | mixed | Restrict plugin marketplace sources (`git`, `host_pattern`, `local`). |
| `apps.<id>.enabled` / `.tools.<tool>.approval_mode` | mixed | Managed app/tool constraints. |
| `rules.prefix_rules[].{pattern,decision,justification}` | mixed | Admin-enforced command prefix rules (`decision`: `prompt`\|`forbidden` only). |

## Notes

- Both tables above are condensed from the official page; consult the source for exact wording of edge cases before relying on precedence details in automated tooling.
- `requirements.toml` details, file locations, and precedence with cloud-fetched requirements are documented under Admin-enforced requirements (out of this skill's `config` scope — see enterprise/managed-configuration docs).

## Related

- [Config basics](./config-basics.md)
- [Advanced Configuration](./config-advanced.md)
- [Sample Configuration](./config-sample.md)
- [Model Context Protocol](./mcp-config.md)

# Sample Configuration

A complete example `config.toml` covering most keys Codex reads, with default behaviors and short notes. Copy only the sections you need into `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`).

## Signature / Usage

```toml
################################################################################
# Core Model Selection
################################################################################
model = "gpt-5.6"
# personality = "pragmatic"            # none | friendly | pragmatic
# review_model = "gpt-5.6"
model_provider = "openai"
# oss_provider = "ollama"
# service_tier = "fast"
# model_context_window = 128000
# model_auto_compact_token_limit = 64000
# model_auto_compact_token_limit_scope = "total" # total | body_after_prefix
# tool_output_token_limit = 12000
# model_catalog_json = "/absolute/path/to/models.json"
# background_terminal_max_timeout = 300000
# log_dir = "/absolute/path/to/codex-logs"
# sqlite_home = "/absolute/path/to/codex-state"

################################################################################
# Reasoning & Verbosity (Responses API capable models)
################################################################################
# model_reasoning_effort = "medium"        # minimal | low | medium | high | xhigh
# plan_mode_reasoning_effort = "high"
# model_reasoning_summary = "auto"         # auto | concise | detailed | none
# model_verbosity = "medium"               # low | medium | high
# model_supports_reasoning_summaries = true

################################################################################
# Instruction Overrides
################################################################################
# developer_instructions = ""
# compact_prompt = ""
# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"

################################################################################
# Notifications
################################################################################
# notify = ["notify-send", "Codex"]

################################################################################
# Approval & Sandbox
################################################################################
approval_policy = "on-request"       # untrusted | on-request | never | { granular = {...} }
# approvals_reviewer = "user"        # user | auto_review
# approval_policy = { granular = {
#   sandbox_approval = true, rules = true, mcp_elicitations = true,
#   request_permissions = false, skill_approval = false
# } }
allow_login_shell = true             # default true
sandbox_mode = "read-only"           # read-only | workspace-write | danger-full-access
# default_permissions = ":workspace" # :read-only | :workspace | :danger-full-access | custom name

################################################################################
# Authentication & Login
################################################################################
cli_auth_credentials_store = "file"           # file | keyring | auto
chatgpt_base_url = "https://chatgpt.com/backend-api/"
# openai_base_url = "https://us.api.openai.com/v1"
# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"
# forced_login_method = "chatgpt"               # chatgpt | api
mcp_oauth_credentials_store = "auto"          # auto | file | keyring
# mcp_oauth_callback_port = 4321
# mcp_oauth_callback_url = "https://devbox.example.internal/callback"

################################################################################
# Project Documentation Controls
################################################################################
project_doc_max_bytes = 32768
project_doc_fallback_filenames = []
# project_root_markers = [".git"]

################################################################################
# History & File Opener
################################################################################
file_opener = "vscode"  # vscode | vscode-insiders | windsurf | cursor | none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
disable_paste_burst = false
windows_wsl_setup_acknowledged = false
check_for_update_on_startup = true

################################################################################
# Web Search
################################################################################
web_search = "cached"  # disabled | cached | indexed | live
# suppress_unstable_features_warning = true

################################################################################
# Agents (multi-agent roles and limits)
################################################################################
[agents]
# enabled = true
# max_concurrent_threads_per_session = 6
# default_subagent_model = "gpt-5.6-terra"
# default_subagent_reasoning_effort = "high"
# interrupt_message = true
# [agents.reviewer]
# description = "Find correctness, security, and test risks in code."
# config_file = "./agents/reviewer.toml"

################################################################################
# Skills (per-skill overrides)
################################################################################
# [[skills.config]]
# path = "/path/to/skill"       # folder containing SKILL.md
# enabled = false

################################################################################
# Sandbox settings (workspace-write only)
################################################################################
[sandbox_workspace_write]
writable_roots = []
network_access = false
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

################################################################################
# Shell Environment Policy for spawned processes
################################################################################
[shell_environment_policy]
inherit = "all"                  # all | core | none
ignore_default_excludes = false
set = {}
experimental_use_profile = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

################################################################################
# History
################################################################################
[history]
persistence = "save-all"   # save-all | none
# max_bytes = 5242880

################################################################################
# UI, Notifications, and Misc
################################################################################
[tui]
notifications = false
# notification_method = "auto"      # auto | osc9 | bel
# notification_condition = "unfocused"
animations = true
show_tooltips = true
# alternate_screen = "auto"
# resume_cwd = "session"
# status_line = ["model", "context-remaining", "git-branch"]
# terminal_title = ["spinner", "project"]
# theme = "catppuccin-mocha"

[analytics]
enabled = true

[feedback]
enabled = true

[notice]
# hide_full_access_warning = true
# model_migrations = { "gpt-5.4" = "gpt-5.6-terra" }

################################################################################
# Centralized Feature Flags
################################################################################
[features]
# shell_tool = true
# apps = true
# hooks = false
# unified_exec = true
# multi_agent = true
# fast_mode = true
# network_proxy = false

################################################################################
# Memories
################################################################################
# [memories]
# generate_memories = true
# use_memories = true
# disable_on_external_context = false

################################################################################
# Lifecycle hooks (inline; or use a sibling hooks.json)
################################################################################
# [hooks]
# [[hooks.PreToolUse]]
# matcher = "^Bash$"
# [[hooks.PreToolUse.hooks]]
# type = "command"
# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'
# timeout = 30

################################################################################
# MCP servers
################################################################################
[mcp_servers]
# --- STDIO transport ---
# [mcp_servers.docs]
# command = "docs-server"
# args = ["--port", "4000"]
# env = { "API_KEY" = "value" }
# env_vars = ["ANOTHER_SECRET"]
# startup_timeout_sec = 10.0
# tool_timeout_sec = 60.0
# enabled_tools = ["search", "summarize"]
# disabled_tools = ["slow-tool"]

# --- Streamable HTTP transport ---
# [mcp_servers.github]
# url = "https://github-mcp.example.com/mcp"
# bearer_token_env_var = "GITHUB_TOKEN"
# http_headers = { "X-Example" = "value" }
# scopes = ["repo"]

################################################################################
# Model Providers
################################################################################
[model_providers]
# [model_providers.openaidr]
# name = "OpenAI Data Residency"
# base_url = "https://us.api.openai.com/v1"
# wire_api = "responses"

# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# wire_api = "responses"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"

################################################################################
# Apps / Connectors
################################################################################
[apps]
# [apps._default]
# enabled = true
# default_tools_approval_mode = "auto"   # auto | prompt | writes | approve

################################################################################
# Config Profiles (separate files under $CODEX_HOME)
################################################################################
# $CODEX_HOME/ci.config.toml:
# model = "gpt-5.6-terra"
# approval_policy = "on-request"
# sandbox_mode = "read-only"

################################################################################
# Projects (trust levels)
################################################################################
[projects]
# [projects."/absolute/path/to/project"]
# trust_level = "trusted"   # or "untrusted"

################################################################################
# Tools
################################################################################
[tools]
# view_image = true

################################################################################
# OpenTelemetry (OTEL) - disabled by default
################################################################################
[otel]
log_user_prompt = false
environment = "dev"
exporter = "none"           # none | otlp-http | otlp-grpc
trace_exporter = "none"
metrics_exporter = "statsig" # none | statsig | otlp-http | otlp-grpc

################################################################################
# Windows
################################################################################
[windows]
sandbox = "unelevated"   # unelevated | elevated
```

## Notes

- Root keys must appear before tables in TOML.
- Optional keys that default to "unset" are shown commented out with notes.
- MCP servers, profile files, and model providers in the sample are illustrative — remove or edit for your setup.
- For every key's type/description, see [Configuration Reference](./config-reference.md).

## Related

- [Config basics](./config-basics.md)
- [Advanced Configuration](./config-advanced.md)
- [Configuration Reference](./config-reference.md)

# Environment variables

Environment variables Codex reads, complementing `config.toml` for shell-scoped overrides and automation needs.

## Signature / Usage

```shell
export CODEX_HOME="$HOME/.codex"
export CODEX_API_KEY="sk-..."
codex exec "summarize this repo"
```

## Options / Props

| Name | Description |
|------|-------------|
| `CODEX_HOME` | Root directory for configuration, auth, logs, sessions. Default `~/.codex`; the directory must already exist if overridden. |
| `CODEX_SQLITE_HOME` | Where SQLite-backed state resides separately from `CODEX_HOME`. The config file option (`sqlite_home`) takes precedence. |
| `CODEX_NON_INTERACTIVE` | Set to `1`, `true`, or `yes` to skip installer prompts and use default responses (scripted install). |
| `CODEX_INSTALL_DIR` | Changes where the executable installs; platform-specific defaults on macOS, Linux, Windows. |
| `CODEX_API_KEY` | API key for single non-interactive runs via `codex exec`. |
| `CODEX_ACCESS_TOKEN` | ChatGPT or Codex access token for trusted automation scenarios. |
| `CODEX_CA_CERTIFICATE` | PEM certificate bundle for TLS; takes precedence over `SSL_CERT_FILE`. |
| `SSL_CERT_FILE` | PEM certificate bundle for TLS environments. |
| `RUST_LOG` | Logging verbosity: `error`, `warn`, `info`, `debug`, `trace`; supports per-component filtering. |

## Notes

- `CODEX_HOME` is the base for most other config/state locations documented in [Advanced Configuration](./config-advanced.md).

## Related

- [Config basics](./config-basics.md)
- [Advanced Configuration](./config-advanced.md)

# Model Context Protocol (MCP server configuration)

Connect Codex to MCP servers to give it access to third-party documentation and developer tools (browser, Figma, GitHub, etc). Configuration is stored in `config.toml` and shared across the ChatGPT desktop app, Codex CLI, and IDE extension.

## Signature / Usage

```bash
# Add a STDIO MCP server via CLI
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

# Example: Context7 docs server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# List / manage
codex mcp list
codex mcp login <server-name>   # OAuth login for a server
```

```toml
# ~/.codex/config.toml or .codex/config.toml (project-scoped, trusted only)
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
```

Each server is a `[mcp_servers.<server-name>]` table. In the TUI, `/mcp` lists active servers.

## Supported server types

- **STDIO servers**: run as a local process, support environment variables.
- **Streamable HTTP servers**: accessed at a URL; support bearer token auth, OAuth, and ChatGPT session auth for trusted first-party servers.
- **Server instructions**: Codex reads the MCP `instructions` field from server initialization and uses it as server-wide guidance. Server authors should keep the first 512 characters self-contained.

## Options / Props

### STDIO servers

| Name | Type | Description |
|------|------|-------------|
| `command` | string (required) | Command that starts the server. |
| `args` | array<string> | Arguments passed to the server. |
| `env` | map<string,string> | Environment variables set for the server. |
| `env_vars` | array<string \| {name, source}> | Env vars to allow/forward. String entries and `source = "local"` read Codex's local environment; `source = "remote"` reads a remote executor environment (requires remote MCP stdio). |
| `cwd` | string | Working directory to start the server from. |
| `experimental_environment` | `remote` | Start the stdio server through a remote executor environment when available. |

```toml
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]
```

### Streamable HTTP servers

| Name | Type | Description |
|------|------|-------------|
| `url` | string (required) | Server address. |
| `auth` | `oauth` \| `chatgpt` | Auth to try after configured bearer tokens/headers. `oauth` (default) uses stored MCP OAuth credentials. `chatgpt` uses the current ChatGPT session for the trusted first-party ChatGPT origin, falling back to stored OAuth. |
| `bearer_token_env_var` | string | Env var name for a bearer token sent in `Authorization`. |
| `http_headers` | map<string,string> | Static header values. |
| `env_http_headers` | map<string,string> | Header values pulled from environment variables. |

If no credential source resolves, Codex can connect without authentication. Run `codex mcp login <server-name>` to start MCP OAuth login separately.

### Common to both transports

| Name | Type | Description |
|------|------|-------------|
| `startup_timeout_sec` | number | Server start timeout. Default `10`. |
| `tool_timeout_sec` | number | Tool run timeout. Default `60`. |
| `enabled` | boolean | Set `false` to disable a server without deleting it. |
| `required` | boolean | Set `true` to fail startup if this enabled server can't initialize. |
| `enabled_tools` | array<string> | Tool allow list. |
| `disabled_tools` | array<string> | Tool deny list, applied after `enabled_tools`. |
| `default_tools_approval_mode` | `auto` \| `prompt` \| `writes` \| `approve` | Default approval behavior for this server's tools. `writes` prompts only for tools not marked read-only. |
| `tools.<tool>.approval_mode` | `auto` \| `prompt` \| `writes` \| `approve` | Per-tool approval override. |

Top-level OAuth callback overrides:

```toml
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
```

`mcp_oauth_callback_port` fixes the local callback port (ephemeral if unset). `mcp_oauth_callback_url` sets a base callback URL for the OAuth `redirect_uri`; Codex appends a server-specific callback ID, so register the full derived URI with the OAuth provider, not just the base host/path. If the MCP server advertises `scopes_supported`, Codex prefers those scopes over `config.toml`-configured ones.

## Config examples

```toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
```

```toml
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
```

### Plugin-provided MCP servers

Installed plugins can bundle MCP servers in their plugin manifest; the plugin launches them, so user config cannot set transport (`command`/`url`). User config still controls on/off state and tool policy under `plugins.<plugin>.mcp_servers.<server>`.

```toml
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"
```

## Configure without editing TOML directly

- **ChatGPT desktop app**: Settings > MCP servers > Add server (STDIO or Streamable HTTP) > Restart. `/mcp` in the composer lists connected servers.
- **Codex CLI**: `codex mcp add`, `codex mcp list`, `codex mcp login <server-name>`, `codex mcp --help`. In the TUI, `/mcp` lists active servers.
- **IDE extension**: gear menu > MCP servers > Add server > Restart extension.
- **ChatGPT web**: doesn't read local Codex config; use **Plugins** in ChatGPT Work to install plugin-bundled connectors/remote MCP tools instead.

## Examples of useful MCP servers

- OpenAI Docs MCP — search/read OpenAI developer docs.
- Context7 — up-to-date developer documentation.
- Figma (Local / Remote) — access Figma designs.
- Playwright — control/inspect a browser.
- Chrome Developer Tools — control/inspect Chrome.
- Sentry — access Sentry logs.
- GitHub — manage issues/PRs beyond `git`.

## Notes

- This page documents OpenAI Codex's MCP **client** configuration (Codex connecting out to MCP servers), distinct from OpenAI API / Agents SDK MCP usage (`openai-agents` skill), which covers building/consuming MCP from the Agents SDK side.
- For the full key list (types, defaults) alongside every other `config.toml` key, see [Configuration Reference](./config-reference.md).

## Related

- [Config basics](./config-basics.md)
- [Advanced Configuration](./config-advanced.md)
- [Configuration Reference](./config-reference.md)

# config

| Name | Description | Path |
|------|-------------|------|
| Config basics | Config file locations, precedence, common options, feature flags | [config-basics.md](./config-basics.md) |
| Advanced Configuration | Profiles, CLI overrides, hooks, custom providers, sandbox/approvals, shell env policy, OTel, notifications, history, desktop file handlers | [config-advanced.md](./config-advanced.md) |
| Configuration Reference | Complete `config.toml` and `requirements.toml` key/type/description tables | [config-reference.md](./config-reference.md) |
| Sample Configuration | Full example `config.toml` covering most keys | [config-sample.md](./config-sample.md) |
| Environment variables | `CODEX_HOME`, `CODEX_API_KEY`, `RUST_LOG`, and other env vars | [environment-variables.md](./environment-variables.md) |
| Model Context Protocol (MCP config) | `[mcp_servers.<name>]` STDIO/HTTP server configuration, OAuth, approval modes | [mcp-config.md](./mcp-config.md) |

# Cloud environments

Control what Codex installs and runs during cloud chats: dependencies, tools (linters, formatters), and environment variables. Configured per repository in [Codex settings](https://chatgpt.com/codex/settings/environments).

## Signature / Usage

```bash
# Manual setup script example (runs before the agent phase)
pip install pyright
poetry install --with test
pnpm install
```

## How Codex cloud chats run

1. Codex creates a container and checks out the repo at the selected branch/commit.
2. Codex runs the setup script, plus an optional maintenance script when a cached container is resumed.
3. Codex applies internet access settings: setup scripts run with internet access; agent internet access is off by default (configurable).
4. The agent runs terminal commands in a loop, editing code and validating work. If the repo has `AGENTS.md`, the agent uses it to find project-specific lint/test commands.
5. The agent shows its answer and a diff; you can open a PR or ask follow-up questions.

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| Default image | `universal` | Pre-installed common languages/packages/tools; pin runtime versions via **Set package versions**. See [openai/codex-universal](https://github.com/openai/codex-universal) for the reference Dockerfile. |
| Environment variables | key/value | Set for the full chat duration (setup scripts + agent phase). |
| Secrets | key/value | Extra encryption layer; available only to setup scripts, removed before the agent phase starts. |
| Automatic setup | — | For `npm`/`yarn`/`pnpm`/`pip`/`pipenv`/`poetry` projects, Codex can auto-install dependencies. |
| Setup script | bash | Custom install/build commands; runs in a separate Bash session from the agent, so `export` doesn't persist (use `~/.bashrc` or environment settings to persist vars). |
| Maintenance script | bash | Optional; runs when a cached container is resumed, to refresh dependencies against a newer commit. |

## Container caching

Codex caches container state for up to 12 hours. When cached, Codex clones the repo, checks out the default branch, runs the setup script, and caches the result. When a cached container is resumed, Codex checks out the chat's branch and runs the maintenance script. Codex invalidates the cache automatically on setup/maintenance script, environment variable, or secret changes; use **Reset cache** on the environment page otherwise. For Business/Enterprise, caches are shared workspace-wide, so invalidation affects all users of the environment.

## Notes

- Internet access is available during the setup script phase; during the agent phase it's off by default (see agent internet access settings, `cloud-internet-access.md`).
- Environments run behind an HTTP/HTTPS network proxy for security and abuse prevention; all outbound traffic passes through it.
- This page covers cloud environment configuration in depth. For the cloud product overview (getting started, when to use cloud), see `cloud.md` in the getting-started category.

## Related

- [modes.md](./modes.md)
- [local-environment.md](./local-environment.md)
- [Codex cloud](../getting-started/cloud.md)
- [Agent internet access](../getting-started/cloud-internet-access.md)

# Worktrees

Git worktrees in Codex in the ChatGPT desktop app let Codex run multiple independent chats in the same project without interfering with each other, and move a chat between Local and Worktree via Handoff.

## Signature / Usage

```text
# .worktreeinclude — copy ignored local files into managed worktrees
.env
.env.local
config/secrets.json
```

## Options / Props

| Name | Description |
|------|-------------|
| Local checkout | The repository you created; also called Local in the app. |
| Worktree | A [Git worktree](https://git-scm.com/docs/git-worktree) created from the local checkout in the app; shares `.git` metadata with the local checkout. |
| Handoff | Moves a chat (and its code) between Local and Worktree; Codex handles the required Git operations. |
| `.worktreeinclude` | Repo-root file listing `.gitignore`-style patterns of ignored files (e.g. `.env`) to copy into a new managed worktree. Tracked files must not be listed. |

## Getting started

1. Select **Worktree** under the composer in the new chat view (optionally choose a local environment for setup scripts).
2. Choose the starting Git branch (`main`/`master`, a feature branch, or the current branch with unstaged changes).
3. Submit the prompt; Codex creates a worktree in a detached HEAD state.
4. Keep working on the worktree, or hand the chat off to the local checkout.

## Notes

- Worktrees require the project to be a Git repository; scheduled tasks on non-version-controlled projects run directly in the project directory.
- Git only allows a branch to be checked out in one place at a time — a branch created on a worktree (**Create branch here**) can't also be checked out in the local checkout or another worktree until it's freed via Handoff.
- Codex-managed worktrees live under `$CODEX_HOME/worktrees` (configurable at **Settings > Worktrees > Worktree root**); Codex keeps the most recent 15 by default and deletes older ones unless a pinned/in-progress chat or a permanent worktree references them (a snapshot is saved before deletion and can be restored).
- Permanent worktrees (created from a project's three-dot menu) are not automatically deleted and can host multiple chats.

## Related

- [modes.md](./modes.md)
- [local-environment.md](./local-environment.md)

# Local environments

Configure setup steps for worktrees and common actions for a project, in Codex in the ChatGPT desktop app. Stored in the `.codex` folder at the project root, so the configuration can be checked into Git and shared.

## Signature / Usage

```bash
# Setup script example (runs automatically when Codex creates a new worktree)
npm install
npm run build
```

```bash
# Action script example (e.g. a "Run" action for a Node.js project)
npm start
```

## Options / Props

| Name | Description |
|------|-------------|
| Setup script | Runs automatically when Codex creates a new worktree at the start of a new chat; installs dependencies or runs a build. Platform-specific overrides available (macOS/Windows/Linux). |
| Actions | Common tasks (dev server, test suite) defined per project; appear in the ChatGPT desktop app top bar and run in the [integrated terminal](https://learn.chatgpt.com/docs/integrated-terminal). Platform-specific scripts and an icon can be set per action. |
| Built-in Git tools | Diff pane with inline comments, stage/revert chunks or files, commit, push, and create a pull request without leaving the app. |

## Notes

- Local environments are available only in Codex in the ChatGPT desktop app (select **Codex** before configuring or using one).
- Configured through ChatGPT desktop app settings; if a repository contains more than one project, open the project directory that has the shared `.codex` folder.
- To isolate concurrent changes from the local checkout, start the task in a worktree (see `git-worktrees.md`).

## Related

- [git-worktrees.md](./git-worktrees.md)
- [modes.md](./modes.md)

# Codex environments (chat run modes)

Where a Codex chat runs and how its files stay isolated, chosen in the ChatGPT desktop app when starting a chat: Local, Worktree, or Cloud.

## Signature / Usage

In the ChatGPT desktop app, open the ChatGPT dropdown and select **Codex**. When starting a chat, choose where it runs.

## Options / Props

| Name | Description |
|------|-------------|
| Local | Work directly in the current project directory. |
| Worktree | Isolate changes in a Git worktree; runs on the local machine like Local. |
| Cloud | Run remotely in a configured cloud environment. |

## Notes

- Local and Worktree both run on the local computer; only Cloud runs remotely.
- This page is the desktop-app run-mode selector, distinct from `cloud-environment.md` (cloud environment configuration: dependencies, secrets, caching) and `getting-started/cloud.md` (Codex cloud product overview).

## Related

- [git-worktrees.md](./git-worktrees.md)
- [cloud-environment.md](./cloud-environment.md)
- [Codex cloud](../getting-started/cloud.md)
- [Prompting](../agent-configuration/prompting.md)

# Environments

| Name | Description | Path |
|------|-------------|------|
| Cloud environments | Control what Codex installs and runs during cloud chats: dependencies, tools (linters, formatters), and environment variables. Configured per repository in Codex settings. | [cloud-environment.md](./cloud-environment.md) |
| Worktrees | Git worktrees in Codex in the ChatGPT desktop app let Codex run multiple independent chats in the same project without interfering with each other, and move a chat between Local and Worktree via Handoff. | [git-worktrees.md](./git-worktrees.md) |
| Local environments | Configure setup steps for worktrees and common actions for a project, in Codex in the ChatGPT desktop app. Stored in the `.codex` folder at the project root, so the configuration can be checked into Git and shared. | [local-environment.md](./local-environment.md) |
| Codex environments (chat run modes) | Where a Codex chat runs and how its files stay isolated, chosen in the ChatGPT desktop app when starting a chat: Local, Worktree, or Cloud. | [modes.md](./modes.md) |

# Extend

| Name | Description | Path |
|------|-------------|------|
| Record & Replay | Demonstrate a workflow on your Mac and turn it into a reusable skill, without writing a prompt from scratch. | [record-and-replay.md](./record-and-replay.md) |

# Record & Replay

Demonstrate a workflow on your Mac and turn it into a reusable skill, without writing a prompt from scratch.

## Signature / Usage

```text
1. In the ChatGPT desktop app, select ChatGPT and turn on Work in the switcher, or select Codex. Then open Plugins.
2. Open the + menu.
3. Select "Record a skill".
4. Review the suggested prompt, add any helpful context, and submit it.
5. When the chat asks for permission to record your actions, approve the request once you are ready to demonstrate the workflow.
6. Perform the workflow on your Mac.
7. When you are done, stop recording from the menu bar or overlay, or tell the chat that you are done.
```

Recording continues until you stop it; ChatGPT or Codex observes the actions and window content needed to learn the workflow. After you stop, it inspects the captured workflow and drafts a skill explaining when to use it, what inputs it needs, what steps to follow, and how to verify the result. You can ask for further refinements before using it.

To replay, start a new ChatGPT or Codex chat and ask it to use the generated skill, supplying the values that differ this time (file to upload, issue to create, date range, etc.). The product completes the workflow with the tools available in the current environment: Computer Use, browser actions, and installed plugins.

## Requirements

- Available on macOS only.
- Initial availability excludes the European Economic Area, the United Kingdom, and Switzerland.
- Computer Use must be available and enabled.
- If an organization manages Codex with `requirements.toml`, the `[features].computer_use` requirement controls Record & Replay too — disabling `computer_use` also disables Record & Replay.

## Tips for better recordings

- Keep the demonstration short and complete.
- State your goal and any specific inputs that might vary between skill uses before you start recording.
- Use realistic inputs, but avoid secrets and sensitive data.
- Refine the skill after recording to call out hidden preferences that matter, such as naming conventions, field defaults, or decision points.
- Stop recording when the workflow is complete instead of continuing into unrelated cleanup.

## When to build a plugin instead

Record & Replay is a fast way to create a skill from a demonstrated workflow. To distribute a stable package across a team, bundle multiple skills, include connectors, add MCP servers, or manage install metadata, package the workflow as its own plugin instead (see [Build plugins](https://developers.openai.com/plugins/build/plugins), outside this skill's scope).

## Notes

- Pick a workflow you already know how to complete; Record & Replay works best when the steps are stable and the success criteria are clear.
- The "skill" this feature produces is a Codex/ChatGPT skill document (instructions + supporting resources), distinct from this repository's Claude Code Skills (`SKILL.md`) and from the OpenAI Apps SDK's plugin "skills" concept — see `references/administration/skill-controls.md` for the ChatGPT workspace / filesystem / plugin skill distribution models.
- For MCP server configuration referenced above (used by replayed workflows and plugin-based alternatives), see [MCP server configuration](../config/mcp-config.md).

## Related

- [Skill controls](../administration/skill-controls.md)
- [Model Context Protocol (MCP config)](../config/mcp-config.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント.

# Best practices

Getting started with Codex and proven practices for better results, across the CLI, IDE extension, and ChatGPT desktop app — prompting, planning, validation, MCP, skills, and scheduled tasks.

## Signature / Usage

A good default prompt includes four things:

- **Goal** — what are you trying to change or build?
- **Context** — which files, folders, docs, examples, or errors matter (you can `@` mention files)?
- **Constraints** — what standards, architecture, safety requirements, or conventions should Codex follow?
- **Done when** — what should be true when the task is complete (tests passing, behavior changed, bug no longer reproducing)?

## Options / Props

| Reasoning level | When to use |
|------|-------------|
| Low | Faster, well-scoped tasks |
| Medium / High | More complex changes or debugging |
| Extra High | Long, agentic, reasoning-heavy tasks |

## Notes

- Codex is useful even with an imperfect prompt, but clear prompting makes results more reliable, especially in large or higher-stakes codebases. Speech dictation in the desktop app is one way to provide context faster.
- **Plan first for difficult tasks**: for complex or ambiguous work, ask Codex to plan before coding. Plan mode (`/plan` or Shift+Tab) lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation; alternatives are asking Codex to interview you first, or using a `PLANS.md` template for multi-step work.
- **Testing and review**: ask Codex to create/modify tests, run the test suite, run lint/type-checking, and validate behavior — don't just generate code. The `/review` slash command runs a GitHub-style review against a base branch, uncommitted changes, or a specific commit.
- **MCP**: connect Codex to external tools/systems when needed context lives outside the repo or changes frequently, instead of copy-pasting live information into prompts; start with one or two tools that remove a real manual step rather than connecting everything at once.
- **Skills**: once a workflow becomes repeatable, package it as a `SKILL.md` file, scoped to one job with clear inputs/outputs; start with 2-3 concrete use cases and iterate rather than covering every edge case up front.
- **Scheduled tasks**: automate stable, recurring workflows (e.g. commit summaries, release notes) through the desktop app's Scheduled page once a skill is proven; skills define the method, scheduled tasks define the cadence.
- Durable per-repo/per-user guidance (`AGENTS.md`, `config.toml` layering, MCP server setup) is documented in detail on separate reference pages outside this category (agent-configuration / config scopes).

## Related

- [cli.md](./cli.md)
- [ide.md](./ide.md)
- [cloud.md](./cloud.md)
- [models.md](./models.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# CLI customization

Terminal-specific options for how interactive Codex CLI sessions look and how you enter commands and prompts: syntax-highlight themes, shell completions, and an external prompt editor.

## Signature / Usage

```bash
# Generate a completion script (bash | zsh | fish | powershell)
codex completion zsh
eval "$(codex completion zsh)"
```

```text
/theme
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `/theme` | slash command | Opens the theme picker for the TUI's Markdown/diff syntax highlighting; saves the selection to `tui.theme` in `$CODEX_HOME/config.toml`. |
| custom `.tmTheme` | file | Place under `$CODEX_HOME/themes` to make it selectable from the theme picker. |
| `codex completion <shell>` | CLI | Prints a completion script for Bash, Z shell, Fish, or PowerShell. |
| Ctrl+G | keyboard shortcut | Opens the external editor set by `VISUAL` (falling back to `EDITOR`) for composing a longer prompt; saving and closing returns the text to the composer. |

## Notes

- If the Z shell reports `command not found: compdef`, run `autoload -Uz compinit && compinit` before `eval "$(codex completion zsh)"`.
- For the full interactive keyboard shortcut and command/option list, see the CLI reference page (`/docs/developer-commands`).

## Related

- [Codex CLI](./cli.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# Codex CLI

Inspect code, make changes, run commands, and automate repeatable work without leaving your terminal. Works against your local repository with configurable model, reasoning effort, and permissions.

## Signature / Usage

Install with one of the standalone installers, npm, or Homebrew, then run `codex` from a project directory:

```bash
# macOS/Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex
```

```bash
codex
```

Updates use the same install command for each method (e.g. `brew upgrade --cask codex`).

## Getting started

1. **Install Codex** with the installer, npm, or Homebrew (see above).
2. **Run Codex and sign in.** Open a project directory and run `codex`; the first time, choose "Sign in with ChatGPT" or another available sign-in method.
3. **Start your first task.** Describe what you want (e.g. `Tell me about this project`). Create Git checkpoints before and after a task so you can revert changes.

## Notes

- `codex exec` runs Codex non-interactively for scripts and CI — the flag/option reference for automation belongs to a different scope (see the automation-focused reference); this page covers only the interactive CLI entry point.
- Codex CLI can delegate work to Codex cloud (`codex cloud`) and browse/apply results from the terminal.
- Full command/flag/slash-command reference and IDE/config surfaces are documented on separate pages outside this category.

## Related

- [ide.md](./ide.md)
- [cloud.md](./cloud.md)
- [models.md](./models.md)
- [best-practices.md](./best-practices.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント.

# Agent internet access

Control internet access for Codex cloud chats. By default, Codex blocks internet access during the agent phase; setup scripts still run with internet access so dependencies can install. Agent internet access can be enabled per environment when needed.

## Signature / Usage

Configure per environment in Codex cloud environment settings: toggle internet access **Off**/**On**, and when **On**, restrict it with a domain allowlist and allowed HTTP methods.

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| Internet access | `Off` \| `On` | Off completely blocks internet access; On allows it, optionally restricted |
| Domain allowlist | `None` \| `Common dependencies` \| `All` | None starts empty (build your own); Common dependencies presets major package registries (npm, PyPI, Maven, Docker Hub, GitHub, etc.); All is unrestricted |
| HTTP methods | `GET, HEAD, OPTIONS` (recommended) | Limiting to these blocks potentially dangerous methods like `POST`, `PUT`, `PATCH`, `DELETE` |

## Notes

- Risks of enabling agent internet access: prompt injection from untrusted web content, exfiltration of code/secrets, downloading malware or vulnerable dependencies, and pulling in license-restricted content.
- Prompt injection example: asking Codex to fix a GitHub issue whose description contains hidden instructions (e.g. piping `git show HEAD` to an attacker-controlled endpoint) can leak commit data if the agent follows them.
- Mitigation: allow only the domains and HTTP methods actually needed, and review the agent output and work log.

## Related

- [cloud.md](./cloud.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント.

# Codex cloud

Run coding tasks in isolated, parallel cloud environments. Work in parallel, and start work from the web, GitHub, Linear, or Slack.

## Signature / Usage

Open [chatgpt.com/codex](https://chatgpt.com/codex) and sign in with a ChatGPT account, or run `codex cloud` from the Codex CLI to browse and submit cloud tasks.

## Getting started

1. **Open Codex and sign in** at [chatgpt.com/codex](https://chatgpt.com/codex).
2. **Connect GitHub** and choose the repositories Codex can access.
3. **Create an environment** in [environment settings](https://chatgpt.com/codex/settings/environments): configure dependencies, tools, environment variables, or secrets the task needs.
4. **Start your first task**: choose the environment and describe the result you want; watch logs or let the task run in the background.
5. **Review the result**: inspect the summary and diff, ask for follow-up changes, or open a pull request.

## Why use Codex cloud

- **Run work in parallel** — give longer tasks dedicated environments and continue other work.
- **Reproduce the environment** — configure dependencies, tools, variables, and setup steps per repository.
- **Review before you merge** — inspect the summary/diff, request a follow-up, or open a pull request.

## Use Codex cloud when...

- Work needs to run in the background and you want to return when it's ready.
- You want to compare several attempts by running tasks in parallel without tying up your local machine.
- Work starts in GitHub, Linear, or Slack and you want to hand it off without leaving the pull request, issue, channel, or thread.
- You are away from your development machine and want to start/review work from the web or Codex CLI.

## Notes

- Codex CLI can browse active/completed cloud chats, submit work, and apply the result to a local repository via `codex cloud`.
- Internet access for cloud agents is off by default and is configured per environment (see Agent internet access below).
- Cloud environment configuration details, and GitHub/Linear/Slack integration specifics, belong to separate reference pages outside this category.

## Related

- [cloud-internet-access.md](./cloud-internet-access.md)
- [cli.md](./cli.md)
- [ide.md](./ide.md)
- [models.md](./models.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# Codex Micro

A limited-run hardware keyboard accessory (collaboration with Work Louder) for the ChatGPT desktop app: six illuminated Agent Keys that follow chats and show status, customizable Command Keys, an analog stick, a dial, and voice input — a way to check chats, switch between them, and trigger Codex actions or skills without leaving the keyboard.

## Signature / Usage

Press the rear button once to turn the device on, connect via USB-C or Bluetooth, then follow the setup that appears when ChatGPT detects it. Open **Settings > Codex Micro** to configure the Agent Keys, Command Keys, analog stick, dial, and lighting.

## Options / Props

| Name | Description |
|------|-------------|
| Agent Keys (6) | Each follows a chat and lights up with status (idle/thinking/complete/requires input/error/unassigned). Single press switches to that chat; double press (within 350ms) also brings ChatGPT forward. Arrangement modes: Most recent chats, Pinned chats, Priority chats, Custom assignments (can trigger an action or enabled skill instead of following a chat). |
| Command Keys (6) | Default layout: Fast (toggle Fast mode), Approve, Decline, Fork (continue chat in a new chat), Mic (push-to-talk), Codex (send composer message). Each is remappable to another command or enabled skill. |
| Analog stick | Four directional actions, default: Up = toggle Plan mode, Right/Left = forward/back in app history, Down = toggle sidebar. Remappable per direction. |
| Dial | Modes: Composer navigation (default), Reasoning only, Conversation scrolling, Custom assignments. Press-and-hold opens device settings (except in Custom assignments mode). |

## Notes

- macOS requires granting **Input Monitoring** to ChatGPT (System Settings > Privacy & Security > Input Monitoring) for key presses to register.
- Mic key uses the host computer's microphone; the device has no microphone of its own.
- Support for Bluetooth/cable/power issues comes from Work Louder (`hello@worklouder.cc`), not OpenAI Support.

## Related

- [Best practices](./best-practices.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント.

# Codex IDE extension

Use Codex beside your code and editor context. Bring open files and selections into the prompt, review edits in place, and hand off longer work without breaking your flow.

## Signature / Usage

Install the extension, then open it from the editor:

- Visual Studio Code / Cursor / Windsurf: install the Codex extension (`openai.chatgpt` on the VS Code Marketplace), then select the Codex icon or run **Codex: Open Codex Sidebar** from the Command Palette.
- Xcode: open the coding assistant, start a new chat, and choose Codex as the agent.
- JetBrains IDEs: open AI Chat and select Codex.

## Getting started

1. **Install or enable Codex** for your IDE (VS Code and compatible editors use the Codex extension; Xcode and JetBrains provide their own integrations).
2. **Open Codex** in the editor sidebar / AI chat panel.
3. **Start your first chat.** Ask Codex to explain the codebase, make a focused change, or help debug an issue. Create Git checkpoints before and after a task so you can revert changes.

## Notes

- The IDE extension can reference open files, selections, and recent chats directly from the composer as editor context.
- Longer tasks can be delegated to Codex cloud from the same editor workflow and the chat stays available when you return to review the result.
- IDE-specific keyboard shortcuts/commands and settings (`chatgpt.*` keys) are documented on separate reference pages outside this category.

## Related

- [cli.md](./cli.md)
- [cloud.md](./cloud.md)
- [models.md](./models.md)
- [best-practices.md](./best-practices.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント.

# Models

Meet the AI models that power ChatGPT Work and Codex, and how to choose between them across the desktop app, ChatGPT Work on the web, Codex CLI, and the IDE extension.

## Signature / Usage

```bash
# Choose a model / reasoning effort for a CLI run
codex --model gpt-5.6
codex exec -m gpt-5.6 "Review the current changes"
```

In an interactive CLI session, use `/model` to switch models or adjust reasoning effort. In the desktop app, ChatGPT Work on the web, and the IDE extension, use the model/reasoning control beneath the composer.

To set a default model for the desktop app, CLI, and IDE extension (they share one `config.toml`):

```toml
model = "gpt-5.6"
```

## Options / Props

| Name | Capability | Speed | Desktop app | Web | CLI | IDE extension | Cloud |
|------|-----------|-------|-------------|-----|-----|----------------|-------|
| `gpt-5.6-sol` | 5/5 | 2/5 | Yes | Yes | Yes | Yes | Yes |
| `gpt-5.6-terra` | 4/5 | 3/5 | Yes | Yes | Yes | Yes | No |
| `gpt-5.6-luna` | 3/5 | 4/5 | Yes | Yes | Yes | Yes | No |
| `gpt-5.3-codex-spark` | 2/5 | 5/5 | Yes | No | Yes | Yes | No |
| `gpt-5.5` (previous gen) | 4/5 | 3/5 | Yes | Yes | Yes | Yes | No |
| `gpt-5.4` (deprecated) | 3/5 | 3/5 | Yes | Yes | Yes | Yes | No |
| `gpt-5.4-mini` (deprecated) | 2/5 | 4/5 | Yes | Yes | Yes | Yes | No |

## Notes

- Recommended default is **Sol** (`gpt-5.6-sol`) for complex, open-ended work; **Terra** for pragmatic everyday work; **Luna** for clear, repeatable/high-volume tasks.
- Reasoning effort levels: Light/Low (quick well-scoped tasks) -> Medium (balanced) -> High/Extra High (difficult, multi-step work). There is no exact mapping from GPT-5.5 to GPT-5.6 reasoning efforts.
- **Max** gives the selected model more time on a single task. **Ultra** uses [subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents) to parallelize a divisible task; enable via Settings > Configuration > "Ultra in model picker slider" if not shown by default.
- `gpt-5.4` and `gpt-5.4-mini` retire from Codex (ChatGPT sign-in) on August 31, 2026 — replace with `gpt-5.6-terra` and `gpt-5.6-luna` respectively in saved configs, custom agents, and scheduled tasks. `gpt-5.2` and `gpt-5.3-codex` are already deprecated. The OpenAI API and Codex authenticated with your own API key are unaffected.
- Codex also supports any model/provider compatible with the Chat Completions or Responses APIs; Chat Completions support is deprecated and will be removed in a future release.
- Currently you cannot change the default model for Codex cloud chats.
- `subagents` (referenced by Ultra mode) belongs to a different scope's reference page, not this category.

## Related

- [cli.md](./cli.md)
- [ide.md](./ide.md)
- [cloud.md](./cloud.md)
- [best-practices.md](./best-practices.md)

# Getting Started

| Name | Description | Path |
|------|-------------|------|
| Best practices | Getting started with Codex and proven practices for better results, across the CLI, IDE extension, and ChatGPT desktop app — prompting, planning, validation, MCP, skills, and scheduled tasks. | [best-practices.md](./best-practices.md) |
| Codex CLI | Inspect code, make changes, run commands, and automate repeatable work without leaving your terminal. Works against your local repository with configurable model, reasoning effort, and permissions. | [cli.md](./cli.md) |
| CLI customization | Terminal-specific options for how interactive Codex CLI sessions look and how you enter commands and prompts: syntax-highlight themes, shell completions, and an external prompt editor. | [cli-customization.md](./cli-customization.md) |
| Codex cloud | Run coding tasks in isolated, parallel cloud environments. Work in parallel, and start work from the web, GitHub, Linear, or Slack. | [cloud.md](./cloud.md) |
| Agent internet access | Control internet access for Codex cloud chats. By default, Codex blocks internet access during the agent phase; setup scripts still run with internet access so dependencies can install. Agent internet access can be enabled per environment when needed. | [cloud-internet-access.md](./cloud-internet-access.md) |
| Codex Micro | A limited-run hardware keyboard accessory (collaboration with Work Louder) for the ChatGPT desktop app: six illuminated Agent Keys that follow chats and show status, customizable Command Keys, an analog stick, a dial, and voice input — a way to check chats, switch between them, and trigger Codex actions or skills without leaving the keyboard. | [codex-micro.md](./codex-micro.md) |
| Codex IDE extension | Use Codex beside your code and editor context. Bring open files and selections into the prompt, review edits in place, and hand off longer work without breaking your flow. | [ide.md](./ide.md) |
| Models | Meet the AI models that power ChatGPT Work and Codex, and how to choose between them across the desktop app, ChatGPT Work on the web, Codex CLI, and the IDE extension. | [models.md](./models.md) |
| Codex Remote | Start, guide, and review Codex coding tasks from the ChatGPT mobile app while the work actually runs on a connected Mac or Windows PC — follow progress, approve requested actions, and review diffs from your phone. | [remote.md](./remote.md) |
| Remote connections | Full setup and reference for connecting the ChatGPT mobile app (or another ChatGPT desktop app device) to a Mac/Windows host running Codex, or connecting the desktop app to a project on an SSH host. The remote session uses the connected host's projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools. | [remote-connections.md](./remote-connections.md) |
| ChatGPT desktop app for Windows | The Windows build of the ChatGPT desktop app: worktrees, scheduled tasks, Git functionality, built-in browser, file previews, plugins, and skills, running natively via PowerShell under the native Windows sandbox, or configurable to run the agent inside WSL2. | [windows-app.md](./windows-app.md) |

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# Remote connections

Full setup and reference for connecting the ChatGPT mobile app (or another ChatGPT desktop app device) to a Mac/Windows host running Codex, or connecting the desktop app to a project on an SSH host. The remote session uses the connected host's projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.

## Signature / Usage

```text
# ~/.ssh/config on the machine running the desktop app
Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519
```

```bash
ssh devbox   # confirm connectivity before adding the host in Settings > Connections
```

## Options / Props

| Name | Description |
|------|-------------|
| Mobile → desktop host | Desktop app: **Settings > Connections > Control this Mac or PC > Set up** → scan QR code from ChatGPT mobile app **Remote**. Supports macOS and Windows hosts. |
| Control other devices | Desktop app: **Settings > Connections > Control other devices**, for continuing work from another signed-in desktop app device. A device can both allow remote access and control another device. |
| SSH host project | Add the host to `~/.ssh/config` (concrete aliases only, resolved via OpenSSH; pattern-only hosts are ignored), confirm `ssh <host>` works, ensure `codex` is on `PATH` in the remote login shell, then add it under **Settings > Connections**. |
| Chat handoff | Chat footer → select run location → destination host (or **This computer** to bring a remote chat back) → **Hand off**. Requires a saved project for the same Git repository (same subdirectory) on both hosts; interrupts an in-flight response before transferring. |

## Notes

- Existing connections used since June 8, 2026 remain paired; older unused connections require updating both apps and re-pairing.
- Uses SSH to start/manage the remote Codex app server — don't expose app-server transports directly on a shared or public network; use a VPN/mesh tool to reach a remote machine outside the current network.
- Signing out of ChatGPT turns off Remote Control but keeps existing device pairings; sign back in and re-enable it to restore the connection.
- Workspace admins may need to enable Remote Control access before a user can connect from their phone.

## Related

- [Codex Remote](./remote.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# Codex Remote

Start, guide, and review Codex coding tasks from the ChatGPT mobile app while the work actually runs on a connected Mac or Windows PC — follow progress, approve requested actions, and review diffs from your phone.

## Signature / Usage

In the ChatGPT desktop app on the host: **Settings > Connections > Control this Mac or PC > Set up**, scan the resulting QR code with the ChatGPT mobile app, then open **Remote** on the phone to start or continue a task.

## Notes

- Requires the ChatGPT desktop app running and signed in on the host (kept awake and online), and the ChatGPT mobile app on the same account/workspace.
- Capabilities: start tasks from the phone, follow/steer active work, approve requested commands, and review diffs/test results — all executed on the connected computer under its existing sandbox/approval settings.
- This page is the product landing page; setup steps, SSH-host connections, chat handoff between hosts, and troubleshooting live in [Remote connections](./remote-connections.md).

## Related

- [Remote connections](./remote-connections.md)

> OpenAI Codex (learn.chatgpt.com) のドキュメント。

# ChatGPT desktop app for Windows

The Windows build of the ChatGPT desktop app: worktrees, scheduled tasks, Git functionality, built-in browser, file previews, plugins, and skills, running natively via PowerShell under the native Windows sandbox, or configurable to run the agent inside WSL2.

## Signature / Usage

```powershell
winget install --id 9PLM9XGG6VKS -s msstore
```

Then follow the quickstart (`learn.chatgpt.com/docs/quickstart?setup=app`) to sign in and open a project.

## Options / Props

| Name | Description |
|------|-------------|
| Preferred editor | Default app for **Open** (VS Code, Visual Studio, etc.); overridable per project. |
| Integrated terminal | PowerShell, Command Prompt, Git Bash, or WSL — applies to new terminal sessions only. |
| Agent: Windows-native vs. WSL | **Settings**: switch the agent to run in WSL2 instead of PowerShell; requires an app restart to take effect. |
| Useful dev tools | Git (review panel), Node.js, Python, .NET SDK, GitHub CLI — installable via `winget install --id <PackageId>`. |

## Notes

- Native sandbox applies when the agent runs in PowerShell; Linux sandboxing applies when the agent runs in WSL2. Select **Ask for approval** beneath the composer to keep sandbox protections active in either mode.
- Elevated command execution: start the desktop app itself via **Run as administrator** — the Codex agent inherits that permission level.
- PowerShell execution-policy errors (`... cannot be loaded because running scripts is disabled ...`) are commonly fixed with `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`.
- Uses the same Codex home directory as native Windows Codex CLI: `%USERPROFILE%\.codex`. See [WSL](../security-automation/windows-wsl.md) for sharing config/auth with a WSL-side CLI install.
- Opening a project from `\\wsl$\...` with the Windows-native agent is unreliable — prefer storing the project on the native Windows drive and accessing it from WSL via `/mnt/<drive>/...`.

## Related

- [Codex CLI](./cli.md)
- [Codex IDE extension](./ide.md)
- Windows sandbox (`../security-automation/windows-sandbox.md`)
- WSL (`../security-automation/windows-wsl.md`)
- Deploy the Windows app (`../administration/windows-deployment.md`)

# Agent approvals & security

How to operate Codex safely across sandboxing, approvals, and network access. Covers the two-layer security model (sandbox mode + approval policy), network isolation, auto-review, OS-level enforcement, Dev Containers, and telemetry.

## Signature / Usage

```bash
# Auto preset (default recommendation for version-controlled folders)
codex --sandbox workspace-write --ask-for-approval on-request

# Read-only, non-interactive (CI)
codex --sandbox read-only --ask-for-approval never

# Dangerous full access (not recommended)
codex --dangerously-bypass-approvals-and-sandbox   # alias: --yolo
```

```toml
# config.toml
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false  # optional hardening

[sandbox_workspace_write]
network_access = true
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `sandbox_mode` | `read-only` \| `workspace-write` \| `danger-full-access` | What Codex can technically do (where it can write, whether it can reach the network) when executing model-generated commands. |
| `approval_policy` | `untrusted` \| `on-request` \| `never` \| `{ granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = false, skill_approval = false } }` | When Codex must stop and ask before acting. Granular policy can toggle `sandbox_approval`, `rules`, `mcp_elicitations`, `request_permissions`, `skill_approval` independently. |
| `approvals_reviewer` | `user` (default) \| `auto_review` | Who reviews interactive approval requests. `auto_review` routes eligible requests to a reviewer agent instead of a human (see Auto-review). |
| `sandbox_workspace_write.network_access` | boolean | Enables network access in `workspace-write` mode (off by default). |
| `features.network_proxy.enabled` / `.domains` | boolean / table | Constrains already-enabled command network access to an allow/deny domain policy. Does not grant network access by itself. |
| `web_search` | `cached` (default) \| `live` \| `disabled` \| `indexed` | Controls the web search tool independently of full network access. |
| `--ask-for-approval never` / `-a never` | flag | Disables approval prompts; works with all `--sandbox` modes. |
| `codex sandbox macos\|linux\|windows [--permission-profile <name>] [COMMAND]...` | CLI | Test what a command would do under the sandbox locally (aliases: `codex debug`, `codex sandbox seatbelt`, `codex sandbox landlock`). |

## Notes

- Codex uses different sandbox mechanisms per surface: Codex cloud runs isolated containers (two-phase: networked setup, then offline agent phase unless internet access is enabled); local CLI/IDE use OS-level enforcement.
- Protected paths remain read-only even in `workspace-write`: `<root>/.git`, `<root>/.agents`, `<root>/.codex` (recursively).
- OS enforcement: macOS uses Seatbelt (`sandbox-exec`); Linux/WSL2 use `bwrap` + `seccomp` (WSL1 unsupported since Codex 0.115); native Windows uses the Windows sandbox (`elevated`/`unelevated`, see windows-sandbox.md).
- Network policy is allowlist-first: exact hosts match only themselves, `*.example.com` matches subdomains only, `**.example.com` matches apex + subdomains, global `*` is allow-only, `deny` always wins.
- Local/private destinations are blocked by default (`allow_local_binding = false`); DNS-rebinding checks block hostnames resolving to non-public addresses.
- Two `dangerously_*` settings widen the trust boundary and should be used only in tightly controlled environments: `dangerously_allow_non_loopback_proxy`, `dangerously_allow_all_unix_sockets`.
- **This page and `sandboxing.md` describe the older `sandbox_mode` / `sandbox_workspace_write` / `features.network_proxy` model.** As of Codex 0.138.0 it does not compose with the newer `default_permissions` / `[permissions.<name>]` profile system in `permissions.md` — only one system is active per session. Codex falls back to this older model whenever `sandbox_mode` appears in any loaded config, `--sandbox` is passed, or the selected profile sets `sandbox_mode`; the exception is managed `allowed_permission_profiles`, which forces the profile system.
- Dev Containers can supply the outer isolation boundary when the host cannot run the Linux sandbox directly; see the `openai/codex` `.devcontainer` secure example.
- Opt-in OpenTelemetry (`[otel]`) can log tool approval decisions and results (off by default); keep `log_user_prompt = false` unless policy allows storing prompt text.
- This page is distinct from "Codex Security", OpenAI's separate product for scanning connected GitHub repositories (`docs/security/*`) — not covered in this category.
- The official guide (this page) writes the flag as `--permissions-profile` (plural), while the CLI reference (`/docs/cli/reference`) lists `-P, --permission-profile <NAME>` (singular, alongside a separate `-p, --profile <NAME>`); the singular form is authoritative.

## Related

- [Permission profiles](./permission-profiles.md)
- [Sandbox](./sandbox.md)
- [Auto-review](./auto-review.md)
- [Windows sandbox](./windows-sandbox.md)

# Use Codex with the Agents SDK (MCP server)

Runs Codex CLI as a Model Context Protocol (MCP) server so other MCP clients — for example an agent built with the OpenAI Agents SDK — can call it, enabling deterministic, reviewable multi-agent workflows.

## Signature / Usage

```bash
codex mcp-server

# Inspect it
npx @modelcontextprotocol/inspector codex mcp-server
```

```python
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "codex", "args": ["mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    ...
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `codex` tool: `prompt` (required) | string | Initial user prompt starting a Codex conversation. |
| `codex` tool: `approval-policy` | string | `untrusted`, `on-request`, or `never` for shell commands the model generates. |
| `codex` tool: `sandbox` | string | `read-only`, `workspace-write`, or `danger-full-access`. |
| `codex` tool: `model` / `cwd` / `config` / `base-instructions` / `developer-instructions` / `compact-prompt` | various | Per-session overrides; `config` merges into `$CODEX_HOME/config.toml` settings. |
| `codex-reply` tool: `prompt` (required), `threadId` (required) | string | Continues a session; `conversationId` is a deprecated alias for `threadId`. |

## Notes

- `tools/list` on the MCP server returns two tools: `codex` (start a session) and `codex-reply` (continue via `threadId`, taken from `structuredContent.threadId` in the prior `tools/call` response; approval prompts also carry `threadId`).
- Modern MCP clients generally read only `structuredContent`; the server also returns `content` for older clients.
- The multi-agent workflow pattern uses `MCPServerStdio` to keep one long-running Codex MCP server alive across many agent turns, with sub-agents instructed to always call Codex with an explicit `approval-policy`/`sandbox` pair (e.g. `"never"` / `"workspace-write"`) so file-writing steps don't block on interactive approval.
- Requires Codex CLI installed locally (`codex` on `PATH`), Python 3.10+ for the Agents SDK example, and Node.js 18+ only if using the MCP Inspector.

## Related

- [Codex SDK](./codex-sdk.md)
- [Non-interactive mode](./non-interactive-mode.md)

# Auto-review

Replaces manual approval at the sandbox boundary with a separate reviewer agent. The main Codex agent still runs inside the same sandbox with the same approval policy and network/filesystem limits; only who reviews eligible escalation requests changes.

## Signature / Usage

```toml
approval_policy    = "on-request"
approvals_reviewer = "auto_review"

[auto_review]
policy = """
YOUR POLICY GOES HERE
"""
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `approvals_reviewer` | `user` \| `auto_review` | Routes eligible approval requests to a reviewer agent instead of a human. Only applies when approvals are interactive (`on-request` or a granular policy that still surfaces the prompt); does nothing under `approval_policy = "never"`. |
| `[auto_review].policy` | string (TOML multiline) | Local override of the reviewer policy text; managed enterprise `guardian_policy_config` requirements take precedence. |
| `/approve` (TUI) | command | Opens the Auto-review Denials picker to approve one recently denied action for a single retry. |

## Notes

- Triggers on: shell/exec calls requesting escalated sandbox permissions, network requests blocked by policy, file edits outside writable roots, MCP/app tool calls requiring approval, and Computer Use access to a new domain. Does not run for actions already allowed inside the sandbox. Computer Use app approvals still surface directly to the user.
- Blocks (at a high level): sending private data/secrets/credentials to untrusted destinations, credential probing, broad/persistent security weakening, and destructive irreversible actions. Low/medium risk actions may proceed per policy; critical risk is always denied; high risk requires user authorization and no matching deny rule. Prompt-build, review-session, and parse failures fail closed.
- Denials are stronger than ordinary sandbox errors: the main agent is instructed not to pursue the same outcome via workaround and to find a materially safer path or stop and ask the user.
- Rejection circuit breaker: interrupts the turn after 3 consecutive denials or 10 denials within the last 50 reviews in that turn; any non-denial resets the consecutive counter.
- The reviewer sees a compact transcript plus the exact approval request (user messages, surfaced updates, relevant tool calls/outputs) — not hidden assistant chain-of-thought.
- Default policy source: `codex-rs/core/src/guardian/policy.md` in the `openai/codex` repo. Enterprises replace its tenant-specific section via `guardian_policy_config`; per-user `[auto_review].policy` is supported but managed requirements win.
- Reduce noisy reviews by narrowing the sandbox boundary first (add scoped `writable_roots`, precise command-prefix rules) rather than teaching the reviewer to approve broad escalations.
- Session transcripts are retained under `~/.codex/sessions` by default.
- Not a deterministic security guarantee — complements, not replaces, sandbox design and monitoring.

## Related

- [Agent approvals & security](./agent-approvals-security.md)
- [Sandbox](./sandbox.md)

# Codex SDK

Programmatic control of local Codex threads from TypeScript or Python, for CI/CD pipelines, custom agents, or embedding Codex in internal tools and applications.

## Signature / Usage

```python
from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)
```

```ts
import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `npm install @openai/codex-sdk` | package | TypeScript library; server-side use only, requires Node.js 18+. |
| `pip install openai-codex` | package | Python library controlling the local Codex app-server over JSON-RPC; requires Python 3.10+. While in beta, plain `pip install openai-codex` gets the latest beta build. |
| `codex.startThread()` / `codex.resumeThread(threadId)` | TS methods | Start a new thread or resume a past one by ID. |
| `thread.run(prompt)` | TS/Python method | Runs a prompt on a thread; call again to continue the same thread. |
| `Sandbox.read_only` / `.workspace_write` / `.full_access` | Python enum (presets) | Filesystem access for `thread_start(sandbox=...)` or a later `run(...)`/`turn(...)` call; a sandbox passed to `run`/`turn` applies to that turn and later turns on the thread. |
| `AsyncCodex` | Python class | Async variant of `Codex` for applications already running asyncio. |
| `CodexConfig(codex_bin=...)` | Python config | Runs against a specific local Codex executable instead of the SDK's pinned runtime dependency (only needed intentionally). |

## Notes

- Use the Codex SDK for coding-focused Codex threads. If Codex is one specialist inside a broader orchestrated workflow, run Codex CLI as an MCP server and orchestrate it with the Agents SDK instead (see `agents-sdk-mcp-server.md`).
- Omitting `sandbox=` lets app-server use its configured default.
- A separate Codex Security TypeScript SDK exists for repository/change scans with structured security findings — not the same product as this coding-agent SDK.

## Related

- [Use Codex with the Agents SDK](./agents-sdk-mcp-server.md)
- [Non-interactive mode](./non-interactive-mode.md)

# Codex GitHub Action

`openai/codex-action@v1` runs Codex in CI/CD jobs, applies patches, or posts reviews from a GitHub Actions workflow. Installs the Codex CLI, starts a Responses API proxy for the provided key, and runs `codex exec` under the permissions you specify.

## Signature / Usage

```yaml
- name: Run Codex
  id: run_codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    output-file: codex-output.md
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `prompt` / `prompt-file` | string (choose one) | Inline instructions or a repo path (e.g. `.github/codex/prompts/`) to the task text. |
| `codex-args` | JSON array or shell string | Extra `codex exec` flags, e.g. `["--ephemeral"]` or `--profile ci`. |
| `model` / `effort` | string | Overrides the Codex agent configuration; empty for defaults. |
| `sandbox` | `workspace-write` \| `read-only` \| `danger-full-access` | Sandbox mode matched to the permissions the run needs. |
| `output-file` | string | Path to save the final Codex message for later steps/artifacts. |
| `codex-version` | string | Pins a specific CLI release; blank uses the latest published version. |
| `codex-home` | string | Shared Codex home directory to reuse config/MCP setups across steps. |
| `safety-strategy` | `drop-sudo` (default) \| `unprivileged-user` \| `unsafe` | Removes `sudo` before running Codex (irreversible for the job); Windows runners require `unsafe`. |
| `unprivileged-user` / `codex-user` | boolean / string | Pairs with `safety-strategy: unprivileged-user` to run Codex as a specific account. |
| `read-only` | boolean | Blocks file/network changes but still runs with elevated privileges — not sufficient alone to protect secrets. |
| `allow-users` / `allow-bots` | string | Restricts who can trigger the workflow; default is write-access collaborators only. |

## Notes

- Emits the last Codex message via the `final-message` output; map it to a job output or a later step.
- Run on a Linux or macOS runner unless `safety-strategy: unsafe` is set (required for Windows).
- Security checklist: limit who can start the workflow, sanitize prompt inputs from PR/issue/commit text (prompt injection), keep `safety-strategy` on `drop-sudo` or an unprivileged user, run Codex as the last step in a job, and rotate keys if proxy logs or output might have exposed secrets.
- Typical CI-autofix pattern: a read-only job (`contents: read`) runs Codex and uploads only the diff as a patch artifact (no repo write, no `OPENAI_API_KEY` in the second job); a separate job with `contents: write` / `pull-requests: write` applies the patch and opens the PR.

## Related

- [Non-interactive mode](./non-interactive-mode.md)
- [Codex SDK](./codex-sdk.md)

# Non-interactive mode (`codex exec`)

Runs Codex from scripts (CI jobs, pipelines) without opening the interactive TUI. Streams progress to `stderr` and prints only the final agent message to `stdout`.

## Signature / Usage

```bash
codex exec "summarize the repository structure and list the top 5 risky areas"

# Explicit sandbox/permissions for automation
codex exec --sandbox workspace-write "<task>"

# Machine-readable JSON Lines output
codex exec --json "summarize the repo structure" | jq

# Structured output via JSON Schema
codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json

# Resume a previous non-interactive session
codex exec resume --last "fix the race conditions you found"
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `--sandbox workspace-write` \| `read-only` (default) \| `danger-full-access` | flag | Sets least-privilege permissions for the automation task; `danger-full-access` only in a controlled runner/container. |
| `--ephemeral` | flag | Doesn't persist session rollout files to disk. |
| `--json` | flag | Emits a JSONL event stream on `stdout` (`thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.*`, `error`). |
| `-o, --output-last-message <path>` | flag | Writes the final message to a file (still also printed to `stdout`). |
| `--output-schema <file>` | flag | Requests a final response conforming to a JSON Schema — useful for stable downstream fields. |
| `--ignore-user-config` | flag | Skips loading `$CODEX_HOME/config.toml`. |
| `--ignore-rules` | flag | Skips user/project execpolicy `.rules` files. |
| `--skip-git-repo-check` | flag | Overrides the requirement that `codex exec` run inside a Git repository. |
| `CODEX_API_KEY` | env var | API key scoped to a single `codex exec` invocation (only supported in `codex exec`, not the interactive CLI). |
| `codex exec resume [--last \| <SESSION_ID>]` | subcommand | Continues a previous non-interactive session (for two-stage pipelines). |

## Notes

- If stdin is piped and a prompt argument is also given, the prompt is the instruction and piped content is additional context (`prompt-plus-stdin`). Use `codex exec -` to force stdin to become the entire prompt instead.
- `codex exec --full-auto` is a deprecated compatibility alias for `--sandbox workspace-write`; prefer the explicit flag.
- If an enabled MCP server has `required = true` and fails to initialize, `codex exec` exits with an error instead of continuing.
- Do not set `OPENAI_API_KEY`/`CODEX_API_KEY` as a job-level environment variable in workflows that check out or run repository-controlled code — build scripts, tests, or a compromised action in the same job can read it. For GitHub Actions, prefer the Codex GitHub Action, which proxies the key instead of exposing it to shell steps.
- Codex requires running inside a Git repository by default (safety check against destructive changes).

## Related

- [Codex GitHub Action](./github-action.md)
- [Agent approvals & security](./agent-approvals-security.md)
- [Codex SDK](./codex-sdk.md)

# Permission modes

The high-level modes exposed in the ChatGPT desktop app, IDE extension, and CLI (`/permissions`) that set the boundary for what Codex can do on its own versus what needs review — the user-facing counterpart to the `sandbox_mode`/`approval_policy` or `default_permissions`/`[permissions]` config systems.

## Signature / Usage

Use the permissions control below the composer in the ChatGPT desktop app or IDE extension, or run `/permissions` in the CLI.

## Options / Props

| Name | Description |
|------|-------------|
| Ask for approval | Recommended starting point. Codex works within the current workspace and pauses before reaching beyond that boundary. |
| Approve for me | Called **Auto-review** in settings. Keeps the same workspace boundary as "Ask for approval"; sends requests that would cross that boundary to automatic review instead of pausing for a human. |
| Full access | Removes the workspace boundary; available only after being enabled. |

## Notes

- Two controls work together: the **sandbox** defines which files/network resources Codex can access, and **approvals** determine when Codex pauses or sends a request to automatic review. Changing who reviews a request (e.g. selecting Approve for me) does not by itself expand the sandbox.
- **Ask for approval** is always available. To add **Approve for me** or **Full access** to the menu, turn them on under **Settings > General > Permissions** in the ChatGPT desktop app first — this makes the mode available, it doesn't select it or change an existing chat.
- Available modes can depend on local configuration and organization-managed requirements; a disallowed mode appears disabled.
- This page describes the product-level mode selector. For the underlying config keys, see [Sandbox](./sandbox.md) (`sandbox_mode`/`approval_policy`) and [Permission profiles](./permission-profiles.md) (`default_permissions`/`[permissions.<name>]`) — the two config systems do not compose with each other.

## Related

- [Sandbox](./sandbox.md)
- [Permission profiles](./permission-profiles.md)
- [Auto-review](./auto-review.md)
- [Agent approvals & security](./agent-approvals-security.md)

# Permission profiles

Beta. Named policies that combine filesystem rules (what commands can read/write) with network rules (which destinations commands can reach), applying least-privilege boundaries to local commands Codex runs on your behalf.

## Signature / Usage

```toml
default_permissions = "project-edit"

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.workspace_roots]
"~/code/app" = true

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"*.github.com" = "allow"
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `:read-only` | built-in profile | Keeps local command execution read-only. |
| `:workspace` | built-in profile | Allows writes inside active workspace roots and system temp directories; keeps `.codex`/`.git`/`.agents` read-only. |
| `:danger-full-access` | built-in profile | Removes local sandbox restrictions. Cannot be used as an `extends` parent. |
| `default_permissions` | string | Selects the active profile by name or built-in. |
| `[permissions.<name>]` | table | Defines a named profile; `extends` starts it from `:read-only`, `:workspace`, or another named profile (not `:danger-full-access`; no unknown parents or cycles). |
| `[permissions.<name>.workspace_roots]` | table | Adds concrete directories treated as workspace roots for the profile. |
| `[permissions.<name>.filesystem]` | table of path → `read`\|`write`\|`deny` | Filesystem access rules. `deny` beats `write` beats `read` at equal specificity; a more specific path can reopen a narrower subtree inside a broader `deny`. |
| `[permissions.<name>.network]` | table | `enabled` (bool), `domains` (host pattern → `allow`\|`deny`), `unix_sockets`, `proxy_url`, `enable_socks5`, `allow_local_binding`, and `dangerously_*` escape hatches. |

## Notes

- Supported filesystem path forms: `:root` (filesystem root), `:minimal` (platform/runtime paths common tools need), `:workspace_roots` (session + profile-defined roots, supports scoped subpaths), `:tmpdir`, `:slash_tmp`, absolute paths, and `~/path`.
- Network domain patterns: exact host, `*.example.com` (subdomains only), `**.example.com` (apex + subdomains), `*` (allow-only global wildcard). `deny` always overrides `allow`.
- **Permission profiles do not compose with the older sandbox settings.** Configure either `default_permissions` + `[permissions]`, or `sandbox_mode` / `sandbox_workspace_write`, but not both. If `sandbox_mode` appears in any loaded config file, `--sandbox` is passed, or the selected profile sets `sandbox_mode`, Codex uses the older sandbox settings instead (see `sandbox.md` / `agent-approvals-security.md`). Managed `allowed_permission_profiles` is the exception — it forces the profile system; remove `sandbox_mode` / `[sandbox_workspace_write]` before deploying it. Full backward-compat requires every client on Codex 0.138.0 or later.
- Enforcement differs by OS: macOS Seatbelt refuses to run a command instead of running it unsandboxed if the policy can't be enforced; Linux/WSL use bubblewrap + seccomp (Landlock as compatibility fallback); native Windows uses `elevated` (strongest, dedicated low-privilege sandbox users + firewall rules) or the weaker `unelevated` fallback (restricted token + ACL boundaries), and unsupported split read/write policies are refused.
- Config detail beyond the profile-shaping keys above (the full `permissions.<name>.network.*` listener/proxy spec, `glob_scan_max_depth`, etc.) is `config.toml` key reference material — see the config category for the exhaustive table.
- Local permission profiles are supported on macOS, Linux, WSL, and native Windows.

## Related

- [Agent approvals & security](./agent-approvals-security.md)
- [Sandbox](./sandbox.md)

# Security & Automation

| Name | Description | Path |
|------|-------------|------|
| Agent approvals & security | Sandbox mode + approval policy model, network isolation, auto-review integration, OS enforcement, Dev Containers, telemetry | [agent-approvals-security.md](./agent-approvals-security.md) |
| Sandbox | Core sandbox concept and modes (`read-only`/`workspace-write`/`danger-full-access`), approval policies, per-OS prerequisites | [sandbox.md](./sandbox.md) |
| Permission profiles | Newer `default_permissions` / `[permissions.<name>]` profile system (filesystem + network least-privilege) | [permission-profiles.md](./permission-profiles.md) |
| Auto-review | Reviewer-agent replacement for manual approvals at the sandbox boundary | [auto-review.md](./auto-review.md) |
| Windows sandbox | Native Windows `elevated`/`unelevated` sandbox setup and troubleshooting | [windows-sandbox.md](./windows-sandbox.md) |
| Non-interactive mode (`codex exec`) | Running Codex from scripts/CI, JSON/JSONL output, structured schemas, auth in automation | [non-interactive-mode.md](./non-interactive-mode.md) |
| Codex GitHub Action | `openai/codex-action@v1` for CI/CD workflows, patch generation, PR review | [github-action.md](./github-action.md) |
| Codex SDK | TypeScript/Python SDKs for programmatic control of local Codex threads | [codex-sdk.md](./codex-sdk.md) |
| Use Codex with the Agents SDK | Running Codex CLI as an MCP server for multi-agent orchestration | [agents-sdk-mcp-server.md](./agents-sdk-mcp-server.md) |

# Sandbox

The boundary that lets Codex act autonomously without unrestricted machine access. Applies to spawned commands (`git`, package managers, test runners), not just built-in file operations, and works together with the separate approval-policy control.

## Signature / Usage

```toml
# config.toml
sandbox_mode    = "workspace-write"   # read-only | workspace-write | danger-full-access
approval_policy = "on-request"        # untrusted | on-request | never
approvals_reviewer = "user"           # user | auto_review
```

```bash
# Equivalent CLI flags for the low-friction local automation preset
codex --sandbox workspace-write --ask-for-approval on-request
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `read-only` | sandbox mode | Agent can inspect files; edits and commands need approval. |
| `workspace-write` | sandbox mode | Agent can read, edit within the workspace, and run routine commands in that boundary (default low-friction mode). |
| `danger-full-access` | sandbox mode | No filesystem/network restrictions; use only when full access is intended. |
| `untrusted` | approval policy | Asks before running commands outside its trusted set. |
| `on-request` | approval policy | Works inside the sandbox by default, asks when it must go beyond it. |
| `never` | approval policy | Never stops for approval prompts. |
| `sandbox_workspace_write.writable_roots` | table | Extends writable directories beyond the workspace without disabling the sandbox entirely. |

## Notes

- Prerequisites: macOS works out of the box (Seatbelt). Linux/WSL2 need `bubblewrap` installed (`apt install bubblewrap` / `dnf install bubblewrap`); Codex falls back to a bundled helper requiring unprivileged user-namespace support if no `bwrap` binary is on `PATH`. Native Windows uses the Windows sandbox; WSL2 uses the Linux sandbox implementation.
- Full access = `sandbox_mode = "danger-full-access"` + `approval_policy = "never"`. The lower-risk automation preset is `workspace-write` + `on-request` (or `--sandbox workspace-write --ask-for-approval on-request`).
- For a workflow-specific exception, prefer command-prefix rules over broadly expanding sandbox access.
- **This page describes the older `sandbox_mode`/`approval_policy` model.** It does not compose with the newer permission-profile system (`default_permissions` / `[permissions.<name>]`) — see the mutual-exclusion note in `permission-profiles.md`.
- `approvals_reviewer = "auto_review"` only changes who reviews requests that already need approval; it never changes the sandbox boundary itself.

## Related

- [Agent approvals & security](./agent-approvals-security.md)
- [Auto-review](./auto-review.md)
- [Permission profiles](./permission-profiles.md)
- [Windows sandbox](./windows-sandbox.md)

# Windows sandbox

The native sandbox used when Codex runs directly on Windows (ChatGPT desktop app, CLI, or IDE extension) without WSL — blocks filesystem writes outside the working folder and prevents network access without explicit approval.

## Signature / Usage

```toml
[windows]
sandbox = "elevated"  # or "unelevated"
# sandbox_private_desktop = true  # default
```

```text
/sandbox-add-read-dir C:\absolute\directory\path
```

## Options / Props

| Name | Type | Description |
|------|------|-------------|
| `windows.sandbox` | `elevated` \| `unelevated` | `elevated` (preferred): dedicated lower-privilege sandbox users, filesystem permission boundaries, firewall rules. `unelevated` (fallback): restricted Windows token derived from the current user, ACL-based filesystem boundaries, weaker network isolation; useful when administrator-approved setup is blocked. |
| `windows.allowed_sandbox_implementations` (managed `requirements.toml`) | array | Restricts which native sandbox implementations are permitted, e.g. `["elevated"]`. Codex prefers `elevated` when unset. |
| `windows.sandbox_private_desktop` | boolean (default `true`) | Uses a private desktop for stronger UI isolation; set `false` only for `Winsta0\Default` compatibility. |
| `/sandbox-add-read-dir <path>` | slash command | Grants sandbox read access to an absolute directory for the rest of the session when a command fails due to a directory it can't read. |

## Notes

- If both modes are available, use `elevated`; fall back to `unelevated` only while troubleshooting.
- Windows version support: Windows 11 recommended; recent fully-updated Windows 10 (1809+, needs ConPTY) is best-effort; older Windows 10 builds are not recommended. `winget` should be available.
- The IDE extension on Windows can instead run inside WSL2 (`chatgpt.runCodexInWindowsSubsystemForLinux: true` in VS Code settings), inheriting Linux sandbox semantics.
- Common failures: UAC/administrator prompt declined, blocked local user/group creation, blocked firewall changes, or blocked sandbox-user logon rights fall back to `unelevated`. Windows error `1385` means Windows denies the logon type the sandbox user needs — check device policy / group policy. A warning about folders writable by `Everyone` means folder ACLs are too broad for the sandbox to fully protect.
- Diagnostics: send `CODEX_HOME/.sandbox/sandbox.log`; never send the contents of `CODEX_HOME/.sandbox-secrets/`.
- For general sandbox/approval concepts (not Windows-specific), see `agent-approvals-security.md` and `sandbox.md`.

## Related

- [Sandbox](./sandbox.md)
- [Agent approvals & security](./agent-approvals-security.md)

# WSL

Running Codex inside WSL2 instead of the native Windows sandbox — the Linux-native alternative when your repositories/tooling already live in WSL2 or the native Windows sandbox modes don't fit. WSL1 is unsupported (dropped when the Linux sandbox moved to `bubblewrap` in Codex 0.115; last supported in 0.114).

## Signature / Usage

```powershell
# Elevated PowerShell
wsl --install
wsl
```

```bash
# Inside the WSL shell
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
```

## Options / Props

| Name | Description |
|------|-------------|
| CLI in WSL | Install/run Codex CLI directly inside the WSL2 shell; runs under the Linux sandbox (bubblewrap/seccomp), not the native Windows sandbox. |
| Desktop app agent = WSL | Desktop app **Settings**: switch the agent from Windows-native to WSL, then restart the app (required for the change to take effect). Terminal choice (PowerShell/WSL/etc.) is configured independently of the agent. |
| VS Code from WSL | `code .` from a WSL shell opens a WSL remote window; confirm with the `WSL: <distro>` status bar item or `echo $WSL_DISTRO_NAME`. |

## Notes

- Keep repositories under the Linux home directory (e.g. `~/code/my-app`), not Windows-mounted paths like `/mnt/c/...` — the latter is markedly slower and prone to symlink/permission issues.
- Windows-side file access to a WSL repo: `\\wsl$\<distro>\home\<user>` in Explorer.
- Large-repo slowness troubleshooting: confirm you're not under `/mnt/c`, then `wsl --update` / `wsl --shutdown`.
- Sharing config/auth/sessions between the Windows-native app and CLI-in-WSL: the desktop app always uses `%USERPROFILE%\.codex`, while WSL's CLI defaults to its own Linux home — sync `~/.codex` with `%USERPROFILE%\.codex`, or set `export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex` in the WSL shell profile.
- This page covers running/using Codex through WSL2; for the native (non-WSL) Windows sandbox model (`elevated`/`unelevated`), see [Windows sandbox](./windows-sandbox.md).

## Related

- [Windows sandbox](./windows-sandbox.md)
- [Sandbox](./sandbox.md)

# Run bulk security scans

Discover GitHub repositories or run resumable security scans from a CSV inventory using `npx @openai/codex-security bulk-scan`.

## Signature / Usage

GitHub discovery (interactive):

```bash
gh auth login
npx @openai/codex-security bulk-scan
```

Steps: choose personal account or organization → review repositories active within 90 days → search/select repositories → choose results directory → confirm campaign. Discovery excludes archived repositories and forks; selections are recorded in `<output-directory>/repositories.csv`.

GitHub Enterprise Server:

```bash
gh auth login --hostname github.example.com
GH_HOST=github.example.com npx @openai/codex-security bulk-scan
```

CSV inventory:

```csv
id,repository,revision,scope,mode
payments,https://github.com/example/payments.git,0123456789abcdef0123456789abcdef01234567,services/api,standard
identity,https://github.com/example/identity.git,fedcba9876543210fedcba9876543210fedcba98,,deep
```

```bash
npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4
```

## Options / Props

| Column | Required | Description |
|--------|----------|-------------|
| `id` | Yes | Unique identifier (letters, numbers, `.`, `-`, `_`) |
| `repository` | Yes | HTTPS URL, SSH URL, or local path (relative paths resolve from CSV directory) |
| `revision` | Yes | Full 40- or 64-character Git commit SHA — no branches/tags/short hashes |
| `scope` | No | Repository-relative directory to scan; omit for full repository |
| `mode` | No | `standard` or `deep`; omit to use the command's selected mode |

| Flag | Default | Description |
|------|---------|-------------|
| `--workers` | `4` | Concurrent repository scans |
| `--mode` | — | Mode for rows without their own `mode` |
| `--max-attempts` | `1` | Retries for temporary repository/scan errors |
| `--model` / `--effort` | `gpt-5.6-sol` / `xhigh` | Model and reasoning effort |

## Campaign results

```text
security-scans/
├── manifest.json
├── results.jsonl
├── checkouts/
└── artifacts/
    └── <repo-id>/
        └── attempt-1/
            ├── scan-manifest.json
            ├── findings.json
            ├── coverage.json
            └── report.md
```

A repository counts as complete only when its scan has complete coverage and all required artifacts exist.

Export a single repository's result:

```bash
npx @openai/codex-security export \
  /path/outside/repositories/security-scans/artifacts/payments/attempt-1 \
  --export-format sarif \
  --output /path/outside/repositories/payments.sarif
```

## Resume / retry

Run the original command with the same CSV and output directory to resume; the CLI skips a repository only when its receipt and all required artifacts still exist. Don't change the repository inventory for an existing output directory — use a new output directory instead.

Exit codes: `0` all succeeded, `2` repository/coverage/input error, `130` Ctrl-C, `143` SIGTERM.

## Docker

```bash
docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4
```

Requires a Linux Docker host supporting unprivileged user namespace creation. Supply `GH_TOKEN`/`GITHUB_TOKEN` for private repositories; set `CODEX_SECURITY_GIT_HOST` for GitHub Enterprise Server.

## Notes

- Don't change the repository inventory for an existing output directory — the CLI checks the pinned manifest and rejects a different campaign; use a new output directory when repositories, revisions, scopes, or modes change
- Results can contain source excerpts and vulnerability details; keep the output directory private, outside scanned repositories, and subject to an appropriate retention policy

## Related

- [Codex Security CLI quickstart](./cli-quickstart.md)
- [Codex Security CLI reference](./cli-reference.md)
- [Codex Security CLI FAQ](./cli-faq.md)

# Run Codex Security in CI

Scan pull-request changes, preserve structured results, upload SARIF, and set a severity policy using the `@openai/codex-security` CLI.

## Signature / Usage

Store an OpenAI API key as a secret `CODEX_SECURITY_API_KEY`. Runner needs Node.js 22+, Python 3.10+, `@openai/codex-security` installed outside the repository checkout, and full PR head/base history.

```yaml
name: Codex Security scan
on:
  pull_request:
jobs:
  codex-security:
    if: github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: "26"
      - uses: actions/setup-python@v7
        with:
          python-version: "3.14"
      - name: Install Codex Security
        run: |
          npm install --prefix "$RUNNER_TEMP/codex-security" \
            --ignore-scripts --no-audit --no-fund @openai/codex-security@0.1.3
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false
      - name: Scan the pull request
        env:
          OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          CODEX_SECURITY_STATE_DIR: ${{ runner.temp }}/codex-security-state
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_SHA")"
          "$CODEX_SECURITY_BIN" scan . --diff "$BASE_REVISION" --head "$HEAD_SHA" \
            --auth api-key --output-dir "$SCAN_DIR" --json > "$RUNNER_TEMP/codex-security.json"
      - name: Export SARIF
        id: export-sarif
        if: always()
        env:
          CODEX_SECURITY_BIN: ${{ runner.temp }}/codex-security/node_modules/.bin/codex-security
          SCAN_DIR: ${{ runner.temp }}/codex-security-results
          SARIF_FILE: ${{ runner.temp }}/codex-security.sarif
        run: |
          if test -f "$SCAN_DIR/scan-manifest.json"; then
            "$CODEX_SECURITY_BIN" export "$SCAN_DIR" --export-format sarif \
              --source-root "$GITHUB_WORKSPACE" --output "$SARIF_FILE"
            echo "available=true" >> "$GITHUB_OUTPUT"
          fi
      - uses: github/codeql-action/upload-sarif@v4
        if: always() && steps.export-sarif.outputs.available == 'true'
        with:
          sarif_file: ${{ runner.temp }}/codex-security.sarif
          category: codex-security
```

## Severity policy

```bash
"$CODEX_SECURITY_BIN" scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --fail-on-severity high
```

Thresholds: `critical`, `high`, `medium`, `low` (includes findings at that severity and above).

## Options / Props

| Exit | Meaning |
|------|---------|
| `0` | Scan complete, coverage complete, policy passed |
| `1` | Completed scan contains a finding at/above the threshold |
| `2` | Input/runtime error, or incomplete coverage |
| `130` | Ctrl-C interrupted |
| `143` | SIGTERM terminated |

## Notes

- `--json` writes one complete JSON document to stdout, unlike `codex exec --json` which emits a JSON Lines event stream
- `--auth api-key` explicitly selects the scoped credential; map the secret directly to `OPENAI_API_KEY` on the scan step only
- `persist-credentials: false` on checkout keeps the repository token out of Git config; install the CLI before checkout and invoke its absolute path to keep repository-controlled executables away from the scan credential
- For a persistent/self-hosted runner, use `--archive-existing` to preserve earlier results instead of failing on a non-empty output directory
- SARIF export requires GitHub Code Security enabled for private/internal repositories, and workflow permissions `actions: read`, `contents: read`, `security-events: write`
- Examples skip forked pull requests deliberately — run credentialed jobs only from a protected pipeline for trusted contributors
- The official workflow pins third-party actions to full commit SHAs (e.g. `actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7`); this page uses version tags for brevity, but pin to SHAs in a production security workflow

## Related

- [Codex Security CLI reference](./cli-reference.md)
- [Review code changes for security](./code-changes.md)

# Codex Security CLI FAQ

Answers about Codex Security scans, findings, false positives, coverage, cost, and CI.

## Signature / Usage

```bash
npx @openai/codex-security scan /path/to/repository --output-dir /path/outside/repository/codex-security-results
```

This FAQ assumes a working `@openai/codex-security` CLI install and sign-in; see [Codex Security CLI quickstart](./cli-quickstart.md) for setup and the base `scan` command.

## Repository scans

- The `@openai/codex-security` package is public; running scans requires Codex Security access
- When `OPENAI_API_KEY`/`CODEX_API_KEY` is set, scans without an interactive terminal (and JSON/JSONL scans) use the environment API key by default, even after a ChatGPT sign-in. Select explicitly with `--auth chatgpt` / `--auth api-key`. Dry runs don't prompt or load credentials
- Bulk scanning: `gh auth login` then `npx @openai/codex-security bulk-scan` (or with a CSV + `--output-dir` + `--workers`). Interrupted bulk scans resume by rerunning the same command; add `--max-attempts 3` to retry temporary errors
- Pass architecture/security-policy documents with `--knowledge-base` (repeatable)

## Findings and coverage

```bash
npx @openai/codex-security scans list /path/to/repository
npx @openai/codex-security scans show SCAN_ID
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
```

The comparison identifies new, persisting, reopened, resolved, and unknown findings. A finding counts as resolved only when the later scan covers its original target and affected path without coverage gaps.

```bash
npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"
```

Future scans receive that explanation as context but still independently recheck the current source. A dismissal doesn't suppress a rule, path, or vulnerability class.

Confirm a fix:

```bash
npx @openai/codex-security scans rerun BEFORE_SCAN_ID
npx @openai/codex-security scans match BEFORE_SCAN_ID AFTER_SCAN_ID
npx @openai/codex-security scans compare BEFORE_SCAN_ID AFTER_SCAN_ID
npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"
```

A missing finding or scan comparison alone doesn't prove a fix worked.

Coverage can be `complete`, `partial`, or `unknown`. Scans with partial/unknown coverage return exit code `2`, even without a severity policy.

## Automation and cost

```bash
npx @openai/codex-security scan . --max-cost 5
npx @openai/codex-security install-hook
npx @openai/codex-security scan . --diff origin/main --fail-on-severity high
```

`--max-cost` is an estimate, not a hard cap — in-progress requests can finish above it. A complete scan returns exit code `1` when it finds an issue at or above the selected severity.

## Notes

- AI-assisted scans can vary even with the same configuration; rerun the baseline and use `scans match`/`scans compare` to track variation — matching doesn't make scans deterministic
- Another application can run scans directly via the [TypeScript SDK](./sdk.md)

## Related

- [Codex Security CLI quickstart](./cli-quickstart.md)
- [Codex Security CLI reference](./cli-reference.md)
- [Run bulk security scans](./cli-bulk-scans.md)
- [Run Codex Security in CI](./cli-ci.md)

# Codex Security CLI quickstart

Set up the `@openai/codex-security` CLI, run a local scan, and review the report, findings, and coverage.

## Signature / Usage

Requires Node.js 22+ (and Python 3.10+ for scanning/exporting).

```bash
npm install @openai/codex-security
npx @openai/codex-security --version
npx @openai/codex-security --help
```

Sign in:

```bash
npx @openai/codex-security login              # interactive ChatGPT login
npx @openai/codex-security login --device-auth # remote/headless machine
export OPENAI_API_KEY="<your-api-key>"          # CI / automated workflows
```

Run a scan:

```bash
REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"
```

Scans default to `gpt-5.6-sol` with `xhigh` reasoning effort:

```bash
npx @openai/codex-security scan "$REPOSITORY" --model gpt-5.6-terra --effort high
```

## Results

```text
codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
```

Coverage is `complete`, `partial`, or `unknown`.

## Next scans

```bash
# path scan
npx @openai/codex-security scan "$REPOSITORY" --path services/billing --path packages/auth
# committed changes
npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD
# staged/unstaged changes
npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD
# deep mode
npx @openai/codex-security scan "$REPOSITORY" --mode deep
```

Add architecture/security context:

```bash
npx @openai/codex-security scan "$REPOSITORY" \
  --knowledge-base /path/to/architecture.md \
  --knowledge-base /path/to/security-policies
```

Pre-commit hook and bulk scans:

```bash
npx @openai/codex-security install-hook
gh auth login
npx @openai/codex-security bulk-scan
```

## Notes

- Scans are report-only by default; add `--fail-on-severity` when ready to enforce a policy in CI (see [Run Codex Security in CI](./cli-ci.md))
- If the default state directory isn't writable, set `CODEX_SECURITY_STATE_DIR` to a private directory outside the repository
- Diff and working-tree scans require the repository argument to be the Git worktree root; deep mode supports repository/path targets only

## Related

- [Codex Security CLI reference](./cli-reference.md)
- [Run bulk security scans](./cli-bulk-scans.md)
- [Run Codex Security in CI](./cli-ci.md)
- [Codex Security CLI FAQ](./cli-faq.md)
- [Codex Security TypeScript SDK](./sdk.md)

# Codex Security CLI reference

Arguments, output formats, scan artifacts, and exit codes for the `codex-security` command-line tool (`@openai/codex-security`).

## Signature / Usage

```bash
npm install @openai/codex-security
npx @openai/codex-security --help
```

## Commands

| Command | Purpose |
|---------|---------|
| `codex-security scan` | Run a Codex Security scan |
| `codex-security install-hook` | Install a Git pre-commit security scan |
| `codex-security bulk-scan` | Discover repositories and run resumable bulk scans |
| `codex-security scans` | List, inspect, match, rerun, and compare saved scans |
| `codex-security findings` | Review and update saved security findings |
| `codex-security export` | Export completed findings as CSV, JSON, or SARIF |
| `codex-security validate` | Check one or more candidate security findings |
| `codex-security patch` | Patch one or more security issues |
| `codex-security login` / `logout` | Sign in / remove stored sign-in |
| `codex-security info` | Read-only SDK and bundled-plugin metadata |
| `codex-security completions` | Generate shell completion scripts |
| `codex-security mcp` | Register the CLI as an MCP server |
| `codex-security skills` | Sync Codex Security skills to agents |

## `scan`

```text
usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]
```

`repository` defaults to the current directory.

### Target selection

| Argument | Description |
|----------|-------------|
| `--path PATH` | Scan a path relative to the repository; repeatable |
| `--diff BASE` | Scan committed changes from `BASE` to `--head` (head defaults to `HEAD`) |
| `--head HEAD` | Head revision for `--diff` |
| `--working-tree` | Scan staged/unstaged changes against `--base` (base defaults to `HEAD`) |
| `--base BASE` | Base revision for `--working-tree` |
| `--mode {standard,deep}` | Scan mode, default `standard` |

`--path`, `--diff`, `--working-tree` are mutually exclusive. Deep mode supports repository/path targets only. Diff/working-tree require the repository argument to be the Git worktree root.

### Output and policy

| Argument | Description |
|----------|-------------|
| `--output-dir DIR` | Write artifacts to a private directory outside the Git worktree (defaults to persistent Codex Security state) |
| `--archive-existing` | Move existing results to `DIR.previous-<timestamp>-<id>`; requires `--output-dir` |
| `--fail-on-severity LEVEL` | Exit `1` on a finding at/above `critical`/`high`/`medium`/`low` |
| `--max-cost USD` | Stop when estimated model cost exceeds this USD amount (estimate, not a hard cap) |
| `--dry-run` | Check inputs without starting a scan |
| `--verbose` | Redacted lifecycle/auth/progress/cost diagnostics to stderr |
| `--json` | Print manifest/findings/coverage/paths/turn metadata as one JSON document |
| `--format {toon,json,yaml,jsonl}` | Print the complete result in the given format |
| `--full-output` | Print the complete result in the default structured format |

Default result location: `$CODEX_HOME/state/plugins/codex-security/scans/<repository>` (`CODEX_HOME` defaults to `~/.codex`); override with `CODEX_SECURITY_STATE_DIR`.

### Runtime

| Argument | Description |
|----------|-------------|
| `--auth {auto,chatgpt,api-key}` | Credential selection, default `auto` |
| `--model MODEL` | Default `gpt-5.6-sol` |
| `--effort {minimal,low,medium,high,xhigh}` | Default `xhigh` |
| `--plugin-path PATH` | Override the bundled plugin (directory or ZIP) |
| `--python PATH` | Python interpreter for the plugin runtime |
| `--codex KEY=VALUE` | Override an isolated Codex config value (TOML syntax); repeatable |

## `install-hook`

```bash
npx @openai/codex-security install-hook
npx @openai/codex-security install-hook . --fail-on-severity medium
```

Scans staged/unstaged changes before each commit; blocks high-severity findings or scan errors; respects `core.hooksPath`; doesn't replace an existing pre-commit script.

## `bulk-scan`

```text
usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]
```

CSV requires `id`, `repository`, `revision` columns (full commit hash); optional `scope`, `mode`. `--workers` defaults to `4`, `--mode` to `standard`, `--max-attempts` to `1`. See [Run bulk security scans](./cli-bulk-scans.md).

## `scans`

```bash
npx @openai/codex-security scans list /path/to/repository
npx @openai/codex-security scans list --scan-root /path/outside/repository/results
npx @openai/codex-security scans show SCAN_ID
npx @openai/codex-security scans rerun SCAN_ID
npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID
npx @openai/codex-security scans match --all
```

Add `--force` to `match` to recompute an existing match. A finding is `unknown` when the later scan has incomplete coverage or doesn't cover the finding's original location.

## `findings`

```text
usage: codex-security findings false-positive OCCURRENCE_ID --reason REASON
```

```bash
npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"
```

The reason must not be empty. Saved as context for future scans; doesn't suppress a rule/path/vulnerability class.

## `export`

```text
usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir
```

| Argument | Description |
|----------|-------------|
| `--export-format {csv,json,sarif}` | Default `sarif` |
| `--output FILE\|-` | File or stdout; defaults to a file in the current directory |
| `--source-root PATH` | SARIF only — adds source-line fingerprints |
| `--python PATH` | Python interpreter for the bundled exporter |

Defaults without `--output`: `results.sarif`, `findings.json`, `findings.csv`.

## `validate` and `patch`

```bash
npx @openai/codex-security validate findings.json "Possible SQL injection in src/query.ts:42"
npx @openai/codex-security patch findings.json "Missing authorization check in src/routes.ts:18"
npx @openai/codex-security validate "Possible SQL injection" --effort high
```

Each argument can be literal text or a file path. A scan comparison alone doesn't prove a fix worked — use `validate` to recheck.

## `login`, `logout`, `info`

```bash
npx @openai/codex-security login
npx @openai/codex-security login --device-auth
npx @openai/codex-security login status
npx @openai/codex-security logout
printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key
printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token
npx @openai/codex-security info --json
```

When exposed as an MCP server, `info` is the only available command.

## Scan artifacts

```text
<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
```

| File | Contents |
|------|----------|
| `scan-manifest.json` | Identity, status, target, scope, producer, sealed artifact records |
| `findings.json` | Identifiers, severity, confidence, taxonomy, locations, evidence, validation, data flow, reachability, remediation |
| `coverage.json` | Reviewed surfaces, exclusions, deferred work, open questions, completeness |
| `report.md` | Readable scan report |

Coverage completeness: `complete`, `partial`, `unknown`.

## Exit codes and signals

| Exit | Condition |
|------|-----------|
| `0` | Success (scan passed policy with complete coverage, or another command succeeded) |
| `1` | A completed scan reports a finding at/above the configured severity |
| `2` | Input/runtime/export error, incomplete coverage, or bulk-scan repository errors |
| `130` | Ctrl-C interrupted a scan |
| `143` | SIGTERM terminated a scan |

Any scan with `partial`/`unknown` coverage returns `2`, even without a severity policy.

## Notes

- Requires Node.js 22+; scanning/exporting also requires Python 3.10+ (with `tomli` on 3.10)
- `codex-security scan --json` emits one JSON document; `codex exec --json` emits a JSON Lines event stream — these are different contracts
- Set `CODEX_SECURITY_LOG_LEVEL=debug` (or `LOG_LEVEL=debug` when unset) for the same diagnostics as `--verbose`

## Related

- [Codex Security CLI quickstart](./cli-quickstart.md)
- [Run bulk security scans](./cli-bulk-scans.md)
- [Codex Security CLI FAQ](./cli-faq.md)
- [Run Codex Security in CI](./cli-ci.md)
- [Codex Security TypeScript SDK](./sdk.md)

# Codex Security cloud FAQ

Common questions about Codex Security cloud: what it is, how it works, the analysis pipeline, validation, and threat models.

## Signature / Usage

Codex Security is an LLM-driven security analysis toolkit that inspects source code and returns structured, ranked vulnerability findings with proposed patches. It runs analysis in an ephemeral, isolated container, temporarily clones the target repository, and returns findings with description, file/location, criticality, root cause, and suggested remediation. It complements SAST rather than replacing it.

## Analysis pipeline

1. **Analysis** — builds a threat model for the repository
2. **Commit scanning** — reviews merged commits and repository history for likely issues
3. **Validation** — tries to reproduce likely vulnerabilities in a sandbox to reduce false positives
4. **Patching** — integrates with Codex to propose patches that reviewers inspect before opening a PR

## Notes

- Language-agnostic; performance depends on the model's reasoning ability for the language/framework used
- Does **not** auto-apply patches — the proposed patch is a recommended remediation users can push as a PR
- Does not require the project to build for scanning; may attempt a build inside the container during auto-validation
- A **threat model** is the scan-time security context for a repository (project overview + attack-surface details: entry points, trust boundaries, auth assumptions, risky components); editable at any time (see [Improving the threat model](./threat-model.md))
- Initial scans can take several hours to multiple days for larger repositories; later scans are usually faster (incremental)
- Does not replace manual security review, exploitability checks, or human threat assessment

## Related

- [Codex Security](./overview.md)
- [Codex Security cloud setup](./cloud-setup.md)
- [Improving the threat model](./threat-model.md)

# Codex Security cloud setup

Walks through the five-step process from initial access to reviewed findings and remediation pull requests in Codex Security cloud.

## Signature / Usage

Prerequisite: Codex cloud must already be set up.

1. **Access and environment** — confirm workspace access to Codex Security cloud and that the target repository is available in Codex cloud. Check/create an environment at `https://chatgpt.com/codex/settings/environments`.
2. **New security scan** — go to `https://chatgpt.com/codex/security/scans/new`, select GitHub organization, repository, branch, environment, and a **history window** (longer windows = more context but longer backfill).
3. **Initial scans can take a while** — Codex Security runs a commit-level security pass across the selected history window first; initial backfill can take a few hours for larger repositories or longer windows.
4. **Review scans and improve the threat model** — after the initial scan finishes, open the scan and review/update the generated threat model to match architecture, trust boundaries, and business context (see [Improving the threat model](./threat-model.md)).
5. **Review findings and patch** — use **Recommended Findings** (top-10 evolving list) or **All Findings** (sortable/filterable table); create a PR directly from a finding detail page.

## Notes

- Codex Security scans repositories from newest commits backward first
- Finding detail pages include description, metadata, contextual reasoning, code excerpts, call-path/data-flow context, and validation steps/output

## Related

- [Codex Security](./overview.md)
- [Codex Security cloud FAQ](./cloud-faq.md)
- [Improving the threat model](./threat-model.md)

# Review code changes for security

Runs a security change review to find regressions in one Git-backed change set. Codex reviews each changed source-like file and its directly supporting code; it doesn't expand into a full repository audit.

## Signature / Usage

Desktop app: **Security** → **Scans** → **+ Scan** → choose repository → **Changes** (uncommitted changes, a single commit, or a base/head revision range). **Deep scan** isn't available for a changes scan.

Conversation prompt (uncommitted changes):

```text
Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.
```

Conversation prompt (revision range):

```text
Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.
```

## CI/CD automation

```bash
npm install --global @openai/codex
codex plugin add codex-security@openai-curated
CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."
```

Output at `$TMPDIR/codex-security-scans/<repository>/<scan-id>/`: `report.md`, `findings/<slug>/`, `hardening/`, `findings.json`, `scan-manifest.json`, `coverage.json`.

## Options / Props

Key `findings.json` fields (schema at `github.com/openai/plugins` → `plugins/codex-security/schemas/findings.schema.json`):

| Name | Type | Description |
|------|------|-------------|
| `documentType` | String | `codex-security.findings` |
| `schemaVersion` | String | Findings schema version |
| `scanId` | String | Scan that produced the findings |
| `findings[].findingId` | String | Stable identifier derived from the finding fingerprint |
| `findings[].occurrenceId` | String | Identifies this occurrence in a specific scan |
| `findings[].ruleId` | String | Vulnerability family |
| `findings[].severity` | Object | Severity level and optional scoring |
| `findings[].confidence` | Object | Confidence level and rationale |
| `findings[].taxonomy` | Object | Vulnerability category and CWE identifiers |
| `findings[].locations` | Array | Affected files, line numbers, location roles |
| `findings[].remediation` | String | Recommended fix |

## Notes

- For a beta standalone CLI with structured JSON, severity policy, and SARIF upload, see [Run Codex Security in CI](./cli-ci.md); this page's CI section instead invokes the installed plugin skill via `codex exec`
- Requires `--sandbox workspace-write` so the scan can create temporary artifacts, but the prompt must still require leaving the checkout unchanged
- After reviewing results: [Fix and verify a finding](./fix-findings.md) or [Export and track findings](./export-findings.md)

## Related

- [Run a Codex Security scan](./scans.md)
- [Fix and verify security findings](./fix-findings.md)
- [Run Codex Security in CI](./cli-ci.md)

# Run a deep security scan

Run a deep scan when a more thorough review is needed and a longer runtime is acceptable. Deep scans search a repository more extensively and can reduce variability between runs.

## Signature / Usage

Conversation prompt (repository-wide):

```text
Use $codex-security:deep-security-scan to run a deep security scan of this repository.
```

Scoped to a folder in a monorepo:

```text
Use $codex-security:deep-security-scan to run a deep security scan of /absolute/path/to/repository/services/payments.
```

Desktop app: **Security** → **Scans** → **+ Scan** → choose repository/folder → **Codebase** → turn on **Deep scan**.

## Standard vs deep scan

| | Standard scan | Deep scan |
|---|---|---|
| Best for | First runs, routine review | More thorough review after a standard scan |
| Variability | Standard | Reduced |
| Runtime/resources | Lower | Higher |
| Pull requests/diffs | Use change-review workflow | Not supported; use change-review workflow instead |

## Options / Props

Configured via `~/.codex/codex-security/config.toml` (or `$CODEX_HOME/codex-security/config.toml`) under `[deep_scan]`:

| Name | Default | Description |
|------|---------|-------------|
| `workers` | `auto` | Concurrent discovery workers; positive integer or `"auto"` |
| `subagents` | `3` | Subagents each discovery worker may start; `0` disables them |
| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs with no new candidates |
| `max_discovery_runs` | `60` | Limit on discovery runs before moving to validation |

```toml
[deep_scan]
workers = 2
subagents = 0
stop_after_no_new = 3
max_discovery_runs = 10
```

## Notes

- Deep scans require delegated workers; if the runtime doesn't meet capability requirements, use a standard scan or retry later
- Lower config values reduce scan time/token use but may miss findings; config changes apply only to new deep scans
- For best scan quality, use `gpt-5.6-sol` with `xhigh` reasoning effort

## Related

- [Run a Codex Security scan](./scans.md)
- [Review code changes for security](./code-changes.md)
- [Fix and verify security findings](./fix-findings.md)

# Export and track security findings

Use a completed Codex Security scan for two handoffs: **Export** creates a portable JSON, CSV, or SARIF file; **Track findings** prepares selected findings as Linear/GitHub/Jira issues or a private draft GitHub Security Advisory (with duplicate check and approval gate). Neither changes the sealed scan bundle.

## Signature / Usage

Export prompt:

```text
Export the findings from [completed scan directory] as [JSON, CSV, or SARIF]. Do not modify the sealed scan bundle or upload its contents.
```

Track findings (Linear):

```text
Use $codex-security:track-findings to prepare finding [finding ID] from [completed scan directory] for the Linear team [team] and project [project, if any]. Check for duplicates and show me the exact issue title, body, metadata, and destination. Do not create or update anything until I approve that payload.
```

Track findings (private draft GitHub Security Advisory):

```text
Use $codex-security:track-findings to prepare finding [finding ID] from [completed scan directory] as a private draft GitHub Security Advisory in [owner/repository]. Verify the sealed source revision, repository, affected paths, package metadata, and duplicate state. Show me the exact advisory payload, authenticated GitHub CLI identity, and disclosure warnings. Do not create anything until I approve that payload.
```

## Options / Props

| Format | Use it for |
|--------|-------------|
| JSON | Preserve sealed structured findings for tools/scripts |
| CSV | Review findings and local triage state in a spreadsheet |
| SARIF | Send findings to tools supporting the SARIF interchange format |

## Notes

- `$codex-security:track-findings` accepts one validated finding or an explicitly selected batch of up to 25 from the same sealed scan; one provider/destination per run; a private draft GitHub Security Advisory accepts only one finding
- Draft advisories require: a finding from a sealed `git_revision` scan, verified public canonical source repository, and administrator access
- Jira tracking requires the Atlassian Rovo plugin; reusing an issue needs read access, creating/updating needs read+write
- Review the proposed write before approval: finding ID/fingerprint, exact destination and visibility, duplicate outcome (`create`/`reuse`/`update`/`blocked`), and complete title/body/metadata
- After approval, Codex rechecks source/destination/access/duplicate state and verifies by reading the created item back
- Exporting does not upload findings to a code-scanning service

## Related

- [Fix and verify security findings](./fix-findings.md)
- [Run a Codex Security scan](./scans.md)

# Fix and verify security findings

Turn an accepted security finding into a focused, verified patch. Codex validates the issue and, when safe and practical, adds a focused regression test that fails before the fix and passes after it.

## Signature / Usage

UI workflow (Findings or Scans → open accepted finding → **Patch** tab):

1. **Generate a focused patch** — Codex validates/reproduces the issue when feasible and writes a patch artifact without modifying the checkout
2. **Review the proposed diff** — reject broad refactors, unrelated cleanup, or changes weakening another control
3. **Apply the patch locally** — **Apply patch** applies the exact generated patch to the working tree
4. **Verify the fix** — **Verify fix** reruns the original reproducer or strongest exploit check; checks legitimate behavior and nearby bypasses
5. **Close the finding deliberately** — verification doesn't auto-close; review evidence and close with an accurate reason or keep open

CLI prompt:

```text
Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.
```

CI/CD:

```bash
codex exec --sandbox workspace-write 'Use $codex-security:fix-finding to fix finding <finding-id> from <report-path>. Validate the issue, make the smallest safe change, and add a focused regression test that fails before the fix and passes after it. If that test is unsafe or infeasible, record the proof gap and provide the strongest repeatable validation artifact instead. Verify that the issue no longer reproduces.'
```

## Notes

- Install Codex Security in the `CODEX_HOME` that `codex exec` uses before running these commands — a fresh CI runner doesn't include marketplace plugins by default
- In CI/CD, separate the change scan from remediation: preserve the completed scan directory as a job artifact, then start one Codex task/job per accepted finding
- Uses `--sandbox workspace-write`; see Non-interactive mode (`security-automation` category) for permissions/safety details
- If a regression test is unsafe/infeasible, Codex records the proof gap and provides the strongest repeatable validation artifact instead

## Related

- [Run a Codex Security scan](./scans.md)
- [Export and track security findings](./export-findings.md)
- [Triage a backlog](./triage-backlog.md)

# Codex Security

Codex Security is an application security agent that helps security and engineering teams find, confirm, and fix vulnerabilities. Use it in Codex, from your terminal, through the TypeScript SDK, or with connected GitHub repositories.

## Signature / Usage

Available through four surfaces:

- **Desktop app plugin** — `Security` sidebar with Scans, Findings, and Repositories views (see [Security workbench](./workbench.md))
- **CLI and TypeScript SDK** — public `@openai/codex-security` npm package
- **Codex Security cloud** — scans connected GitHub repositories through Codex cloud (research preview)

```bash
npm install @openai/codex-security
```

Running scans requires Codex Security access. For best results, use an account verified for Trusted Access for Cyber (https://chatgpt.com/cyber).

## How Codex Security cloud works

Codex Security cloud scans connected repositories commit by commit. It builds scan context from the repo, checks likely vulnerabilities against that context, and validates high-signal issues in an isolated environment before surfacing them:

1. **Find likely vulnerabilities** using a repo-specific threat model and real code context
2. **Reduce noise** by validating findings before review
3. **Move findings toward fixes** with ranked results, evidence, and suggested patch options

## Notes

- Codex Security cloud works with connected GitHub repositories through Codex cloud; if a repository isn't visible, confirm it is available in your Codex cloud workspace
- Codex Security (this product family) is distinct from Codex's built-in approvals / sandbox / network controls, which are covered separately (see `security-automation` category, e.g. Agent approvals & security)

## Related

- [Codex Security plugin quickstart](./plugin-quickstart.md)
- [Codex Security CLI quickstart](./cli-quickstart.md)
- [Codex Security TypeScript SDK](./sdk.md)
- [Codex Security cloud setup](./cloud-setup.md)

# Codex Security plugin changelog

Notable user-facing changes to the Codex Security plugin, by version. Latest release in the hosted Codex Security catalog: `0.1.17`.

## Signature / Usage

Check the plugin version in the current Codex environment before relying on a feature from a newer release. Reopening or rerunning a saved scan doesn't pin the installed plugin version. Versions apply to the Codex Security plugin only — the Codex app, Codex CLI, TypeScript SDK, and plugin app have separate version numbers.

## Notable versions

| Version | Date | Highlights |
|---------|------|-----------|
| 0.1.17 | 2026-08-05 | Live scan progress view; resumable interrupted deep scans; native scan start/completion without the retired embedded widget |
| 0.1.16 | 2026-08-04 | Measured token usage reporting; unified threat-modeling/discovery/validation/attack-path/reporting phases for standard and deep scans; configurable deep-scan workers |
| 0.1.15 | 2026-07-30 | Persistent scan lifecycle metadata; false-positive feedback for completed scans; nested Git repository support in scan snapshots |
| 0.1.14 | 2026-07-28 | Scan history filtering/comparison (new/persisting/resolved/not-rescanned); `SECURITY.md` policy support via `$codex-security:define-security-policy`; select up to 25 findings for Linear/GitHub Issues tracking |
| 0.1.13 | 2026-07-25 | Findings kept for local/internal/training-only/non-production code, calibrated by deployment/exposure context instead of auto-suppression |
| 0.1.12 | 2026-07-23 | Repository-wide/directory-scoped deep scans with worker coordination; scan reopen/rerun; SARIF/JSON/CSV export |
| 0.1.11 | 2026-07-10 | Per-finding vulnerability reports and structural hardening portfolio (`findings/`, `hardening/`); `$codex-security:vulnerability-writeup` and `$codex-security:propose-security-hardening` skills; `SECURITY.md` guidance support |
| 0.1.10 | 2026-06-23 | Improved Jira/Linear ticket intake with duplicate detection |
| 0.1.9 | 2026-06-18 | Findings workspace (coverage, severity, confidence, artifacts); JSON/CSV/SARIF export; backlog triage against scanners, advisories, bug bounty reports |
| 0.1.7 | 2026-06-04 | Initial evidence-backed security review workflow: repository/folder scans, PR/commit/branch diff review, threat modeling → discovery → validation → impact analysis → reporting, focused fix generation |

## Notes

- This changelog covers the plugin only, distinct from the CLI/SDK package version (`@openai/codex-security`)

## Related

- [Codex Security plugin quickstart](./plugin-quickstart.md)
- [Use the Codex Security workbench](./workbench.md)

# Codex Security plugin quickstart

Install the Codex Security plugin, run your first read-only scan, and review the result in Codex (desktop app or CLI).

## Signature / Usage

Install (desktop app): open **Plugins**, search for **Codex Security**, install, then open **Security** in the sidebar.

Install (CLI):

```bash
codex
```

Then `/plugins` → search **Codex Security** → **Install plugin** → `/new` to start a new chat for the repository.

Run a scan (CLI conversation prompt):

```text
Run a Codex Security scan on this repository.
```

For best scan quality, use `gpt-5.6-sol` with `xhigh` reasoning effort.

## What the scan creates

- `report.md` — primary readable entry point
- `findings/<slug>/` — detailed vulnerability reports and PoC files, when available
- `hardening/` — structural hardening guidance, when available
- `scan-manifest.json`, `findings.json`, `coverage.json` — structured data for automation

## Notes

- This page covers the plugin in the desktop app / Codex CLI; for connected GitHub repositories in Codex cloud, see [Codex Security cloud setup](./cloud-setup.md)
- The hosted desktop-app catalog and public Codex CLI marketplace can offer different plugin versions — check the [plugin changelog](./plugin-changelog.md) before relying on a feature

## Related

- [Use the Codex Security workbench](./workbench.md)
- [Run a Codex Security scan](./scans.md)
- [Run a deep security scan](./deep-scans.md)
- [Review code changes for security](./code-changes.md)

# Security

| Name | Description | Path |
|------|-------------|------|
| Run bulk security scans | Discover GitHub repositories or run resumable security scans from a CSV inventory using `npx @openai/codex-security bulk-scan`. | [cli-bulk-scans.md](./cli-bulk-scans.md) |
| Run Codex Security in CI | Scan pull-request changes, preserve structured results, upload SARIF, and set a severity policy using the `@openai/codex-security` CLI. | [cli-ci.md](./cli-ci.md) |
| Codex Security CLI FAQ | Answers about Codex Security scans, findings, false positives, coverage, cost, and CI. | [cli-faq.md](./cli-faq.md) |
| Codex Security CLI quickstart | Set up the `@openai/codex-security` CLI, run a local scan, and review the report, findings, and coverage. | [cli-quickstart.md](./cli-quickstart.md) |
| Codex Security CLI reference | Arguments, output formats, scan artifacts, and exit codes for the `codex-security` command-line tool (`@openai/codex-security`). | [cli-reference.md](./cli-reference.md) |
| Codex Security cloud FAQ | Common questions about Codex Security cloud: what it is, how it works, the analysis pipeline, validation, and threat models. | [cloud-faq.md](./cloud-faq.md) |
| Codex Security cloud setup | Walks through the five-step process from initial access to reviewed findings and remediation pull requests in Codex Security cloud. | [cloud-setup.md](./cloud-setup.md) |
| Review code changes for security | Runs a security change review to find regressions in one Git-backed change set. Codex reviews each changed source-like file and its directly supporting code; it doesn't expand into a full repository audit. | [code-changes.md](./code-changes.md) |
| Run a deep security scan | Run a deep scan when a more thorough review is needed and a longer runtime is acceptable. Deep scans search a repository more extensively and can reduce variability between runs. | [deep-scans.md](./deep-scans.md) |
| Export and track security findings | Use a completed Codex Security scan for two handoffs: **Export** creates a portable JSON, CSV, or SARIF file; **Track findings** prepares selected findings as Linear/GitHub/Jira issues or a private draft GitHub Security Advisory (with duplicate check and approval gate). Neither changes the sealed scan bundle. | [export-findings.md](./export-findings.md) |
| Fix and verify security findings | Turn an accepted security finding into a focused, verified patch. Codex validates the issue and, when safe and practical, adds a focused regression test that fails before the fix and passes after it. | [fix-findings.md](./fix-findings.md) |
| Codex Security | Codex Security is an application security agent that helps security and engineering teams find, confirm, and fix vulnerabilities. Use it in Codex, from your terminal, through the TypeScript SDK, or with connected GitHub repositories. | [overview.md](./overview.md) |
| Codex Security plugin changelog | Notable user-facing changes to the Codex Security plugin, by version. Latest release in the hosted Codex Security catalog: `0.1.17`. | [plugin-changelog.md](./plugin-changelog.md) |
| Codex Security plugin quickstart | Install the Codex Security plugin, run your first read-only scan, and review the result in Codex (desktop app or CLI). | [plugin-quickstart.md](./plugin-quickstart.md) |
| Run a Codex Security scan | Start with a standard scan for an initial review or routine repository/component assessment; it runs the full scan workflow once. | [scans.md](./scans.md) |
| Codex Security TypeScript SDK | Run Codex Security scans from TypeScript, select targets, inspect results, and manage scan lifecycle via `@openai/codex-security`. ESM, Node.js 22+ (scanning also requires Python 3.10+). | [sdk.md](./sdk.md) |
| Propose security hardening | Use `$codex-security:propose-security-hardening` to turn security evidence into structural or architectural hardening options. Analyzes a completed Codex Security scan or supplied findings, disclosure reports, incident reviews, assessment documents, and source code. | [security-hardening.md](./security-hardening.md) |
| Security Review | Research preview. Automatic or on-demand security review of a GitHub pull request diff, run alongside (or independently of) general Code Review — analyzes the PR diff, supporting repository context, and configured threat model for security-specific risks. Available to Enterprise, Business, Edu, and Pro workspaces; not available on Plus. | [security-review.md](./security-review.md) |
| Improving the threat model | Explains what a threat model is in Codex Security cloud and how editing it improves scan results and prioritization. | [threat-model.md](./threat-model.md) |
| Triage a backlog | Use `$codex-security:triage-finding` to review existing security findings against the current repository. This is a read-only static analysis: Codex treats each finding as an unproven claim and inspects repository evidence without executing code. | [triage-backlog.md](./triage-backlog.md) |
| Write vulnerability reports | Use `$codex-security:vulnerability-writeup` to create a self-contained report for each distinct vulnerability, from Codex Security scan results or supplied findings, disclosure notes, PoCs, and source code directly. A Codex Security scan isn't required. | [vulnerability-reports.md](./vulnerability-reports.md) |
| Use the Codex Security workbench | The Security workbench brings scans, findings, and repositories together in the Codex desktop app. Codex performs scan analysis in a regular task, while the workbench keeps results available on return. | [workbench.md](./workbench.md) |

# Run a Codex Security scan

Start with a standard scan for an initial review or routine repository/component assessment; it runs the full scan workflow once.

## Signature / Usage

Desktop app: **Security** → **Scans** → **+ Scan** → choose repository/folder → **Codebase**.

Conversation prompt:

```text
Use $codex-security:security-scan to scan this repository for security vulnerabilities.
```

Scoped to a folder:

```text
Use $codex-security:security-scan to scan this repository for security vulnerabilities, focusing on the services/billing component.
```

## Scan phases

1. **Threat modeling** — assets, entry points, trust boundaries, security invariants
2. **Finding discovery** — plausible broken controls and source-to-sink paths
3. **Validation** — tests/checks each candidate, records evidence or proof gaps
4. **Impact and path analysis** — realistic paths, impact, severity
5. **Reporting** — validated findings, coverage, scan metadata (detailed per-finding reports are optional for standard scans)
6. **Structural hardening** (when available) — design guidance from the finding set
7. **Finalization** — validates the structured scan contract, generates `report.md`

## Notes

- Add `SECURITY.md` (repo root, or nested for directory-specific guidance) for persistent security guidance: threat model, invariants, reportable-finding criteria, exclusions, severity context. The closest file to the code takes precedence. Treated as policy context, not executable instructions
- Use `AGENTS.md` for supported build/validation commands
- For a more thorough assessment after reviewing standard-scan results, use a [deep scan](./deep-scans.md)

## Related

- [Run a deep security scan](./deep-scans.md)
- [Fix and verify security findings](./fix-findings.md)
- [Export and track security findings](./export-findings.md)

# Codex Security TypeScript SDK

Run Codex Security scans from TypeScript, select targets, inspect results, and manage scan lifecycle via `@openai/codex-security`. ESM, Node.js 22+ (scanning also requires Python 3.10+).

## Signature / Usage

```ts
import { CodexSecurity } from "@openai/codex-security";

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}
```

`run` starts the scan, waits for completion, validates sealed artifacts, and returns a `ScanResult`. `close` releases the isolated runtime.

## Preflight

```ts
const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  outputDir: "/path/outside/repository/results",
});
```

Leaves the Codex runtime, credentials, and plugin/Python discovery untouched — useful for validating user input before a credentialed operation.

## Scan targets

```ts
// selected paths
await security.run(repo, { target: ["services/billing", "packages/auth"] });

// committed changes
const target = DiffTarget.refs({ base: "origin/main", head: "HEAD" });
await security.run(repo, { target });

// working tree
const wt = DiffTarget.workingTree({ base: "HEAD" });
await security.run(repo, { target: wt });

// deep mode (repository/path targets only)
await security.run(repo, { target: ["services/billing"], mode: "deep" });
```

## Options / Props

`ScanOptions` (selected):

| Name | Type | Description |
|------|------|-------------|
| `outputDir` | string | Private results directory outside the Git worktree |
| `target` | string[] \| DiffTarget | Paths or a diff/working-tree target |
| `mode` | `"standard"` \| `"deep"` | Scan mode |
| `knowledgeBasePaths` | string[] | Architecture/threat-model/policy files or directories (`.md`, `.markdown`, `.txt`, `.pdf`, `.docx`) |
| `maxCostUsd` | number | Estimated cost limit; throws `ScanCostLimitExceededError` when exceeded |
| `auth` | `"chatgpt"` \| `"api-key"` | Explicit credential selection |
| `archiveExisting` | boolean | Archive existing output directory before starting |
| `signal` | AbortSignal | Cancellation |
| `onScanStarted` / `onWorkerStatus` / `onReconnect` / `onCost` / `onOutputArchived` / `onOutputDirReady` / `onObserverError` | function | Lifecycle callbacks |

`ScanResult` (selected):

| Property | Contents |
|----------|----------|
| `manifest` | Sealed scan manifest |
| `findings` | Findings document (`findings.findings`) |
| `coverage` | Reviewed surfaces, exclusions, deferred work, completeness |
| `scanDir` / `reportPath` / `manifestPath` / `findingsPath` / `coveragePath` / `artifactsDir` / `sarifPath` | Artifact paths |
| `threadId` / `turnResult` | Codex task metadata |
| `cost` | Estimated cost or `null` |
| `pluginVersion` | Scan producer version |

`result.toJSON()` returns a JSON-ready object with manifest, findings, coverage, identifiers, `reportPath`, `artifactsDir`, `sarifPath`, and turn metadata.

## Runtime configuration and authentication

```ts
const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-5.6-terra",
    model_reasoning_effort: "high",
  },
});
```

Auth methods: `loginApiKey(apiKey)`, `loginChatGPT()`, `loginChatGPTDeviceCode()`, `account()`, `logout()`. Default model is `gpt-5.6-sol` with `xhigh` reasoning effort. When both an API key and stored sign-in exist, the SDK uses the API key by default; pass `auth: "chatgpt"` to override.

## Notes

- Error classes to catch: `AuthenticationRequiredError`, `ConfigurationError`, `InvalidTargetError`, `OutputDirectoryError`, `OutputInsideProtectedRootError`, `PluginPythonUnavailableError`, `PluginBootstrapError`, `ScanCostLimitExceededError`, `IncompleteScanError`, `ContractValidationError`, `ScanInterruptedError`
- An interrupted scan can leave partial output in `scanDir` — preserve it for investigation
- Publicly available on GitHub at `github.com/openai/codex-security`; running scans requires Codex Security access
- For general coding agents (not security-specific), see the separate Codex SDK guide in `security-automation`

## Related

- [Codex Security CLI quickstart](./cli-quickstart.md)
- [Codex Security CLI reference](./cli-reference.md)
- [Run Codex Security in CI](./cli-ci.md)

# Propose security hardening

Use `$codex-security:propose-security-hardening` to turn security evidence into structural or architectural hardening options. Analyzes a completed Codex Security scan or supplied findings, disclosure reports, incident reviews, assessment documents, and source code.

## Signature / Usage

```text
Use $codex-security:propose-security-hardening to analyze [scan directory or finding paths] against [source tree and revision]. Develop evidence-backed structural hardening options with engineering tradeoffs, before-and-after diagrams, a migration plan, and an implementation handoff. Do not modify the repository.
```

The result is a design portfolio, not a patch — it doesn't prove that it fixes a vulnerability. Codex changes the repository only after an option is selected and Codex is explicitly asked to make the change.

## Notes

- Provide: scan directory or explicit findings/reports, target source tree and revision, PoCs/traces/incident evidence, and constraints (performance, memory, compatibility, reliability, operations, delivery time, change scope)
- Can conclude that local fixes are more proportionate than an architectural change
- When a scan has reportable findings, Codex runs this workflow once after detailed vulnerability reports are ready, writing `hardening/hardening.md` (portfolio), `hardening/hardening.json` (structured analysis), and supporting proposals/diagrams under `hardening/`, linked from `report.md`

## Related

- [Write vulnerability reports](./vulnerability-reports.md)
- [Run a deep security scan](./deep-scans.md)

# Security Review

Research preview. Automatic or on-demand security review of a GitHub pull request diff, run alongside (or independently of) general Code Review — analyzes the PR diff, supporting repository context, and configured threat model for security-specific risks. Available to Enterprise, Business, Edu, and Pro workspaces; not available on Plus.

## Signature / Usage

Request manually by commenting on a pull request:

```text
@codex security review
```

## Options / Props

| Name | Description |
|------|-------------|
| Repository preferences | **Follow personal** (each contributor opts in), **Review all PRs**, or **Review team PRs** (ChatGPT workspace members). |
| Trigger | **On PR open**, **Every push**, or **Whenever code review runs** (requires Code Review enabled). |
| Threat-model context | Reuses an existing Codex Security scan's threat model, or a repository-checked-in threat model file; regenerated per review if unset. |
| Reporting threshold | Default: automatic reviews post **High**/**Critical**; manual reviews post **Medium**/**High**/**Critical**. Configurable independently per trigger type, with path-based overrides. |

## Notes

- Configure under **Codex settings > Repository preferences** at `chatgpt.com/codex/settings/code-review`; requires Codex cloud with a connected GitHub repository and GitHub push/admin permission.
- Findings posted to a PR inherit that PR's GitHub visibility — anyone who can view the PR (including public repos and outside contributors) can view them. The reporting threshold only controls what's posted to GitHub; the full report stays in the Codex task's **Security Report** tab.
- Distinct from [Review code changes for security](./code-changes.md): that page's `security-diff-scan` conversation prompt / CI invocation is a manually-triggered plugin skill run via `codex exec` or the desktop app's Scans flow, scoped to whatever diff you point it at. Security Review is GitHub-PR-native, can run automatically on push/open, and posts findings as PR comments directly.
- Code Review (general, non-security) can already surface security-related issues, so some overlap between the two is expected.

## Related

- [Review code changes for security](./code-changes.md)
- [Codex Security](./overview.md)
- [Codex Security cloud setup](./cloud-setup.md)
- [Improving the threat model](./threat-model.md)

# Improving the threat model

Explains what a threat model is in Codex Security cloud and how editing it improves scan results and prioritization.

## Signature / Usage

A threat model is a short security summary of how a repository works, edited as a `project overview`, used as scan context for future scans, prioritization, and review. Codex Security creates the first draft from the code.

A useful threat model calls out:

- entry points and untrusted inputs
- trust boundaries and auth assumptions
- sensitive data paths or privileged actions
- the areas the team wants reviewed first

Example:

> Public API for account changes. Accepts JSON requests and file uploads. Uses an internal auth service for identity checks and writes billing changes through an internal service. Focus review on auth checks, upload parsing, and service-to-service trust boundaries.

Edit the threat model at `https://chatgpt.com/codex/security/scans` → open repository → **Edit**.

## Notes

- Edit when findings are missing areas you care about or showing up in unexpected places
- Threat model changes affect **future** scan context only

## Related

- [Codex Security cloud setup](./cloud-setup.md)
- [Codex Security](./overview.md)
- [Codex Security cloud FAQ](./cloud-faq.md)

# Triage a backlog

Use `$codex-security:triage-finding` to review existing security findings against the current repository. This is a read-only static analysis: Codex treats each finding as an unproven claim and inspects repository evidence without executing code.

## Signature / Usage

Pasted or local findings:

```text
Use $codex-security:triage-finding to triage these existing security findings against this repository:

[Paste the findings or provide the artifact path.]
```

Jira/Linear:

```text
Use $codex-security:triage-finding to import and triage the security findings from [Jira or Linear issue URLs, identifiers, or query] against this repository.
Do not change the source issues.
```

GitHub:

```text
Use $codex-security:triage-finding to import and triage [code scanning, Dependabot vulnerabilities and malware, security advisories and private vulnerability reports, or all] from [owner/repository] against this repository.
```

## Options / Props

Finding sources:

| Source | What to provide | Requirements |
|--------|------------------|---------------|
| Pasted/local | SARIF, CVE/GHSA, advisory, scanner ticket, bug bounty report, Codex Security finding artifact, plain-language claim | None |
| Jira/Linear | Issue URLs/identifiers, JQL, or team/project/search phrase | Jira via Atlassian Rovo or Linear connector with read access |
| GitHub | Repository + finding source (code scanning, Dependabot, advisories/private vulnerability reports, or all) | Authenticated GitHub REST access (`gh auth token`, `GH_TOKEN`, `GITHUB_TOKEN`) |

Verdicts:

| Verdict | Meaning |
|---------|---------|
| `confirmed` | Repository evidence shows the path is reachable under stated preconditions and crosses a supported security boundary |
| `not_actionable` | Repository evidence rules out the claim (unaffected version, unreachable path, effective guard, non-shipped surface) |
| `needs_review` | Evidence insufficient — missing, ambiguous, runtime/environment/policy-dependent |

`confirmed` and `needs_review` findings are ranked separately by exploitability (positive integers starting at 1); `not_actionable` findings aren't ranked.

## Notes

- Differs from `$codex-security:validation`, which can build/run code or exercise a real interface to reproduce/disprove a finding — triage classifies/ranks an existing backlog, validation resolves proof gaps with runtime evidence
- Doesn't modify the repository, implement fixes, or automatically write back to source tickets
- `confirmed` findings hand off to [`$codex-security:fix-finding`](./fix-findings.md) after a person accepts remediation

## Related

- [Run a Codex Security scan](./scans.md)
- [Fix and verify security findings](./fix-findings.md)

# Write vulnerability reports

Use `$codex-security:vulnerability-writeup` to create a self-contained report for each distinct vulnerability, from Codex Security scan results or supplied findings, disclosure notes, PoCs, and source code directly. A Codex Security scan isn't required.

## Signature / Usage

```text
Use $codex-security:vulnerability-writeup to create one self-contained report for each distinct vulnerability in [input paths]. Verify the claims against [source path and revision], preserve or improve the supplied PoCs, and write the reports to [output directory]. Do not test public or production systems.
```

Codex inventories the supplied material, groups reports describing the same root cause/vulnerable path, and creates one report directory per distinct vulnerability (Markdown report + optional `poc/` directory).

## Notes

- Provide: findings/disclosure notes/assessment documents, target source tree and affected revision, existing PoCs/logs/traces, fix commits/diffs, and the authorization boundary for testing
- Never test a public or production target without explicit authorization for that exact target
- When a deep or change scan has reportable findings, Codex runs this workflow once per finding during final reporting; reports for standard scans are optional. Output: `findings/<slug>/<slug>.md` with supporting files under `findings/<slug>/poc/`, linked from `report.md`

## Related

- [Run a deep security scan](./deep-scans.md)
- [Propose security hardening](./security-hardening.md)

# Use the Codex Security workbench

The Security workbench brings scans, findings, and repositories together in the Codex desktop app. Codex performs scan analysis in a regular task, while the workbench keeps results available on return.

## Signature / Usage

Install and enable the [Codex Security plugin](./plugin-quickstart.md), then select **Security** in the desktop-app sidebar.

Start a scan: **Scans** → **+ Scan** → select repository/folder → choose **Codebase** (full or deep scan) or **Changes** (Git-backed diff review; deep scan unavailable) → choose model/reasoning effort → optionally add **Additional context** → **Start scan**.

For best scan quality, use `gpt-5.6-sol` with `xhigh` reasoning effort.

## Views

| View | Purpose |
|------|---------|
| Scans | Start scans, follow progress (`View activity` opens the underlying Codex task), review saved results |
| Findings | Inspect issues and evidence across completed scans; `Summary` and `Patch` tabs |
| Repositories | Browse repositories/folders, scan history, latest revision, open findings |

## Notes

- The **Findings** tab shows findings from saved Codex Security scans only; imported tickets belong to the separate [backlog triage workflow](./triage-backlog.md)
- Scans can also be started from a regular Codex conversation; they still appear in **Scans**

## Related

- [Codex Security plugin quickstart](./plugin-quickstart.md)
- [Run a Codex Security scan](./scans.md)
- [Run a deep security scan](./deep-scans.md)
- [Fix and verify security findings](./fix-findings.md)

# Review GitHub pull requests with Codex

Codex code review posts a standard GitHub code review on pull requests, following repository guidance from `AGENTS.md`; Security Review adds an in-depth pass on security issues (research preview).

## Signature / Usage

```md
# In a pull request comment
@codex review

# Focus a review
@codex review for issues in the database migration

# Request a deeper security pass
@codex security review

# Act on findings
@codex fix the P1 issue

# Any other mention starts a cloud chat with the PR as context
@codex fix the CI failures
```

## Set up

1. Set up [Codex cloud](../getting-started/cloud.md) for the repository.
2. Go to Codex settings (`chatgpt.com/codex/settings/code-review`) and turn on **Code review**. Requires GitHub push or admin permission on the repo.
3. (Optional) Turn on **Automatic reviews** to post a review on every new pull request without an `@codex review` comment.

## Customize review rules

Codex searches the repository for `AGENTS.md` files and follows the applicable `## Code Review Rules` section (use `###` subheadings to group checks). Root `AGENTS.md` holds repo-wide rules; nested `AGENTS.md` (e.g. `services/experiment_reporting/AGENTS.md`) holds service-specific rules — Codex applies both root and the most-specific match per changed file.

```md
## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.
```

## Notes

- In GitHub, Codex flags only P0/P1 issues so comments stay focused on high-priority risks.
- Security Review is a separate, deeper pass (`@codex security review`); results appear in the associated Codex task's **Security Report** tab. Configuration and threat models are documented on the `security` category's Security Review page, not here.
- Code review rules guide Codex; they do not replace tests, branch protections, or required approvals. Keep deterministic checks (formatting, lint) in CI, not in review rules.
- This is the GitHub **pull request review** integration (Codex commenting on PRs). It is distinct from the `security-automation/github-action.md` page, which covers `openai/codex-action@v1` — a GitHub Actions step that runs `codex exec` inside a CI job.

## Related

- [Codex cloud](../getting-started/cloud.md)
- [Codex GitHub Action](../security-automation/github-action.md)

# Use Codex in Linear

Delegate work from Linear issues: assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud chat and replies with progress and results. Available on paid plans.

## Signature / Usage

```md
# In a Linear issue comment thread
@Codex fix this in openai/codex

# CLI: connect Linear MCP for local access to issues
codex mcp add linear --url https://mcp.linear.app/mcp
```

```toml
# ~/.codex/config.toml (manual MCP setup)
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
```

## Set up the Linear integration

1. Set up [Codex cloud chats](../getting-started/cloud.md): connect GitHub in Codex and create an environment for the target repository.
2. Go to Codex settings (`chatgpt.com/codex/settings/connectors`) and install **Codex for Linear** for the workspace.
3. Link the Linear account by mentioning `@Codex` in a comment thread on a Linear issue.
4. Enterprise plans: a workspace admin must turn on Codex cloud chats and enable **Codex for Linear** in connector settings.

## Delegate work to Codex

- **Assign an issue to Codex** the same way issues are assigned to teammates; Codex starts work and posts updates back to the issue.
- **Mention `@Codex` in comments** to delegate work or ask questions; follow up in the thread to continue the same chat.
- Pin a specific repo by naming it in the comment, e.g. `@Codex fix this in openai/codex`.
- **Automatic assignment**: in Linear, Settings > team > Triage, turn on Triage and add a rule with **Delegate > Codex**. Codex then runs chats using the account of the issue creator.

### How Codex chooses an environment and repo

Linear suggests a repository from issue context; Codex picks the environment that best matches, falling back to the most recently used environment if ambiguous. The chat runs against the default branch of the first repository listed in that environment's repo map.

## Notes

- `codex mcp add linear` / the `[mcp_servers.linear]` block here is Linear's own remote MCP server for **local** Codex (CLI/IDE/desktop app) access to issues — a specific server instance, distinct from the general MCP client configuration mechanism documented in `config/mcp-config.md`.
- Data handling for `@Codex` mentions follows OpenAI's Privacy Policy and Terms of Use; see the security-automation category for Codex's own security model.

## Related

- [Codex cloud](../getting-started/cloud.md)
- [MCP server configuration](../config/mcp-config.md)
- [Use Codex in Slack](./slack.md)

# third-party

| Name | Description | Path |
|------|-------------|------|
| Review GitHub pull requests with Codex | Codex code review posts a standard GitHub code review on pull… | [github.md](./github.md) |
| Use Codex in Linear | Delegate work from Linear issues: assign an issue to Codex or… | [linear.md](./linear.md) |
| Use Codex in Slack | Kick off coding work from Slack channels and threads: mention… | [slack.md](./slack.md) |

# Use Codex in Slack

Kick off coding work from Slack channels and threads: mention `@Codex` with a prompt, and Codex creates a cloud chat and replies with results.

## Signature / Usage

```md
# In a Slack channel or thread
@Codex fix the above in openai/codex
```

## Set up the Slack app

1. Set up [Codex cloud chats](../getting-started/cloud.md). Requires a Plus, Pro, Business, Enterprise, or Edu plan, a connected GitHub account, and at least one environment.
2. Go to Codex settings (`chatgpt.com/codex/settings/connectors`) and install the Slack app for the workspace (a Slack admin may need to approve, depending on workspace policy).
3. Add `@Codex` to a channel (Slack prompts to add it on first mention if not already present).

## Start a chat

1. In a channel or thread, mention `@Codex` with a prompt; Codex can reference earlier thread messages for context.
2. Optionally specify an environment/repository in the prompt, e.g. `@Codex fix the above in openai/codex`.
3. Codex reacts (👀), then replies with a link to the chat and, depending on settings, an answer in the thread when finished.

### How Codex chooses an environment and repo

Codex reviews accessible environments and selects the best match for the request, falling back to the most recently used environment if ambiguous. The chat runs against the default branch of the first repository listed in that environment's repo map.

### Enterprise data controls

By default Codex posts an answer in the thread, which can include information from the run environment. An Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in workspace settings so Codex replies only with a chat link.

## Notes

- Data handling for `@Codex` mentions (message + thread history) follows OpenAI's Privacy Policy and Terms of Use; see the security-automation category for Codex's own security/approval model.
- Distinct from the GitHub Action / non-interactive automation surfaces: this integration is triggered by chat mentions, not CI events.

## Related

- [Codex cloud](../getting-started/cloud.md)
- [Use Codex in Linear](./linear.md)

# Create a CLI Codex can use

Give Codex a composable command for an API, log source, export, or team script.

```text
Use $cli-creator to create a CLI you can use, and use $skill-creator to create the companion skill in this same chat.

Source to learn from: [docs URL, OpenAPI spec, redacted curl command, existing script path, log folder, CSV or JSON export, SQLite database path, or pasted --help output].

First job the CLI should support: [download failed CI logs from a build URL, search support tickets and read one by ID, query an admin API, read a local database, or run one step from an existing script].

Optional write job: [create a draft comment, upload media, retry a failed job, or read-only for now].

Command name: [cli-name, or recommend one].

Before coding, show me the proposed command surface and ask only for missing details that would block the build.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `$cli-creator` designs the command surface, installs the command on PATH, and verifies it from another folder
- The companion skill built with `$skill-creator` teaches future Codex tasks which CLI commands to run first and which write actions require approval
- Best for: repeated work against the same service, export, or repo script; agent tools needing paged search, exact reads by ID, or draft-before-write commands

# Add evals to your AI application

Use Codex to turn expected behavior into a Promptfoo eval suite.

```text
Use $promptfoo-evals to add a Promptfoo eval suite for this AI application. If there is not already a working Promptfoo provider or target adapter, use $promptfoo-provider-setup first.

Behavior to evaluate: [support answer quality / tool-call correctness / retrieval grounding / business rules / agent task completion]

Before editing:
- Inspect the app path users hit and any existing evals or tests.
- Propose the smallest useful eval plan: target adapter, seed cases, assertions, files, commands, and required env vars or local services.
- Do not change production prompts, model settings, or app behavior until the baseline eval exists and has been run.

Requirements:
- Exercise the application path users hit when possible, not only the raw model prompt.
- Keep fixtures free of secrets, customer data, and sensitive personal data.
- Add a local eval command such as `npm run evals` or document the exact command to run.

Finish with:
- Files changed
- Eval commands run
- Passing and failing cases
- Recommended next evals to add
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: medium`. Uses the Promptfoo plugin (`$promptfoo-evals` / `$promptfoo-provider-setup`)
- Best for: AI applications with prompts, model calls, tools, retrieval, or agents but no repeatable eval suite; regression tests before a model/prompt/retrieval change merges

# Automate bug triage

Turn daily bug reports into a prioritized list, then automate the sweep.

```text
Run a bug triage sweep for [repo/service/team] covering the last [time window].

Use these plugins: [@Sentry / @Slack / @Linear / @GitHub / none]

Input sources:
- Sentry: [project / alert link / none]
- Slack: [channel / thread links / none]
- Linear: [team / project / view / issue query / none]
- GitHub: [repo / issue query / PR checks / none]
- Other: [logs / support tickets / deploy link / dashboard / attached file / none]

Output format:
First, name any input source you could not access.
Then return a prioritized list of bugs, sorted from P0 to P3.
If you find no bugs, say: No qualifying bugs found.

For each bug, include:
- Priority: P0, P1, P2, or P3
- Title
- Evidence (links or short citations)
- Recommended next action

Rules:
- Do not post, create, assign, label, close, rerun, or edit anything.
- Group duplicate reports under one bug.
- Keep observed evidence separate from guesses.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). Uses the GitHub, `$sentry`, Slack, and Linear plugins to sweep bug sources
- A manual, one-shot triage chat can graduate into a Scheduled task (https://learn.chatgpt.com/codex/automations) for recurring runs
- For internal sources with no existing plugin, use Codex MCP (https://learn.chatgpt.com/codex/extend/mcp) to wire up a small MCP server or CLI

# Run code migrations

Migrate legacy stacks in controlled checkpoints.

```text
Migrate this codebase from [legacy stack or system] to [target stack or system].

Requirements:
- Start by inventorying the legacy assumptions: routing, data models, auth, configuration, build tooling, tests, deployment, and external contracts.
- Map the old stack to the new one and call out anything that has no direct equivalent.
- Propose an incremental migration plan with compatibility layers or checkpoints instead of one big rewrite.
- Keep behavior unchanged unless the migration explicitly requires a user-visible change.
- Work in milestones and run lint, type-check, and focused tests after each milestone.
- Keep rollback or fallback options visible until the transition is complete.
- If validation fails, fix it before continuing.
- Start by mapping the migration surface and proposing the checkpoint plan.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). Can be paired with `$security-best-practices`, `$gh-fix-ci`, and framework-specific skills such as `$aspnet-core`
- Best for: legacy-to-modern stack moves where frameworks, runtimes, build systems, or platform conventions change; teams needing compatibility layers and checkpoint validation
- Combine with Follow a goal (`follow-goals.md`) and Git worktrees (https://learn.chatgpt.com/codex/environments/git-worktrees) for long-running, milestone-based execution

# Understand large codebases

Trace request flows, map unfamiliar modules, and find the right files fast.

```text
Explain how the request flows through <name of the system area> in the codebase.

Include:
- which modules own what
- where data is validated
- the top gotchas to watch for before making changes

End with the files I should read next.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedModel: gpt-5.3-codex-spark`, `suggestedEffort: medium`
- Best for: new engineers onboarding to a repo or service, anyone trying to understand how a feature works before changing it
- Related: ChatGPT desktop app (https://learn.chatgpt.com/codex/app)

# Run a deep security scan

Search an authorized repository deeply for plausible vulnerabilities.

```text
Use $codex-security:deep-security-scan to run a deep security scan on [this repository / absolute path to a scoped folder].

Scope and rules:
- I am authorized to assess this repository.
- Keep the scan within [the entire repository / the exact folder named above].
- Use the Codex Security plugin's deep-scan workflow; do not reinterpret this as a pull request or diff review.

Return the scan directory and report.md path. Summarize the findings, reviewed surfaces, structural hardening guidance, and proof gaps that require human review first.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: high`. Uses the `$codex-security:deep-security-scan` skill
- Best for: application security reviews of an owned or authorized repository/component; more comprehensive reviews where extra runtime and token cost are acceptable
- For diff-level reviews, use Scan code changes for security (`scan-code-changes-for-security.md`); to fix found issues, use Remediate a vulnerability backlog (`remediate-vulnerability-backlog.md`)

# Audit dependency incidents

Turn a public package advisory into a safe repo-audit plan.

```text
Help me audit this repository for exposure to this public package advisory: [advisory URL].

Stay read-only unless I explicitly approve a remediation step.

First, summarize:
- affected packages and version ranges
- authoritative sources versus broader reports
- what evidence would prove exposure in this repo
- what evidence would rule it out

Then inspect:
- package manifests and lock files
- CI workflows and permissions
- install, build, and postinstall scripts
- vendored artifacts, containers, or generated bundles if relevant
- cache or token exposure paths if the advisory involves CI or publishing

Return:
- evidence status: confirmed exposure, needs verification, or ruled out
- severity and blast-radius notes
- file references for every repo-specific claim
- caveats and recommended next steps

Do not install packages, run lifecycle scripts, build the project, execute untrusted code, rotate credentials, or clean up files unless I explicitly approve that step.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: high`. The GitHub plugin inspects repository files, pull requests, workflows, and security-relevant history
- Best for: engineering and security teams responding to public package or supply chain advisories; incident reviews that must gather evidence without installing packages or running untrusted code

# Follow a goal

Give Codex a durable objective for long-running work.

```text
/goal Complete [objective] without stopping until [verifiable end state].
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). Maps to the CLI slash command `/goal`, controlled with `/goal pause`, `/goal resume`, and `/goal clear`
- Best for: code migrations with a target spec, large refactors backed by tests, prototypes/games with measurable success criteria
- A strong goal states: one objective and stopping condition, files/docs to consult, commands that validate progress, checkpoint-based work
- Related: Run code migrations (`code-migrations.md`)

# Review GitHub pull requests

Catch regressions and potential issues before human review.

```text
@codex review for security regressions, missing tests, and risky behavior changes.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedModel: cloud`. Triggered by mentioning `@codex` on a GitHub pull request
- The `$security-best-practices` skill can narrow the review to risky surfaces such as secrets, auth, and dependency changes
- Best for: teams that want another review signal before human merge approval, large production codebases
- Related: Custom instructions with AGENTS.md (https://learn.chatgpt.com/codex/agent-configuration/agents-md), Scan code changes for security (`scan-code-changes-for-security.md`)

# Debug in iOS simulator

Use Codex and XcodeBuildMCP to drive your app in iOS Simulator, capture evidence, and iterate toward a fix.

```text
Use the Build iOS Apps plugin and XcodeBuildMCP to reproduce this bug directly in Simulator, diagnose the root cause, and implement a small fix.

Bug report:
[Describe the expected behavior, the actual bug, and any known screen or account setup.]

Constraints:
- First check whether a project, scheme, and simulator are already selected. If not, discover the right Xcode project or workspace, pick the app scheme, choose a simulator, and reuse that setup for the rest of the session.
- Build and launch the app in Simulator, then confirm the right screen is visible with a UI snapshot or screenshot before you start interacting with it.
- Drive the exact reproduction path yourself by tapping, typing, scrolling, and swiping in the simulator. Prefer accessibility labels or IDs over raw coordinates, and re-read the UI hierarchy before the next action when the layout changes.
- Capture evidence while you debug: screenshots for visual state, simulator logs around the failure, and LLDB stack frames or variables if the bug looks like a crash or hang.
- If the simulator is not already booted, boot one and tell me which device and OS you chose. If credentials or a special fixture are required, pause and ask only for that missing input.
- Make the smallest code change that addresses the bug, then rerun the simulator flow and tell me exactly how you verified the fix.

Deliver:
- the reproduction steps Codex executed
- the key screenshots, logs, or stack details that explained the bug
- the code fix and why it works
- the simulator and scheme used for final verification
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). The Build iOS Apps plugin provides an iOS debugger agent that drives simulator setup, build/launch, UI snapshots, taps, gestures, screenshots, log capture, and debugger attachment via XcodeBuildMCP
- Best for: UI bugs reproducible only after a specific tap/scroll/form path; crashes or hangs needing logs, screenshots, view hierarchy state, and a debugger backtrace before editing code
- Observability relies on `Logger`, `OSLog`, LLDB, and Simulator screenshots

# samples

| Name | Description | Path |
| --- | --- | --- |
| Follow a goal | Give Codex a durable objective for long-running work. | [follow-goals.md](./follow-goals.md) |
| Review GitHub pull requests | Catch regressions and potential issues before human review. | [github-code-reviews.md](./github-code-reviews.md) |
| Understand large codebases | Trace request flows, map unfamiliar modules, and find the right files fast. | [codebase-onboarding.md](./codebase-onboarding.md) |
| Automate bug triage | Turn daily bug reports into a prioritized list, then automate the sweep. | [automation-bug-triage.md](./automation-bug-triage.md) |
| Kick off coding tasks from Slack | Turn Slack threads into scoped cloud chats. | [slack-coding-tasks.md](./slack-coding-tasks.md) |
| Save workflows as skills | Create a skill Codex can keep on hand for work you repeat. | [reusable-codex-skills.md](./reusable-codex-skills.md) |
| Refactor your codebase | Remove dead code and modernize legacy patterns without changing behavior. | [refactor-your-codebase.md](./refactor-your-codebase.md) |
| Run code migrations | Migrate legacy stacks in controlled checkpoints. | [code-migrations.md](./code-migrations.md) |
| Keep documentation up-to-date | Use code and other sources to automate docs updates. | [update-documentation.md](./update-documentation.md) |
| Create a CLI Codex can use | Give Codex a composable command for an API, log source, export, or team script. | [agent-friendly-clis.md](./agent-friendly-clis.md) |
| Run verified operations | Run repeatable workflows and verify the result. | [verified-operations-workflows.md](./verified-operations-workflows.md) |
| Add evals to your AI application | Use Codex to turn expected behavior into a Promptfoo eval suite. | [ai-app-evals.md](./ai-app-evals.md) |
| Scan code changes for security | Review a pull request or local diff for security regressions. | [scan-code-changes-for-security.md](./scan-code-changes-for-security.md) |
| Run a deep security scan | Search an authorized repository deeply for plausible vulnerabilities. | [deep-security-scan.md](./deep-security-scan.md) |
| Remediate a vulnerability backlog | Turn reviewed findings into minimal fixes with regression evidence. | [remediate-vulnerability-backlog.md](./remediate-vulnerability-backlog.md) |
| Audit dependency incidents | Turn a public package advisory into a safe repo-audit plan. | [dependency-incident-audits.md](./dependency-incident-audits.md) |
| Debug in iOS simulator | Use Codex and XcodeBuildMCP to drive your app in iOS Simulator, capture evidence, and iterate toward a fix. | [ios-simulator-bug-debugging.md](./ios-simulator-bug-debugging.md) |

# Refactor your codebase

Remove dead code and modernize legacy patterns without changing behavior.

```text
Modernize and refactor this codebase.

Requirements:
- Preserve behavior unless I explicitly ask for a functional change.
- Start by identifying dead code, duplicated paths, oversized modules, stale abstractions, and legacy patterns that are slowing changes down.
- For each proposed pass, name the current behavior, the structural improvement, and the validation check that should prove behavior stayed stable.
- Break the work into small reviewable refactor passes such as deleting dead code, simplifying control flow, extracting helpers, or replacing outdated patterns with the repo's current conventions.
- Keep public APIs stable unless a change is required by the refactor.
- Call out any framework migration, dependency upgrade, API change, or architecture move that should be split into a separate migration task.
- If the work is broad, propose the docs, specs, and parity checks we should create before implementation.

Propose a plan to do this.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). Can be paired with the `$security-best-practices` and `$skill-creator` skills
- Best for: codebases with dead code, oversized modules, or duplicated logic that need modernizing in place rather than a full stack migration
- Split framework or stack migrations into a separate pass: see Run code migrations (`code-migrations.md`)

# Remediate a vulnerability backlog

Turn reviewed findings into minimal fixes with regression evidence.

```text
Use $codex-security:fix-finding to fix this security finding and verify the issue no longer reproduces.

Source: [Codex Security report / Linear or Jira ticket / GitHub Security Advisory / HackerOne or Bugcrowd report / other authorized source]
Title and affected component: [finding title and component]
Vulnerable source, sink, or broken control: [known path or unknown]
Attacker-controlled input and impact: [input, prerequisites, and impact]
Expected security invariant: [behavior the fix must enforce]
Existing proof: [report path, PoC, reproducer, test, or validation notes]
Affected files and lines: [paths and lines, or unknown]
Constraints: [supported behavior to preserve, test command, rollout requirement, or none]

Requirements:
- Confirm that the issue still exists before changing code when feasible.
- Make the smallest change that enforces the intended security invariant.
- Add focused regression coverage or the strongest repeatable validation artifact available.
- Verify legitimate behavior still works and the original issue no longer reproduces.
- Keep unrelated backlog findings and refactors out of this change.

Report the changed files, tests or validation artifacts, exact commands and results, proof that the original issue no longer reproduces, and remaining uncertainty. If the issue is already fixed, show the evidence and do not change code.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: high`. Uses the `$codex-security:fix-finding` skill
- Best for: teams with reviewed findings from Codex Security, Linear/Jira, GitHub Security Advisories, HackerOne/Bugcrowd, or penetration tests; backlogs needing minimal diffs and repeatable validation
- Related: Run a deep security scan (`deep-security-scan.md`), Scan code changes for security (`scan-code-changes-for-security.md`)

# Save workflows as skills

Create a skill Codex can keep on hand for work you repeat.

```text
Use $skill-creator to create a Codex skill that [fixes failing Buildkite checks on a GitHub PR / turns PR notes into inline review comments / writes our release notes from merged PRs]

Use these sources when creating the skill:
- Working example: [say "use this chat," link a merged PR, or paste a good Codex answer]
- Source: [paste a Slack thread, PR review link, runbook URL, docs URL, or ticket]
- Repo: [repo path, if this skill depends on one repo]
- Scripts or commands to reuse: [test command], [preview command], [log-fetch script], [release command]
- Good output: [paste the Slack update, changelog entry, review comment, ticket, or final answer you want future tasks to match]
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). The `$skill-creator` system skill gathers context, scaffolds the skill, and validates the result
- Best for: workflows worth codifying, teams that want a reusable skill instead of pasting a long prompt into every chat
- Related: Agent skills (https://learn.chatgpt.com/codex/build-skills)

# Scan code changes for security

Review a pull request or local diff for security regressions.

```text
Use $codex-security:security-diff-scan to review this PR, commit, branch diff, or working-tree patch for security regressions.

Scope and rules:
- Target: [this pull request / commit SHA / branch diff from BASE to HEAD / the current working-tree patch]
- I am authorized to assess this repository and change set.
- Pay particular attention to [auth, input handling, secrets, filesystem, network, dependencies, or other sensitive surface].

Return the final Markdown report and inline code comments for findings that require human review.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: high`. Uses the `$codex-security:security-diff-scan` skill
- Best for: pull requests touching authentication, authorization, parsing, file access, secrets, or privileged workflows; a security-focused check before merge
- Related: Review GitHub pull requests (`github-code-reviews.md`), Agent approvals and security (https://learn.chatgpt.com/codex/agent-approvals-security)

# Kick off coding tasks from Slack

Turn Slack threads into scoped cloud chats.

```text
@Codex analyze the issue mentioned in this thread and implement a fix in <name of your environment>.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedModel: cloud`. Requires the Codex Slack integration and a configured Codex cloud environment
- Best for: async handoffs that already have enough context to act on, quick issue triage or scoped implementation work without context switching
- Related: Use Codex in Slack (https://learn.chatgpt.com/codex/third-party/slack), Codex cloud environments (https://learn.chatgpt.com/codex/environments/cloud-environment)

# Keep documentation up-to-date

Use code and other sources to automate docs updates.

```text
Update the [product/feature] documentation based on the following sources:
- the changed source files in [this repo/source linked repo]
- the existing docs pages that mention a new behavior
- any linked issue, PR, release note, or public reference I provide below

Then:
- identify what is user-facing
- update only the docs that need to change
- keep unpublished roadmap, private customer details, and internal-only context out of public docs
- preserve the existing docs structure, terminology, and cross-links
- run the docs checks that fit the change

Before finalizing, summarize what changed, what you verified, and any claims you could not prove from trusted sources.

[link release notes or other references here]
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). The GitHub plugin can read issues, pull requests, review threads, and failed checks as source context
- Best for: developer docs, READMEs, runbooks, examples, and migration notes that need to track frequently changing behavior

# Run verified operations

Run repeatable workflows and verify the result.

```text
I need to run this workflow:

Goal: [what should happen]
Inputs: [CSV, Google Sheet, list, ticket, or file path]
Approval or policy source: [Slack thread, doc, ticket, or none]
Runner: [script, API, CLI, skill, or manual app workflow]
Verification artifact: [result CSV, log, dashboard, screenshot, or other proof]

Please:
- inspect the inputs and ask only for missing required fields
- normalize dates, amounts, owners, and IDs before running the workflow
- run a dry run first when the workflow supports it
- run only the approved scope
- record one success or failure row per item
- retry transient failures once without restarting successful rows
- summarize totals, failures, retries, and verification artifacts

Pause before irreversible actions or scope changes.
```

## Notes

- Source: OpenAI Codex use-case (learn.chatgpt.com). `suggestedEffort: medium`
- Best for: operations tasks with structured inputs, explicit approval, and an auditable result, such as access updates, invite batches, or quota changes
- Related: Plugins (https://learn.chatgpt.com/codex/plugins), Scheduled tasks (https://learn.chatgpt.com/codex/automations), Agent skills (https://learn.chatgpt.com/codex/build-skills)

# Auth

Sign in, check status, and sign out of the Codex CLI.

## Sign in with ChatGPT

```bash
codex login
```

Opens the browser-based ChatGPT sign-in flow. Uses your ChatGPT workspace credentials and follows enterprise permissions/data policies.

## Sign in with an API key

```bash
printenv OPENAI_API_KEY | codex login --with-api-key
```

Uses usage-based access through your OpenAI Platform account at standard API rates.

## Device code authentication (headless environments)

```bash
codex login --device-auth
```

For environments without a browser (e.g. remote servers, containers).

## Check authentication status

```bash
codex login status
```

## Sign out

```bash
codex logout
```

> **警告**: Credentials are cached locally at `~/.codex/auth.json`. Treat this file like a password — it contains access tokens. Don't commit it, paste it into tickets, or share it in chat.

# Automation

Run Codex headlessly in scripts, CI pipelines, and GitHub Actions.

## Basic non-interactive invocation

```bash
codex exec "summarize the repository structure and list the top 5 risky areas"
```

Progress streams to stderr while only the final agent message goes to stdout, so output pipes cleanly.

```bash
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
```

## Sandbox / permission levels

`codex exec` defaults to read-only mode. Use the least permission needed for the workflow.

```bash
codex exec --sandbox workspace-write "<task>"
```

> **警告**: `--sandbox danger-full-access` removes filesystem/network restrictions. Use only in isolated, trusted environments.

```bash
codex exec --sandbox danger-full-access "<task>"
```

## Machine-readable output

```bash
codex exec --json "summarize the repo structure" | jq
```

JSON Lines output captures all events for script consumption.

```bash
codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json
```

## Piping input into Codex

```bash
curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md
```

```bash
cat prompt.txt | codex exec -
```

Reads the prompt from stdin.

## Resume a session non-interactively

```bash
codex exec resume --last "fix the race conditions you found"
```

> **警告**: For CI/CD, prefer the Codex GitHub Action over passing API keys directly, and never set credentials as job-level environment variables in workflows that check out repository code.

## GitHub Action: PR review workflow

`openai/codex-action@v1` installs the Codex CLI, starts the Responses API proxy when given an API key, and runs `codex exec` under the permissions specified. This example workflow (from the official docs) reviews new pull requests and posts the result as a comment.

```yaml
name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
```

Replace `.github/codex/prompts/review.md` with your own prompt file, or use the `prompt` input for inline text instead of `prompt-file`.

Prerequisites:
- Store the OpenAI API key as a GitHub secret (e.g. `OPENAI_API_KEY`) and reference it in the workflow
- Run the job on a Linux or macOS runner; Windows requires `safety-strategy: unsafe`
- Check out the repository before invoking the action

Key inputs that map to `codex exec` options:

| Input | Purpose |
| --- | --- |
| `prompt` / `prompt-file` | Inline instructions or a repository path to the task text (choose one) |
| `codex-args` | Extra CLI flags as a JSON array (`["--ephemeral"]`) or shell string (`--profile ci`) |
| `model` / `effort` | Codex agent configuration; leave empty for defaults |
| `sandbox` | `workspace-write`, `read-only`, or `danger-full-access` |
| `output-file` | Save the final Codex message to disk |
| `codex-version` | Pin a specific CLI release |
| `codex-home` | Point to a shared Codex home directory to reuse config/MCP setups |

Privilege controls:

| Input | Purpose |
| --- | --- |
| `safety-strategy` | Default `drop-sudo` removes `sudo` before running Codex (irreversible for the job). Windows requires `unsafe` |
| `unprivileged-user` | Pairs with `codex-user` to run Codex as a specific unprivileged account |
| `allow-users` / `allow-bots` | Restrict who can trigger the workflow (default: write-access users only) |

> **警告**: Don't rely on `sandbox: read-only` alone to protect secrets — it still runs with elevated privileges unless combined with `safety-strategy`. Never leave `safety-strategy: unsafe` set on multi-tenant runners.

The action emits the final Codex message through the `final-message` output.

## Codex Security scan in CI

Install `@openai/codex-security` outside the repository checkout, then run a diff scan and export SARIF for upload.

```bash
npm install \
  --prefix "$RUNNER_TEMP/codex-security" \
  --ignore-scripts \
  --no-audit \
  --no-fund \
  @openai/codex-security@0.1.3
```

`npm install` does not define `CODEX_SECURITY_BIN` — set it explicitly to the installed binary path before invoking it (matches the CI example in `references/security/cli-ci.md`).

```bash
CODEX_SECURITY_BIN="$RUNNER_TEMP/codex-security/node_modules/.bin/codex-security"

"$CODEX_SECURITY_BIN" scan . \
  --diff "$BASE_REVISION" \
  --head "$HEAD_SHA" \
  --auth api-key \
  --output-dir "$SCAN_DIR" \
  --json > "$RUNNER_TEMP/codex-security.json"
```

```bash
"$CODEX_SECURITY_BIN" export "$SCAN_DIR" \
  --export-format sarif \
  --source-root "$GITHUB_WORKSPACE" \
  --output "$SARIF_FILE"
```

### Enforce a severity policy

```bash
--fail-on-severity high
```

Supported thresholds: `critical`, `high`, `medium`, `low`.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Scan completed successfully, policy passed |
| `1` | Finding detected at or above the severity threshold |
| `2` | Input/runtime error or incomplete coverage |
| `130` | Ctrl-C interrupt |
| `143` | SIGTERM termination |

Requires Node.js 22+, Python 3.10+, the `@openai/codex-security` package installed outside the repository, and an OpenAI API key stored as `CODEX_SECURITY_API_KEY`.

# CLI Basics

Core interactive and session-management commands for the Codex terminal client.

## Start an interactive session

```bash
codex
```

Run from a project directory to start the interactive TUI. After authenticating, describe the task in natural language (e.g. "Tell me about this project").

## Run a single prompt non-interactively

```bash
codex exec "summarize the repository structure and list the top 5 risky areas"
```

`exec` (alias: `e`) runs Codex from scripts without the interactive interface. See `automation.md` for flags and CI usage.

## Resume a previous session

```bash
codex resume
```

Reopens recent repository chats interactively.

```bash
codex exec resume --last "fix the race conditions you found"
```

Resumes the most recent `exec` session non-interactively with a follow-up prompt.

## Review code changes

```bash
codex review
```

Reviews code changes before committing.

## Model Context Protocol (MCP) integration

```bash
codex mcp
```

Integrate external tools via MCP.

## Environment diagnostics

```bash
codex doctor
```

## Notable CLI features

- `codex resume` — reopen recent repository chats
- `codex --image` — include screenshots or diagrams as input
- `codex --search` — enable live web search capability
- `codex mcp` — integrate external tools via Model Context Protocol
- `/permissions` (in-session slash command) — configure file editing and command execution boundaries

## Other documented subcommands

```
codex app-server
codex remote-control
codex remote-control start
codex remote-control stop
codex remote-control pair
codex app
codex debug app-server send-message-v2
codex debug models
codex debug prompt-input
codex apply
codex archive <SESSION>
codex unarchive <SESSION>
codex delete <SESSION>
codex delete <SESSION_UUID> --force
codex cloud
codex cloud exec
codex cloud list
codex completion
codex features
codex execpolicy
codex execpolicy check
codex fork
codex login
codex login status
codex logout
codex mcp-server
codex plugin
codex plugin add
codex plugin list
codex plugin remove
codex plugin marketplace
codex plugin marketplace add
codex plugin marketplace list
codex sandbox
codex update
```

Listed in the official command reference (see `developer-commands.md?surface=cli`); flag details are rendered as interactive `<ConfigTable>` components that are not present in the Markdown export. Run `codex <command> --help` for options. 要確認: exact flags/arguments per subcommand.

`codex login`, `codex login status`, and `codex logout` are documented in detail in `auth.md` (kept here only for completeness of the subcommand list).

`codex app` (stable) launches the ChatGPT desktop app and is macOS/Windows only; the subcommand is not compiled on other platforms, where `app` instead falls through to prompt interpretation. Distinct from `codex app-server` above.

## Slash commands (in-session)

Type these during an interactive `codex` session:

```
/permissions
/ide
/keymap
/vim
/setup-default-sandbox
/sandbox-add-read-dir
/agent
/subagents
/apps
/plugins
/hooks
/clear
/rename
/archive
/delete
/compact
/copy
/diff
/exit
/experimental
/approve
/memories
/skills
/import
/feedback
/init
/logout
/mcp
/mention
/model
/fast
/plan
/goal
/personality
/ps
/stop
/fork
/app
/side
/btw
/raw
/resume
/new
/quit
/review
/status
/usage
/debug-config
/statusline
/title
/theme
/pets
/pet
```

# Config

Customize the Codex terminal interface: shell completions, editor, and themes.

## Shell completions (zsh)

```bash
codex completion zsh
```

Prints the zsh completion script.

```bash
eval "$(codex completion zsh)"
```

Loads completions into the current shell session.

```bash
autoload -Uz compinit && compinit
eval "$(codex completion zsh)"
```

Full setup when `compinit` has not already been run (e.g. in `~/.zshrc`).

## Config home and files

- `$CODEX_HOME/config.toml` — main configuration file
- `$CODEX_HOME/themes` — custom theme directory (`.tmTheme` files)

## Environment variables

| Variable | Purpose |
| --- | --- |
| `CODEX_HOME` | Overrides the default Codex config directory |
| `VISUAL` | External editor used for longer prompts |
| `EDITOR` | Fallback external editor |

## Editor shortcut

<kbd>Ctrl</kbd>+<kbd>G</kbd> opens the external editor (`$VISUAL` / `$EDITOR`) for composing longer prompts. <kbd>Tab</kbd> triggers shell completion inside the CLI.

# Install

Install or update the Codex CLI binary on macOS, Linux, or Windows.

## macOS / Linux standalone installer

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

## Windows standalone installer

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

## npm

```bash
npm install -g @openai/codex
```

## Homebrew (macOS)

```bash
brew install --cask codex
```

## Update

Re-run the same command used for the original install (the `curl | sh` installer, the PowerShell installer, `npm install -g @openai/codex`, or `brew upgrade --cask codex`) to update to the latest release.

## Environment diagnostics

```bash
codex doctor
```

Runs environment diagnostics for the CLI install.

# scripts

| Name | Description | Path |
| --- | --- | --- |
| install | Install or update the Codex CLI binary (curl / PowerShell / npm / Homebrew) | [install.md](./install.md) |
| auth | Sign in, check status, and sign out of the Codex CLI | [auth.md](./auth.md) |
| cli-basics | Core interactive and session-management commands (`codex`, `exec`, `resume`, `review`, `apply`, `mcp`, plugins, cloud) | [cli-basics.md](./cli-basics.md) |
| automation | Run Codex headlessly in scripts, CI, GitHub Actions, and security scans | [automation.md](./automation.md) |
| config | CLI customization: shell completions, config home, editor, themes | [config.md](./config.md) |

---
name: openai-codex
description: >
  OpenAI Codex (CLI / IDE / cloud) の公式リファレンス。
  codex CLI, codex exec, AGENTS.md, rules, subagents, prompting,
  approvals, sandbox, permission profiles, auto-review,
  config.toml, profiles, MCP 設定, 環境変数,
  GitHub Action, Codex SDK, Agents SDK 連携, cloud 委譲,
  administration, roles, provisioning, analytics API, compliance API,
  Codex Security 脆弱性スキャン, deep scan, triage, findings, SARIF export,
  threat model, security hardening,
  cloud / local / worktree 環境, git worktrees, Record & Replay,
  GitHub / Linear / Slack 連携。
user-invocable: false
---

# openai-codex

OpenAI Codex — `codex` CLI / IDE 拡張 / cloud からなる OpenAI 公式のコーディングエージェント製品。
CLI・IDE・cloud への導入、AGENTS.md/rules/subagents によるエージェント設定、config.toml/MCP 設定、
approvals・sandbox・GitHub Action・Codex SDK による自動化、ワークスペース administration、
Codex Security による脆弱性スキャン・修復、cloud/local/worktree 環境の切り替えと Record & Replay
によるスキル化、GitHub・Linear・Slack との連携をカバーする。

本スキルは OpenAI Codex の公式ドキュメントを蒸留したものであり、本リポジトリが対象とする Claude Code の
`.claude/` 体系とは別物である。`AGENTS.md` / `rules` / `subagents` など用語が重なる箇所があるが、
設定ファイルの形式・置き場所・意味は Claude Code の `CLAUDE.md` / `.claude/rules/` / `.claude/agents/` と互換性がない
（詳細は `references/agent-configuration/README.md` の冒頭注記を参照）。

## ディレクトリ構成

```text
skills/openai-codex/
  SKILL.md
  references/
    getting-started/
      README.md
      cli.md
      cli-customization.md
      ide.md
      windows-app.md
      cloud.md
      cloud-internet-access.md
      remote.md
      remote-connections.md
      models.md
      codex-micro.md
      best-practices.md
    agent-configuration/
      README.md
      agents-md.md
      rules.md
      hooks.md
      speed.md
      subagents.md
      prompting.md
    config/
      README.md
      config-basics.md
      config-advanced.md
      config-reference.md
      config-sample.md
      environment-variables.md
      mcp-config.md
      amazon-bedrock.md
    security-automation/
      README.md
      agent-approvals-security.md
      sandbox.md
      permission-profiles.md
      permission-modes.md
      auto-review.md
      windows-sandbox.md
      windows-wsl.md
      non-interactive-mode.md
      github-action.md
      codex-sdk.md
      agents-sdk-mcp-server.md
    administration/
      README.md
      administration.md
      admin-rollout-guide.md
      work-admin-faq.md
      usage-limits.md
      groups-and-provisioning.md
      roles-and-workspace-permissions.md
      access-tokens.md
      analytics-api.md
      compliance-api.md
      governance.md
      workspace-analytics.md
      workspace-model-availability.md
      plugin-controls.md
      skill-controls.md
      managed-configuration.md
      manage-app-updates.md
      windows-deployment.md
      authentication.md
    security/
      README.md
      overview.md
      cloud-setup.md
      cloud-faq.md
      threat-model.md
      plugin-quickstart.md
      workbench.md
      scans.md
      deep-scans.md
      code-changes.md
      security-review.md
      triage-backlog.md
      fix-findings.md
      export-findings.md
      vulnerability-reports.md
      security-hardening.md
      plugin-changelog.md
      cli-quickstart.md
      cli-reference.md
      cli-faq.md
      cli-bulk-scans.md
      cli-ci.md
      sdk.md
    environments/
      README.md
      cloud-environment.md
      git-worktrees.md
      local-environment.md
      modes.md
    extend/
      README.md
      record-and-replay.md
    third-party/
      README.md
      github.md
      linear.md
      slack.md
  samples/
    README.md
    follow-goals.md
    github-code-reviews.md
    codebase-onboarding.md
    automation-bug-triage.md
    slack-coding-tasks.md
    reusable-codex-skills.md
    refactor-your-codebase.md
    code-migrations.md
    update-documentation.md
    agent-friendly-clis.md
    verified-operations-workflows.md
    ai-app-evals.md
    scan-code-changes-for-security.md
    deep-security-scan.md
    remediate-vulnerability-backlog.md
    dependency-incident-audits.md
    ios-simulator-bug-debugging.md
  scripts/
    README.md
    install.md
    auth.md
    cli-basics.md
    automation.md
    config.md
```

## 探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す
2. そのカテゴリの `references/{category}/README.md` を参照して目的のページを特定する
3. 該当ページの `.md` を Read して詳細を確認する

## タスク → カテゴリ マッピング

| タスク | カテゴリ | 参照 README |
|--------|---------|------------|
| Codex CLI / IDE 拡張 / cloud の導入・違いを知りたい | getting-started | [references/getting-started/README.md](references/getting-started/README.md) |
| CLI の出力・エイリアスをカスタマイズしたい、Windows デスクトップアプリ・リモート接続から使いたい | getting-started | [references/getting-started/README.md](references/getting-started/README.md) |
| モデル選択（Codex Micro 含む）・reasoning effort・ベストプラクティスを知りたい | getting-started | [references/getting-started/README.md](references/getting-started/README.md) |
| AGENTS.md / prompting / subagents ワークフローを設定したい | agent-configuration | [references/agent-configuration/README.md](references/agent-configuration/README.md) |
| サンドボックス外で実行するコマンドを rules（`.rules` / Starlark `prefix_rule`）で許可したい、hooks でエージェントのライフサイクルにフックしたい | agent-configuration | [references/agent-configuration/README.md](references/agent-configuration/README.md) |
| config.toml のキー・プロファイル・MCP サーバー設定、Amazon Bedrock 経由の利用を知りたい | config | [references/config/README.md](references/config/README.md) |
| 環境変数の一覧を知りたい | config | [references/config/README.md](references/config/README.md) |
| approvals / sandbox / permission profiles / permission modes を設計したい | security-automation | [references/security-automation/README.md](references/security-automation/README.md) |
| codex exec を CI/GitHub Action/Codex SDK から自動実行したい、Windows/WSL 上のサンドボックスを設定したい | security-automation | [references/security-automation/README.md](references/security-automation/README.md) |
| ワークスペースの roles / provisioning / analytics / compliance を管理したい | administration | [references/administration/README.md](references/administration/README.md) |
| Enterprise ロールアウト・アクセストークン運用を知りたい | administration | [references/administration/README.md](references/administration/README.md) |
| リポジトリの脆弱性スキャン・トリアージ・修復（Codex Security）を行いたい、PR/差分のセキュリティレビューをしたい | security | [references/security/README.md](references/security/README.md) |
| 検出結果の SARIF/CSV/JSON エクスポート・CI 連携・threat model 調整をしたい | security | [references/security/README.md](references/security/README.md) |
| Cloud / Local / Worktree 環境の設定・切り替え、git worktree でチャットを分離したい | environments | [references/environments/README.md](references/environments/README.md) |
| ワークフローを録画してスキル化したい（Record & Replay） | extend | [references/extend/README.md](references/extend/README.md) |
| GitHub / Linear / Slack から Codex を呼び出したい | third-party | [references/third-party/README.md](references/third-party/README.md) |
| 典型的な使い方を知りたい | samples | [samples/README.md](samples/README.md) |
| インストール・CLI コマンドを知りたい | scripts | [scripts/README.md](scripts/README.md) |