Chapter 12: Configuration File Deep Dive

Everything about how OpenClaw behaves is controlled by a single JSON file: ~/.openclaw/openclaw.json. This chapter documents every field, every option, and every pattern you need to configure OpenClaw for any scenario — from a personal single-user setup to a multi-team enterprise deployment.

File Location

OS	Path
Linux / macOS	`~/.openclaw/openclaw.json`
Windows	`C:\Users\<username>\.openclaw\openclaw.json`

Create the directory if it does not exist:

mkdir -p ~/.openclaw
touch ~/.openclaw/openclaw.json

Minimal Valid Configuration

The smallest openclaw.json that actually works:

{
  "agents": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  },
  "workspaces": [
    {
      "id": "personal",
      "agent": "default",
      "allowlist": ["*"]
    }
  ]
}

Full Configuration Reference

Top-Level Structure

{
  "version": "1.4",
  "logLevel": "info",
  "port": 3000,
  "host": "0.0.0.0",
  "baseUrl": "https://your-domain.com",
  "sessionStore": "memory",
  "agents": { ... },
  "channels": { ... },
  "workspaces": [ ... ],
  "skills": { ... },
  "security": { ... }
}

Field	Type	Default	Description
`version`	string	—	Config schema version (for future migrations)
`logLevel`	string	`"info"`	One of: `error`, `warn`, `info`, `debug`, `trace`
`port`	number	`3000`	HTTP port the gateway listens on
`host`	string	`"0.0.0.0"`	Bind address (`127.0.0.1` for localhost-only)
`baseUrl`	string	—	Public HTTPS URL of your gateway (for webhooks)
`sessionStore`	string	`"memory"`	Session storage: `memory` or `redis`

The `agents` Block

Defines available AI models. Keys are agent identifiers used in workspace config.

{
  "agents": {
    "claude-sonnet": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "maxTokens": 8192,
      "temperature": 0.3,
      "systemPrompt": "You are a helpful AI assistant."
    },
    "claude-opus": {
      "provider": "anthropic",
      "model": "claude-opus-4-7",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "maxTokens": 16384,
      "temperature": 0.2
    },
    "gpt4o": {
      "provider": "openai",
      "model": "gpt-4o",
      "apiKey": "${OPENAI_API_KEY}",
      "maxTokens": 8192
    },
    "gemini-pro": {
      "provider": "google",
      "model": "gemini-1.5-pro",
      "apiKey": "${GOOGLE_AI_API_KEY}"
    },
    "local-llama": {
      "provider": "ollama",
      "model": "llama3",
      "baseUrl": "http://localhost:11434",
      "maxTokens": 4096
    }
  }
}

Agent Fields

Field	Type	Description
`provider`	string	`anthropic`, `openai`, `google`, `ollama`, `azure-openai`
`model`	string	Model identifier (provider-specific)
`apiKey`	string	API key — use `${ENV_VAR}` syntax
`baseUrl`	string	Override base URL (for Azure OpenAI, local models, proxies)
`maxTokens`	number	Maximum output tokens per response
`temperature`	number	0.0 = deterministic, 1.0 = creative
`systemPrompt`	string	Default system prompt for this agent
`topP`	number	Nucleus sampling (optional)
`timeout`	number	API request timeout in milliseconds

Supported Providers

Provider	`provider` value	Models
Anthropic	`anthropic`	claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001
OpenAI	`openai`	gpt-4o, gpt-4-turbo, gpt-3.5-turbo
Google	`google`	gemini-1.5-pro, gemini-1.5-flash
Ollama	`ollama`	llama3, mistral, codellama, etc.
Azure OpenAI	`azure-openai`	Deployment names from your Azure resource

The `channels` Block

Each channel has its own configuration object. Only channels with "enabled": true are started.

{
  "telegram": {
    "enabled": true,
    "token": "${TELEGRAM_BOT_TOKEN}",
    "mode": "polling",
    "pollInterval": 1000,
    "allowGroups": false,
    "groupTrigger": "@mybot",
    "enableInlineKeyboard": true
  }
}

WhatsApp Business API

{
  "whatsapp": {
    "enabled": true,
    "method": "business-api",
    "phoneNumberId": "123456789",
    "wabaId": "987654321",
    "accessToken": "${WHATSAPP_ACCESS_TOKEN}",
    "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
    "webhookPath": "/webhooks/whatsapp"
  }
}

WhatsApp Baileys

{
  "whatsapp": {
    "enabled": true,
    "method": "baileys",
    "sessionDir": "~/.openclaw/sessions/whatsapp"
  }
}

Slack

{
  "slack": {
    "enabled": true,
    "botToken": "${SLACK_BOT_TOKEN}",
    "signingSecret": "${SLACK_SIGNING_SECRET}",
    "appToken": "${SLACK_APP_TOKEN}",
    "mode": "socket",
    "respondToMentions": true,
    "respondToDMs": true,
    "respondToThreads": true
  }
}

Discord

{
  "discord": {
    "enabled": true,
    "token": "${DISCORD_BOT_TOKEN}",
    "respondToMentions": true,
    "respondToDMs": true,
    "prefix": "!ai",
    "allowedChannelIds": [],
    "ignoreBots": true
  }
}

Microsoft Teams

{
  "teams": {
    "enabled": true,
    "appId": "${TEAMS_APP_ID}",
    "appPassword": "${TEAMS_APP_PASSWORD}",
    "webhookPath": "/webhooks/teams"
  }
}

iMessage

{
  "imessage": {
    "enabled": true,
    "imessageRestUrl": "http://localhost:8000",
    "pollInterval": 2000
  }
}

Signal

{
  "signal": {
    "enabled": true,
    "phoneNumber": "+12125550100",
    "socketPath": "/tmp/signal-cli.sock",
    "pollInterval": 2000
  }
}

The `workspaces` Array

Each workspace is an object in this array. Order matters — first match wins.

{
  "workspaces": [
    {
      "id": "admin",
      "label": "Administrators",
      "agent": "claude-opus",
      "systemPrompt": "You have full access. Users are senior developers.",
      "temperature": 0.2,
      "maxTokens": 16384,
      "channels": ["slack", "telegram"],
      "allowlist": ["U01ADMIN123"],
      "skills": ["bash", "files", "web-search", "github", "database"],
      "sessionTimeout": 3600,
      "adminCommands": true,
      "disabledCommands": []
    },
    {
      "id": "team",
      "label": "Development Team",
      "agent": "claude-sonnet",
      "channels": ["slack"],
      "allowlist": ["U01DEV1", "U01DEV2", "U01DEV3"],
      "skills": ["bash", "files", "web-search"],
      "sessionTimeout": 1800
    },
    {
      "id": "public",
      "label": "General Access",
      "agent": "claude-haiku",
      "channels": ["telegram"],
      "allowlist": ["*"],
      "skills": ["web-search"],
      "sessionTimeout": 600,
      "disabledCommands": ["/restart", "/reload", "/sessions", "/logs"]
    }
  ]
}

Workspace Fields

Field	Type	Description
`id`	string	Unique workspace identifier
`label`	string	Human-readable name (optional)
`agent`	string	Agent key from the `agents` block
`systemPrompt`	string	Override agent's default system prompt
`temperature`	number	Override agent's default temperature
`maxTokens`	number	Override agent's default maxTokens
`channels`	array	Channels this workspace accepts (empty = all)
`allowlist`	array	Authorized channel user IDs (`"*"` = everyone)
`skills`	array	Skills available to the agent
`sessionTimeout`	number	Session expiry in seconds
`adminCommands`	boolean	Allow admin-level commands in this workspace
`disabledCommands`	array	Commands not available in this workspace

The `skills` Block

Global skill configuration. Individual skills may have their own settings:

{
  "skills": {
    "bash": {
      "enabled": true,
      "allowedCommands": ["ls", "cat", "grep", "find", "git", "npm", "python3"],
      "blockedCommands": ["rm -rf", "sudo", "chmod 777"],
      "timeout": 30000,
      "workingDirectory": "/home/user/projects"
    },
    "files": {
      "enabled": true,
      "allowedPaths": ["/home/user/projects", "/tmp"],
      "blockedPaths": ["/etc", "/root", "/var/log"],
      "maxFileSize": "10MB"
    },
    "web-search": {
      "enabled": true,
      "provider": "brave",
      "apiKey": "${BRAVE_SEARCH_API_KEY}",
      "maxResults": 5
    },
    "github": {
      "enabled": true,
      "token": "${GITHUB_TOKEN}",
      "allowedRepos": ["myorg/repo1", "myorg/repo2"]
    }
  }
}

The `security` Block

{
  "security": {
    "rateLimiting": {
      "enabled": true,
      "maxRequestsPerMinute": 20,
      "maxRequestsPerHour": 200
    },
    "sandboxMode": {
      "enabled": false,
      "allowedDomains": ["api.github.com", "npmjs.com"]
    },
    "unauthorizedResponse": "You are not authorized to use this service.",
    "silenceUnauthorized": false
  }
}

Environment Variable Syntax

Use ${VARIABLE_NAME} anywhere in the config to inject environment variables:

{
  "agents": {
    "claude": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

This keeps secrets out of the config file. Set variables in your shell profile, .env file, or system environment.

Applying Config Changes

Change Type	How to Apply
New workspace or agent	`openclaw restart`
Channel token update	`openclaw channel restart <channel>`
Allowlist change	`openclaw reload` (no full restart needed)
Log level change	`openclaw reload`
Skills change	`openclaw restart`

Next: Chapter 13 — Security, Pairing & Allowlists — How OpenClaw authenticates users and keeps unauthorized access out.