Skip to main content
@openai/codex (Rust port, v0.128.0+). Distributed as an npm package wrapping a per-platform Rust binary.

​
Install

npm install -g @openai/codex
Pre-installed in every seeded crew container via Crewship’s baseCLIPostCreate provisioning script.

​
Auth

API key only (BYO). Subscription path (ChatGPT Plus/Pro via codex login) not yet wired in Crewship.
TypeEnv varFormat
API keyOPENAI_API_KEYsk-…
Service accountOPENAI_API_KEYsk-svcacct-…
Crewship’s sidecar passes the real OPENAI_API_KEY directly into the agent container env — Codex talks to api.openai.com over HTTPS CONNECT through the sidecar (sidecar reverse-proxy is wired only for Anthropic).

​
Models

Codex CLI is a STRICT subset of OpenAI’s general API — only the GPT-5.x coding-tuned family is accepted:
API stringTier
gpt-5.5frontier — Crewship default
gpt-5.4frontier
gpt-5.4-minifast
gpt-5.3-codexfrontier (coding-specialised)
gpt-5.3-codex-sparkreasoning preview
Codex CLI rejects o3, o4-mini, gpt-4o etc. — those are general-API only.

​
Command shape

codex exec --json --sandbox <mode> --model <m> -- "[SYSTEM]\n<preamble>\n\n[USER]\n<msg>"
  • exec — non-interactive subcommand (NOT --quiet, that flag doesn’t exist)
  • --json — newline-delimited JSON events on stdout
  • --sandbox — read-only (MINIMAL/CONSULTATIVE profile) | workspace-write (CODING) | danger-full-access (never opted into)
  • -- separator prevents user message dash-prefixed tokens from being parsed as flags
  • System prompt is folded into the user message body with [SYSTEM]/[USER] delimiters because Codex exec has no system-prompt flag

​
MCP

Codex uses TOML, not JSON. Crewship writes /crew/agents/<slug>/.codex/config.toml (HOME, NOT workdir — Codex requires interactive trust ceremony for project-scoped configs). 
[mcp_servers.linear]
url = "https://mcp.linear.app/sse"
bearer_token_env_var = "LINEAR_TOKEN"

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/work"]
# env = { LINEAR_TOKEN = "${VAR}" } intentionally NOT written —
# Codex doesn't interpolate ${VAR} so writing it would override the
# inherited container env with the literal string.
Authorization: Bearer ${TOKEN} headers are translated to bearer_token_env_var = "TOKEN". Generic X-API-Key: ${KEY} headers go to env_http_headers = { "X-API-Key" = "KEY" }. Literal headers go to http_headers = { ... }.

​
Memory

Canonical memory file set written to /output/<slug>/AGENTS.md (Codex’s auto-discovered file). Plus the cross-CLI parity files for an agent swapping CLI mid-mission. First-turn parity: system prompt is also prepended to the user message via [SYSTEM]/[USER] delimiters since Codex doesn’t load AGENTS.md until the second invocation.

​
Output stream

Per developers.openai.com/codex/cli/reference, Codex emits an envelope-and-item model (NOT the Agents SDK schema):
EventPayload
thread.startedsession bootstrap; thread_id, model
turn.startedturn boundary (no payload)
turn.completedusage.{input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}
turn.failederror envelope with usage
item.started/updated/completednested item.type discriminator
Item subtypes: agent_message, reasoning, command_execution (uses aggregated_output + exit_code, NOT output), file_change, mcp_tool_call (uses server/tool/arguments/result), web_search, plan_update, todo_list, collab_tool_call.

​
Troubleshooting

codex: not found — npm install failed in container. Check journalctl -u prod-server | grep codex. unknown flag: --quiet — adapter regression; ensure orchestrator pinned to current schema (see cli_adapter_versions_test.go). MCP server returns 401 — verify bearer_token_env_var references a credential present in the container env. Run crewship agent mcp <slug> --resolved to dump the effective merged MCP config (crew + agent, including each server’s bound credential name) and confirm the expected credential is wired.