Why does my openclaw.json cause the gateway not to start?

OpenClaw uses strict Zod schema validation. Any unknown key in openclaw.json causes the Gateway to refuse to start with no graceful fallback. Run 'openclaw doctor --fix' after every manual edit to remove stale or invalid keys. Use this generator to build a schema-valid config from scratch.

🦀 OpenClaw Tool

OpenClaw JSON Config Generator

Build a valid openclaw.json config visually. Configure every section — gateway, models, agents, channels, cron, sandbox and logging — with a live JSON preview and one-click download. Zero schema errors guaranteed.

🎛️ Visual Form Builder👁️ Live JSON Preview✅ Schema Validation⬇️ Download Ready🔒 Env Var Safe🔒 100% Private

Config completeness0%

🌐GatewayRequired

▼

Port

Default: 18789. Do not change unless port is in use.

Mode

Bind Address

⚠️ Always use loopback on VPS. Setting all without a token exposes your gateway to the internet and leaks API keys.

Auth Token (use ${ENV_VAR} for security)

Leave empty if using loopback only. Required if bind = all.

Reload Mode

Update Channel

🛡️ Allow Tailscale IPs (bypass token check)

🖥️ Enable Control UI

🤖Models & ProvidersRequired

▼

Primary Model

Custom Model ID

Fallback Models

Models tried in order when primary fails or hits rate limits.

Anthropic API Key

OpenAI API Key

OpenRouter API Key

🦙 Enable Ollama (local model server)

🕵️AgentsRequired

▼

Workspace Path

Max Concurrent Tasks

4–8 is safe. Higher = more parallel tasks but risk of runaway retries.

Heartbeat Interval

Context Pruning

✂️ Enable Context Pruning (strongly recommended)

Pruning Mode

Cache TTL

Compaction

🗜️ Enable Memory Flush on Compaction

Compaction Mode

Soft Threshold Tokens

Additional Agents

A "main" agent is always included. Add additional agents here.

📡ChannelsOptional

▼

💬 Telegram

🎮 Discord

🔒Session & PrivacyRequired

▼

DM Scope

⚠️ Use per-channel-peer for any multi-user setup. With "main", all users share one session — a data leak.

Session Reset Mode

Daily Reset Hour (UTC)

⏰Cron JobsOptional

▼

⏰ Enable Cron Jobs

Max Concurrent Cron Runs

Keep low (2–3) to avoid runaway tasks burning quota.

🧪Sandbox (Docker)Optional

▼

Sandbox Mode

Requires Docker CLI. Set OPENCLAW_INSTALL_DOCKER_CLI=1 in your environment.

Docker Image

CPUs

Memory (MB)

🔒 Read-Only Root Filesystem

🔧ToolsOptional

▼

🔍 Web Search

🐚 Shell Environment Import

📋LoggingOptional

▼

Log Level (file)

Console Log Level

Redact Sensitive Data

✅ Config structure is valid

📄 openclaw.json Preview

⚡ Quick Actions

📂 Save to: ~/.openclaw/openclaw.json
🔍 Then run: openclaw doctor --fix

🦀 What Is the OpenClaw JSON Config Generator?

The OpenClaw JSON Config Generator is a free visual tool that builds a complete, schema-valid openclaw.json configuration file for the OpenClaw AI agent gateway. Instead of manually writing JSON and risking the Zod schema validation errors that prevent the gateway from starting, you fill out a structured form and the tool generates correct, ready-to-use JSON in real time.

OpenClaw's config file controls every aspect of the system: the gateway port and binding, which LLM models to use with automatic fallback, agent workspace and context pruning settings, messaging channels like Telegram and Discord, cron job automation, Docker sandbox isolation and logging. All of these can be configured visually here and downloaded as a single file. [web:26]

📦 Config Sections Explained

🌐

gateway

Port, bind address, auth token and reload mode. Always use bind: loopback on a VPS to prevent internet exposure.

🤖

models

Primary LLM, fallback chain, API keys via ${ENV_VAR} references, and local model servers (Ollama, LM Studio).

🕵️

agents

Workspace path, concurrency limits, context pruning (prevents token overflow), compaction and heartbeat interval.

📡

channels

Telegram and Discord bot integration with DM policy control — allowlist to restrict access to your account only.

🔒

session

DM scope (critical for privacy), session reset schedule and thread bindings. Use per-channel-peer to isolate users.

⏰

cron

Enable scheduled automation tasks. Set maxConcurrentRuns low (2–3) to avoid runaway retries burning your quota.

🧪

sandbox

Docker isolation for subagents. Use non-main mode to sandbox cron jobs and subagents while keeping your main session on the host.

📋

logging

Log level, console log level and sensitive data redaction. Use redactSensitive: tools to keep API keys out of logs.

⚠️ Critical Rules for openclaw.json

Unknown keys cause the Gateway to refuse to start — OpenClaw uses strict Zod schema validation with no warning mode. This generator only outputs schema-valid keys. [web:26]
Never hardcode API keys — always use ${ENV_VAR} syntax. Store actual keys in ~/.openclaw/.env or your system environment.
Always run openclaw doctor --fix after any manual edit — it removes stale keys and adds required new fields after upgrades.
Back up before editing: cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
gateway.port and gateway.bind require a full restart — they are the two fields that do not hot-reload. [web:26]
Compaction settings only work at agents.defaults — per-agent compaction overrides are silently ignored by the gateway. [web:26]

💰 Cost Optimization Tips

Keep expensive models (claude-opus) out of the primary slot — use them only as fallbacks or per specific agents
Use claude-haiku or gpt-5-mini for the heartbeat — at 48 heartbeats/day the cost difference is $0.005/day vs $0.24/day [web:27]
Enable contextPruning — without it, sessions with many tool calls can silently hit the model's 200k token limit
Set maxConcurrent: 4 on agents — prevents one stuck task from spawning 50 retries and burning your quota in minutes [web:27]
Target $45–50/month for moderate usage. If costs climb above $100/month, check for expensive default model, no concurrency limits, or memory flush running too often [web:27]

❓ Frequently Asked Questions

What is the openclaw.json file?+

openclaw.json is the single configuration file for OpenClaw, the AI agent gateway. It lives at ~/.openclaw/openclaw.json and controls the gateway port, LLM models, agent settings, messaging channels (Telegram, Discord), cron jobs, sandbox isolation, and logging. The file is validated by Zod at startup — any unknown key causes the gateway to refuse to start.

Why does my openclaw.json prevent the gateway from starting?+

OpenClaw uses strict Zod schema validation — unknown keys cause the Gateway to refuse to start with no graceful fallback and no warning mode. The most common cause is manually editing the file and adding a key that no longer exists in the schema after an upgrade. Run openclaw doctor --fix after every edit or upgrade. Use this generator to build a config from scratch with only schema-valid keys.

How do I add API keys securely to openclaw.json?+

Never hardcode API keys directly in the config file. Use ${ENV_VAR} syntax in the JSON — for example "apiKey": "${ANTHROPIC_API_KEY}" — and store the actual key values in ~/.openclaw/.env or your system environment. This generator outputs environment variable placeholders by default. After editing, run openclaw security audit --deep to check for exposed credentials.

What is the difference between contextPruning and compaction?+

contextPruning runs before each LLM call and trims old tool results from the in-memory context to prevent token overflow. It only affects what gets sent to the model, not the session file on disk. compaction runs when the full context window approaches its limit and summarizes the entire conversation history. Without contextPruning, sessions with many tool calls can silently exceed the model's 200k token limit and stop responding. Both should be enabled in production.

Which settings require a full gateway restart?+

Only a few settings require a full restart: gateway.port, gateway.bind, gateway.reload, gateway.remote, sandbox Docker image/network config, and plugin installation or removal. Most other settings — model changes, agent config, channel policies, cron jobs, heartbeat intervals and logging — hot-reload without a restart.

What should gateway.bind be set to?+

Always use bind: "loopback" (binds to 127.0.0.1 only) on VPS deployments. Setting bind: "all" exposes the gateway to the internet on 0.0.0.0. Exposed OpenClaw gateways have leaked API keys, OAuth tokens and full session histories. If you need external access, use a reverse proxy (nginx/Caddy) with HTTPS in front of the local gateway instead of binding directly.