Skip to main content

OpenClaw Configuration Guide

· 3 min read

This document is a complete reference for the OpenClaw openclaw.json configuration file, revised and expanded from the official documentation.

Contents​

Basic structure​

OpenClaw uses JSON5 format, which supports comments and trailing commas.

{
  // Identity
  "identity": {},

  // Agent configuration (core)
  "agents": {
    "defaults": {},
    "list": []
  },

  // Communication channels
  "channels": {},

  // Tool permissions
  "tools": {},

  // Session management
  "session": {},

  // Model providers and custom models
  "models": {},

  // Authentication
  "auth": {},

  // Security sandbox
  "sandbox": {},

  // Logging
  "logging": {},

  // Gateway
  "gateway": {},

  // Scheduled tasks
  "cron": {},

  // Webhook hooks
  "hooks": {},

  // Environment variables
  "env": {}
}

Core module configuration​

1. Identity (identity)​

"identity": {
  "name": "AssistantName",           // Display name, used for @mentions
  "theme": "professional assistant", // Personality description, affects system prompt
  "emoji": "🤖",                     // Default reaction emoji
  "avatar": "images/avatar.png"      // Avatar image path or URL
}

2. Agents (agents)​

Defaults and multi-agent setup​

"agents": {
  "defaults": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4-5",
      "fallbacks": ["openai/gpt-5-mini"]
    },
    "maxConcurrent": 4,
    "contextPruning": {
      "enabled": true,
      "maxLength": 8000
    },
    "heartbeat": {
        "every": "30m",
        "target": "last"
    }
  },
  "list": [
    {
      "id": "monitor",
      "model": {
        "primary": "openai/gpt-5-nano"
      },
      "systemPromptFile": "workspace/agents/monitor.md",
      "maxConcurrent": 2
    },
    {
      "id": "researcher",
      "model": {
        "primary": "anthropic/claude-opus"
      },
      "tools": {
        "web": { "search": { "enabled": true } }
      }
    }
  ]
}

3. Channels (channels)​

Telegram configuration​

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
    "dmPolicy": "pairing",              // pairing | allowlist | open | disabled
    "allowFrom": ["tg:123456789"],
    "groupPolicy": "allowlist",
    "allowedGroups": ["-1001234567890"]
  },
  "modelByChannel": {
      "telegram": {
          "-1001234567890": "anthropic/claude-opus"
      }
  }
}

4. Tools (tools)​

"tools": {
  "web": {
    "search": {
      "enabled": true,
      "provider": "brave",
      "apiKey": "YOUR_BRAVE_API_KEY"
    },
    "browse": {
      "enabled": true,
      "headless": true
    }
  },
  "filesystem": {
    "read": true,
    "write": false,
    "execute": false
  }
}

5. Session (session)​

"session": {
  "dmScope": "per-channel-peer",      // main | per-peer | per-channel-peer | per-account-channel-peer
  "reset": {
      "mode": "daily",
      "atHour": 4
  },
  "threadBindings": {
      "enabled": true,
      "idleHours": 24
  },
  "maxHistoryLength": 50
}

6. Models (models)​

"models": {
  "providers": {
    "local-ollama": {
      "baseUrl": "http://localhost:11434/api/generate",
      "api": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "contextWindow": 8192
        }
      ]
    }
  }
}

7. Authentication (auth)​

"auth": {
  "profiles": {
    "openrouter": {
      "provider": "openrouter",
      "apiKey": "YOUR_OPENROUTER_KEY"
    },
    "anthropic": {
      "provider": "anthropic",
      "apiKey": "YOUR_ANTHROPIC_KEY"
    }
  }
}

Security configuration​

Sandbox (sandbox)​

"sandbox": {
  "mode": "agent",                 // off | agent | all
  "scope": "session",               // session | agent | shared
  "docker": {
    "enabled": true,
    "image": "openclaw/sandbox:latest",
    "network": "none",
    "memoryLimit": "512m"
  }
}

Gateway (gateway)​

"gateway": {
  "port": 18789,
  "bind": "loopback",                 // localhost | loopback | 0.0.0.0
  "tls": {
    "enabled": false
  },
  "auth": {
    "mode": "token",
    "token": "GENERATE_SECURE_TOKEN"
  },
  "cors": {
    "enabled": false
  }
}

Advanced settings​

Cron jobs (cron)​

"cron": {
    "enabled": true,
    "jobs": [
        {
            "id": "daily-report",
            "schedule": "0 9 * * *",
            "prompt": "Summarize yesterday's activities and send a report to the #general channel.",
            "agentId": "reporter"
        }
    ]
}

Webhooks (hooks)​

"hooks": {
    "enabled": true,
    "token": "your-shared-secret",
    "mappings": [
        {
            "match": { "path": "/github-pr" },
            "action": "agent",
            "agentId": "developer",
            "prompt": "A new pull request has been opened. Please review it."
        }
    ]
}

WhatsApp Web (web)​

"web": {
    "enabled": true,
    "heartbeatSeconds": 60,
    "reconnect": {
        "initialMs": 2000,
        "maxMs": 120000
    }
}

Logging (logging)​

"logging": {
  "level": "info",
  "format": "json",
  "outputs": [
    {
      "type": "file",
      "path": "~/logs/openclaw.log"
    }
  ]
}

Best practices​

Cost control​

{
  "budget": {
    "monthlyLimit": 50, // USD
    "alerts": {
      "email": "admin@example.com"
    }
  }
}

FAQ​

If you run into issues while configuring OpenClaw, see the OpenClaw installation guide or the official documentation. This guide is revised with each release.

Last updated: March 2026

Related posts