OpenClaw Configuration Guide — Complete Settings Reference

🚀Quick Start

OpenClaw stores its configuration in ~/.openclaw/openclaw.json. The easiest way to get started is using the setup wizard:

Terminal

# Run the setup wizard
openclaw onboard

# Or generate a config interactively
openclaw config wizard

For manual configuration, you can edit the JSON file directly or use the openclaw config commands:

Terminal

# View current config
openclaw config show

# Set a specific value
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-20250514"

# Add a channel
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"

💡Use openclaw doctor to validate your configuration and check for common issues.

📁File Locations

OpenClaw uses these key files and directories:

Setting	Type	Default	Description
~/.openclaw/openclaw.json	JSON	Created on first run	Main configuration file containing all settings
~/.openclaw/.env	dotenv	Optional	Environment variables (API keys, secrets)
~/.openclaw/agents/	Directory	Auto-created	Per-agent configuration overrides
~/.openclaw/skills/	Directory	Auto-created	Installed skills and their configs
~/.openclaw/plugins/	Directory	Auto-created	Installed plugins
~/.openclaw/memory/	Directory	Auto-created	Conversation memory and context
~/clawd/	Directory	Configurable	Default workspace for file operations

You can also use a project-specific openclaw.config.json in your project directory, which merges with the global config.

🤖AI Models

Configure which AI models power your assistant. OpenClaw supports multiple providers and allows fine-grained control over model parameters.

Supported Providers

🤖

Anthropic (Claude)

Recommended for complex reasoning and coding

anthropic/claude-sonnet-4-20250514

🧠

OpenAI (GPT)

Great all-around performance

openai/gpt-4o

✨

Google (Gemini)

Free tier available, great value

google/gemini-2.0-flash

🚀

MiniMax

Budget-friendly with good quality

minimax/MiniMax-M2.1

Model Configuration Example

{
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "google": {
        "apiKey": "${GOOGLE_API_KEY}"
      },
      "minimax": {
        "baseUrl": "https://api.minimax.io/anthropic",
        "apiKey": "${MINIMAX_API_KEY}",
        "api": "anthropic-messages"
      }
    }
  }
}

Model Parameters

Fine-tune model behavior with per-model parameters:

Per-Model Parameters

{
  "agents": {
    "defaults": {
      "models": {
        "anthropic/claude-opus-4-5": {
          "alias": "opus",
          "params": {
            "cacheControlTtl": "1h",
            "cacheRetention": "short",
            "temperature": 0.7,
            "maxTokens": 8192
          }
        },
        "anthropic/claude-sonnet-4-20250514": {
          "alias": "sonnet",
          "params": {
            "temperature": 0.5
          }
        }
      }
    }
  }
}

Setting	Type	Default	Description
alias	string	—	Short name to reference this model (e.g., 'opus')
params.temperature	number	1.0	Randomness (0-2). Lower = more focused
params.maxTokens	number	8192	Maximum tokens in response
params.cacheControlTtl	string	—	Cache TTL for prompt caching (e.g., '1h')
params.cacheRetention	string	—	Cache strategy: 'short', 'medium', 'long'

Fallback Models

Configure fallback models for resilience when your primary model is unavailable:

Fallback Configuration

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": [
          "anthropic/claude-sonnet-4-20250514",
          "minimax/MiniMax-M2.1",
          "openai/gpt-4o"
        ]
      }
    }
  }
}

ℹ️Fallbacks are tried in order. If Claude Opus fails (rate limit, outage), OpenClaw automatically tries Claude Sonnet, then MiniMax, then GPT-4o.

👤Agents

An agent is an AI assistant instance with its own identity, model settings, and workspace. OpenClaw supports multiple agents for different use cases.

Agent Defaults

Settings that apply to all agents unless overridden:

Agent Defaults

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5"
      },
      "workspace": "/Users/you/clawd",
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      },
      "compaction": {
        "mode": "safeguard"
      },
      "heartbeat": {
        "every": "30m"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

Setting	Type	Default	Description
workspace	string	~/clawd	Working directory for file operations
contextPruning.mode	string	cache-ttl	How to manage conversation context: 'cache-ttl', 'sliding', 'none'
contextPruning.ttl	string	1h	Context cache lifetime
compaction.mode	string	safeguard	Message compaction strategy: 'safeguard', 'aggressive', 'none'
heartbeat.every	string	—	How often the agent checks in (e.g., '30m', '1h')
maxConcurrent	number	4	Max concurrent conversations per agent
subagents.maxConcurrent	number	8	Max concurrent subagent tasks

Multi-Agent Setup

Run multiple specialized agents for different purposes — a work assistant, personal assistant, and coding assistant, each with unique settings:

Multi-Agent Configuration

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514"
      }
    },
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "Samantha",
          "theme": "Personal assistant 🐙",
          "emoji": "🐙"
        }
      },
      {
        "id": "work",
        "identity": {
          "name": "Atlas",
          "theme": "Professional work assistant",
          "emoji": "💼"
        },
        "model": {
          "primary": "anthropic/claude-opus-4-5"
        },
        "workspace": "/Users/you/work"
      },
      {
        "id": "code",
        "identity": {
          "name": "Claude",
          "theme": "Coding assistant",
          "emoji": "💻"
        },
        "model": {
          "primary": "anthropic/claude-opus-4-5"
        }
      }
    ]
  }
}

💡Switch between agents using /agent work or /agent code in any channel. Each agent maintains its own conversation history.

Agent Identity

Customize your agent's personality and behavior with identity files:

~/.openclaw/agents/main/SOUL.md

# Who I Am

I'm Samantha — your personal AI assistant. I help with daily tasks, 
research, writing, and keeping you organized.

## Personality
- Friendly but efficient
- Concise unless asked for details
- Proactive about reminders and follow-ups
- Use emojis sparingly but warmly

## Communication Style
- Keep responses under 200 words unless necessary
- Ask clarifying questions when ambiguous
- Always confirm before taking important actions

## Rules
- Never share private information externally
- Always respect calendar time blocks
- Remind about important deadlines 24h in advance

Create these files per agent at ~/.openclaw/agents/{agent_id}/SOUL.md

📱Channels

Channels connect your AI assistant to messaging platforms. Configure one or multiple channels to chat with your assistant from anywhere.

The most feature-rich channel with inline buttons, reactions, and voice notes.

Telegram Configuration

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "allowFrom": [123456789, 987654321],
      "groups": {
        "-1001234567890": {
          "enabled": true,
          "agent": "work"
        }
      },
      "streamMode": "partial",
      "draftChunk": {
        "breakPreference": "paragraph"
      },
      "actions": {
        "reactions": true,
        "sendMessage": true
      }
    }
  }
}

Setting	Type	Default	Description
botToken	string	Required	Bot token from @BotFather
dmPolicy	string	open	Who can DM: 'open', 'pairing', 'allowlist'
groupPolicy	string	mention	Group behavior: 'open', 'mention', 'disabled'
allowFrom	number[]	[]	Telegram user IDs allowed to chat (if using allowlist)
streamMode	string	partial	Response streaming: 'partial', 'full', 'none'
actions.reactions	boolean	true	Allow the bot to react to messages

Discord

Discord Configuration

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "${DISCORD_BOT_TOKEN}",
      "applicationId": "${DISCORD_APP_ID}",
      "allowedGuilds": ["123456789"],
      "allowedChannels": ["general", "ai-chat"]
    }
  }
}

WhatsApp Configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "phoneNumberId": "${WHATSAPP_PHONE_ID}",
      "accessToken": "${WHATSAPP_ACCESS_TOKEN}",
      "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
      "webhookUrl": "https://your-server.com/webhook/whatsapp"
    }
  }
}

Slack

Slack Configuration

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "${SLACK_BOT_TOKEN}",
      "appToken": "${SLACK_APP_TOKEN}",
      "signingSecret": "${SLACK_SIGNING_SECRET}"
    }
  }
}

ℹ️Each channel can route to a different agent. Set "agent": "work" on a channel or group to use a specific agent.

🌐Gateway

The Gateway is the background service that runs your AI assistant. Configure networking, authentication, and deployment options.

Gateway Configuration

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${GATEWAY_TOKEN}"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  }
}

Setting	Type	Default	Description
port	number	18789	HTTP port for the gateway API
mode	string	local	Deployment mode: 'local', 'cloud', 'hybrid'
bind	string	loopback	Network binding: 'loopback' (localhost), 'all'
auth.mode	string	token	Auth method: 'token', 'none' (not recommended)
auth.token	string	Auto-generated	Bearer token for API access
tailscale.mode	string	off	Tailscale VPN: 'off', 'funnel', 'serve'

Gateway Commands

# Start gateway as background daemon
openclaw gateway start

# Run in foreground (for debugging)
openclaw gateway run

# Check status
openclaw gateway status

# Stop the daemon
openclaw gateway stop

# Restart
openclaw gateway restart

🔐Secrets & Security

OpenClaw provides multiple ways to manage sensitive credentials securely.

Environment Variables

The recommended approach is using environment variables. OpenClaw reads from ~/.openclaw/.env:

~/.openclaw/.env

# AI Provider Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

# Channel Tokens
TELEGRAM_BOT_TOKEN=123456:ABC...
DISCORD_BOT_TOKEN=MTIz...
SLACK_BOT_TOKEN=xoxb-...

# Gateway Security
GATEWAY_TOKEN=your-secret-token

# Optional Services
BRAVE_SEARCH_KEY=BSA...

Reference environment variables in your config using the ${VAR_NAME} syntax:

Using Environment Variables

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  },
  "channels": {
    "telegram": {
      "botToken": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

API Key Management

Best practices for managing API keys:

✓Use .env files — Never commit API keys to version control
✓Set file permissions — Run chmod 600 ~/.openclaw/.env
✓Rotate regularly — Regenerate keys periodically
✓Use scoped keys — Create keys with minimal required permissions
✗Never share .env — Keep secrets out of screenshots and logs

⚠️OpenClaw never logs or transmits your API keys. They remain on your local machine and are only used for direct API calls to providers.

🔌Plugins

Plugins extend OpenClaw with additional capabilities. Install from npm or local directories.

Plugin Configuration

{
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      },
      "unbrowse-openclaw": {
        "enabled": true,
        "credentialSource": "auto"
      }
    },
    "installs": {
      "unbrowse-openclaw": {
        "source": "npm",
        "spec": "@getfoundry/unbrowse-openclaw",
        "version": "0.5.2"
      }
    }
  }
}

Plugin Commands

# List installed plugins
openclaw plugins list

# Install a plugin from npm
openclaw plugins add @getfoundry/unbrowse-openclaw

# Enable/disable a plugin
openclaw plugins enable telegram
openclaw plugins disable telegram

# Update all plugins
openclaw plugins update

🧩Skills

Skills are specialized capabilities for specific tasks like email, calendar, or web automation.

Skills Configuration

{
  "skills": {
    "install": {
      "nodeManager": "bun"
    },
    "entries": {
      "nano-banana-pro": {
        "apiKey": "${NANO_BANANA_KEY}"
      },
      "sag": {
        "apiKey": "${SAG_API_KEY}"
      }
    }
  }
}

Skill Commands

# List available skills
openclaw skills list

# Install a skill
openclaw skills install sag

# Configure a skill
openclaw skills config sag set apiKey "your-key"

# Run a skill
openclaw skills run sag say "Hello world"

🛠️Tools

Built-in tools provide core functionality like web search and media processing.

Tools Configuration

{
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "${BRAVE_SEARCH_KEY}"
      }
    },
    "media": {
      "audio": {
        "enabled": true,
        "models": [
          {
            "type": "cli",
            "command": "whisper",
            "args": ["--model", "base", "{{MediaPath}}"],
            "timeoutSeconds": 60
          }
        ]
      }
    }
  },
  "talk": {
    "apiKey": "${TTS_API_KEY}"
  }
}

Setting	Type	Default	Description
tools.web.search.provider	string	brave	Web search provider: 'brave', 'google'
tools.media.audio.enabled	boolean	true	Enable voice note transcription
talk.apiKey	string	—	API key for text-to-speech service

🪝Hooks

Hooks run custom logic at key points in the conversation lifecycle.

Hooks Configuration

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "boot-md": {
          "enabled": true
        },
        "command-logger": {
          "enabled": true
        },
        "session-memory": {
          "enabled": true
        }
      }
    }
  }
}

Setting	Type	Default	Description
boot-md	hook	enabled	Loads BOOT.md on startup for initial context
command-logger	hook	enabled	Logs all commands executed by the agent
session-memory	hook	enabled	Persists conversation memory between sessions

⚡Advanced Settings

Context Pruning

Control how conversation history is managed to stay within context limits:

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h",
        "maxTokens": 150000
      }
    }
  }
}

Message Settings

{
  "messages": {
    "ackReactionScope": "group-mentions",
    "maxMessageLength": 4096,
    "splitLongMessages": true
  }
}

Update Settings

{
  "update": {
    "checkOnStart": true,
    "autoUpdate": false,
    "channel": "stable"
  }
}

Command Settings

{
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "prefix": "/"
  }
}

📋Complete Configuration Example

Here's a comprehensive example combining all the settings:

Complete openclaw.json

{
  "update": {
    "checkOnStart": true
  },
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "minimax": {
        "baseUrl": "https://api.minimax.io/anthropic",
        "apiKey": "${MINIMAX_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["minimax/MiniMax-M2.1"]
      },
      "workspace": "/Users/you/clawd",
      "heartbeat": {
        "every": "30m"
      },
      "maxConcurrent": 4
    },
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "Samantha",
          "emoji": "🐙"
        }
      }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "streamMode": "partial"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "${GATEWAY_TOKEN}"
    }
  },
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "${BRAVE_SEARCH_KEY}"
      }
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}

⚙️ Configuration Guide

🚀Quick Start

📁File Locations

🤖AI Models

Supported Providers

Anthropic (Claude)

OpenAI (GPT)

Google (Gemini)

MiniMax

Model Parameters

Fallback Models

👤Agents

Agent Defaults

Multi-Agent Setup

Agent Identity

📱Channels

Telegram

Discord

WhatsApp

Slack

🌐Gateway

🔐Secrets & Security

Environment Variables

API Key Management

🔌Plugins

🧩Skills

🛠️Tools

🪝Hooks

⚡Advanced Settings

Context Pruning

Message Settings

Update Settings

Command Settings

📋Complete Configuration Example

Need Help?