openclaw-config-guide_skill

Overview

This skill documents OpenClaw configuration management best practices and common pitfalls to prevent downtime and misconfiguration. It focuses on safe inspection, incremental updates, and verification steps so operators can change settings without breaking the system. The guidance highlights correct config paths and the recommended gateway commands.

How this skill works

The guide explains how to inspect the live configuration with gateway config.get, make targeted changes with gateway config.patch, and verify results by re-reading the config. It points out dangerous practices (direct file edits, guessing paths, full replacements) and shows correct path examples for channels and providers. The content also references a canonical path cheat sheet for common keys and the JSON schema command for validation.

When to use it

• Before making any OpenClaw configuration change
• When you need to find or confirm configuration paths or structure
• If you encounter configuration errors or startup failures
• When adding or updating providers or communication channels
• When asked how to safely update tokens, credentials, or channel settings

Best practices

• Always read the current config first: run gateway config.get to confirm structure
• Use gateway config.patch for incremental updates instead of replacing the whole config
• Avoid direct edits to ~/.openclaw/openclaw.json or raw write/edit operations
• Verify changes immediately by running gateway config.get and checking for schema errors
• Consult the common-paths reference when uncertain about a key’s correct path
• Prefer small, reversible patches and backup the current config if you plan larger changes

Example use cases

• Enable or update a Discord channel token by patching channels.discord.token instead of modifying plugins.entries.discord.botToken
• Turn a provider on or off by applying a small patch to the provider section, then validate with config.get
• Resolve startup failures by comparing the live config to the expected schema via gateway config.schema
• Add a new channel or provider incrementally so other unrelated settings remain intact
• Audit recent changes by reading the configuration before and after a patch to confirm intended effects