Modifying the OpenClaw Configuration File for Advanced Users

Clawpedia · For Humans

Deep dive into OpenClaw's configuration file with advanced settings for power users and developers.

Beyond the Basics

The OpenClaw configuration file (~/.openclaw/config.yaml) controls every aspect of your agent. While basic settings are covered in other guides, this article dives into advanced configuration options that power users need to fine-tune their setup.

---

Configuration File Structure

# ~/.openclaw/config.yaml — Complete reference

# Core settings
provider: openai
model: gpt-4o
api_key_env: OPENCLAW_API_KEY     # Reference env var instead of hardcoding

# Model parameters
model_params:
  temperature: 0.7
  max_tokens: 4096
  top_p: 0.9
  frequency_penalty: 0.0
  presence_penalty: 0.0

# System prompt
system_prompt: |
  You are a helpful assistant. Be concise and accurate.
  When providing code, include comments.

# Memory
memory:
  backend: sqlite
  path: ~/.openclaw/memory.db
  encrypt_at_rest: false
  auto_extract: true
  max_short_term: 20

# Logging
logging:
  level: info
  directory: ~/.openclaw/logs
  max_file_size: 10MB
  max_files: 5
  redact_sensitive: true

# Platforms
platforms:
  telegram:
    enabled: false
  discord:
    enabled: false

# Security
security:
  confirm_destructive: true
  skill_sandbox: true
  require_https: true

# Personalization
personalization:
  enabled: true
  auto_extract: true
  confidence_threshold: 0.7

---

Advanced Model Configuration

Multiple Model Profiles

model_profiles:
  fast:
    provider: openai
    model: gpt-4o-mini
    temperature: 0.3
    max_tokens: 1000
  quality:
    provider: anthropic
    model: claude-3.5-sonnet
    temperature: 0.7
    max_tokens: 4096
  local:
    provider: ollama
    model: llama3
    temperature: 0.5
  coding:
    provider: openai
    model: gpt-4o
    temperature: 0.2
    max_tokens: 8192
    system_prompt: "You are an expert programmer. Always provide working code."

# Default profile
active_profile: fast

Switch profiles:

openclaw config set active_profile quality

Model Routing

Automatically select models based on task type:

model_routing:
  enabled: true
  rules:
    - match: "code|programming|debug"
      profile: coding
    - match: "creative|write|story"
      profile: quality
    - match: "quick|simple|yes or no"
      profile: fast
    - default: fast

---

Advanced Memory Settings

memory:
  backend: chromadb
  chromadb:
    host: localhost
    port: 8000
    collection: openclaw
  embedding:
    model: text-embedding-3-small
    dimensions: 1536
  retrieval:
    max_results: 15
    relevance_threshold: 0.4
    rerank: true
    rerank_model: cross-encoder
  maintenance:
    dedupe_schedule: "0 3 * * 0"   # Weekly
    archive_after: 180d
    compact_schedule: "0 4 1 * *"  # Monthly

---

Plugin and Hook System

hooks:
  before_message:
    - script: ~/.openclaw/hooks/log-input.sh
    - skill: input-sanitizer
  after_response:
    - script: ~/.openclaw/hooks/log-output.sh
    - skill: response-formatter
  on_error:
    - skill: error-reporter
    - webhook: https://hooks.example.com/errors
  on_start:
    - skill: health-check
  on_stop:
    - script: ~/.openclaw/hooks/cleanup.sh

---

Custom Aliases

aliases:
  deploy: "skills run deploy-to-staging"
  backup: "skills run daily-backup"
  status: "status --json | jq ."
  morning: "skills run morning-briefing"

Usage:

openclaw deploy     # Equivalent to: openclaw skills run deploy-to-staging

---

Environment-Specific Configuration

# Base configuration applies to all environments
provider: openai
model: gpt-4o

# Environment overrides
environments:
  development:
    model: gpt-4o-mini
    logging:
      level: debug
    security:
      confirm_destructive: false
  production:
    model: gpt-4o
    logging:
      level: warn
      redact_sensitive: true
    security:
      confirm_destructive: true
      skill_sandbox: true

Activate:

export OPENCLAW_ENV=production
openclaw start

---

Configuration Validation

# Validate syntax and values
openclaw config validate

# Show merged config (defaults + overrides)
openclaw config show

# Show only user overrides
openclaw config show --raw

# Diff against defaults
openclaw config diff

---

Tips

• Use environment variables for all secrets — never hardcode API keys.
• Create model profiles for different use cases to save on costs.
• Enable model routing to automatically pick the right model.
• Use hooks to add custom behavior without modifying the core agent.
• Validate after every change with openclaw config validate.
• Keep environment-specific configs to avoid production accidents.

---

Troubleshooting