OpenClaw AI Configuration Guide

Configure OpenClaw AI for your environment — from simple API key setup to advanced multi-provider configurations with local LLMs, custom tool paths, and agent behavior settings.

Setup ⏱ 12 min read

Config File Location

OpenClaw stores its configuration in a YAML file at:

OSConfig Path
Linux / macOS~/.openclaw/config.yaml
Windows%USERPROFILE%\.openclaw\config.yaml
Docker/root/.openclaw/config.yaml

Initialize a default config:

openclaw config init

LLM Provider Setup

OpenAI

openclaw config set provider openai
openclaw config set api_key sk-...your-openai-key...
openclaw config set model gpt-4o         # default
openclaw config set temperature 0.2      # 0.0 = deterministic

Anthropic Claude

openclaw config set provider anthropic
openclaw config set api_key sk-ant-...your-key...
openclaw config set model claude-3-5-sonnet-20241022

Local Models via Ollama

Run agents completely offline — no API key needed:

# Make sure Ollama is running first:
ollama serve &

# Configure OpenClaw
openclaw config set provider ollama
openclaw config set ollama_host http://localhost:11434
openclaw config set model llama3.2:3b   # or mistral:7b, phi3:14b...

# Test the connection
openclaw ping
💡
Recommended local models by hardware:

4 GB RAM → llama3.2:3b or phi3:3.8b
8 GB RAM → mistral:7b or llama3.1:8b
16 GB RAM → mixtral:8x7b or llama3.1:70b-q4
GPU 8 GB VRAM → llama3.1:70b (quantized)

Environment Variables

All config values can be overridden via environment variables (useful for CI/CD and Docker):

export OPENCLAW_PROVIDER=openai
export OPENCLAW_API_KEY=sk-...
export OPENCLAW_MODEL=gpt-4o
export OPENCLAW_MAX_STEPS=20
export OPENCLAW_TEMPERATURE=0.1
export OPENCLAW_TIMEOUT=120
export OPENCLAW_LOG_LEVEL=info   # debug | info | warning | error

Or use a .env file (loaded automatically from the working directory):

# .env
OPENCLAW_PROVIDER=openai
OPENCLAW_API_KEY=sk-...your-key...
OPENCLAW_MODEL=gpt-4o-mini

Full Configuration Reference

The complete ~/.openclaw/config.yaml with all available options:

# OpenClaw AI - Full Configuration Reference
# ~/.openclaw/config.yaml

# === LLM Provider ===
provider: openai           # openai | anthropic | ollama | groq | mistral
api_key: "sk-..."          # Your provider API key
model: gpt-4o              # Model identifier
temperature: 0.2           # 0.0-2.0. Lower = more deterministic
max_tokens: 4096           # Max tokens per LLM response

# === Ollama (when provider: ollama) ===
ollama:
  host: http://localhost:11434
  model: llama3.2:3b
  keep_alive: 5m           # How long to keep model loaded

# === Agent Behavior ===
agent:
  max_steps: 25            # Max actions per task (prevent infinite loops)
  timeout: 180             # Max seconds per complete task run
  dry_run: false           # If true, plan but don't execute actions
  verbose: false           # Print each step to stdout
  ask_confirmation: false  # Ask user before destructive actions

# === Tools ===
tools:
  shell:
    enabled: true
    allowed_commands: []   # Empty = all commands allowed
    blocked_commands:      # Dangerous commands to block
      - "rm -rf /"
      - "format"
      - "mkfs"
  web:
    enabled: true
    search_api: duckduckgo  # duckduckgo | serpapi | brave
    search_api_key: ""     # Required for serpapi/brave
  browser:
    enabled: false         # Requires: pip install openclaw[browser]
  files:
    workspace: "."         # Default working directory for file ops
    allowed_paths: []      # Empty = current + subdirectories only

# === Memory ===
memory:
  short_term: true          # Keep conversation context within task
  long_term: false          # Persist memory across runs (SQLite)
  long_term_db: ~/.openclaw/memory.db

# === Logging ===
logging:
  level: info               # debug | info | warning | error
  file: ~/.openclaw/logs/openclaw.log
  max_size_mb: 50
  keep_days: 30

# === Telegram Bot Integration ===
telegram:
  enabled: false
  bot_token: ""
  allowed_user_ids: []      # Whitelist of Telegram user IDs

# === API Server (openclaw serve) ===
server:
  port: 8080
  host: 0.0.0.0
  auth_token: ""            # Bearer token for API requests

Multiple Profiles

You can maintain multiple configurations for different projects or providers:

# Create a profile
openclaw config profile create work --provider openai --model gpt-4o
openclaw config profile create local --provider ollama --model llama3.2

# List profiles
openclaw config profile list

# Use a specific profile for one task
openclaw run "Summarize this document" --profile local

# Set a default profile
openclaw config profile use work

Security Best Practices

🚨
Never commit API keys to version control

Always use environment variables or .env files (add .env to your .gitignore). The config file at ~/.openclaw/config.yaml is outside your project directory — keep it there.

  • Use read-only API keys when possible (some providers support key scoping).
  • Enable ask_confirmation: true in untrusted environments or when running destructive tasks.
  • Use allowed_paths to restrict which directories the agent can access.
  • Use blocked_commands to prevent dangerous shell commands.
  • Set dry_run: true to preview what the agent would do without executing.

Verify Your Configuration

# Show current config (masks API keys)
openclaw config show

# Test connection to provider
openclaw ping

# Run a simple test task
openclaw run "What is 2 + 2?" --verbose
🔗
See Also

Getting Started — Back to basics: quick-start guide for new users.

CLI Commands — Full reference for all OpenClaw commands and flags.

Integrations — Connect OpenClaw to OpenAI, Claude, Ollama, Telegram, and more.

Troubleshooting — Fix API key errors, connection issues, and config problems.

← Previous
Installation