介绍
# ClawGuard Plugin Installation Guide
ClawGuard 是一个安全插件，它使用 LLM-as-a-Judge 机制在执行前评估工具调用，检测并可选地阻止风险操作。
## 前置条件
在安装 ClawGuard 之前，请确保网关的聊天补全端点已启用：
```bash openclaw config set gateway.http.endpoints.chatCompletions.enabled true ```
## 安装
从 npm 安装插件：
```bash openclaw plugins install @capsulesecurity/clawguard ```
安装完成后，重启网关以加载插件。
## Docker 安装
如果在 Docker 中运行 OpenClaw：
```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 ```
**重要：** 重启时请务必使用 `--force-recreate`。普通的 `docker compose restart` **不会**重新加载环境变量。
## 验证安装
检查网关日志以确认初始化消息：
``` [clawguard] Initialized (logging: true, security: true, block: true, metrics: enabled) ```
## 配置
通过 `openclaw config set plugins.clawguard.<option> <value>` 配置 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 # 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 ```
## 网关身份验证
ClawGuard 内部调用网关的 `/v1/chat/completions` 端点。如果您看到 401 Unauthorized 错误：
1. 检查环境中的网关令牌是否与配置匹配： ```bash # Check env var printenv OPENCLAW_GATEWAY_TOKEN
# Check config token cat ~/.openclaw/openclaw.json | grep -A2 '"token"' ```
2. 如果令牌不匹配，请更新您的环境变量并重启网关。
对于 Docker，请确保 `.env` 文件包含正确的 `OPENCLAW_GATEWAY_TOKEN`，并在重启时使用 `--force-recreate`。
## 故障排查
### 405 Method Not Allowed
聊天补全端点未启用。运行：
```bash openclaw config set gateway.http.endpoints.chatCompletions.enabled true ```
### 401 Unauthorized
环境变量与配置之间的令牌不匹配。请参阅上面的网关身份验证部分。
### 插件未加载
1. 检查 `openclaw plugins list` 是否显示 clawguard 2. 重启网关 3. 检查网关日志中的错误信息
## 工作原理
ClawGuard 注册了一个 `before_tool_call` 钩子，执行以下操作：
1. 记录工具调用详情（如果启用了 `logToolCalls`） 2. 将工具上下文发送给 LLM 进行安全评估 3. 返回风险评估（none/low/medium/high/critical） 4. 如果风险为高/严重则阻止执行（如果启用了 `blockOnRisk`）
安全评估使用您配置的 LLM 提供商，因此它适用于您在 OpenClaw 中设置的任何模型。
## 链接
- GitHub: https://github.com/capsulesecurity/clawguard - npm: https://www.npmjs.com/package/@capsulesecurity/clawguard