Configure OpenClaw Like a Pro
Master OpenClaw configuration with our comprehensive guide. From basic setup to advanced security.
📍 Config File Location
OpenClaw stores its configuration in config.yaml.
The location depends on your operating system:
# macOS
~/Library/Application Support/OpenClaw/config.yaml
# Linux
~/.config/openclaw/config.yaml
# Windows
%APPDATA%\OpenClaw\config.yaml
💡 Pro Tip: You can also specify a custom config location using the
--config flag:
openclaw --config /path/to/config.yaml start
📄 Basic Config Structure
A minimal OpenClaw configuration consists of three main sections: gateway, skills, and logging.
# OpenClaw Configuration File
# Documentation: https://docs.openclaw.ai/reference/config
# Gateway settings (API server)
gateway:
host: "127.0.0.1" # Bind to localhost for security
port: 18789 # Default OpenClaw port
auth:
method: "api_key" # Authentication method
api_key: "your-api-key-here # Set via environment variable"
# Skills configuration
skills:
auto_update: true # Keep skills updated
install_path: "~/.openclaw/skills"
max_concurrent: 5 # Max parallel skill executions
# Logging configuration
logging:
level: "info" # debug | info | warn | error
file: "~/.openclaw/logs/openclaw.log"
max_size: "100MB" # Log rotation size
🌐 Gateway Configuration
The gateway controls how OpenClaw exposes its API and handles incoming requests.
Host Binding
# Local only (recommended for development)
gateway:
host: "127.0.0.1" # Only accessible from this machine
port: 18789
# All interfaces (use with authentication!)
gateway:
host: "0.0.0.0" # Accessible from network
port: 18789
auth:
method: "api_key"
api_key: "your-api-key-here # Set via environment variable"
⚠️ Security Warning: Never bind to 0.0.0.0 without authentication.
This exposes your OpenClaw instance to your entire network. See our security guide for details.
Authentication Methods
🔑 API Key (Recommended)
Simple and secure for most use cases
gateway:
auth:
method: "api_key"
api_key: "your-api-key-here # Set via environment variable"
📝 Bearer Token
JWT-based authentication for distributed systems
gateway:
auth:
method: "bearer"
secret: "your-jwt-secret # Set via environment variable"
algorithm: "HS256"
expiration: "24h"
🔒 OAuth 2.0
Enterprise authentication with SSO support
gateway:
auth:
method: "oauth2"
provider: "google" # google | github | azure
client_id: "your-client-id # Set via environment variable"
client_secret: "your-client-secret # Set via environment variable"
CORS Configuration
Control which domains can access your OpenClaw API (useful for web dashboards)
gateway:
cors:
enabled: true
origins:
- "http://localhost:3000"
- "https://yourdomain.com"
methods:
- "GET"
- "POST"
- "DELETE"
credentials: true # Allow cookies/auth headers
🧩 Skills Configuration
Customize how skills are installed, updated, and executed.
skills:
# Auto-update settings
auto_update: true
update_interval: "24h"
update_channel: "stable" # stable | beta | dev
# Installation paths
install_path: "~/.openclaw/skills"
cache_path: "~/.openclaw/cache"
# Execution settings
max_concurrent: 5 # Max parallel executions
timeout: "5m" # Per-skill timeout
memory_limit: "2GB" # Per-skill memory limit
# Skill repositories
repositories:
- name: "official"
url: "https://skills.openclaw.ai"
enabled: true
- name: "community"
url: "https://community-skills.openclaw.ai"
enabled: false
# Permissions (skill sandbox)
permissions:
allow_network: true
allow_filesystem: true
allow_subprocess: false # Disable shell commands
allowed_domains:
- "api.openai.com"
- "api.anthropic.com"
- "*.github.com"
✅ Best Practice: Restrict skill permissions in production environments. Only enable the minimum permissions your skills need.
🎯 Environment-Specific Configs
Different environments require different security and performance settings.
💻 Development
gateway:
host: "127.0.0.1"
port: 18789
auth:
method: "none" # OK for dev!
logging:
level: "debug" # Verbose logs
skills:
auto_update: true
update_channel: "beta" # Test new features
🚀 Production
gateway:
host: "127.0.0.1"
port: 18789
auth:
method: "api_key"
api_key: "your-api-key-here # Set via environment variable"
logging:
level: "warn" # Only warnings & errors
max_size: "1GB" # Larger logs
skills:
auto_update: false # Manual updates only
update_channel: "stable"
# Resource limits
max_concurrent: 10
memory_limit: "4GB"
timeout: "10m"
🔄 Using Multiple Configs
Use environment-specific config files and switch between them:
# Use development config
openclaw --config config.dev.yaml start
# Use production config
openclaw --config config.prod.yaml start
# Set via environment variable
export OPENCLAW_CONFIG=/path/to/config.prod.yaml
openclaw start
🔐 Environment Variables
Store sensitive data in environment variables, not in config files. This prevents accidental secrets in version control.
1. Create a .env file
# OpenClaw Environment Variables
OPENCLAW_API_KEY=your-api-key-here
OPENCLAW_ENCRYPTION_KEY=your-32-char-encryption-key
JWT_SECRET=your-jwt-secret
OAUTH_CLIENT_ID=your-oauth-client-id
OAUTH_CLIENT_SECRET=your-oauth-client-secret
# Optional: Custom config location
OPENCLAW_CONFIG=/path/to/custom/config.yaml
2. Reference in config.yaml
gateway:
auth:
method: "api_key"
api_key: "your-api-key-here # Set via environment variable" # Loaded from .env
encryption:
key: "your-encryption-key # Set via environment variable"
3. Load before starting OpenClaw
# Load .env file (requires dotenv)
source .env
# Or use direnv (recommended for development)
direnv allow
# Start OpenClaw
openclaw start
⚠️ Important: Never commit .env files to version control. Add .env to your .gitignore.
⚡ Performance Tuning
Optimize OpenClaw for your workload and hardware.
Concurrent Executions
Increase concurrent executions for high-throughput workloads:
skills:
max_concurrent: 20 # Run up to 20 skills in parallel
queue_size: 100 # Queue up to 100 pending tasks
💡 Set based on your CPU cores. A good starting point: CPU cores × 2
Memory Management
Limit memory per skill to prevent runaway processes:
skills:
memory_limit: "4GB" # Per-skill limit
memory_warning: "3GB" # Warning threshold
# Kill skills that exceed limits
enforce_limits: true
Caching
Enable caching for frequently used skill outputs:
cache:
enabled: true
type: "redis" # redis | memory | file
url: "redis://localhost:6379"
ttl: "1h" # Cache duration
max_size: "1GB" # Max cache size
🔧 Configuration Troubleshooting
Config not loading?
Check if OpenClaw is finding your config file:
openclaw --config /path/to/config.yaml --debug start
Environment variables not working?
Verify the variable is set before starting OpenClaw:
# Check if variable is set
echo $OPENCLAW_API_KEY
# Test with inline variable
OPENCLAW_API_KEY=test openclaw start
Syntax errors in config?
Validate your YAML syntax:
# Using yamllint
yamllint config.yaml
# Or use online tools
# https://www.yamllint.com/