ClawGuard

# 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:

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

## Installation

Install the plugin from npm:

```bash openclaw plugins install @capsulesecurity/clawguard ```

After installation, restart the gateway to load the plugin.

## Docker Installation

If running OpenClaw in Docker:

```bash # 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

```bash # 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:

1. Check the gateway token in your environment matches the config: ```bash # Check env var printenv OPENCLAW_GATEWAY_TOKEN

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

2. 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: ```bash 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 1. Check `openclaw plugins list` shows clawguard 2. Restart the gateway 3. Check gateway logs for errors

## How It Works

ClawGuard registers a `before_tool_call` hook that:

1. Logs tool call details (if `logToolCalls` is enabled) 2. Sends tool context to an LLM for security evaluation 3. Returns a risk assessment (none/low/medium/high/critical) 4. 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.

## Links

- GitHub: https://github.com/capsulesecurity/clawguard - npm: https://www.npmjs.com/package/@capsulesecurity/clawguard