home / skills / openclaw / skills / config-guardian

config-guardian skill

safe

This skill validates and safeguards OpenClaw config updates by backing up, checking schema, and enabling safe rollback before restarts.

npx playbooks add skill openclaw/skills --skill config-guardian

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

1.5 KB

---
name: config-guardian
description: Safe OpenClaw config updates with automatic backup, validation, and rollback. For agent use - prevents invalid config updates.
---

# Config Guardian

## Overview
**For Agent use only.** Safe config updates with automatic backup, validation, and rollback. Prevents the agent from updating non-existent keys or invalid values.

## When to Use
Use this skill **every time** you need to update `openclaw.json`. Prevents:
- Updating non-existent config keys
- Using invalid values
- Breaking the gateway with bad config

## Workflow: Atomic Apply (Default)

For all config changes - handles everything in one command:

```bash
./scripts/atomic_apply.sh <config_path> <new_value>
# Example: ./scripts/atomic_apply.sh "agents.defaults.model.primary" "minimax-portal/MiniMax-M2.5"
```

**What it does:**
1. Creates timestamped backup automatically
2. Applies change via `openclaw config set <path> <value>`
3. Validates with `openclaw doctor --non-interactive`
4. **Auto-rollback** if validation fails
5. Trap ensures rollback even on crash

**Backup location:**
```
~/.openclaw/config-guardian-backups/
```

## Guardrails
- **Never** restart or apply config without explicit user approval
- **Always** use `atomic_apply.sh`
- If validation fails -> config auto-rolled back, don't force it

## Scripts
| Script | Purpose |
|--------|---------|
| `atomic_apply.sh` | Default - all-in-one safe apply |
| `validate_config.sh` | Validate via OpenClaw doctor |
| `restore_config.sh` | Manual restore from backup |

Overview

This skill validates and safeguards OpenClaw configuration updates (openclaw.json or openclaw config set/apply). It enforces backups, schema validation, and safe rollback procedures so gateway changes do not introduce downtime or security issues. Use it whenever modifying gateway config, models, channels, agents, tools, sessions, or routing.

How this skill works

Before any change it runs a preflight to confirm scope and scan for sensitive keys, then creates a timestamped backup. It runs schema validation via openclaw doctor both before and after applying changes, and if post-change validation fails it restores the backup and halts further actions. Restarts are only performed after explicit approval to avoid accidental service interruptions.

When to use it

Editing ~/.openclaw/openclaw.json directly
Running openclaw config set/apply for gateway, models, channels, agents, tools, sessions, or routing
Preparing a deployment that depends on configuration changes
After merging a config change in CI to validate before gateway restart
Any time you suspect invalid or risky config edits

Best practices

Run the preflight checklist: confirm change scope and scan for tokens or credentials
Always create a timestamped backup with scripts/backup_config.sh before edits
Prefer openclaw config set for small updates; keep direct-file diffs minimal and documented
Validate with scripts/validate_config.sh (openclaw doctor --non-interactive) before and after changes
Never restart the gateway or apply changes without explicit approval; require sign-off for restarts
If validation fails, use scripts/restore_config.sh immediately and review diffs with scripts/diff_config.sh

Example use cases

Add a new model endpoint to routing: back up, validate, set via openclaw config set, revalidate, then request restart approval
Rotate or remove credentials: preflight to detect sensitive keys, create backup, apply change, validate, and rollback on failure
CI pipeline step that gates merges by running scripts/validate_config.sh to ensure schema compliance
Emergency rollback after a bad deploy: run scripts/restore_config.sh and restart only after approval
Make a non-breaking channel change locally: perform backup, small openclaw config set, verify with doctor, skip restart if not required

FAQ

How do I roll back a bad config change?

Run scripts/restore_config.sh to restore the latest timestamped backup, then validate with scripts/validate_config.sh. Only restart the gateway after confirming the restored config passes validation and you have explicit approval.

Which tool performs schema validation?

Use openclaw doctor --non-interactive (wrapped by scripts/validate_config.sh) to validate against the gateway schema. It reports unknown keys, invalid types, and security issues before you restart.