openclaw-plugin-harness

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

npm: openclaw-plugin-harness — 必须用 OpenClaw CLI 安装到 ~/.openclaw/extensions/，见下文。

🎯 功能

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

🚀 快速开始

安装（正确方式）

OpenClaw 不会从你在任意目录执行的 npm install 里加载插件；它只扫描 ~/.openclaw/extensions/。请用官方 CLI 从 npm 拉取并登记插件：

openclaw plugins install openclaw-plugin-harness
openclaw gateway restart

可选固定版本（建议 ≥ 0.2.18，已修正 plugins.entries.harness.config 的 JSON Schema，与插件实际字段一致）：

openclaw plugins install [email protected]

不要把下面这种当成「安装 OpenClaw 插件」的唯一步骤（这只会把包装进当前目录的 node_modules，Gateway 仍然找不到 harness）：

# ❌ 单独执行这一句通常不够
npm install openclaw-plugin-harness

若你已经在 openclaw.json 里写了 plugins.allow / plugins.entries.harness，但从未执行过 openclaw plugins install …，就会出现 plugin not found: harness 一类提示；按上面 CLI 安装后即可，或删掉多余配置项。

若安装时报 plugins.entries.harness.config: invalid config: must NOT have additional properties：说明当时装的包版本较旧，configSchema 与插件真实配置字段不一致。请升级到 ≥0.2.18 后重装，或先执行 openclaw doctor --fix，并确保 plugins.entries.harness.config 里只有：autoValidateConfig、autoAuditSkill、loopDetectionEnabled、protectedFiles、logsDir（enabled 应写在 plugins.entries.harness 顶层，不要塞进 config）。

手动配置（可选）

如果你想自定义配置，编辑 ~/.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