configuration

OpenClaw Configuration

Overview

OpenClaw uses a single configuration file at ~/.openclaw/openclaw.json in JSON5 format (comments, trailing commas, and unquoted keys are all valid). The gateway validates every key against a strict schema on startup -- unknown keys prevent the process from starting. If no config file exists, safe defaults apply and OpenClaw remains functional for basic use.

Five methods exist to manage configuration:

1. Interactive wizard -- openclaw configure (or openclaw onboard for first-time setup)
2. CLI -- openclaw config get <key>, openclaw config set <key> <value>, openclaw config unset <key>
3. Web UI -- Config tab at http://127.0.0.1:18789
4. Direct file editing -- the gateway watches openclaw.json and auto-reloads safe changes
5. RPC API -- config.get, config.apply (full replace), config.patch (partial merge)

For most users, start with openclaw onboard and then fine-tune via the CLI or Web UI.

Config File Format

The config file supports JSON5 syntax:

{
  // Primary model for all agents
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-4o", "gemini/gemini-2.0-flash"]
      }
    }
  },

  // Gateway infrastructure
  gateway: {
    port: 18789,
    host: "127.0.0.1",
  },
}

Modular Configs with $include

Split large configurations into focused files using $include:

{
  $include: [
    "./models.json",
    "./channels.json",
    "./memory.json"
  ]
}

Rules for $include:

• Paths are relative to the file containing the directive
• Nesting is supported up to 10 levels deep
• Included files deep-merge into the parent object (later files win on conflicts)
• Each included file must itself be valid JSON5

For the complete file-format specification, including every top-level key and merge semantics, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/config-file-format.md.

Environment Variables

Secrets and host-specific values belong in environment variables, never hardcoded in openclaw.json. Reference them with the interpolation syntax:

{
  providers: {
    anthropic: {
      apiKey: "${ANTHROPIC_API_KEY}"
    }
  }
}

Precedence Order

Environment variable resolution follows this precedence (highest to lowest):

1. Parent process environment (the shell that launched openclaw gateway)
2. .env file in the current working directory
3. ~/.openclaw/.env (global dotenv)
4. Inline env.vars block inside openclaw.json

Key Environment Variables

Variable	Purpose
ANTHROPIC_API_KEY	Anthropic / Claude models
OPENAI_API_KEY	OpenAI models
GEMINI_API_KEY	Google Gemini models
OPENROUTER_API_KEY	OpenRouter aggregated access
TELEGRAM_BOT_TOKEN	Telegram channel
DISCORD_BOT_TOKEN	Discord channel
SLACK_BOT_TOKEN	Slack channel (bot token)
SLACK_APP_TOKEN	Slack channel (app-level token)
OPENCLAW_GATEWAY_TOKEN	Gateway authentication
OPENCLAW_HOME	Override default ~/.openclaw directory
BRAVE_API_KEY	Brave Search tool
ELEVENLABS_API_KEY	ElevenLabs voice synthesis
DEEPGRAM_API_KEY	Deepgram speech-to-text

For the full list, dotenv file syntax, and advanced interpolation patterns, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/environment-variables.md.

Hot-Reload

The gateway watches openclaw.json for changes and reacts according to the configured reload mode.

Reload Modes

Set the mode under gateway.reloadMode:

Mode	Behavior
"hybrid" (default)	Auto-applies safe changes; restarts automatically for critical changes
"hot"	Applies safe changes only; logs a warning when a restart is needed
"restart"	Restarts the gateway on any detected change
"off"	Disables file watching entirely

Safe vs. Critical Changes

Safe changes (applied without restart):

• channels -- add, remove, or reconfigure messaging channels
• agents -- model selection, system prompts, tool permissions
• models -- provider keys, fallback lists
• automation -- scheduled tasks, triggers
• sessions -- scoping rules, identity links
• tools -- enable/disable tools, tool configuration

Critical changes (require gateway restart):

• gateway -- port, host, TLS, authentication
• Core infrastructure settings (logging transport, plugin loader)

For reload internals, debounce timing, and per-section override flags, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/hot-reload.md.

Model Configuration

Models use a provider/model-name format string. Configure defaults under agents.defaults.model:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openai/gpt-4o",
          "gemini/gemini-2.0-flash"
        ]
      }
    }
  }
}

Supported Providers

Provider	Prefix	Notes
Anthropic	anthropic/	Claude models; recommended default
OpenAI	openai/	GPT-4o, o1, o3
Google Gemini	gemini/	Gemini 2.0 Flash, Pro
DeepSeek	deepseek/	DeepSeek-V3, R1
OpenRouter	openrouter/	Aggregator; any model on their catalog
Ollama	ollama/	Local models; requires 48GB+ VRAM for quality results

Auto-Failover

The gateway automatically fails over to the next model in the fallbacks array when:

• An authentication error occurs (invalid or expired API key)
• A rate limit is hit (429 responses)
• A request times out

Failover is transparent to the end user. The gateway logs which model served each request.

For per-agent model overrides, token-budget settings, temperature/top-p tuning, and provider-specific options, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/models-and-providers.md.

Memory Configuration

OpenClaw maintains conversation memory through daily Markdown logs and a curated long-term memory file.

Storage Layout

~/.openclaw/memory/
  YYYY-MM-DD.md    # Daily conversation logs (auto-generated)
  MEMORY.md        # Curated long-term memory (agent-maintained)

Search Backend

Configure the vector search provider under memorySearch.provider:

Provider	Value	Notes
OpenAI	"openai"	Uses text-embedding-3-small; requires OPENAI_API_KEY
Local	"local"	On-device embeddings; no external calls
Gemini	"gemini"	Uses Gemini embedding model; requires GEMINI_API_KEY
Voyage	"voyage"	Voyage AI embeddings; requires VOYAGE_API_KEY

Memory search uses a hybrid approach: BM25 keyword matching combined with vector similarity, both backed by SQLite. This means recall stays high even when the embedding model changes.

Compaction

Control memory compaction to keep context windows manageable:

{
  memoryFlush: {
    enabled: true,
    softThresholdTokens: 80000  // trigger compaction at this token count
  }
}

When the token count in the active context crosses softThresholdTokens, the gateway compacts older messages into a summary and persists them to the daily log.

For embedding model selection, compaction strategies, MEMORY.md curation rules, and SQLite index tuning, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/memory-configuration.md.

Session Scoping

Session scoping determines how conversations are isolated across users and channels. Set the mode under session.mode:

Mode	Isolation	Use Case
"main"	All DMs share one session	Single-user or shared-assistant setups
"per-peer"	Isolate by sender ID	Multi-user; each person gets their own context
"per-channel-peer"	Isolate by channel + sender ID	Multi-platform; same person on Telegram and Discord gets separate sessions

Identity Links

Collapse multiple platform identities into a single logical user with session.identityLinks:

{
  session: {
    mode: "per-peer",
    identityLinks: [
      {
        // These three identities share one session
        telegram: "12345678",
        discord: "987654321",
        slack: "U04ABCDEF"
      }
    ]
  }
}

When identity links are defined, messages from any linked identity route to the same session, regardless of which channel they arrive on.

For advanced scoping patterns, TTL-based session expiry, and multi-tenant configurations, read ${CLAUDE_PLUGIN_ROOT}/skills/configuration/references/sessions-and-scoping.md.

Quick Reference: Configuration Methods

Method	Best For	Command / Location
Interactive wizard	First-time setup	openclaw onboard or openclaw configure
CLI get/set	Scripting, CI	openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-6"
Web UI	Visual editing	http://127.0.0.1:18789 Config tab
Direct file edit	Bulk changes	~/.openclaw/openclaw.json (auto-reloads)
RPC API	Programmatic control	config.get, config.apply, config.patch

Verification

After making configuration changes, verify the setup:

# Health check -- validates config schema, provider keys, channel connectivity
openclaw doctor

# Gateway status -- confirm gateway is running with expected config
openclaw gateway status

# Channel probe -- verify each channel can send/receive
openclaw channels status --probe

If openclaw doctor --fix is available, it can auto-repair common configuration issues such as missing environment variables or malformed JSON5 syntax.