Codex

The Codex connector wires DefenseClaw into Codex's documented hooks, native OpenTelemetry exporter, and the notify bridge for agent-turn-complete events.

Platform support

Setup

defenseclaw setup codex                # observe (default) — record only
defenseclaw setup codex --mode action  # block on policy hits via PreToolUse deny

defenseclaw setup codex                # observe (default) — record only
defenseclaw setup codex --mode action  # block on policy hits via PreToolUse deny

setup codex is the dedicated Codex setup alias. It uses the same setup backend as setup guardrail, adds or reconfigures Codex, wires hooks + OTel + the notify bridge, and can join an existing hook-connector roster when you choose Add. No proxy listener binds in either mode.

Native logs, metrics, and traces use the standard loopback /v1/{logs,metrics,traces} endpoints with X-DefenseClaw-Source: codex and an Authorization bearer managed in Codex's exporter configuration. The credential is separate from both the gateway master token and the Codex hook credential, is accepted only for matching Codex OTLP over loopback, and cannot call management or another connector. Do not print or copy the managed exporter header or its protected sidecar. Setup also pins Codex's documented otel.environment field to DefenseClaw's configured environment (Codex otherwise defaults it to dev). Doctor compares that on-disk value with authenticated live runtime metadata and telemetry health so a stale gateway or configuration drift is visible.

Redaction is configured through the v8 bucket/profile policy: edit observability.destinations[].routes[].selector.buckets and observability.redaction_profiles, then follow Redaction → Verify policy.

The alias defaults to observe mode and accepts the common hook-connector options, including --mode, --workspace, --rule-pack, --human-approval, --hilt-min-severity, --fail-mode, --block-message, --replace, --with-local-stack, and restart controls. Use the quick-alias reference for that surface. Use the full guardrail setup when you also need scanner, detection-strategy, or judge-provider configuration. Defaults are documented once on the Defaults page.

Files DefenseClaw will modify

Everything outside DefenseClaw-marked fields is preserved. Teardown restores a pristine backup when its identity still matches; otherwise it removes only owned entries.

Hook capabilities

Action-mode responses follow each event's official control or feedback contract; the events do not all have the same effect:

Each native hook request must exactly match the registered event and its stdin hook_event_name. Before policy evaluation, the gateway also compares that event and its contract ID with the protected contract lock; mismatches or tampering are rejected.

The lifecycle-control rows marked v3/v4 below are contract-supported only for Codex >=0.133: v3 covers 0.133 through 0.144, and v4 covers >=0.145. This version boundary is not release certification; native Windows support does not populate authentic official-client validation metadata. DefenseClaw does not infer or backfill these matcher/control semantics onto the smaller v1/v2 contracts.

Inventory surfaces

DefenseClaw follows the current Codex layouts rather than Claude Code's .mcp.json convention:

• Skills: .agents/skills at every directory from the active working directory to the detected repository root, then $HOME/.agents/skills, plus $CODEX_HOME/skills; /etc/codex/skills is also included on Unix. CODEX_HOME does not redirect personal .agents/skills. Operator-installed children of $CODEX_HOME/skills are scanned normally. The exact $CODEX_HOME/skills/.system children are vendor-bundled: DefenseClaw lists them in inventory but never scans, blocks, disables, or quarantines them. A directory merely named .system anywhere else is not exempt. Linked or reparse-point roots, children, and markers (including Windows junctions) are rejected; copy a linked skill into a real contained directory before relying on inventory coverage.
• MCP: [mcp_servers.*] in candidate project .codex/config.toml layers, closest layer first, followed by $CODEX_HOME/config.toml. The exact URL-only openaiDeveloperDocs = https://developers.openai.com/mcp entry in the canonical user config is vendor-bundled: it remains visible with bundled: true, but DefenseClaw never scans or enforces it. A same-named project entry, or a user entry with any command, auth, header, query, transport, or other added field, is not exempt. Codex's generated node_repl currently has no stable published provenance/schema contract, so it intentionally remains scan-eligible even when the observed local runtime binary is OpenAI-signed. MCP manifests shipped inside Amp skills are also user/workspace assets and remain scan-eligible.
• Custom agents: standalone .toml files in candidate project .codex/agents/ layers and $CODEX_HOME/agents/. Inventory validates the required name, description, and developer_instructions fields without copying instruction text into the AIBOM.
• Rules: *.rules below rules/ beside each candidate active config layer, including project .codex/rules/ and $CODEX_HOME/rules/.
• Memories: generated local-memory state under $CODEX_HOME/memories/. $CODEX_HOME/history.jsonl is a separate transcript-history file and is not reported as a memory store.
• Plugins: exact local source.path entries from repository and personal .agents/plugins/marketplace.json, the repository's lower-precedence legacy-compatible .claude-plugin/marketplace.json, plus bounded inventory of installed copies in the implementation-observed $CODEX_HOME/plugins/cache/ hierarchy. Personal marketplace entries follow both repository sources. DefenseClaw does not invent a fixed project plugin directory. The marketplace paths, local source.path resolution, and .codex-plugin/plugin.json manifest are official. Codex CLI reports an installedPath, but its public CLI contract does not promise that the cache hierarchy will remain stable. DefenseClaw therefore does not claim that Git/URL/npm sources must land there; bounded inventory reports only installed copies actually observed under that hierarchy.

Codex activates project .codex/ config, MCP, agent, and rule layers only for trusted projects. Filesystem inventory reports project entries as trust_required; it does not infer the client's private trust decision from the presence of a file.

Telemetry channels at boot

In an OpenShell sandbox

defenseclaw sandbox run codex runs Codex in an NVIDIA OpenShell sandbox on Linux, or on a Mac with Apple silicon in a MicroVM of its own that works on a copy of your folder (macOS): the agent sees only your project folder, and DefenseClaw hooks gate every tool call. The sandbox guide covers setup, the session and every flag. The files below exist only in the sandbox image; your own Codex configuration does not change.

• Managed tier. The hooks are in root-owned /etc/codex/requirements.toml, which pins allow_managed_hooks_only and features.hooks on, so user and project config cannot add hooks or switch DefenseClaw's off. Root-owned /etc/codex/managed_config.toml turns off the update check, analytics and the features that reach remote services, sends Codex's OTel to DefenseClaw, and pins BASH_ENV, ENV and the dynamic-loader variables to empty for every command Codex runs. The hooks fail closed and authenticate with a per-sandbox token, which never goes on a command line: the launcher hands it to Codex's OTel exporters in their header variables (blanked for the commands Codex runs), and the hooks and the notify bridge give it to curl as configuration on a file descriptor. The notify bridge only sends telemetry, so it never blocks Codex.
• Startup tip download. The Codex TUI fetches its startup tip from raw.githubusercontent.com at every start, around the egress proxy. OpenShell refuses it and DefenseClaw's triage rejects the drafted rule (harness_background_fetch) instead of opening a direct one; the refusal is not counted as a blocked site, and Codex shows a built-in tip.
• Skip-permissions. On by default (the open and balanced packs): Codex starts with --dangerously-bypass-approvals-and-sandbox. Codex's own sandbox cannot run inside OpenShell, so --safe (or the strict pack) keeps its approval prompts with sandbox_mode="danger-full-access" and approval_policy="untrusted": Codex asks before every command outside its read-only set and before every edit. A headless --safe run (--prompt, codex exec) cannot ask, so it refuses those commands. The sandbox's requirements.toml then refuses the never approval policy (falling back to untrusted), and --dangerously-bypass-approvals-and-sandbox, --yolo, --full-auto, --ask-for-approval never and -c approval_policy="never" are dropped from the arguments you pass.
• Model sign-in. --llm auto (the default) shares OPENAI_API_KEY (or CODEX_API_KEY) from your shell, or else the API key that codex login --with-api-key stored in ~/.codex/auth.json. A ChatGPT sign-in is not shared. OpenShell holds the secret, and the sandbox gets a placeholder that works only at api.openai.com. --llm bedrock, and auto when neither is set, shares a short-term Amazon Bedrock API key from AWS_BEARER_TOKEN_BEDROCK for a Codex custom provider on the Bedrock Mantle endpoint in --bedrock-region (default $AWS_REGION, then $AWS_DEFAULT_REGION, then us-east-1), with Codex's multi-agent and web search tools off. Mantle does not serve Codex's own default model, so a Bedrock run uses openai.gpt-oss-20b unless you pick another with -- -m MODEL (a -c model= override does not change it); the banner's Model line names the model either way. openshell.llm sets the choice for runs without --llm, such as the codex shell wrapper's.
• Bedrock follow-up turns. Bedrock Mantle rejects every turn after the first of a Codex conversation, which Codex shows as stream disconnected before completion; no provider setting avoids it. Start each task with /new in the TUI, or run one --prompt per task. The banner of an interactive Codex session on Bedrock says so.
• Per-sandbox settings. Codex reads one managed_config.toml and one requirements.toml, so each sandbox gets both again, read-only, with its own settings. managed_config.toml pins the model provider the run chose, so a config.toml the agent writes cannot redirect Codex, and defines the MCP servers DefenseClaw brought along from your Codex setup. Unless the sandbox pack sets mcp.project_servers: allow, requirements.toml allows exactly those servers, which disables every other one, a repository's included. --no-mcp leaves your servers behind.
• MCP gap. Codex matches an allowed server by its command only, and merges a repository's [mcp_servers.<name>] table into yours key by key, so a repository could add environment variables to an imported server of the same name. DefenseClaw leaves such a server behind and names it when the run starts.
• Image and verification. The image installs Codex 0.146.0 by default, replacing the base image's older Codex, and refuses a version without a reviewed Linux hook contract. Verified end to end: against a mock model every required hook fired and a blocked tool call did not run, also with hostile user and project config (features.hooks = false, hooks, a notify program and OTel exporters of their own, a planted BASH_ENV, fake tools on PATH and a forged sandbox token), and a live sandbox run fired the hooks and honoured a deny with a Bedrock Mantle model.

Disable

defenseclaw guardrail disable --connector codex --yes