Codex

Codex connector wires versioned lifecycle hooks, native OTel logs/metrics/traces, and the notify bridge without inserting a model proxy.

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

The Codex connector is hook-only. There is no LLM-proxy data path — Codex talks directly to its native upstream (api.openai.com or the ChatGPT backend) and DefenseClaw observes via hooks + native OTel.

mode=action is supported on Codex's declared blocking hook events. For example, PreToolUse can return permissionDecision: "deny" before the tool. Observation-only events and agent activity outside the registered hook contract are not proxy-intercepted.

Setup

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.

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

%CODEX_HOME%\managed_config.toml carries the managed hook matrix. %CODEX_HOME%\config.toml carries DefenseClaw-marked OTLP and notify fields. Generated runtime and protected connector credentials live below %USERPROFILE%\.defenseclaw\hooks. Use setup/teardown commands; do not edit or copy those entries manually. See the Windows path reference.

config.toml (DefenseClaw-managed hooks, OTel, and notify fields)

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

Block events

UserPromptSubmit
PreToolUse
PermissionRequest
PostToolUse
Stop

Native ask events

None — confirm verdicts are downgraded with the raw action preserved.

Codex has no native ask surface here. Confirm verdicts become an alert/system message with raw_action preserved so operators can review the original action in audit or the TUI. That review cannot resume the hook call.

Telemetry channels at boot

Three independent channels make Codex one of the most thoroughly inspected agents.

Disable

defenseclaw guardrail disable --connector codex --yes

For the exact native Windows event and fail-mode boundary, see Connectors and enforcement.