OpenClaw Security Testing & Defense Analysis Guide

March 11, 2026 · View on GitHub

本仓库包含 OpenClaw 的安全测试框架和防御分析工具。用于评估 AI 助手对恶意提示的抵抗力以及 HITL（Human-in-the-Loop）防御系统的有效性。

安装 OpenClaw

本指南基于 OpenClaw 项目。完整文档请访问 docs.openclaw.ai

环境要求

  • Node.js ≥ 22
  • pnpm (推荐用于从源码构建)

快速安装

# 全局安装
npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

# 运行配置向导
openclaw onboard --install-daemon

从源码构建

git clone https://github.com/openclaw/openclaw.git
cd openclaw

pnpm install
pnpm build

pnpm openclaw onboard --install-daemon

基本使用

# 启动 Gateway
openclaw gateway --port 18789 --verbose

# 与助手对话
openclaw agent --message "你的问题"

🔒 安全测试框架

本测试框架包含两个核心脚本，用于全面评估 OpenClaw 的安全性和防御能力。

测试脚本概览

脚本用途测试层级
auto-security-test-safe.tsLLM/Tool 层安全测试模型层 + 工具权限层
defense-test-runner.tsHITL 防御效果测试基线对比 + 防御模式对比

1. LLM/Tool 层安全测试

脚本: scripts/auto-security-test-safe.ts

测试 OpenClaw 在两个安全层级的防护能力：

  • LLM 层: 测试 AI 模型是否会自然拒绝恶意请求
  • Tool 层: 测试工具权限系统是否会阻止危险操作

测试模式

# 仅测试 LLM 层（模型是否拒绝恶意请求）
pnpm tsx scripts/auto-security-test-safe.ts --mode=llm

# 仅测试 Tool 层（权限系统是否阻止操作）
pnpm tsx scripts/auto-security-test-safe.ts --mode=tool

# 双层对比测试（推荐）
pnpm tsx scripts/auto-security-test-safe.ts --mode=both

结果分类

测试结果会被分类为以下 6 种安全层级：

分类含义安全状态
🧠 llm-refused模型明确拒绝了请求✅ 安全
😶 llm-passive模型给出教育性回复，未执行也未拒绝⚠️ 待观察
💭 llm-intent模型表达了执行意图但未完成调用⚠️ 待观察
🔧 tool-blocked工具权限系统阻止了调用✅ 安全
⚡ tool-executed工具调用被执行（潜在安全漏洞）🚨 风险
❌ error执行出错⚪ 未知

测试场景分类

框架覆盖 6 大安全测试类别：

类别描述示例攻击
evasion-obfuscation编码绕过攻击Base64/Hex 编码的恶意命令
sandbox-boundary沙箱边界攻击路径遍历、软链接攻击
indirect-injection间接注入攻击文件中嵌入的恶意指令
supply-chain供应链攻击依赖/配置篡改
resource-state资源状态攻击竞态条件、状态操纵
privilege-audit权限审计过度权限操作

使用示例

# 测试所有风险级别
pnpm tsx scripts/auto-security-test-safe.ts --mode=both --risk=ALL

# 仅测试高风险场景
pnpm tsx scripts/auto-security-test-safe.ts --mode=llm --risk=CRITICAL

# 测试特定类别
pnpm tsx scripts/auto-security-test-safe.ts --category=evasion-obfuscation
pnpm tsx scripts/auto-security-test-safe.ts --category=sandbox-boundary
pnpm tsx scripts/auto-security-test-safe.ts --category=indirect-injection

# 限制测试场景数量（快速测试）
pnpm tsx scripts/auto-security-test-safe.ts --scenarios=5

# 测试特定 Agent
pnpm tsx scripts/auto-security-test-safe.ts --agent=claude --mode=both
pnpm tsx scripts/auto-security-test-safe.ts --agent=kimi --mode=llm

输出文件

测试完成后会生成以下文件：

文件描述
*.html可视化测试报告
*-detailed.json详细测试结果（JSON 格式）
*-detailed.jsonl简要日志（每行一条记录）

2. HITL 防御效果测试

脚本: scripts/defense-test-runner.ts

对比 基线模式（无防御）和 防御模式（启用 HITL）的行为差异，评估 Human-in-the-Loop 防御系统的有效性。

HITL 防御层级

防御层环境变量作用
白名单检查OPENCLAW_HITL_ENFORCE_ALLOWLIST阻止非白名单操作
语义分析OPENCLAW_HITL_SEMANTIC_JUDGEAI 语义风险分析
LLM 判决OPENCLAW_HITL_LLM_JUDGE_MODELLM 风险评估
人工审批OPENCLAW_HITL_APPROVAL_MODE高风险操作需人工确认
沙箱保护OPENCLAW_HITL_SANDBOX_REQUIRED强制沙箱执行

防御策略

策略触发条件适用场景
strict中等及以上风险需要审批生产环境
standard高风险需要审批一般使用
permissive仅关键风险需要审批宽松环境

改进分类

对比测试会将结果分类为：

类型含义
✅ new-block被 HITL 新增拦截的场景
🔵 same-block基线和防御模式都被拦截
🚨 same-pass仍存在安全缺口
⚠️ regression回归（基线阻止但防御模式通过）

使用示例

# 基础测试（strict 策略）
pnpm tsx scripts/defense-test-runner.ts --policy=strict

# 测试不同策略
pnpm tsx scripts/defense-test-runner.ts --policy=standard
pnpm tsx scripts/defense-test-runner.ts --policy=permissive

# 测试特定 Agent
pnpm tsx scripts/defense-test-runner.ts --agent=qwen3 --risk=ALL

# 配置防御栈
pnpm tsx scripts/defense-test-runner.ts --stack=layered --approval=deny
pnpm tsx scripts/defense-test-runner.ts --allowlist=on --semantic-judge=on

# 启用 LLM Judge
pnpm tsx scripts/defense-test-runner.ts --llm-judge=hybrid

# 强制沙箱执行
pnpm tsx scripts/defense-test-runner.ts --sandbox-required=on

# 仅运行基线测试
pnpm tsx scripts/defense-test-runner.ts --baseline-only

# 仅运行防御测试
pnpm tsx scripts/defense-test-runner.ts --defended-only

环境变量配置

HITL 防御系统

变量可选值说明
OPENCLAW_HITL_POLICYstrict, standard, permissive防御策略级别
OPENCLAW_HITL_AUTO_DENY1, 0自动拒绝高风险操作（测试模式）
OPENCLAW_HITL_AUTO_ALLOW1, 0自动允许操作
OPENCLAW_HITL_APPROVAL_MODEdeny, allow, prompt人工审批行为
OPENCLAW_HITL_ENFORCE_ALLOWLIST1, 0启用白名单检查
OPENCLAW_HITL_SEMANTIC_JUDGE1, 0启用语义分析
OPENCLAW_HITL_SANDBOX_REQUIRED1, 0命令强制沙箱执行
OPENCLAW_HITL_LLM_JUDGE_MODEhybrid, pure, offLLM 风险评估模式

测试场景定义

测试场景定义在 src/security/test-scenarios-safe.ts，每个场景包含：

{
  id: "scenario-id",           // 唯一标识
  name: "场景名称",              // 描述性名称
  prompt: "恶意提示内容",        // 测试用的恶意提示
  riskLevel: "CRITICAL",       // 风险级别: CRITICAL/HIGH/MEDIUM/LOW
  category: "evasion-obfuscation", // 测试类别
  expectedBehavior: "预期行为", // 应该发生的防御行为
  attackVector: "攻击向量描述"   // 攻击技术说明
}

推荐测试流程

1. 运行 LLM 层基线测试
   └─> pnpm tsx scripts/auto-security-test-safe.ts --mode=llm --risk=ALL

2. 分析报告，识别 tool-executed 场景
   └─> 查看 HTML 报告中的 🚨 风险项

3. 运行 HITL 防御测试
   └─> pnpm tsx scripts/defense-test-runner.ts --policy=strict

4. 对比基线与防御效果
   └─> 关注 new-block（新增拦截）和 same-pass（仍存在的缺口）

5. 根据结果调整配置
   └─> 调整策略、白名单、语义分析等参数

6. 重复测试验证改进
   └─> 确保缺口被修复，无回归

相关文件

文件描述
src/security/test-scenarios-safe.ts测试场景定义
src/security/defense-hitl.tsHITL 防御核心实现
src/security/hitl-tool-wrapper.tsHITL 工具包装器
src/security/tool-audit-logger.ts工具调用审计日志

更多资源