配置字段验证器

根据官方 Zod 模式验证 OpenClaw 配置字段。

何时使用此技能

• 编辑配置前 - 在添加字段前确认其是否存在
• 排查配置错误 - 检查无效字段是否导致问题
• 迁移配置时 - 版本升级后验证字段
• 审查配置 - 确保所有字段符合模式要求

工作原理

该技能自动管理模式同步：

1. 检查版本 - 检测本地 OpenClaw 版本
2. 同步模式 - 如需，从 GitHub 下载匹配的模式
3. 生成字段 - 解析 Zod 模式以提取字段定义
4. 验证 - 使用生成的模式验证配置

快速开始

# 验证单个字段（如需会自动同步模式）
python3 scripts/validate_field.py agents.defaults.model.primary

# 验证整个配置文件
python3 scripts/validate_config.py /path/to/openclaw.json

# 强制重新同步模式
python3 scripts/sync_schema.py --force

# 检查当前模式状态
python3 scripts/sync_schema.py --status

字段路径格式

字段路径使用点号表示法：

agents.defaults.model.primary              → agents.defaults.model.primary
channels.telegram.botToken                 → channels.telegram.botToken
tools.web.search.provider                  → tools.web.search.provider

使用流程

对用户而言

直接使用验证命令——模式同步为自动处理：

# 若检测到版本不匹配，将自动同步模式
python3 scripts/validate_field.py agents.defaults.timeoutSeconds

对模式管理而言

# 检查模式状态
python3 scripts/sync_schema.py --status
# 输出：Schema version: 2.1.0 (matches OpenClaw)

# 强制重新同步（如有需要）
python3 scripts/sync_schema.py --force

# 生成新的字段参考文档
python3 scripts/generate_fields.py

模式存储位置

模式本地缓存于：

~/.config/openclaw/skills/config-field/
├── schema/              # 下载的 TypeScript 模式文件
├── cache/               # 解析后的模式缓存
└── schema-fields.md     # 生成的字段参考文档

参考资料

完整字段参考

[references/schema-fields.md](references/schema-fields.md) - 由官方 Zod 模式自动生成

脚本说明

常用字段

代理配置

• agents.defaults.model.primary - 默认模型 ID
• agents.defaults.workspace - 工作空间路径
• agents.defaults.timeoutSeconds - 请求超时时间
• agents.defaults.sandbox.mode - 沙箱运行模式

通道配置

• channels.telegram.botToken - Telegram 机器人令牌
• channels.discord.token - Discord 机器人令牌
• channels.slack.botToken - Slack 机器人令牌

工具配置

• tools.web.search.enabled - 启用网页搜索
• tools.web.search.provider - 搜索服务提供商
• tools.exec.security - 执行安全模式

故障排除

模式过期

若出现关于应存在但未知字段的警告：

# 强制刷新模式
python3 scripts/sync_schema.py --force

验证错误

# 查看字段详情以正确使用
python3 scripts/field_info.py agents.defaults.model

# 验证配置语法
python3 scripts/validate_config.py ~/.config/openclaw/openclaw.json