OpenClaw Configuration Guide: Every Config Command & Setting Explained (2026)

What Is OpenClaw Configuration?

OpenClaw is an open-source AI agent framework that lets you build, deploy, and orchestrate AI agents from the command line. Before your agents can do anything useful, you need to configure the framework: which AI model to use, how to authenticate with providers, which communication channels to enable, and how the gateway server should behave.

OpenClaw provides two ways to manage configuration. The interactive wizard (openclaw configure) guides you through every setting step by step. The direct command (openclaw config set) lets you set any individual value instantly. This guide covers both approaches and documents every configuration option available in the OpenClaw agent framework.

Quick Start: Interactive Configuration Wizard

If you are setting up OpenClaw for the first time, the interactive wizard is the fastest way to get everything configured. It walks you through model selection, API key setup, channel configuration, and gateway settings in a single session.

# Launch the interactive configuration wizard
openclaw configure

# The wizard will prompt you for:
# 1. Primary AI model provider (Anthropic, OpenAI, Ollama)
# 2. API key for the selected provider
# 3. Default model identifier
# 4. Gateway port and host
# 5. Channel setup (Telegram, Slack, Discord)
# 6. Agent default settings

The wizard writes all settings to ~/.openclaw/config.json. You can re-run it at any time to change settings, or use openclaw config set to modify individual values directly.

Model Configuration

The model configuration determines which AI model your agents use for reasoning and generating responses. OpenClaw supports Anthropic (Claude), OpenAI (GPT), and local models through Ollama. You can set both a primary and a secondary (fallback) model.

Setting the Primary Model

The primary model is what every agent uses by default. Use openclaw config set agents.defaults.model.primary followed by the model identifier.

# Set Claude Sonnet as the primary model
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514

# Set Claude Opus as the primary model
openclaw config set agents.defaults.model.primary claude-opus-4-20250514

# Set GPT-4o as the primary model
openclaw config set agents.defaults.model.primary gpt-4o

# Set a local Ollama model as primary
openclaw config set agents.defaults.model.primary llama3.2

Setting the Secondary (Fallback) Model

The secondary model activates when the primary model is unavailable, rate-limited, or returns an error. It is optional but recommended for production setups. A common pattern is using a high-capability primary model with a cheaper secondary fallback.

# Set a fallback model
openclaw config set agents.defaults.model.secondary gpt-4o-mini

# Example: Claude primary with GPT-4o-mini fallback
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set agents.defaults.model.secondary gpt-4o-mini

# Example: GPT-4o primary with local Ollama fallback
openclaw config set agents.defaults.model.primary gpt-4o
openclaw config set agents.defaults.model.secondary llama3.2

Supported Model Identifiers

Provider	Model ID	Notes
Anthropic	`claude-sonnet-4-20250514`	Best balance of speed and quality
Anthropic	`claude-opus-4-20250514`	Highest capability, slower
Anthropic	`claude-haiku-3-5`	Fastest, lowest cost
OpenAI	`gpt-4o`	Latest GPT-4 multimodal
OpenAI	`gpt-4o-mini`	Cost-effective fallback
Ollama	`llama3.2`	Local, no API key needed
Ollama	`mistral`	Local, lightweight

API Key Setup

Before agents can call any cloud-hosted model, you need to authenticate with the provider. OpenClaw stores API keys locally in your home directory and never transmits them anywhere except to the model provider during inference.

Anthropic (Claude)

# Authenticate with Anthropic
openclaw models auth paste-token --provider anthropic

# When prompted, paste your API key:
# sk-ant-api03-xxxxxxxxxxxxxxxxxxxx

OpenAI (GPT)

# Authenticate with OpenAI
openclaw models auth paste-token --provider openai

# When prompted, paste your API key:
# sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ollama (Local Models)

Ollama runs models locally on your machine, so no API key is required. You only need to tell OpenClaw where Ollama is running.

# Register Ollama as a provider (no API key needed)
openclaw models auth paste-token --provider ollama

# Ollama must be running locally first
# Default endpoint: http://localhost:11434

# Set a local model as default
openclaw config set agents.defaults.model.primary llama3.2

Channel Configuration

Channels are communication interfaces that connect your agents to messaging platforms. OpenClaw supports Telegram, Slack, and Discord out of the box. Each channel requires its own authentication token set via openclaw config set.

Telegram Bot Token

Telegram is the most common channel for OpenClaw agents. To set it up, first create a bot through @BotFather on Telegram, then copy the bot token.

# Set Telegram bot token
openclaw config set channels.telegram.bottoken YOUR_TELEGRAM_BOT_TOKEN

# Example with a real token format
openclaw config set channels.telegram.bottoken 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Restart gateway to activate the channel
openclaw gateway restart

Important: After setting the Telegram bot token, you must restart the gateway with openclaw gateway restart for the channel to become active. The gateway does not hot-reload channel configuration.

Slack Integration

To connect your agents to a Slack workspace, you need a Slack Bot token (starts with xoxb-) and optionally a signing secret for webhook verification.

# Set Slack bot token
openclaw config set channels.slack.bottoken xoxb-YOUR-SLACK-BOT-TOKEN

# Set Slack signing secret (for webhook verification)
openclaw config set channels.slack.signingsecret YOUR_SIGNING_SECRET

# Restart gateway to activate
openclaw gateway restart

Discord Integration

# Set Discord bot token
openclaw config set channels.discord.bottoken YOUR_DISCORD_BOT_TOKEN

# Restart gateway to activate
openclaw gateway restart

Setting the Default Channel

You can set a default channel that agents use for outbound notifications and heartbeat messages.

# Set Telegram as the default channel
openclaw config set agents.defaults.channel telegram

# Set Slack as the default channel
openclaw config set agents.defaults.channel slack

Agent Defaults

Agent defaults are global settings that apply to every agent unless overridden in the individual agent's workspace configuration. These settings control heartbeat behavior, default channels, and session management.

Heartbeat Configuration

The heartbeat is a periodic task system that triggers agents to perform scheduled work. You can enable or disable it globally and set the interval.

# Enable heartbeat globally
openclaw config set agents.defaults.heartbeat true

# Disable heartbeat globally
openclaw config set agents.defaults.heartbeat false

# Set heartbeat interval in seconds (default: 3600)
openclaw config set agents.defaults.heartbeat.interval 1800

Default Channel for Agents

# All agents default to Telegram for notifications
openclaw config set agents.defaults.channel telegram

# Override for a specific agent in its SOUL.md or workspace config

Session Defaults

# Set maximum session history length (number of messages retained)
openclaw config set agents.defaults.session.maxhistory 50

# Set session timeout in seconds
openclaw config set agents.defaults.session.timeout 3600

Gateway Settings

The gateway is the central server that manages agent routing, channel connections, and the web interface. By default it runs on port 18789, but you can customize the port, host binding, and other server-level settings.

Port and Host Configuration

# Change the gateway port (default: 18789)
openclaw config set gateway.port 3000

# Bind to a specific host (default: localhost)
openclaw config set gateway.host 0.0.0.0

# Bind to all interfaces (useful for remote access)
openclaw config set gateway.host 0.0.0.0
openclaw config set gateway.port 8080

# Restart to apply changes
openclaw gateway restart

Security note: Setting gateway.host to 0.0.0.0 exposes the gateway to your entire network. Only do this on trusted networks or behind a reverse proxy with authentication.

Gateway Logging

# Set log level (debug, info, warn, error)
openclaw config set gateway.loglevel debug

# Enable verbose logging for troubleshooting
openclaw config set gateway.loglevel debug
openclaw gateway restart

Environment Variables

OpenClaw reads several environment variables that override config file settings. These are useful for CI/CD pipelines, Docker containers, and production deployments where you do not want to run openclaw config set manually.

Variable	Purpose	Default
`OPENCLAW_HOME`	Root directory for OpenClaw data	~/.openclaw
`OPENCLAW_MODEL`	Override primary model globally	From config
`OPENCLAW_GATEWAY_PORT`	Override gateway port	18789
`OPENCLAW_LOG_LEVEL`	Set logging verbosity	info
`ANTHROPIC_API_KEY`	Anthropic key (overrides stored key)	From auth
`OPENAI_API_KEY`	OpenAI key (overrides stored key)	From auth

# Use environment variables in your shell profile
export OPENCLAW_HOME=/opt/openclaw
export OPENCLAW_MODEL=claude-sonnet-4-20250514
export OPENCLAW_GATEWAY_PORT=8080

# Or in a Docker container
docker run -e OPENCLAW_MODEL=gpt-4o \
  -e OPENAI_API_KEY=sk-xxx \
  -e OPENCLAW_GATEWAY_PORT=3000 \
  openclaw/gateway

Configuration File Locations

OpenClaw uses a hierarchy of configuration files. Understanding where each file lives and what it controls is essential for managing multi-agent setups.

~/.openclaw/
├── config.json              # Global config (openclaw config set writes here)
├── auth/
│   ├── anthropic.json       # Anthropic API key
│   ├── openai.json          # OpenAI API key
│   └── ollama.json          # Ollama connection settings
├── agents/
│   ├── my-agent/
│   │   ├── sessions/
│   │   │   └── sessions.json  # Conversation history
│   │   └── ...
│   └── ...
│
# Project-level files (in your workspace)
project/
├── agents/
│   ├── content-writer/
│   │   ├── SOUL.md          # Agent identity and rules
│   │   ├── HEARTBEAT.md     # Scheduled task instructions
│   │   ├── TOOLS.md         # Available tools
│   │   ├── AGENTS.md        # Team awareness
│   │   └── MEMORY.md        # Persistent knowledge
│   └── seo-analyst/
│       └── SOUL.md
└── agents.md                # Team registry (optional)

config.json Structure

Here is what a fully configured ~/.openclaw/config.json looks like after running several openclaw config set commands.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",
        "secondary": "gpt-4o-mini"
      },
      "channel": "telegram",
      "heartbeat": false,
      "session": {
        "maxhistory": 50,
        "timeout": 3600
      }
    }
  },
  "channels": {
    "telegram": {
      "bottoken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    },
    "slack": {
      "bottoken": "xoxb-your-slack-bot-token",
      "signingsecret": "your-signing-secret"
    },
    "discord": {
      "bottoken": "your-discord-bot-token"
    }
  },
  "gateway": {
    "port": 18789,
    "host": "localhost",
    "loglevel": "info"
  }
}

Common Configuration Patterns

Below are complete configuration examples for typical OpenClaw setups. Copy the commands for the setup that matches your use case.

Solo Developer Setup

One agent, one model provider, Telegram for mobile access. This is the simplest production configuration.

# Solo dev: single agent with Telegram
openclaw models auth paste-token --provider anthropic
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set channels.telegram.bottoken YOUR_TOKEN
openclaw config set agents.defaults.channel telegram
openclaw config set agents.defaults.heartbeat false
openclaw gateway start

Multi-Agent Team Setup

Multiple agents with different roles, dual model providers for redundancy, and Slack for team communication.

# Team setup: multiple agents with Slack
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openai
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set agents.defaults.model.secondary gpt-4o-mini
openclaw config set channels.slack.bottoken xoxb-YOUR-SLACK-TOKEN
openclaw config set channels.slack.signingsecret YOUR_SIGNING_SECRET
openclaw config set agents.defaults.channel slack
openclaw config set agents.defaults.heartbeat true
openclaw config set agents.defaults.heartbeat.interval 3600

# Register team agents
openclaw agents add project-manager --workspace ./agents/project-manager --non-interactive
openclaw agents add content-writer --workspace ./agents/content-writer --non-interactive
openclaw agents add seo-analyst --workspace ./agents/seo-analyst --non-interactive

openclaw gateway start

Local-Only Setup (Ollama)

Fully local setup with no cloud API calls. Ideal for privacy-sensitive environments or offline development.

# Local-only setup with Ollama
# First, make sure Ollama is running: ollama serve
openclaw models auth paste-token --provider ollama
openclaw config set agents.defaults.model.primary llama3.2
openclaw config set agents.defaults.model.secondary mistral
openclaw config set gateway.port 18789
openclaw config set agents.defaults.heartbeat false
openclaw gateway start

Production Server Setup

A hardened setup for running OpenClaw on a remote server with Telegram and Slack channels, verbose logging, and custom port binding.

# Production server setup
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openai
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set agents.defaults.model.secondary gpt-4o

# Channels
openclaw config set channels.telegram.bottoken YOUR_TELEGRAM_TOKEN
openclaw config set channels.slack.bottoken xoxb-YOUR-SLACK-TOKEN
openclaw config set agents.defaults.channel telegram

# Gateway: bind to all interfaces behind reverse proxy
openclaw config set gateway.host 0.0.0.0
openclaw config set gateway.port 8080
openclaw config set gateway.loglevel warn

# Heartbeat enabled for automated tasks
openclaw config set agents.defaults.heartbeat true
openclaw config set agents.defaults.heartbeat.interval 1800

# Session limits to manage memory
openclaw config set agents.defaults.session.maxhistory 100
openclaw config set agents.defaults.session.timeout 7200

openclaw gateway start

Troubleshooting Configuration Issues

"No model provider configured"

You have not set an API key yet. Run openclaw models auth paste-token --provider anthropic and paste your key. Then verify the model is set with openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514.

"Channel not responding after config set"

The gateway does not hot-reload channel settings. After running openclaw config set channels.telegram.bottoken, you must restart the gateway with openclaw gateway restart. This is the most common cause of channels not working after configuration.

"Config file not found"

The config file at ~/.openclaw/config.json does not exist. Run openclaw configure to create it with the interactive wizard, or run any openclaw config set command to create it automatically with that setting.

"Invalid model identifier"

The model name passed to agents.defaults.model.primary is not recognized. Check the supported model identifiers table above. Common mistakes include using claude-3.5-sonnet instead of claude-sonnet-4-20250514, or gpt4o instead of gpt-4o.

"Port already in use"

Another process is occupying the configured gateway port. Either change the port with openclaw config set gateway.port 3001 or find and kill the blocking process with lsof -i :18789.

"Environment variable overriding config"

If your openclaw config set changes seem to have no effect, check whether an environment variable is overriding the setting. Run env | grep OPENCLAW to see all active OpenClaw environment variables. Environment variables always take precedence over config.json values.

Config Set Quick Reference

Every openclaw config set command in one place for quick copy-paste access.

Command	Purpose
`openclaw config set agents.defaults.model.primary <model>`	Set primary AI model
`openclaw config set agents.defaults.model.secondary <model>`	Set fallback AI model
`openclaw config set agents.defaults.channel <name>`	Set default messaging channel
`openclaw config set agents.defaults.heartbeat <bool>`	Enable/disable heartbeat
`openclaw config set agents.defaults.heartbeat.interval <seconds>`	Set heartbeat frequency
`openclaw config set agents.defaults.session.maxhistory <n>`	Limit conversation history
`openclaw config set channels.telegram.bottoken <token>`	Set Telegram bot token
`openclaw config set channels.slack.bottoken <token>`	Set Slack bot token
`openclaw config set channels.discord.bottoken <token>`	Set Discord bot token
`openclaw config set gateway.port <number>`	Set gateway server port
`openclaw config set gateway.host <address>`	Set gateway bind address
`openclaw config set gateway.loglevel <level>`	Set logging verbosity

Frequently Asked Questions

Where is the OpenClaw config file?

The main OpenClaw configuration file is located at ~/.openclaw/config.json. This file stores all settings applied via 'openclaw config set' commands, including model providers, channel tokens, gateway settings, and agent defaults. You can view the full contents by running 'cat ~/.openclaw/config.json' or open it in any text editor. If the file does not exist, run 'openclaw configure' to create it with the interactive wizard.

How do I change the default model in OpenClaw?

Run 'openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514' to set the primary model. You can use any supported model identifier: claude-sonnet-4-20250514 or claude-opus-4-20250514 for Anthropic, gpt-4o or gpt-4o-mini for OpenAI, or a local model name like llama3.2 for Ollama. The change takes effect on the next agent invocation. You can also set a secondary fallback model with 'openclaw config set agents.defaults.model.secondary gpt-4o-mini'.

How do I set up a Telegram bot token in OpenClaw?

First, create a bot through @BotFather on Telegram and copy the token. Then run 'openclaw config set channels.telegram.bottoken YOUR_BOT_TOKEN'. After setting the token, restart the gateway with 'openclaw gateway restart' for the change to take effect. Your agents will then be accessible through the Telegram bot. You can verify the token is set by checking ~/.openclaw/config.json.

Can I use multiple AI providers in OpenClaw?

Yes. OpenClaw supports multiple providers simultaneously. Set API keys for each provider with 'openclaw models auth paste-token --provider anthropic' and 'openclaw models auth paste-token --provider openai'. Then configure your primary and secondary models from different providers: 'openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514' and 'openclaw config set agents.defaults.model.secondary gpt-4o-mini'. The secondary model acts as a fallback if the primary is unavailable.

How do I reset OpenClaw configuration?

To reset all configuration to defaults, delete the config file with 'rm ~/.openclaw/config.json' and then run 'openclaw configure' to start fresh with the interactive wizard. If you only want to reset a specific setting, use 'openclaw config set' to overwrite it with the default value. To reset agent sessions without touching configuration, delete the session files: 'rm ~/.openclaw/agents/*/sessions/sessions.json'.

What is the difference between config set and configure?

'openclaw configure' launches an interactive wizard that walks you through all settings step by step, asking questions and applying answers. It is best for first-time setup. 'openclaw config set' is a direct, non-interactive command that sets a specific key-value pair immediately, like 'openclaw config set gateway.port 3000'. Use 'config set' when you know exactly which setting to change, and 'configure' when you want guided setup or are not sure what options are available.

Skip Manual Configuration

CrewClaw generates a fully configured SOUL.md, HEARTBEAT.md, and deploy package. No config commands needed.

Build Your Agent Config