provider-codex

Provider: OpenAI Codex CLI

Process guidance for keeping the gateway's Codex (codex) integration aligned with the upstream CLI. This skill does not define argv/env behaviour; the single mechanical source of truth is UPSTREAM_CLI_CONTRACTS.codex in src/upstream-contracts.ts, enforced by validateUpstreamCliArgs / validateUpstreamCliEnv. Never re-encode flags, sandbox/approval modes, or resume rules here or in TOML.

Identity

Field	Value
CliType	codex
Executable	codex
Package	@openai/codex (npm)
Repo	https://github.com/openai/codex
Release API	https://api.github.com/repos/openai/codex/releases/latest
Changelog RSS	https://learn.chatgpt.com/docs/changelog/rss.xml
Watch categories	flags, sandbox-modes, approval-modes, session-resume, output-schema

These values mirror UPSTREAM_CLI_CONTRACTS.codex.upstreamMetadata and docs/upstream/provider-sources.dag.toml ([providers.codex]). The TypeScript metadata is authoritative; the TOML is scanner input only.

When to use

• An OpenAI Codex CLI release lands and you need to check for contract drift.
• A codex request fails the upstream contract check before spawn.
• npm run upstream:scan -- --live reports a change on the Codex release notes or changelog.

How LLM agents should use Codex through the gateway

1. Discover the live gateway/provider surface before relying on Codex-specific controls:

   provider_tool_capabilities({cli:"codex"})
   

   For a cached read-only resource, use provider-tools://codex.
2. Use codex_request for normal implementation/review turns and codex_request_async for long-running work. To continue an existing Codex conversation, pass codex_request a real Codex session UUID from ~/.codex/sessions/, or resumeLatest:true; both route through codex exec resume and work headlessly. codex_fork_session is registered but cannot run from the gateway: codex fork is interactive and requires a controlling terminal, and Codex exposes no non-interactive equivalent (codex exec has only resume/review/help). Re-check that on each Codex release; if a headless fork lands, codexForkCanRunHeadless in src/index.ts is the single predicate to flip.
3. Omit model unless the caller explicitly asked for a specific variant; the gateway resolves the configured Codex default/profile.
4. Prefer sandboxMode:"workspace-write" when Codex needs a writable workspace. fullAuto:true is the deprecated compatibility shorthand. Use approvalStrategy:"legacy": Codex rejects mcp_managed before launch because its ambient MCP configuration cannot be isolated, and approvalPolicy has no effect for Codex.
5. Do not pass Claude-style allowedTools or disallowedTools; Codex does not expose those request fields through the gateway. Codex owns its MCP configuration, and a gateway mcpServers list is descriptive metadata, not an enforceable allowlist.
6. Use sandboxMode, profile, configOverrides, oss, images, outputFormat, and outputSchema only as reported by provider_tool_capabilities. askForApproval and useLegacyFullAutoFlag are deprecated compatibility inputs: current Codex emits no corresponding argv and the gateway returns a warning. fullAuto:true remains a compatibility shorthand for sandboxMode:"workspace-write". These are provider-native legacy controls, not inputs to the Claude-only gateway approval boundary.
7. Codex continuity is real through codex exec resume: pass a real Codex UUID from ~/.codex/sessions/, or resumeLatest:true. Gateway gw-* IDs are not Codex sessions. sandboxMode and its deprecated fullAuto:true shorthand are dropped on resume, so those fields cannot select a posture there. That is not a guarantee that the original posture is retained: configOverrides is not filtered and can set sandbox_mode, and Codex re-resolves configuration on a cold resume. resumeLatest is under review (#258): --last is cwd-filtered upstream unless --all is passed, which the gateway does not emit, and the child is still spawned with the gateway-resolved cwd. Do not rely on which session it selects or on the resumed working directory. The provider-native workingDir and addDir flags scope new sessions only; the gateway accepts but omits those fields on resume. Omitting them does not pin the resumed directory: the child is still spawned with the gateway-resolved cwd. A verified workspace or gateway worktree can still select the child process launch cwd and bind gateway tracking. Do not rely on a resumed session's directory in any resume form, including a direct UUID resume: the child is spawned with the gateway-resolved cwd even though the flags are filtered.
8. Codex new and resume requests send the exact prompt through stdin with the native - marker. They do not consume the platform's single-argv prompt allowance and are never truncated. codex_fork_session uses the distinct codex fork contract, remains argv-bound, and rejects oversized UTF-8 prompts as non-retryable input_too_large. That rejection is deliberately evaluated before the tool's availability check, so argv admission stays observable even though the call cannot ultimately run. An otherwise unscoped child still runs in a fresh neutral temporary cwd, not the gateway repository. All other caller-controlled argv values are admitted in their final encoded form before spawn. Embedded NUL bytes return non-retryable invalid_input without exposing the rejected value. New and resumed stdin requests complete only after the full payload write callback succeeds; a clean child exit with closed or pending delivery is a fixed non-sensitive failure.