.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw is configured entirely through a single JSON5 file at ~/.openclaw/openclaw.json and a CLI that has well over 100 subcommands. Neither is fully documented in one place. The official CLI reference lists the command tree; the config reference explains individual fields; but the practical patterns that connect them, the gotchas around schema strictness, hot-reload behavior, and config hierarchy, live in GitHub issues, community runbooks, and production post-mortems.
This guide covers both comprehensively. It starts with the config file: format, structure, every major section with working examples. Then the CLI: organized by workflow rather than alphabetical order, so you can find what you need for gateway management, channel setup, diagnostics, and automation. It ends with environment variables, the resolution order that governs them, and how to manage config safely under version control.
The openclaw.json config file
File format, location and validation rules
The config file is JSON5, not plain JSON. This means comments (// like this), trailing commas, and unquoted keys are all valid. The file lives at ~/.openclaw/openclaw.json by default. You can override the location with the OPENCLAW_CONFIG_PATH environment variable or the --profile <name> CLI flag, which isolates all state under a separate directory, useful for testing or running multiple isolated instances.
Schema validation is enforced by Zod at startup. Unknown keys cause the Gateway to refuse to start. There is no warning mode, no graceful degradation: if you add a key that doesn't exist in the schema, the Gateway won't launch and the error message will point you to the bad key. This is the single most important thing to know before editing the file manually. Safe editing workflow:
# 1. Back up first — always
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# 2. Edit the file
# 3. Validate JSON5 syntax
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 4. Validate schema and fix any issues
openclaw doctor --fixThe Gateway watches the file for changes and hot-reloads most settings without a restart. The word "most" matters — see the hot-reload section below for exactly which changes require a restart and which don't, because silently failing hot reloads are a common source of confusion in production setups.
Top-level config structure
A complete overview of every top-level section:
{
// Written by the wizard — don't edit manually
meta: { lastTouchedVersion: "...", lastTouchedAt: "..." },
gateway: { ... }, // Port, bind address, auth token
update: { channel: "stable" }, // stable | beta | dev
env: { shellEnv: { enabled: true }, vars: { KEY: "value" } },
agents: { defaults: { ... }, list: [ ... ] }, // Agent config + overrides
models: { mode: "merge", providers: { ... } }, // LLM providers
auth: { profiles: { ... }, order: { ... } }, // Provider failover
channels: { telegram: { ... }, discord: { ... } }, // Messaging channels
session: { dmScope: "per-channel-peer", reset: { ... } },
bindings: [ { agentId: "...", match: { ... } } ], // Multi-agent routing
cron: { enabled: true, maxConcurrentRuns: 2 },
tools: { web: { search: { provider: "brave", apiKey: "..." } } },
sandbox: { mode: "non-main", docker: { ... } },
logging: { level: "info", consoleLevel: "warn" },
skills: { install: { nodeManager: "pnpm" } },
}Gateway section
Controls how the Gateway process binds, authenticates, and reloads:
gateway: {
port: 18789,
mode: "local", // local | cloud
bind: "loopback", // loopback = 127.0.0.1 only (recommended)
// all = 0.0.0.0 (requires auth token)
auth: {
mode: "token",
token: "your-generated-token",
allowTailscale: true, // Tailscale IPs bypass token check
},
controlUi: {
enabled: true,
dangerouslyDisableDeviceAuth: false, // never true on shared hosts
},
reload: "hybrid", // hot | hybrid | restart
}Always use bind: "loopback" on VPS deployments. Setting bind: "all" without a strong auth token exposes the gateway to the internet. Exposed OpenClaw gateways found on public IPs have leaked API keys, OAuth tokens, and session histories. The Gateway will refuse to bind to non-loopback addresses without an auth token. See the VPS security guide for reverse proxy setup.
The reload field controls hot-reload behavior. "hybrid" applies changes live where possible and restarts only where required. gateway.reload and gateway.remote are the two fields that do not trigger a reload when changed — if you change either of these, restart the Gateway manually.
Agents section: Defaults and per-agent overrides
The agents section uses a defaults-with-overrides pattern. agents.defaults sets the baseline for every agent. Each entry in agents.list can override specific fields. The Gateway merges them at runtime: agent-specific config wins where it's present, defaults fill everything else.
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: [
"openai/gpt-5-mini",
"openrouter/google/gemini-3-flash-preview",
],
},
// Alias shortcuts used with the :model slash command
models: {
"anthropic/claude-haiku-4-5": { alias: "haiku" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"anthropic/claude-opus-4-6": { alias: "opus" },
},
maxConcurrent: 4,
// Context pruning: trims old tool results before each LLM call
contextPruning: {
mode: "cache-ttl", // off | cache-ttl
ttl: "45m",
keepLastAssistants: 2,
minPrunableToolChars: 12000,
softTrim: { maxChars: 2500, headChars: 900, tailChars: 900 },
hardClear: { enabled: true, placeholder: "[Old tool result cleared]" },
tools: { deny: ["browser", "canvas"] },
},
// Compaction: summarizes full history when context window fills
compaction: {
mode: "safeguard", // default | safeguard
reserveTokensFloor: 12000,
identifierPolicy: "strict",
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
systemPrompt: "Session nearing compaction.",
},
},
// Heartbeat
heartbeat: {
every: "30m",
mode: "next-heartbeat",
},
},
list: [
{ id: "main", default: true },
{
id: "work",
workspace: "~/work-agent",
model: { primary: "anthropic/claude-opus-4-6" },
lane: "work-lane",
laneConcurrency: 4,
},
],
}A critical constraint: several fields only work at the agents.defaults level and are silently ignored when set per-agent. Compaction settings, browser profile defaults, and thinking level overrides fall into this category. The Gateway doesn't warn you — the hot reload just doesn't execute. openclaw doctor --fix finds and removes these invalid per-agent keys. Always run it after editing agent-specific config.
ContextPruning vs compaction: Explained
contextPruning runs before each LLM call. It inspects the in-memory context and trims old tool results that exceed the TTL or size threshold. It does not touch the session file on disk, only what gets sent to the model. Without this, sessions running many tool calls accumulate enormous tool result payloads in context. This is the root cause of the pattern documented in GitHub issue #2254: 35 messages produced a 2.9MB session file and a 208,467-token context that silently stopped responding when it exceeded the model's 200k limit. Enabling contextPruning with mode: "cache-ttl" prevents this.
compaction runs when the context window approaches its limit. The Gateway summarizes conversation history, optionally writes notes to the daily memory file first via memoryFlush, then replaces the full history with the summary. The "safeguard" mode does chunked summarization for very long histories rather than trying to summarize everything in one LLM call. Both should be enabled in production — older configs may not have contextPruning at all since it became default later.
Models section
models: {
mode: "merge", // merge = combine provider lists; replace = replace defaults
providers: {
anthropic: {
apiKey: "${ANTHROPIC_API_KEY}",
},
openai: {
apiKey: "${OPENAI_API_KEY}",
},
// LM Studio (OpenAI-compatible local server)
"lmstudio": {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "lmstudio/qwen2.5-coder-7b",
name: "Qwen 2.5 Coder 7B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32768,
maxTokens: 8000,
},
],
},
// Ollama
ollama: {
baseUrl: "http://localhost:11434",
apiKey: "ollama-local",
api: "openai-completions",
models: [ ... ],
},
},
}The api field controls which request format is used. "openai-responses" works for most OpenAI-compatible local servers; "openai-completions" for Ollama; "anthropic" for the Anthropic API. If a model doesn't support tool calling, set reasoning: false and don't use it as a primary agent model — OpenClaw's tool system requires function calling support.
Auth section: Provider failover profiles
Multiple auth profiles per provider enable automatic failover on rate limits. Sessions stay pinned to one profile (for cache warmth) and reset on /new or compaction:
auth: {
profiles: {
"anthropic:subscription": { mode: "oauth", email: "[email protected]" },
"anthropic:api": { mode: "api_key", apiKey: "${ANTHROPIC_API_KEY}" },
"openai:default": { mode: "api_key", apiKey: "${OPENAI_API_KEY}" },
},
order: {
anthropic: ["anthropic:subscription", "anthropic:api"],
openai: ["openai:default"],
},
}When a profile hits a rate limit or auth failure, OpenClaw tries the next profile in the list for that provider. If all profiles for a provider fail, it falls through to the next model in agents.defaults.model.fallbacks. Configure cross-provider fallbacks (Anthropic → OpenAI, not Anthropic → Anthropic) to avoid the known issue where one model hitting limits marks the entire provider as in cooldown.
Session section
session: {
dmScope: "per-channel-peer",
// Options:
// "main" — all DMs share one session (single-user default)
// "per-peer" — isolate by sender ID across all channels
// "per-channel-peer" — isolate by sender + channel (recommended for multi-user)
// "per-account-channel-peer" — most granular
threadBindings: {
enabled: true,
idleHours: 24, // auto-unbind thread after this many idle hours
maxAgeHours: 0, // 0 = no max age
},
reset: {
mode: "daily", // none | daily | idle
atHour: 4, // UTC hour for daily reset
idleMinutes: 120, // for idle mode
},
identityLinks: {
// Link one user's identities across channels
alice: ["telegram:123456", "discord:987654"],
},
}Set dmScope: "per-channel-peer" for any setup where multiple people can DM your agent. With the default "main", all users share a single session, meaning Alice's private conversation context is visible to Bob. This is a data leak, not just a preference issue. See the privacy and compliance guide.
sandbox section
sandbox: {
mode: "non-main", // off | all | non-main
scope: "session",
docker: {
image: "openclaw-sandbox:bookworm-slim",
network: "none", // no outbound network from sandbox
readOnlyRoot: true,
cpus: "1",
memoryMb: 512,
},
}"non-main" runs subagents and cron jobs inside isolated Docker containers while keeping your main DM session running on the host. "all" sandboxes everything. Requires Docker CLI inside the gateway image (OPENCLAW_INSTALL_DOCKER_CLI=1) and Docker socket access.
Hot reload: what applies live and what requires a restart
Settings that require a Gateway restart:
gateway.portandgateway.bind(can't rebind a live socket)gateway.reloadandgateway.remote(by design — these don't trigger reloads)- Sandbox docker image or network config
- Plugin installation or removal
Settings that hot-apply without restart: model and fallback changes, agent config changes, channel policies (dmPolicy, allowFrom), cron jobs, heartbeat intervals, tool config, and most session settings.
CLI reference
Setup and onboarding
# Interactive setup wizard
openclaw onboard
# Setup + install daemon in one step (most common first-run command)
openclaw onboard --install-daemon
# Re-run specific setup steps
openclaw configure
# Non-interactive (Docker, CI)
openclaw onboard --non-interactive
# Reset config only (preserves sessions and credentials)
openclaw reset --scope config
# Reset config + credentials + sessions (keeps workspace)
openclaw reset --scope config+creds+sessions
# Full nuclear reset (includes workspace)
openclaw reset --scope fullDoctor and diagnostics
openclaw doctor is the most useful single command in the whole CLI. Run it after any config change, after any upgrade, and whenever the gateway behaves unexpectedly.
# Basic health check (read-only, safe any time)
openclaw doctor
# Health check + auto-fix
openclaw doctor --fix
# Deep scan (more thorough, slower)
openclaw doctor --deep --yes
# Non-interactive (for scripts)
openclaw doctor --non-interactive
# Full status dump
openclaw status --all --deep
# Status as JSON
openclaw status --json
# Direct gateway health probe (works even if daemon is down)
openclaw health --json --verbose
# Security audit
openclaw security audit
openclaw security audit --fix
# Check for credential leaks
openclaw secrets audit --checkGateway management
# Run in foreground (debugging)
openclaw gateway run
# Run on a non-default port
openclaw gateway run --port 19000 --bind loopback
# Force-kill any process on the port, then start fresh
openclaw gateway run --force
# Daemon control (requires daemon to be installed)
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status
# Install/manage daemon
openclaw daemon install
openclaw daemon install --user # user-level systemd service
openclaw daemon start | stop | restart | status | logs | uninstall
# Open Control UI in browser
openclaw dashboard
# Remote terminal UI (connect to a remote gateway)
openclaw tui --url https://example.com --token YOUR_TOKENConfig management
Prefer openclaw config over direct file edits. CLI writes go through the same JSON5 parser and schema validation, so they can't introduce unknown keys.
# Get a specific value
openclaw config get agents.defaults.model.primary
openclaw config get gateway.port
# Get everything (pretty-printed)
openclaw config get
# Set a value
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.defaults.maxConcurrent 8
openclaw config set gateway.bind "loopback"
# Unset (remove) a key
openclaw config unset tools.web.search.apiKey
openclaw config unset agents.defaults.heartbeatChannel management
# List channels
openclaw channels list
# Status check (connection health)
openclaw channels status
openclaw channels status --probe --all # runs extra connectivity checks
# Channel-specific logs
openclaw channels logs --channel telegram
openclaw channels logs --channel discord --limit 100
# Add a channel (interactive wizard)
openclaw channels add --channel telegram
openclaw channels add --channel discord
# Add non-interactively
openclaw channels add --channel telegram \
--account main \
--name "My Bot" \
--token "$TELEGRAM_BOT_TOKEN"
# WhatsApp and OAuth login (QR scan / browser flow)
openclaw channels login
openclaw channels login whatsapp
# Approve pairing code from a new DM sender
openclaw pairing approve telegram CODE123
# Remove a channel (disables by default)
openclaw channels remove --channel telegram
openclaw channels remove --channel discord --delete # also removes config entryLogs
# Tail live logs (colorized in TTY)
openclaw logs --follow
# Output as JSON (one event per line, for piping)
openclaw logs --json
# Limit output lines
openclaw logs --limit 200
# Filter by log level
openclaw logs --level warn
# Channel-specific logs
openclaw channels logs --channel whatsappModel management
# List configured models
openclaw models list
openclaw models list --all # includes full catalog
# Check model status and auth
openclaw models status
openclaw models status --probe # test connectivity per provider
# Change primary model
openclaw models set anthropic/claude-sonnet-4-5
# Set image model (for vision inputs)
openclaw models set-image openai/gpt-4o
# Manage aliases
openclaw models aliases list
openclaw models aliases add fast anthropic/claude-haiku-4-5
# Manage fallbacks
openclaw models fallbacks list
openclaw models fallbacks add openai/gpt-5-mini
openclaw models fallbacks clear
# Auth management
openclaw models auth add
openclaw models auth setup-token
openclaw models auth order get
openclaw models auth order set anthropic "anthropic:subscription,anthropic:api"Agent management
# List agents
openclaw agents list
# Add an agent (interactive)
openclaw agents add
# Add non-interactively
openclaw agents add --id "work" --workspace ~/work-agent --non-interactive
# List routing bindings
openclaw agents acp list
# Add binding (route a channel/group to a specific agent)
openclaw agents acp add --agent work --channel telegram --group-id -1001234567
# Remove binding
openclaw agents acp remove --agent work --channel telegram
# Run one agent turn directly (bypasses channel)
openclaw agent --message "What needs my attention today?"
# Delete an agent
openclaw agents delete --id workMemory management
# Memory index status
openclaw memory status
# Re-index all workspace memory files
openclaw memory index --all
# Search memory
openclaw memory search --query "deployment notes"
# Send a message to a specific session
openclaw message agent --session "session-key" --message "Status update?"Cron management
# List all cron jobs
openclaw cron list --all
# Show cron job status
openclaw cron status
# Add a cron job (one-time at specific time)
openclaw cron add \
--name "morning-brief" \
--at "2026-04-01T09:00:00Z" \
--message "Summarize emails and calendar for today"
# Add recurring (interval in milliseconds)
openclaw cron add \
--name "hourly-check" \
--every 3600000 \
--message "Check for priority items"
# Add with cron expression
openclaw cron add \
--name "weekly-report" \
--cron "0 9 * * 1" \
--message "Generate weekly summary"
# Run a job immediately (ignoring schedule)
openclaw cron run --id morning-brief
# Enable/disable
openclaw cron enable --id morning-brief
openclaw cron disable --id morning-brief
# View run history
openclaw cron runs --id morning-brief --limit 10
# Edit an existing job
openclaw cron edit --id morning-brief
# Remove a job
openclaw cron rm --id morning-briefSkills and plugins
# List installed skills
openclaw skills list
# Show skill details
openclaw skills info web-search
# Check eligibility (verify requirements are met)
openclaw skills check --eligible
# Plugin management
openclaw plugins list
openclaw plugins info my-plugin
openclaw plugins install my-plugin
openclaw plugins enable my-plugin
openclaw plugins disable my-plugin
openclaw plugins doctor # report plugin load errorsSessions and devices
# List conversation sessions
openclaw sessions --json
# Clean up old session files
openclaw sessions cleanup
# Device management
openclaw devices list
openclaw devices node run --id DEVICE_ID
# Approvals (for tools that require human confirmation)
openclaw approvals get
openclaw approvals set --policy "auto"
openclaw approvals allowlist add "exec"Update management
# Update to latest stable
openclaw update
# Switch update channel
openclaw update --channel stable # stable | beta | dev
# Migrate config after a major version upgrade
openclaw migrateGlobal flags
These flags work with any command:
--dev # Use dev environment (separate state directory)
--profile <name> # Use a named profile (separate state directory)
--json # Output as JSON
--verbose # Verbose logging
--no-color # Disable ANSI color output
--log-level debug # Set log level (debug | info | warn | error)Environment variables
Resolution order
OpenClaw resolves environment variables in this order, with earlier sources winning. Once a variable is set, later sources don't override it:
- Process environment (variables already in the shell when you start the Gateway)
.envin the current working directory (if present when the Gateway starts)~/.openclaw/.env(global fallback)env.varsin openclaw.json (inline config vars, non-overriding)
The env.vars block in config is for setting defaults that don't override what's already in the environment. Use it for non-sensitive config values. Use ~/.openclaw/.env or process environment for credentials.
Key environment variables
# Config paths
OPENCLAW_HOME=~/.openclaw # Base directory
OPENCLAW_CONFIG_PATH=/path/to/openclaw.json # Override config file location
# Logging
OPENCLAW_LOG_LEVEL=debug # debug | info | warn | error
OPENCLAW_LOG_FORMAT=json # for structured log output
# Model API keys (referenced via ${VAR} in config)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
# Gateway
OPENCLAW_GATEWAY_TOKEN=your-token # Overrides gateway.auth.token in configVariable substitution in config
Any string value in openclaw.json can reference environment variables with ${VAR_NAME}. This is evaluated at Gateway startup. To use a literal dollar sign, escape it: $${NOT_A_VAR}.
models: {
providers: {
anthropic: {
apiKey: "${ANTHROPIC_API_KEY}",
},
},
}
channels: {
telegram: {
botToken: "${TELEGRAM_BOT_TOKEN}",
},
}For the most secure handling of credentials, use the SecretRef system rather than env vars directly. See the secrets management guide for how to reference Docker secrets, HashiCorp Vault, and 1Password from config.
Shell environment integration
The env.shellEnv.enabled: true setting runs your login shell and imports environment from it. This is useful when you have API keys set in your shell profile (~/.bashrc, ~/.zshrc) that you want OpenClaw to pick up without duplicating them in ~/.openclaw/.env. If your shell startup is slow or heavy, set env.shellEnv.timeoutMs to cap how long the import waits.
Managing config under version control
The config file at ~/.openclaw/openclaw.json contains both infrastructure config (safe to version-control) and credentials (never safe to commit). The simplest approach: version-control a sanitized template with all sensitive values replaced by environment variable references, and keep actual credentials only in ~/.openclaw/.env or your secrets manager.
What to version-control and what to exclude
A minimal .gitignore for an OpenClaw config repo:
# Credentials
.env
*.env
credentials/
# Sessions (large, ephemeral, contain private conversation content)
sessions/
*.jsonl
# Memory files (personal content)
workspace/memory/
workspace/MEMORY.md
# Cron job state (runtime state, not config)
cron/runs/
# Runtime state
*.lock
tmp/What you can safely version-control: the structure of openclaw.json with ${VAR} references in place of actual keys, workspace skill files, AGENTS.md and SOUL.md (if they don't contain personal info), and cron job definitions in cron/jobs.json.
Pre-commit credential scanning
Add truffleHog or gitleaks as a pre-commit hook to catch any credential accidentally added to config files before they're committed. A quick manual check:
# Scan for leaked keys before committing
grep -rE "sk-ant-|sk-or-|sk-[A-Za-z0-9]{40}" ~/.openclaw/openclaw.json
# Should find nothing; all key references should be ${VAR} syntaxConfig drift after upgrades
Each OpenClaw version may add or rename config keys, and the schema can change between releases. After upgrading, always run openclaw doctor --fix to remove stale keys and add any required new fields. Failing to do this is the most common cause of settings that appear to be configured but don't take effect — old keys that were silently dropped from the schema are ignored rather than errored, so the gateway starts but the setting does nothing. See the upgrade and maintenance guide for a complete upgrade checklist.
