Skills openclaw-ops

Name: openclaw-ops
Author: openclaw

Safe OpenClaw gateway configuration operations. Use when reading, analyzing, or modifying openclaw.json. Enforces schema validation + official documentation verification before every change.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/astralwaveorg/openclaw-config-ops" ~/.claude/skills/openclaw-skills-openclaw-ops && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/astralwaveorg/openclaw-config-ops" ~/.openclaw/skills/openclaw-skills-openclaw-ops && rm -rf "$T"

manifest: skills/astralwaveorg/openclaw-config-ops/SKILL.md

OpenClaw Ops

Safe, documented, schema-validated gateway configuration operations.

When to Use

Any interaction with
```
openclaw.json
```
: read, analyze, modify

config.get

config.schema.lookup

config.patch

config.apply

Adding/removing models, plugins, channels, agents, MCP servers, tools config
Troubleshooting config validation errors
Analyzing current config for optimization opportunities

Two Modes

Determine mode before starting any config work.

Mode A: Analysis Only (no config change)

Trigger: user asks to check, review, compare, optimize, or analyze config, without providing a specific target value.

Flow:

```
config.schema.lookup
```
for relevant keys
Official doc verification (see Step 2)
Present findings with schema + doc evidence
Stop. Wait for user instruction.

Output format:

## Config Analysis

**Finding**: what was found
**Current state**: relevant config values (from config.get)
**Schema evidence**: what schema.lookup confirmed
**Doc evidence**: source URL or QMD reference
**Recommendation**: suggested change (if any), or "no action needed"

Transitioning to Mode B: if user responds with explicit approval to execute a recommended change (e.g. "do it", "apply", "yes, modify it"), switch to Mode B. Start from Step 3 (Form Change Proposal) — Steps 1 and 2 evidence from Mode A can be reused.

Mode B: Modification (config change)

Trigger: user explicitly requests a change AND provides sufficient detail (target key + intended value or clear intent). Examples:

"add model X with id Y"
"set thinkingDefault to medium"
"remove the minimax plugin"
Responding to a Mode A recommendation with "do it" / "apply" / "确认修改"

Insufficient for Mode B (fall back to Mode A + ask):

"帮我改一下配置" without specifying what to change
"优化一下" without target values
Vague instructions without concrete config keys or values

Flow: all 6 steps below, in strict order. No step may be skipped.

Mode Switching Rules

Situation	Action
Mode A analysis done, user says "do it"	→ Mode B, start from Step 3 (reuse Steps 1-2)
Mode B Step 3 proposal rejected	→ Back to Mode A, re-analyze
User intent unclear	→ Mode A, ask for clarification
Emergency config fix needed	→ Still Mode B, but note "emergency" in log

Mandatory Process — Mode B (6 Steps)

Step 1: Schema Lookup

config.schema.lookup(path="target.config.key")

Verify:

Key exists in schema (not invented)
Type matches intended value
```
enum
```
values present → only use values from the enum
```
additionalProperties: false
```
→ no extra sub-fields allowed
Free-form objects (
```
additionalProperties: {}
```
) → still verify field names from docs

Schema has key + config doesn't: this means the key can be created. Proceed to Step 2. Schema lookup fails or key doesn't exist: STOP. Do not proceed. Report to user.

Step 2: Official Documentation Verification

This step is mandatory for both Mode A and Mode B.

Priority order (use first that works):

Priority	Method	When to use
1	`qmd__query`	QMD has OpenClaw docs indexed → fastest, saves tokens
2	`web_fetch("https://docs.openclaw.ai/<path>")`	QMD unavailable or no results
3	`exec("openclaw <command> --help")`	Docs site unreachable; last resort only

What to verify:

Correct parameter names and values
Required vs optional fields
Known limitations, version requirements, provider-specific behavior
Example configurations

If no documentation source covers the target config:

Note explicitly: "No documentation found for <key>"
Rely on schema alone (type + enum + children)
Do NOT guess. If schema is ambiguous, ask user.

Step 3: Form Change Proposal

Present to user:

## Config Change Proposal

**Target**: full config key path
**Action**: add / modify / remove
**Current value**: (from config.get, or "does not exist")
**Proposed value**: exact new value
**Schema evidence**: type, enum, constraints from schema.lookup
**Doc evidence**: URL or "QMD:collection/doc-id" confirming correctness
**Impact**: what changes for the user
**Risk**: version constraints, provider limitations, side effects

Step 4: User Confirmation

Wait for explicit user approval. Quote the exact change.

All Mode B operations require confirmation. There are no exceptions — if the user already said "do it", that triggered Mode B, but Step 3 proposal must still be presented and acknowledged.

When in doubt: ask. Over-confirming is better than wrong changes.

Step 5: Backup + Execute

5a. Backup first (always, before any modification):

exec("cp ~/.openclaw/openclaw.json ~/.openclaw/backups/openclaw-$(date +%Y%m%d%H%M%S).json")

If backup fails: STOP. Do not proceed without backup.

5b. Apply change (in preference order):

```
config.patch
```
— partial updates, preferred
```
config.apply
```
— only for replacing entire config sections
```
exec
```
+ Python JSON edit — only when config.patch cannot achieve the change (e.g. removing keys)

One logical change per operation — see definition below.

Step 6: Verify + Log

1. config.get(path="target.key") → confirm value applied correctly
2. exec("openclaw config validate") → confirm config is valid
3. If gateway restart triggered → confirm restart succeeded
4. Record change to logs/config-changes.log

Change log format (append to

~/.openclaw/workspace/logs/config-changes.log

## YYYY-MM-DDTHH:MM:SS+08:00
- action: add|modify|remove
- target: config.key.path
- old_value: <previous value or "N/A">
- new_value: <new value>
- reason: <brief justification>
- schema_verified: true
- doc_source: <URL or "QMD:collection/doc-id">
- user_approved: true
- backup: <backup file path>

Definition: "One Logical Change"

A logical change = changes to keys within the same config subtree that serve a single user intent.

Example	Count	Reason
Add one model entry	1	Single intent, one subtree
Add model + set it as fallback	1	Same intent (add fallback model), same subtree
Add model + add plugin + change channel	3	Different subtrees, different intents
Modify 3 unrelated fields in tools.*	3	Different intents, must be separate patches

Rule of thumb: if you need to mention two different top-level config sections in one proposal, split it.

If in doubt, split. Smaller patches are safer and easier to roll back.

Hard Prohibitions

❌ Guess field names or values — always verify via schema + docs
❌ Skip schema.lookup — even for "obvious" or "previously used" keys
❌ Skip doc verification — even when you "already know" the config
❌ Use external blogs/GitHub issues as config source — clues only, never evidence
❌ Bundle unrelated changes — one logical change per patch
❌ Modify config without backup — Step 5a is mandatory
❌ Modify config without logging — every change must go to config-changes.log
❌ Proceed after schema lookup failure — STOP and report
❌ Assume prior knowledge replaces verification — "I've done this before" is not evidence
❌ Skip user confirmation — all Mode B operations require Step 4

Documentation Quick Reference

Topic	URL
Config reference	`https://docs.openclaw.ai/gateway/configuration-reference`
Config examples	`https://docs.openclaw.ai/gateway/configuration-examples`
Models	`https://docs.openclaw.ai/models/`
Plugins	`https://docs.openclaw.ai/plugins/`
Channels	`https://docs.openclaw.ai/channels/`
Tools	`https://docs.openclaw.ai/tools/`
MCP	`https://docs.openclaw.ai/tools/mcp`
CLI reference	`https://docs.openclaw.ai/cli/`
Security	`https://docs.openclaw.ai/gateway/security`
Sandbox	`https://docs.openclaw.ai/gateway/sandboxing`
Skills	`https://docs.openclaw.ai/tools/skills`
Multi-agent	`https://docs.openclaw.ai/concepts/multi-agent`
CLI backends	`https://docs.openclaw.ai/gateway/cli-backends`
Thinking levels	`https://docs.openclaw.ai/tools/thinking`
apply_patch	`https://docs.openclaw.ai/tools/apply-patch`
Web search	`https://docs.openclaw.ai/tools/web-search`
TTS	`https://docs.openclaw.ai/tools/tts`
Image gen	`https://docs.openclaw.ai/tools/image-generation`
Music gen	`https://docs.openclaw.ai/tools/music-generation`
Providers	`https://docs.openclaw.ai/providers/<provider-name>`

Schema Drill-Down

For nested structures, lookup sub-paths incrementally:

config.schema.lookup(path="agents.defaults.cliBackends")
config.schema.lookup(path="agents.defaults.cliBackends.*")
config.schema.lookup(path="agents.defaults.cliBackends.*.sessionMode")

Each level returns type, enum, children, and hints.

Error Recovery

Problem	Action
Gateway won't start	`openclaw config validate --json` → find specific errors
Unknown key error	Restore from backup → `openclaw config unset <path>`
Type mismatch	Schema lookup for expected type → fix value → re-verify
Plugin fails to load	Check plugin docs for required config fields
config.patch rejected	Check schema for `additionalProperties: false` → verify all sub-fields
Patch succeeds but wrong value	Restore from backup → redo with correct value

Scope

This skill covers

openclaw.json

configuration only.

Workspace files (SOUL.md, AGENTS.md, etc.): follow workspace rules
Skill creation: use the skill-creator skill
Plugin development: follow plugin docs