# Configuration

## Overview

OpenClaw reads an optional JSON5 config from `~/.openclaw/openclaw.json` with support for comments and trailing commas. The system uses sensible defaults when the file is absent, though configuration becomes necessary for:

- Restricting bot access by channel and sender
- Managing group allowlists and mention behaviors
- Customizing message prefixes
- Setting agent workspaces
- Tuning embedded agent defaults and session behavior
- Defining per-agent identity settings

## Validation & Error Handling

OpenClaw only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start for safety.

When validation fails, diagnostic commands remain available. Running `openclaw doctor` reveals specific issues, while `openclaw doctor --fix` applies migrations without requiring explicit confirmation.

## Configuration Management

### Apply & Restart

The `config.apply` RPC validates and writes the complete configuration in one operation, replacing the entire config file. Users should maintain backups before updates.

### Partial Updates

The `config.patch` method merges changes without affecting unrelated keys, using JSON merge patch semantics where objects combine recursively and `null` deletes entries.

## Environment Variables

OpenClaw loads environment variables from:

- Parent process (shell, launchd/systemd, CI)
- `.env` in the current working directory
- Global `.env` from `~/.openclaw/.env`

Variables can be referenced in config strings using `${VAR_NAME}` syntax, with substitution occurring at load time before validation.

## Multi-Agent Routing

Multiple isolated agents can run within a single Gateway instance, each with separate workspaces and sessions. Inbound messages route to agents via bindings based on channel, account, and peer matching with deterministic precedence rules.

Per-agent configuration allows mixed access levels - from full access (personal agents) to restricted tools and read-only workspaces (family/public agents).

## Channel Configuration

### WhatsApp

Supports DM policies (pairing, allowlist, open, disabled), multi-account setup, read receipt control, and group allowlists with mention gating.

### Telegram

Includes custom commands, draft streaming, reaction notifications, and per-topic configuration for groups.

### Discord

Offers guild/channel-specific settings, reaction modes, thread isolation, and action gating with media size limits.

### Additional Channels

Google Chat, Slack, Mattermost, Signal, iMessage, and Microsoft Teams each support webhooks, tokens, or native integrations with channel-specific mention and reaction handling.

## Agent Defaults

### Models

The embedded agent runtime is controlled via `agents.defaults`, which manages model selection, thinking modes, verbose output, and timeouts.

Primary and fallback models support provider/model format (e.g., `anthropic/claude-opus-4-6`). Model catalogs include built-in aliases and custom provider definitions.

### Sandbox Configuration

Optional Docker sandboxing isolates non-main sessions from the host system, with configurable scopes (session, agent, shared), workspace access levels, and optional browser support via Chromium and CDP.

### Thinking & Reasoning

`thinkingDefault` and `verboseDefault` control extended reasoning behavior, while `contextPruning` manages token usage by pruning old tool results before LLM requests.

## Session Management

Sessions can scope to per-sender, per-channel-peer, or per-account-channel-peer models. Reset policies support daily schedules and idle thresholds, with per-session-type overrides. Identity links map canonical IDs across channels for unified conversations.

## Tools & Access Control

Tool policies use allow/deny lists with group shorthands (`group:fs`, `group:runtime`, `group:sessions`). Elevated access requires explicit allowlisting by channel and sender. Per-agent tool restrictions further limit capabilities in multi-agent setups.

## Advanced Features

- **TTS**: Auto text-to-speech for outbound replies via ElevenLabs or OpenAI
- **Block Streaming**: Chunked message delivery for long responses
- **Typing Indicators**: Configurable modes (never, instant, thinking, message)
- **Heartbeats**: Periodic agent runs with optional memory flush before compaction
- **Skills**: Bundled and workspace skill management with per-skill configuration
- **Plugins**: Extension loading with allow/deny lists and per-plugin config

## Recommended Starting Configuration

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