OpenClaw Detailed Configuration Guide

This page focuses on field-level configuration for ~/.openclaw/openclaw.json. If you have not finished baseline setup yet, read OpenClaw Installation and Configuration first.

1. openclaw.json Top-Level Field Table (Complete)

The table below covers the complete top-level fields from the official schema. If you only need quick startup troubleshooting, prioritize gateway, agents, models, channels, and tools.

Top-level field	What it controls	Typical use
$schema	Schema identity for config	Editor hints/autocomplete
meta	Auto-written metadata	Usually not edited manually
env	Env import/override	Centralized secret/variable management
wizard	Wizard run state	Onboarding troubleshooting
diagnostics	Diagnostics/tracing	Deeper troubleshooting
logging	Log level and log output	Debugging and incident checks
update	Update channel/startup checks	stable / beta / dev
browser	Browser tool capability	Web automation settings
ui	Control UI behavior/display	Minor UI adjustments
auth	Auth profiles and fallback behavior	Multi-provider auth management
models	Model providers/catalog	Model/provider setup
nodeHost	Node proxy capability	Browser node forwarding
agents	Agent defaults and agent list	Most frequently edited
tools	Tool toggles/allow/deny	Security boundaries
bindings	Session binding routes	Multi-agent routing
broadcast	Broadcast routing strategy	Fan-out/distribution behavior
audio	Audio settings	Voice features
media	Media handling	Upload naming and related rules
messages	Message-layer behavior	Prefixes, queueing, TTS
commands	Slash command behavior	/config, /restart, etc.
approvals	Approval policy	High-risk action approvals
session	Session scope/reset behavior	Isolation and lifecycle
cron	Scheduled task system	Automation
hooks	Webhook inbound settings	External system push
web	Web channel heartbeat/reconnect	Control UI connection stability
channels	Chat channel configs	Telegram/Discord/etc.
discovery	Gateway discovery (mDNS/DNS-SD)	LAN discovery
canvasHost	Canvas service settings	Visual canvas capability
talk	Speech synthesis settings	Talk mode
gateway	Gateway port/bind/auth/remote	Most critical
memory	Memory backend/retrieval	Long-term memory behavior
skills	Skills loading/install	Extend abilities
plugins	Plugin system and install state	Plugin-based extension

2. gateway Field Dictionary (Complete)

gateway is the module most likely to break startup when misconfigured. Read this first.

Field path	Description	Common values
gateway.port	Gateway listening port	18789
gateway.mode	Local or remote gateway mode	local / remote
gateway.bind	Listen address scope	loopback / lan / tailnet / custom
gateway.customBindHost	Custom listen host	192.168.1.10
gateway.controlUi.enabled	Control UI toggle	true
gateway.controlUi.basePath	Control UI base path	/openclaw
gateway.controlUi.root	Control UI static root	dist/control-ui
gateway.controlUi.allowedOrigins	Allowed frontend origins	["https://xxx.com"]
gateway.controlUi.allowInsecureAuth	Insecure-auth warning behavior	false (recommended)
gateway.controlUi.dangerouslyDisableDeviceAuth	Disable device auth validation (dangerous)	false (strongly recommended)
gateway.auth.mode	Gateway auth mode	token / password / trusted-proxy / none
gateway.auth.token	Token auth secret	Long custom string
gateway.auth.password	Password auth secret	Long custom string
gateway.auth.allowTailscale	Allow Tailscale-related auth paths	true / false
gateway.auth.rateLimit.maxAttempts	Max failed attempts	Number
gateway.auth.rateLimit.windowMs	Rate-limit window (ms)	Number
gateway.auth.rateLimit.lockoutMs	Lockout duration (ms)	Number
gateway.auth.rateLimit.exemptLoopback	Exempt loopback from rate-limit	true / false
gateway.auth.trustedProxy.userHeader	Trusted-proxy user header	e.g. x-auth-user
gateway.auth.trustedProxy.requiredHeaders	Required trusted-proxy headers	String array
gateway.auth.trustedProxy.allowUsers	Allowed users via trusted proxy	String array
gateway.trustedProxies	Trusted proxy IP list	["127.0.0.1"]
gateway.allowRealIpFallback	Fallback to X-Real-IP if no X-Forwarded-For	false (safer default)
gateway.tools.deny	Extra denied tools over HTTP	Tool name array
gateway.tools.allow	Re-allow tools from default deny set	Tool name array
gateway.channelHealthCheckMinutes	Channel health check interval	Number
gateway.tailscale.mode	Tailscale mode	off / serve / funnel
gateway.tailscale.resetOnExit	Reset Tailscale state on exit	true / false
gateway.remote.url	Remote gateway URL	ws:// or wss://
gateway.remote.transport	Remote transport	ssh / direct
gateway.remote.token	Remote mode token	String
gateway.remote.password	Remote mode password	String
gateway.remote.tlsFingerprint	TLS pinning fingerprint	sha256:...
gateway.remote.sshTarget	SSH target	user@host
gateway.remote.sshIdentity	SSH private key path	File path
gateway.reload.mode	Hot-reload strategy	off / restart / hot / hybrid
gateway.reload.debounceMs	Reload debounce time	Number
gateway.tls.enabled	TLS enabled	true / false
gateway.tls.autoGenerate	Auto-generate certificates	true / false
gateway.tls.certPath	Certificate path	File path
gateway.tls.keyPath	Private key path	File path
gateway.tls.caPath	CA path	File path
gateway.http.endpoints.chatCompletions.enabled	OpenAI-compatible Chat Completions endpoint	true / false
gateway.http.endpoints.responses.enabled	OpenAI-compatible Responses endpoint	true / false
gateway.http.endpoints.responses.maxBodyBytes	Responses request-body size limit	Number
gateway.http.endpoints.responses.maxUrlParts	URL parts limit	Number
gateway.http.endpoints.responses.files.allowUrl	Allow file URL input	true / false
gateway.http.endpoints.responses.files.urlAllowlist	File URL allowlist	String array
gateway.http.endpoints.responses.files.allowedMimes	File MIME allowlist	String array
gateway.http.endpoints.responses.files.maxBytes	Per-file byte limit	Number
gateway.http.endpoints.responses.files.maxChars	Text extraction char limit	Number
gateway.http.endpoints.responses.files.maxRedirects	Max redirects for file URL	Number
gateway.http.endpoints.responses.files.timeoutMs	File fetch timeout	Number
gateway.http.endpoints.responses.files.pdf.maxPages	PDF page limit	Number
gateway.http.endpoints.responses.files.pdf.maxPixels	PDF render pixel cap	Number
gateway.http.endpoints.responses.files.pdf.minTextChars	Minimum extracted text chars in PDF	Number
gateway.http.endpoints.responses.images.allowUrl	Allow image URL input	true / false
gateway.http.endpoints.responses.images.urlAllowlist	Image URL allowlist	String array
gateway.http.endpoints.responses.images.allowedMimes	Image MIME allowlist	String array
gateway.http.endpoints.responses.images.maxBytes	Per-image size limit	Number
gateway.http.endpoints.responses.images.maxRedirects	Max redirects for image URL	Number
gateway.http.endpoints.responses.images.timeoutMs	Image fetch timeout	Number
gateway.nodes.browser.mode	Browser node routing mode	auto / manual / off
gateway.nodes.browser.node	Fixed browser node ID	Node ID
gateway.nodes.allowCommands	Extra allowed node commands	Command array
gateway.nodes.denyCommands	Explicitly denied node commands	Command array

3. Six High-Frequency Field Groups for Beginners

Module	Frequently edited fields	What this affects
agents.defaults	model.primary, workspace, heartbeat, sandbox	Default model, workspace, heartbeat, isolation policy
channels	channels.<channel>.enabled, dmPolicy, allowFrom, groupPolicy	Who can message your agent and which groups trigger it
tools	tools.allow, tools.deny, tools.web.*	Tool safety boundary and scope
session	scope, dmScope, reset.*	Session isolation and auto-reset behavior
skills	skills.load.extraDirs, skills.entries.*	Additional skills directories and per-skill keys
logging	level, file, consoleLevel	Day-to-day troubleshooting visibility

References (Official Sources)

• Gateway Configuration
• Configuration Reference
• OpenClaw GitHub Repository

Checked on: 2026-02-23