OpenClaw Config Reference: Every openclaw.json Option

Key takeaways

• Every OpenClaw config lives in ~/.openclaw/openclaw.json (JSON5 format: comments and trailing commas allowed)
• The schema is strict. Any unknown key causes the gateway to refuse to start. Run openclaw doctor to diagnose failures.
• Sensitive credentials like bot tokens have environment variable fallbacks so you can keep secrets out of the config file
• You can edit config with openclaw config set <key> <value>, the interactive wizard (openclaw configure), or the Control UI at http://127.0.0.1:18789
• All fields are optional. OpenClaw uses safe defaults when a key is omitted

What openclaw.json is and where to find it

The config file lives at ~/.openclaw/openclaw.json. If the file does not exist, OpenClaw boots with safe defaults. The format is JSON5, which means you can use comments (// or /* */) and trailing commas without breaking the parser.

OpenClaw validates the file against a strict schema on startup. Unknown keys, wrong types, and invalid values all prevent the gateway from starting. Only the root-level $schema key is exempt, so JSON Schema-aware editors can attach metadata. When validation fails, diagnostic commands like openclaw doctor, openclaw logs, openclaw health, and openclaw status continue to work so you can debug.

Run openclaw doctor --fix to auto-repair common issues.

How to edit the openclaw.json config

Four methods work for editing config:

CLI (best for scripting):

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Interactive wizard:

openclaw configure
openclaw onboard

Control UI: Open http://127.0.0.1:18789 and use the Config tab. The UI renders a form from the schema with a Raw JSON editor as a fallback.

Direct file edit: Edit ~/.openclaw/openclaw.json directly. The gateway watches the file and applies changes automatically without a restart (hot reload).

Environment variable fallbacks for API keys

These environment variables are read automatically without needing entries in openclaw.json. Useful for secrets management or CI environments.

Model provider API key resolution

OpenClaw checks these sources in priority order for each provider:

Examples: ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY. Google providers also check GOOGLE_API_KEY as a fallback.

OpenClaw only retries with the next key for rate-limit errors (429, quota, resource exhausted). Non-rate-limit errors are not retried with alternate keys.

For daemon setups (systemd, launchd), put keys in ~/.openclaw/.env so the daemon can read them without shell inheritance.

Channel-specific environment variables

iOS push relay variables (temporary overrides)

Gateway config options (gateway.*)

Controls the gateway server itself: binding, health checks, and push.

Disable auto-restarts globally:

{
  gateway: {
    channelHealthCheckMinutes: 0,
  },
}

Disable auto-restarts for one channel only:

{
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
    },
  },
}

Channel config keys by provider

DM and group access policy (all channels)

Every channel supports dmPolicy and groupPolicy.

Use channels.defaults.groupPolicy to set a fallback for all providers at once.

Channel defaults (channels.defaults.*)

{
  channels: {
    defaults: {
      groupPolicy: "allowlist",
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

Channel model overrides (channels.modelByChannel.*)

Pin specific channel IDs to a model. Applies when a session does not already have a model override.

{
  channels: {
    modelByChannel: {
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
      },
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
    },
  },
}

WhatsApp config (channels.whatsapp.*)

WhatsApp uses the Baileys Web protocol. It starts automatically when a linked session exists.

Multi-account: add account IDs under channels.whatsapp.accounts.<id>. Per-account keys: sendReadReceipts, dmPolicy, allowFrom.

Reconnect settings live under web.*:

Telegram config (channels.telegram.*)

Group config: channels.telegram.groups.<chatId>.* with keys allowFrom, systemPrompt, requireMention, topics.

Discord config (channels.discord.*)

Thread bindings (channels.discord.threadBindings.*):

Voice (channels.discord.voice.*):

Discord actions (channels.discord.actions.*):

All default to true except roles and moderation:

reactions, stickers, polls, permissions, messages, threads, pins, search, memberInfo, roleInfo, channelInfo, voiceStatus, events are all enabled by default. roles and moderation are disabled by default (opt-in).

Per-guild config: channels.discord.guilds.<guildId>.* with keys slug, requireMention, ignoreOtherMentions, reactionNotifications, users, channels.

Slack config (channels.slack.*)

Thread behavior (channels.slack.thread.*):

Slash command (channels.slack.slashCommand.*):

Google Chat config (channels.googlechat.*)

Env fallbacks: GOOGLE_CHAT_SERVICE_ACCOUNT, GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.

Signal config (channels.signal.*)

Mattermost config (channels.mattermost.*)

Mattermost requires the plugin: openclaw plugins install @openclaw/mattermost.

Agent and model config options (agents.*)

Controls the agent runtime: workspace, models, thinking mode, heartbeat, and sandboxing.

agents.defaults.*

Heartbeat (agents.defaults.heartbeat.*)

Sandbox (agents.defaults.sandbox.*)

Build the sandbox image first: scripts/sandbox-setup.sh.

Memory search (agents.defaults.memorySearch.*)

Per-agent list (agents.list[])

Override defaults per agent. Each entry requires id. Common per-agent keys:

Session management config (session.*)

Controls conversation continuity, scoping, and cleanup.

Thread bindings (session.threadBindings.*):

Session maintenance (session.maintenance.*):

Send policy (session.sendPolicy.*):

Cron job config options (cron.*)

Controls scheduled task execution behavior.

Cron jobs are defined separately in ~/.openclaw/cron/jobs.json. The cron.* config keys only control the runner behavior.

Webhooks and hooks config (hooks.*)

Enables HTTP webhook ingestion on the gateway.

Treat all webhook payload content as untrusted input. Keep allowUnsafeExternalContent flags disabled except for tightly scoped debugging.

Tool permissions config (tools.*)

Controls which tools the agent can use, execution limits, and media handling.

Exec settings (tools.exec.*):

Elevated permissions (tools.elevated.*):

Media tools (tools.media.audio., tools.media.video.):

Identity, logging, routing, and environment config

Identity (identity.*)

Logging (logging.*)

Messages (messages.*)

Routing (routing.*)

Environment injection (env.*)

Auth profiles (auth.*)

Auth profile metadata lives in openclaw.json. Secrets live in ~/.openclaw/auth-profiles.json.

Custom model providers (models.*)

Key terms

JSON5: A superset of JSON that allows comments (//, /* */) and trailing commas. OpenClaw reads openclaw.json as JSON5.

dmPolicy: A per-channel setting controlling who can DM the bot. Options: pairing, allowlist, open, disabled.

Sandbox: An isolated Docker container for agent tool execution. Controlled by agents.defaults.sandbox.*.

SecretRef: A reference to a secret stored outside the config file. Supports env, file, and exec sources.

Socket Mode vs HTTP Mode (Slack): Socket Mode requires both botToken and appToken. HTTP Mode requires botToken and signingSecret.

FAQ

What happens in OpenClaw if I add an unknown key to openclaw.json?

OpenClaw validates the config against a strict schema on every startup. If you add a key that does not exist in the schema, or use the wrong type, the gateway refuses to start. You will see an error in openclaw doctor output. Use openclaw doctor --fix to apply automatic repairs for common issues. The only key that bypasses strict validation is the root-level $schema string.

Where does OpenClaw look for the ANTHROPIC_API_KEY and what is the priority order when multiple keys exist?

OpenClaw checks these sources in descending priority: OPENCLAW_LIVE_ANTHROPIC_KEY (single-session override), then ANTHROPIC_API_KEYS (comma-separated rotation list), then ANTHROPIC_API_KEY (standard single key), then any ANTHROPIC_API_KEY_* wildcard matches. For daemon setups, place the key in ~/.openclaw/.env. Keys rotate automatically on rate-limit errors (429, quota exceeded). Non-rate-limit errors do not trigger rotation.

How do I set channels.telegram.botToken in OpenClaw without putting the token directly in openclaw.json?

Set the TELEGRAM_BOT_TOKEN environment variable instead. OpenClaw reads it automatically as the fallback for the default Telegram account. For daemon setups, add it to ~/.openclaw/.env. You can also use channels.telegram.tokenFile to point to a regular file containing the token. This keeps secrets out of the JSON config while remaining file-based. Symlinks are rejected for security.

What is the difference between dmPolicy pairing and allowlist in OpenClaw channel config?

Both restrict who can DM the bot, but with different mechanics. pairing (the default) means any unknown sender gets a one-time code to request access. The owner reviews and approves or ignores it. Codes expire after 1 hour, with a cap of 3 pending requests per channel. allowlist is stricter: only senders in allowFrom or the paired allow store can contact the bot. Unknown senders are silently dropped with no code issued.

Can I run openclaw.json changes without restarting the gateway?

Yes. The OpenClaw gateway watches ~/.openclaw/openclaw.json for changes and applies them automatically via hot reload. You do not need to restart the gateway after editing the config file. The CLI method (openclaw config set <key> <value>) also applies changes immediately. If the change causes a schema validation failure, the gateway logs an error and continues running on the previous valid config.

Related resources

• Build a Website with OpenClaw: Practical OpenClaw project walkthrough
• How to Fix OpenClaw Discord Bot Not Responding: Discord channel config troubleshooting
• Best VPS for OpenClaw: Hosting recommendations and gateway setup

Changelog