# 方式一：ClawHub（推荐）
openclaw plugins install clawhub:@victorqr/clawguard

# 更新
openclaw plugins update clawguard

# 查看插件状态
openclaw plugins list | grep clawguard

# 完整状态（含速率限制、完整性、会话统计）
curl -s http://127.0.0.1:18789/gateway/clawguard.status | jq

{
  "plugin": "ClawGuard",
  "version": "0.3.2",
  "mode": "supervised",
  "fallbackMode": false,
  "integrity": true,
  "rules": { "deny": 33, "allow": 45, "approve": 31 },
  "auditDir": "/home/victor/.clawguard/audit",
  "activeSessions": 1,
  "rateLimit": {
    "recentExecs": 3,
    "denyCount": 0,
    "escalated": false,
    "paused": false
  },
  "currentSession": {
    "channel": "direct",
    "commandCount": 15,
    "denyCount": 0,
    "approveCount": 0
  }
}

DENY list (最高)
   ↓ 未命中
ALLOW list
   ↓ 未命中
APPROVE list
   ↓ 未命中
Policy 文件 (allow_cmd prefix match)
   ↓ 未命中
默认放行（按模式决定：permissive=放行, supervised=审批, enforce=拒绝）

正常:     exec(1) exec(2) ... exec(9) → 放行
Burst:    exec(10) → 暂停 30s ⏳
Global:   exec(50+) → 阻断 🚫 (记录 audit)
Escalate: deny(1) deny(2) deny(3) → 自动 enforce 🔴

加载 policy.ini
    ↓
第一次加载？→ 计算 SHA256 → 存储到 .policy-hash → 通过
    ↓
后续加载 → 比对存储的 SHA256
    ├── 一致 → 通过 ✅
    └── 不一致 → 解析新内容
              ├── 解析成功 → 更新哈希（合法修改） → 通过 ✅
              └── 解析失败 → 回退 enforce 模式 🚫

exec:systemctl --user restart openclaw-gateway
file:/home/victor/.openclaw/workspace/user_workspace/temp/backup.tar.gz
net:https://api.github.com/repos/VictorQR/clawguard

{"timestamp":"2026-05-09T10:53:20.000Z","toolName":"exec","params":"{\"command\":\"ls -la\"}","result":"","toolCallId":"abc123","durationMs":12,"error":null,"session":"agent:main:qqbot:direct:0a39eb...","command":"ls -la"}
{"timestamp":"2026-05-09T10:53:25.000Z","toolName":"exec","params":"{\"command\":\"rm -rf /tmp/test\"}","result":"","toolCallId":"def456","durationMs":5,"error":null,"decision":"DENY","rule":"rm_rf_deny","session":"agent:main:qqbot:direct:0a39eb...","command":"rm -rf /tmp/test"}

[
  {"hour": "00:00", "total": 5, "denied": 0, "approved": 0},
  {"hour": "01:00", "total": 120, "denied": 3, "approved": 2},
  {"hour": "02:00", "total": 87, "denied": 1, "approved": 1}
]

curl -s http://127.0.0.1:18789/gateway/clawguard.report \
  -H "Content-Type: application/json" \
  -d '{"type":"weekly"}' | jq

# ClawGuard Policy File
# =====================
# 运行模式（permissive | supervised | enforce）
mode = supervised

# ── 命令白名单 ──────────────────────────
# 支持前缀匹配，$WORKSPACE 自动解析
allow_cmd = gio trash *
allow_cmd = git status
allow_cmd = git log
allow_cmd = git diff
allow_cmd = python3 $WORKSPACE/user_workspace/
allow_cmd = npx tsx tests/

# ── 域名白名单 ──────────────────────────
allow_domain = api.github.com
allow_domain = api.deepseek.com
allow_domain = api.tavily.ai
allow_domain = registry.npmjs.org
allow_domain = pypi.org

# ── 文件写入白名单 ──────────────────────
# 支持 ** glob，~ 自动展开
allow_write = ~/.openclaw/workspace/**
allow_write = /tmp/**

OpenClaw Gateway 进程
│
├── 其他插件 / 原生工具
│
└── @victorqr/clawguard (进程内 TypeScript 插件)
    │
    ├── before_tool_call (priority=100)
    │   ├── parseChannelType()    → 通道解析（私聊/群聊/Cron）
    │   ├── RateLimiter.check()   → 速率限制（burst/global/escalation）
    │   ├── extractCommand()      → 统一命令提取
    │   ├── checkBypass()         → 编码绕过检测
    │   ├── Policy.checkCommand() → Policy 文件规则
    │   ├── checkCommand()        → 三段式规则引擎（DENY>ALLOW>APPROVE）
    │   ├── checkFileWrite/Read() → 文件路径规则
    │   └── checkDomain()         → 网络域名白名单
    │
    ├── after_tool_call (priority=50)
    │   ├── auditLog.append()     → 脱敏 → JSONL 写入
    │   └── stats.recordCall()    → 更新会话统计
    │
    ├── RateLimiter (v0.2.0)
    │   ├── 30s sliding window burst detection
    │   ├── 5min global cap
    │   └── Consecutive deny → auto enforce
    │
    ├── StatsCollector (v0.2.0)
    │   ├── Per-session counters
    │   ├── Hourly heatmap
    │   └── Weekly report generator
    │
    ├── PolicyEngine
    │   ├── ~/.clawguard/policy.ini → parse → watch
    │   ├── ~/.clawguard/.policy-hash → SHA256 校验
    │   └── 损坏时回退 enforce 兜底
    │
    ├── AuditLogger
    │   ├── ~/.clawguard/audit/YYYY-MM-DD.jsonl
    │   └── 90 天轮转 + 敏感信息脱敏
    │
    └── Gateway Methods
        ├── clawguard.status  → 完整运行状态
        ├── clawguard.config  → 策略重载/查看
        └── clawguard.report  → 周报/热力图/会话统计

index.ts
├── rateLimiter.ts    # 速率限制（无外部依赖）
├── session-stats.ts  # 统计收集（fs）
├── policy.ts         # 策略引擎（fs, crypto, os）
├── audit.ts          # 审计日志（fs, os）
├── rules.ts          # 规则加载匹配（fs）
├── extractor.ts      # 命令提取（无依赖）
├── bypass.ts         # 绕过检测（无依赖）
├── file-rules.ts     # 文件规则（fs, minimatch）
├── network-rules.ts  # 网络规则（url）
└── types.ts          # 类型定义

{
  plugin: string;          // "ClawGuard"
  version: string;         // "0.2.0"
  mode: string;            // "permissive" | "supervised" | "enforce"
  fallbackMode: boolean;   // 是否处于回退 enforce 模式
  integrity: boolean;      // policy.ini SHA256 完整性
  rules: {
    deny: number;          // DENY 规则数
    allow: number;         // ALLOW 规则数
    approve: number;       // APPROVE 规则数
  };
  auditDir: string;        // 审计日志目录
  policySummary: {
    mode: string;
    rules: number;
    fallback: boolean;
    integrity: boolean;
  };
  activeSessions: number;  // 活跃会话数
  rateLimit: {             // 当前会话速率状态
    recentExecs: number;
    denyCount: number;
    escalated: boolean;
    paused: boolean;
    pauseRemaining: number;
  } | null;
  currentSession: {        // 当前会话统计
    sessionKey: string;
    channel: string;
    commandCount: number;
    denyCount: number;
    approveCount: number;
    bypassDetections: number;
    totalDurationMs: number;
    topDenied: Array<{command:string; count:number}>;
    toolCalls: Record<string, number>;
  } | null;
}

cd ~/github/clawguard

# TypeScript 编译
npm run build

# 单元测试（规则引擎 + 绕过检测）
npx tsx tests/rules.test.ts

# 集成测试（端到端拦截）
npx tsx tests/integration.test.ts