Text of github.github.com › gh-aw › reference › engines › codex as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

OpenAI Codex reference | GitHub Agentic Workflows

Skip to main content OpenAI Codex reference For first-time setup, see Using OpenAI Codex . Shared options are in AI engines . Selection and authentication Section titled “Selection and authentication” Use engine: codex with CODEX_API_KEY , OPENAI_API_KEY , or OpenAI Workload Identity Federation . GitHub Copilot inference uses separate GitHub authentication. ChatGPT subscription login is unsupported. The default CLI pin is 0.169.0 ; override it with engine.version .

With the native OpenAI provider, Codex has no default model; set a specific model , set model: router to route on OpenAI, or configure the repository’s model-selection variables (see model selection ). With model-provider: github , an eligible Codex workflow that sets no model is routed by default; see GitHub Copilot inference and default routing for workflows without a model . OpenAI Workload Identity Federation Section titled “OpenAI Workload Identity Federation” With engine.auth.type: github-oidc and engine.auth.provider: openai , the AWF API proxy exchanges a GitHub Actions OIDC token for an OpenAI service-account access token.

Codex inference does not require CODEX_API_KEY or OPENAI_API_KEY ; the OIDC and OpenAI credentials remain outside the agent container. This mode requires the OpenAI inference provider, permissions.id-token: write , and an enabled AWF sandbox at v0.29.11 or newer. sandbox.agent: false is unsupported. Explicit AWF versions and API-proxy image tags must use a full semantic version at or above that minimum; tags such as latest or stable do not establish WIF support. engine.version selects the Codex CLI, not AWF.

The proxy reaches auth.openai.com through its dedicated egress path. Neither that host nor the codex-vendor network opt-in is required in network.allowed for WIF. Startup refuses to launch Codex unless fresh AWF reflection confirms the configured OpenAI WIF endpoint. Codex threat detection inherits the main Codex engine’s authentication when no detector-specific auth is set, including when a same-engine detector override is present.

The generated detection job receives id-token: write . The separate evals job does not inherit WIF and still requires CODEX_API_KEY or OPENAI_API_KEY for OpenAI models. See Codex OpenAI Workload Identity Federation for provider setup, required fields, and a workflow example. GitHub Copilot inference Section titled “GitHub Copilot inference” To select Codex as the AI engine, with inference hosted and billed through a GitHub Copilot subscription, add a copilot/ model declaration.

This configures Codex’s BYOK provider to use GitHub Copilot inference. Select a Codex-compatible model available to your Copilot account. For example: engine : id : codex model : copilot/gpt-6.1-sol GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-6 Astra, and GPT-5.6 Sol, Terra, and Luna support Codex through the Responses API without a -codex suffix. Check Codex model support , API pricing , and API deprecations before pinning a model; a cached pricing entry alone does not establish availability.

Both copilot/auto and auto with engine.model-provider: github delegate model selection to the Copilot gateway through the Responses API. The bare spelling does not change Codex’s default OpenAI provider; select GitHub explicitly to use Copilot inference. To authenticate: For organization-billed usage, grant copilot-requests: write . Otherwise, provide a COPILOT_GITHUB_TOKEN secret containing a fine-grained PAT with Copilot Requests access.

GitHub inference requires the AWF sandbox. Do not set sandbox.agent: false for this provider. For a model supplied through an expression or repository variable, set engine.model-provider: github explicitly; runtime model prefixes do not change the selected credentials. With engine.model-provider: github and no model , engine.model , or engine.model-routing , the main agent uses model routing with goal: cost and mode: auto , limited to GPT models.

A nonempty GH_AW_MODEL_AGENT_CODEX or GH_AW_DEFAULT_MODEL_CODEX variable bypasses routing at run time; top-level model-routing: false opts out. The native OpenAI route isn’t routed by default. GitHub inference uses direct function-backed exec_command for native shell execution unless tools.bash: false . JavaScript code mode is disabled because the compatibility adapter does not support its custom exec tool. gh-aw generates a direct-tool catalog from the installed binary’s bundled metadata; MCP and apply_patch remain available.

The binary must support debug models --bundled . engine.config cannot re-enable code mode or replace the managed catalog. OpenAI inference is unchanged. Capabilities and limitations Section titled “Capabilities and limitations” Codex enables its shared native search/browsing tool when either tools.web-search or tools.web-fetch is enabled. Search and page fetching cannot be disabled independently; use network.hosted-web to restrict hosted retrieval.

Codex can disable shell execution completely, but not restrict it to a per-command tools.bash allowlist. With OpenAI inference through the AWF sandbox, enabling network.hosted-web also enables Codex’s standalone web.run search tool for Responses Lite models, which do not receive the hosted web_search tool. Without hosted web, this provider flag is not set. Codex standalone search does not support network.hosted-web.max-uses ; omit that limit when using Codex with OpenAI inference. network.hosted-web is not functional with Codex using GitHub Copilot inference.

The compiler rejects this combination; use OpenAI inference to enable Codex standalone web search. Codex does not support bare mode, Copilot-style max-continuations , or native engine.agent selection. engine.harness.use can select a replacement harness that has been provisioned in the setup-action directory before execution. See the AI engine feature comparison . When a workflow does not declare any plugins , GitHub Agentic Workflows writes features.plugins=false to Codex’s generated config.toml .

This prevents Codex from contacting the ChatGPT plugin catalog or synchronizing the curated plugin repository at startup. Codex does not provide a narrower setting that disables only startup synchronization, so workflows that declare Agent Plugins keep the plugin subsystem and its startup checks enabled. Directly configured MCP servers are unaffected. Plugins are registered after configuration generation in the same CODEX_HOME used for execution.

Inline skills use .codex/skills/<name>/SKILL.md . The harness resolves model aliases before Codex starts, against the configured provider’s live models: copilot/gpt-5.6 runs on the newest live gpt-5.6* model, and workflow-defined aliases under models: work the same way. Exact ids such as copilot/gpt-5.6-sol reach Codex unchanged. copilot/auto stays the Copilot gateway sentinel. Custom Codex configuration Section titled “Custom Codex configuration” engine.config accepts TOML that is parsed and structurally merged with the generated configuration.

Root settings remain at the root, and table settings preserve unrelated defaults: engine : id : codex config : | model_reasoning_effort = "high" Generated configuration disables the default metrics exporter and preserves native MCP timeouts and client headers. MCP connections and the AWF provider’s connection settings remain gateway-managed; configure upstream servers through mcp-servers and inference endpoints through engine.api-target or engine.env.OPENAI_BASE_URL .

Use ${ENV_VAR} inside TOML strings to reference an environment value configured through engine.env . GitHub Actions expressions are not accepted directly inside engine.config . The native integration supports OpenAI Responses-compatible inference and GitHub inference; an Anthropic backend requires a Responses-compatible bridge configured as an OpenAI endpoint. For shell environment filtering, use either [shell_environment_policy.filters] or the legacy include_only / exclude arrays.

Selectin

The rest of this page is on the live site.