openclaw-config-referenceOpenClaw configuration reference for openclaw.json. Use when asked about config, configuration, gateway settings, channel setup, agent config, session manage...
Install via ClawdBot CLI:
clawdbot install Yixn/openclaw-config-referenceBuilt by ClawHosters - managed OpenClaw hosting with 1-click deployment. If you'd rather skip the config headaches and have everything set up for you, check us out.
openclaw.json uses strict schema validation. Unknown keys cause the Gateway to refuse to start. Before editing config:
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bakcat ~/.openclaw/openclaw.json | python3 -m json.toolopenclaw doctor (or openclaw doctor --fix to auto-repair)If the Gateway won't start after a config change:
# Restore backup
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
# Or run doctor to auto-fix
openclaw doctor --fix
# Verify config is valid
openclaw config get| Property | Value |
|----------|-------|
| Path | ~/.openclaw/openclaw.json |
| Format | JSON5 (comments, trailing commas, unquoted keys allowed) |
| Validation | Strict - unknown keys = Gateway refuses to start |
| Watching | Gateway watches file for changes and hot-reloads |
| Method | Description |
|--------|-------------|
| Direct file edit | Edit ~/.openclaw/openclaw.json directly. Gateway detects changes. |
| CLI | openclaw config get/set/unset - safest method |
| Web UI | Control UI at http://127.0.0.1:18789 |
| Onboard wizard | openclaw onboard - guided initial setup |
openclaw config get # Show full config
openclaw config get gateway.port # Get specific value
openclaw config set gateway.port 19000 # Set a value
openclaw config unset gateway.auth.token # Remove a valueThe CLI validates before writing, making it the safest way to change config.
Split config across files:
{
"$include": "./channels-config.json",
gateway: { port: 18789 }
}The included file is merged into the main config.
The Gateway exposes config methods via RPC:
| Method | Description |
|--------|-------------|
| config.get | Read current config (or a specific path) |
| config.apply | Apply a full config object (replaces) |
| config.patch | Merge partial config (rate-limited: 3 calls per 60 seconds) |
config.patch is rate-limited to prevent accidental rapid-fire config changes that could destabilize the Gateway.
The Gateway watches openclaw.json and reloads on changes.
| Mode | Behavior |
|------|----------|
| hybrid | Smart: hot-reload where possible, restart where needed (default) |
| hot | Non-destructive in-place reload (keeps connections alive) |
| restart | Full process restart on any config change |
| off | Disable auto-reload entirely |
gateway: {
reload: "hybrid"
}What hot-applies (no restart needed):
What requires restart:
Manual reload via SIGUSR1:
pkill -SIGUSR1 -f gatewaySIGUSR1 is non-destructive: reloads config without dropping connections or sessions.
| Section | Purpose | Reference |
|---------|---------|-----------|
| gateway | Core process: port, bind, auth, reload, HTTP endpoints | gateway.md |
| commands | Messenger commands (e.g., /restart) | See below |
| agents | Multi-agent system: defaults, agent list, models | agents.md |
| channels | Messenger integrations (Telegram, WhatsApp, Discord, etc.) | channels.md |
| session | Session scoping, reset behavior | session.md |
| sandbox | Code execution isolation (Docker) | session.md |
| cron | Built-in job scheduler | session.md |
| hooks | Webhook receiver configuration | session.md |
| tools | Tool permissions, profiles, restrictions | tools.md |
| browser | Playwright browser integration | tools.md |
| skills | Skill loading, entries, installation | tools.md |
| models | LLM providers and model configuration | models-env.md |
| env | Environment variable injection | models-env.md |
commands: {
restart: true // Allow /restart command from messenger clients
}Security warning: Setting commands.config: true allows users to modify config from chat. Only enable for trusted single-user setups.
The smallest config that runs:
{
gateway: {
port: 18789
},
agents: {
list: [
{ agentId: "main", workspace: "~/.openclaw/workspace" }
]
}
}Everything else uses defaults.
{
gateway: {
mode: "local",
port: 18789,
bind: "loopback",
reload: "hybrid",
auth: { mode: "token", token: "change-me-please" },
http: { endpoints: { chatCompletions: { enabled: true } } }
},
commands: { restart: true },
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: { primary: "anthropic/claude-opus-4-6" },
heartbeat: { every: "30m" }
},
list: [
{ agentId: "main" },
{ agentId: "work", workspace: "~/.openclaw/workspace-work" }
]
},
channels: {
telegram: {
botToken: "...",
enabled: true,
dmPolicy: "pairing",
streamMode: "partial"
}
},
session: {
dmScope: "main",
reset: { mode: "daily", atHour: 4 }
},
cron: { enabled: true },
models: {
providers: {
"openrouter": {
baseUrl: "https://openrouter.ai/api/v1",
apiKey: "sk-or-...",
api: "openai-completions"
}
}
},
env: {
vars: { TZ: "America/New_York" },
shellEnv: true
}
}Before saving config changes:
lan (Gateway refuses to start without auth on lan)openclaw.json.bak)After saving:
openclaw config get returns without errorsopenclaw doctor shows no critical issuesFor detailed troubleshooting with examples and recovery procedures, see troubleshooting.md.
Quick list of things that will break your setup:
openclaw config set instead of manual editing when possible.gateway.bind: "lan" without auth - Gateway refuses to start for safety. Always set auth when binding to lan.commands.config: true - Lets anyone in chat modify your config. Only for trusted single-user.tools.elevated.enabled: true + open DM policy - Gives strangers admin access to your system.OPENCLAW_GATEWAY_TOKEN env var - If auth mode is token but no token is set in config or env.sandbox.mode: "all" without Docker - Sandbox requires Docker to be running.Each config section has a dedicated reference file with full schema documentation:
Generated Mar 1, 2026
A business deploys OpenClaw to handle customer inquiries across multiple messaging platforms like Telegram and WhatsApp. The configuration manages channel setups, agent models for consistent responses, and session handling to maintain conversation context, reducing manual support workload.
An organization uses OpenClaw as an internal assistant for employees to troubleshoot technical issues via Discord. Config includes secure authentication, tool permissions for system diagnostics, and cron jobs for automated maintenance alerts, improving IT efficiency.
A media agency configures OpenClaw to assist with content generation and scheduling across social media channels. It leverages browser tools for research, hooks for webhook integrations with CMS platforms, and sandbox isolation for safe code execution in creative tasks.
An educational institution sets up OpenClaw to provide personalized tutoring sessions via messaging apps. Configuration involves session management for student progress tracking, model adjustments for subject-specific responses, and environment variables for API keys to educational resources.
A fintech company implements OpenClaw to monitor market data and send alerts through configured channels. The setup includes cron jobs for periodic data fetching, secure gateway settings to protect sensitive information, and agent models tailored for financial analysis queries.
Offer OpenClaw as a managed hosting service with pre-configured setups for different industries. Revenue comes from monthly subscriptions that include automated deployment, configuration support, and regular updates, targeting businesses seeking hassle-free AI integration.
Provide expert services to tailor OpenClaw configurations for specific client needs, such as complex channel integrations or custom tool development. Revenue is generated through project-based fees and ongoing maintenance contracts, ideal for enterprises with unique requirements.
Develop and sell training programs and certifications for OpenClaw configuration and troubleshooting. Revenue streams include course fees, certification exams, and workshop materials, catering to IT professionals and developers looking to enhance their skills in AI agent management.
💬 Integration Tip
Use the CLI config commands for safe changes and enable hot reload in hybrid mode to minimize downtime during updates, ensuring smooth integration with existing systems.
Transform AI agents from task-followers into proactive partners that anticipate needs and continuously improve. Now with WAL Protocol, Working Buffer, Autonomous Crons, and battle-tested patterns. Part of the Hal Stack 🦞
Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawdhub CLI.
Clawdbot documentation expert with decision tree navigation, search scripts, doc fetching, version tracking, and config snippets for all Clawdbot features
Interact with Moltbook social network for AI agents. Post, reply, browse, and analyze engagement. Use when the user wants to engage with Moltbook, check their feed, reply to posts, or track their activity on the agent social network.
OpenClaw CLI wrapper — gateway, channels, models, agents, nodes, browser, memory, security, automation.
MoltGuard — runtime security plugin for OpenClaw agents by OpenGuardrails. Helps users install, register, activate, and check the status of MoltGuard. Use wh...