OpenClaw Config Guardian

Indexed sub-skill references (source map)

• @[SKILL.md#L1-L136] Standard Frontmatter (name, description).
• @[SKILL.md#L6-L136] OpenClaw Config Guardian.
• @[SKILL.md#L8-L136] Target.
• @[SKILL.md#L11-L136] When to use.
• @[SKILL.md#L17-L136] Required rule.
• @[SKILL.md#L24-L136] Standard path.
• @[SKILL.md#L33-L136] Standard Procedure (SOP).
• @[SKILL.md#L80-L136] Standard report template.
• @[SKILL.md#L93-L136] Error-proof guardrails.
• @[SKILL.md#L99-L136] Quick checklist before closing.
• @[SKILL.md#L106-L136] Expected result.

Scope

• In-scope: audit/patch ~/.openclaw/openclaw.json after an OpenClaw update, backup-first, verify-first, rollback-ready.
• Out-of-scope: runtime issues that are not config/schema drift, or secret mutations without approval.

Target

Standardize operations on ~/.openclaw/openclaw.json when OpenClaw has just updated its version (schema/docs/runtime changes), reducing incorrect patch errors or config drift across future sessions.

When to use?

Activate this skill when one of the following signs appears:

• Boss just updated OpenClaw and asked to "check/patch config".
• It is suspected that the schema has changed, old fields have been deprecated, or the docs have changed.
• openclaw doctor / openclaw status --all reports a warning related to config/gateway/session policy.

Mandatory principles

1. Local docs first: prioritize local docs in the module before concluding.
2. Backup first: always create a backup before writing config.
3. Minimum patch: only correct approved items, do not touch logic outside scope.
4. Verify after patch: always include a re-check step with CLI.
5. Rollback-ready: if verification fails, restore the backup immediately.

Standard path

• Config: /data/adb/openclaw/home/.openclaw/openclaw.json
• Docs root: /data/adb/openclaw/node/lib/node_modules/openclaw/docs
• Priority references:
  • docs/gateway/configuration-reference.md
  • docs/gateway/configuration.md
  • docs/cli/doctor.md
  • docs/gateway/troubleshooting.md

SOP

Step 0 — Snapshot runtime

Run:

• openclaw status
• openclaw doctor
• openclaw status --all (when in-depth diagnosis is needed)

Collect:

• runtime version
• config-related error/warn
• gateway/auth state (if available)

Step 1 — Compare docs/schema

• Read local docs to confirm current fields, avoid guessing the schema.
• If there is a conflict between runtime behavior and docs: prioritize actual runtime + doctor output, and state it clearly in the report.

Step 2 — Create a patch plan by layer

Sort patches before touching files:

• A (Critical/required): metadata version drift, required fields according to the new schema.
• B (Recommended/safe): explicit policy keys (e.g. session scope), slight hardening.
• C (Out-of-scope/runtime issue): gateway pairing, OAuth dir, service state (not considered schema patch).

Only apply classes approved by Boss.

Step 3 — Backup + patch

1. Create timestamped backup:
   • openclaw.json.bak.patch-YYYYMMDD-HHMM
2. Record the patch deterministically (idempotent, no meaningless reorder).
3. Do not delete keys unless there is a clear instruction or doctor requests fixing unknown keys.

Step 4 — Required verification

After patching, run at minimum:

• openclaw config get <each path just edited>
• openclaw doctor
• openclaw status --all (if there was a gateway/auth warning before)

The result must be:

• the new value is correct
• no new errors arise due to the patch

Step 5 — Rollback if failed

If verification fails because of the patch:

• restore the backup immediately
• rerun openclaw doctor
• report failure + cause + new proposed patch

Standard report template

⚡ [patch] scope=A+B3 → done
- changed: <path1>: <old> -> <new>
- changed: <path2>: <old> -> <new>
- backup: <backup_path>
- verify:
  - openclaw config get <path>: <value>
  - doctor: <summary>
  - status --all: <summary>
🛡️ [WARN] <runtime issues not caused by patch>

Error-proof guardrails

• Do not treat runtime warnings (pairing/OAuth/service supervisor) as schema errors if config parsing is still valid.
• Do not arbitrarily touch tokens/secrets without approval.
• Do not run doctor --fix automatically in production without approval (because it may drop unknown keys).
• When lacking schema evidence: stop at the report + request a specific patch scope.

Quick checklist before closing

• There is a backup file
• There is an explicit diff by path
• Each edited key is verified
• Doctor shows no new errors caused by the patch
• There is a noted runtime issue outside config scope if applicable

Expected results

Any session that activates this skill will patch openclaw.json through a consistent process, with backup, verification, and rollback, reducing the risk of incorrect schema when OpenClaw changes versions or docs.

Trigger Rules

• Positive: Triggers when user request matches openclaw-config-guardian according to description: Standardizes audit/patch ~/.openclaw/openclaw.json process after updating OpenClaw (schema/docs/runtime drift), with mandatory backup, verify and rollback.
• Negative: Not enabled for requests outside scope or without the workflow/expertise of this skill.
• Escalation: If there is an external action/network write or sensitive operation, an approval checkpoint must be added before executing.

Output Contract

• Deliverable: target tracking result of openclaw-config-guardian; specify the artifact/path/steps performed (if any).
• Validation: reports PASS/FAIL status and the main checks that were run.
• Failure mode: when there is an error, the root cause + proposed fix must be stated.

Error Handling

• If input/permissions are missing: report what is missing and clearly request additional information.
• If runtime/tool error: brief error return + possible cause + suggested fix.
• If there is a risk policy/safety concern: stop and escalate according to the approval checkpoint.