OpenClaw Workspace Configuration Guide

The Configuration File

openclaw.json is the central configuration file for your OpenClaw instance. It controls everything from channel connections to security permissions.

File Location

~/.openclaw/openclaw.json      # Global configuration
./openclaw.json                 # Workspace-local override

Workspace-local settings override global settings.

Configuration Sections

Model Configuration

{
  "model": "anthropic/claude-sonnet-4-5",
  "provider": "openrouter",
  "api_key_env": "OPENROUTER_API_KEY",
  "temperature": 0.7,
  "max_tokens": 4096
}

Channel Configuration

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "BOT_TOKEN"
    },
    "whatsapp": {
      "enabled": true
    }
  }
}

Tool Permissions

{
  "tools": {
    "read": { "enabled": true },
    "write": { "enabled": true, "confirm": true },
    "shell": { "enabled": true, "confirm": true },
    "browser": { "enabled": false }
  }
}

Skills Configuration

{
  "skills": {
    "load": {
      "extraDirs": ["/path/to/custom/skills"]
    },
    "entries": {
      "web-researcher": { "enabled": true },
      "shell-commander": {
        "enabled": true,
        "env": { "GITHUB_TOKEN": "your-token" }
      }
    }
  }
}

Context Settings

{
  "context": {
    "max_history_messages": 50,
    "persist_history": true,
    "system_prompt": "Your custom system prompt here"
  }
}

Environment Variables

Sensitive values (API keys, tokens) should use environment variables:

{
  "api_key_env": "OPENROUTER_API_KEY"
}

Set the environment variable in your shell profile or .env file.

Validating Configuration

openclaw config validate

This checks for syntax errors, missing required fields, and invalid values.

Hot Reloading

Some settings can be changed without restarting:

openclaw config reload

Channel and model changes typically require a restart.