openclaw-config

# OpenClaw Config

## Overview

Safely edit `~/.openclaw/openclaw.json` (or the path set by `OPENCLAW_CONFIG_PATH`) using a schema-first workflow. Validate before and after changes to avoid invalid keys/types that can break startup or change security behavior.

## Workflow (Safe Edit)

1. **Identify the active config path**

- Precedence: `OPENCLAW_CONFIG_PATH` > `OPENCLAW_STATE_DIR/openclaw.json` > `~/.openclaw/openclaw.json`
- The config file is **JSON5** (comments + trailing commas allowed).

2. **Get an authoritative schema (do not guess keys)**

- If the Gateway is running: use `openclaw gateway call config.schema --params '{}'` to fetch a JSON Schema matching the running version.
- Otherwise: use `openclaw/openclaw` source-of-truth, primarily:
  - `src/config/zod-schema.ts` (`OpenClawSchema` root keys like `gateway`/`skills`/`plugins`)
  - `src/config/zod-schema.*.ts` (submodules: channels/providers/models/agents/tools)
  - `docs/gateway/configuration.md` (repo docs + examples)

3. **Apply changes with the smallest safe surface**

- Prefer small edits: `openclaw config get|set|unset` (dot path or bracket notation).
- If the Gateway is online and you want "write + validate + restart" in one step: use RPC `config.patch` (merge patch) or `config.apply` (replaces the entire config; use carefully).
- For complex setups, split config with `$include` (see below).

4. **Validate strictly**

- Run `openclaw doctor`, then fix issues using the reported `path` + `message`.
- Do not run `openclaw doctor --fix/--yes` without explicit user consent (it writes to config/state files).

## Guardrails (Avoid Schema Bugs)

- **Most objects are strict** (`.strict()`): unknown keys usually fail validation and the Gateway will refuse to start.
- `channels` is `.passthrough()`: extension channels (matrix/zalo/nostr, etc.) can add custom keys, but most provider configs remain strict.
- `env` is `.catchall(z.string())`: you can put string env vars directly under `env`, and you can also...