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

​
Install

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. With the sidecar enabled, Crewship puts only a disposable OPENAI_API_KEY in the agent environment and points Codex at the loopback reverse proxy. The sidecar injects the real OpenAI key after the request leaves the agent process. Credential-backed OPENROUTER and OPENAI_COMPAT models use Codex’s native custom model_provider configuration for that invocation. For example, openrouter/anthropic/claude-sonnet-4 is sent to /llm/openrouter with anthropic/claude-sonnet-4 as Codex’s provider-local model ID. The provider must implement the OpenAI Responses API; current Codex no longer supports wire_api = "chat". Use the OpenCode adapter for a Chat-Completions-only compatible endpoint.

​
Models

Codex CLI is a STRICT subset of OpenAI’s general API — only the GPT-5.x coding-tuned family is accepted: Codex CLI rejects o3, o4-mini, gpt-4o etc. — those are general-API only.

​
Command shape

  • exec — non-interactive subcommand (NOT --quiet, that flag doesn’t exist)
  • --json — newline-delimited JSON events on stdout
  • --sandbox — read-only (MINIMAL profile) | workspace-write (all other profiles — CODING/FULL) | 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).
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 = { ... }.
Two sidecar-hosted MCP servers are auto-injected into every generated config (injectMemoryMCP + injectRoutinesMCP): crewship-memory (http://127.0.0.1:9119/mcp/memory/<slug>) and crewship-routines (.../mcp/routines) — both http transport. They give the model native memory.read/write/search/append_daily and save_routine/list_routines tools regardless of CLI. A user-declared server of the same name wins (no overwrite).

​
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): 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.