openclaw-config-doctor

name	openclaw-config-doctor
description	Safely diagnose, back up, validate, and repair OpenClaw configuration issues for openclaw.json and related runtime config state. Use when config edits break startup, OpenClaw reports JSON5/schema validation errors, channels repeatedly fail after config changes, doctor reports configuration drift, or before/after risky config migrations in local or Docker-based deployments.

OpenClaw Config Doctor

Overview

Stabilize OpenClaw config with a backup-first workflow. Prefer deterministic CLI operations (config, doctor, channels status, health) over manual edits.

Quick Start

1. Detect active config path:

   openclaw config file
   

2. Back up config:

   ./scripts/config_backup.sh
   

3. Validate schema:

   ./scripts/config_validate.sh
   

4. If validation fails, repair and re-validate:

   ./scripts/config_repair.sh
   

Workflow

Step 1: Confirm scope and symptoms

• Collect the failing command and exact error text first.
• Identify whether failure is parse-level (JSON5 syntax), schema-level (invalid key/value), or runtime/channel-level.
• Record deployment mode: local host CLI vs Docker volume-backed gateway.

Step 2: Resolve config location and target

• Resolve active file with openclaw config file whenever possible.
• If running in Docker, mount the same data volume used by gateway and set OPENCLAW_CONFIG_PATH explicitly when validating/repairing.
• Never assume path consistency between host and container.

Step 3: Create a backup before any mutation

• Run scripts/config_backup.sh to create timestamped backup.
• Keep backups under a restricted directory (700) with backup files (600).
• Do not continue if backup fails.

Step 4: Validate before repair

• Run scripts/config_validate.sh.
• If validation succeeds, continue to post-checks and stop.
• If validation fails, capture the output as the repair target.

Step 5: Repair with doctor, then validate again

• Run scripts/config_repair.sh.
• Re-run scripts/config_validate.sh.
• If still failing, restore previous backup and escalate with exact failing key/path.

Step 6: Post-check runtime behavior

• Verify:
  • openclaw health
  • openclaw channels status --probe
  • openclaw doctor --deep when incident severity is high
• Confirm previously failing channel/workflow recovers.

Guardrails

• Do not print raw secrets (tokens, API keys, refresh tokens) in output.
• Prefer openclaw config set/unset over manual file editing for single-key changes.
• Treat config edits as transactional:
  1. backup
  2. mutate
  3. validate
  4. runtime check
• If config is invalid after attempted fix, roll back first, then retry in smaller changes.

Common Triggers and Responses

• JSON5 parse failed:
  • run backup
  • validate to confirm line/column
  • repair with doctor
  • re-validate
• Repeated Discord failures after config edits:
  • validate config
  • inspect channel capability/intents and bot settings
  • run channel probe checks
• Gateway starts but behavior is inconsistent:
  • run doctor and health checks
  • compare with last known-good backup

Resources

• scripts/config_backup.sh: Backup and checksum active config.
• scripts/config_validate.sh: Validate current config with selected path.
• scripts/config_repair.sh: Backup -> doctor repair -> re-validate.
• references/doctor-playbook.md: Detailed runbook for local and Docker modes.

Example Requests

• "OpenClaw không lên sau khi sửa config, giúp mình khôi phục an toàn."
• "Doctor báo config invalid, sửa giúp nhưng phải backup trước."
• "Discord channel cứ fail sau khi đổi cấu hình, chẩn đoán theo chuẩn."

For deeper procedures, load references/doctor-playbook.md.