Skip to main content

​
openclaw config

Manage OpenClaw configuration values programmatically.

​
Usage

openclaw config [command] [options]
Run without a subcommand to launch the interactive setup wizard: 
openclaw config

​
Commands

​
get

Get a configuration value by dot path. 
openclaw config get <path> [options]
​
path
string
required
Configuration path using dot notation (e.g., gateway.port)
​
--json
boolean
Output in JSON format

​
set

Set a configuration value by dot path. 
openclaw config set <path> <value> [options]
​
path
string
required
Configuration path using dot notation
​
value
string
required
Value to set (JSON5 or raw string)
​
--json
boolean
Parse value as JSON5 (required for objects/arrays)

​
unset

Remove a configuration value by dot path. 
openclaw config unset <path>
​
path
string
required
Configuration path using dot notation

​
Path Notation

Configuration paths use dot notation with support for:
  • Nested objects: gateway.auth.token
  • Arrays: channels.telegram.accounts[0].token
  • Bracket notation: gateway["auth"]["token"]
  • Escaped dots: path.with\.dot.in\.key

​
Examples

# Get gateway port
openclaw config get gateway.port

# Get with JSON output
openclaw config get gateway.auth --json

# Get nested value
openclaw config get agents.defaults.model.primary

# Get array element
openclaw config get channels.telegram.accounts[0].token

# Set simple value
openclaw config set gateway.port 18790

# Set string value
openclaw config set gateway.mode local

# Set object (requires --json)
openclaw config set gateway.auth '{"mode":"token","token":"secret"}' --json

# Set array (requires --json)
openclaw config set agents.defaults.models '["gpt-4","claude-3"]' --json

# Set nested value
openclaw config set agents.defaults.model.primary "anthropic:claude-4.5-sonnet"

# Remove a value
openclaw config unset gateway.auth.password

# Remove nested value
openclaw config unset channels.telegram.accounts[0]

# Remove entire section
openclaw config unset channels.discord

# Launch interactive wizard
openclaw config

# Configure specific sections
openclaw config --section gateway --section channels
After modifying configuration, restart the gateway for changes to take effect: openclaw gateway restart

​
Common Configuration Paths

​
Gateway

  • gateway.mode - Gateway mode (local or remote)
  • gateway.port - WebSocket port (default: 18789)
  • gateway.bind - Bind mode (loopback, lan, tailnet, auto, custom)
  • gateway.auth.mode - Auth mode (token, password, none)
  • gateway.auth.token - Auth token
  • gateway.auth.password - Auth password

​
Agents

  • agents.defaults.workspace - Default workspace directory
  • agents.defaults.model.primary - Primary model (e.g., anthropic:claude-4.5-sonnet)
  • agents.defaults.thinkingDefault - Default thinking level
  • agents.defaults.contextTokens - Max context tokens

​
Channels

  • channels.telegram.accounts.default.token - Telegram bot token
  • channels.discord.accounts.default.token - Discord bot token
  • channels.slack.accounts.default.botToken - Slack bot token
  • channels.slack.accounts.default.appToken - Slack app token

​
Discovery

  • discovery.wideArea.domain - Wide-area discovery domain

​
JSON5 Syntax

When setting complex values, use JSON5 syntax with --json: 
# Object with comments
openclaw config set gateway.auth '{
  mode: "token",  // Use token auth
  token: "secret"
}' --json

# Array
openclaw config set agents.defaults.models '["gpt-4", "claude-3"]' --json

# Nested structure
openclaw config set channels.telegram '{
  accounts: {
    default: {
      token: "123456:ABC-DEF",
      enabled: true
    }
  }
}' --json

​
Configuration File

The configuration file is located at ~/.openclaw/openclaw.json and supports:
  • JSON5 syntax - Comments, trailing commas, unquoted keys
  • Environment variables - ${ENV_VAR} substitution
  • Includes - $include: "path/to/other.json5"

​
Example Configuration

{
  // Gateway configuration
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  
  // Agent defaults
  agents: {
    defaults: {
      workspace: "~/openclaw-workspace",
      model: {
        primary: "anthropic:claude-4.5-sonnet"
      },
      thinkingDefault: "medium",
      contextTokens: 200000
    }
  },
  
  // Channel configurations
  channels: {
    telegram: {
      accounts: {
        default: {
          token: "${TELEGRAM_BOT_TOKEN}"
        }
      }
    }
  }
}

​
Environment Variable Substitution

Use ${VAR_NAME} in config values to reference environment variables: 
{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  channels: {
    telegram: {
      accounts: {
        default: {
          token: "${TELEGRAM_BOT_TOKEN}"
        }
      }
    }
  }
}

​
Configuration Validation

The CLI validates configuration on load. Check for errors with: 
openclaw doctor
Common validation issues:
  • Invalid JSON5 syntax
  • Missing required fields
  • Invalid enum values
  • Type mismatches

​
Backup and Migration

The CLI creates automatic backups when writing config: 
# Backups are stored as
~/.openclaw/openclaw.json.bak
To manually backup: 
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
  • configure - Interactive configuration wizard
  • setup - Initialize local config and workspace
  • doctor - Validate and repair configuration