ClawSentry

OpenClaw 插件，提供工具调用的安全策略拦截能力。每次 before_tool_call 事件触发时，依次经过本地策略检查和远端服务检查两道关卡。

---

配置项

在 ~/.openclaw/openclaw.json 中配置（插件自定义字段必须嵌套在 config 下）：

{
  "plugins": {
    "entries": {
      "clawsentry": {
        "enabled": true,
        "config": {
          "apiKey": "your-api-key",
          "backendEndpoint": "https://your-clawsentry-server",
          "timeoutMs": 5000,
          "policy": { "rules": [] }
        }
      }
    }
  }
}

字段	说明	默认值
enabled	是否启用插件	false
apiKey	远端服务鉴权 key，也可通过 CLAWSENTRY_API_KEY 环境变量设置	—
backendEndpoint	远端审计服务地址，也可通过 BACKEND_ENDPOINT 环境变量设置	—
timeoutMs	远端请求超时（ms）	5000
policy	策略规则配置	—

---

拦截流程

tool call 触发
     │
     ▼
【Step 1】本地策略检查
     │
     ├─ 命中 deny        ──────────────→ 直接 block，结束
     │
     ├─ 命中 remote_check  ────────────→ 强制进入 Step 2
     │
     └─ 未命中任何规则（或命中 allow）
          │
          ├─ 配置了 endpoint  ──────────→ 进入 Step 2
          └─ 未配置 endpoint  ──────────→ 放行
     │
     ▼
【Step 2】远端服务检查
  POST {endpoint}/v1/tool/check → { allowed, reason }
     │
     ├─ allowed: false  ──→ block
     └─ allowed: true   ──→ 放行

---

策略规则（Policy Rules）

action 类型

action	行为
allow	命中即放行，后续规则不再匹配
deny	命中即拦截，返回 block
remote_check	命中后不在本地裁决，强制请求服务端判断是否放行。若未配置 endpoint 则 block

remote_check vs 配置 endpoint 的区别

• 配置 endpoint：所有 tool call 都经过服务端审查（全量模式）
• remote_check 规则：仅命中规则的 tool call 转交服务端，其余本地放行（精准模式）

规则结构

{
  id: string;                                   // 规则唯一 ID
  action: "allow" | "deny" | "remote_check";
  tool: string;                                 // 工具名，支持 "*" 通配全部，支持 "prefix_*" 前缀通配
  params?: Record<string, unknown>;             // 工具参数子集匹配（可选）
                                                // key 为工具实际参数字段名，值支持 * 通配符
                                                // 例：exec 工具的参数字段是 command，不是 path
}

规则按数组顺序首次命中即停止，未命中任何规则时默认放行。

params 说明：params 里的 key 必须与被拦截工具实际传入的参数字段名一致，插件对 key 名没有任何内置约定。 例如拦截 exec 工具时用 { "command": "rm -rf *" }，而不是 { "path": "..." }。

示例

{
  "rules": [
    {
      "id": "deny-rm-rf",
      "action": "deny",
      "tool": "exec",
      "params": { "command": "rm -rf *" }
    },
    {
      "id": "deny-clawhub-install",
      "action": "deny",
      "tool": "exec",
      "params": { "command": "clawhub install *" }
    },
    {
      "id": "remote-check-exec",
      "action": "remote_check",
      "tool": "exec"
    },
    {
      "id": "allow-read",
      "action": "allow",
      "tool": "read_file"
    }
  ]
}

---

远端服务接口

远端检查请求：

POST {backendEndpoint}/v1/tool/check
Authorization: Bearer {apiKey}
Content-Type: application/json

{
  "tool": "write_file",
  "params": { ... },
  "userId": "user-123",
  "agentId": "agent-abc",
  "contextId": "session-xyz"
}

响应：

{ "allowed": true }
{ "allowed": false, "reason": "操作不在授权范围内" }