Configuration Problems

🔧 Configuration troubleshooting: This page covers OpenClaw configuration file and config validation errors. For gateway startup, channels, or model/API issues, see Troubleshooting Guide, Gateway Issues, Channel Errors, or Model & API Errors.

Quick diagnostic

Not sure where to start? Run openclaw doctor first. It checks configuration, paths, and common issues. Then use the commands below to narrow down config-specific problems.

# Full health check (config, gateway, paths)
openclaw doctor

# Optional: try auto-fixing some issues
openclaw doctor --fix

# Check status and which config is in use
openclaw status

# Validate configuration file
openclaw config validate

# View recent logs (errors often mention config keys)
openclaw logs --tail 50
openclaw logs --follow

See Quick diagnostics and the main Troubleshooting Guide for the full diagnostic flow. If the gateway won’t start at all, start with Gateway Issues.

Summary: Configuration errors at a glance

Symptom / error Likely cause What to do
Config validation failed Invalid YAML/JSON, wrong keys, or schema mismatch Fix syntax; check key names against official docs; run openclaw doctor and openclaw config validate. See Config validation failed below.
Session file path violations Session path not allowed, missing, or bad permissions Set a valid session path in config; ensure directory exists and is writable; check schema for allowed paths. See Session path violations.
Model not allowed Agent references a model not in allowed list or wrong provider Add model to provider config and/or allowlist; verify agent’s model matches a configured provider. See model provider setup and Model not allowed.
Missing scope errors Config node or permission scope missing for an operation Add required scope or config block per official docs; run openclaw config validate.
Schema node unsupported Config structure doesn’t match your OpenClaw version (e.g. channel adapter name changed) Update config to match your version’s schema; check release notes and config file structure; see Schema node unsupported.
Agent config moved / agent not found Config file or path changed; CLI and gateway using different config Ensure single config path for CLI and gateway; verify with openclaw doctor; see Agent config moved.

Config validation failed

Errors like “Config validation failed” or “Invalid configuration” mean the config file doesn’t pass the schema or syntax checks. Common causes:

  • YAML/JSON syntax: Wrong indentation, missing colons, unclosed quotes, or tabs instead of spaces (in YAML). Use a linter or openclaw config validate to get line hints.
  • Wrong or deprecated keys: Key names and nesting can change between OpenClaw versions. Compare your file to the official OpenClaw documentation for your release.
  • Wrong config file: You might be editing a file that isn’t the one OpenClaw loads. Run openclaw doctor to see which config path is in use (see where configuration lives).

Steps:

  1. Run openclaw config validate and openclaw doctor; note the reported error and file/line if given.
  2. Open the config with openclaw config edit (so you edit the correct file) and fix the reported key or syntax.
  3. If you recently upgraded, read release notes and update or remove deprecated keys. See Configuration file structure for main sections (gateway, channels, model providers, agents, skills, memory).

Session file path violations

OpenClaw stores session and state data in a configured path. If that path is invalid, missing, or not allowed by your config, you may see session file path violations or similar errors.

  • Path must be allowed: Some setups restrict which directories can be used for session data. Check your config schema for session/storage path options and allowed values.
  • Directory must exist and be writable: Create the directory if needed and set permissions so the user running the gateway can write to it.
  • Absolute vs relative: Prefer an absolute path for session data to avoid confusion when starting the gateway from different working directories.

See directory layout and memory configuration for where session and state are typically stored. After changing paths, run openclaw doctor and restart the gateway.

Model not allowed

Errors like “Model not allowed” or “Model X is not configured” mean the agent is trying to use a model that isn’t enabled or doesn’t exist in your model provider configuration.

  • Provider and model name: In the config, each provider (Anthropic, OpenAI, Google, Ollama, etc.) has a list of models. The agent’s model (or equivalent) must match one of those. See model provider setup and per-provider guides: Anthropic, OpenAI, Ollama.
  • Allowlist / allow list: Some versions require an explicit allowlist of model names. Add the model name to the provider’s allowed models in config.
  • API key and provider: Ensure the provider block has a valid API key (or env var) and the model name matches what that provider supports. For API errors (rate limits, billing), see Model & API Errors.

Missing scope errors

Missing scope errors usually mean a required configuration block or permission scope is absent. For example, a channel might require a scope that isn’t set, or an agent might need a capability that isn’t declared.

  • Check the exact error message for the missing scope or node name.
  • Consult the official OpenClaw documentation for the channel, agent, or feature you’re configuring-add the required block or scope.
  • Run openclaw config validate and openclaw doctor; they may point to the missing section.

Schema node unsupported

Errors like “Schema node unsupported” or “Channel schema unavailable” mean part of your config uses a structure or key that your OpenClaw version doesn’t recognize. This often happens after an upgrade or when copying config from another version.

  • Version mismatch: Adapter names, channel schema, and top-level keys can change between versions. Read the release notes for your version and the official docs.
  • Typos in channel id or adapter: Validate with openclaw config validate and openclaw doctor. Fix any reported path or schema errors (e.g. wrong adapter or channel id).
  • Config file location: OpenClaw may be reading a different config file than the one you edited. openclaw doctor shows which config file is in use-see Configuration file guide.

For channel-specific schema errors, see Channel Errors (e.g. Telegram, WhatsApp, Discord).

Agent config moved or agent not found

If you see “Agent config moved”, “Agent not found”, or the gateway can’t find channels/agents after a config change, the CLI and gateway may be using different config files or paths.

  • Single config: Ensure the same user and environment (e.g. same OPENCLAW_CONFIG_PATH if you use it) are used when running openclaw and when the gateway starts. Otherwise one may read an old or different file.
  • Verify path: Run openclaw doctor to see which config file the CLI expects. If you start the gateway manually (e.g. systemd, Docker), ensure that process uses the same path. See where configuration lives.
  • After moving or copying config: Update any scripts or service files that point to the config path. Restart the gateway after changing the path.

For defining and naming agents, see Agent customization.

Step-by-step config debugging

  1. Run diagnostics: openclaw doctor and openclaw doctor --fix.
  2. Confirm config in use: openclaw status (or doctor output) shows the config path. Edit only that file.
  3. Validate: openclaw config validate and fix any reported errors.
  4. Check logs: openclaw logs --tail 50 or openclaw logs --follow for messages that mention config keys or schema.
  5. Restart gateway: After fixing config, restart so the gateway reloads: openclaw restart (or your service manager).

Related configuration guides

Getting help

If you're still stuck:

When reporting, include: OpenClaw version, output of openclaw doctor (redact paths if sensitive), the exact error message, and a redacted config snippet (no API keys or tokens).