~/.openclaw/openclaw.json
```text
You can specify a custom location:
```bash
oclaw gateway --config /path/to/config.json
```text
<Info>
The config file uses JSON5 format, which supports comments and trailing commas.
</Info>
## Minimal Configuration
The simplest configuration just specifies the AI model:
```json
{
"agent": {
"model": "anthropic/claude-opus-4-6"
}
}
```text
This uses all default values:
- Gateway on port 18789
- Localhost binding
- No authentication (local-only access)
- Main agent with default settings
## Configuration Structure
The configuration file has these top-level sections:
```json
{
"agent": {}, // AI model and agent configuration
"agents": {}, // Multi-agent setup
"gateway": {}, // Gateway server settings
"channels": {}, // Messaging channel configs
"browser": {}, // Browser automation settings
"tools": {}, // Tool configuration
"cron": {}, // Scheduled jobs
"hooks": {}, // Webhook configuration
"skills": {} // Skills registry settings
}
```text
## Agent Configuration
### Basic Model Setup
```json
{
"agent": {
"model": "anthropic/claude-opus-4-6"
}
}
```text
### Model with Fallbacks
```json
{
"agent": {
"model": {
"primary": "anthropic/claude-opus-4-6",
"fallbacks": [
"anthropic/claude-sonnet-4",
"openai/gpt-5-turbo"
]
}
}
}
```text
### Agent Defaults
```json
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"model": "anthropic/claude-opus-4-6",
"thinkingLevel": "medium",
"sandbox": {
"mode": "non-main",
"scope": "session"
}
}
}
}
```text
<Note>
The `sandbox.mode: "non-main"` setting runs group chat sessions in Docker containers for security, while direct DMs use host tools.
</Note>
## Gateway Configuration
### Port and Binding
```json
{
"gateway": {
"port": 18789,
"bind": "loopback"
}
}
```text
Binding modes:
- `loopback`: 127.0.0.1 (local only, most secure)
- `lan`: 0.0.0.0 (all interfaces)
- `tailnet`: Tailscale network
- `custom`: Specific IP address
### Authentication
#### Token Authentication
```json
{
"gateway": {
"auth": {
"mode": "token",
"token": "your-secure-random-token-here"
}
}
}
```text
#### Password Authentication
```json
{
"gateway": {
"auth": {
"mode": "password",
"password": "your-secure-password"
}
}
}
```text
<Warning>
Always use authentication when binding to anything other than localhost.
</Warning>
### TLS Configuration
```json
{
"gateway": {
"tls": {
"enabled": true,
"certPath": "~/.openclaw/certs/cert.pem",
"keyPath": "~/.openclaw/certs/key.pem",
"autoGenerate": true
}
}
}
```text
### Control UI
```json
{
"gateway": {
"controlUi": {
"enabled": true,
"basePath": "/",
"allowedOrigins": ["https://yourapp.com"]
}
}
}
```text
## Channel Configuration
### WhatsApp
```json
{
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["+1234567890", "+9876543210"],
"groups": ["*"]
}
}
}
```text
<Info>
WhatsApp requires pairing via QR code. Run `openclaw channels login` to pair your device.
</Info>
### Telegram
```json
{
"channels": {
"telegram": {
"botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"allowFrom": ["@username1", "@username2"],
"groups": {
"*": {
"requireMention": true
}
}
}
}
}
```text
Get a bot token from [@BotFather](https://t.me/BotFather) on Telegram.
### Discord
```json
{
"channels": {
"discord": {
"token": "YOUR_DISCORD_BOT_TOKEN",
"allowFrom": ["user_id_1", "user_id_2"],
"guilds": {
"guild_id_here": {
"channels": ["channel_id_1", "channel_id_2"],
"requireMention": true
}
}
}
}
}
```text
### Slack
```json
{
"channels": {
"slack": {
"botToken": "xoxb-your-bot-token",
"appToken": "xapp-your-app-token",
"allowFrom": ["U01234567", "U98765432"]
}
}
}
```text
### Signal
```json
{
"channels": {
"signal": {
"account": "+1234567890",
"allowFrom": ["+9876543210"]
}
}
}
```text
<Note>
Signal requires `signal-cli` to be installed and registered.
</Note>
### iMessage (macOS only)
```json
{
"channels": {
"imessage": {
"enabled": true,
"allowFrom": ["+1234567890", "email@example.com"],
"groups": ["*"]
}
}
}
```text
<Warning>
Legacy iMessage integration requires macOS and the Messages app to be signed in. Consider using BlueBubbles for a more reliable integration.
</Warning>
## Multi-Agent Routing
Route different channels or groups to specialized agents:
```json
{
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-6"
},
"list": [
{
"id": "main",
"default": true,
"workspace": "~/.openclaw/workspace"
},
{
"id": "coding",
"model": "anthropic/claude-opus-4-6",
"workspace": "~/.openclaw/workspaces/coding",
"skills": ["git", "bash", "python"]
},
{
"id": "research",
"model": "openai/gpt-5-turbo",
"workspace": "~/.openclaw/workspaces/research",
"skills": ["browser", "search"]
}
]
},
"routing": {
"bindings": [
{
"agentId": "coding",
"match": {
"channel": "discord",
"guildId": "123456789"
}
},
{
"agentId": "research",
"match": {
"channel": "telegram",
"peer": { "kind": "user", "id": "@researcher" }
}
}
]
}
}
```text
## Security Settings
### DM Pairing (Default)
```json
{
"channels": {
"telegram": {
"dmPolicy": "pairing"
},
"discord": {
"dmPolicy": "pairing"
}
}
}
```text
Unknown senders receive a pairing code. Approve with:
```bash
oclaw pairing approve <channel> <code>
```text
### Open DM Policy
```json
{
"channels": {
"telegram": {
"dmPolicy": "open",
"allowFrom": ["*"]
}
}
}
```text
<Warning>
Only use `dmPolicy: "open"` with `allowFrom: ["*"]` if you understand the security implications. Anyone can message your bot.
</Warning>
### Sandbox for Groups
```json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session",
"workspaceAccess": "ro"
}
}
}
}
```text
This runs group chat sessions in isolated Docker containers.
## Browser Automation
```json
{
"browser": {
"enabled": true,
"color": "#FF5A36",
"headless": true,
"viewport": {
"width": 1920,
"height": 1080
}
}
}
```text
## Cron Jobs
```json
{
"cron": {
"jobs": [
{
"id": "daily-summary",
"schedule": "0 9 * * *",
"message": "Generate a summary of yesterday's activity",
"deliverTo": {
"channel": "telegram",
"target": "@me"
}
}
]
}
}
```text
Schedule format: [cron expression](https://crontab.guru/)
## Environment Variables
Environment variables override config file values:
```bash
# Gateway
export OPENCLAW_GATEWAY_PORT=18789
export OPENCLAW_GATEWAY_TOKEN=your-token
# Telegram
export TELEGRAM_BOT_TOKEN=your-bot-token
# Discord
export DISCORD_BOT_TOKEN=your-discord-token
# Slack
export SLACK_BOT_TOKEN=xoxb-your-bot-token
export SLACK_APP_TOKEN=xapp-your-app-token
```text
<Tip>
Environment variables are useful for secrets in CI/CD pipelines and Docker deployments.
</Tip>
## Configuration Validation
Validate your configuration file:
```bash
# Check for errors
oclaw config validate
# Show current config
oclaw config show
# Edit config
oclaw config edit
```text
## Configuration Management
### Get a Value
```bash
oclaw config get gateway.port
# Output: 18789
```text
### Set a Value
```bash
oclaw config set gateway.port 18790
oclaw config set agent.model "anthropic/claude-sonnet-4"
```text
### Unset a Value
```bash
oclaw config unset channels.telegram.botToken
```text
## Example Configurations
### Single User, Telegram Only
```json
{
"agent": {
"model": "anthropic/claude-opus-4-6"
},
"channels": {
"telegram": {
"botToken": "123456789:ABCdef...",
"allowFrom": ["@myusername"]
}
}
}
```text
### Multi-Channel with Security
```json
{
"agent": {
"model": "anthropic/claude-opus-4-6"
},
"gateway": {
"port": 18789,
"bind": "loopback",
"auth": {
"mode": "token",
"token": "secure-random-token"
}
},
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session"
}
}
},
"channels": {
"telegram": {
"botToken": "123456789:ABCdef...",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
}
},
"discord": {
"token": "discord-bot-token",
"dmPolicy": "pairing",
"guilds": {
"123456789": {
"requireMention": true
}
}
}
}
}
```text
### Remote VPS Deployment
```json
{
"agent": {
"model": "anthropic/claude-opus-4-6"
},
"gateway": {
"port": 18789,
"bind": "lan",
"auth": {
"mode": "password",
"password": "very-secure-password-here"
},
"tls": {
"enabled": true,
"certPath": "/etc/letsencrypt/live/gateway.example.com/cert.pem",
"keyPath": "/etc/letsencrypt/live/gateway.example.com/privkey.pem"
}
},
"channels": {
"whatsapp": {
"enabled": true,
"allowFrom": ["+1234567890"]
},
"telegram": {
"botToken": "...",
"allowFrom": ["@myuser"]
}
}
}
```text
## Next Steps
<CardGroup cols={2}>
<Card title="Add Channels" icon="plug" href="/channels/overview">
Connect WhatsApp, Telegram, Discord, and more
</Card>
<Card title="Core Concepts" icon="book" href="/concepts/architecture">
Learn about gateway, agents, and sessions
</Card>
<Card title="Security Guide" icon="shield" href="/guides/security">
Best practices for securing your gateway
</Card>
<Card title="Multi-Agent Setup" icon="users" href="/guides/multi-agent">
Route channels to specialized agents
</Card>
</CardGroup>
