Configuration File Structure

📘 Guide Status: This page explains where OpenClaw stores configuration and how the config file is organized. For first-time setup, see the Quick Start Guide; for editing agents or model providers, use the links below.

Overview

OpenClaw uses a single main configuration file (usually YAML or JSON) and a predictable directory layout for config, session data, logs, and installed skills. Understanding this structure helps you edit settings safely, back up correctly, and troubleshoot issues. The exact paths and key names can vary by OpenClaw version-check the official OpenClaw documentation for your release.

This guide covers:

Where Configuration Lives

After installing OpenClaw, the CLI and gateway look for configuration in a standard location. Typical locations (depending on install method and OS) include:

  • User config directory: A folder such as ~/.openclaw (Linux/macOS) or %USERPROFILE%\.openclaw (Windows), containing the main config file and often subdirectories for data.
  • Project or workspace directory: Some setups use a config file in the current working directory or a path set via environment variable.
  • Docker deployments: Config is usually mounted from the host into a path like /root/.openclaw or a custom path-see the Docker deployment guide and Docker security for best practices.

To see where your installation expects the config, run:

openclaw doctor

or check the output of openclaw status. The official docs for your version will list the exact default paths. Never commit this directory or config file to public repositories-it can contain API keys and channel credentials. Use environment variables or a secrets manager for sensitive values; see credential management and security best practices.

Directory Layout

OpenClaw’s data directory typically contains:

Path / item Purpose
Config file (e.g. config.yaml or config.json) Main configuration: gateway, channels, model providers, agents, skills, memory. Edited via openclaw config edit or manually.
Session / state data Persistent conversation context, memory storage, and agent state. Location is often configurable in the config file.
Logs Gateway and CLI logs for debugging. Use openclaw logs or check the path reported by openclaw doctor. See monitoring and logging.
Skills (ClawHub / custom) Installed skills from the ClawHub marketplace or custom skills. Usually in a dedicated subdirectory; avoid editing skill internals unless developing.

Back up the config file and any custom env files regularly. Session and log paths may grow; plan log rotation and storage. For production, follow the security checklist and keep the gateway bound to localhost unless you use proper network isolation.

Main Config File Sections

The main configuration file is structured into logical sections. Exact key names depend on your OpenClaw version; the following reflects common patterns described in the architecture overview and official docs.

Gateway

Controls the gateway daemon: bind address, port, and sometimes auth token. For security, bind to 127.0.0.1 only; use VPN or SSH tunneling for remote access. See network isolation.

Channels

Each messaging platform (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Teams, etc.) is a channel. Channel config holds platform-specific credentials (e.g. bot tokens, API keys) and options (e.g. which agent handles the channel). Add or edit channels in this section; step-by-step guides: Telegram, WhatsApp, Discord, Slack. Overview: channel setup hub.

Model providers

OpenClaw is model-agnostic: you configure one or more LLM providers (Anthropic Claude, OpenAI GPT, Google Gemini, DeepSeek, local models via Ollama, etc.). Each provider has its own block (API key via env var, model names, optional limits). Agents then reference a provider and model. See model provider setup and the per-provider guides: Anthropic, OpenAI, Ollama, Google, DeepSeek.

Agents

Each agent defines the “brain”: system prompt, model, enabled skills, tool policies, and optional memory settings. You can have one default agent or multiple agents for different channels or use cases. Details: agent customization.

Skills

Lists which skills are enabled globally or per agent, and optional skill-specific options or env vars. Install skills from ClawHub; then reference them in config. Security: audit skills before use-see skills security and security and skills.

Memory

Configuration for persistent context and cross-session storage. See the dedicated memory configuration guide.

Additional options (MCP servers, sandbox mode, tool policies, logging, performance) are covered in advanced configuration. For the authoritative schema, always refer to the official OpenClaw documentation for your version.

How to Edit Configuration

Recommended: Use the CLI to open the config in your default editor:

openclaw config edit

This uses the config path your installation expects and helps avoid path mistakes. Save and exit; the gateway may need a restart to pick up changes (depending on version).

Manual editing: Open the config file directly at the path shown by openclaw doctor or openclaw status. Use valid YAML or JSON; even a small syntax error can prevent the gateway from starting. After editing, run openclaw doctor to check for issues, and see the troubleshooting guide for common config errors (e.g. “Config validation failed”, “Session file path violations”).

Keep API keys and secrets out of the config file when possible-use environment variables or a secrets manager and reference them in config. See credential management.

Validation and Troubleshooting

Issue What to do
Config validation failed / schema errors Check YAML/JSON syntax (indentation, quotes). Confirm key names against the official docs. Run openclaw doctor.
Gateway won’t start after config change Revert recent edits or fix the reported error. Check logs with openclaw logs. See troubleshooting and gateway issues.
Agent or channel not found / wrong config path Ensure CLI and gateway use the same config (same user, same env). Verify paths with openclaw doctor.
Session file path violations Session path must be allowed by your config and exist; check config schema and file permissions.

For more errors and fixes, see the full troubleshooting hub and configuration problems page.

Next Steps

Related Resources