@hddz/plugin-harness

OpenClaw Harness Engineering 插件 - 为 AI Agent 构建约束、反馈与控制系统

最新版本: v0.2.3 (2026-03-25) ✨ 安装即配置

🎯 功能

• ✅ 配置验证：修改 openclaw.json 前自动验证
• ✅ Skill 审核：安装 Skill 前自动安全扫描
• ✅ 循环检测：防止 AI 反复修改同一文件
• ✅ 文件保护：保护关键文件（SOUL.md 等）不被误删
• ✅ 操作审计：记录所有关键操作
• ✅ Trace 追踪：完整的工具调用链路
• ✅ 文件监听器 (v0.2.0 新增)：实时监听配置文件变化，用户手动编辑也能触发验证
• ✅ 自动配置 (v0.2.3 新增)：安装时自动配置，无需手动编辑

🚀 快速开始

安装（一键完成）

# 从 npm 安装（推荐）- 自动配置！
npm install @hddz/[email protected]

# 安装完成后重启 Gateway
openclaw gateway restart

🎉 就这么简单！ 安装脚本会自动：

1. 将 harness 添加到允许插件列表
2. 配置默认安全选项
3. 备份原配置文件
4. 提示你重启 Gateway

手动配置（可选）

如果你想自定义配置，编辑 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "allow": ["harness"],
    "entries": {
      "harness": {
        "enabled": true,
        "config": {
          "autoValidateConfig": true,
          "autoAuditSkill": true,
          "loopDetectionEnabled": true,
          "protectedFiles": [
            "SOUL.md",
            "USER.md",
            "AGENTS.md",
            "TOOLS.md",
            "MEMORY.md",
            "openclaw.json"
          ],
          "logsDir": "logs/harness"
        }
      }
    }
  }
}

然后重启 gateway：

openclaw gateway restart

📋 配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | autoValidateConfig | boolean | true | 配置修改前自动验证 | | autoAuditSkill | boolean | true | Skill 安装前自动审核 | | loopDetectionEnabled | boolean | true | 启用循环检测 | | protectedFiles | string[] | 见上文 | 受保护的文件列表 | | logsDir | string | logs/harness | 日志目录 |

🔍 使用示例

配置验证（自动）

// 修改 openclaw.json 时自动触发
const result = await plugin.onConfigChange(newConfig);
// 如果验证失败，会抛出异常阻止修改

Skill 审核（自动）

// 安装 Skill 时自动触发
const auditResult = await plugin.onSkillInstall('/path/to/skill');
if (!auditResult.passed) {
  throw new Error(`Skill 审核未通过：${auditResult.riskLevel}`);
}

手动查询

# 查看最近的配置变更
harness get-config-changes -l 10

# 查看操作日志
harness get-operations -l 20

# 查看循环检测统计
harness loop-stats

🛡️ 安全机制

保护文件

以下文件默认受保护，修改/删除前会告警：

• SOUL.md - 身份定义
• USER.md - 用户信息
• AGENTS.md - Agent 指南
• TOOLS.md - 工具配置
• MEMORY.md - 长期记忆
• openclaw.json - 核心配置

风险等级

| 等级 | 标识 | 处理 | |------|------|------| | LOW | 🟢 | 允许 | | MEDIUM | 🟡 | 警告，但允许 | | HIGH | 🟠 | 阻止，需人工确认 | | CRITICAL | 🔴 | 阻止，禁止操作 |

📚 文档

• 使用指南
• 开发文档
• API 参考

🔧 开发

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 链接到 OpenClaw
npm link

📝 变更日志

v0.1.0 (2026-03-19)

• ✅ 初始版本
• ✅ 配置验证
• ✅ Skill 审核
• ✅ 循环检测
• ✅ 操作日志
• ✅ Trace 追踪

📄 许可证

MIT

@openclaw/plugin-harness | 蓝山 | 2026-03-19