Configuration Guide

This page is the configuration reference for OpenClaw. You’ll find where the config file lives, how to pick a model and authenticate (OAuth or API key), where the workspace and skills live, how security and DM access work, and how to tune the Gateway and agent. Use it when you want to change providers, add failover, lock down DMs or sandboxing, or move the workspace. Newer installs use ~/.openclaw/openclaw.json and ~/.openclaw/workspace; legacy ~/.clawdbot/moltbot.json and ~/clawd are still supported. Restart the Gateway after editing config so changes take effect.

The smallest valid config is a model identifier. Put it in ~/.openclaw/openclaw.json or ~/.clawdbot/moltbot.json (depending on your install). Everything else falls back to defaults. You get a working agent that uses the chosen model; add more keys as you need them.

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

You choose the LLM provider and model in config (agent.model) and authenticate with OAuth (for subscriptions like Claude Pro/Max or ChatGPT) or API keys. OpenClaw supports Anthropic, OpenAI, Gemini, and local models; you can set up failover and profile rotation so another provider is used if the first fails. Recommended: Anthropic Pro/Max with Opus 4.6 for long context and stronger prompt-injection resistance. Run openclaw onboard again to re-run OAuth or switch auth method; keep only one auth method per provider (OAuth or API key, not both). Full options: Troubleshooting for auth issues.

Per-channel model overrides (2026.2.21): Use channels.modelByChannel to override the model per channel; active overrides are noted in /status output.

Different models for different tasks: Use a strong model (e.g. Opus) for general reasoning and a specialized model for coding, research, or creative writing to save cost and speed up parallel work. Configure overrides per channel or per agent; see Tips & best practices for patterns.

OpenClaw keeps prompts, skills, and memory in a single workspace directory. Default root is ~/.openclaw/workspace or ~/clawd; override with agents.defaults.workspace. Inside it: AGENTS.md, SOUL.md, TOOLS.md (and optionally SHIELD.md for a loadable security policy), plus skills/<skill>/SKILL.md and daily memory files (Markdown). The workspace is plain files and folders—edit with any editor, search with Raycast or Obsidian, back up or version-control as you like. Your agent's identity (soul) in SOUL.md and AGENTS.md shapes how it uses its capabilities; many practitioners find identity matters more than adding more skills—see Soul & Agent Identity. To add or change skills: Skills.

OpenClaw is connected to real messaging apps; treat inbound DMs as untrusted. By default the main session runs tools on the host (full access when it’s just you). For group and channel sessions you can run them in per-session Docker sandboxes so bash and tools are isolated: set agents.defaults.sandbox.mode to "non-main". Sandboxed sessions use an allowlist of tools (e.g. bash, read, write, sessions_*) and a denylist (e.g. browser, gateway). Run openclaw doctor to see risky or inconsistent DM/sandbox settings. Details: Security guide.

By default, unknown people who DM the bot get a pairing code and their message is not processed until you approve. Approve with clawdbot pairing approve <channel> <code> (or the equivalent in config); the sender is then allowlisted. To allow open DMs (anyone can message the bot), set dmPolicy="open" and add "*" to the channel’s allowFrom (e.g. channels.discord.dm.allowFrom, channels.slack.dm.allowFrom). Use this only if you’re sure; otherwise keep pairing. Channels and Security have more on DM policies.

The Gateway is the control plane: it listens on a port and bind address, and can use Tailscale or auth. Default is port 18789, bind 127.0.0.1 (loopback only). Change with gateway.port and gateway.bind. For remote access via Tailscale, set gateway.tailscale.mode (Serve/Funnel). To protect the Gateway itself, set gateway.auth.mode for password or token auth. Architecture and Remote access cover binding and tunnels.

Agent behaviour is controlled by agent.* and related keys: default model (agent.model), thinking depth for supported models, verbose output, and session behaviour (isolation, activation mode, queue mode). See Sessions for session types and routing; the rest of the agent options are documented in the same config schema.

Model auth errors or “unauthorized”: Re-run the provider’s login (e.g. Anthropic OAuth via openclaw onboard). If you switched between API key and OAuth, ensure only one auth method is active for that provider.

Changes not taking effect: Restart the Gateway after editing the JSON (openclaw restart or openclaw gateway restart). Some options need a full restart.

Sandbox or DM policy issues: openclaw doctor flags risky or inconsistent DM/sandbox settings. Run it before opening DMs to the public. More: Troubleshooting.