Claw Config

/claw-config

A grounded toolkit that lets any OpenClaw agent reliably answer:

"Who am I, what does my own config look like, and how do I change it safely?"

Design principle: no hallucination. Every field name, every JSON pointer, every current value is read from the installed openclaw CLI at call time (openclaw config schema, openclaw config get). Every write goes through openclaw config patch (which validates against the schema internally). When the agent needs to know what a field does, the skill fetches the official documentation from docs.openclaw.ai (Mintlify .md raw + full-content index llms-full.txt) — never the model's training memory.

Comparison with openclaw doctor: doctor is a system-wide health check (gateway / secrets / channels), human-readable output. claw-config is agent-scoped (sliced by $OPENCLAW_AGENT_ID — only sees the caller's own config) and supports --json for downstream tooling. They are complementary, not duplicates.

Cron behaviour: apply is hard-refused under OPENCLAW_CRON_CONTEXT=1 (destructive write). All other subcommands run anywhere (read-only or cache-only); docs will serve a cached page in cron context but never makes a fresh HTTPS request.

⚠️ Docs vs installed schema — trust the schema when they disagree

docs.openclaw.ai is a single-version site that always reflects the latest published release (no /v2026.5/... history URLs, no /changelog — only /announcements for breaking changes). The installed openclaw binary may lag (stable channel) or lead (dev channel). So docs and the installed binary can drift:

• Schema is truth — openclaw config schema is generated by the installed binary. If a field appears in schema, it works.
• Docs are guidance — they may describe fields your version does not have yet, or omit new fields you do have.
• When they disagree, trust schema. Treat docs as background context.

The skill defends against this drift: cache files live under ~/.openclaw/.maintenance-cache/docs/<openclaw-version>/<slug>. When you upgrade openclaw, the previous version's cache directory is auto-removed on the next docs call. Each docs call also reports cache age on stderr so the calling agent can decide whether to --refresh.

After upgrading openclaw, run claw-config docs announcements to see breaking changes.

When to invoke

• An operator (the human running the agents) asks you (the agent) to check whether your own config is correct
• You are about to modify a field that belongs to you in ~/.openclaw/openclaw.json (your telegram account, your cron bindings, your model override, your memorySearch settings, your identity)
• You suspect something is wrong with your own setup but cannot describe it precisely (telegram not receiving messages? skill not visible? binding not routing?) → run diagnose
• An operator reports an incident like "the agent silently lost access to its workspace skills" → run report to give them a snapshot

When NOT to invoke

• The field you want to change does not belong to you (e.g., agent myagent trying to edit other-agent's telegram account) → escalate to a coordinator agent or the operator. The skill statically refuses such patches at the plan step.
• The change is to a cron job (lives in ~/.openclaw/cron/jobs.json, not openclaw.json) → use openclaw cron add/edit/rm instead
• The change involves agent-level auth-profiles.json, secrets, or credentials → out of scope; ask the operator
• You are in cron context and want to call apply → it is hard-refused (interactive only)

Hard rules

1. Never hand-edit ~/.openclaw/openclaw.json (no sed, no awk, no python json.dump rewriting the file). All writes go through claw-config apply → openclaw config patch.
2. Before composing any patch, run whoami. Confirm that $OPENCLAW_AGENT_ID resolves to you. If whoami fails, stop and tell the operator. Do not guess your own identity.
3. If you do not know what a field is called, run schema <path>. Do not write nativeSkill / enableSkills / commands.skills from memory. The real names come from the installed binary's schema.
4. Before composing a patch, read the docs. Run docs <topic> (e.g., cli/config, channels/telegram, tools/skills, cli/cron, gateway/config-agents, announcements). If you do not know which page is relevant, run docs (no argument, prints the site index) or docs search:<keyword> (greps the full-content corpus across every page). --help is not enough. Many field semantics are documented only in the prose docs, not in --help output or schema descriptions. The canonical motivating example: a production incident where commands.nativeSkills: false silently hid an agent's workspace skills from its Telegram dispatch table — --help did not describe the field at all, and the schema only said boolean | "auto". The actual semantics lived in tools/slash-commands, reachable via docs search:nativeSkills.
5. Before apply, always plan first. plan is a dry-run via openclaw config patch --dry-run. Read the diff, confirm the validate result.
6. If apply fails, the backup is automatically restored. Quote the stderr verbatim to the operator. Do not retry the patch with guessed adjustments — that is the start of the hallucination spiral the skill exists to prevent.

Seven subcommands

Workflow ordering: whoami → schema → docs → (compose patch) → plan → apply → report

Exit codes: 0 ok / 1 runtime error / 2 bad args or self cannot be resolved / 3 diagnose found at least one fail.

Self-identification (refuses to guess)

Resolution order:

1. $OPENCLAW_AGENT_ID environment variable
2. --agent <id> CLI flag
3. If neither is set → exit 2 with the message cannot resolve self: refusing to guess

The skill never infers identity from cwd, hostname, or the first entry in agents.list[]. The reason: writing the wrong agent's config (e.g., myagent accidentally editing other-agent's telegram bot token) is the highest-impact failure mode this skill is designed to prevent. Forcing the caller to declare its identity makes that class of bug impossible by construction.

Patch format: JSON5 recursive merge

openclaw config patch accepts JSON5 natively: comments, trailing commas, unquoted keys, single quotes are all fine. Semantics:

• Objects merge recursively
• Arrays and scalars replace entire value at that path
• null deletes the path

The skill writes patches as JSON5 files (typically in /tmp/) and passes them to plan / apply. The patch file itself is your audit trail — start it with a comment explaining why you are making the change.

Example patch (sets commands.nativeSkills to true for agent myagent's Telegram account):

// re-enable native skill dispatch on telegram so workspace skills become visible
{
  channels: {
    telegram: {
      accounts: {
        myagent: {
          commands: { nativeSkills: true }
        }
      }
    }
  }
}

Three meaningful tokens (myagent, nativeSkills, true). Everything else is structural path framing — the agent already retrieved the canonical path from schema channels/telegram/accounts/myagent/commands and confirmed semantics with docs search:nativeSkills.

Cross-agent safety

plan and apply statically walk the top-level paths inside the patch. If the patch references another agent's slice (channels.<chan>.accounts.<other>, agents.list[i].id != self, bindings[i].agentId != self), the skill refuses with exit 1 and a message like:

patch refers to other agent(s):
  - channels.telegram.accounts.other-agent
self is 'myagent'. refusing — wrong-agent writes are the #1 risk class.

Patches touching shared sections (agents.defaults, gateway, secrets, auth, etc.) are also refused unless you pass --force-shared. This is to make agent-level vs. system-level changes ergonomically distinct.

Backup naming

Backups go to ~/.openclaw/.maintenance-backups/openclaw.<YYYYMMDD-HHMMSS>.pre-<patch-stem>.json. They live in a dedicated directory to avoid being caught by openclaw's own rotating backup scheme (which rotates files matching openclaw.json.bak[.N]). On apply failure the file is cp-restored to ~/.openclaw/openclaw.json before the script exits non-zero.

Failure modes

Invocation

OPENCLAW_AGENT_ID=myagent claw-config whoami --json
OPENCLAW_AGENT_ID=myagent claw-config schema channels/telegram/accounts/myagent/commands
claw-config docs                                  # site index
claw-config docs cli/config                       # one page
claw-config docs channels/telegram                # one page
claw-config docs search:nativeSkills              # corpus search
claw-config docs announcements                    # breaking changes
OPENCLAW_AGENT_ID=myagent claw-config diagnose
OPENCLAW_AGENT_ID=myagent claw-config plan  /tmp/fix.json5
OPENCLAW_AGENT_ID=myagent claw-config apply /tmp/fix.json5
OPENCLAW_AGENT_ID=myagent claw-config report

If you want a shorter command name in your own shell, symlink it:

ln -s ~/.local/bin/claw-config ~/.local/bin/oclm

Stdout is structured plain text by default, or JSON with --json (where the subcommand supports it). All informational notes (cache age, fetch URLs, hints) go to stderr so they do not pollute the structured output.