openclaw.example.json

{
  "$schema": "https://openclaw.dev/schema/openclaw.schema.json",
  "_comment": "Reference config from the OpenClaw Optimization Guide. Updated for the 2026.6.4 stable / 2026.6.11-beta.1 era. Copy to ~/.openclaw/openclaw.json (or your project root) and edit. Never commit real credentials — use env var references like ${ANTHROPIC_API_KEY}. Treat this as a starting point; provider catalogs/manifests should own durable model rows where possible.",

  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/opus",
        "fallbacks": [
          "deepseek/deepseek-v4-flash",
          "moonshot/kimi-k2.6",
          "google/gemini-3-flash",
          "openai/gpt-5.5"
        ],
        "_comment": "`opus` aliases resolve to Claude Opus 4.7 on current Anthropic/Bedrock routes. Codex app-server routes should use canonical openai/gpt-* refs from your local provider catalog; do not pin durable openai-codex/* or codex-cli/* model refs. Do not assume Claude Pro/Max subscription usage covers OpenClaw after the April 4 cutoff; set budget caps on paid routes."
      },
      "runRetries": 1,
      "budget": {
        "dailyUsd": 25,
        "monthlyUsd": 400,
        "onExceed": "degrade"
      },
      "_budget_comment": "2026.6.4+: per-agent budget caps. onExceed: warn | degrade | stop. `degrade` reroutes to the cheapest fallback lane — only useful if fallbacks are configured. Override per agent in agents.list[].budget.",
      "imageQuality": "balanced",
      "_imageQuality_comment": "2026.5.24-beta.1: token-efficient | balanced | high-detail. Keep balanced unless a worker truly needs high-detail OCR/vision.",
      "compaction": {
        "model": "cerebras/gpt-oss-120b",
        "reserveTokens": 8000,
        "maxActiveTranscriptBytes": 300000,
        "_comment": "Keep compaction on a cheap, fast, non-reasoning model. The transcript byte guard prevents runaway compaction on huge sessions."
      },
      "memorySearch": {
        "provider": "ollama",
        "model": "qwen3-embedding:0.6b",
        "endpoint": "http://localhost:11434",
        "inputType": "search_query",
        "documentInputType": "search_document",
        "_comment": "Local Ollama is the right default. Switch to `copilot` only if your org already pays for Copilot Business/Enterprise and accepts cloud-latency memory search."
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m",
        "_comment": "Stops SOUL+AGENTS+MEMORY re-injection every turn. Single biggest latency win on frontier models."
      },
      "experimental": {
        "localModelLean": false
      }
    },
    "list": [
      {
        "id": "local-worker",
        "experimental": {
          "localModelLean": true
        },
        "_comment": "2026.5.20+: prefer per-agent lean mode for small local workers instead of forcing the orchestrator lean globally."
      }
    ]
  },

  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true,
        "config": {
          "recall": {
            "maxParallel": 3,
            "_comment": "2026.6.11-beta.1+: bound concurrent memory sub-agents. Raise on a fast local embedding tier; lower on shared hardware so recall doesn't starve foreground turns. Not available on 2026.6.4 stable yet."
          },
          "dreaming": {
            "enabled": true,
            "schedule": "0 3 * * *",
            "_schedule_comment": "Off-hours dreaming schedule (cron). 2026.6.11-beta.1 adds finer schedule controls. Verify promotions with `memory promote --dry-run` (2026.6.4+) before trusting them.",
            "storage": {
              "mode": "separate",
              "_comment": "Current default. Phase blocks land in memory/dreaming/{phase}/YYYY-MM-DD.md. Flip to `inline` if you want them in the daily memory file."
            }
          }
        }
      },
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "storage": {
            "mode": "local",
            "_comment": "Switch to `cloud` with S3-compatible creds if you want durable memory indexes on object storage. Keep embeddings local unless you accept 2-5s memory-search latency."
          }
        }
      },
      "active-memory": {
        "enabled": false,
        "config": {
          "allowedChatTypes": ["dm"],
          "allowedChatIds": [],
          "deniedChatIds": [],
          "timeoutMs": 3000,
          "queryMode": "balanced",
          "_comment": "Enable per surface. Deny public/group channels until you have a retention policy."
        }
      },
      "policy": {
        "enabled": true,
        "_comment": "2026.5.20+: run openclaw policy check before inviting shared-channel users."
      },
      "meeting-notes": {
        "enabled": false,
        "config": {
          "retentionDays": 30,
          "redact": ["email", "phone", "api-key"],
          "sources": {
            "discordVoice": { "autoStart": false },
            "googleMeet": { "autoStart": false }
          }
        },
        "_comment": "2026.5.22+ source-only external plugin; 2026.6.4 adds Google Meet live capture plus retentionDays/redaction. Define retention before enabling any live source."
      }
    }
  },

  "messages": {
    "visibleReplies": true,
    "queue": {
      "mode": "steer",
      "byChannel": {
        "email": { "mode": "collect" },
        "slack": { "mode": "steer" },
        "telegram": { "mode": "steer" }
      }
    },
    "groupChat": {
      "visibleReplies": true,
      "ambientTurns": "room_event"
    },
    "_comment": "Current May line: steer is the default active-run queue mode. Use collect/followup/interrupt only when intentional. ambientTurns=room_event should collect context quietly; visible replies still go through message tools."
  },

  "tools": {
    "profile": "coding",
    "toolsBySender": {
      "*": {
        "deny": ["exec", "process", "write", "edit", "apply_patch"]
      },
      "channel:discord:1234567890123": {
        "alsoAllow": ["group:fs"]
      }
    },
    "_comment": "Defense-in-depth for channel users. Sender identities must come from the channel adapter, not message text. Replace the discord id with your own admin/channel sender key."
  },

  "models": {
    "providers": {
      "anthropic": {
        "type": "anthropic",
        "health": {
          "checkIntervalMs": 60000,
          "failureThreshold": 3,
          "demoteForMs": 300000
        },
        "_comment": "2026.6.4+: health-checked failover. A lane that crosses failureThreshold is demoted for demoteForMs, then re-promoted. Only helps if fallback lanes exist (see agents.defaults.model.fallbacks)."
      },
      "openrouter": {
        "type": "openrouter",
        "params": {
          "provider": {
            "order": ["Fireworks", "Together"],
            "allow_fallbacks": true
          }
        },
        "_comment": "2026.5.20+: provider-level OpenRouter routing policy; model/agent params can override."
      },
      "ollama-local": {
        "type": "ollama",
        "endpoint": "http://localhost:11434",
        "localService": {
          "command": "ollama serve",
          "healthUrl": "http://localhost:11434/api/tags",
          "readyTimeoutMs": 20000,
          "idleStopMs": 900000
        },
        "_comment": "2026.5+: provider-level localService can start local model daemons on demand. Remove this block if Ollama is managed elsewhere."
      }
    }
  },

  "mcp": {
    "servers": {
      "repo-tools": {
        "command": "repo-mcp",
        "codex": {
          "agents": ["coding-agent"]
        },
        "_comment": "2026.5.16+: scope user MCP projection into native Codex to named OpenClaw agents. Do not expose every MCP server to every Codex run."
      }
    }
  },

  "codex": {
    "defaultToolsApprovalMode": "prompt",
    "_comment": "2026.5.16+: make native Codex tool approvals explicit (auto | prompt | approve)."
  },

  "security": {
    "audit": {
      "suppressions": [],
      "_comment": "2026.5.18+: only suppress reviewed audit findings with owner/reason/expiry in your real config."
    },
    "secrets": {
      "rotation": {
        "maxAgeDays": 90,
        "_comment": "2026.6.4+: openclaw doctor warns on credentials older than this so stale long-lived keys surface in routine health checks."
      }
    }
  },

  "skills": {
    "autoUpdate": false,
    "updateNotify": true,
    "_comment": "Auto-update ON is the sleeper-update attack. Pin specific refs: `openclaw skills install author/skill --ref v1.2.0`. See Part 23."
  },

  "taskBrain": {
    "approvals": {
      "defaults": {
        "read-only.*": "allow",
        "execution.sandbox.*": "allow",
        "execution.*": "ask",
        "write.fs.workspace": "allow",
        "write.fs.outside-workspace": "deny",
        "write.network": "ask",
        "control-plane.*": "deny"
      },
      "_comment": "Semantic categories replaced name-based allowlists in 2026.3.31-beta.1. See Part 24 for per-agent overrides."
    }
  },

  "hooks": {
    "internal": {
      "entries": {
        "auto-capture": {
          "enabled": true,
          "path": "./hooks/auto-capture/handler.ts",
          "event": "session:compact:before",
          "_comment": "Extracts claim-named knowledge notes into vault/00_inbox/. See Part 11 and Part 29 for current hook registration."
        }
      }
    }
  },

  "auth": {
    "profiles": {
      "default": {
        "anthropic": "${ANTHROPIC_API_KEY}",
        "openai":    "${OPENAI_API_KEY}",
        "google":    "${GOOGLE_API_KEY}",
        "cerebras":  "${CEREBRAS_API_KEY}"
      }
    }
  }
}