OpenClaw Configuration

Configure OpenClaw on any OS, VM, or deployment target via natural language.

First Step: Fetch Latest Docs Index

Always fetch the latest docs index before doing anything:

curl -fsSL https://docs.openclaw.ai/llms.txt

Use this index to find the right documentation page for the user's specific need, then fetch that page with read_web_page for up-to-date details.

Overview

OpenClaw is an AI chat gateway that connects AI agents with chat apps (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, etc.). Configuration lives at ~/.openclaw/openclaw.json (JSON5 format -- comments and trailing commas allowed).

Workflow

1. Determine User's Goal

Ask what they want:

• Fresh install? -> Guide through install + onboard + config
• Edit existing config? -> Read their current config first, then modify
• Add a channel? -> Add the channel block to their config
• Change models/providers? -> Update agents.defaults.model and models.providers
• Set up sandboxing? -> Configure agents.defaults.sandbox
• Cron/automation? -> Configure cron, hooks, or automation

2. Read Existing Config (if editing)

cat ~/.openclaw/openclaw.json 2>/dev/null || echo "No config found"

Also check:

openclaw doctor 2>/dev/null  # diagnose issues
openclaw status 2>/dev/null  # gateway status

3. Generate or Edit Config

• Config format: JSON5 (comments + trailing commas OK)
• All fields optional -- OpenClaw uses safe defaults when omitted
• Config hot-reloads (no restart needed for most changes)
• Use $include to split config into multiple files

4. Validate

After writing config, run:

openclaw doctor

Fix any issues it reports. Use openclaw doctor --fix for auto-repair.

Installation (any platform)

macOS / Linux / WSL2

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)

iwr -useb https://openclaw.ai/install.ps1 | iex

Docker

./docker-setup.sh

Or manually:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

npm / pnpm

npm install -g openclaw@latest
openclaw onboard --install-daemon

From source

git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

After install, always run openclaw onboard --install-daemon to set up auth, gateway, and channels.

Config Structure Quick Reference

See references/config-reference.md for the complete field-by-field reference. See references/config-examples.md for common patterns and examples.

Minimal Config

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Top-Level Sections

Section	Purpose
identity	Bot name, theme, emoji
agents	Model selection, workspace, sandbox, heartbeat
channels	WhatsApp, Telegram, Discord, Slack, Signal, iMessage, etc.
session	Session scope, reset, DM scope, pruning
models	Custom providers, local models, base URLs
tools	Tool allow/deny, exec settings, elevated mode
cron	Scheduled jobs
hooks	Inbound webhooks
gateway	Port, bind, auth, reload, TLS
logging	Log level, file, redaction
messages	TTS, prefix, reactions
env	Inline env vars, shell env
auth	OAuth profiles, API key order
secrets	Secret providers (env, file, exec)
skills	Skill loading, entries, bundled skills
browser	Browser tool config
plugins	Plugin loading and config

Channel DM Policy Pattern (all channels share this)

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // for allowlist/open
    },
  },
}

Model Configuration

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

Custom / Local Model Providers

{
  models: {
    mode: "merge",
    providers: {
      "my-provider": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "my-model",
            name: "My Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

Sandbox Configuration

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "session",    // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
      },
    },
  },
}

Build sandbox image: scripts/sandbox-setup.sh

Session Configuration

{
  session: {
    dmScope: "per-channel-peer", // main | per-peer | per-channel-peer | per-account-channel-peer
    reset: {
      mode: "daily",   // daily | idle
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

Config Includes (split into files)

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

Environment Variables in Config

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Only uppercase names matched. Missing/empty vars throw errors. Escape with $${VAR}.

Key Environment Variables

Variable	Purpose
OPENCLAW_HOME	Home directory for path resolution
OPENCLAW_STATE_DIR	Override state directory
OPENCLAW_CONFIG_PATH	Override config file path
OPENCLAW_HIDE_BANNER	Hide CLI banner

Gateway Hot Reload

Most config changes hot-apply without restart. Fields requiring restart:

• gateway.* (port, bind, auth, TLS)
• discovery, canvasHost, plugins

Reload mode config:

{ gateway: { reload: { mode: "hybrid", debounceMs: 300 } } }
// modes: hybrid (default) | hot | restart | off

Programmatic Config Updates

# Read current config
openclaw gateway call config.get --params '{}'

# Patch (partial update, preferred)
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

# Full replace
openclaw gateway call config.apply --params '{
  "raw": "<full config>",
  "baseHash": "<hash>"
}'

Detailed References

For specific topics, read the appropriate reference file:

• Full config field reference: Read references/config-reference.md
• Config examples and patterns: Read references/config-examples.md
• Docs index for latest pages: Fetch https://docs.openclaw.ai/llms.txt
• Specific channel setup: Fetch https://docs.openclaw.ai/channels/<channel>.md
• Provider setup: Fetch https://docs.openclaw.ai/providers/<provider>.md

When in doubt about any specific feature, fetch the relevant page from https://docs.openclaw.ai/ using the llms.txt index.