Introduction
All of OpenClaw's behavior is driven by a single configuration file — located by default at ~/.openclaw/openclaw.json. While other articles have introduced the configuration sections from a functional perspective, in day-to-day operations you often need a "field-level" quick reference. This article lists every valid field in openclaw.json in table format, noting the type, default value, and constraints for quick lookup when editing your configuration.
Top-Level Structure
The top level of openclaw.json consists of the following configuration sections:
{
"gateway": {},
"models": {},
"channels": {},
"agents": {},
"sessions": {},
"skills": {},
"persona": {},
"logging": {},
"security": {},
"advanced": {}
}
Each section is independent — you only need to fill in the parts you actually use, and the rest will use default values.
gateway Field Reference
The gateway is OpenClaw's HTTP entry point, responsible for receiving Webhook callbacks from all channels as well as Dashboard requests.
| Field | Type | Default | Description |
|---|---|---|---|
port |
number | 18789 |
Gateway listening port |
host |
string | "127.0.0.1" |
Listening address; set to "0.0.0.0" to accept external connections |
dashboardPassword |
string | "" |
Dashboard access password; leave empty for no authentication |
apiKey |
string | "" |
REST API authentication key |
timeout |
number | 120000 |
Request timeout in milliseconds |
maxBodySize |
string | "10mb" |
Maximum request body size |
cors.enabled |
boolean | true |
Whether to enable CORS |
cors.origins |
string[] | ["*"] |
List of allowed origin domains |
webhookBase |
string | "" |
Webhook base URL, used for automatic callback registration |
models Field Reference
Model configuration determines which AI backends OpenClaw connects to.
| Field | Type | Default | Description |
|---|---|---|---|
default |
string | "claude" |
Default model provider name |
providers.<name>.apiKey |
string | Required | Provider API key |
providers.<name>.model |
string | Required | Model identifier to use |
providers.<name>.maxTokens |
number | 4096 |
Maximum tokens per response |
providers.<name>.temperature |
number | 0.7 |
Temperature parameter, between 0-2 |
providers.<name>.baseUrl |
string | Provider-dependent | Custom API endpoint |
providers.<name>.headers |
object | {} |
Additional HTTP request headers |
routing.rules |
array | [] |
Model routing rules array |
routing.fallback |
string | Same as default |
Fallback model when no routing rule matches |
channels Field Reference
Channel configuration defines the instant messaging platforms OpenClaw connects to. Each channel type has shared fields and type-specific fields.
Common Channel Fields
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | false |
Whether this channel is enabled |
allowedUsers |
array | [] |
User allowlist; leave empty for no restrictions |
allowedGroups |
array | [] |
Group allowlist |
webhookPath |
string | Auto-generated | Custom Webhook path |
mediaSupport |
object | Channel default | Media type support toggles |
Telegram-Specific Fields
| Field | Type | Description |
|---|---|---|
token |
string | Bot Token |
parseMode |
string | Message parse mode: "Markdown" or "HTML" |
groupRules.triggerOnMention |
boolean | Whether to reply only when @mentioned |
WhatsApp-Specific Fields
| Field | Type | Description |
|---|---|---|
phoneNumber |
string | Bound phone number |
accessToken |
string | Business API access token |
verifyToken |
string | Webhook verification token |
Discord-Specific Fields
| Field | Type | Description |
|---|---|---|
token |
string | Bot Token |
allowedChannels |
string[] | List of allowed channel names or IDs for interaction |
agents Field Reference
Agent configuration defines multi-agent routing behavior.
| Field | Type | Default | Description |
|---|---|---|---|
default |
string | "default" |
Default Agent ID |
list[].id |
string | Required | Agent unique identifier |
list[].name |
string | Required | Agent display name |
list[].model |
string | Inherits global | Model used by this Agent |
list[].systemPrompt |
string | "" |
Agent-specific system prompt |
list[].skills |
string[] | [] |
List of skills available to this Agent |
list[].knowledgeBase |
string | "" |
Knowledge base directory path |
sessions Field Reference
Session configuration controls conversation history storage and management.
| Field | Type | Default | Description |
|---|---|---|---|
storageFormat |
string | "jsonl" |
Storage format; currently only JSONL is supported |
storagePath |
string | "~/.openclaw/agents/<agentId>/sessions/" |
Session file directory |
maxHistoryMessages |
number | 50 |
Maximum number of messages retained in context |
maxHistoryTokens |
number | 8000 |
Maximum number of tokens retained in context |
autoCompaction |
boolean | true |
Whether to auto-compact when context overflows |
compactionStrategy |
string | "summary" |
Compaction strategy: "summary" or "truncate" |
treeStructure |
boolean | true |
Whether to enable tree-structured sessions (supports branching) |
security Field Reference
| Field | Type | Default | Description |
|---|---|---|---|
rateLimit.enabled |
boolean | true |
Whether to enable rate limiting |
rateLimit.maxRequests |
number | 60 |
Maximum requests per window |
rateLimit.windowMs |
number | 60000 |
Window duration (milliseconds) |
ipWhitelist |
string[] | [] |
IP allowlist |
ipBlacklist |
string[] | [] |
IP blocklist |
tls.enabled |
boolean | false |
Whether to enable HTTPS |
tls.cert |
string | "" |
Certificate file path |
tls.key |
string | "" |
Private key file path |
logging Field Reference
| Field | Type | Default | Description |
|---|---|---|---|
level |
string | "info" |
Log level: debug, info, warn, error |
file |
string | "" |
Log file path; leave empty to output to terminal only |
maxSize |
string | "10m" |
Maximum size per log file |
maxFiles |
number | 5 |
Number of log files to retain |
format |
string | "text" |
Output format: "text" or "json" |
advanced Field Reference
| Field | Type | Default | Description |
|---|---|---|---|
workers |
number | 0 |
Number of worker threads; 0 for auto |
queueSize |
number | 100 |
Message queue size |
storage |
string | "sqlite" |
Data storage backend |
dbPath |
string | "~/.openclaw/data/openclaw.db" |
SQLite database path |
redis.url |
string | "" |
Redis connection URL |
redis.db |
number | 0 |
Redis database number |
pluginDir |
string | "~/.openclaw/plugins" |
Plugin directory |
Configuration Validation and Debugging
After modifying the configuration, be sure to validate using the built-in tools:
# Validate configuration file syntax and required fields
openclaw doctor
# Output the complete effective configuration (including defaults)
openclaw config --dump
The --dump option outputs all fields (including default values not explicitly set) to the terminal, helping you confirm the final effective configuration.
Summary
This article lists every configuration option in openclaw.json at the field level. For daily use, we recommend bookmarking this article as a quick reference. In most cases, you only need to focus on the three core sections — gateway, models, and channels — and leave the rest at their default values. For deeper understanding of a specific section, refer to the corresponding topic tutorial.