OpenClaw Config Safety v2#

Safe config management for openclaw.json — validate, normalize, export as tokens, import from tokens.

Tools#

openclaw-config-onboard — Config wizard#

Interactive or non-interactive config management.

bash

openclaw-config-onboard              # Interactive wizard
openclaw-config-onboard --audit     # Print config summary
openclaw-config-onboard --validate  # Run validation checks
openclaw-config-onboard --export    # Export token to stdout
openclaw-config-onboard --normalize # Normalize config in place
openclaw-config-onboard --import <token>  # Import a config token
openclaw-config-onboard --help      # Show usage

Exit codes: 0 = success, 1 = failure, 2 = invalid arguments.

validate-openclaw-config.sh — Pre-write validator#

Run before any direct edit to openclaw.json:

bash

OPENCLAW_BIN=~/.nvm/versions/node/v24.14.0/bin/openclaw \
  ~/.openclaw/workspace/skills/openclaw-config-safety/scripts/validate-openclaw-config.sh \
  --file /path/to/candidate.json

When to Use#

• Any edit to ~/.openclaw/openclaw.json
• Changing model config, adding/removing models or providers
• Modifying gateway, agent, or plugin settings
• Planning OpenClaw version upgrades
• Running openclaw doctor --fix
• Exporting config to share as a mrconf:v1:... token
• Importing a config token from another machine

Pre-Write Protocol#

1. Backup current config (automatic with wizard, manual otherwise): bash

   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d-%H%M%S)
   
   

2. Write candidate to temp file (never edit live config directly)

3. Validate before writing: bash

   openclaw-config-onboard --validate
   
   

   Or use the wizard for interactive flow: openclaw-config-onboard

Token Format#

Exported configs are mrconf:v1:... tokens — base64url-encoded JSON. Credential values are NEVER included; only ${REFERENCE} placeholders are embedded. Tokens are safe to share.

Token structure:

text

mrconf:v1:<base64url>{
  "version": 1,
  "exportedAt": "ISO-8601",
  "normalizerVersion": "1.0.0",
  "config": { ... },
  "credentialRefs": ["VAR_NAME", ...]
}

Import Protocol#

When importing a token:

1. Wizard creates automatic backup
2. Merges token config into existing config (deep merge, preserving keys not in token)
3. Validates merged result
4. On gateway restart failure: automatically restores backup

Normalization#

The normalize step fixes:

• String whitespace/alias normalization (e.g. " m2.7 " → "minimax/MiniMax-M2.7")
• Type coercion ( "true" → true, "60" → 60)
• Empty array/object cleanup
• Deprecated field detection

Known-Green Fields#

LocationFieldsagents.defaults.models[<key>]``alias (string), params (record), streaming (boolean)models.providers[<provider>].models[]``id, name, api, reasoning, input, cost, contextWindow, maxTokens, headers, compat``agents.defaults top-levelmodel, models, timeoutSeconds, compaction, memorySearch, bootstrapMaxChars, workspace

Known-Red Fields#

FieldLocationReasonstatusPer-model override.strict() Zod modifier — instant crashnotePer-model overrideNot in schema — crashUnknown fieldsAny .strict() Zod objectRejected at load time

Backup & Restore#

bash

# List backups
ls -lt ~/.openclaw/openclaw.json.bak-*

# Restore
cp ~/.openclaw/openclaw.json.bak-<timestamp> ~/.openclaw/openclaw.json
openclaw gateway restart

The wizard creates timestamped backups automatically: ~/.openclaw/openclaw.json.bak-YYYYMMDD-HHMMSS

Architecture#

text

src/
  alias-map.js       — model alias → canonical name
  audit.js           — config summary generator
  base64url.js      — base64url encode/decode
  config-patch.js   — safe deep merge for import
  doctor-check.js   — openclaw doctor wrapper
  errors.js         — NormalizationError
  export.js         — config → token
  import.js         — token → config
  normalize.js      — field normalization
  prompt.js         — TTY readline helpers
  resolve-refs.js   — env/pass credential resolution
  restore-backup.js — timestamped backup + restore
  token-errors.js   — token error classes

bin/
  openclaw-config-onboard  — main wizard CLI

References#

• NORMALIZATION-SPEC.md — field normalization spec
• EXPORT-TOKEN-SPEC.md — token format spec
• ONBOARDING-SPEC.md — wizard behavior spec
• CONFIG-EDIT.md — pre-write protocol (same directory)