openclaw-config-safety

Validate your openclaw.json before writing it.

A pre-flight validator that catches known-dangerous field patterns and schema violations before they crash your gateway. Uses OpenClaw's own doctor command as the definitive check, plus targeted field-level guards for patterns known to cause crashes.

Why

Editing openclaw.json blindly is a fast path to a broken gateway. A single misplaced status or note field in a per-model override will crash on restart. This tool validates before you write, so you find out at 20:00 instead of at 02:00 when you're already half-asleep.

Features

• Check 1–2: Validates providers and agents top-level key structure
• Check 3: Validates per-model override fields (alias, params, streaming only)
• Check 4: Validates agents.defaults top-level fields
• Check 5: Catches forbidden fields (status, note) in per-model overrides — the fields that actually crash the gateway
• Check 6: Runs openclaw doctor --fix as the definitive schema validator

Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/ether-btc/openclaw-config-safety/main/validate-openclaw-config.sh | bash

Or clone the repo

git clone https://github.com/ether-btc/openclaw-config-safety.git
cd openclaw-config-safety
chmod +x validate-openclaw-config.sh

AgentSkill (OpenClaw)

For automatic validation when editing config in an OpenClaw agent context, install as a skill:

# Copy the skill to your workspace's skills directory
cp -r openclaw-config-safety ~/.openclaw/workspace/skills/

# The skill will automatically trigger when:
# - Editing openclaw.json
# - Planning config changes
# - Running openclaw doctor
# - Preparing for OpenClaw updates

Skill structure:

~/.openclaw/workspace/skills/openclaw-config-safety/
├── SKILL.md                         # Usage instructions
├── scripts/
│   └── validate-openclaw-config.sh  # 6-check validator
└── references/
    └── CONFIG-EDIT.md                # Full protocol

The skill includes pre-edit checklists, known-safe/red fields, and post-write recovery steps.

Usage

# Validate a candidate file before writing
./validate-openclaw-config.sh --file /path/to/candidate.json

# Validate a JSON diff/patch string
./validate-openclaw-config.sh --diff '{"agents":{"defaults":{"models":{"nvidia/qwen/qwq-32b":{"status":"experimental"}}}}}'  # → FAILS, catches crash field

# Read from stdin
cat /tmp/candidate.json | ./validate-openclaw-config.sh --stdin

# Strict mode: warnings also cause exit 1
./validate-openclaw-config.sh --file candidate.json --strict

Exit codes

Code	Meaning
0	Valid (or only non-critical warnings)
1	Invalid — critical errors found
2	Cannot validate — file not found or openclaw CLI unavailable

Workflow: Safe config edit

1. cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
2. $EDITOR ~/.openclaw/openclaw.json
3. validate-openclaw-config.sh --file ~/.openclaw/openclaw.json
   → GREEN  → restart gateway
   → RED    → cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

Schema

Field registry is extracted from OpenClaw's Zod schema (version in schema/field-registry.json):

{
  "per_model_override": ["alias", "params", "streaming"],
  "agents_defaults_top_level": ["params","model","imageModel","... (see schema/)"],
  "top_level_keys": ["meta","wizard","auth","models","agents","... (see schema/)"]
}

Full schema: schema/field-registry.json

Known crash patterns

These fields in agents.defaults.models[<key>] will crash the gateway:

{
  "agents": {
    "defaults": {
      "models": {
        "nvidia/qwen/qwq-32b": {
          "status": "experimental"   // ← CRASH
          "note": "some note"        // ← CRASH
        }
      }
    }
  }
}

The Zod schema modifier .strict() rejects unknown keys — these fields simply aren't in the schema. openclaw doctor will tell you the same thing, but this validator catches it before a restart.

Running tests

cd tests && bash test-all.sh

License

MIT — use freely, contribute gladly.

---

Built for the OpenClaw community.

---

If this saved you time or made your day a little better, consider sharing a coffee — and keep the ideas flowing. konto.fkey.id