Openclaw Config Validator

OpenClaw Config Validator Skill

ID: openclaw-config-validator
Version: 1.0.0
OpenClaw Version: 2026.2.1+

A comprehensive configuration validation and management skill for OpenClaw, providing authoritative schema documentation, validation tools, and best practices.

Overview

This skill helps OpenClaw agents and users:

• Understand the complete OpenClaw configuration schema
• Validate configurations against the official JSON Schema
• Follow safe configuration management practices
• Prevent common configuration errors

Features

📚 Complete Schema Reference

• 22 top-level configuration nodes documented
• Official JSON Schema from OpenClaw 2026.2.1
• Risk levels marked for each node (🟢 Low 🟡 Medium 🔴 High)
• Field types, defaults, and examples

✅ Validation Tools

• get-schema.sh - Extract runtime schema from live configuration
• schema-validate.sh - Validate configuration against schema
• Pre-commit checklist to prevent errors

🛡️ Safety Features

• Forbidden fields list - Know what not to add
• Pre-modification checklist - 7-step safety process
• Rollback procedures - Recovery when things go wrong
• Error troubleshooting - Common issues and solutions

Quick Start

1. Validate Current Configuration

./scripts/schema-validate.sh

2. Extract Runtime Schema

./scripts/get-schema.sh

3. Read Schema Reference

cat reference/SCHEMA.md

File Structure

openclaw-config-validator/
├── SKILL.md                          # This file
├── reference/
│   ├── SCHEMA.md                     # Authoritative schema reference (v2)
│   ├── openclaw-official-schema.json # Official JSON Schema from OpenClaw
│   └── AGENT_PROMPT.md              # Configuration management guide
└── scripts/
    ├── get-schema.sh                # Runtime schema extractor
    └── schema-validate.sh           # Configuration validator

Configuration Safety Rules

✅ DO

• Read SCHEMA.md before making changes
• Backup config: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%s)
• Use jq for modifications, never direct edit
• Run openclaw doctor before and after changes
• Test in non-production first

❌ DON'T

• Create new top-level nodes not in SCHEMA.md
• Add web.braveApiKey or similar non-existent fields
• Modify gateway node (read-only)
• Skip the backup step
• Guess field names or formats

Schema Highlights

New in OpenClaw 2026.2.1

Risk Levels

Validation

Using schema-validate.sh

# Basic validation
./scripts/schema-validate.sh

# Detailed report
./scripts/schema-validate.sh --verbose

# Generate report file
./scripts/schema-validate.sh --report

Using Ajv (optional)

# Install ajv-cli
npm install -g ajv-cli

# Validate with official schema
ajv validate -s reference/openclaw-official-schema.json \
  -d ~/.openclaw/openclaw.json

Troubleshooting

Configuration Validation Failed

# 1. Check specific errors
openclaw doctor

# 2. Restore from backup
cp ~/.openclaw/openclaw.json.backup.* ~/.openclaw/openclaw.json

# 3. Restart gateway (if needed)
openclaw gateway restart

Gateway Won't Start

# Check config syntax
jq '.' ~/.openclaw/openclaw.json

# If invalid, restore default
mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken
# Then re-run: openclaw onboard

References

• Official Docs: https://docs.openclaw.ai/gateway/configuration
• OpenClaw Repo: https://github.com/openclaw/openclaw
• OpenClaw Discord: https://discord.gg/clawd

Changelog

v1.0.0 (2026-02-04)

• Initial release
• Complete OpenClaw 2026.2.1 schema documentation
• Official JSON Schema integration
• Validation scripts
• Safety guidelines and checklists

License

MIT - See OpenClaw project for details.

"Schema is the boundary, not the permission. Know where the boundary is."

Created by Galatea 🜁