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:
CODEBLOCK0
Installation
Install the plugin from npm:
CODEBLOCK1
After installation, restart the gateway to load the plugin.
Docker Installation
If running OpenClaw in Docker:
CODEBLOCK2
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:
CODEBLOCK3
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
CODEBLOCK4
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:
CODEBLOCK5
- 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:
CODEBLOCK6
401 Unauthorized
Token mismatch between environment and config. See Gateway Authentication section above.
Plugin Not Loading
- 1. 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:
- 1. 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.
Links
- - GitHub: https://github.com/capsulesecurity/clawguard
- npm: https://www.npmjs.com/package/@capsulesecurity/clawguard
技能名称: clawguard
详细描述:
ClawGuard 插件安装指南
ClawGuard 是一款安全插件，它采用大语言模型作为评判者的方式，在执行工具调用前进行评估，检测并可选地阻止高风险操作。
前置条件
安装 ClawGuard 前，请确保网关的聊天补全端点已启用：
bash
openclaw config set gateway.http.endpoints.chatCompletions.enabled true
安装
通过 npm 安装插件：
bash
openclaw plugins install @capsulesecurity/clawguard
安装完成后，重启网关以加载插件。
Docker 安装
如果在 Docker 中运行 OpenClaw：
bash
安装插件
docker compose run --rm openclaw-cli plugins install @capsulesecurity/clawguard
使用强制重建重启网关以重新加载环境变量
docker compose up -d --force-recreate openclaw-gateway
重要提示： 重启时务必使用 --force-recreate。仅使用 docker compose restart 不会重新加载环境变量。
验证安装
检查网关日志中是否出现初始化消息：
[clawguard] Initialized (logging: true, security: true, block: true, metrics: enabled)
配置
通过 openclaw config set plugins.clawguard.<选项> <值> 配置 ClawGuard：
| 选项 | 默认值 | 描述 |
|---|
| enabled | true | 启用/禁用插件 |
| logToolCalls |
true | 将工具调用 JSON 记录到网关日志 |
| securityCheckEnabled | true | 运行 LLM 安全评估 |
| blockOnRisk | true | 阻止高/严重风险的工具调用 |
| maxContextWords | 2000 | 用于评估的会话上下文词数限制 |
| timeoutMs | 15000 | 安全检查超时时间（毫秒） |
| gatewayHost | 127.0.0.1 | 用于 LLM 调用的网关主机 |
| gatewayPort | 18789 | 用于 LLM 调用的网关端口 |
| metricsEnabled | true | 启用匿名使用指标 |
配置示例
bash
禁用阻止（仅记录模式）
openclaw config set plugins.clawguard.blockOnRisk false
为较慢的模型增加超时时间
openclaw config set plugins.clawguard.timeoutMs 30000
禁用指标收集
openclaw config set plugins.clawguard.metricsEnabled false
网关认证
ClawGuard 会在内部调用网关的 /v1/chat/completions 端点。如果遇到 401 未授权错误：
- 1. 检查环境中的网关令牌是否与配置匹配：
bash
# 检查环境变量
printenv OPENCLAW
GATEWAYTOKEN
# 检查配置中的令牌
cat ~/.openclaw/openclaw.json | grep -A2 token
- 2. 如果令牌不匹配，请更新环境变量并重启网关。
对于 Docker，请确保 .env 文件中包含正确的 OPENCLAWGATEWAYTOKEN，并在重启时使用 --force-recreate。
故障排除
405 方法不允许
聊天补全端点未启用。请运行：
bash
openclaw config set gateway.http.endpoints.chatCompletions.enabled true
401 未授权
环境变量与配置中的令牌不匹配。请参阅上方网关认证部分。
插件未加载
- 1. 检查 openclaw plugins list 是否显示 clawguard
- 重启网关
- 检查网关日志中的错误信息
工作原理
ClawGuard 注册了一个 beforetoolcall 钩子，该钩子会：
- 1. 记录工具调用详情（如果启用了 logToolCalls）
- 将工具上下文发送给 LLM 进行安全评估
- 返回风险评估结果（无/低/中/高/严重）
- 如果风险为高或严重，则阻止执行（如果启用了 blockOnRisk）
安全评估使用您配置的 LLM 提供商，因此它可以与您在 OpenClaw 中设置的任何模型配合使用。
相关链接
- - GitHub：https://github.com/capsulesecurity/clawguard
- npm：https://www.npmjs.com/package/@capsulesecurity/clawguard
