OpenClaw Configuration Guide: Complete Settings Reference (2026)

Locate your configuration: OpenClaw stores config at ~/.openclaw/openclaw.json. You can also use environment variables in ~/.openclaw/.env for sensitive data like API keys. For project-specific settings, create openclaw.config.json in your project directory.

Use the setup wizard for quick configuration: Run 'openclaw onboard' for a guided setup that configures your AI provider and first channel. For editing existing config, use 'openclaw config wizard' or 'openclaw config set <path> <value>' for specific changes.

Configure AI providers: In the 'models' section, configure your AI providers. Supported: Anthropic (Claude), OpenAI (GPT), Google (Gemini), MiniMax. Example: Set anthropic.apiKey to your key, then set agents.defaults.model.primary to 'anthropic/claude-opus-4-5' or 'anthropic/claude-sonnet-4-20250514'.

Set up model fallbacks for reliability: Configure fallback models in agents.defaults.model.fallbacks as an array. When your primary model fails (rate limits, outages), OpenClaw automatically tries fallbacks in order. Example: primary 'claude-opus-4-5' with fallbacks ['claude-sonnet-4-20250514', 'minimax/MiniMax-M2.1'].

Fine-tune model parameters: Each model can have custom parameters under agents.defaults.models. Set alias (short name like 'opus'), temperature (0-2, lower = more focused), maxTokens (response length), and cacheControlTtl for prompt caching. Different settings per model.

Configure Telegram channel: Under channels.telegram, set botToken (from @BotFather), dmPolicy ('open', 'pairing', 'allowlist'), groupPolicy ('open', 'mention', 'disabled'), and allowFrom (array of allowed user IDs). Enable streamMode 'partial' for typing indicators.

Set up Discord, Slack, WhatsApp: Each channel has its own configuration block. Discord needs botToken and applicationId. Slack needs botToken, appToken, and signingSecret. WhatsApp needs phoneNumberId, accessToken, and webhookUrl. All tokens should use environment variables.

Create a multi-agent setup: Define multiple agents in agents.list, each with unique id and identity (name, emoji, theme). Each agent can override model, workspace, and other defaults. Switch between agents using /agent <id> in any channel.

Customize agent identity: Create SOUL.md in ~/.openclaw/agents/<agent_id>/ to define personality, communication style, and rules. The agent reads this on startup and follows the guidelines. Great for creating specialized assistants.

Configure the Gateway: The Gateway is the background service. Set port (default 18789), mode ('local' or 'cloud'), bind ('loopback' for localhost-only), and auth.token for API access. Use 'openclaw gateway start' to run as daemon.

Manage secrets securely: Store API keys in ~/.openclaw/.env using ANTHROPIC_API_KEY=sk-ant-... format. Reference in config using ${ANTHROPIC_API_KEY} syntax. Set file permissions with chmod 600. Never commit .env files to git.

Install and configure plugins: Plugins add capabilities. Use 'openclaw plugins add <name>' to install. Configure in plugins.entries with enabled:true and any plugin-specific settings. Unbrowse plugin needs credentialSource for auto-login.

Configure skills: Skills are specialized tools. Install with 'openclaw skills install <name>'. Configure per-skill settings in skills.entries. Skills can have their own API keys and parameters.

Set up web search: Configure tools.web.search with provider ('brave' or 'google') and apiKey. This enables the agent to search the web when needed. Brave Search API is recommended for best results.

Enable voice features: Configure tools.media.audio for voice note transcription (uses Whisper). Set talk.apiKey for text-to-speech responses. Voice notes in Telegram will be automatically transcribed.

Configure context management: Set contextPruning.mode to 'cache-ttl' (prune after time), 'sliding' (keep recent), or 'none'. Set compaction.mode to 'safeguard' or 'aggressive' for long conversations. These prevent context overflow.

Set up heartbeats: Configure agents.defaults.heartbeat.every (e.g., '30m') for periodic check-ins. The agent runs HEARTBEAT.md tasks on schedule. Great for daily briefings and automated monitoring.

Validate your configuration: Run 'openclaw doctor' to check for errors and warnings. It validates API keys, channel configs, file permissions, and common issues. Fix any warnings before production use.

Backup your configuration: The ~/.openclaw/ directory contains all settings. Back it up with git or rsync. OpenClaw creates .bak files on config changes. For version control, add openclaw.json to a private repo.