openclaw-plugin-security-guard
OpenClaw 安全守卫插件 — 在 AI Agent 调用工具前进行安全检测，支持阻断、审批、熔断降级与可观测性。
功能特性
| 能力 | 说明 |
|---|---|
| 阻断 (Block) | 高危/严重风险 (HIGH/CRIT) 的工具调用直接拦截，附带风险类型说明 |
| 审批 (Approval) | 中危 (WARN) 工具调用触发用户审批流程，支持中英文双语确认 |
| 熔断 (Circuit Breaker) | 安全 API 连续失败时自动熔断，降级放行避免阻塞业务 |
| 可观测性 (Observability) | 内置 metrics 事件枚举 + 结构化日志，支持接入 OpenClaw runtime 指标 |
| 配置热更新 | 支持运行时更改配置无需重启，hotPrefixes 机制 |
| 版本兼容 | 运行时检测 SDK 版本，按能力等级降级注册 |
架构概览 (ASCII)
┌──────────────────────────────────────────────────────────────────┐
│ OpenClaw Runtime │
│ │
│ ┌──────────┐ before_tool_call ┌─────────────────────────┐ │
│ │ Agent │ ──────────────────────▶│ security-guard plugin │ │
│ │ (调用工具)│ │ │ │
│ └──────────┘ │ ┌───────────────────┐ │ │
│ ▲ │ │ Hook Handler │ │ │
│ │ │ │ 1. enabled? │ │ │
│ │ pass / block / approval │ │ 2. whitelist? │ │ │
│ │◀─────────────────────────────│ │ 3. call API │ │ │
│ │ │ │ 4. dryRun? │ │ │
│ │ │ 5. route result │ │ │
│ │ └───────┬───────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼───────────┐ │ │
│ │ │ Circuit Breaker │ │ │
│ │ │ CLOSED→OPEN→HALF │ │ │
│ │ └───────┬───────────┘ │ │
│ │ │ │ │
│ │ ┌───────▼───────────┐ │ │
│ │ │ Security Client │ │ │
│ │ │ POST /check │ │ │
│ │ │ timeout: 200ms │ │ │
│ │ └───────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────┐ │ │
│ │ │ Approval Capability│ │ │
│ │ │ ├─ message-builder │ │ │
│ │ │ ├─ timeout-handler │ │ │
│ │ │ └─ parseDecision │ │ │
│ │ └───────────────────┘ │ │
│ └─────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Security Detection │
│ API (外部后端) │
│ POST /api/v1/ │
│ security/check │
└───────────────────────┘
安装
pnpm add openclaw-plugin-security-guard
在 OpenClaw 配置文件中注册插件：
{
"plugins": [
{
"id": "openclaw-plugin-security-guard",
"config": {
"apiEndpoint": "https://your-security-api.example.com",
"enabled": true
}
}
]
}
配置说明
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
apiEndpoint | string | "" | 安全检测 API 地址，留空则 fail-open |
apiTimeoutMs | integer | 200 | 单次 API 请求超时（最小 50ms） |
circuitBreaker.failureThreshold | integer | 5 | 连续失败几次后触发熔断 |
circuitBreaker.resetTimeoutMs | integer | 60000 | 熔断后等待多久进入半开状态 |
approval.timeoutMs | integer | 60000 | 等待用户审批的最长时间 |
approval.timeoutBehavior | "allow" | "deny" | "deny" | 审批超时后的处理策略 |
enabled | boolean | true | 总开关，关闭后跳过所有检测 |
dryRun | boolean | false | 干跑模式，仅记录日志不实际拦截 |
toolWhitelist | string[] | [] | 白名单中的工具不经过安全检测 |
所有配置均支持运行时热更新（无需重启 Agent）。
SDK 版本兼容性矩阵
| SDK 版本 | 兼容等级 | 能力 |
|---|---|---|
| >= v2026.4.15 | full | hook + 审批 + fail-closed 模式 |
| >= v2026.3.28 | approval | hook + 审批，无 fail-closed |
| >= v2026.3.13 | block-only | 仅 hook，WARN 当作 block 处理 |
| < v2026.3.13 | unsupported | 无法注册，插件不生效 |
插件在启动时自动检测当前 OpenClaw SDK 版本并按能力等级注册。
开发指南
环境准备
git clone <repo-url>
cd openclaw-plugin-security-guard
pnpm install
测试
# 运行全部测试（单元 + 集成）
pnpm test
# 仅单元测试
node --experimental-test-module-mocks --import tsx --test tests/unit/*.test.ts
# 仅集成测试
node --experimental-test-module-mocks --import tsx --test tests/integration/*.test.ts
测试框架：node:test（Node.js 原生测试运行器）+ tsx（TypeScript 加载器）。
构建
pnpm build # tsc 编译到 dist/
Lint
pnpm lint # 检查
pnpm lint:fix # 自动修复
发布
pnpm release # 执行 scripts/release.sh
目录结构
src/
├── config/
│ ├── schema.ts # 配置接口 + 默认值 + JSON Schema
│ └── hot-reload.ts # 配置热更新机制
├── hook/
│ ├── hook-types.ts # Hook 事件/结果类型定义
│ └── before-tool-call.ts # 核心 hook 处理器
├── security/
│ ├── types.ts # 安全检测请求/响应类型
│ ├── client.ts # HTTP 客户端（singleton, fail-open）
│ ├── circuit-breaker.ts # 熔断器（CLOSED→OPEN→HALF_OPEN）
│ └── rules.ts # 安全规则引擎
├── approval/
│ ├── capability.ts # 审批流程管理
│ ├── message-builder.ts # 审批消息构建
│ └── timeout-handler.ts # 超时处理
├── observability/
│ ├── logger.ts # 结构化日志
│ └── metrics.ts # 指标事件发射
└── compat.ts # SDK 版本兼容层
tests/
├── unit/ # 6 个模块的单元测试（111 case）
└── integration/ # E2E 集成测试（8 场景）
许可证
MIT