openclaw.json Explained: Every Config Field and What It Does
One file controls everything about how your OpenClaw agent runs: openclaw.json. Whether you are deploying your first agent or tuning a production system for a VPS, every behavior, permission, message channel, scheduled job, and LLM provider lives in this single configuration file. Understanding what each field does is the difference between an agent that works and one that silently fails at the worst possible moment.
This guide walks through every top-level section of openclaw.json: model, channels, plugins, security, crons, nodes, and ui. Each section includes annotated examples so you can copy, paste, and adapt them to your own setup. By the end, you will know exactly how to configure an OpenClaw agent for any environment, from a development laptop to a headless production server.
Where openclaw.json Lives and How OpenClaw Reads It
openclaw.json lives in the OpenClaw installation directory, not in your agent’s workspace. When the gateway daemon starts, it reads openclaw.json first. The file determines which plugins load, which channels the agent can speak on, who is allowed to talk to it, what LLM powers its reasoning, and what automation runs on a schedule. After parsing the config, OpenClaw loads workspace files such as SOUL.md, MEMORY.md, AGENTS.md, and HEARTBEAT.md and injects them as session context.
Here is a minimal skeleton of what a complete openclaw.json looks like:
{
"model": "anthropic/claude-sonnet-4-6",
"channels": {
"slack": {
"token": "xoxb-your-bot-token",
"appToken": "xapp-your-app-token",
"defaultChannel": "C1234567890"
}
},
"plugins": {
"memory": {
"config": {
"path": "/home/node/.openclaw/memory"
}
}
},
"security": {
"exec": {
"security": "allowlist"
}
},
"crons": [],
"nodes": {},
"ui": {
"port": 3000,
"host": "127.0.0.1"
}
}
The model Field: Choosing Your Default LLM
The model field is the single string that defines which large language model powers your agent’s reasoning. It uses the format provider/model-name. OpenClaw supports a growing list of providers: Anthropic, OpenAI, Google, DeepSeek, Mistral, Groq, Together, and more. The model you choose directly affects response quality, latency, and cost, especially in production deployments where you may run thousands of conversations per day.
Provider Alias Shorthand
OpenClaw provides shorthand aliases for frequently used models so you do not have to type the full canonical name every time:
- ds-v3 maps to deepseek/deepseek-chat
- ds-reason maps to deepseek/deepseek-reasoner
- sonnet maps to anthropic/claude-sonnet-4-6
- haiku maps to anthropic/claude-haiku-3-5
- opus maps to anthropic/claude-opus-4-5
- gpt4o maps to openai/gpt-4o
- gpt4o-mini maps to openai/gpt-4o-mini
- gemini maps to google/gemini-2-5-pro
Examples
{
"model": "sonnet"
}
is equivalent to:
{
"model": "anthropic/claude-sonnet-4-6"
}
Both resolve to Claude Sonnet 4. You can also use an environment variable to override the model at runtime without touching the config file:
export OPENCLAW_MODEL="deepseek/deepseek-reasoner"
The channels Section: Every Messaging Platform
The channels section is where you configure the messaging platforms your agent listens on and responds to. Each platform gets its own key under channels, with provider-specific configuration fields. OpenClaw supports Slack, Telegram, Discord, Signal, WhatsApp, Matrix, and custom webhooks.
A channel entry typically needs authentication tokens, signing secrets, webhook URLs, and a default destination channel where the agent sends messages that are not replies to a specific user.
Slack (Socket Mode)
{
"channels": {
"slack": {
"token": "xoxb-1234567890-abc123def456",
"appToken": "xapp-1-ABC123DEF456",
"signingSecret": "abc123secret",
"defaultChannel": "C0123456789"
}
}
}
Slack in Socket Mode requires both a bot token (token) and an app-level token (appToken). The signingSecret verifies request authenticity. The defaultChannel is where the agent sends messages that are not initiated by a user interaction.
Telegram
{
"channels": {
"telegram": {
"token": "1234567890:AAGHxabc123def456",
"defaultChannel": "-1001234567890"
}
}
}
Telegram needs a bot token from BotFather. The defaultChannel can be a chat ID, group ID, or channel ID.
Discord
{
"channels": {
"discord": {
"token": "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.abc123.def456",
"defaultChannel": "1234567890123456789"
}
}
}
Discord uses a single bot token. The defaultChannel is the snowflake ID of the channel where the agent posts.
Signal
{
"channels": {
"signal": {
"number": "+15551234567",
"defaultChannel": "+15559876543"
}
}
}
Signal requires a registered phone number. The defaultChannel can be another phone number or a group ID.
The plugins Section: Enabling Agent Capabilities
Plugins extend what your OpenClaw agent can do beyond conversation. Each plugin has a name and an optional config object. The config varies by plugin but typically includes API keys, storage paths, and behavior flags.
Memory Plugin (LanceDB)
{
"plugins": {
"memory": {
"config": {
"path": "/home/node/.openclaw/memory",
"dimensions": 1536
}
}
}
}
The memory plugin uses LanceDB for vector storage. The path is where the vector database is stored on disk. dimensions should match the embedding model’s output dimensions. Without this plugin, the agent has no long-term recall between sessions.
Web Search Plugin
{
"plugins": {
"webSearch": {
"config": {
"provider": "brave",
"apiKey": "YOUR_BRAVE_API_KEY"
}
}
}
}
The web search plugin gives the agent real-time internet access. Supported providers include Brave Search (brave) and Tavily (tavily). This plugin is essential for any agent that needs to answer current events or look up live data.
Browser Plugin
{
"plugins": {
"browser": {
"config": {
"headless": true,
"viewport": {
"width": 1280,
"height": 720
}
}
}
}
}
The browser plugin enables the agent to navigate web pages, fill forms, take screenshots, and interact with JavaScript-rendered sites. It runs a headless Chromium instance. This is a powerful capability but comes with significant resource overhead, so it should only be enabled when needed.
The security Section: Who Can Talk to Your Agent
The security section controls access to your agent. Misconfiguring this section can leave your agent exposed to unauthorized users or, conversely, lock you out entirely. There are three main areas:
allowedUsers
{
"security": {
"allowedUsers": ["U0123456789", "U9876543210"]
}
}
The allowedUsers array contains user IDs (platform-specific) who are permitted to interact with the agent. Users not in this list will be ignored. When deploying on a public server, keeping this list tight is your first line of defense.
requireAuth
{
"security": {
"requireAuth": true
}
}
When requireAuth is set to true, the agent enforces authentication on channel messages. The specific auth mechanism depends on the channel provider. For internal or team deployments, you may set this to false and rely on allowedUsers instead.
exec.security Policy
{
"security": {
"exec": {
"security": "allowlist"
}
}
}
The exec.security policy determines what shell commands the agent can run. Three modes exist:
- deny — No shell commands allowed. Safest option. Use when the agent only needs conversation and plugin capabilities.
- allowlist — Only whitelisted commands are permitted. Recommended for production. You specify which commands the agent can run.
- full — Full shell access. Use only in development or trusted environments. Granting full exec access means the agent can read, write, and execute anything on the host system.
The crons Section: Scheduled Automation
The crons section is an array of scheduled jobs that trigger the agent at specific times. Each cron entry has an id, a schedule (standard cron expression), a message that is sent to the agent as a prompt, and a delivery object that tells OpenClaw where to send the agent’s response.
Basic Cron Example
{
"crons": [
{
"id": "morning-briefing",
"schedule": "0 7 * * 1-5",
"message": "Give me a morning briefing: today's date, weather, and top reminders.",
"delivery": {
"channel": "C0123456789",
"to": "U0123456789",
"mode": "direct"
}
}
]
}
Delivery Object Fields
The delivery object defines where and how the agent’s cron response is sent:
- channel — The platform channel or room where the message is delivered.
- to — A specific user ID or group to mention or target.
- mode — Delivery mode: direct sends a direct message, channel posts to the channel.
Multiple Cron Jobs
{
"crons": [
{
"id": "morning-news",
"schedule": "0 6 * * *",
"message": "Summarize today's top AI news from trusted sources.",
"delivery": {
"channel": "C0123456789",
"mode": "channel"
}
},
{
"id": "weekly-report",
"schedule": "0 9 * * 1",
"message": "Generate the weekly performance report for last week.",
"delivery": {
"channel": "C0123456789",
"to": "U0123456789",
"mode": "direct"
}
}
]
}
Each cron job runs independently. The agent boots up, processes the message, and delivers its response to the specified destination. For a deeper dive into cron automation, see this companion guide to OpenClaw cron jobs.
The nodes Section: Remote Companion App Pairing
The nodes section configures remote companion app connections. OpenClaw nodes allow you to pair the gateway daemon with the OpenClaw mobile app (iOS and Android), effectively giving you a remote control and notification surface for your agent from anywhere.
Node Configuration
{
"nodes": {
"node-phone-1": {
"name": "Ghost's iPhone",
"publicUrl": "https://your-server.example.com",
"token": "node-specific-auth-token"
}
}
}
Each node has a unique ID (the key), a human-readable name, a publicUrl that points to the gateway server reachable from the companion app, and an authentication token. Nodes are essential for mobile pairing, push notifications, and remote monitoring.
The companion app connects to the gateway through the publicUrl. If your server is behind NAT or a firewall, you will need to ensure the gateway is reachable, either through a public IP, a reverse proxy, or a tunnel such as Tailscale.
The ui Section: Web Interface Settings
The ui section configures the web-based interface for your OpenClaw agent. This is useful for testing, monitoring logs, and interacting with the agent when you are away from your messaging platform of choice.
{
"ui": {
"port": 3000,
"host": "127.0.0.1",
"theme": "dark"
}
}
Key fields:
- port — The port the web interface listens on (default 3000).
- host — The bind address. Use 127.0.0.1 for local-only access or 0.0.0.0 to expose externally.
- theme — UI theme preference: dark or light.
openclaw.json vs. Workspace Files: The Critical Distinction
A common point of confusion is the difference between openclaw.json and workspace files. They serve completely different purposes and live in different directories.
openclaw.json is the system configuration file. It lives in the OpenClaw installation directory. It controls the agent’s infrastructure: which LLM to use, which channels to connect to, which plugins to load, who can access the agent, and what automation runs. It contains secrets such as API keys, bot tokens, and signing secrets. It should never be committed to a public repository.
Workspace files live in a separate workspace directory, typically /home/user/.openclaw/workspace/ or a custom path you specify. These files are loaded as session context and define the agent’s personality, instructions, and long-term memory:
- SOUL.md — Defines the agent’s identity, role, and behavioral guidelines.
- AGENTS.md — Operational protocols and session start routines.
- MEMORY.md — Persistent memory that the agent appends to across sessions.
- HEARTBEAT.md — Health check and uptime tracking for the agent process.
- IDENTITY.md and USER.md — Optional metadata about the agent’s persona and its human counterpart.
In short: openclaw.json configures how the agent runs. Workspace files configure who the agent is. If you change the model or add a channel, you edit openclaw.json. If you change the agent’s persona or add a new instruction, you edit the workspace files.
Environment Variable Overrides: The Secure Way to Deploy
Hardcoding API keys and bot tokens in openclaw.json works fine on your local machine, but it is a security risk in production. Every field that contains a secret can be set via an environment variable instead. When an environment variable is present, OpenClaw uses it over the value in the config file.
Available Environment Variables
# LLM model override
export OPENCLAW_MODEL="anthropic/claude-sonnet-4-6"
# Slack channel tokens
export OPENCLAW_SLACK_TOKEN="xoxb-your-bot-token"
export OPENCLAW_SLACK_APP_TOKEN="xapp-your-app-token"
export OPENCLAW_SLACK_SIGNING_SECRET="your-signing-secret"
# Telegram
export OPENCLAW_TELEGRAM_TOKEN="123456:ABCdef-token"
# Discord
export OPENCLAW_DISCORD_TOKEN="MTIzNDU2.token"
# Web search API keys
export OPENCLAW_WEBSEARCH_APIKEY="your-brave-or-tavily-key"
# Gateway binding
export OPENCLAW_GATEWAY_PORT="3000"
export OPENCLAW_GATEWAY_HOST="0.0.0.0"
The recommended pattern for VPS deployments is to keep openclaw.json in version control (without secrets) and supply the secrets through environment variables in your deployment system, whether that is Docker Compose, systemd, Kubernetes, or a process manager like PM2.
Security Warning: Never Commit This File
openclaw.json contains API keys, bot tokens, signing secrets, and potentially database paths that reveal your server’s filesystem layout. Committing this file to a public GitHub repository, even temporarily, exposes every connected service to compromise. An exposed Slack token can give an attacker full access to your workspace. An exposed Telegram token lets anyone send messages as your bot. An exposed exec security policy could give an attacker shell access to your server.
If you have already committed openclaw.json to a public repo:
- Revoke every token and API key in the file immediately.
- Rotate secrets for all affected services (Slack, Telegram, Discord, web search providers).
- Remove the file from git history using git filter-branch or BFG Repo-Cleaner.
- Add openclaw.json to your .gitignore to prevent future commits.
- Switch to environment variable overrides for all secrets.
A minimal .gitignore entry:
openclaw.json
Your agent’s workspace files, on the other hand, do not contain secrets and are generally safe to track in version control, as long as they do not include embedded credentials.
Sources
This guide is based on the official OpenClaw documentation and direct analysis of the OpenClaw configuration parser. The config structure, field naming, and default behaviors described here reflect OpenClaw as of April 2026.