OpenAI Codex

Setup for Codex CLI

OpenAI Codex Integration Guide

Complete guide for using AIWG with OpenAI Codex CLI, the Codex App, and the Codex API.

Implementation note: The Codex CLI has two implementations. The Rust implementation (`codex-rs/`) is the current active product, shipping via `npm install -g @openai/codex` and `brew install --cask codex`. The TypeScript implementation (`codex-cli/`) is officially legacy. All AIWG integration targets the Rust CLI.

Platform Overview

OpenAI Codex is available across multiple interfaces:

Interface	Model Default	Best For
Codex CLI	`gpt-5.3-codex`	Terminal-first development, automation
Codex App (macOS)	`gpt-5.4`	Parallel agents, long-running tasks
Codex in Copilot	`gpt-5.3-codex`	GitHub-integrated workflows
Codex API	`gpt-5.3-codex`	Custom tooling, CI/CD integration

Available Models (March 2026)

Model	Capability	Pricing	Notes
GPT-5.4	Newest flagship	Premium tier	Priority 0, latest generation
GPT-5.3-Codex	Proven flagship	Premium tier	Priority 0, combines Codex + GPT-5 stacks
GPT-5.1-Codex-Mini	Budget	Free-tier compat	Listed, priority 12, cost-effective

Switch models mid-session with `/model` or configure in `config.toml`.

Install & Deploy

1. Install AIWG

npm install -g aiwg

2. Deploy to your project

cd /path/to/your/project

# Deploy all 4 artifact types for Codex
aiwg use sdlc --provider codex

This deploys to:

`.codex/agents/` — Project-local agent definitions
`.codex/rules/` — Project-local context rules
`~/.codex/prompts/` — User-level command prompts
`~/.codex/skills/` — User-level AIWG skills
`AGENTS.md` — Project context file

Note: Codex uses a split deployment model. Agents and rules are project-local (`.codex/`), while commands and skills are deployed to the user's home directory (`~/.codex/`) to be available across all projects.

3. Deploy commands and skills separately (optional)

# Skills only (user-level)
aiwg -deploy-skills --provider codex

# Commands/prompts only (user-level)
aiwg -deploy-commands --provider codex

4. Regenerate for intelligent integration

/aiwg-regenerate

`aiwg use` already wrote the project context, so natural-language command mapping ("run security review" maps to the correct workflow) works right away via AIWG's Discover-First protocol. On an existing project, or to pull in the latest AIWG, run this to re-tailor the context to your codebase — optional on a brand-new project.

What Gets Created

your-project/
├── .codex/
│   ├── agents/          # SDLC agents (Requirements Analyst, etc.)
│   └── rules/           # Context rules (token security, citation policy, etc.)
├── AGENTS.md            # Project context
└── .aiwg/               # SDLC artifacts

~/.codex/
├── AGENTS.md            # Global personal instructions (optional)
├── config.toml          # Configuration (copy template)
├── auth.json            # Stored auth credentials (ChatGPT login tokens)
├── history.jsonl        # Conversation history
├── skills/              # AIWG skills (voice profiles, project awareness, etc.)
├── prompts/             # AIWG commands as prompts (/project-status, /security-gate, etc.)
└── plugins/             # Installed plugins

Skills Loading

Codex loads skills from two locations:

`~/.codex/skills/` — User-level skills (AIWG deploys here)
`.agents/skills/` — Project-local skills in any git repo

Use the built-in `$skill-creator` to bootstrap new skills.

Skills Context Budget (2% ceiling)

Codex CLI reserves a hardcoded 2% of the model's context window for the "available skills" metadata block (skill name + short description) shown to the model at turn start. Source: `codex-rs/core-skills/src/render.rs:18` (`SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2`).

Approximate budgets:

Model context window	Skills metadata budget
200k tokens	~4,000 tokens
400k tokens	~8,000 tokens
1M tokens	~20,000 tokens

When the budget is exceeded, Codex degrades in three stages: 1. Render full descriptions. 2. Truncate descriptions to fit (`Skill descriptions were shortened to fit the 2% skills context budget…`). 3. Drop entire skills from the visible list (`Exceeded skills context budget of 2%. All skill descriptions were removed and N additional skills were not included…`).

Important nuance: dropped skills are still on disk and still invocable by exact name — Codex only stops advertising them to the model. SKILL.md is read on selection, not on listing. So this is a discovery problem, not a capability loss.

Why this hits AIWG users

`aiwg use sdlc --provider codex` deploys ~480 skill files to `~/.codex/skills/`. Adding `media-curator`, `forensics-complete`, `research-complete` (or `aiwg use all`) pushes the total well past what fits in 2% of a 200k-context model. Combined with Codex's built-in `.system/` skills and any installed plugins, the warning is expected at full deployment on smaller-context models.

What you can do

The 2% ceiling is hardcoded — there is no env var, CLI flag, or config knob to raise it. Tracked upstream as openai/codex#19679. The supported levers are:

1. Disable unused skills in `~/.codex/config.toml`:

   [[skills.config]]
   name = "soul-blend"
   enabled = false

Repeat for every skill you do not actively use. This is Codex's first-class lever (`codex-rs/core-skills/src/config_rules.rs`).

2. Deploy fewer frameworks to Codex. Prefer `aiwg use sdlc --provider codex` over `aiwg use all --provider codex`. Add other frameworks only if you actively use them in Codex sessions.

3. Remove unused skill directories under `~/.codex/skills/<name>/` for skills you will never invoke. Re-run `aiwg use` later to restore.

4. Use a larger-context model. 2% of 1M is 20k tokens versus 4k on a 200k-context model — the budget scales linearly with the configured context window.

Configuration

Copy the AIWG config template:

cp $(npm root -g)/aiwg/agentic/code/frameworks/sdlc-complete/templates/codex/config.toml.aiwg-template ~/.codex/config.toml

Key settings

# Model selection
model = "gpt-5.3-codex"              # Default CLI model (proven flagship)
review_model = "gpt-5.4"             # Most capable for /review

# Profiles for different workflows
[profiles.aiwg-sdlc]
model = "gpt-5.4"
model_reasoning_effort = "high"
approval_policy = "on-request"

[profiles.aiwg-dev]
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"

Config layers (precedence order)

1. MDM managed preferences (macOS only) — highest 2. System managed config (`/etc/codex/managed_config.toml`) 3. Session/CLI flags (`--set key=value` dotted-path overrides) 4. User `~/.codex/config.toml` 5. Built-in defaults

Note: Project-level `.codex/config.toml` is not a separate precedence layer — it is loaded as user config when present in the working directory.

Use `/debug-config` in the CLI to inspect the effective configuration.

AGENTS.md Format

AGENTS.md is free-form Markdown — there is no structured schema, no YAML frontmatter, and no machine-readable directives. The model reads the content as instructional prose appended to its system context.

Discovery hierarchy (merged top-down, later entries take precedence):

1. `~/.codex/AGENTS.md` — Personal global guidance 2. `AGENTS.md` at repo root — Shared project notes 3. `AGENTS.md` in the current working directory — Sub-folder specifics

Disable loading: `--no-project-doc` flag or `CODEX_DISABLE_PROJECT_DOC=1` environment variable.

Size limit: Configurable via `project_doc_max_bytes` in `config.toml` (default: 32KB). Fallback filenames are configurable via `project_doc_fallback_filenames` (defaults include `CLAUDE.md`).

No `model:` directive: Model selection is exclusively a `config.toml` concern, not an AGENTS.md field. Similarly, `allowed-tools` and `shell-environment` are config.toml settings, not AGENTS.md directives.

Approval Policy & Sandboxing

Approval Modes

Three CLI modes via `--approval-mode` / `-a`:

Mode	Flag	Auto-approves	Requires approval
Suggest	`suggest` (default)	File reads	All writes, all shell commands
Auto Edit	`auto-edit`	File reads + patch writes	All shell commands
Full Auto	`full-auto`	Reads, writes, shell execution (sandboxed)	Nothing (sandbox enforced instead)

Approval Policy (config.toml)

Five policy variants for fine-grained control:

Policy	Behavior
`untrusted`	Only known-safe read commands auto-approved; everything else prompts
`on-failure`	Deprecated — was full auto-approve with sandbox escalation on failure
`on-request`	Model decides when to prompt
`never`	Never prompt; failures go directly back to the model
`granular`	Fine-grained sub-fields for shell, rules, MCP, permissions, skills

The `approvals_reviewer` setting controls who handles escalated approvals: `user` (default) or `guardian_subagent` (a risk-assessment subagent that auto-decides).

Sandbox Modes

Three named modes via `sandbox_mode` in config.toml:

Mode	Config value	Description
Read-only	`read-only`	Default for Suggest. All writes and shell commands need approval
Workspace Write	`workspace-write`	Default for Full Auto. Read/write within configured roots, network disabled
Danger Full Access	`danger-full-access`	No sandboxing. All operations permitted

Platform implementations:

macOS 12+: Apple Seatbelt (`sandbox-exec`). Writable roots: `$PWD`, `$TMPDIR`, `~/.codex`. Outbound network blocked.
Linux: Bubblewrap (`bwrap`) with `iptables`/`ipset` firewall rules. Egress denied except OpenAI API.
Windows: Restricted-token sandboxing (native Rust binary, no WSL required).

Configure additional writable paths:

[sandbox_workspace_write]
writable_roots = ["/path/to/extra"]
network_access = false

CLI Features

Mid-Turn Steering

Submit messages while Codex is working to redirect behavior. Steer mode is now stable and the default — Enter sends immediately, Tab queues a follow-up.

Code Review

/review

Opens review presets. Reads the selected diff, reports prioritized actionable findings without touching the working tree. Trained to catch critical flaws and match PR intent to diff.

Web Search

Built-in first-party web search. Defaults to cached mode for speed. Use `--search` flag for live browsing when you need the latest information.

Image Attachments

Attach PNG and JPEG images directly in the CLI composer or via command line for visual context.

Cloud Tasks

codex cloud

Interactive picker for cloud tasks. List, filter, and browse cloud task results. Apply cloud task diffs locally. Cloud environments use 12-hour container caching.

# JSON output for automation
codex cloud --json

AIWG Orchestration — `/aiwg-mission`

AIWG deploys its own orchestration command to `~/.codex/prompts/aiwg-mission.md`, so it renders as `/aiwg-mission` in the Codex TUI. It launches an AIWG Mission — durable, audited dynamic agent orchestration toward a measurable completion criterion, with AIWG owning the bookkeeping (activity-log, gates, best-output selection, crash-resilient checkpoint/resume, cost) while the worker mechanism runs on whatever stack fits. Missions are cross-stack capable (a Codex Mission can coordinate workers on other stacks via the AIWG `serve` executor registry).

`/aiwg-mission` is AIWG-owned and always present once AIWG is deployed. Do not confuse it with a `/workflow` command you may see from an installed Codex plugin (e.g. `temporal`, `superpowers`) — that is plugin-provided and environment-specific, not a core Codex primitive, so AIWG never assumes it. For in-session "iterate until a condition" on Codex alone, use the native `/goal`.

For a pre-established repeatable sequence (rather than dynamic orchestration), discover a Flow instead: `aiwg discover "<goal>"`.

Plugins

Plugins are installable bundles that package skills, app integrations, and MCP server configurations into a single distributable unit. They are the recommended way to share reusable Codex workflows across teams and projects.

What plugins contain

A plugin can bundle any combination of:

Skills — Workflow prompts progressively discovered by the agent
Apps — Optional app integrations or connector mappings
MCP servers — Remote tools or shared context the plugin needs

Plugin structure

Every plugin requires a manifest at `.codex-plugin/plugin.json`:

my-plugin/
├── .codex-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md         # Optional: skill instructions
├── .app.json                # Optional: app/connector mappings
├── .mcp.json                # Optional: MCP server configuration
└── assets/                  # Optional: icons, logos, screenshots

Minimal manifest

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow bundle",
  "skills": "./skills/"
}

Full manifest fields

Field	Purpose
`name`, `version`, `description`	Package identity
`author`, `homepage`, `repository`, `license`, `keywords`	Publisher and discovery metadata
`skills`, `mcpServers`, `apps`	Paths to bundled components (relative to plugin root, `./` prefix)
`interface`	Install-surface metadata (display name, descriptions, icons, screenshots, brand color, default prompts, legal links)

Installing plugins

# In-session plugin management
codex
/plugins

# Use the built-in @plugin-creator skill to scaffold a new plugin

Plugin marketplaces

Codex reads plugin catalogs from three locations:

Marketplace	Location	Scope
Official directory	Curated by OpenAI	Global
Repo marketplace	`$REPO_ROOT/.agents/plugins/marketplace.json`	Project team
Personal marketplace	`~/.agents/plugins/marketplace.json`	Individual developer

Marketplace file format:

{
  "name": "local-repo",
  "interface": {
    "displayName": "My Team Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./agentic/code/plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Key marketplace rules:

`source.path` is relative to the marketplace root, must start with `./`
`policy.installation` values: `AVAILABLE`, `INSTALLED_BY_DEFAULT`, `NOT_AVAILABLE`
`policy.authentication`: `ON_INSTALL` or on first use
Plugins are cached at `~/.codex/plugins/cache/$MARKETPLACE/$PLUGIN/$VERSION/`
Enable/disable state stored in `~/.codex/config.toml`

AIWG as a Codex plugin

AIWG can be deployed as a Codex plugin bundle, generating a `.codex-plugin/plugin.json` manifest and a repo marketplace entry:

# Deploy and generate plugin bundle in one step
aiwg use sdlc --provider codex --as-plugin

# Or package the plugin bundle separately
node tools/plugin/package-plugins.mjs --plugin codex-sdlc

The bundle is written to `agentic/code/plugins/sdlc/` and a marketplace entry is created at `.agents/plugins/marketplace.json` so your team can install it via the Codex `/plugins` panel without any external registry.

Local plugin development workflow

# 1. Scaffold with built-in skill
# Use @plugin-creator in Codex

# 2. Or manually create
mkdir -p my-plugin/.codex-plugin my-plugin/skills/hello

# 3. Add manifest
cat > my-plugin/.codex-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom workflow",
  "skills": "./skills/"
}
EOF

# 4. Add a skill
cat > my-plugin/skills/hello/SKILL.md << 'EOF'
---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.
EOF

# 5. Add to repo marketplace
mkdir -p .agents/plugins
# Add marketplace.json pointing to ./agentic/code/plugins/my-plugin

# 6. Restart Codex to pick up the plugin

Feature Flags

codex features enable unified_exec
codex features disable some_feature

Manage CLI feature flags for experimental capabilities (e.g., `child_agents_md` for hierarchical AGENTS.md).

Model Switching

/model gpt-5.3-codex

Switch models mid-session without restarting.

Codex App (macOS)

The Codex App (launched February 2, 2026) provides a native macOS interface for:

Parallel agents — Run multiple Codex agents simultaneously on different tasks
Long-running tasks — Background processing with notification on completion
Automations — Schedule recurring tasks combining instructions and optional skills
Review queue — Automation results are queued for human review before applying

Automations

Schedule tasks to run periodically:

Issue triage and categorization
CI failure summaries
Release briefs
Automated bug checking

Results go to a review queue — you approve before changes are applied.

Using AIWG Prompts

/prompts:aiwg-pr-review PR_NUMBER=123
/prompts:aiwg-security-audit
/prompts:aiwg-generate-tests

Wire Protocol

Codex uses the OpenAI Responses API (`/v1/responses`) exclusively for all model communication. The legacy Chat Completions API (`wire_api = "chat"`) has been removed — any config using it produces a hard error at startup.

Custom model providers are configured in `config.toml`:

[model_providers.my-proxy]
name = "My Proxy"
base_url = "https://proxy.example.com/v1"
env_key = "MY_PROXY_API_KEY"
wire_api = "responses"    # Only "responses" is supported

Built-in providers: `openai` (default), `ollama` (localhost:11434), `lmstudio` (localhost:1234).

Codex as MCP Server

Codex can also expose itself as an MCP server for programmatic control from other tools:

codex mcp-server

This is a separate capability from Codex consuming MCP tools (the sidecar pattern). The internal MCP server uses stdio JSON-RPC 2.0 and is experimental.

Non-Interactive / CI Mode

# Full auto execution
codex exec "Perform AIWG security review" --full-auto --sandbox read-only

# With specific model
codex exec "Fix failing tests" --model gpt-5.3-codex --full-auto

AIWG Model Mapping

When AIWG deploys agents, model shorthands are mapped:

AIWG Shorthand	Codex Model	Use Case
`opus`	`gpt-5.4`	Architecture, complex reasoning
`sonnet`	`gpt-5.3-codex`	Code generation, implementation
`haiku`	`gpt-5.1-codex-mini`	Quick tasks, file operations

GitHub Integration

Codex is available as a coding agent for GitHub Copilot Pro+ and Enterprise customers. AIWG agents deployed via `--provider copilot` work with this integration.

Agent Loop

Agent loops can target Codex directly via `--provider codex`:

# Run Al with Codex as the execution provider
aiwg ralph "Fix all failing tests" \
  --completion "npm test passes" \
  --provider codex

# External Al with Codex for long-running tasks
aiwg ralph-external "Migrate codebase to TypeScript" \
  --completion "npx tsc --noEmit exits 0" \
  --provider codex \
  --budget 5.0

Model mapping: opus → gpt-5.4, sonnet → gpt-5.3-codex, haiku → gpt-5.1-codex-mini.

See Al Guide for full documentation.

Troubleshooting

Natural language not working? Run regenerate:

/aiwg-regenerate

Skills not loading? Check both skill locations:

ls ~/.codex/skills/
ls .agents/skills/    # Project-local

Restart Codex after installing new skills.

Warning: `Exceeded skills context budget of 2%, all skill descriptions were removed and N additional skills were not included…`? This is Codex's hardcoded 2% skills metadata ceiling — see Skills Context Budget above. Dropped skills are still invocable by exact name; only their visibility to the model is removed. Mitigate by disabling unused skills in `~/.codex/config.toml` (`[[skills.config]] name = "..." enabled = false`), deploying fewer frameworks, or using a larger-context model. Tracking issue: openai/codex#19679.

Config not applying? Inspect effective config:

/debug-config

Model not available? Check your tier:

GPT-5.3-Codex requires Pro/Team plan
gpt-5.1-codex-mini available on all plans (including free tier)
GPT-5-Codex-Mini auto-offered at 90% usage

Verify installation:

ls ~/.codex/skills/
ls ~/.codex/prompts/
ls .codex/agents/
ls .codex/rules/
cat AGENTS.md | head -20

MCP Sidecar (AIWG Tooling Layer)

For structured AIWG tool access beyond what `--full-auto` provides, connect the MCP sidecar:

aiwg mcp install codex

See the Codex MCP Sidecar Guide for the two-layer model and setup details.