Codex Docs

Name: Codex Docs
Author: mehmetbaykar

mehmetbaykar/codex-docs-skill

32 installs
1 repo stars
Updated August 4, 2026
mehmetbaykar/codex-docs-skill

Helps with ai & agent building tasks.

About

codex-docs is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted coding.

codex-docs
AI & Agent Building
AI-coding skill

Codex Docs by the numbers

32 all-time installs (skills.sh)
Ranked #9,101 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/mehmetbaykar/codex-docs-skill --skill codex-docs

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/mehmetbaykar/codex-docs-skill/codex-docs.svg)](https://skillselion.com/skills/mehmetbaykar/codex-docs-skill/codex-docs)

Installs	32
repo stars	★ 1
Last updated	August 4, 2026
Repository	mehmetbaykar/codex-docs-skill ↗

What it does

Helps with ai & agent building tasks.

Files

agents/
references/
- _raw/

agents/openai.yamlYAMLGitHub ↗

interface:
  display_name: "Codex Docs"
  short_description: "Search and read OpenAI Codex documentation locally"

policy:
  allow_implicit_invocation: true

Glossary

Use this glossary as a quick reference for Codex terms across the app, CLI, IDE extension, cloud, SDK, and related integrations.

Agent approvals & security

Codex helps protect your code and data and reduces the risk of misuse.

This page covers how to operate Codex safely, including sandboxing, approvals, and network access. If you are looking for Codex Security, the product for scanning connected GitHub repositories, see Codex Security.

By default, the agent runs with network access turned off. Locally, Codex uses an OS-enforced sandbox that limits what it can touch (typically to the current workspace), plus an approval policy that controls when it must stop and ask you before acting.

For a high-level explanation of how sandboxing works across the Codex app, IDE extension, and CLI, see sandboxing. For a broader enterprise security overview, see the Codex security white paper.

Sandbox and approvals

Codex security controls come from two layers that work together:

Sandbox mode: What Codex can do technically (for example, where it can write and whether it can reach the network) when it executes model-generated commands.
Approval policy: When Codex must ask you before it executes an action (for example, leaving the sandbox, using the network, or running commands outside a trusted set).

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

Codex cloud: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.
Codex CLI / IDE extension: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

In the Auto preset (for example, --sandbox workspace-write --ask-for-approval on-request), Codex can read files, make edits, and run commands in the working directory automatically.

Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to read-only mode with the /permissions command.

Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn't a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

Network access

For Codex cloud, see agent internet access to enable full internet access or a domain allow list.

For the Codex app, CLI, or IDE Extension, the default workspace-write sandbox mode keeps network access turned off unless you enable it in your configuration:

[sandbox_workspace_write]
network_access = true

Network isolation

Network access is controlled through destination rules that apply to scripts, programs, and subprocesses spawned by commands. When command network access is already enabled, turn on the network_proxy feature to constrain that traffic to the network policy you configure.

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

For a one-off CLI session, use the boolean shorthand when you only need the toggle, and the table form when you also set policy options:

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

The feature changes how enabled network access is enforced; it does not grant network access by itself. Use sandbox_workspace_write.network_access with workspace-write config to decide whether commands have network access at all:

Network off + network_proxy on: network stays off, and the feature does nothing.
Network on + network_proxy off: network stays on with unrestricted direct

outbound access.

Network on + network_proxy on: network stays on, and outbound traffic is

constrained by the configured network policy.

Admin-managed experimental_network requirements are separate from the user feature toggle. They can configure and start sandboxed networking without features.network_proxy, but they do not turn on network access when the active sandbox keeps it off. See Managed configuration for the administrator-side requirements.toml shape.

Network policy

Domain rules are allowlist-first:

Exact hosts match only themselves.
*.example.com matches subdomains such as api.example.com, but not

example.com.

**.example.com matches both the apex and subdomains.
A global * allow rule matches any public host that is not denied. Treat *

as broad network access and prefer scoped rules when you can.

deny always wins over allow, and global * is only valid for allow rules.

Local and private destinations

By default, allow_local_binding = false blocks loopback, link-local, and private destinations:

Specific exceptions: add an exact local IP literal or localhost allow rule

when a command needs one local target.

Broader access: set allow_local_binding = true only when you intentionally

want wider local/private reach.

Wildcards: wildcard rules do not count as explicit local exceptions.
Resolved addresses: hostnames that resolve to local/private IPs stay blocked

even if they match the allowlist.

DNS rebinding protections

Before allowing a hostname, Codex performs a best-effort DNS and IP classification check:

Lookups that fail or time out are blocked.
Hostnames that resolve to non-public addresses are blocked.
The check reduces DNS rebinding risk, but it does not eliminate it. Preventing

rebinding completely would require pinning resolved IPs through the transport layer.

If hostile DNS is in scope, enforce egress controls at a lower layer too.

Dangerous settings

Two settings deliberately widen the trust boundary:

dangerously_allow_non_loopback_proxy = true can expose proxy listeners beyond

loopback.

dangerously_allow_all_unix_sockets = true bypasses the Unix socket allowlist.

Use them only in tightly controlled environments. When Unix socket proxying is enabled, listeners stay loopback-only even if non-loopback binding was requested, so sandboxed networking does not become a remote bridge into local daemons.

network_proxy is off by default. When you enable it:

Setting	Default	Behavior
`enabled`	`false`	Starts sandboxed networking only when command network access is already on.
`domains`	unset	Uses allowlist behavior, so no external destinations are allowed until you add `allow` rules. Supports exact hosts, scoped wildcards, and global `*` allow rules; `deny` always wins.
`unix_sockets`	unset	No Unix socket destinations are allowed until you add explicit `allow` rules.
`allow_local_binding`	`false`	Blocks local and private-network destinations unless you add an exact local IP literal or `localhost` allow rule, or explicitly opt into broader local/private access.
`enable_socks5`	`true`	Exposes SOCKS5 support when policy allows it.
`enable_socks5_udp`	`true`	Allows UDP over SOCKS5 when SOCKS5 is available.
`allow_upstream_proxy`	`true`	Lets sandboxed networking honor an upstream proxy from the environment.
`dangerously_allow_non_loopback_proxy`	`false`	Keeps listener endpoints on loopback unless you deliberately expose them beyond localhost.
`dangerously_allow_all_unix_sockets`	`false`	Keeps Unix socket access allowlist-based unless you deliberately bypass that protection.

You can also control the web search tool without granting full network access to spawned commands. Codex defaults to using a web search cache to access results. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using --yolo or another full access sandbox setting, web search defaults to live results. Use --search or set web_search = "live" to allow live browsing, or set it to "disabled" to turn the tool off:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

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

Defaults and recommendations

On launch, Codex detects whether the folder is version-controlled and recommends:
Version-controlled folders: Auto (workspace write + on-request approvals)
Non-version-controlled folders: read-only
Depending on your setup, Codex may also start in read-only until you explicitly trust the working directory (for example, via an onboarding prompt or /permissions).
The workspace includes the current directory and temporary directories like /tmp. Use the /status command to see which directories are in the workspace.
To accept the defaults, run codex.
You can set these explicitly:
codex --sandbox workspace-write --ask-for-approval on-request
codex --sandbox read-only --ask-for-approval on-request

Protected paths in writable roots

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

<writable_root>/.git is protected as read-only whether it appears as a directory or file.
If <writable_root>/.git is a pointer file (gitdir: ...), the resolved Git directory path is also protected as read-only.
<writable_root>/.agents is protected as read-only when it exists as a directory.
<writable_root>/.codex is protected as read-only when it exists as a directory.
Protection is recursive, so everything under those paths is read-only.

Run without approval prompts

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

This option works with all --sandbox modes, so you still control Codex's level of autonomy. Codex makes a best effort within the constraints you set.

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

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

Automatic approval reviews

By default, approval requests route to you:

approvals_reviewer = "user"

Automatic approval reviews apply when approvals are interactive, such as approval_policy = "on-request" or a granular approval policy. Set approvals_reviewer = "auto_review" to route eligible approval requests through a reviewer agent before Codex runs the request:

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

For the full reviewer lifecycle, trigger conditions, configuration precedence, and failure behavior, see Auto-review.

The reviewer evaluates only actions that already need approval, such as sandbox escalations, blocked network requests, request_permissions prompts, or side-effecting app and MCP tool calls. Actions that stay inside the sandbox continue without an extra review step.

The reviewer policy checks for data exfiltration, credential probing, persistent security weakening, and destructive actions. Low-risk and medium-risk actions can proceed when policy allows them. The policy denies critical-risk actions. High-risk actions require enough user authorization and no matching deny rule. Prompt-build, review-session, and parse failures fail closed. Timeouts are surfaced separately, but the action still does not run.

The default reviewer policy is in the open-source Codex repository. Enterprises can replace its tenant-specific section with guardian_policy_config in managed requirements. Local [auto_review].policy text is also supported, but managed requirements take precedence. For setup details, see Managed configuration.

In the Codex app, these reviews appear as automatic review items with a status such as Reviewing, Approved, Denied, Aborted, or Timed out. They can also include a risk level and user-authorization assessment for the reviewed request.

Automatic review uses extra model calls, so it can add to Codex usage. Admins can constrain it with allowed_approvals_reviewers.

Common sandbox and approval combinations

Intent	Flags / config	Effect
Auto (preset)	_no flags needed_ or `--sandbox workspace-write --ask-for-approval on-request`	Codex can read files, make edits, and run commands in the workspace. Codex requires approval to edit outside the workspace or to access network.
Safe read-only browsing	`--sandbox read-only --ask-for-approval on-request`	Codex can read files and answer questions. Codex requires approval to make edits, run commands, or access network.
Read-only non-interactive (CI)	`--sandbox read-only --ask-for-approval never`	Codex can only read files; never asks for approval.
Automatically edit but ask for approval to run untrusted commands	`--sandbox workspace-write --ask-for-approval untrusted`	Codex can read and edit files but asks for approval before running untrusted commands.
Auto-review mode	`--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review` or `approvals_reviewer = "auto_review"`	Same sandbox boundary as standard on-request mode, but eligible approval requests are reviewed by Auto-review instead of surfacing to the user.
Dangerous full access	`--dangerously-bypass-approvals-and-sandbox` (alias: `--yolo`)	No sandbox; no approvals _(not recommended)_

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

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

Configuration in `config.toml`

For the broader configuration workflow, see Config basics, Advanced Config, and the Configuration Reference.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

You can also save presets as profile files, then select them with codex --profile profile-name:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

Test the sandbox locally

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

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

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

OS-level sandbox

Codex enforces the sandbox differently depending on your OS:

macOS uses Seatbelt policies and runs commands using sandbox-exec with a profile (-p) that corresponds to the --sandbox mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing /System) to preserve common tool compatibility.
Linux uses bwrap plus seccomp by default.
Windows uses the Linux sandbox implementation when running in Windows Subsystem for Linux 2 (WSL2). WSL1 was supported through Codex 0.114; starting in 0.115, the Linux sandbox moved to bwrap, so WSL1 is no longer supported. When running natively on Windows, Codex uses a Windows sandbox implementation.

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

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the Windows setup guide.

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

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

See the Windows setup guide for details.

When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration blocks the namespace, setuid bwrap, or seccomp operations that Codex needs.

In that case, configure your Docker container to provide the isolation you need, then run codex with --sandbox danger-full-access (or the --dangerously-bypass-approvals-and-sandbox flag) inside the container.

Run Codex in Dev Containers

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

Use the Codex secure devcontainer example as a reference implementation. The example installs Codex, common development tools, bubblewrap, and firewall-based outbound controls.

Devcontainers provide substantial protection, but they do not prevent every attack. If you run Codex with --sandbox danger-full-access or --dangerously-bypass-approvals-and-sandbox inside the container, a malicious project can exfiltrate anything available inside the devcontainer, including Codex credentials. Use this pattern only with trusted repositories, and monitor Codex activity as you would in any other elevated environment.

The reference implementation includes:

an Ubuntu 24.04 base image with Codex and common development tools installed;
an allowlist-driven firewall profile for outbound access;
VS Code settings and extension recommendations for reopening the workspace in a container;
persistent mounts for command history and Codex configuration;
bubblewrap, so Codex can still use its Linux sandbox when the container grants the needed capabilities.

To try it:

1. Install Visual Studio Code and the Dev Containers extension. 2. Copy the Codex example .devcontainer setup into your repository, or start from the Codex repository directly. 3. In VS Code, run Dev Containers: Open Folder in Container... and select .devcontainer/devcontainer.secure.json. 4. After the container starts, open a terminal and run codex.

You can also start the container from the CLI:

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

The example has three main pieces:

.devcontainer/devcontainer.secure.json controls container settings, capabilities, mounts, environment variables, and VS Code extensions.
.devcontainer/Dockerfile.secure defines the Ubuntu-based image and installed tools.
.devcontainer/init-firewall.sh applies the outbound network policy.

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

Inside the container, choose one of these modes:

Keep Codex's Linux sandbox enabled if the Dev Container profile grants the capabilities needed for bwrap to create the inner sandbox.
If the container is your intended security boundary, run Codex with --sandbox danger-full-access inside the container so Codex does not try to create a second sandbox layer.

Version control

Codex works best with a version control workflow:

Work on a feature branch and keep git status clean before delegating. This keeps Codex patches easier to isolate and revert.
Prefer patch-based workflows (for example, git diff/git apply) over editing tracked files directly. Commit frequently so you can roll back in small increments.
Treat Codex suggestions like any other PR: run targeted verification, review diffs, and document decisions in commit messages for auditing.

Monitoring and telemetry

Codex supports opt-in monitoring via OpenTelemetry (OTel) to help teams audit usage, investigate issues, and meet compliance requirements without weakening local security defaults. Telemetry is off by default; enable it explicitly in your configuration.

Overview

Codex turns off OTel export by default to keep local runs self-contained.
When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.
Codex tags exported events with service.name (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

Enable OTel (opt-in)

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

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

exporter = "none" leaves instrumentation active but doesn't send data anywhere.
To send events to your own collector, pick one of:

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

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

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

Event categories

Representative event types include:

codex.conversation_starts (model, reasoning settings, sandbox/approval policy)
codex.api_request (attempt, status/success, duration, and error details)
codex.sse_event (stream event kind, success/failure, duration, plus token counts on response.completed)
codex.websocket_request and codex.websocket_event (request duration plus per-message kind/success/error)
codex.user_prompt (length; content redacted unless explicitly enabled)
codex.tool_decision (approved/denied, source: configuration vs. user)
codex.tool_result (duration, success, output snippet)

Associated OTel metrics (counter plus duration histogram pairs) include codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event, and codex.tool.call (with corresponding .duration_ms instruments).

For the full event catalog and configuration reference, see the Codex configuration documentation on GitHub.

Security and privacy guidance

Keep log_user_prompt = false unless policy explicitly permits storing prompt contents. Prompts can include source code and sensitive data.
Route telemetry only to collectors you control; apply retention limits and access controls aligned with your compliance requirements.
Treat tool arguments and outputs as sensitive. Favor redaction at the collector or SIEM when possible.
Review local data retention settings (for example, history.persistence / history.max_bytes) if you don't want Codex to save session transcripts under CODEX_HOME. See Advanced Config and Configuration Reference.
If you run the CLI with network access turned off, OTel export can't reach your collector. To export, allow network access in workspace-write mode for the OTel endpoint, or export from Codex cloud with the collector domain on your approved list.
Review events periodically for approval/sandbox changes and unexpected tool executions.

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

Managed configuration

Enterprise admins can configure Codex security settings for their workspace in Managed configuration. See that page for setup and policy details.

Use Codex with Amazon Bedrock

Configure Codex to use OpenAI models available through Amazon Bedrock. In this setup, Codex runs locally and sends model requests to Bedrock using AWS-managed authentication and access controls.

How it works

When you configure Codex with Amazon Bedrock as the model provider, the OpenAI-hosted Responses API isn't in the request path. Codex sends model requests to Amazon Bedrock, and Bedrock provides an OpenAI-compatible Responses API implementation for supported OpenAI models.

Authentication is AWS-native. Users authenticate with a Bedrock API key or AWS IAM credentials. They do not use ChatGPT sign-in or OPENAI_API_KEY for this provider.

Before you start

Make sure you have:

Access to supported OpenAI models in Amazon Bedrock.
An AWS Region where the selected model is available.
Authentication for the Amazon Bedrock Mantle path configured for the AWS

account.

Configure Codex

Add the amazon-bedrock model provider for the Amazon Bedrock Mantle path to ~/.codex/config.toml. Supplying a model is optional. Select a supported model explicitly when needed.

model_provider = "amazon-bedrock"

This guide covers the Amazon Bedrock Mantle path in supported commercial AWS Regions. Codex doesn't support Bedrock Mantle endpoints in AWS GovCloud Regions.

Authentication options

Codex supports two Bedrock authentication paths. It checks them in this order:

1. Bedrock API key. 2. AWS SDK credential chain.

Option 1: Bedrock API key

Set the Bedrock API key in the environment Codex reads. You must specify a Region when using API-key authentication.

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

Option 2: AWS SDK credentials

Use this path when your organization manages Bedrock access through the AWS SDK credential chain. Codex can use these standard AWS SDK credential sources:

1. Shared AWS config and credentials files.

   aws configure

2. Environment variables.

   export AWS_ACCESS_KEY_ID=<your-access-key-id>
   export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
   export AWS_SESSION_TOKEN=<your-session-token>

3. AWS Management Console credentials.

   aws login

4. AWS SSO or a named profile.

   aws sso login --profile codex-bedrock
   export AWS_PROFILE=codex-bedrock

5. Federated identity configured with credential_process. For corporate SSO or OIDC federation, configure the AWS profile outside Codex and let the AWS SDK resolve credentials. Put browser login, token exchange, caching, and refresh in your AWS profile's credential_process helper.

Desktop app and VS Code extension

Desktop apps and IDE extensions may not inherit environment variables from the shell. Put required values in ~/.codex/.env, then restart the app or extension.

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

Verify setup

In Codex CLI, open /status and confirm Codex is using the

amazon-bedrock model provider.

In the desktop app or VS Code extension, start a new session after restarting

the app.

Confirm the selected model is available in the configured AWS Region and that

the AWS identity has permission to access it.

Supported models

Use exact model IDs:

openai.gpt-5.5
openai.gpt-5.4

Model availability varies by AWS Region. Before selecting a model, see model support by AWS Region.

Feature availability

This configuration supports local Codex workflows. Some features that depend on OpenAI-hosted cloud services, hosted tools, or cloud-managed discovery aren't currently available.

Fast Mode isn't available with Amazon Bedrock. Fast Mode uses priority processing, and the initial Amazon Bedrock offering supports on-demand inference only.

<sup>*</sup> Feature is currently limited to only specific regions. Check the individual feature documentation to learn more about geo restrictions. <sup>†</sup> Local plugin bundles are supported when their capabilities do not require ChatGPT authentication. OpenAI-curated plugin discovery and features that depend on app connectors or cloud-hosted sharing aren't available.

Troubleshooting

If setup fails, check the following:

The model ID exactly matches a supported model.
You specify an AWS Region where the model is available.
The Bedrock API key or AWS credentials are valid and not expired.
The AWS identity has permission to access the selected Bedrock model.
AWS_BEARER_TOKEN_BEDROCK isn't set to an expired or unintended key.
For desktop app or VS Code extension usage, required environment variables

are present in ~/.codex/.env.

Support boundaries

OpenAI Support can help with Codex client setup, configuration, local CLI behavior, desktop app behavior, IDE extension behavior, and the local Codex product experience.

For AWS credentials, IAM permissions, Bedrock model access, quotas, billing, regional availability, Bedrock request failures, AWS service logs, or Bedrock service behavior, contact the customer's AWS administrator or AWS Support.

Automations

Automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives the task if there's nothing to report. You can combine automations with skills for more complex tasks.

For project-scoped automations, the machine running the local Codex app must be powered on, Codex must be running, and the selected project must still be available on disk when the automation is scheduled to run.

In Git repositories, you can choose whether an automation runs in your local project or on a new worktree. Both options run in the background. Worktrees keep automation changes separate from unfinished local work, while running in your local project can modify files you are still working on. In non-version-controlled projects, automations run directly in the project directory.

You can also leave the model and reasoning effort on their default settings, or choose them explicitly if you want more control over how the automation runs.

Managing tasks

Find all automations and their runs in the automations pane inside your Codex app sidebar.

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

Standalone automations start fresh runs on a schedule and report results in Triage. Use them when each run should be independent or when one automation should run across one or more projects. If you need a custom cadence, choose a custom schedule and enter cron syntax.

For Git repositories, each automation can run either in your local project or on a dedicated background worktree. Use worktrees when you want to isolate automation changes from unfinished local work. Use local mode when you want the automation to work directly in your main checkout, keeping in mind that it can change files you are actively editing. In non-version-controlled projects, automations run directly in the project directory. You can have the same automation run on more than one project.

Automations use your default sandbox settings. In read-only mode, tool calls fail if they require modifying files, network access, or working with apps on your computer. With full access enabled, background automations carry elevated risk. You can adjust sandbox settings in Settings and selectively allowlist commands with rules.

Automations can use the same plugins and skills available to Codex. To keep automations maintainable and shareable across teams, use skills to define the action and provide tools and context. You can explicitly trigger a skill as part of an automation by using $skill-name inside your automation.

Ask Codex to create or update automations

You can create and update automations from a regular Codex thread. Describe the task, the schedule, and whether the automation should stay attached to the current thread or start fresh runs. Codex can draft the automation prompt, choose the right automation type, and update it when the scope or cadence changes.

For example, ask Codex to remind you in this thread while a deployment finishes, or ask it to create a standalone automation that checks a project on a recurring schedule.

Skills can also create or update automations. For example, a skill for babysitting a pull request could set up a recurring automation that checks the PR status with the GitHub plugin and fixes new review feedback.

Thread automations

Thread automations are heartbeat-style recurring wake-up calls attached to the current thread. Use them when you want Codex to keep returning to the same conversation on a schedule.

Use a thread automation when the scheduled work should preserve the thread's context instead of starting from a new prompt each time.

Thread automations can use minute-based intervals for active follow-up loops, or daily and weekly schedules when you need a check-in at a specific time.

Thread automations are useful for:

checking a long-running command until it finishes
polling Slack, GitHub, or another connected source when the results should

stay in the same thread

reminding Codex to continue a review loop at a fixed cadence
running a skill-driven workflow that uses plugins, such as checking PR status

and addressing new feedback

keeping a chat focused on an ongoing research or triage task

Use a standalone or project automation when each run should be independent, when it should run across more than one project, or when findings should appear as separate automation runs in Triage.

When you create a thread automation, make the prompt durable. It should describe what Codex should do each time the thread wakes up, how to decide whether there is anything important to report, and when to stop or ask you for input.

Test automations

Before you schedule an automation, test the prompt manually in a regular thread first. This helps you confirm:

The prompt is clear and scoped correctly.
The selected or default model, reasoning effort, and tools behave as expected.
The resulting diff is reviewable.

When you start scheduling runs, review the first few outputs and adjust the prompt or cadence as needed.

Worktree cleanup for automations

If you choose worktrees for Git repositories, frequent schedules can create many worktrees over time. Archive automation runs you no longer need, and avoid pinning runs unless you intend to keep their worktrees.

Permissions and security model

Automations run unattended and use your default sandbox settings.

If your sandbox mode is read-only, tool calls fail if they require

modifying files, accessing network, or working with apps on your computer. Consider updating sandbox settings to workspace write.

If your sandbox mode is workspace-write, tool calls fail if they require

modifying files outside the workspace, accessing network, or working with apps on your computer. You can selectively allowlist commands to run outside the sandbox using rules.

If your sandbox mode is full access, background automations carry

elevated risk, as Codex may change files, run commands, and access network without asking. Consider updating sandbox settings to workspace write, and using rules to selectively define which commands the agent can run with full access.

If you are in a managed environment, admins can restrict these behaviors using admin-enforced requirements. For example, they can disallow approval_policy = "never" or constrain allowed sandbox modes. See Admin-enforced requirements (`requirements.toml`).

Automations use approval_policy = "never" when your organization policy allows it. If admin requirements disallow approval_policy = "never", automations fall back to the approval behavior of your selected mode.

Examples

Automatically create new skills

Scan all of the `~/.codex/sessions` files from the past day and if there have been any issues using particular skills, update the skills to be more helpful. Personal skills only, no repo skills.

If there’s anything we’ve been doing often and struggle with that we should save as a skill to speed up future work, let’s do it.

Definitely don't feel like you need to update any- only if there's a good reason!

Let me know if you make any.

Stay up-to-date with your project

Look at the latest remote origin/master or origin/main . Then produce an exec briefing for the last 24 hours of commits that touch <DIRECTORY>

Formatting + structure:

- Use rich Markdown (H1 workstream sections, italics for the subtitle, horizontal rules as needed).
- Preamble can read something like “Here’s the last 24h brief for <directory>:”
- Subtitle should read: “Narrative walkthrough with owners; grouped by workstream.”
- Group by workstream rather than listing each commit. Workstream titles should be H1.
- Write a short narrative per workstream that explains the changes in plain language.
- Use bullet points and bolding when it makes things more readable
- Feel free to make bullets per person, but bold their name

Content requirements:

- Include PR links inline (e.g., [#123](...)) without a “PRs:” label.
- Do NOT include commit hashes or a “Key commits” section.
- It’s fine if multiple PRs appear under one workstream, but avoid per‑commit bullet lists.

Scope rules:

- Only include changes within the current cwd (or main checkout equivalent)
- Only include the last 24h of commits.
- Use `gh` to fetch PR titles and descriptions if it helps.
  Also feel free to pull PR reviews and comments

Combining automations with skills to fix your own bugs

Create a new skill that tries to fix a bug introduced by your own commits by creating a new $recent-code-bugfix and store it in your personal skills.

---
name: recent-code-bugfix
description: Find and fix a bug introduced by the current author within the last week in the current working directory. Use when a user wants a proactive bugfix from their recent changes, when the prompt is empty, or when asked to triage/fix issues caused by their recent commits. Root cause must map directly to the author’s own changes.
---

# Recent Code Bugfix

## Overview

Find a bug introduced by the current author in the last week, implement a fix, and verify it when possible. Operate in the current working directory, assume the code is local, and ensure the root cause is tied directly to the author’s own edits.

## Workflow

### 1) Establish the recent-change scope

Use Git to identify the author and changed files from the last week.

- Determine the author from `git config user.name`/`user.email`. If unavailable, use the current user’s name from the environment or ask once.
- Use `git log --since=1.week --author=<author>` to list recent commits and files. Focus on files touched by those commits.
- If the user’s prompt is empty, proceed directly with this default scope.

### 2) Find a concrete failure tied to recent changes

Prioritize defects that are directly attributable to the author’s edits.

- Look for recent failures (tests, lint, runtime errors) if logs or CI outputs are available locally.
- If no failures are provided, run the smallest relevant verification (single test, file-level lint, or targeted repro) that touches the edited files.
- Confirm the root cause is directly connected to the author’s changes, not unrelated legacy issues. If only unrelated failures are found, stop and report that no qualifying bug was detected.

### 3) Implement the fix

Make a minimal fix that aligns with project conventions.

- Update only the files needed to resolve the issue.
- Avoid adding extra defensive checks or unrelated refactors.
- Keep changes consistent with local style and tests.

### 4) Verify

Attempt verification when possible.

- Prefer the smallest validation step (targeted test, focused lint, or direct repro command).
- If verification cannot be run, state what would be run and why it wasn’t executed.

### 5) Report

Summarize the root cause, the fix, and the verification performed. Make it explicit how the root cause ties to the author’s recent changes.

Afterward, create a new automation:

Check my commits from the last 24h and submit a $recent-code-bugfix.

In-app browser

The in-app browser gives you and Codex a shared view of rendered web pages inside a thread. Use it when you're building or debugging a web app and want to preview pages and attach visual comments.

Use it for local development servers, file-backed previews, and public pages that don't require sign-in. For anything that depends on login state or browser extensions, use your regular browser or the Codex Chrome extension.

Open the in-app browser from the toolbar, by clicking a URL, by navigating manually in the browser, or by pressing Cmd+Shift+B (Ctrl+Shift+B on Windows).

The in-app browser does not support authentication flows, signed-in pages, your regular browser profile, cookies, extensions, or existing tabs. Use it for pages Codex can open without logging in.

Treat page content as untrusted context. Don't paste secrets into browser flows.

Browser use

Browser use lets Codex operate the in-app browser directly. Use it for local development servers and file-backed previews when Codex needs to click, type, inspect rendered state, take screenshots, download page assets, run read-only page inspection JavaScript, or verify a fix in the page.

To use it, install and enable the Browser plugin. Then ask Codex to use the browser in your task, or reference it directly with @Browser. The app keeps browser use inside the in-app browser and lets you manage allowed and blocked websites from settings.

Example:

Use the browser to open http://localhost:3000/settings, reproduce the layout
bug, and fix only the overflowing controls.

Codex asks before using a website unless you've allowed it. Removing a site from the allowed list means Codex asks again before using it; removing a site from the blocked list means Codex can ask again instead of treating it as blocked.

For signed-in websites in Chrome, see Codex Chrome extension.

Preview a page

1. Start your app's development server in the integrated terminal or with a local environment action. 2. Open an unauthenticated local route, file-backed page, or public page by clicking a URL or navigating manually in the browser. 3. Review the rendered state alongside the code diff. 4. Leave browser comments on the elements or areas that need changes. 5. Ask Codex to address the comments and keep the scope narrow.

Example feedback:

I left comments on the pricing page in the in-app browser. Address the mobile
layout issues and keep the card structure unchanged.

Comment on the page

When a bug is visible only in the rendered page, use browser comments to give Codex precise feedback on the page.

Turn on Annotation mode, select an element or area, and submit a comment.
In Annotation mode, hold Shift and click to select an area.
Hold Cmd while clicking to send a comment immediately.

After you leave comments, send a message in the thread asking Codex to address them. Comments are most useful when Codex needs to make a precise visual change.

Good feedback is specific:

This button overflows on mobile. Keep the label on one line if it fits,
otherwise wrap it without changing the card height.

This tooltip covers the data point under the cursor. Reposition the tooltip so
it stays inside the chart bounds.

Styling feedback

When you add an annotation to a section on the page, press the config icon next to the text input to give Codex more granular style feedback. You can change values like font, text, spacing, and color, preview the result directly on the page, and then send the annotation so Codex has a clearer target for the change.

Keep browser tasks scoped

The in-app browser is for review and iteration. Keep each browser task small enough to review in one pass.

Name the page, route, or local URL.
Name the visual state you care about, such as loading, empty, error, or

success.

Leave comments on the exact elements or areas that need changes.
Review the updated route after Codex changes the code.
Ask Codex to start or check the dev server before it uses the browser.

For repository changes, use the review pane to inspect the changes and leave comments.

Developer mode

Developer mode works with Browser use in Chrome and the Codex in-app browser. It gives Codex controlled access to the Chrome DevTools Protocol (CDP). Use it when you want Codex to profile JavaScript, inspect console output and network traffic, examine page state such as the DOM and applied styles, or diagnose an issue directly in the live browser.

To enable it, open **Settings > Browser** and, under Developer mode, turn on Enable full CDP access. If your organization has disabled this setting, you can't enable it locally. Admins can set browser_use_full_cdp_access = false under [features] in `requirements.toml`.

Full CDP access lets Codex inspect and control sensitive browser internals that may put your data at risk. Codex asks for explicit approval before it uses full CDP to inspect a website. Review the site, task, and requested access before you approve it.

Use @Browser for the in-app browser. To use Developer mode in Chrome, set up the Codex Chrome extension and invoke @Chrome.

For example:

This app is slow. Use @Browser to capture a performance trace and inspect
network traffic, then identify the bottleneck.

Codex Chrome extension

The Codex Chrome extension lets Codex use Chrome for browser tasks that need your signed-in browser state. Use it when Codex needs to read or act on sites such as LinkedIn, Salesforce, Gmail, or internal tools.

For local development servers, file-backed previews, and public pages that do not require sign-in, use the in-app browser first. The in-app browser keeps preview and verification work inside Codex without using your Chrome profile.

Codex can also switch between tools as a task requires, using plugins when a dedicated integration is available, Chrome when it needs logged-in browser context, and the in-app browser for localhost.

Set up Chrome from Plugins

Set up the extension from Codex:

1. Open Codex and go to Plugins. 2. Add the Chrome plugin. 3. Follow the setup flow. It guides you through installing the Codex Chrome extension and approving Chrome's permission prompts. 4. Open Chrome and confirm the Codex extension shows Connected.

After the plugin setup is complete, start a new Codex thread. Codex can suggest Chrome when a task needs a signed-in website. You can also invoke it directly in a prompt:

@Chrome open Salesforce and update the account from these call notes.

If Chrome isn't already open, Codex can open it. Chrome browser tasks run in Chrome tab groups so the work for a thread stays grouped together.

Control website access

By default, Codex asks before it interacts with each new website. Codex bases the prompt on the website host, such as example.com.

When Codex asks to use a website, you can choose the option that matches the task and your risk tolerance:

Allow the website for the current chat.
Always allow the host so Codex can use that website again without asking.
Decline the website.

Manage the allowlist and blocklist

In Computer Use settings, you can manage an allowlist and blocklist for domains. The allowlist contains domains Codex can use without asking again. The blocklist contains domains Codex shouldn't use.

Removing a domain from the allowlist means Codex asks again before using it. Removing a domain from the blocklist means Codex can ask again instead of treating the domain as blocked.

Always allow browser content

If you turn on always allow browser content, Codex no longer asks for confirmation before using websites.

Browser history

Browser history can include sensitive telemetry, internal URLs, search terms, and activity from Chrome sessions on signed-in devices. If you allow Codex to access browser history, relevant history entries can become part of the context Codex uses for the task. Malicious or misleading page content can increase the risk that Codex copies this data somewhere unintended.

Codex asks when it wants to use browser history. Codex scopes history access to the request, and history doesn't have an always-allow option.

Data and security

Chrome extension permissions

Chrome asks you to accept extension permissions when you install the extension. The permission prompt may include:

Access the page debugger
Read and change all your data on all websites
Read and change your browsing history on all your signed-in devices
Display notifications
Read and change your bookmarks
Manage your downloads
Communicate with cooperating native applications
View and manage your tab groups

These Chrome permissions make the extension capable of operating browser workflows. Codex still uses its own confirmations, settings, allowlists, and blocklists before using websites or browser history during a task.

Memories

Browser use follows your Codex Memories setting. If Memories is on, Codex can use relevant saved memories while working in Chrome. If Memories is off, browser use doesn't use memories.

What OpenAI stores from browsing

OpenAI doesn't store a separate complete record of your Chrome actions from the extension. OpenAI stores browser activity only when it becomes part of the Codex context, such as text Codex reads from a page, screenshots, tool calls, summaries, messages, or other content included in the thread.

Your ChatGPT and Codex data controls apply to content processed in context. Avoid sending secrets or highly sensitive data through browser tasks unless they're required and you are present to review each prompt.

Troubleshooting

If Codex can't connect to Chrome, first confirm the website Codex is trying to access isn't in the blocklist in Settings. If the website isn't blocked, work through these checks:

1. Open the Codex extension from the Chrome toolbar or Chrome's extensions menu. Make sure it shows Connected. If it shows disconnected or mentions a missing native host, remove and re-add the Chrome plugin from Plugins in Codex, then follow the setup flow again. 2. In Codex, open Plugins and confirm that the Chrome plugin is on. If the plugin is off, turn it on and try the task again. 3. Make sure you are using the same Chrome profile where the Codex extension is installed. If you use more than one Chrome profile, install and enable the extension in the active profile. 4. Start a new Codex thread and try the Chrome task again. This can clear a thread-specific connection state. 5. Restart Chrome and Codex, then try again. If the extension still doesn't connect, uninstall the Codex Chrome extension, remove and re-add the Chrome plugin from Plugins, and follow the setup flow again. 6. If the extension shows Connected but Codex still can't use Chrome, run /feedback in the Codex app and include the thread ID when you contact support.

Upload Files

If a Chrome task needs to upload a file from your computer, allow the Codex extension to access file URLs in Chrome:

1. In Chrome, open the extensions icon in the toolbar, then click Manage Extensions. 2. On the Codex extension card, click Details. 3. Turn on Allow access to file URLs.

After you change the setting, start the Chrome task again.

Codex app commands

Use these commands and keyboard shortcuts to navigate the Codex app.

Keyboard shortcuts

	Action	macOS shortcut
General
	Command menu	`Cmd` + `Shift` + `P` or `Cmd` + `K`
	Settings	`Cmd` + `,`
	Keyboard shortcuts	`Cmd` + `/`
	Open folder	`Cmd` + `O`
	Navigate back	`Cmd` + `[`
	Navigate forward	`Cmd` + `]`
	Increase font size	`Cmd` + `+` or `Cmd` + `=`
	Decrease font size	`Cmd` + `-` or `Cmd` + `\_`
	Toggle sidebar	`Cmd` + `B`
	Toggle diff panel	`Cmd` + `Option` + `B`
	Toggle terminal	`Cmd` + `J`
	Clear the terminal	`Ctrl` + `L`
Thread
	New thread	`Cmd` + `N` or `Cmd` + `Shift` + `O`
	Search threads	`Cmd` + `G`
	Find in thread	`Cmd` + `F`
	Previous thread	`Cmd` + `Shift` + `[`
	Next thread	`Cmd` + `Shift` + `]`
	Dictation	`Ctrl` + `M`

To find, customize, or reset shortcuts, open Settings > Keyboard Shortcuts. You can search by command name or switch the search field into keystroke mode and press the shortcut you want to find.

Search past threads and find in a thread

Use thread search (Cmd/Ctrl + G) to reopen a past conversation. When expanded matching is available in your Codex desktop app, it can also match conversation content and Git branch names, so you can search for a phrase from the thread or a branch such as fix/login-redirect.

Use Find in thread (Cmd + F) after opening a thread to find text within that current conversation. It doesn't search across other threads.

Slash commands

Slash commands let you control Codex without leaving the thread composer. Available commands vary based on your environment and access.

Use a slash command

1. In the thread composer, type /. 2. Select a command from the list, or keep typing to filter (for example, /status).

You can also explicitly invoke skills by typing $ in the thread composer. See Skills.

Enabled skills also appear in the slash command list.

Available slash commands

Slash command	Description
`/feedback`	Open the feedback dialog to submit feedback and optionally include logs.
`/goal`	Set a persistent goal for Codex to work toward; use `/plan` first to shape it.
`/init`	Generate an `AGENTS.md` scaffold for the current project.
`/mcp`	Open MCP status to view connected servers.
`/plan`	Toggle plan mode for multi-step planning.
`/review`	Start code review mode to review uncommitted changes or compare against a base branch.
`/status`	Show the thread ID, context usage, and rate limits.

Set or manage a goal with `/goal`

Use /goal in the app composer to start Goal mode. A goal is a persistent objective that Codex works toward until it finishes the task, pauses, or needs more input. To define the goal with Codex first, start with /plan, then set the refined goal with /goal.

If /goal doesn't appear in the slash command list, enable features.goals in config.toml:

[features]
goals = true

You can also run codex features enable goals from the CLI or ask Codex to run it.

When a goal is active, the app shows its progress above the composer. Use the buttons in that progress row to pause or resume the goal, edit the goal text, or clear the goal instead of typing another slash command. You can keep steering Codex with follow-up messages while the goal runs.

For guidance on writing effective goals, see Goal mode.

Deep links

The Codex app registers the codex:// URL scheme so links can open specific parts of the app directly. Encode query string values before adding them to a URL.

Supported links

Use these canonical forms when you create links. The sections below list the full reference by link type.

Deep link	Opens
`codex://threads/new`	A new local thread.
`codex://new?<query>`	A new local thread with at least one new-thread query parameter.
`codex://threads/<thread-id>`	A local thread. `<thread-id>` must be the thread's session UUID.
`codex://settings`	Settings.
`codex://settings/connections/<connection-type>`	Computer, device, or SSH connection settings.
`codex://settings/connections/ssh/add?name=<ssh-config-host>`	Adds a host from your SSH config to Codex.
`codex://skills`	Skills.
`codex://automations`	Automations with the create flow open.
`codex://plugins/install/<plugin-name>?marketplace=<marketplace-name>`	The install flow for a plugin from a known marketplace.
`codex://plugins/<plugin-id>`	A plugin detail page.
`codex://plugins/<plugin-name>?marketplacePath=<absolute-marketplace-path>`	A local plugin detail page from a local marketplace.
`codex://pets/install?name=<pet-name>&imageUrl=<https-image-url>`	The pet install flow.

Threads

Use these links when you need to open an existing local thread or start a new one.

Deep link	Opens
`codex://threads/<thread-id>`	A local thread. `<thread-id>` must be the thread's session UUID.
`codex://threads/new`	A new local thread.
`codex://threads/new?<query>`	A new local thread with optional query parameters.
`codex://new?<query>`	A new local thread. Include at least one of `prompt`, `path`, or `originUrl`; otherwise the link does nothing.

For codex://threads/new or codex://new, add any of these query parameters as needed; you can combine them in the same URL.

Query parameter	Required	What it does
`prompt=<text>`	No	Sets the initial composer text.
`path=<absolute-path>`	No	Opens the new thread in a local workspace. `path` must be an absolute path to a local directory. When valid, Codex uses that directory as the active workspace.
`originUrl=<git-remote-url>`	No	Matches one of your current workspace roots by Git remote URL. If `path` is also present, Codex resolves `path` first.

Example: Show me some fun stats about how I've been using Codex

Settings

Use these links when you need to open Settings or a specific settings page.

Deep link	Opens
`codex://settings`	Settings.
`codex://settings/browser-use`	Browser settings.
`codex://settings/computer-use/google-chrome`	Google Chrome settings for computer use.
`codex://settings/connections`	Remote connections settings.
`codex://settings/connections/computer`	Settings for controlling this Mac or PC from another device.
`codex://settings/connections/devices`	Settings for controlling other devices.
`codex://settings/connections/ssh`	SSH connection settings.
`codex://settings/connections/ssh/add?name=<ssh-config-host>`	Adds the named host alias as a Codex-managed connection, then opens SSH connection settings.

The name value must match a host alias in ~/.ssh/config. The link disables automatic connection for the added host. If Codex can't find the named host, it opens SSH connection settings and shows an error.

Unsupported codex://settings/... paths open the main Settings page.

Skills

Use these links when you need to open Skills.

Deep link	Opens
`codex://skills`	Skills.

Automations

Use these links when you need to open Automations.

Deep link	Opens
`codex://automations`	Automations with the create flow open.

Plugins

Plugin links use different forms depending on whether you are installing from a marketplace, opening a plugin, or working from a local marketplace.json. For plugin basics, see Plugins. For local or repo marketplace setup, see Build plugins.

Plugin install

Use this form to open the install flow for a plugin from a marketplace that Codex already knows about.

Deep link	Opens
`codex://plugins/install/<plugin-name>?marketplace=<marketplace-name>`	The plugin detail or install flow for a plugin.

Query parameter	Required	What it does
`marketplace=<marketplace-name>`	Yes	Identifies the marketplace. For an OpenAI-curated plugin, use `openai-curated`.

The install link accepts only the marketplace query parameter. If Codex can't find the requested marketplace or plugin, it opens the Plugins page instead.

Plugin detail

Deep link	Opens
`codex://plugins/<plugin-id>`	A plugin detail page.

<plugin-id> must identify the plugin. For an OpenAI-curated plugin, use the form <plugin-name>@openai-curated.

Codex-generated plugin links can also include these query parameters. Omit both when you write a link manually.

Query parameter	Required	What it does
`hostId=<host-id>`	No	Identifies the Codex host that owns the plugin context, such as `local` or one of your configured remote connections. Codex provides these IDs.
`source=manage`	No	Preserves the app's plugin-management entry point. It's not admin-only.

Example: Open the OpenAI Developers plugin

Local plugin

For local or repo marketplace setup, see Build plugins.

Deep link	Opens
`codex://plugins/<plugin-name>?marketplacePath=<absolute-marketplace-path>`	A local plugin detail page from a local marketplace.

Query parameter	Required	What it does
`marketplacePath=<absolute-marketplace-path>`	Yes	Absolute path to the local `marketplace.json`, for example `/Users/alex/.agents/plugins/marketplace.json`.
`mode=share`	No	Opens the share flow for that local plugin.

Pets

Use these links to open the pet install flow when that feature is enabled.

Deep link	Opens
`codex://pets/install?name=<pet-name>&imageUrl=<https-image-url>`	The pet install flow.

Query parameter	Required	What it does
`name=<pet-name>`	Yes	Sets the pet name.
`imageUrl=<https-image-url>`	Yes	Sets the pet image URL. `imageUrl` must be HTTPS.
`description=<text>`	No	Sets the optional pet description.

Computer Use

In supported regions, computer use in the Codex app is available on macOS and Windows. Install the Computer Use plugin. On macOS, grant Screen Recording and Accessibility permissions when prompted.

With computer use, Codex can see and operate graphical user interfaces on macOS or Windows. Use it for tasks where command-line tools or structured integrations aren't enough, such as checking a desktop app, using a browser, changing app settings, working with a data source that isn't available as a plugin, or reproducing a bug that only happens in a graphical user interface.

Because computer use can affect app and system state outside your project workspace, use it for scoped tasks and review permission prompts before continuing.

Set up computer use

In Codex settings, open Computer Use and click Install to install the Computer Use plugin before you ask Codex to operate desktop apps. On Windows, keep the target app visible on the active desktop while the task runs. On macOS, grant Screen Recording and Accessibility permissions when prompted so Codex can see and interact with the target app.

On macOS, grant:

Screen Recording permission so Codex can see the target app.
Accessibility permission so Codex can click, type, and navigate.

When to use computer use

Choose computer use when the task depends on a graphical user interface that's hard to verify through files or command output alone.

Good fits include:

Testing a macOS app, Windows app, iOS simulator flow, or another desktop app

that Codex is building.

Performing a task that requires your web browser.
Reproducing a bug that only appears in a graphical interface.
Changing app settings that require clicking through a UI.
Inspecting information in an app or data source that isn't available through a

plugin.

On macOS, running a scoped task in the background while you keep working

elsewhere.

Executing a workflow that spans more than one app.

For web apps you are building locally, use the in-app browser first.

Windows foreground use

On Windows, computer use runs on the active desktop. It can't operate in the background while you keep using the same Windows session, so expect Codex to move the pointer, type, and take over the foreground while the task runs.

For Windows tasks that should continue while you step away, keep the Windows device unlocked and connected to the internet. Use remote control from your phone to check progress or send follow-up instructions, or run the Codex app inside a Windows virtual machine so computer use takes over the VM instead of your main desktop.

Start a computer use task

Mention @Computer or @AppName in your prompt, or ask Codex to use computer use. Describe the exact app, window, or flow Codex should operate.

Open the app with computer use, reproduce the onboarding bug, and fix the
smallest code path that causes it. After each change, run the same UI flow
again.

Open @Chrome and verify the checkout page still works after the latest changes.

If the target app exposes a dedicated plugin or MCP server, prefer that structured integration for data access and repeatable operations. Choose computer use when Codex needs to inspect or operate the app visually.

Permissions and approvals

System permissions for computer use are separate from app approvals in Codex. On macOS, Screen Recording and Accessibility permissions let Codex see and operate apps. App approvals determine which apps you allow Codex to use. File reads, file edits, and shell commands still follow the sandbox and approval settings for the thread.

With computer use, Codex can see and take action only in the apps you allow. During a task, Codex asks for your permission before it can use an app on your computer. You can choose Always allow so Codex can use that app in the future without asking again. You can remove apps from the Always allow list in the Computer Use section of Codex settings.

Codex may also ask for permission before taking sensitive or disruptive actions.

If Codex can't see or control an app, open System Settings > Privacy & Security and check Screen Recording and Accessibility for the Codex app on macOS. On Windows, make sure the target app is visible in the active desktop session.

On Windows, Computer Use stores persistent app decisions in $CODEX_HOME/computer-use/config.toml. List apps that Computer Use can open without prompting and apps that it must decline:

[apps]
allowed = ["mspaint.exe"]
denied = ["calc.exe"]

Use the app identifier that Windows Computer Use reports, such as an executable name for a desktop app or an app user model ID for a packaged app. Denied apps take precedence over allowed apps. Codex prompts for apps that don't appear in either list.

This file stores local Computer Use decisions. It's separate from the admin-enforced requirements.toml, where administrators can disable Computer Use with [features].computer_use = false.

Locked use

Locked use is for macOS. On Windows, computer use works in the foreground.

Locked computer use lets Codex use Computer Use after your Mac locks, but only after you enable it. Use it when a Codex task needs to use desktop apps from a connected device after the Mac locks.

When you enable locked computer use, Codex installs an Apple authorization plug-in that participates in the macOS unlock flow.

Locked use is intentionally narrow. It's not a general-purpose remote-unlock path for your Mac, and it doesn't let other apps or local processes unlock the computer.

To use locked computer use:

1. Open Codex settings > Computer Use. 2. Enable locked computer use. 3. Start a task that uses computer use from a connected device after your Mac's screen has locked.

When a Codex task accesses an app via Computer Use after your Mac locks, Codex temporarily unlocks the Mac while blocking local use and preserving the locked screen protections. Before unlocking, Codex checks whether the unlock attempt is for an active, trusted computer use turn. Outside that short-lived window, Codex denies the unlock and asks you to unlock manually if needed.

Locked use includes safeguards:

The authorization window is short-lived and scoped to the current unlock

attempt.

Automatic unlock is available only to Codex during active computer use turns.
Codex covers every display while the desktop is temporarily unlocked.
If Codex detects local keyboard or pointer input, it relocks the Mac and

pauses automatic unlock until you unlock it manually.

Safety guidance

With computer use, Codex can view screen content, take screenshots, and interact with windows, menus, keyboard input, and clipboard state in the target app. Treat visible app content, browser pages, screenshots, and files opened in the target app as context Codex may process while the task runs.

Keep tasks narrow and stay present for sensitive flows:

Give Codex one clear target app or flow at a time.
You can stop the task or take over your computer at any time.
Keep sensitive apps closed unless they're required for the task.
On Windows, expect Codex to take over foreground input while it works; use a

secondary device, a VM, or stop the task before using that desktop yourself.

Avoid tasks that require secrets unless you're present and can approve each

step.

Review app permission prompts before allowing Codex to use an app.
Use Always allow only for apps you trust Codex to use automatically in

future tasks.

Stay present for account, security, privacy, network, payment, or

credential-related settings.

Cancel the task if Codex starts interacting with the wrong window.

If Codex uses your browser, it can interact with pages where you're already signed in. Review website actions as if you were taking them yourself: web pages can contain malicious or misleading content, and sites may treat approved clicks, form submissions, and signed-in actions as coming from your account. To keep using your browser while Codex works, ask Codex to use a different browser.

The feature can't automate terminal apps or Codex itself, since automating them could bypass Codex security policies. It also can't authenticate as an administrator or approve security and privacy permission prompts on your computer.

File edits and shell commands still follow Codex approval and sandbox settings where applicable. Changes made through desktop apps may not appear in the review pane until they're saved to disk and tracked by the project. Your ChatGPT data controls apply to content processed through Codex, including screenshots taken by computer use.

Codex app features

The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.

Most Codex app features are available on both macOS and Windows. The sections below note platform-specific exceptions.

---

Multitask across projects

Use one Codex app window to run tasks across projects. Add a project for each codebase and switch between them as needed.

When available in your Codex desktop app, you can ask Codex to manage threads in your local projects or worktrees. For example, ask it to find a related thread, continue an existing thread, or pin or archive a thread. To create a separate background thread, make that request explicit: Create a separate background thread in a worktree for this project to update the tests.

If you've used the Codex CLI, a project is like starting a session in a specific directory.

If you work in a single repository with two or more apps or packages, split distinct projects into separate app projects so the sandbox only includes the files for that project.

Skills support

The Codex app supports the same agent skills as the CLI and IDE Extension. You can also view and explore new skills that your team has created across your different projects by clicking Skills in the sidebar.

Automations

You can also combine skills with automations to perform routine tasks such as evaluating errors in your telemetry and submitting fixes or creating reports on recent codebase changes. For ongoing work that should stay in one thread, use a thread automation.

Modes

Each thread runs in a selected mode. When starting a thread, you can choose:

Local: work directly in your current project directory.
Worktree: isolate changes in a Git worktree. Learn more.
Cloud: run remotely in a configured cloud environment.

Both Local and Worktree threads will run on your computer.

For the full glossary and concepts, explore the concepts section.

Built-in Git tools

The Codex app provides common Git features directly within the app.

The diff pane shows a Git diff of your changes in your local project or worktree checkout. You can also add inline comments for Codex to address and stage or revert specific chunks or entire files.

You can also commit, push, and create pull requests for local and worktree tasks directly from within the Codex app.

For more advanced Git tasks, use the integrated terminal.

Worktree support

When you create a new thread, choose Local or Worktree. Local works directly within your project. Worktree creates a new Git worktree so changes stay isolated from your regular project.

Use Worktree when you want to try a new idea without touching your current work, or when you want Codex to run independent tasks side by side in the same project.

Automations run in dedicated background worktrees for Git repositories, and directly in the project directory for non-version-controlled projects.

Learn more about using worktrees in the Codex app.

Integrated terminal

Each thread includes a built-in terminal scoped to the current project or worktree. Toggle it using the terminal icon in the top right of the app or by pressing Cmd+J.

Use the terminal to validate changes, run scripts, and perform Git operations without leaving the app. Codex can also read the current terminal output, so it can check the status of a running development server or refer back to a failed build while it works with you.

Common tasks include:

git status
git pull --rebase
pnpm test or npm test
pnpm run lint or similar project commands

If you run a task regularly, you can define an action inside your local environment to add a shortcut button to the top of your Codex app window.

Note that Cmd+K opens the command palette in the Codex app. It doesn't clear the terminal. To clear the terminal use Ctrl+L.

Native Windows sandbox

On Windows, Codex can run natively in PowerShell with a native Windows sandbox instead of requiring WSL or a virtual machine. This lets you stay in Windows-native workflows while keeping bounded permissions in place.

Learn more about Windows setup and sandboxing.

Voice dictation

Use your voice to prompt Codex. Hold Ctrl+M while the composer is visible and start talking. Your voice will be transcribed. Edit the transcribed prompt or hit send to have Codex start work.

Floating pop-out window

Pop out an active conversation thread into a separate window and move it to where you are actively working. This is ideal for front-end work, where you can keep the thread near your browser, editor, or design preview while iterating quickly.

You can also toggle the pop-out window to stay on top when you want it to remain visible across your workflow.

In-app browser

Use the in-app browser to preview, review, and comment on local development servers, file-backed previews, and public pages that don't require sign-in while you iterate on a web app.

The in-app browser doesn't support authentication flows, signed-in pages, your regular browser profile, cookies, extensions, or existing tabs.

Use browser comments to mark specific elements or areas on a page, then ask Codex to address that feedback.

When you want Codex to operate the page directly, use browser use for local development servers and file-backed pages. You can manage the Browser plugin, allowed websites, and blocked websites from settings.

Computer use

Computer use helps Codex operate a macOS or Windows app by seeing, clicking, and typing. This is useful for testing desktop apps, checking browser or simulator flows, working with data sources that aren't available as plugins, changing app settings, and reproducing GUI-only bugs.

Because computer use can affect app and system state outside your project workspace, keep tasks narrow and review permission prompts before continuing.

Work with non-code artifacts

When a task produces non-code artifacts, the sidebar can preview PDF files, spreadsheets, documents, and presentations. Give Codex the source data, expected file type, structure, and review criteria you care about.

For spreadsheets and presentations, describe the sheets, columns, charts, slide sections, and checks that matter. Ask Codex to explain where it saved the output and how it checked the result.

Use the task sidebar to follow what Codex is doing while a thread runs. It can surface the agent's plan, sources, generated artifacts, and task summary so you can steer the work, inspect generated files, and decide what needs another pass.

---

Sync with the IDE extension

If you have the Codex IDE Extension installed in your editor, your Codex app and IDE Extension automatically sync when both are in the same project.

When they sync, you see an IDE context option in the Codex app composer. With "Auto context" enabled, the Codex app tracks the files you're viewing, so you can reference them indirectly (for example, "What's this file about?"). You can also see threads running in the Codex app inside the IDE Extension, and vice versa.

If you're unsure whether the app includes context, toggle it off and ask the same question again to compare results.

Thread automations

Automations can also attach to a single thread. These thread automations are recurring wake-up calls that preserve the thread's context so Codex can check on long-running work, poll a source for new information, or continue a follow-up loop. Use them for heartbeat-style automations that should keep returning to the same conversation on a schedule.

Use a thread automation when the next run depends on the current conversation. Use a standalone or project automation when you want Codex to start a fresh recurring task for one or more projects.

Approvals and sandboxing

Your approval and sandbox settings constrain Codex actions.

Approvals determine when Codex pauses for permission before running a command.
The sandbox controls which directories and network access Codex can use.

When you see prompts like “approve once” or “approve for this session,” you are granting different scopes of permission for tool execution. If you are unsure, approve the narrowest option and continue iterating.

By default, Codex scopes work to the current project. In most cases, that's the right constraint.

If your task requires work across more than one repository or directory, prefer opening separate projects or using worktrees rather than asking Codex to roam outside the project root.

If automatic review is available in your workspace, you can choose it from the permissions selector. It keeps the same sandbox boundary but routes eligible approval requests through the configured review policy instead of waiting for you.

For a high-level overview, see sandboxing. For configuration details, see the agent approvals & security documentation.

MCP support

The Codex app, CLI, and IDE Extension share Model Context Protocol (MCP) settings. If you've already configured MCP servers in one, they're automatically adopted by the others. To configure new servers, open the MCP section in the app's settings and either enable a recommended server or add a new server to your configuration.

Web search

Codex ships with a first-party web search tool. For local tasks in the Codex app, Codex enables web search by default and serves results from a web search cache. If you configure your sandbox for full access, web search defaults to live results. See Config basics to disable web search or switch to live results that fetch the most recent data.

Image generation

Ask Codex to generate or edit images directly in a thread. This is useful for UI assets, banners, backgrounds, illustrations, sprite sheets, and placeholders you want to create alongside code. Add a reference image when you want Codex to transform or extend an existing asset.

You can ask in natural language or explicitly invoke the image generation skill by including $imagegen in your prompt.

Built-in image generation uses gpt-image-2, counts toward your general Codex usage limits, and uses included limits 3-5x faster on average than similar turns without image generation, depending on image quality and size. For details, see Pricing. For prompting tips and model details, see the image generation guide.

For larger batches of image generation, set OPENAI_API_KEY in your environment variables and ask Codex to generate images through the API so API pricing applies instead.

Image input

You can drag and drop images into the prompt composer to include them as context. Hold down Shift while dropping an image to add the image to the context.

You can also ask Codex to view images on your system. By giving Codex tools to take screenshots of the app you are working on, Codex can verify the work it's doing.

Chats

Chats are threads you can start when the task doesn't need a specific project folder or Git repository. Use them for research, triage, planning, plugin-heavy workflows, and other conversations where Codex should use connected tools instead of editing a codebase.

Chats use a Codex-managed threads directory under your Codex home as their working location. By default, that location is ~/.codex/threads.

Memories

Memories, where available, let Codex carry useful context from past tasks into future threads. They're most useful for stable preferences, project conventions, recurring work patterns, and known pitfalls that would otherwise need to repeat.

Notifications

By default, the Codex app sends notifications when a task completes or needs approval while the app is in the background.

In the Codex app settings, you can choose to never send notifications or always send them, even when the app is in focus.

Keep your computer awake

Since your tasks might take a while to complete, you can have the Codex app prevent your computer from going to sleep by enabling the "Prevent sleep while running" toggle in the app's settings.

Local environments

Local environments let you configure setup steps for worktrees as well as common actions for a project.

You configure your local environments through the Codex app settings pane. You can check the generated file into your project's Git repository to share with others.

Codex stores this configuration inside the .codex folder at the root of your project. If your repository contains more than one project, open the project directory that contains the shared .codex folder.

Setup scripts

Since worktrees run in different directories than your local tasks, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new thread.

Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.

For example, for a TypeScript project you might want to install the dependencies and do an initial build using a setup script:

npm install
npm run build

If your setup is platform-specific, define setup scripts for macOS, Windows, or Linux to override the default.

Actions

Use actions to define common tasks like starting your app's development server or running your test suite. These actions appear in the Codex app top bar for quick access. The actions will be run within the app's integrated terminal.

Actions are helpful to keep you from typing common actions like triggering a build for your project or starting a development server. For one-off quick debugging you can use the integrated terminal directly.

For example, for a Node.js project you might create a "Run" action that contains the following script:

npm start

If the commands for your action are platform-specific, define platform-specific scripts for macOS, Windows, and Linux.

To identify your actions, choose an icon associated with each action.

Related skills

Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k

Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k

CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k

Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k

Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72

Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10

AI & Agent Buildingagents

About

Codex Docs by the numbers

Add your badge

What it does

Files

Glossary

Agent approvals & security

Sandbox and approvals

Network access

Network isolation

Network policy

Local and private destinations

DNS rebinding protections

Dangerous settings

Defaults and recommendations

Protected paths in writable roots

Run without approval prompts

Automatic approval reviews

Common sandbox and approval combinations

Configuration in config.toml

Test the sandbox locally

OS-level sandbox

Run Codex in Dev Containers

Version control

Monitoring and telemetry

Overview

Enable OTel (opt-in)

Event categories

Security and privacy guidance

Managed configuration

Use Codex with Amazon Bedrock

How it works

Before you start

Configure Codex

Authentication options

Option 1: Bedrock API key

Option 2: AWS SDK credentials

Desktop app and VS Code extension

Verify setup

Supported models

Feature availability

Troubleshooting

Support boundaries

Automations

Managing tasks

Ask Codex to create or update automations

Thread automations

Test automations

Worktree cleanup for automations

Permissions and security model

Examples

Automatically create new skills

Stay up-to-date with your project

Combining automations with skills to fix your own bugs

In-app browser

Browser use

Preview a page

Comment on the page

Styling feedback

Keep browser tasks scoped

Developer mode

Codex Chrome extension

Set up Chrome from Plugins

Control website access

Manage the allowlist and blocklist

Always allow browser content

Browser history

Data and security

Chrome extension permissions

Memories

What OpenAI stores from browsing

Troubleshooting

Upload Files

Codex app commands

Keyboard shortcuts

Search past threads and find in a thread

Slash commands

Use a slash command

Available slash commands

Set or manage a goal with /goal

Configuration in `config.toml`

Set or manage a goal with `/goal`