ClawHub

Agent Config Validator

Other

OpenClaw Agent配置验证器 - 自动检查openclaw.json与agent核心文档的一致性，检测过时引用，生成诊断报告并支持自动修复。当新增/调整agent或修改核心文档后使用此技能确保配置完整性。

Install

openclaw skills install agent-config-validator

Agent Config Validator Skill

OpenClaw Agent 配置验证器 - 确保多智能体系统配置的一致性和完整性。

功能概述

此技能用于验证 OpenClaw 多智能体系统的配置完整性，包括：

  1. 配置一致性检查 - 验证 openclaw.json 与实际 agent 目录结构是否匹配
  2. 过时引用检测 - 检测核心文档中引用的已删除 agent、旧模型配置等
  3. 文档完整性验证 - 检查必需的核心文档是否存在
  4. 自动修复 - 支持自动修复常见问题（仅限安全配置项）
  5. 诊断报告 - 生成详细的验证报告

安全设计原则

❌ 严禁自动修改的内容

以下核心数据严禁自动修改，仅做检测和报告：

类型文件路径原因
Agent 角色定义agents/{agent}/agent/{agent}.md包含角色人格定义
身份文档agents/main/agent/IDENTITY.md定义 Star 助手身份
灵魂/价值观agents/main/agent/SOUL.md核心价值观和行为准则
记忆文档agents/main/agent/MEMORY.md用户偏好和历史记忆
用户偏好agents/main/agent/USER.md用户个性化设置

⚠️ 需要人工确认的配置

以下配置变更需要人工确认：

配置项说明
agents.list新增/删除 agent
model.primary主模型变更
model.fallbacks备用模型变更
channels渠道配置
auth认证配置

✅ 可以安全自动修复的内容

类型示例安全级别
清理无效引用从 allowAgents 移除已删除 agent✅ 安全
移除无效绑定清理指向不存在 agent 的 binding✅ 安全
格式修复JSON 语法错误、多余逗号✅ 安全
备份创建修改前自动备份✅ 安全

使用场景

  • 新增 agent 后验证配置
  • 删除/合并 agent 后清理引用
  • 修改 agent 核心文档后检查一致性
  • 定期维护检查

工作流程

1. 执行完整验证（默认只读模式）

// 默认：只检查，不修复（推荐）
validate_agent_config()

// 或显式指定
validate_agent_config({ 
    fix: false,        // 是否自动修复
    dryRun: true,      // 试运行模式（显示会做什么但不执行）
    verbose: true      // 显示详细信息
})

2. 安全修复模式

// 仅修复安全项（清理无效引用）
validate_agent_config({ 
    fix: true,                    // 启用修复
    safeMode: true,               // 仅修复白名单内的配置
    confirmSensitive: false       // 不询问敏感变更
})

3. 完整修复模式（需要交互确认）

// 修复所有可修复项（会询问敏感变更）
validate_agent_config({ 
    fix: true,
    safeMode: false,              // 允许修复非白名单项
    confirmSensitive: true        // 敏感变更需要确认
})

4. 检查特定 Agent

validate_specific_agent({
    agentId: "luffy",
    checkDocs: ["AGENTS.md", "IDENTITY.md"]
})

5. 生成修复建议

generate_fix_suggestions({
    outputPath: "D:\\OpenClaw\\工作汇报\\agent-config-report.md"
})

检查项目

A. openclaw.json 配置检查

  • agents.list 中的每个 agent 都有对应的目录
  • agent 目录中的每个 agent 都在配置中注册
  • subagents.allowAgents 只包含存在的 agent
  • agentToAgent.allow 只包含存在的 agent
  • bindings 中的 agentId 都有效

B. 核心文档过时检查

检查以下文档中的过时引用：

  • AGENTS.md

    • 可用子Agent列表与实际一致
    • 模型配置表与实际一致
    • 团队架构图与实际一致
    • 文档保存目录与实际一致

  • IDENTITY.md

    • 团队架构描述与实际一致
    • 调度规则表与实际一致
    • 核心职责描述与实际一致

  • SOUL.md

    • 团队引用与实际一致

  • Agent 自身文档 (如 luffy.md, nami.md)

    • 协作对象引用是否有效
    • 能力描述是否准确

C. 目录结构检查

  • 每个 agent 都有 agent/ 目录
  • 每个 agent 都有 workspace/ 目录
  • 必需的核心文档存在

安全修复白名单

以下配置项可以安全自动修复：

SAFE_TO_AUTO_FIX = [
    'subagents.allowAgents',      // 清理无效 agent 引用
    'agentToAgent.allow',         // 清理无效通信权限
    'bindings'                    // 清理无效绑定
]

以下配置项需要人工确认：

REQUIRE_MANUAL_CONFIRM = [
    'agents.list',                // 增删 agent
    'models.primary',             // 主模型变更
    'models.fallbacks',           // 备用模型变更
    'channels',                   // 渠道配置
    'auth'                        // 认证配置
]

自动修复功能

1. 安全自动修复（无需确认）

  • 从 subagents.allowAgents 中移除无效 agent
  • 从 agentToAgent.allow 中移除无效 agent
  • 从 bindings 中移除无效绑定

2. 敏感变更（需要确认）

  • 修改 agents.list
  • 变更模型配置
  • 修改渠道配置
  • 修改认证信息

3. 文档更新（永不自动修复）

  • 核心文档内容更新
  • Agent 角色定义修改
  • 团队架构描述更新

诊断报告格式

# Agent Config Validation Report
生成时间: 2026-03-19 12:00:00

## 摘要
- 总 Agent 数: 3
- 配置有效: ✅
- 发现问题: 5
- 可安全修复: 2
- 需人工确认: 2
- 需人工处理: 1

## 安全状态
✅ 白名单修复: 启用
⚠️ 敏感变更确认: 需要
❌ 文档自动修复: 禁用

## 详细结果

### 1. openclaw.json 配置检查
✅ 所有配置的 agent 目录都存在
✅ subagents.allowAgents 有效
⚠️ agentToAgent.allow 包含无效引用: ["zoro", "sanji"]
   [可安全自动修复] 运行 --fix 清理

### 2. AGENTS.md 检查
⚠️ 发现过时引用:
  - 第42行: 引用已删除 agent "zoro"
  - 第58行: 模型配置表过时
   [需人工处理] 文档内容不会自动修改

### 3. IDENTITY.md 检查
✅ 团队架构描述正确
⚠️ 第31行: 仍引用已删除的 "索隆、山治"
   [需人工处理] 文档内容不会自动修改

## 修复建议
### 可安全自动修复
1. 从 agentToAgent.allow 移除 ["zoro", "sanji"]
   命令: validate_agent_config({fix: true, safeMode: true})

### 需人工处理
2. 更新 AGENTS.md 第42-45行
3. 更新 IDENTITY.md 第31行

## 执行修复
安全修复: validate_agent_config({fix: true, safeMode: true})
完整修复: validate_agent_config({fix: true, safeMode: false, confirmSensitive: true})

最佳实践

何时运行验证

  1. 新增 Agent 后

    • 验证新 agent 配置正确
    • 确保其他文档更新引用

  2. 删除/合并 Agent 后

    • 检查并清理所有引用
    • 验证无残留配置

  3. 修改核心文档后

    • 确保文档间一致性
    • 验证与配置匹配

  4. 定期维护

    • 建议每周运行一次
    • 及时发现配置漂移

修复策略

  1. 先查看报告

    // 第一步：只检查，不修复
validate_agent_config({ fix: false, verbose: true })

  2. 安全修复

    // 第二步：修复安全项
validate_agent_config({ fix: true, safeMode: true })

  3. 人工处理文档

    • 根据报告手动更新文档
    • 审核敏感配置变更

  4. 验证修复结果

    // 第四步：再次验证
validate_agent_config({ fix: false })

注意事项

1. 备份机制

  • 自动修复前始终创建备份
  • 备份文件: openclaw.json.backup.{timestamp}
  • 可随时手动恢复

2. 权限要求

  • 需要读写 openclaw.json
  • 需要访问所有 agent 目录
  • 建议以相同用户运行

3. 安全警告

⚠️ 永远不要：

  • 自动修改 Agent 核心文档
  • 未经确认修改敏感配置
  • 在生产环境直接修复

✅ 始终：

  • 先运行检查模式查看问题
  • 确认备份已创建
  • 验证修复后的配置

命令行使用

# 默认：只检查
agent-config-validator

# 详细输出
agent-config-validator --verbose

# 试运行（显示会做什么）
agent-config-validator --dry-run

# 安全修复（仅白名单项）
agent-config-validator --fix --safe-mode

# 完整修复（会询问敏感变更）
agent-config-validator --fix

# 生成报告文件
agent-config-validator --output report.md

API 使用

const AgentConfigValidator = require('agent-config-validator');

const validator = new AgentConfigValidator();

// 基本验证
const result = validator.validate({
    fix: false,
    verbose: true
});

// 获取详细结果
const report = validator.generateReport('report.md');

// 查看发现的问题
console.log(validator.issues);

// 查看已应用的修复
console.log(validator.fixes);

错误处理

配置文件不存在

❌ 错误: 配置文件不存在: D:\OpenClaw\.openclaw\openclaw.json
解决: 确保在正确的目录运行，或设置 OPENCLAW_ROOT 环境变量

JSON 语法错误

❌ 错误: 无法加载 openclaw.json: Unexpected token...
解决: 手动修复 JSON 语法错误，或使用 JSON 验证器检查

权限不足

❌ 错误: 保存配置失败: EACCES: permission denied
解决: 确保有写入权限，或以管理员身份运行