Source Code

ClawGuard Plugin Installation Guide

ClawGuard is a security plugin that uses an LLM-as-a-Judge to evaluate tool calls before execution, detecting and optionally blocking risky operations.

Prerequisites

Before installing ClawGuard, ensure the gateway's chat completions endpoint is enabled:

openclaw config set gateway.http.endpoints.chatCompletions.enabled true

Installation

Install the plugin from npm:

openclaw plugins install @capsulesecurity/clawguard

After installation, restart the gateway to load the plugin.

Docker Installation

If running OpenClaw in Docker:

# Install the plugin
docker compose run --rm openclaw-cli plugins install @capsulesecurity/clawguard

# Restart gateway with force-recreate to reload env vars
docker compose up -d --force-recreate openclaw-gateway

Important: Always use --force-recreate when restarting. Plain docker compose restart does NOT reload environment variables.

Verify Installation

Check the gateway logs for the initialization message:

[clawguard] Initialized (logging: true, security: true, block: true, metrics: enabled)

Configuration

Configure ClawGuard via openclaw config set plugins.clawguard.<option> <value>:

Option	Default	Description
enabled	true	Enable/disable the plugin
logToolCalls	true	Log tool call JSON to gateway logs
securityCheckEnabled	true	Run LLM security evaluation
blockOnRisk	true	Block high/critical risk tool calls
maxContextWords	2000	Session context word limit for evaluation
timeoutMs	15000	Security check timeout in milliseconds
gatewayHost	127.0.0.1	Gateway host for LLM calls
gatewayPort	18789	Gateway port for LLM calls
metricsEnabled	true	Enable anonymous usage metrics

Example Configuration

# Disable blocking (log-only mode)
openclaw config set plugins.clawguard.blockOnRisk false

# Increase timeout for slower models
openclaw config set plugins.clawguard.timeoutMs 30000

# Disable metrics collection
openclaw config set plugins.clawguard.metricsEnabled false

Gateway Authentication

ClawGuard calls the gateway's /v1/chat/completions endpoint internally. If you see 401 Unauthorized errors:

Check the gateway token in your environment matches the config:

# Check env var
printenv OPENCLAW_GATEWAY_TOKEN

# Check config token
cat ~/.openclaw/openclaw.json | grep -A2 '"token"'

If tokens don't match, update your environment and restart the gateway.

For Docker, ensure .env contains the correct OPENCLAW_GATEWAY_TOKEN and use --force-recreate when restarting.

Troubleshooting

405 Method Not Allowed

The chat completions endpoint is not enabled. Run:

openclaw config set gateway.http.endpoints.chatCompletions.enabled true

401 Unauthorized

Token mismatch between environment and config. See Gateway Authentication section above.

Plugin Not Loading

Check openclaw plugins list shows clawguard
Restart the gateway
Check gateway logs for errors

How It Works

ClawGuard registers a before_tool_call hook that:

Logs tool call details (if logToolCalls is enabled)
Sends tool context to an LLM for security evaluation
Returns a risk assessment (none/low/medium/high/critical)
Blocks execution if risk is high/critical (if blockOnRisk is enabled)

The security evaluation uses your configured LLM provider, so it works with any model you have set up in OpenClaw.

clawguard