Claw Config

---
name: claw-config
description: A grounded self-diagnosis and safe self-modification skill for any OpenClaw agent. Lets the calling agent answer "who am I, what do I own, what does my config look like, and how do I change a field without breaking it?" — without hallucinating field names, identity, or paths. Before patching openclaw.json, the agent must run `claw-config whoami` (self-identification) → `schema <path>` (real field name + type from the installed binary) → `docs <topic>` or `docs search:<keyword>` (official semantics from docs.openclaw.ai). Read-only and diagnose subcommands are cron-safe; `apply` (destructive write) refuses to run under `OPENCLAW_CRON_CONTEXT`.
user-invocable: true
---

# /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`

| Subcommand | What it does | Writes? | Cron-safe? |
|---|---|---|---|
| `claw-config whoami [--json]` | Agent record (id / workspace / agentDir / model) + telegram flags + bindings + cron jobs + skills inventory | No | Yes |
| `claw-config schema [<pointer>]` | Prints the JSON schema (or sub-tree at a JSON pointer or dot path) for the installed `openclaw` binary | No | Yes |
| `claw-config docs [<topic>\|search:<kw>] [--refresh] [--max-age <h>]` | Official documentation as raw markdown from `docs.openclaw.ai` (Mintlify `.md`). No argument prints the site index. `search:<kw>` greps the full-content corpus and groups hits by source page. Cache is keyed by installed openclaw version and TTL'd | No (writes cache) | Yes (cache-only in cron) |
| `claw-config diagnose [--json]` | 12 structural self-checks. Each result reports a dot-path pointer that can be pasted directly into `openclaw config get`. Exits `3` on any `fail` | No | Yes |
| `claw-config plan <patch.json5>` | Dry-run: invokes `openclaw config patch --dry-run`. Prints diff at the affected paths + validation outcome | No | Yes |
| `claw-config apply <patch.json5>` | Versioned backup → `openclaw config patch` → on failure, restore from backup | **Yes** | **No** |
| `claw-config report [--json]` | Combines `whoami` + `diagnose` into a single markdown block suitable for pasting back to the operator | No | Yes |

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):

```json5
// 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

| stderr keyword | Meaning | What the agent should do |
|---|---|---|
| `cannot resolve self` | `$OPENCLAW_AGENT_ID` missing and no `--agent` flag | Report to the operator; ask them to export `OPENCLAW_AGENT_ID=<your-id>` in the calling shell |
| `schema path not found` | The path passed to `schema` does not exist in the installed binary's schema | Run `schema` with no argument first to see the top-level shape; check field name spelling |
| `validate failed: <reason>` | Schema validation rejected the patch (during `plan` dry-run or live `apply`) | Quote the patch file and the validator output verbatim to the operator. **Do not edit the patch and retry on guesswork** — that is the hallucination loop this skill exists to break |
| `patch refers to other agent: <x>` | The patch touches another agent's slice | Stop. Escalate to the operator |
| `backup restored from <path>` | `apply` failed mid-flight; the previous config has been restored | The system is in the pre-patch state. Safe to investigate |
| `docs fetch disabled in cron and no cached copy` | In cron context, the requested docs page has never been fetched | Re-run in interactive context once to populate the cache |

## Invocation

```bash
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:

```bash
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.