What does openclaw config set do?

The 'openclaw config set' command writes a key-value pair directly to your OpenClaw configuration file at ~/.openclaw/config.json. It takes two arguments: a dot-notation key like 'agents.defaults.model.primary' and a value like 'claude-sonnet-4-20250514'. The change is written to disk immediately and takes effect on the next agent invocation or after a gateway restart for channel-related settings.

Where does openclaw config set store configuration?

All settings from 'openclaw config set' are stored in ~/.openclaw/config.json. This is the global config file for your OpenClaw installation. You can also set the OPENCLAW_HOME environment variable to change the root directory, in which case the config file lives at [OPENCLAW_HOME]/config.json. Environment variables always override values in the config file.

How do I configure different models for different OpenClaw agents?

OpenClaw supports per-agent model overrides through each agent's SOUL.md file. Add a 'model: gpt-4o' line to the agent's SOUL.md frontmatter to override the global default. The global default is set with 'openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514'. Any agent without a model override in SOUL.md will use the global default. This lets you run a mix of cheap and powerful models across your agent team.

How do I reset all OpenClaw configuration to defaults?

Run 'openclaw config reset' to wipe all settings back to factory defaults. This deletes ~/.openclaw/config.json and recreates it with default values. If you only want to reset a specific key, use 'openclaw config set' to overwrite it with the default value. To reset everything including auth tokens and session data, delete the entire ~/.openclaw directory and run 'openclaw configure' to start fresh.

OpenClaw Config Set: Complete Configuration Guide (2026)

What Is openclaw config set and Why It Matters

Every OpenClaw agent needs configuration before it can do anything. Which AI model should it use? What channel should it listen on? Where should the gateway bind? The openclaw config set command answers all of these questions by writing key-value pairs directly to your configuration file.

Unlike the interactive wizard (openclaw configure), which walks you through every setting with prompts, openclaw config set is a single, non-interactive command. You specify exactly what you want to change, and it changes it. This makes it ideal for scripting, automation, CI/CD pipelines, and quick adjustments when you know exactly which setting needs updating.

If you are managing multiple agents, switching between model providers, or deploying to production servers, understanding openclaw config set is essential. This guide covers every config key, real examples, and the troubleshooting steps for when things go wrong.

Basic Syntax

The command follows a simple pattern: the config key in dot-notation, followed by the value you want to set.

openclaw config set [key] [value]

# Examples:
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set gateway.port 8080
openclaw config set channels.telegram.bottoken 1234567890:ABCdefGHI

The key uses dot-notation to navigate the JSON structure. For example, agents.defaults.model.primary maps to { agents: { defaults: { model: { primary: "..." } } } } in the config file. The value can be a string, number, or boolean.

# String value
openclaw config set agents.defaults.channel telegram

# Number value
openclaw config set gateway.port 3000

# Boolean value
openclaw config set agents.defaults.heartbeat true

Common Config Keys Explained

Below is every commonly used config key, what it controls, and the exact command to set it. These cover the settings that 90% of OpenClaw users will need.

agents.defaults.model.primary - Set Default Model

This is the most important config key. It determines which AI model all your agents use for reasoning and responses. Every agent without a per-agent model override in SOUL.md will use this model.

# Anthropic models
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set agents.defaults.model.primary claude-opus-4-20250514

# OpenAI models
openclaw config set agents.defaults.model.primary gpt-4o
openclaw config set agents.defaults.model.primary gpt-4o-mini

# Local models via Ollama
openclaw config set agents.defaults.model.primary llama3.2
openclaw config set agents.defaults.model.primary mistral
openclaw config set agents.defaults.model.primary qwen2.5

You can also set a secondary (fallback) model with agents.defaults.model.secondary. The fallback activates when the primary model is unavailable or rate-limited.

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

# Or use a local model as fallback for zero-cost redundancy
openclaw config set agents.defaults.model.secondary llama3.2

channels.telegram.bottoken - Telegram Bot Token

Connects your OpenClaw agents to a Telegram bot. First create a bot through @BotFather on Telegram, copy the token, then set it here. After setting this value, you must restart the gateway for it to take effect.

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

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

# Restart gateway to apply channel changes
openclaw gateway restart

channels.slack.token - Slack Bot Token

Connects agents to a Slack workspace. You need both a bot token and a signing secret from the Slack API dashboard.

# Set Slack credentials
openclaw config set channels.slack.bottoken xoxb-YOUR-SLACK-BOT-TOKEN
openclaw config set channels.slack.signingsecret YOUR_SIGNING_SECRET

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

# Restart gateway
openclaw gateway restart

channels.discord.token - Discord Bot Token

Connects agents to a Discord server. Create a bot through the Discord Developer Portal, grab the token, and set it here.

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

# Set Discord as the default channel
openclaw config set agents.defaults.channel discord

# Restart gateway
openclaw gateway restart

models.auth - API Key Authentication

API keys are managed through the openclaw models auth command rather than openclaw config set. This keeps sensitive credentials in a separate auth directory instead of the main config file.

# Authenticate with Anthropic (Claude)
openclaw models auth paste-token --provider anthropic
# Paste your API key when prompted

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

# Authenticate with Ollama (local models)
openclaw models auth paste-token --provider ollama

# Verify authentication status
openclaw models auth status

Auth tokens are stored in ~/.openclaw/auth/[provider].json, separate from the main config.json file. You can authenticate with multiple providers simultaneously and switch between them by changing agents.defaults.model.primary to a model from any authenticated provider.

Config File Location and Format

Every openclaw config set command writes to a single JSON file. Understanding where this file lives and how it is structured helps with debugging and manual edits.

# Default config file location
~/.openclaw/config.json

# Full directory structure
~/.openclaw/
├── config.json              # All openclaw config set values live 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
└── logs/
    └── gateway.log          # Gateway server logs

Here is what a fully configured config.json looks like after running multiple openclaw config set commands:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-sonnet-4-20250514",
        "secondary": "gpt-4o-mini"
      },
      "channel": "telegram",
      "heartbeat": true,
      "heartbeat.interval": 3600,
      "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"
  }
}

You can edit this file directly with any text editor, but using openclaw config set is safer because it validates the key path and handles JSON formatting automatically.

How to View Current Config: openclaw config get

Before changing anything, it helps to see what is currently configured. The openclaw config get command reads and displays config values.

# View all configuration
openclaw config get

# View a specific key
openclaw config get agents.defaults.model.primary
# Output: claude-sonnet-4-20250514

# View all channel settings
openclaw config get channels
# Output: { telegram: { bottoken: "..." }, slack: { ... } }

# View gateway settings
openclaw config get gateway
# Output: { port: 18789, host: "localhost", loglevel: "info" }

# View the raw config file directly
cat ~/.openclaw/config.json

Use openclaw config get to verify your changes after running openclaw config set. This is especially useful when debugging why an agent is using the wrong model or why a channel is not responding.

How to Reset Config: openclaw config reset

If your configuration gets into a broken state, or you want to start fresh, OpenClaw provides several reset options.

# Reset all config to defaults
openclaw config reset

# Reset only a specific section
openclaw config reset gateway
openclaw config reset channels

# Nuclear option: delete everything and start from scratch
rm -rf ~/.openclaw/config.json
openclaw configure

# Reset sessions without touching config
rm ~/.openclaw/agents/*/sessions/sessions.json

Note that openclaw config reset does not delete your auth tokens. API keys stored in ~/.openclaw/auth/ are preserved. To reset those, re-run openclaw models auth paste-token with a new key.

Multi-Agent Config: Different Models Per Agent

In a multi-agent setup, you often want different agents running different models. Your PM agent might need Claude Opus for complex reasoning, while your content writer works fine with Claude Sonnet, and your monitoring agent can run on a cheap local model. OpenClaw supports this through a combination of global defaults and per-agent overrides.

Step 1: Set the Global Default

The global default applies to any agent that does not have its own model override.

# Set the default model for all agents
openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514
openclaw config set agents.defaults.model.secondary gpt-4o-mini

Step 2: Override Per Agent in SOUL.md

Add a model field to each agent's SOUL.md frontmatter to override the global default.

# agents/project-manager/SOUL.md
---
name: Project Manager
model: claude-opus-4-20250514
channel: slack
---
You are the project manager. Coordinate tasks across the team...

# agents/content-writer/SOUL.md
---
name: Content Writer
model: claude-sonnet-4-20250514
channel: slack
---
You write blog posts, documentation, and social media content...

# agents/monitor/SOUL.md
---
name: System Monitor
model: llama3.2
channel: telegram
---
You monitor server health and alert on issues...

Step 3: Verify the Configuration

# Check what model each agent will use
openclaw agent --agent project-manager --message "what model are you using?"
# Should respond with claude-opus-4-20250514

openclaw agent --agent monitor --message "what model are you using?"
# Should respond with llama3.2

# Check the global default
openclaw config get agents.defaults.model.primary
# Output: claude-sonnet-4-20250514

Per-agent model overrides in SOUL.md always take priority over the global default set with openclaw config set. This gives you fine-grained control over cost and performance across your agent team.

Environment Variables vs Config Set

OpenClaw reads configuration from three sources, in order of priority. Understanding this hierarchy prevents confusion when settings do not behave as expected.

Priority	Source	Best For
1 (highest)	Environment variables	Docker, CI/CD, temporary overrides
2	Per-agent SOUL.md	Agent-specific model and channel overrides
3 (lowest)	config.json (openclaw config set)	Global defaults for your installation

Environment variables override everything. If you set OPENCLAW_MODEL=gpt-4o in your shell, all agents will use GPT-4o regardless of what is in config.json or SOUL.md.

# Common environment variables
export OPENCLAW_HOME=/opt/openclaw           # Change config directory
export OPENCLAW_MODEL=claude-sonnet-4-20250514   # Override primary model
export OPENCLAW_GATEWAY_PORT=8080            # Override gateway port
export OPENCLAW_LOG_LEVEL=debug              # Override log level
export ANTHROPIC_API_KEY=sk-ant-xxx          # Override Anthropic key
export OPENAI_API_KEY=sk-xxx                 # Override OpenAI key

# Use env vars in Docker
docker run -e OPENCLAW_MODEL=gpt-4o \
  -e OPENAI_API_KEY=sk-xxx \
  -e OPENCLAW_GATEWAY_PORT=3000 \
  openclaw/gateway

# Use env vars for one-off testing
OPENCLAW_MODEL=gpt-4o-mini openclaw agent --agent writer --message "test"

When to use which approach:

openclaw config set for permanent settings on your machine (default model, channel tokens, gateway port)
SOUL.md overrides for per-agent differences (different model per agent, different channel per agent)
Environment variables for temporary overrides, Docker deployments, and CI/CD pipelines

Troubleshooting Common Config Errors

These are the most common issues users hit when working with openclaw config set and how to fix each one.

"No model provider configured"

You set the model name but have not authenticated with the provider yet. Run openclaw models auth paste-token --provider anthropic first, then set the model with openclaw config set agents.defaults.model.primary claude-sonnet-4-20250514.

"Channel not responding after config change"

The gateway does not hot-reload channel settings. After any openclaw config set channels.* command, you must run openclaw gateway restart. This is the number one cause of channels not working after configuration.

"Config file not found"

The file ~/.openclaw/config.json does not exist yet. Run openclaw configure to create it with the wizard, or run any openclaw config set command, which creates the file automatically.

"Invalid model identifier"

The model name does not match any known identifier. Common mistakes: claude-3.5-sonnet instead of claude-sonnet-4-20250514, or gpt4o instead of gpt-4o. Check the exact model identifiers in the model configuration section above.

"Config set has no effect"

An environment variable is likely overriding your config file value. Run env | grep OPENCLAW to check for active overrides. Also check if the agent has a per-agent override in its SOUL.md frontmatter. Priority order: environment variables, then SOUL.md, then config.json.

"Port already in use"

Another process is using 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.

"Permission denied on config file"

The config file has restrictive permissions. Fix it with chmod 644 ~/.openclaw/config.json. This commonly happens when OpenClaw was initially run with sudo. Avoid running OpenClaw commands as root.

Config Set Quick Reference

Every key you can pass to openclaw config set in one table.

Key	Example Value	Purpose
`agents.defaults.model.primary`	claude-sonnet-4-20250514	Default AI model
`agents.defaults.model.secondary`	gpt-4o-mini	Fallback AI model
`agents.defaults.channel`	telegram	Default messaging channel
`agents.defaults.heartbeat`	true	Enable scheduled tasks
`agents.defaults.heartbeat.interval`	3600	Heartbeat frequency (seconds)
`agents.defaults.session.maxhistory`	50	Max conversation messages
`agents.defaults.session.timeout`	3600	Session timeout (seconds)
`channels.telegram.bottoken`	123:ABCdef...	Telegram bot token
`channels.slack.bottoken`	xoxb-xxx	Slack bot token
`channels.slack.signingsecret`	your-secret	Slack signing secret
`channels.discord.bottoken`	your-token	Discord bot token
`gateway.port`	18789	Gateway server port
`gateway.host`	localhost	Gateway bind address
`gateway.loglevel`	info	Logging verbosity

Skip the Config Hassle

CrewClaw generates all configs for you. 103 templates, zero manual setup. Pick a template, get a fully configured SOUL.md, HEARTBEAT.md, and deploy package in 60 seconds.

Browse 103 Agent Templates