OpenClaw Configuration Reference

intent

openclaw.json uses strict schema validation to configure the OpenClaw Gateway: port, bind address, auth mode, messenger channels (Telegram, WhatsApp, Discord), agent defaults, session scoping, sandbox isolation, cron jobs, tool permissions, model providers, and environment variables. use this skill when setting up OpenClaw for the first time, debugging gateway startup failures, modifying channel settings, switching auth modes, configuring multi-agent systems, or troubleshooting "unknown key" validation errors. the config file lives at ~/.openclaw/openclaw.json and supports hot-reload in hybrid mode (smart reload where possible, full restart where needed).

inputs

config file location:

• ~/.openclaw/openclaw.json (JSON5 format: comments, trailing commas, unquoted keys allowed)

external connections (optional, depending on channels enabled):

• telegram: botToken (store in env var, not hardcoded)
• whatsapp: apiToken (env var)
• discord: botToken (env var)
• other messengers: see channels.md

environment variables for auth:

• OPENCLAW_GATEWAY_TOKEN: gateway auth token (if auth.mode is "token" and no token in config)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.: for model providers (do not hardcode in config)

runtime context:

• Docker: required if sandbox.mode is "all" or "isolated"
• Gateway process: must be running to watch config and hot-reload
• Workspace directory: agent workspace location (default ~/.openclaw/workspace)

cli access:

• openclaw binary: required for openclaw config get/set/unset, openclaw doctor, openclaw onboard

procedure

1. back up existing config before making edits.

   • input: current ~/.openclaw/openclaw.json
   • command: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
   • output: backup file at ~/.openclaw/openclaw.json.bak

2. validate json syntax if editing file directly.

   • input: edited ~/.openclaw/openclaw.json
   • command: cat ~/.openclaw/openclaw.json | python3 -m json.tool
   • output: formatted JSON (no syntax errors) or error message
   • edge case: if file is half-written (e.g., interrupted edit), Gateway may crash on next reload. use openclaw config set to avoid this.

3. set gateway core settings (port, bind, auth, reload mode).

   • input: desired port (default 18789), bind mode (loopback, lan, or off), auth mode (token, none), reload mode (hybrid, hot, restart, off)
   • command (safest): openclaw config set gateway.port 18789 and openclaw config set gateway.auth.mode token and openclaw config set gateway.reload hybrid
   • output: config updated in ~/.openclaw/openclaw.json
   • edge case: if binding to "lan" without auth, Gateway refuses to start for security

4. configure agent defaults (workspace, primary model, heartbeat).

   • input: workspace path (default ~/.openclaw/workspace), model name (e.g., anthropic/claude-opus-4-6), heartbeat interval (e.g., 30m)
   • command: openclaw config set agents.defaults.workspace ~/.openclaw/workspace and openclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6
   • output: agents.defaults section in config
   • edge case: if workspace path does not exist, agent startup fails. create it first.

5. add agents to the agent list if running multi-agent setup.

   • input: agentId (unique identifier), optional override workspace for that agent
   • command: edit config directly or use RPC config.patch method (see decision points)
   • output: agents.list array with agent objects (agentId, workspace)
   • edge case: duplicate agentId causes validation error

6. configure messenger channels (Telegram, WhatsApp, Discord, etc.).

   • input: channel name, botToken or apiToken (store in env var, reference via $env syntax), enabled flag, dmPolicy (pairing, open, restricted), streamMode (partial, full, off)
   • command: openclaw config set channels.telegram.botToken "$TELEGRAM_BOT_TOKEN" or edit config directly
   • output: channels. object in config
   • edge case: if botToken is invalid or missing, channel fails to initialize. always test with openclaw doctor after adding channel.

7. set session scoping and reset behavior.

   • input: dmScope (which agent handles DMs, e.g., main), reset mode (daily, weekly, manual), atHour (hour of day for daily reset, 0-23)
   • command: openclaw config set session.dmScope main and openclaw config set session.reset.mode daily and openclaw config set session.reset.atHour 4
   • output: session section in config
   • edge case: if dmScope agent does not exist in agents.list, session initialization fails

8. configure models and providers (OpenRouter, Anthropic, OpenAI, etc.).

   • input: provider name (openrouter, anthropic, openai), baseUrl, apiKey (from env var), api type (openai-completions, anthropic-messages, etc.)
   • command: openclaw config set models.providers.openrouter.apiKey "$OPENROUTER_API_KEY"
   • output: models.providers. object in config
   • edge case: if apiKey is invalid, model inference fails at runtime. test with a simple agent query after setup.

9. enable optional features (sandbox, cron, hooks, skills, browser).

   • input: feature name, enabled flag, mode/settings specific to each feature
   • command: openclaw config set sandbox.enabled true and openclaw config set sandbox.mode all and openclaw config set cron.enabled true
   • output: sandbox, cron, hooks, skills, browser sections in config
   • edge case: sandbox.mode "all" or "isolated" requires Docker running. cron.enabled allows scheduling jobs via RPC. hooks.enabled allows webhook receivers.

10. validate final config before deploying.

    • input: fully edited ~/.openclaw/openclaw.json
    • command: openclaw config get (read-only check) and openclaw doctor (detailed validation and auto-repair suggestion)
    • output: full config dump or validation report
    • edge case: if "doctor" finds issues, run openclaw doctor --fix to auto-repair minor issues (e.g., missing defaults, deprecated keys)

11. verify gateway reloads successfully.

    • input: valid config in ~/.openclaw/openclaw.json
    • command: check logs (openclaw logs) or send SIGUSR1 to gateway (pkill -SIGUSR1 -f gateway)
    • output: "config reloaded" message in logs, or full process restart (depending on reload mode)
    • edge case: if reload mode is "restart", all connections drop temporarily. if mode is "hot", connections persist but some changes (e.g., port change) still require restart.

12. recover from broken config if Gateway refuses to start.

    • input: backup file at ~/.openclaw/openclaw.json.bak or last known good config
    • command: cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json or openclaw doctor --fix
    • output: config restored to working state
    • edge case: if no backup exists and auto-fix fails, manually remove offending keys and validate with openclaw config get

decision points

if bind mode is "lan" (exposed to local network):

• do: set auth.mode to "token" and provide a strong token. Gateway refuses to start without auth on lan for security.
• else (bind mode is "loopback" or "off"): auth is optional but recommended.

if running multi-agent system:

• do: define agents.defaults (workspace, model, heartbeat) once, then override per agent in agents.list. set session.dmScope to specify which agent handles DMs.
• else (single agent): use agents.defaults and keep agents.list minimal.

if messenger channels are enabled (Telegram, WhatsApp, etc.):

• do: store botToken and apiKey in environment variables, reference via $env syntax or pass as plain string if using CLI. never hardcode secrets in config file.
• else: leave channels section empty or disabled.

if sandbox.mode is "all" or "isolated":

• do: ensure Docker is running and accessible. test with openclaw doctor before deploying.
• else (sandbox.mode is "none" or "off"): code execution runs in-process (higher risk, no isolation).

if auth.mode is "token":

• do: set auth.token in config or provide OPENCLAW_GATEWAY_TOKEN env var. if neither is set, Gateway startup fails.
• else (auth.mode is "none"): no auth required, but only safe for loopback or fully trusted networks.

if commands.config is true:

• do: restrict to single-user setups only. users can modify config from messenger (highly dangerous in multi-user environments).
• else: set commands.config to false or leave undefined. config changes only via CLI or direct file edit.

if reload mode is "hot":

• do: non-destructive in-place reload, connections stay alive. some changes (port, auth mode, channel add/remove) still require full restart and will fail silently.
• else (reload mode is "restart"): full process restart on any config change, all connections drop briefly.

if using modular config with $include:

• do: included files are merged into main config, same strict validation applies. circular includes cause infinite loop.
• else (single monolithic config): place all settings in ~/.openclaw/openclaw.json.

if calling config.patch via RPC (programmatic access):

• do: note rate limit of 3 calls per 60 seconds to prevent accidental config thrashing. use config.apply only if you need a full config replace.
• else (manual config edits): no rate limit, but file-watch reload may race if edits are rapid-fire.

if config change requires Gateway restart:

• do: manually stop/start the process, or rely on restart reload mode. hot mode will not apply the change.
• else (change is hot-applicable): no restart needed. hot mode and hybrid mode apply the change in-place.

output contract

successful config setup is indicated by:

1. file exists and is valid JSON:

   • location: ~/.openclaw/openclaw.json
   • format: JSON5 (comments, trailing commas allowed)
   • syntax: valid when cat ~/.openclaw/openclaw.json | python3 -m json.tool produces formatted output with no errors

2. config passes strict schema validation:

   • command: openclaw config get returns full config object with no validation errors
   • all top-level keys are known (gateway, agents, channels, session, sandbox, cron, hooks, tools, browser, skills, models, env, commands)
   • no unknown fields present

3. backup file exists:

   • location: ~/.openclaw/openclaw.json.bak
   • purpose: recovery point before last edit

4. Gateway starts without errors:

   • command: openclaw doctor runs with no critical issues
   • logs show: "config loaded" or "config reloaded" message

5. all required sections are present (or use defaults):

   • gateway.port: set (default 18789)
   • gateway.auth: set if bind is "lan"
   • agents.list: at least one agent with valid agentId
   • agents.defaults.workspace: valid path or uses default
   • models.providers: at least one provider configured if agents use external models

6. channel credentials are secure:

   • no API keys or tokens hardcoded in config file
   • all secrets referenced via env vars or provided at runtime

outcome signal

user knows the skill worked when:

1. Gateway starts successfully:

   • command: openclaw logs or process status shows "gateway started on port 18789"
   • no "validation error", "unknown key", or "refused to start" messages in logs

2. config is readable and correct:

   • command: openclaw config get returns expected values (e.g., gateway.port, agents.list, channels.telegram.enabled)
   • values match what was set

3. hot-reload works (if in hot or hybrid mode):

   • command: edit config, check logs
   • logs show: "config reloaded" or "hot-applying changes" without Gateway restart

4. messenger channels are initialized:

   • command: check logs for channel startup messages (e.g., "telegram channel connected")
   • test by sending a message to bot and verifying agent responds

5. agents are active:

   • command: RPC call to agent.status or check logs for "agent started"
   • heartbeat messages appear in logs at configured interval (e.g., every 30m)

6. doctor reports no critical issues:

   • command: openclaw doctor
   • output: "no critical issues found" or list of warnings (non-blocking)

7. config survives a test reload:

   • command: pkill -SIGUSR1 -f gateway (manual SIGUSR1 reload) or restart process
   • no errors during reload, config is not corrupted

---

minimal working config

{
  gateway: {
    port: 18789
  },
  agents: {
    list: [
      { agentId: "main", workspace: "~/.openclaw/workspace" }
    ]
  }
}

everything else uses defaults.

---

full example config

{
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    reload: "hybrid",
    auth: { mode: "token", token: "change-me-please" },
    http: { endpoints: { chatCompletions: { enabled: true } } }
  },

  commands: { restart: true },

  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-opus-4-6" },
      heartbeat: { every: "30m" }
    },
    list: [
      { agentId: "main" },
      { agentId: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },

  channels: {
    telegram: {
      botToken: "...",
      enabled: true,
      dmPolicy: "pairing",
      streamMode: "partial"
    }
  },

  session: {
    dmScope: "main",
    reset: { mode: "daily", atHour: 4 }
  },

  cron: { enabled: true },

  models: {
    providers: {
      "openrouter": {
        baseUrl: "https://openrouter.ai/api/v1",
        apiKey: "sk-or-...",
        api: "openai-completions"
      }
    }
  },

  env: {
    vars: { TZ: "America/New_York" },
    shellEnv: true
  }
}

---

validation checklist

before saving config changes:

• json is valid (no trailing syntax errors, mismatched braces)
• no unknown keys (Gateway rejects unknown fields)
• auth is set if bind mode is "lan" (Gateway refuses to start without auth on lan)
• channel tokens/secrets are in env vars, not hardcoded
• backup exists (openclaw.json.bak)

after saving:

• openclaw config get returns without errors
• openclaw doctor shows no critical issues
• Gateway reloaded successfully (check logs)

---

common pitfalls

1. unknown keys in config - Gateway refuses to start. always check field names against this reference.

2. editing config mid-sentence - Gateway watches the file. if it reads a half-written file, it crashes. use openclaw config set instead of manual editing when possible.

3. gateway.bind: "lan" without auth - Gateway refuses to start for safety. always set auth when binding to lan.

4. commands.config: true - lets anyone in chat modify your config. only for trusted single-user.

5. tools.elevated.enabled: true + open DM policy - gives strangers admin access to your system.

6. missing OPENCLAW_GATEWAY_TOKEN env var - if auth mode is token but no token is set in config or env.

7. sandbox.mode: "all" without Docker - sandbox requires Docker to be running.

8. invalid workspace path - if agents.defaults.workspace does not exist, agent startup fails. create the directory first.

9. dmScope agent does not exist - if session.dmScope points to an agent not in agents.list, session initialization fails.

10. duplicate agentId in agents.list - validation error. each agent must have a unique agentId.

11. botToken/apiKey hardcoded in config - exposes credentials to file-system access attacks. store in env vars instead.

12. model provider apiKey invalid or missing - model inference fails at runtime. test after setup.

13. rate-limiting config.patch RPC - only 3 calls per 60 seconds allowed. rapid-fire updates will fail.

14. hot-reload mode ignores some changes - port, auth mode, channel add/remove still require full restart. use restart mode if unsure.

---

further reference

• gateway, auth, http endpoints: see gateway.md
• agents, models, workspace, heartbeat: see agents.md
• all channel platforms: see channels.md
• session, sandbox, cron, hooks: see session.md
• tools, browser, skills config: see tools.md
• models, env, auth, logging: see models-env.md