名称： clawguard
描述： 安装并配置 ClawGuard 安全插件——一个基于 LLM 作为裁判的安全护栏，用于检测并拦截有风险的工具调用
元数据： {"openclaw":{"emoji":"🛡️","homepage":"https://github.com/capsulesecurity/clawguard"}}

ClawGuard 插件安装指南

ClawGuard 是一个安全插件，它利用 LLM 作为裁判，在执行前评估工具调用，以检测并可选地拦截高风险操作。

前提条件

安装 ClawGuard 前，请确保网关的聊天补全端点已启用：

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

安装

从 npm 安装插件：

openclaw plugins install @capsulesecurity/clawguard

安装完成后，重启网关以加载插件。

Docker 安装

如果在 Docker 中运行 OpenClaw：

# 安装插件
docker compose run --rm openclaw-cli plugins install @capsulesecurity/clawguard

# 重启网关并使用 --force-recreate 重新加载环境变量
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：

配置示例

# 禁用拦截（仅日志模式）
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_GATEWAY_TOKEN

# 检查配置中的令牌
cat ~/.openclaw/openclaw.json | grep -A2 '"token"'
```

2. 如果令牌不匹配，请更新环境变量并重启网关。

对于 Docker，请确保 .env 文件中包含正确的 OPENCLAW_GATEWAY_TOKEN，并在重启时使用 --force-recreate。

故障排除

405 方法不允许

聊天补全端点未启用。请运行：

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

401 未授权

环境变量与配置中的令牌不匹配。请参阅上方的“网关认证”部分。

插件未加载

1. 检查 openclaw plugins list 是否显示 clawguard
2. 重启网关
3. 检查网关日志中的错误信息

工作原理

ClawGuard 注册了一个 before_tool_call 钩子，该钩子会：

1. 记录工具调用详情（如果 logToolCalls 已启用）
2. 将工具上下文发送给 LLM 进行安全评估
3. 返回风险评估结果（无/低/中/高/严重）
4. 如果风险为高/严重，则阻止执行（如果 blockOnRisk 已启用）

安全评估使用您在 OpenClaw 中配置的 LLM 提供商，因此可与您设置的任何模型配合使用。

相关链接

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