Skip to content

Official Codex runner

kew supports the official OpenAI Codex CLI as an explicit host runner for standard issue dispatch. Install version 0.145.0 or newer and authenticate the CLI itself:

npm install -g @openai/codex
codex --version
codex login
codex login status

kew checks both the minimum version and login status before launch. It never reads, copies, mounts, prints, or records the CLI credential. Authentication is owned by the official CLI login cache or operating-system keychain; kew does not fall back to OPENAI_API_KEY or CODEX_ACCESS_TOKEN.

Configuration

Codex is never inferred from a model name. GPT, o-series, and models with Codex in their names continue to infer the opencode runner. Select the official runner explicitly with a nonempty, governed-priced model:

[routing]
simple = { runner = "codex", model = "gpt-5.6-sol" }

[agent.codex]
reasoning_effort = "high"
service_tier = "fast"

reasoning_effort is optional and accepts minimal, low, medium, high, or xhigh. service_tier is optional and accepts only fast; leave it unset to preserve Codex's default behavior. Fast mode is governed rather than inherited from personal configuration: kew passes both -c service_tier="fast" and -c features.fast_mode=true even though Codex runs with --ignore-user-config. The official CLI remains responsible for rejecting an account or model that is not eligible for Fast mode.

For example, an explicitly routed gpt-5.6-luna run may combine reasoning_effort = "xhigh" and service_tier = "fast". Confirm authenticated model availability before dispatch and add a reviewed pricing override if the model is not in kew's shipped pricing table. [agent.codex] intentionally has no extra_args escape hatch.

Codex usage is valued as API-equivalent included-plan value, never described as free and never presented as native billed dollars.

Codex JSONL is the only source used for reported model and service-tier identity: kew reads those fields from the structured response envelope and never searches agent messages or command output for them. kew persists the governed requested_service_tier alongside the structured reported_service_tier; a missing reported value remains missing rather than being inferred. For adaptive Switchyard runs, the admitted route is retained separately from the served model and selected Switchyard tier. The run report also identifies classifier overhead as proxy observation evidence, while runner-reported usage remains authoritative for task accounting.

Execution and security

Codex uses Codex-native workspace-write on the host. Command network access is off, .git is protected, and extension, web-search, shell-environment, and secret inheritance controls are fixed by kew. The Codex process keeps HOME so the official login can work, while OPENAI_API_KEY, CODEX_ACCESS_TOKEN, unrelated provider credentials, GitHub tokens, and AWS credentials are removed from its process environment.

Project policy is deliberately narrow:

  • regular files under .codex/rules/ and .codex/skills/ are visible;
  • symlinks, special files, unknown .codex entries, and .codex/config.toml fail closed; and
  • personal .codex content is neither copied nor mounted by kew.

The runner declares publication_style="host". After a clean exit, kew owns commit, push, pull-request creation, and the dispatch report. An exit-zero run that cannot complete that host broker is a failed dispatch, not success.

The containment posture recorded for this host execution is native. Codex applies its own sandbox instead of kew's external container boundary, and the runner protocol declares that boundary in code; configuration cannot grant native status. required_credentials == () is intentional because native execution uses the official CLI login and never enters the container credential injection path. No container image or CLI-login-cache mount is supported for Codex.

Canary and resume

The standard canary checks fresh JSONL parsing, positive token usage, session capture, terminal completion, classification, derived pricing, tree cleanliness, and session deletion:

kew canary --runner codex --model gpt-5.6-sol --json
kew canary --runner codex --model gpt-5.6-sol \
  --exercise-resume --json

The resume gate interrupts a fresh thread, resumes it through the official CLI, and deletes the session afterward. A Codex needs_human signal is surfaced as a governed pause. Raw --record JSONL is sensitive evidence and is not a credential store.

Supported and refused flows

  • Supported: standard issue dispatch, conflict resolution, and standalone kew review, all with host-brokered publication.
  • Refused in v1: first-class loops, which do not yet own a compatible host publication broker.
  • Production adversarial review: remains externally contained OpenCode. Selecting Codex there fails closed because its credential declaration is empty. The dogfood reviewer remains pinned to OpenCode; other credential-declared contained reviewers remain structurally eligible.