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

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

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

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: shell.dangerous-rm:Recursive delete on root",
  "findings":   ["shell.dangerous-rm"],
  "detailed_findings": [
    {
      "rule_id":    "shell.dangerous-rm",
      "title":      "Recursive delete on root",
      "severity":   "CRITICAL",
      "confidence": 0.93,
      "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 the in-process HITL signal. The gateway resolves the operator approval inline (via the in-process HILTApprovalManager it constructs in SetHILTApprovalManager()) before returning. There is no HTTP HITL surface — every HITL decision happens in-process and the verdict is downgraded to allow or block before the response is written. The TUI reads HITL state from the audit DB, not from a /v1/hilt/* endpoint.

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.

Headers