OpenClaw Config

---

name: openclaw-config

description: Edit and validate OpenClaw Gateway config (openclaw.json / JSON5). Use when adding/changing config keys (gateway.*, agents.*, models.*, channels.*, tools.*, skills.*, plugins.*, $include) or diagnosing openclaw doctor/config validation errors, to avoid schema mismatches that prevent the Gateway from starting or weaken security policies.

---

# 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**

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

- `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**

4. **Validate strictly**

Guardrails (Avoid Schema Bugs)

$include (Modular Config)

`$include` is resolved before schema validation and lets you split config across JSON5 files:

- objects: merge recursively

- arrays: **concatenate** (not replace)

- primitives: later value wins

Common Recipes (Examples)

1. Set default workspace

openclaw config set agents.defaults.workspace '"~/.openclaw/workspace"' --json
openclaw doctor

2. Change Gateway port

openclaw config set gateway.port 18789 --json
openclaw doctor

3. Split config (example)

// ~/.openclaw/openclaw.json
{
  "$include": ["./gateway.json5", "./channels/telegram.json5"],
}

4. Telegram open DMs (must explicitly allow senders)

> Schema constraint: when `dmPolicy="open"`, `allowFrom` must include `"*"`.

openclaw config set channels.telegram.dmPolicy '"open"' --json
openclaw config set channels.telegram.allowFrom '["*"]' --json
openclaw doctor

5. Discord token (config or env fallback)

# Option A: write to config
openclaw config set channels.discord.token '"YOUR_DISCORD_BOT_TOKEN"' --json

# Option B: env var fallback (still recommend a channels.discord section exists)
# export DISCORD_BOT_TOKEN="..."

openclaw doctor

6. Enable web_search (Brave / Perplexity)

openclaw config set tools.web.search.enabled true --json
openclaw config set tools.web.search.provider '"brave"' --json

# Recommended: provide the key via env var (or write tools.web.search.apiKey)
# export BRAVE_API_KEY="..."

openclaw doctor

Resources

Load these when you need a field index or source locations: