agent-config-validator

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

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "agent-config-validator" with this command: npx skills add starai-2026/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
解决: 确保有写入权限，或以管理员身份运行

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Automation

Lobster Config Guide

Provides a step-by-step guide to configure Lobster AI Agent behavior via AGENTS.md, group rules, and skill plugins for optimal interaction.

Registry SourceRecently Updated
740Profile unavailable
Automation

OpenClaw Agent Clone

一键导出或导入小龙虾配置，支持配置共享与克隆，自动备份并过滤敏感信息，方便技能安装与应用恢复。

Registry SourceRecently Updated
2830Profile unavailable
Automation

Agent Memory Persistent Workspace Memory System

Stop your AI agent from forgetting everything between sessions. Three-tier memory architecture (long-term owner namespace / daily logs / session handoff), cr...

Registry SourceRecently Updated
3060Profile unavailable
Automation

OpenClaw 集中配置管理系统

为 OpenClaw 构建集中化配置管理系统，告别硬编码和配置分散，实现"改一处，生效全局"的现代化运维体验。包含配置加载器、主配置融合、记忆同步、AGENTS.md 模板、memoryFlush、memorySearch、多 Agent 配置、ClawRouter 成本优化等核心功能。

Registry SourceRecently Updated
3581Profile unavailable