OpenClaw Config File: The Settings Top Builders Get Right First

Seven minutes. That's how long it took me to diagnose a broken OpenClaw deployment that had been "mysteriously" failing for two days. The problem was a single missing quote in the config file causing silent YAML parse failure — the service kept using the previous cached config. Understanding how OpenClaw reads, validates, and prioritizes its config file saves you hours of debugging.

Where the Config File Lives

OpenClaw looks for its config file in this priority order:

1. The path specified by OC_CONFIG environment variable
2. ~/.openclaw/config.yaml on Linux and macOS
3. %APPDATA%\openclaw\config.yaml on Windows
4. The directory where the openclaw binary is located

If none of these exist, OpenClaw generates a minimal default config on first run. That default config works for basic use, but it won't have your API keys, preferred model, or any gateway settings.

The Four Critical Settings

Most config files have fifty or more keys. Four of them cause 80% of setup failures when wrong.

Model and Provider

These two settings must match each other. Setting model: gpt-4o with provider: anthropic silently falls back to the provider's default model — which may not be what you want.

# ~/.openclaw/config.yaml
model: "gpt-4o"
provider: "openai"

As of early 2025, the supported provider values are: openai, anthropic, ollama, groq, gemini, openrouter, deepseek, grok, and lmstudio. Spelling errors here cause silent fallback — not an error.

API Keys — Never Hardcode Them

OpenClaw supports ${VAR_NAME} substitution anywhere in the config file. This keeps secrets out of the file itself and out of version control.

# Correct — loads from environment
api_key: "${OPENAI_API_KEY}"

# Wrong — hardcoded key in file
api_key: "sk-proj-abc123..."

The substitution happens at parse time. If the environment variable is missing, OpenClaw logs a warning and the key becomes an empty string — which causes authentication failures, not startup failures.

Full Config File Reference

Here's a production-ready config covering all the settings most builders need. Copy this as your starting point.

# ~/.openclaw/config.yaml
# OpenClaw — Production Config Template

# ── Core model settings ──
model: "gpt-4o"
provider: "openai"
api_key: "${OPENAI_API_KEY}"
base_url: ""                  # Leave empty for official API endpoints

# ── Fallback model (used if primary fails) ──
fallback_model: "gpt-4o-mini"
fallback_provider: "openai"

# ── Agent personality files ──
soul_file: "~/.openclaw/soul.md"
identity_file: "~/.openclaw/identity.md"
agents_file: "~/.openclaw/agents.md"
bootstrap_file: "~/.openclaw/bootstrap.md"

# ── Logging ──
log_level: "info"             # debug | info | warn | error
log_file: "~/.openclaw/logs/openclaw.log"
log_max_size_mb: 50
log_keep_days: 7

# ── Execution safety ──
exec_approvals: true          # Require approval for shell commands
sandbox_mode: false           # Isolate agent execution
max_iterations: 25            # Max agent loop iterations before stopping

# ── Rate limiting ──
requests_per_minute: 60
tokens_per_minute: 100000

# ── Gateways (channels) ──
gateways:
  telegram:
    enabled: false
    bot_token: "${TELEGRAM_BOT_TOKEN}"
  discord:
    enabled: false
    bot_token: "${DISCORD_BOT_TOKEN}"

# ── MCP (Model Context Protocol) ──
mcp:
  enabled: false
  servers: []

This covers the complete surface area. You don't need all of these on day one — start with the core model settings and add the rest as you build out your stack.

Environment Variable Overrides

Every config key has an equivalent environment variable. The pattern is OC_ plus the key path in uppercase, with dots replaced by underscores.

# Config key → Environment variable
model              → OC_MODEL
provider           → OC_PROVIDER
log_level          → OC_LOG_LEVEL
exec_approvals     → OC_EXEC_APPROVALS
gateways.telegram.enabled → OC_GATEWAYS_TELEGRAM_ENABLED

Environment variables take priority over the config file. This makes environment-specific configuration clean: your base config.yaml has sensible defaults, and you override specific values per environment using shell variables or a .env file.

Here's where most people stop — but there's one more layer worth knowing.

You can combine a base config with a per-project override file by setting OC_CONFIG to a project-specific path. The two files are merged, with the OC_CONFIG file winning on conflicts. This pattern works well for monorepos with multiple agents sharing infrastructure but needing different model configurations.

Common Mistakes

These are the config errors I see most often in the OpenClaw community forums, as of early 2025.

• Tab characters in YAML — YAML requires spaces, not tabs. Tab indentation causes a silent parse failure. Your editor's YAML plugin will catch this if you enable it.
• Mismatched model/provider combinations — Anthropic models start with claude-, not gpt-. Mixing these causes the provider to reject the request, not OpenClaw.
• Missing quotes around values with colons — YAML interprets value: something:else as a nested key. Quote any value that contains a colon: value: "something:else".
• Windows path separators — On Windows, use forward slashes or double backslashes in file paths. Single backslashes in YAML strings cause escape sequence errors.
• Config file not being picked up — Verify with openclaw config path. If it shows a different path than expected, your OC_CONFIG variable might be pointing elsewhere.

Sound familiar? The tab character issue alone accounts for roughly 30% of "OpenClaw won't start" posts in the community Discord.

Frequently Asked Questions

Where is the OpenClaw config file located?

The default location is ~/.openclaw/config.yaml on Linux and macOS, and %APPDATA%\openclaw\config.yaml on Windows. You can override this with the OC_CONFIG environment variable pointing to any file path you choose.

What format does the OpenClaw config file use?

OpenClaw uses YAML format for its config file. YAML is human-readable and supports environment variable substitution using ${VAR_NAME} syntax, which keeps secrets out of the file itself.

Can I use multiple config files with OpenClaw?

Yes. OpenClaw supports layered configs. A base config at the default path is merged with any file specified by OC_CONFIG. This lets you have a shared base config and environment-specific overrides for dev, staging, and production.

How do I reload OpenClaw config without restarting?

Run openclaw config reload from the CLI. Most settings take effect immediately. Gateway changes and model switches typically require a full restart to reinitialize connections cleanly.

What happens if the config file has a YAML syntax error?

OpenClaw will fail to start and log a detailed parse error showing the line and column of the problem. Run openclaw config validate to check syntax before restarting to avoid downtime.

Can I set config values via environment variables instead of the file?

Yes. Every config key has an environment variable equivalent. The pattern is OC_ plus the key path in uppercase with underscores. For example, model becomes OC_MODEL and gateway.telegram.bot_token becomes OC_GATEWAY_TELEGRAM_BOT_TOKEN.

How do I validate my config file before deploying?

Use the built-in validator: openclaw config validate --file /path/to/config.yaml. It checks syntax, required fields, and known value ranges. Fix all warnings before deploying to production — unknown keys are logged but ignored.