OpenClaw Sacred Rules

Provides essential safety rules and tools for managing OpenClaw configs, backups, auth troubleshooting, and recovery to prevent system failures.

Security Scan

The skill's purpose (config backups, auth troubleshooting, and recovery) broadly matches the scripts provided, but there are inconsistencies and risky behaviours in the instructions and scripts (notably a hardcoded path and un-declared handling of sensitive files) that warrant caution before installing.

Purpose & Capability

The name/description match the actual scripts: they validate configs, create backups, check auth status, and reset cooldowns. However the manifest declares no required environment or filesystem access while the scripts clearly operate on sensitive OpenClaw files under $HOME/.openclaw (openclaw.json, .env, auth-profiles.json). That mismatch (no declared sensitive access but actual file operations) is unexpected and should be clarified.

Instruction Scope

SKILL.md repeatedly warns 'Never directly read auth-profiles.json' yet scripts (safe_backup.sh and reset_cooldowns.sh) copy and, in the case of reset_cooldowns, parse and modify auth-profiles.json. reset_cooldowns.sh backs up a path using $HOME but the embedded Python uses a hardcoded '/Users/admin/...' path, meaning the script will back up one file and modify another — an incoherence that can result in unexpected modifications or failures. The scripts also copy ~/.openclaw/.env (which contains secrets) to a backup dir; the SKILL.md does not discuss backup protection or permissions.

Install Mechanism

No install spec or external downloads — the skill is instruction-only and provides local scripts. This is lower risk than fetching remote binaries. Still, provided scripts will be written to disk as part of the skill bundle, so they should be audited (as done here).

Credentials

The registry metadata declares no required environment variables or credentials, but the scripts expect and source ~/.openclaw/.env and operate on auth-profiles.json (containing API keys and passwords). Backing up and copying .env and auth-profiles.json is a legitimate need for a backup/recovery tool, but the skill should have explicitly declared that it requires access to these sensitive files and should describe how backups are protected (permissions/encryption).

Persistence & Privilege

always:false and no automatic persistence is requested. The skill does modify OpenClaw files when you run its scripts (intended behavior for a recovery tool) but it does not ask for global/always-on privileges or attempt to change other skills' configurations. The risk is limited to the actions of these scripts when invoked.

What to consider before installing

Before installing or running this skill: (1) Review and fix the reset_cooldowns.sh embedded Python: it hardcodes '/Users/admin/...' which is inconsistent with the shell AUTH_FILE ($HOME) and can cause modifying the wrong file — correct it to use the same $AUTH_FILE path. (2) Recognize these scripts will read/copy/modify sensitive files (~/.openclaw/.env and auth-profiles.json). Only run them on a trusted machine, never as root, and ensure backup directories are private and/or encrypted. (3) Confirm the backup flow: safe_backup.sh copies .env and auth-profiles.json into $HOME/openclaw-backups — ensure that directory has restrictive permissions (700) to avoid leaking secrets. (4) If you do not trust the source, don't run the scripts; instead manually inspect and adapt them (especially remove or correct the hardcoded path and add explicit permission/ownership checks). (5) Ask the publisher or maintainer for clarification of required file/permission access and for a signed canonical source; prefer a skill that declares the exact sensitive files it touches and documents backup storage protections. If you want, I can produce a corrected version of reset_cooldowns.sh (and its Python block) that consistently uses $HOME and adds safety checks and permission-locking for the backup directory.

The 8 Sacred Rules learned from production disasters. Never violate these rules.

The 8 Sacred Rules

1. Verify Backups Before Confirming

# Always verify files exist and are valid
ls -la backup-file.json
python3 -m json.tool backup-file.json > /dev/null

2. Never Edit openclaw.json Manually

Wrong: nano ~/.openclaw/openclaw.json
Right: Use Python/CLI tools that handle JSON safely

3. Never Add Unverified Config Keys

Check official docs or ask before adding ANY new configuration keys.

4. Never Enable Sandbox Without Backup

Sandbox mode can cascade auth failures. Always backup first and test in isolation.

5. All Providers Failing = Config Issue

If multiple model providers fail simultaneously, suspect recent config changes, not provider outages.

6. Prefix Auth Commands with Environment

source ~/.openclaw/.env && openclaw auth <command>

7. Anthropic 401 = Check auth-profiles.json

Don't read the file directly - use openclaw status or CLI tools.

8. tool_use without tool_result = Reset Session

Corrupted sessions need /reset to recover.

Safe Backup Script

Use the provided backup script instead of manual file copying:

scripts/safe_backup.sh

Cooldown Reset Script

When experiencing "all providers unavailable" errors despite valid credentials, the in-memory cooldown state may be stale. Use:

scripts/reset_cooldowns.sh

This clears expired cooldowns from auth-profiles.json.

Note: This is a workaround for a bug where in-memory cooldown state doesn't refresh when file timestamps expire.

Config Validation

Before applying config changes:

scripts/config_validator.py ~/.openclaw/openclaw.json

Recovery Procedures

When you break a rule, see references/recovery.md for step-by-step recovery procedures.

Auth Troubleshooting

For auth issues, use the safe checker:

scripts/auth_checker.sh

Never directly read auth-profiles.json - use the checker script instead.