ClawGuard

Install and configure the ClawGuard security plugin - an LLM-as-a-Judge guardrail that detects and blocks risky tool calls

Security Scan

The skill's instructions, required actions, and requested accesses are coherent with installing a local OpenClaw plugin that evaluates tool calls, but it involves installing third‑party code (npm package) and defaults that can send/log tool-call data so you should review the package and settings before installing.

Purpose & Capability

The name and description (an LLM-as-a-Judge guardrail) match the instructions: enabling the chat completions endpoint and installing an OpenClaw plugin that inspects tool calls and queries your configured LLM. Nothing requested in the SKILL.md appears unrelated to that purpose.

Instruction Scope

Instructions stay on task: enable gateway endpoint, install plugin via openclaw, restart gateway, and configure options. They do instruct checking the gateway token (env var OPENCLAW_GATEWAY_TOKEN) and reading ~/.openclaw/openclaw.json for token mismatch — both are directly relevant to connecting to the local gateway and troubleshooting authentication.

Install Mechanism

The skill is instruction-only (no packaged install spec in the registry) and tells the user to install @capsulesecurity/clawguard from npm via the openclaw plugin manager. Installing an npm package pulls third‑party code from the registry — a moderately risky supply‑chain action that is expected for this use but should be reviewed before installation.

Credentials

The skill does not declare required env vars, but the runtime guidance legitimately references OPENCLAW_GATEWAY_TOKEN and the gateway config file to diagnose 401 errors. Those accesses are proportional to operating the plugin.

Persistence & Privilege

No special persistence flags (always:false). The plugin runs inside OpenClaw after installation; the skill does not request system-wide config changes beyond enabling the chat completions endpoint and plugin configuration. Autonomous invocation by the agent is the platform default and not a unique concern here.

Assessment

This instruction-only skill directs you to install a third‑party npm plugin that will inspect and (by default) log and possibly block tool calls. Before installing: 1) Verify the npm package and its publisher (review the package page and the linked GitHub repo, check recent releases and maintainers). 2) Inspect the plugin source or release tarball if possible to confirm no unexpected behavior. 3) Note defaults: logToolCalls=true and metricsEnabled=true — consider disabling metrics and enabling log-only mode (blockOnRisk=false) initially to avoid unintended data sharing or blocking. 4) Run installation and testing in a staging or isolated environment first, and ensure the gateway token is managed securely (do not paste tokens into public logs). 5) If you need higher assurance, obtain a checksum/signature for the npm package or vendor-signed release before deploying in production.

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:

1. 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"'
   

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:

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