Gateway API

defenseclaw-gateway exposes a sidecar management API used by hook scripts, connector plugins, the CLI, and the TUI. This page lists every static route pattern registered by APIServer.Run, the two provider routes installed by registerProviderRoutes, and every built-in connector hook route.

This is not an OpenAPI specification. The canonical request and response shapes are the handlers in internal/gateway/api.go and the files referenced from its mux.HandleFunc registrations.

Bind address

The API binds to loopback by default. In standalone OpenShell mode only, an empty gateway.api_bind inherits guardrail.host when that value is non-empty and is not the literal localhost; set gateway.api_bind: 127.0.0.1 explicitly when the management API must remain loopback-only. A non-loopback value expands access to the authenticated management surface; protect that listener with host firewalling and a deployment-specific network design. gateway.host and gateway.port describe the upstream agent gateway, while guardrail.host/guardrail.port control the separate guardrail proxy listener.

Auth

Every request except GET /health must authenticate. The shared authentication middleware accepts these header forms; all three are constant-time compared with the resolved gateway token:

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

PATCH /v1/guardrail/config performs a second, endpoint-local check and accepts only Authorization: Bearer or X-DefenseClaw-Token; X-DC-Auth alone is rejected there. The endpoint also rejects every patch in managed_enterprise deployment mode.

Loopback connector hook routes can instead use the matching connector's narrow hook token. The Codex token also authorizes /api/v1/codex/notify. A connector-scoped token on a generic /api/v1/inspect/* route is accepted only over loopback and only when X-DefenseClaw-Connector names the same registered connector.

OTLP credentials are source-specific only for the closed scope set geminicli, codex, and claudecode. Codex and Claude Code send their scoped bearer to /v1/{logs,metrics,traces} together with X-DefenseClaw-Source: codex|claudecode; that header selects and must match the scoped credential. Gemini CLI uses /otlp/geminicli/{token}/v1/{signal} because its exporter cannot add the authorization header. Once a scoped token exists for one of those sources, the master gateway token is rejected for that source's scoped route. Other native OTLP sources, including Copilot and OmniGent, currently authenticate their loopback /v1/{signal} requests with the master gateway 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 ~/.defenseclaw/gateway-token file. On first boot the sidecar creates DEFENSECLAW_GATEWAY_TOKEN in ~/.defenseclaw/.env when neither a supported environment nor dotenv source already supplies a token. Rotate a locally managed token with defenseclaw setup rotate-token --yes; that transaction restarts the gateway and refreshes active connector credentials. An externally managed custom gateway.token_env must be rotated by its owning secret system.

CSRF protection

Every non-GET/HEAD request also requires X-DefenseClaw-Client (any non-empty caller identifier such as cli, openclaw-plugin, or inspect-hook/1.0). POST, PUT, PATCH, and DELETE requests require Content-Type: application/json; OTLP requests instead require application/json or application/x-protobuf. OPTIONS requires the client header but no content type. The only narrow client-header exception is a loopback scoped-token OTLP path, because some native exporters cannot add arbitrary headers; that path still requires an OTLP content type and rejects a non-local browser origin.

All ordinary mutations also reject a non-local Origin; cross-site requests are rejected when Sec-Fetch-Site identifies them. A shared middleware caps ordinary POST, PUT, and PATCH bodies at 1 MiB. Exact authenticated OTLP-HTTP ingest routes use a separate 64 MiB receiver limit so exporter batches can follow the protocol's recommended bound without increasing the limit for the rest of the API.

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": {
    "connector": "codex",
    "mode": "observability",
    "policy_mode": "action",
    "guardrail_mode": "action",
    "hook_fail_mode": "closed",
    "enabled": true,
    "hook_enforcement": true,
    "enforcement_surface": "agent_lifecycle_hooks",
    "telemetry": ["hooks", "otel", "notify"],
    "proxy_intercept": false
  },
  "connector_modes": [
    {
      "connector": "codex",
      "mode": "observability",
      "policy_mode": "action",
      "guardrail_mode": "action",
      "hook_fail_mode": "closed",
      "enabled": true,
      "hook_enforcement": true,
      "enforcement_surface": "agent_lifecycle_hooks",
      "telemetry": ["hooks", "otel", "notify"],
      "proxy_intercept": false
    },
    {
      "connector": "claudecode",
      "mode": "observability",
      "policy_mode": "observe",
      "guardrail_mode": "observe",
      "hook_fail_mode": "closed",
      "enabled": true,
      "hook_enforcement": false,
      "enforcement_surface": "agent_lifecycle_hooks",
      "telemetry": ["hooks", "otel"],
      "proxy_intercept": false
    }
  ]
}

• connector_mode (singular) is the same summary object for the primary connector, retained 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 and guardrail_mode report the effective observe/action posture; hook_fail_mode is the effective hook fail mode; enabled is the connector's effective guardrail enablement; hook_enforcement is true for a non-proxy connector in action mode; enforcement_surface identifies the proxy, lifecycle-hook, or OmniGent policy API path; telemetry lists reported wiring channels; 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

Built-in connectors that implement the hook endpoint contract register the following routes. Proxy connectors such as OpenClaw and ZeptoClaw do not register a connector hook route.

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.

/api/v1/inspect/tool is the existing trusted tool-call entry point; there is no client-supplied is_tool_call switch and no additional semantic endpoint. The authenticated route and its server-side connector identity establish the boundary. A request with tool: "message" stays in the message lane and is not eligible for structured tool-call CEL rules.

Single-call semantic findings are available on this inspect route and on native pre-tool hooks. Ordered tool chains are stricter: they use durable SQLite state only on authenticated /api/v1/{connector}/hook events with canonical connector and session correlation. Inspect, proxy, router, and OTLP traffic never advance a chain. Only a matching authoritative successful result can promote an existing pending proposal into a durable successful predecessor. A chain can deny only its final step on an enforcement-safe synchronous pre-tool event. Post-tool and tool-result events never make the final blocking decision. See the stateful connector lifecycle for the pairing, state-level, and cutoff contracts. Chain matches are HIGH severity and retain the connector's effective action matrix: default and permissive profiles alert, strict blocks, and eligible human-in-the-loop configurations confirm. A durable deny receipt is created only when that effective action is block.

Chain state contains bounded masks and fingerprints rather than raw commands, arguments, paths, endpoints, or tool payloads. Durable deny receipts replay the same final decision without duplicating finding telemetry.

Code & network scanning

Asset scanning

Asset enable / disable

These routes return 503 when no upstream client object is present and 502 when an attempted upstream RPC fails, including a disconnected client. They do not perform the CLI's filesystem quarantine/restore workflow.

Inventory

Provider registry

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 manage the durable enforcement allow/block lists.

Audit

There is no general audit-history or streaming HTTP route. Read/export history through the CLI:

defenseclaw-gateway audit export --output audit.jsonl     # JSONL of audit_events
tail -f ~/.defenseclaw/gateway.jsonl | jq                  # Optional configured v8 JSONL destination
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

Runtime control and internal observability bridges

These authenticated routes are narrow process/CLI integration seams rather than general-purpose ingestion APIs.

AI usage / discovery (AIBOM)

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

Correlation ledger

Each read route accepts exactly one supported identity anchor (for example record_id, evaluation_id is not a supported query key here, semantic_event_id, session_id, trace_id, or tool_invocation_id) and supports bounded cursor pagination.

Codex bridge

OTLP receiver

The gateway accepts OTLP-HTTP from configured connectors. Both OTLP JSON and protobuf content types are accepted; decoding is implemented in internal/gateway/otel_ingest.go. Request bodies are bounded at 64 MiB; larger batches receive HTTP 413 and are recorded as content-free body_too_large rejections.

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

Verdict envelope

All four /api/v1/inspect/* endpoints serialize the same ToolInspectVerdict:

{
  "action":     "block | confirm | alert | allow",
  "raw_action": "block",
  "severity":   "CRITICAL | HIGH | MEDIUM | LOW | INFO | NONE",
  "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": 45000
}

Notable behaviours:

• action is the effective verdict, not the raw policy decision. applyMode() downgrades block, confirm, and alert to allow outside action mode and preserves the original in raw_action. It sets would_block: true only for a downgraded block; downgraded confirm and alert leave that field false/omitted.
• 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.
• Pattern-rule and CodeGuard decisions populate both representations for backward compatibility. Clean verdicts can omit details, and static, MCP, or AID merge paths can add string findings without synthesizing matching detailed_findings.
• Optional fields are omitted when empty. In particular, approval_timeout_ms is absent when its value is zero. A structured finding can additionally include tool_capability_class; it has no remediation field.
• Empty request/response content takes a fast allow path. Those two handlers return the same verdict type, but before applyMode() runs; the serialized non-optional mode is therefore an empty string and raw_action is absent.

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

Connector hook responses

A connector hook response can carry evaluation_id and the top rule_ids when the evaluation produced correlation data:

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

Connector-hook responses expose a string findings list, not the inspect endpoint's detailed_findings objects. Pattern-rule entries normally use rule_id:title; some scanner-specific paths emit bare finding IDs. rule_ids is the canonical bare-ID list populated with evaluation_id when the hook evaluation produced correlation data.

For /api/v1/inspect/*, evidence is redacted by default. X-DefenseClaw-Reveal-PII: 1 requests raw response evidence. The tool-inspect handler records an inspect-reveal audit event; the request, response, and tool-response handlers currently reveal without that extra audit event.

Headers