openclaw config

Get, set, and manage OpenClaw configuration

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 Values

# 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

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

Related Commands

• configure - Interactive configuration wizard
• setup - Initialize local config and workspace
• doctor - Validate and repair configuration