Complete Guide to the OpenClaw Configuration File openclaw.json5

Introduction

The core configuration file for OpenClaw is openclaw.json5, located by default at ~/.config/openclaw/openclaw.json5. This file uses the JSON5 format, which supports comments and more relaxed syntax, making the configuration process much more user-friendly. This article provides a thorough explanation of every configuration section and its options.

JSON5 Format Overview

JSON5 is a superset of JSON with the following additional features:

{
  // Single-line comments are supported
  /* Multi-line comments are also supported */

  // Keys don't need quotes
  gateway: {
    port: 18789,
  },

  // Trailing commas are allowed
  tags: [
    "ai",
    "assistant",
  ],

  // Single-quoted strings are supported
  name: 'OpenClaw',

  // Multi-line strings are supported
  prompt: "first line\
    second line",
}

If you're not familiar with JSON5, just think of it as "JSON with comments."

Configuration File Paths

You can also specify a custom path via an environment variable:

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5
openclaw up

Full Configuration Structure Overview

{
  gateway: { /* Gateway settings */ },
  models: { /* Model configuration */ },
  channels: { /* Channel integration */ },
  skills: { /* Skill plugins */ },
  persona: { /* AI persona */ },
  logging: { /* Logging settings */ },
  security: { /* Security settings */ },
  advanced: { /* Advanced options */ },
}

Let's go through each section in detail.

gateway: Gateway Settings

The gateway is the core entry point of OpenClaw, handling all HTTP requests and channel messages.

{
  gateway: {
    // Listening port, default 18789
    port: 18789,

    // Listening address
    // "127.0.0.1" for local access only
    // "0.0.0.0" to allow access from any network
    host: "0.0.0.0",

    // Dashboard password (recommended for production)
    dashboardPassword: "your-strong-password",

    // API key (for external calls to the OpenClaw API)
    apiKey: "your-api-key",

    // Request timeout (milliseconds)
    timeout: 120000,

    // Maximum request body size
    maxBodySize: "10mb",

    // CORS settings
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

Key Parameter Reference

models: Model Configuration

The model configuration defines which AI models OpenClaw uses and how to call them.

{
  models: {
    // Default model provider
    default: "claude",

    // Provider configurations
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.anthropic.com",  // Optional, custom API endpoint
      },

      openai: {
        apiKey: "sk-xxxxx",
        model: "gpt-4o",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.openai.com/v1",
      },

      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1",
        maxTokens: 2048,
      },

      gemini: {
        apiKey: "AIzaSyxxxxx",
        model: "gemini-2.0-flash",
        maxTokens: 4096,
      },

      openrouter: {
        apiKey: "sk-or-xxxxx",
        model: "anthropic/claude-sonnet-4-20250514",
        baseUrl: "https://openrouter.ai/api/v1",
      },
    },

    // Model routing rules (see the multi-model switching tutorial for details)
    routing: {
      rules: [],
      fallback: "claude",
    },
  },
}

Required Parameters by Provider

channels: Channel Integration

The channel configuration defines which messaging platforms OpenClaw connects to.

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      // WhatsApp Business API configuration
      accessToken: "your-access-token",
      verifyToken: "your-verify-token",
      webhookPath: "/webhook/whatsapp",
    },

    telegram: {
      enabled: true,
      token: "123456:ABC-DEF...",
      // Optional: restrict allowed users
      allowedUsers: [12345678, 87654321],
      // Optional: restrict allowed groups
      allowedGroups: [-100123456789],
    },

    discord: {
      enabled: true,
      token: "your-discord-bot-token",
      allowedChannels: ["general", "ai-chat"],
    },

    slack: {
      enabled: true,
      appToken: "xapp-xxxxx",
      botToken: "xoxb-xxxxx",
    },

    // More channels...
    // imessage, signal, teams, googlechat, matrix, line, irc
  },
}

skills: Skill Plugins

Skills are OpenClaw's extension mechanism, stored as SKILL.md files in the ~/.openclaw/skills/ directory.

{
  skills: {
    // Skill file directory
    directory: "~/.openclaw/skills",

    // List of enabled skills (empty means all enabled)
    enabled: [
      "weather",
      "calculator",
      "translator",
    ],

    // List of disabled skills
    disabled: [],

    // MCP Server integration
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      },
      web: {
        command: "npx",
        args: ["-y", "@anthropic/mcp-server-web"],
      },
    },
  },
}

persona: AI Persona

The persona configuration determines the AI assistant's personality and response style.

{
  persona: {
    // System prompt
    systemPrompt: "你是一个友好、专业的AI助手，名叫小智。你会用简洁明了的中文回答问题。",

    // Persona name
    name: "小智",

    // Response language (auto for automatic detection)
    language: "zh-CN",

    // Tone style: formal, casual, friendly, professional
    tone: "friendly",

    // Per-channel persona overrides (override global settings)
    channelOverrides: {
      telegram: {
        systemPrompt: "你是Telegram群组的管理助手...",
        tone: "casual",
      },
      slack: {
        systemPrompt: "你是团队的工作助手，回复专业简洁...",
        tone: "professional",
      },
    },
  },
}

logging: Logging Settings

{
  logging: {
    // Log level: debug, info, warn, error
    level: "info",

    // Log file path (empty for console output only)
    file: "~/.openclaw/logs/openclaw.log",

    // Maximum log file size
    maxSize: "10m",

    // Number of log files to retain
    maxFiles: 5,

    // Whether to colorize console output
    colorize: true,

    // Log format: json, text
    format: "text",
  },
}

security: Security Settings

{
  security: {
    // Enable rate limiting
    rateLimit: {
      enabled: true,
      maxRequests: 60,     // Maximum requests per minute
      windowMs: 60000,     // Window duration (milliseconds)
    },

    // IP whitelist (empty means no restriction)
    ipWhitelist: [],

    // IP blacklist
    ipBlacklist: [],

    // Enable HTTPS (requires certificates)
    tls: {
      enabled: false,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem",
    },
  },
}

advanced: Advanced Options

{
  advanced: {
    // Number of worker threads (0 for auto)
    workers: 0,

    // Message queue size
    queueSize: 100,

    // Maximum number of messages in context memory
    maxContextMessages: 20,

    // Maximum tokens in context memory
    maxContextTokens: 8000,

    // Data storage backend: memory, sqlite, redis
    storage: "sqlite",

    // SQLite database path
    dbPath: "~/.openclaw/data/openclaw.db",

    // Redis connection (if storage is redis)
    redis: {
      url: "redis://localhost:6379",
      db: 0,
    },
  },
}

Environment Variable Overrides

Sensitive fields in the configuration file can be overridden with environment variables, avoiding the need to store keys directly in the file:

# Model API keys
export OPENCLAW_CLAUDE_API_KEY="sk-ant-xxxxx"
export OPENCLAW_OPENAI_API_KEY="sk-xxxxx"

# Channel tokens
export OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF..."
export OPENCLAW_DISCORD_TOKEN="your-discord-token"

# Gateway password
export OPENCLAW_DASHBOARD_PASSWORD="your-password"

Reference them in the configuration file using $env:

{
  models: {
    providers: {
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
}

Configuration Validation

After modifying the configuration file, you can validate it before starting:

# Check configuration file syntax and required fields
openclaw doctor

# Validate configuration only (without starting the service)
openclaw doctor --config-only

Minimal Configuration Example

If you only need the most basic functionality, the configuration file can be very concise:

{
  models: {
    default: "claude",
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      token: "your-telegram-bot-token",
    },
  },
}

Options not explicitly configured will use their default values.

Summary

openclaw.json5 is the core configuration file for OpenClaw, using the human-friendly JSON5 format with support for comments and flexible syntax. Once you understand the purpose of each section, you can precisely tune OpenClaw's behavior to meet your needs. We recommend starting with a minimal configuration and gradually adding the features you need. After making changes, don't forget to run openclaw doctor to validate, then use openclaw restart to reload.