OpenClaw uses file-based storage with configuration stored in ~/.openclaw/openclaw.json. No external database is required.
Important: This tool has known security concerns and should not be used for production workloads without proper hardening.
OpenClaw stores all configuration in:
~/.openclaw/openclaw.json
This file contains:
Example openclaw.json configuration:
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback",
"auth": {
"mode": "token",
"token": "your-secure-random-token-here"
}
},
"models": {
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-api-key-here"
},
"openai": {
"apiKey": "sk-your-openai-api-key-here"
},
"ollama": {
"baseUrl": "http://localhost:11434"
}
},
"defaultProvider": "anthropic",
"defaultModel": "claude-3-5-sonnet-20241022"
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "your-telegram-bot-token"
},
"whatsapp": {
"enabled": true
},
"discord": {
"enabled": true,
"botToken": "your-discord-bot-token"
}
},
"memory": {
"enabled": true,
"path": "~/.openclaw/memory"
},
"skills": {
"enabled": true,
"allowUnsafe": false
}
}
{
"models": {
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-api-key-here"
}
},
"defaultProvider": "anthropic",
"defaultModel": "claude-3-5-sonnet-20241022"
}
}
Supported models:
claude-3-5-sonnet-20241022 (recommended)claude-3-opus-20240229claude-3-haiku-20240307{
"models": {
"providers": {
"openai": {
"apiKey": "sk-your-openai-api-key-here"
}
},
"defaultProvider": "openai",
"defaultModel": "gpt-4o"
}
}
Supported models:
gpt-4ogpt-4-turbogpt-3.5-turbo{
"models": {
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434"
}
},
"defaultProvider": "ollama",
"defaultModel": "llama3.1"
}
}
Supported models (must be pulled via ollama pull):
llama3.1mistralphi3codellama{
"channels": {
"telegram": {
"enabled": true,
"botToken": "your-telegram-bot-token-from-botfather"
}
}
}
WhatsApp uses QR code pairing via the Web UI:
{
"channels": {
"whatsapp": {
"enabled": true
}
}
}
After starting the gateway, access the Web UI and scan the QR code to pair.
{
"channels": {
"discord": {
"enabled": true,
"botToken": "your-discord-bot-token"
}
}
}
{
"channels": {
"slack": {
"enabled": true,
"botToken": "xoxb-your-slack-bot-token",
"appToken": "xapp-your-app-token"
}
}
}
{
"gateway": {
"mode": "local",
"port": 18789,
"bind": "loopback",
"auth": {
"mode": "token",
"token": "your-secure-random-token-here"
}
}
}
{
"gateway": {
"mode": "lan",
"port": 18789,
"bind": "lan",
"auth": {
"mode": "token",
"token": "your-secure-random-token-here"
}
}
}
{
"security": {
"rateLimit": {
"enabled": true,
"requests": 100,
"windowMs": 3600000
}
}
}
{
"skills": {
"enabled": true,
"allowUnsafe": false,
"maxExecutionTime": 30000,
"maxConcurrent": 5
}
}
{
"security": {
"pairingRequired": true,
"autoApprove": false
}
}
OpenClaw uses SQLite with hybrid search for persistent memory:
{
"memory": {
"enabled": true,
"path": "~/.openclaw/memory"
}
}
Memory files are stored per-agent:
~/.openclaw/memory/<agentId>.sqlite
For enhanced security, OpenClaw supports running sessions in Docker sandboxes:
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all"
}
}
}
}
Sandbox mode provides Docker-isolated tool execution. See official sandbox docs for detailed configuration options.
{
"agents": {
"defaults": {
"sandbox": {
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"workdir": "/workspace",
"readOnlyRoot": true,
"tmpfs": ["/tmp", "/var/tmp", "/run"],
"network": "none",
"user": "1000:1000",
"capDrop": ["ALL"],
"pidsLimit": 256,
"memory": "1g",
"memorySwap": "2g",
"cpus": 1,
"ulimits": {
"nofile": { "soft": 1024, "hard": 2048 },
"nproc": 256
}
},
"scope": "agent",
"prune": {
"idleHours": 24,
"maxAgeDays": 7
}
}
}
}
}
Important: Allowing the browser tool in sandbox breaks isolation as the browser runs on the host.
OpenClaw provides CLI commands for managing sandbox containers:
| Command | Description |
|---|---|
openclaw sandbox explain |
Inspect effective sandbox mode, scope, workspace access, and tool policy |
openclaw sandbox explain --session agent:main:main |
Explain sandbox for specific session |
openclaw sandbox explain --agent work |
Explain sandbox for specific agent |
openclaw sandbox explain --json |
Output in JSON format |
openclaw sandbox list |
List all sandbox containers with status |
openclaw sandbox list --browser |
List only browser containers |
openclaw sandbox list --json |
List containers in JSON format |
openclaw sandbox recreate --all |
Recreate all sandbox containers |
openclaw sandbox recreate --session main |
Recreate sandbox for specific session |
openclaw sandbox recreate --agent mybot |
Recreate sandbox for specific agent |
openclaw sandbox recreate --browser |
Recreate only browser containers |
openclaw sandbox recreate --all --force |
Force recreate without confirmation |
When to recreate sandboxes:
openclaw.jsonsetupCommand for an agentTip: Prefer openclaw sandbox recreate over manual docker rm. It uses the Gateway’s container naming and avoids mismatches.
Control how OpenClaw handles direct messages from unknown senders:
{
"channels": {
"whatsapp": {
"allowFrom": ["+15555550123"],
"groups": { "*": { "requireMention": true } }
}
},
"messages": {
"groupChat": {
"mentionPatterns": ["@openclaw"]
}
}
}
DM Policy options (dmPolicy):
pairing (default): Unknown senders receive a pairing code and must be approved. Codes expire after 1 hour. Pending requests capped at 3 per channel by default.allowlist: Unknown senders are blocked (no pairing handshake)open: Public inbound DMs allowed (requires explicit opt-in with "*" in allowFrom)disabled: Ignore inbound DMs entirelyAudit your configuration: Run openclaw doctor to surface risky/misconfigured DM policies.
Pairing management commands:
openclaw pairing list <channel> # List pending pairing requests
openclaw pairing approve <channel> <code> # Approve a pairing request
# Stop gateway
openclaw gateway stop
# Backup entire configuration directory
tar -czf openclaw-backup-$(date +%Y%m%d_%H%M%S).tar.gz ~/.openclaw
# Stop gateway
openclaw gateway stop
# Extract backup
tar -xzf openclaw-backup-YYYYMMDD_HHMMSS.tar.gz -C ~/
# Restart gateway
openclaw gateway start
~/.openclaw/openclaw.json - Main configuration~/.openclaw/memory/ - Agent memory databases~/.openclaw/workspace/ - Agent workspace files~/.openclaw/skills/ - Custom skills (if any)| Command | Description |
|---|---|
openclaw configure |
Reconfigure settings via wizard |
openclaw gateway status |
Check gateway status |
openclaw gateway restart |
Restart gateway |
openclaw logs |
View gateway logs |
openclaw dashboard |
Open Web UI |
openclaw devices list |
List pending device pairings |
openclaw devices approve <id> |
Approve a device pairing |
openclaw plugins list |
List installed plugins |
openclaw doctor |
Run health checks and security audit - surfaces risky/misconfigured DM policies, network exposure |
openclaw pairing approve <channel> <code> |
Approve DM pairing from unknown sender |
openclaw sandbox explain |
Inspect sandbox configuration |
openclaw sandbox list |
List sandbox containers |
openclaw sandbox recreate --all |
Recreate all sandbox containers |
Every deployment is unique. We provide consulting for:
Get personalized assistance: office@linux-server-admin.com | Contact Page