ClawGuard 插件安装指南

ClawGuard 是一款安全插件，它利用 LLM 作为裁判（LLM-as-a-Judge），在执行前评估工具调用，以检测并可选地阻止有风险的操作。

先决条件

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

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

安装

通过 npm 安装插件：

openclaw plugins install @capsulesecurity/clawguard

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

Docker 安装

如果在 Docker 中运行 OpenClaw：

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

配置

通过以下命令配置 ClawGuard：openclaw config set plugins.clawguard.<选项> <值>选项

配置示例

# 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 未授权错误：

1. 请检查您环境中的网关令牌是否与配置匹配：

   # 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 方法不被允许

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

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

401 未授权

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

插件未加载

1. 检查openclaw 插件列表显示 clawguard
2. 重启网关
3. 检查网关日志以查找错误

工作原理

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

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

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

链接

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