Gateway sidecar — DefenseClaw

Overview

The defenseclaw-gateway binary is the enforcement point. It connects to the OpenClaw gateway over WebSocket (device-key authenticated), inspects every tool_call / tool_result, optionally fronts LLM traffic through the guardrail proxy on port 4000, persists verdicts into the SQLite audit store, and exposes a local REST API on port 18970. The Python CLI manages scanners, policies, and config; the Go daemon does the actual live enforcement.

Lifecycle commands

On-boot supervision

systemd (Linux)

DefenseClaw does not install a generic systemd unit during init; install it with:

sudo tee /etc/systemd/system/defenseclaw-gateway@.service > /dev/null <<'EOF'
[Unit]
Description=DefenseClaw gateway sidecar
After=network-online.target
Wants=network-online.target

[Service]
Type=exec
User=%i
ExecStart=/usr/local/bin/defenseclaw-gateway run
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now defenseclaw-gateway@$USER.service

For sandbox standalone mode, init --sandbox generates openshell-sandbox.service and defenseclaw-sandbox.target under ~/.defenseclaw/systemd/ and installs them when run as root — see setup-sandbox.

launchd (macOS)

cat > ~/Library/LaunchAgents/ai.defenseclaw.gateway.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>ai.defenseclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/defenseclaw-gateway</string>
    <string>run</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/defenseclaw-gateway.out.log</string>
  <key>StandardErrorPath</key><string>/tmp/defenseclaw-gateway.err.log</string>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/ai.defenseclaw.gateway.plist

What the sidecar exposes

gateway.api_port and guardrail.port are configurable in config.yaml; the pinned values above are the shipped defaults.

Watchdog

The built-in watchdog is separate from systemd and designed for workstations where users don't run services under an init system. Enable it by setting gateway.watchdog.enabled=true in config.yaml; it auto-starts with start and auto-stops on stop. It polls /health, restarts the daemon on repeated failures, and logs to ~/.defenseclaw/watchdog.log.

Verify it worked

defenseclaw-gateway status
curl -s http://127.0.0.1:18970/health | jq .
curl -s http://127.0.0.1:18970/alerts | jq '.alerts | length'
ps -p $(cat ~/.defenseclaw/gateway.pid)

The /health endpoint returns a JSON map keyed by subsystem: gateway, watcher, guardrail, api, telemetry, splunk, sandbox. Each has state: running|healthy|disabled|stopped|<error>. init parses this and prints a summary.

Undo / reset

defenseclaw-gateway stop
rm -f ~/.defenseclaw/gateway.pid ~/.defenseclaw/gateway.log

Stopping the sidecar does not remove the guardrail's openclaw.json patch. Use defenseclaw setup guardrail --disable to revert OpenClaw to direct LLM mode. See setup-guardrail.

Troubleshooting

Related

• init
• LLM guardrail
• Observability
• Gateway CLI reference