config-field

根据官方 Zod 模式验证 OpenClaw 配置字段。在读取或写入 openclaw.json 时使用来检查配置字段是否存在且有效。涵盖代理、通道、工具、日志记录、会话配置以及 136 多个字段定义。

# Config Field Validator

Validate OpenClaw configuration fields against the official Zod schema.

## When to Use This Skill

- **Before editing configurations** - Verify a field exists before adding it
- **Debugging config errors** - Check if invalid fields are causing issues
- **Migrating configs** - Validate fields after version upgrades
- **Reviewing configs** - Ensure all fields are schema-compliant

## How It Works

This skill automatically manages schema synchronization:

1. **Check Version** - Detects local OpenClaw version
2. **Sync Schema** - Downloads matching schema from GitHub if needed
3. **Generate Fields** - Parses Zod schema to extract field definitions
4. **Validate** - Uses generated schema to validate configuration

## Quick Start

```bash
# Validate a single field (auto-syncs schema if needed)
python3 scripts/validate_field.py agents.defaults.model.primary

# Validate entire config file
python3 scripts/validate_config.py /path/to/openclaw.json

# Force schema re-sync
python3 scripts/sync_schema.py --force

# Check current schema status
python3 scripts/sync_schema.py --status
```

## Field Path Format

Field paths use dot notation:

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

## Workflow

### For Users

Simply use validation commands - schema sync is automatic:

```bash
# This will auto-sync schema if version mismatch detected
python3 scripts/validate_field.py agents.defaults.timeoutSeconds
```

### For Schema Management

```bash
# Check schema status
python3 scripts/sync_schema.py --status
# Output: Schema version: 2.1.0 (matches OpenClaw)

# Force re-sync (if needed)
python3 scripts/sync_schema.py --force

# Generate fresh field reference
python3 scripts/generate_fields.py
```

## Schema Storage

Schema is cached locally at:
```
~/.config/openclaw/skills/config-field/
├── schema/              # Downloaded TypeScript schema files
├── cache/               # Parsed schema cache
└── schema-fields.md     # Generated field reference
```

## Reference

### Complete Field Reference
**[references/schema-fields.md](references/schema-fields.md)** - Auto-generated from official Zod schema

## Scripts

| Script | Purpose |
|--------|---------|
| `validate_field.py <path>` | Validate single field |
| `validate_config.py <file>` | Validate entire config |
| `field_info.py <path>` | Get field details |
| `sync_schema.py` | Manage schema sync |
| `generate_fields.py` | Regenerate field docs |

## Common Fields

### Agent Configuration
- `agents.defaults.model.primary` - Default model ID
- `agents.defaults.workspace` - Workspace path
- `agents.defaults.timeoutSeconds` - Request timeout
- `agents.defaults.sandbox.mode` - Sandbox mode

### Channel Configuration
- `channels.telegram.botToken` - Telegram bot token
- `channels.discord.token` - Discord bot token
- `channels.slack.botToken` - Slack bot token

### Tools
- `tools.web.search.enabled` - Enable web search
- `tools.web.search.provider` - Search provider
- `tools.exec.security` - Execution security mode

## Troubleshooting

### Schema Out of Date

If you see warnings about unknown fields that should exist:

```bash
# Force schema refresh
python3 scripts/sync_schema.py --force
```

### Validation Errors

```bash
# Check field info for correct usage
python3 scripts/field_info.py agents.defaults.model

# Verify config syntax
python3 scripts/validate_config.py ~/.config/openclaw/openclaw.json
```

---

## 中文说明

# 配置字段验证器

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

## 何时使用此技能

- **编辑配置之前** - 在添加字段之前验证其是否存在
- **调试配置错误** - 检查无效字段是否导致问题
- **迁移配置** - 在版本升级后验证字段
- **审查配置** - 确保所有字段都符合模式

## 工作原理

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

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

## 快速开始

```bash
# Validate a single field (auto-syncs schema if needed)
python3 scripts/validate_field.py agents.defaults.model.primary

# Validate entire config file
python3 scripts/validate_config.py /path/to/openclaw.json

# Force schema re-sync
python3 scripts/sync_schema.py --force

# Check current schema status
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
```

## 工作流程

### 面向用户

只需使用验证命令——模式同步是自动的：

```bash
# This will auto-sync schema if version mismatch detected
python3 scripts/validate_field.py agents.defaults.timeoutSeconds
```

### 面向模式管理

```bash
# Check schema status
python3 scripts/sync_schema.py --status
# Output: Schema version: 2.1.0 (matches OpenClaw)

# Force re-sync (if needed)
python3 scripts/sync_schema.py --force

# Generate fresh field reference
python3 scripts/generate_fields.py
```

## 模式存储

模式在本地缓存于：
```
~/.config/openclaw/skills/config-field/
├── schema/              # Downloaded TypeScript schema files
├── cache/               # Parsed schema cache
└── schema-fields.md     # Generated field reference
```

## 参考

### 完整字段参考
**[references/schema-fields.md](references/schema-fields.md)** - 由官方 Zod 模式自动生成

## 脚本

| 脚本 | 用途 |
|--------|---------|
| `validate_field.py <path>` | 验证单个字段 |
| `validate_config.py <file>` | 验证整个配置 |
| `field_info.py <path>` | 获取字段详情 |
| `sync_schema.py` | 管理模式同步 |
| `generate_fields.py` | 重新生成字段文档 |

## 常用字段

### 代理配置
- `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` - 执行安全模式

## 故障排除

### 模式过期

如果你看到有关本应存在的未知字段的警告：

```bash
# Force schema refresh
python3 scripts/sync_schema.py --force
```

### 验证错误

```bash
# Check field info for correct usage
python3 scripts/field_info.py agents.defaults.model

# Verify config syntax
python3 scripts/validate_config.py ~/.config/openclaw/openclaw.json
```