OpenClaw Error: Invalid Config — Complete Troubleshooting Guide

What Does Invalid Config Mean?

The "Invalid Config" error is OpenClaw's general configuration validation failure. It appears at startup when one or more configuration values fail validation. The error always includes additional detail about which field failed and why:

Error: Invalid Config
  → model.primary: "gpt-4" is not a recognized model identifier
  → gateway.bind: Invalid input
  → telegram.token: Required field missing

OpenClaw validates configuration from three sources, in order of precedence:

1. Environment variables (highest priority — overrides everything)
2. Config file (config.json or config.yaml)
3. Built-in defaults (lowest priority)

The validation happens before any services start. If validation fails, OpenClaw exits immediately. This is intentional — running with invalid configuration could cause unpredictable behavior, data loss, or security vulnerabilities.

The error detail lines (after the arrow →) tell you exactly what went wrong. Read them carefully before diving into troubleshooting. Most issues are obvious once you see which field failed.

How Do You Fix JSON and YAML Syntax Errors?

If you use a config.json or config.yaml file, syntax errors are the most common cause of invalid config. Even a single misplaced comma, missing bracket, or wrong indentation can break the entire file.

Common JSON errors:

// WRONG — trailing comma after last property
{
  "model": {
    "primary": "claude-sonnet-4-20250514",
    "fallback": "gpt-4o",
  }
}

// WRONG — single quotes instead of double quotes
{
  'model': {
    'primary': 'claude-sonnet-4-20250514'
  }
}

// CORRECT
{
  "model": {
    "primary": "claude-sonnet-4-20250514",
    "fallback": "gpt-4o"
  }
}

Common YAML errors:

# WRONG — tabs instead of spaces
model:
	primary: claude-sonnet-4-20250514

# WRONG — missing space after colon
model:
  primary:claude-sonnet-4-20250514

# CORRECT
model:
  primary: claude-sonnet-4-20250514

To validate JSON syntax before restarting OpenClaw:

# Using jq
cat config.json | jq .

# Using Python
python3 -m json.tool config.json

For YAML validation:

# Using Python
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

If syntax validation passes but OpenClaw still rejects the config, the problem is with the values, not the format.

What Required Fields Are Most Often Missing?

OpenClaw has very few strictly required fields — most configuration has sensible defaults. The fields that operators most commonly forget:

At least one AI model API key. OpenClaw needs at least one model provider configured. Set one of these:

ANTHROPIC_API_KEY=sk-ant-...       # For Claude models
OPENAI_API_KEY=sk-...              # For GPT models
GOOGLE_AI_API_KEY=...              # For Gemini models

At least one messaging platform. While not strictly required (you can use OpenClaw with just the web UI or API), most operators need at least one messaging integration. The most common is Telegram:

TELEGRAM_BOT_TOKEN=123456:ABC-...

GATEWAY_TOKEN. Required for API access and gateway authentication. If not set, OpenClaw generates a random one at startup and logs it — but you should set it explicitly:

GATEWAY_TOKEN=your-secure-random-token

Check the startup logs carefully. OpenClaw reports exactly which required field is missing in the error detail.

How Do You Fix Wrong Model Names?

OpenClaw validates model identifiers against a list of known models. If you specify a model name that does not match, you get an invalid config error.

Common mistakes:

# WRONG — shortened names are not valid
MODEL_PRIMARY=claude
MODEL_PRIMARY=gpt4
MODEL_PRIMARY=gemini

# CORRECT — use the full model identifier
MODEL_PRIMARY=claude-sonnet-4-20250514
MODEL_PRIMARY=gpt-4o
MODEL_PRIMARY=gemini-2.0-flash

The valid model identifiers change as providers release new models. As of March 2026, the most commonly used identifiers are:

• Anthropic: claude-sonnet-4-20250514, claude-3-5-sonnet-20241022, claude-3-haiku-20240307
• OpenAI: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
• Google: gemini-2.0-flash, gemini-1.5-pro
• Local (Ollama): Any model name that Ollama recognizes (e.g., llama3, mistral)

For Ollama models, OpenClaw does not validate the model name against a list — it passes it directly to Ollama. If the model is not installed in Ollama, you will get a runtime error instead of a config error.

What Legacy Environment Variables Were Removed?

OpenClaw 3.22 removed all legacy environment variable prefixes from the ClawdBot and MoltBot eras. If you are upgrading from an older version, you must rename your variables.

Removed prefixes:

Examples of renamed variables:

# OLD (removed in 3.22)
CLAWDBOT_TELEGRAM_TOKEN=...
MOLTBOT_MODEL_PRIMARY=...
CB_GATEWAY_BIND=...

# NEW (current)
TELEGRAM_BOT_TOKEN=...
MODEL_PRIMARY=...
GATEWAY_BIND=...

If you have a large .env file with legacy variables, the quickest approach is to check the OpenClaw 3.22 migration guide in the release notes. It includes a complete mapping of old to new variable names.

OpenClaw does not silently ignore legacy variables — it logs a warning for each unrecognized variable. Check the startup logs for messages like [config] Unknown variable: CLAWDBOT_TELEGRAM_TOKEN (did you mean TELEGRAM_BOT_TOKEN?).

How Do You Validate Config Before Starting?

OpenClaw 3.22 introduced a config validation command that checks your configuration without starting the server:

# Bare metal
openclaw config validate

# Docker
docker compose exec openclaw openclaw config validate

# Docker (if container is not running)
docker compose run --rm openclaw openclaw config validate

The validation command checks all three configuration sources (environment variables, config file, and defaults), merges them in the correct order of precedence, and reports any errors. It also reports warnings for deprecated fields, legacy variable names, and potential security issues (like missing GATEWAY_TOKEN).

A successful validation looks like:

Configuration valid.
  Model: claude-sonnet-4-20250514
  Gateway: 0.0.0.0:18789
  Platforms: telegram, discord
  Sandbox: docker
  Auth: google
  Warnings: 0

Run this command after every configuration change, before restarting the server. It takes less than a second and saves you from broken deployments.

How Do You Reset Config to Defaults?

If your configuration is deeply broken and you want to start fresh:

Step 1: Back up your current config.

cp .env .env.backup
cp config.json config.json.backup  # if you have one

Step 2: Remove the config file.

rm config.json  # or config.yaml

Step 3: Create a minimal .env.

# Minimal .env — only what is truly required
ANTHROPIC_API_KEY=sk-ant-your-key-here
GATEWAY_TOKEN=your-secure-token

Step 4: Restart OpenClaw.

docker compose down && docker compose up -d

OpenClaw will start with default configuration plus your API key and gateway token. The setup wizard will guide you through configuring messaging platforms and other options. From there, add configuration one variable at a time, validating after each change.

This incremental approach makes it easy to identify exactly which configuration value is causing problems. If you add a variable and validation fails, that variable is the issue.