close
OpenClaw Internals
  • 中文

      • 配置验证错误

      概述

      本指南涵盖 OpenClaw 中的配置验证错误,基于 src/config/validation.ts。配置验证在启动时进行,如果检测到关键问题,将阻止 OpenClaw 运行。理解验证错误对于调试启动失败至关重要。

      症状

      启动失败

      • OpenClaw 启动后立即退出
      • 无服务器初始化
      • 任何其他输出之前出现错误消息

      Zod 模式验证错误

      • 带有 JSON 路径的详细验证错误
      • 类型不匹配错误(例如"expected string, got number")
      • 缺少必填字段错误

      插件配置错误

      • 特定插件的消息: "invalid config"
      • 插件配置与声明的模式不匹配
      • 消息: "plugin schema missing"

      重复代理目录

      • 消息: "Duplicate agent directory detected"
      • 多个代理配置了相同的目录路径
      • 验证失败列出所有重复项

      旧版配置警告

      • 有关已弃用配置格式的警告
      • 建议迁移到新格式
      • 可能阻止或不阻止启动

      根本原因

      1. 模式验证失败(第 98-107 行)

      顶级 OpenClaw 配置与模式不匹配:

      const result = OpenClawSchema.safeParse(config);
if (!result.success) {
  throw new Error(`Config validation failed: ${formatZodError(result.error)}`);
}

      常见问题:

      • 字段数据类型错误(字符串 vs 数字)
      • 缺少必填字段
      • 模式中不存在的未知字段
      • 无效的枚举值

      检测: 启动时 Zod 模式验证 恢复: 必须修复配置文件,无自动恢复

      2. 插件配置模式不匹配(第 403-422 行)

      插件配置与插件声明的 configSchema 不匹配:

      const pluginSchema = plugin.configSchema;
if (pluginSchema) {
  const validation = pluginSchema.safeParse(pluginConfig);
  if (!validation.success) {
    errors.push({
      plugin: pluginName,
      error: formatZodError(validation.error)
    });
  }
}

      常见原因:

      • 插件更新了新的配置要求
      • 插件配置字段名拼写错误
      • 缺少必需的插件特定字段
      • openclaw.plugin.json 中未定义插件 configSchema

      检测: 每个插件的模式验证 恢复: 修复 openclaw.json 中的插件配置部分

      3. 重复代理目录(第 108-118 行)

      多个代理配置了相同的目录:

      function findDuplicateAgentDirs(agents: AgentConfig[]): string[] {
  const dirs = agents.map(a => a.directory);
  const seen = new Set<string>();
  const duplicates = new Set<string>();

  for (const dir of dirs) {
    if (seen.has(dir)) {
      duplicates.add(dir);
    }
    seen.add(dir);
  }

  return Array.from(duplicates);
}

      常见原因:

      • 代理配置中的复制粘贴错误
      • 同一代理列出多次
      • 符号链接创建重复路径

      检测: 目录路径比较 恢复: 从 agents.list 中删除重复条目

      4. 插件诊断错误(第 222-229 行)

      验证期间插件报告的诊断错误:

      插件诊断可以报告:

      • 缺少依赖项
      • 无效的文件路径
      • 不兼容的版本
      • 资源不可用

      严重程度级别:

      • Error: 阻止启动
      • Warning: 记录但不阻止
      • Info: 仅供参考

      恢复: 取决于具体诊断,参见插件文档

      5. 旧版配置格式(第 88-96 行)

      检测到旧配置格式:

      function detectLegacyConfig(config: unknown): boolean {
  // 检查已弃用的字段名或结构
  return hasLegacyFields(config);
}

      常见模式:

      • 旧字段名(例如 llmProvider vs llm.provider)
      • 已弃用的嵌套结构
      • 已删除的配置选项

      恢复: 迁移到新配置格式,警告包含迁移提示

      诊断流程