| name | openclaw-ops |
| description | Safe OpenClaw gateway configuration operations. Use when reading, analyzing, or modifying openclaw.json. Enforces schema validation + official documentation verification before every change. |
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 enumadditionalProperties: 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 "
- 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, preferredconfig.apply — only for replacing entire config sectionsexec + 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
