openclaw-plugin-security-guard

OpenClaw 安全守卫插件 — 在 AI Agent 调用工具前进行安全检测，支持本地规则引擎、审批流程、熔断降级与配置热更新。

功能特性

能力	说明
本地规则引擎	按工具名配置 `allow` / `approve` / `block` 三种动作，优先于 API 检测
API 安全检测	调用外部安全 API (`POST /api/bot/safe_toolcall`) 判断工具调用风险
阻断 (Block)	高风险工具调用直接拦截，返回结构化拦截原因
审批 (Approval)	中风险时暂停调用，等待用户通过 `security_guard_approve` 授权后重试（一次性，5 分钟 TTL）
熔断 (Circuit Breaker)	安全 API 连续失败时自动熔断，降级放行避免阻塞业务
斜杠命令	`/security-guard on/off/status/mode/rules` 实时管理规则和开关
配置热更新	双层配置：admin 层 (openclaw.json) + 运行时层 (runtime.json)，无需重启
版本兼容	运行时检测 SDK 版本，低于 v2026.3.13 时自动禁用并打印警告

架构概览 (ASCII)

┌──────────────────────────────────────────────────────────────────┐
│                       OpenClaw Runtime                           │
│                                                                  │
│  ┌──────────┐    before_tool_call    ┌──────────────────────────┐ │
│  │  Agent   │ ──────────────────────▶│  security-guard plugin   │ │
│  │ (调用工具)│                        │                          │ │
│  └──────────┘                        │  ┌────────────────────┐  │ │
│       ▲                              │  │  Hook Handler      │  │ │
│       │                              │  │  1. enabled?       │  │ │
│       │  pass / block                │  │  2. own tool?      │  │ │
│       │◀─────────────────────────────│  │  3. local rules?   │  │ │
│       │                              │  │  4. API + breaker  │  │ │
│       │                              │  │  5. mode fallback  │  │ │
│                                      │  └────────┬───────────┘  │ │
│                                      │           │              │ │
│                                      │  ┌────────▼───────────┐  │ │
│                                      │  │  Circuit Breaker   │  │ │
│                                      │  │  CLOSED→OPEN→HALF  │  │ │
│                                      │  └────────┬───────────┘  │ │
│                                      │           │              │ │
│                                      │  ┌────────▼───────────┐  │ │
│                                      │  │  Security Client   │  │ │
│                                      │  │  POST /api/bot/    │  │ │
│                                      │  │    safe_toolcall   │  │ │
│                                      │  └────────────────────┘  │ │
│                                      │                          │ │
│                                      │  ┌────────────────────┐  │ │
│                                      │  │  Approval Store    │  │ │
│                                      │  │  (内存, 5min TTL)   │  │ │
│                                      │  └────────────────────┘  │ │
│                                      └──────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │  Security Detection   │
                    │  API (外部后端)        │
                    │  POST /api/bot/       │
                    │    safe_toolcall      │
                    └───────────────────────┘

安装

pnpm add openclaw-plugin-security-guard

在 OpenClaw 配置文件中注册插件（admin 层配置，管 API 连接）：

{
  "plugins": [
    {
      "id": "openclaw-plugin-security-guard",
      "config": {
        "apiDomain": "https://your-security-api.example.com",
        "apiKey": "your-bearer-token"
      }
    }
  ]
}

提示：enabled、dryRun、mode、rules 属于运行时配置层，通过斜杠命令动态调整，无需写入 openclaw.json。

配置说明

Admin 层（openclaw.json）

写入 openclaw.json 的插件配置，变更通过 OpenClaw 热重载生效。

字段	类型	默认值	说明
`apiDomain`	string	`""`	安全检测 API 域名（如 `https://api.example.com`），留空则跳过 API 调用
`apiKey`	string	`""`	Bearer token，发送 `Authorization: Bearer <key>` 头部
`apiTimeoutMs`	integer	`200`	单次 API 请求超时（最小 50ms）
`circuitBreaker.failureThreshold`	integer	`5`	连续失败几次后触发熔断
`circuitBreaker.resetTimeoutMs`	integer	`60000`	熔断后等待多久进入半开状态

运行时层（runtime.json）

通过斜杠命令动态修改，持久化到 ~/.openclaw/plugins/security-guard/runtime.json。Admin 层同名字段被运行时层覆盖。

字段	类型	默认值	说明
`enabled`	boolean	`true`	总开关，关闭后跳过所有检测
`dryRun`	boolean	`false`	干跑模式，仅记录日志不实际拦截
`mode`	`"strict"` \| `"permissive"`	`"permissive"`	无 API 且无规则命中时的降级策略
`rules`	LocalRule[]	`[]`	本地规则表（优先于 API 检测执行）

合并优先级：DEFAULT → admin → runtime（runtime 字段覆盖同名 admin 字段；若 runtime.rules 为空则继承 admin.rules）

决策流程

每次工具调用触发 before_tool_call 钩子后，按以下顺序决策：

1. enabled=false?
   → 直接放行

2. 是自身工具 security_guard_approve?
   → 放行（避免审批工具被自身拦截）

3. 本地规则命中 (rules)?
   - allow   → 放行
   - block   → 拦截，返回本地规则拦截原因
   - approve → 检查已审批记录 → 消费放行 / 创建新审批并阻断

4. 未配置 apiDomain?
   - dryRun=true     → 放行（记录日志）
   - mode=strict     → 拦截（工具未在规则表中且无 API）
   - mode=permissive → 放行

5. 通过熔断器调用安全 API (POST /api/bot/safe_toolcall)
   ↓ 熔断或网络错误 → fail-open 放行
   ↓ API 成功
   - dryRun=true                    → 放行（忽略结果）
   - biz_is_block_toolcall="1"      → 拦截（高风险）
   - biz_is_confirm_required="1"    → 检查已审批记录 → 消费放行 / 创建新审批并阻断
   - 其他                           → 放行（无风险）

审批流程

当工具调用需要用户确认时（规则动作为 approve 或 API 返回 biz_is_confirm_required="1"）：

在内存审批仓库中创建待审批记录（有效期 5 分钟，ID 格式 sg_xxxxxx）
阻断工具调用，在 blockReason 中向 AI 发送结构化授权请求提示
AI 将审批请求展示给用户
用户同意后，AI 调用 security_guard_approve(approvalId="sg_xxxxxx")
原工具调用重试时，审批记录被消费并放行

审批记录为一次性，消费后立即删除；仓库最多保留 1024 条记录，超出时淘汰最旧记录。

`security_guard_approve` 工具

插件自动注册的内置工具，供 AI 在用户同意后调用。

参数	类型	说明
`approvalId`	string	审批 ID（格式 `sg_xxxxxx`），来自拦截时的提示信息

斜杠命令

插件注册 /security-guard 命令，支持以下子命令：

命令	说明
`/security-guard on`	开启安全守卫
`/security-guard off`	关闭安全守卫
`/security-guard status`	查看当前配置状态（开关、模式、规则、API 域名等）
`/security-guard mode strict`	严格模式：无 API 时拦截所有未命中规则的工具
`/security-guard mode permissive`	宽松模式：无 API 时放行所有工具（默认）
`/security-guard mode dry-run`	干跑模式：仅记录日志，不实际拦截
`/security-guard rules add <tool> [action]`	添加/更新规则（action: allow/approve/block，默认 block）
`/security-guard rules remove <tool>`	删除规则
`/security-guard rules list`	查看当前规则表

安全 API 协议

插件向配置的 apiDomain 发送 POST /api/bot/safe_toolcall 请求。

请求体：

{
  "toolCallName": "bash",
  "command": "rm -rf /tmp/test"
}

command 字段：若工具参数包含 command 字符串字段则直接使用，否则序列化整个 params 对象。

响应体：

{
  "biz_is_block_toolcall": "1",
  "biz_is_confirm_required": "0"
}

字段	值	含义
`biz_is_block_toolcall`	`"1"`	高风险，直接拦截
`biz_is_confirm_required`	`"1"`	中风险，需用户确认

超时（默认 200ms）或网络错误时 fail-open（放行），由熔断器保护避免级联故障。

SDK 版本兼容性

最低 hook 版本：v2026.3.13（低于此版本时插件不生效，输出警告）
声明 peer 版本：openclaw >= 2026.3.28

启动时自动通过 api.config.meta.lastTouchedVersion 或 openclaw.json 探测宿主版本，版本为空时默认为兼容。

开发指南

环境准备

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       # 双层配置合并与热更新（admin + runtime）
│   └── runtime-store.ts    # runtime.json 持久化读写（原子写入）
├── hook/
│   ├── hook-types.ts       # Hook 事件/结果类型定义
│   └── before-tool-call.ts # 核心决策引擎（工厂函数，依赖注入）
├── security/
│   ├── types.ts            # 安全 API 请求/响应类型
│   ├── client.ts           # HTTP 客户端（singleton, fail-open）
│   └── circuit-breaker.ts  # 熔断器（CLOSED→OPEN→HALF_OPEN，滑动窗口）
├── approval/
│   └── index.ts            # 审批仓库 + security_guard_approve 工具注册
├── commands/
│   ├── register.ts         # /security-guard 命令注册
│   └── handler.ts          # 子命令路由与实现
├── utils/
│   ├── logger.ts           # 结构化日志（敏感字段脱敏 + 文件持久化）
│   └── openclaw-version.ts # 宿主版本探测工具
├── compat.ts               # SDK 版本最低要求检测（min v2026.3.13）
└── runtime.ts              # SecurityGuardRuntime 生命周期管理类
tests/
├── unit/                   # 单元测试（各模块独立）
└── integration/            # 集成测试（E2E hook 流程 + 配置持久化）

许可证

MIT

Security Guard