Gateway Configuration

OpenClaw reads optional JSON5 configuration from ~/.openclaw/openclaw.json. Safe defaults apply when the file does not exist. You only need explicit config when you want to limit triggers, move workspaces, change Gateway auth or tune tool policy.

Gateway Ops Gateway Troubleshooting Help Center

Configuration Principles

Strict Schema

Strict validation

Unknown keys, wrong types and invalid values can prevent the Gateway from starting. Run openclaw doctor first when troubleshooting config.

Recommended Start

Start from defaults

Most people should not author a full config from scratch. Use onboarding to generate safe defaults, then edit only the fields you actually need.

RPC Update

config.apply / config.patch

config.apply replaces the entire config. For partial edits, config.patch or openclaw config set is safer.

Composable

$include composition

When config becomes large, use $include to split it across files and merge them in order.

Frequent Snippets

Minimal config

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

Replace the full config through RPC

Fetch the current hash first, then apply the whole JSON5 document and restart.

openclaw gateway call config.get --params '{}'
openclaw gateway call config.apply --params '{
  "raw": "{\n  agents: { defaults: { workspace: \"~/.openclaw/workspace\" } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "restartDelayMs": 1000
}'

Patch part of the config through RPC

Change one branch without overwriting unrelated fields.

openclaw gateway call config.patch --params '{
  "raw": "{\n  channels: { telegram: { groups: { \"*\": { requireMention: false } } } }\n}\n",
  "baseHash": "<hash-from-config.get>",
  "restartDelayMs": 1000
}'

Fields People Edit Most Often

channels.*.allowFrom: limit who can trigger the agent.

channels.*.groups and agents.list[].groupChat: control group allowlists and mention behavior.

agents.defaults.workspace and agents.list[].workspace: control workspace paths.

gateway.auth.token: recommended even on loopback-only setups.

tools.allow, tools.deny and tools.profile: define what the agent can actually use.