@lark-apaas/openclaw-scripts-diagnose-cli

OpenClaw 配置诊断与修复 CLI，支持 JSON5 格式。

使用方式

# 检查模式：校验 openclaw 配置
npx -y @lark-apaas/openclaw-scripts-diagnose-cli check --ctx='<base64编码的JSON>'

# 修复模式：修复失败的规则
npx -y @lark-apaas/openclaw-scripts-diagnose-cli repair --ctx='<base64编码的JSON>'

架构

@Rule() 装饰器注册
       ↓
  依赖图拓扑排序
       ↓
  按依赖顺序执行 validate / repair
       ↓
  输出 JSON 结果到 stdout

规则引擎

• DiagnoseRule 抽象基类：每个规则实现 validate() 和可选的 repair()
• @Rule(meta) 装饰器：声明规则元信息（key、dependsOn、repairMode、skipWhen），自动注册到全局注册表
• 依赖图：框架通过 dependsOn 拓扑排序，依赖失败则跳过当前规则

修复模式（RepairMode）

| 模式 | 说明 | 脚本行为 | |------|------|---------| | standard | 可自动修复 | 调用 repair() 方法 | | ai | 需 AI/人工介入 | 仅返回 { rule_name, detail } | | reset | 需外部重置 | 仅返回 { rule_name, detail } |

规则列表

依赖关系图

multi_process_detect              config_file_recover
(无依赖)                              (无依赖)
                                       ↓
                                 config_file_missing
                                       ↓
                                 config_syntax_check
                                  ↙  ↙    ↓    ↘  ↘
                        model_  secret_ feishu  gateway  allowed_
                        provider provider channel         origins
                          ↓        ↓
                       jwt_token secrets_file

规则详情

| 规则 Key | RepairMode | dependsOn | skipWhen | 说明 | |----------|-----------|-----------|----------|------| | multi_process_detect | standard | — | — | 检测多个 openclaw-gateway 进程 | | config_file_recover | standard | — | — | 配置文件缺失但有 .bak 备份，从最高编号备份恢复 | | config_file_missing | reset | config_file_recover | — | 配置文件缺失且无备份 | | config_syntax_check | ai | config_file_recover, config_file_missing | — | JSON5 语法校验 | | model_provider | standard | config_syntax_check | 未使用 miaoda 模型 | 模型 Provider 配置 | | secret_provider | standard | config_syntax_check | 未使用 miaoda 或无 provider 引用 | 密钥 Provider 配置 | | feishu_channel | standard | config_syntax_check | — | 飞书渠道配置 | | gateway | standard | config_syntax_check | — | 网关配置（port、auth、controlUi） | | allowed_origins | standard | config_syntax_check | — | CORS 来源配置 | | jwt_token | standard | config_syntax_check | apiKey 未引用 miaoda-provider | JWT Token 有效期 | | secrets_file | standard | config_syntax_check | 无字段引用 miaoda-secret-provider | 密钥文件内容校验 |

Check 输出格式

{
  "failedRules": {
    "standard": ["gateway", "feishu_channel"],
    "ai": [{ "rule_name": "config_syntax_check", "detail": "JSON5 语法错误..." }],
    "reset": []
  }
}

扩展新规则

1. 在 src/rules/ 下新建文件
2. 实现 @Rule() 装饰的类：

@Rule({
  key: 'my_new_rule',
  dependsOn: ['config_syntax_check'],
  repairMode: 'standard',
})
class MyNewRule extends DiagnoseRule {
  validate(ctx: RuleContext): RuleResult {
    // 检查逻辑
  }
  repair(ctx: RuleContext): void {
    // 修复逻辑（仅 standard 模式需要）
  }
}

3. 在 src/rules/index.ts 加一行 import './my-new-rule.js'

开发

# 构建
npm run build

# 单元测试
npm test

# 集成测试（需要 Docker）
npm run test:integration

调试

三档调试链路（本地 Docker → 热部署 → alpha+TCC）及热部署脚本 scripts/deploy-to-sandbox.sh 用法详见 docs/debugging.md。

BOE 联调环境、TCC 运维、日志检索详见 sandbox_console/docs/openclaw-diagnose-operations.md。