Gateway API

defenseclaw-gateway exposes an HTTP surface used by hook scripts, the OpenClaw plugin, the CLI, and the TUI. This page lists every route the gateway actually registers, grouped by purpose.

This is not an OpenAPI spec — request/response shapes evolve and the canonical source is the handler code. For exact field names, point at the handler in internal/gateway/api.go (which mux.HandleFunc references the implementing file).

Bind address

The gateway binds to localhost by default. To expose the API to the LAN (sandbox/multi-host setups), set gateway.api_bind: "0.0.0.0" in ~/.defenseclaw/config.yaml. defenseclaw setup does this for you when it provisions the sandbox profile.

Auth

Every request — except GET /health — must carry the gateway token. Two header forms are accepted (constant-time compared in tokenAuth):

X-DefenseClaw-Token: <token>
Authorization:        Bearer <token>

The token is resolved from one of, in priority order:

1. The env var named by gateway.token_env (custom name — operator intent wins)
2. DEFENSECLAW_GATEWAY_TOKEN (canonical)
3. OPENCLAW_GATEWAY_TOKEN (legacy fallback for existing installs)
4. gateway.token directly in ~/.defenseclaw/config.yaml

There is no standalone token file (~/.defenseclaw/gateway-token is sometimes mentioned in older docs but the gateway never reads it). Use defenseclaw keys set DEFENSECLAW_GATEWAY_TOKEN to set the canonical env var; it lands in ~/.defenseclaw/.env.

CSRF protection

Every state-changing request also requires X-DefenseClaw-Client (any non-empty value identifying the caller — cli, openclaw-plugin, inspect-hook/1.0, etc.). The middleware rejects same-origin browser requests that lack it with 403. See apiCSRFProtect in api.go.

X-DefenseClaw-Client: cli

Endpoints

Health & status

GET /status carries both a singular and a plural connector field so old and new clients keep working on a multi-connector install:

{
  "connector_mode": "action",
  "connector_modes": [
    {
      "connector": "codex",
      "mode": "observability",
      "policy_mode": "action",
      "enforcement_surface": "agent_lifecycle_hooks",
      "telemetry": ["hook", "otel"],
      "proxy_intercept": false
    },
    {
      "connector": "claudecode",
      "mode": "observability",
      "policy_mode": "observe",
      "enforcement_surface": "agent_lifecycle_hooks",
      "telemetry": ["hook"],
      "proxy_intercept": false
    }
  ]
}

• connector_mode (singular) is a legacy compatibility value for clients written before multi-connector existed. On a fan-out install it is not the authoritative roster view; use connector_modes instead.
• connector_modes (plural) is the authoritative per-connector view: one entry per active connector. mode is the backward-compatible data-path value (guardrail or observability); policy_mode is the operator posture (observe or action); enforcement_surface identifies the proxy, lifecycle-hook, or OmniGent policy API path; telemetry lists active signal sources; and proxy_intercept is true only for proxy connectors. defenseclaw-gateway status renders its per-connector "Connector Mode" section directly from this array.

Connector hooks

Each connector registers exactly one hook endpoint. The path is owned by the connector, declared in its HookAPIPath() method, and registered dynamically in registerConnectorHookRoutes.

All hook endpoints share a per-IP rate limiter (20 RPS, burst 40 — see hookLimiter in api.go). Loopback callers (the on-host hook scripts) are exempt; the limit only applies to remote callers.

Inspection (rate-limited)

The /api/v1/inspect/* family is the hot path that connector hooks and the OpenClaw plugin call to score a single tool call, prompt, or completion. Mounted under a sub-mux that wraps the per-IP rate limiter.

Code & network scanning

Asset scanning

Asset enable / disable

Inventory

Policy

Guardrail control plane

Changing connector uses restart semantics so listener and hook state are rebuilt; it is not accepted as an in-place connector swap.

Enforcement logging

These endpoints are write-only "I just blocked / allowed something" telemetry endpoints used by the OpenClaw plugin to keep the gateway's audit DB authoritative when the plugin makes the decision out-of-band.

Audit

The gateway has no streaming or query HTTP endpoint — read history through the CLI:

defenseclaw-gateway audit export --output audit.jsonl     # JSONL of audit_events
tail -f ~/.defenseclaw/gateway.jsonl | jq                  # Live tail of the JSONL fallback
defenseclaw alerts                                          # Recent alerts (paginated)
defenseclaw tui                                             # Live dashboard

Audit export includes the legacy details text and, when present, first-class structured JSON from audit_events.structured_json. Connector hook rows use schema: "defenseclaw.hook.v1"; older parsers can still read the mirrored details_json= token inside details.

Config

AI usage / discovery (AIBOM)

The continuous AI Discovery surface — see AI Discovery for the operator workflow.

Codex bridge

OTLP receiver

The gateway accepts OTLP-HTTP from connectors (Codex, Gemini CLI native OTLP) and from the local-observability stack. Body is OTLP-JSON.

See internal/gateway/otel_ingest.go for the parsing details and Local observability for the operator setup.

Verdict envelope

The four /api/v1/inspect/* endpoints return a ToolInspectVerdict (or its near-twin for response-side inspection):

{
  "action":     "block | confirm | alert | allow",
  "raw_action": "block",
  "severity":   "CRITICAL | HIGH | MEDIUM | LOW | INFO",
  "confidence": 0.93,
  "reason":     "matched: CMD-RM-RF:Recursive force delete from critical root path",
  "findings":   ["CMD-RM-RF:Recursive force delete from critical root path"],
  "detailed_findings": [
    {
      "rule_id":    "CMD-RM-RF",
      "title":      "Recursive force delete from critical root path",
      "severity":   "CRITICAL",
      "confidence": 0.95,
      "evidence":   "rm -rf /",
      "tags":       ["destructive", "shell"]
    }
  ],
  "mode":       "action | observe",
  "would_block": true,
  "approval_timeout_ms": 0
}

Notable behaviours:

• action is the effective verdict, not the raw policy decision. applyMode() downgrades block / confirm / alert to allow when the gateway is in observe mode, but preserves the raw verdict in raw_action and the would-have-blocked signal in would_block. This is how observe-mode dry-runs work without touching the rule pack.
• confirm is surface-dependent. A native OpenClaw tool-approval caller can receive confirm and resolve it in the plugin. A non-native caller cannot safely pause, so the inspect handler fails the confirmation closed to block. Proxy-lane confirmations may be resolved by the in-process HILTApprovalManager; unsupported proxy surfaces degrade to alert. There is no /v1/hilt/* HTTP API.
• evaluation_id is the runtime join key in telemetry. Inspect calls stamp it on structured JSONL and audit/scan rows, but the current ToolInspectVerdict HTTP schema does not expose evaluation_id or rule_ids. Connector-hook responses do expose both fields, as shown below. See Observability §1.4 for the per-surface contract.
• detailed_findings and findings are both populated for backward compatibility. Existing clients that only read findings: []string are unaffected by the new structured field.

Other endpoints return their own shapes — /v1/skill/scan returns a scanner-specific envelope, /audit/event returns {"status": "stored", "id": "..."}, /skill/disable returns {"status": "disabled", "skillKey": "..."}. Always confirm against the handler code before assuming a shape.

Connector hook responses

Every connector hook response (/api/v1/{claude-code,codex,cursor,...}/hook) carries evaluation_id and the top rule_ids so clients can join it to the audit and scan rows:

{
  "action":        "allow | block | deny | …",
  "reason":        "rule X fired",
  "findings":      ["rule.id.one", "rule.id.two"],
  "evaluation_id": "eval-c1d0…",
  "rule_ids":      ["rule.id.one", "rule.id.two"]
}

Connector-hook responses expose the string findings list, not the inspect endpoint's detailed_findings objects. For /api/v1/inspect/*, evidence is redacted by default; X-DefenseClaw-Reveal-PII: 1 requests raw evidence and creates an audited reveal event. evaluation_id and rule_ids are populated when the hook evaluation produced correlation data.

Headers