Zum Hauptinhalt springen

​
Konfiguration

OpenClaw liest eine optionale -Konfiguration aus ~/.openclaw/openclaw.json. Fehlt die Datei, verwendet OpenClaw sichere Standardwerte. Häufige Gründe für eine Konfiguration:
  • Kanäle verbinden und steuern, wer dem Bot Nachrichten senden darf
  • Modelle, Tools, Sandboxing oder Automatisierung (Cron, Hooks) festlegen
  • Sitzungen, Medien, Netzwerk oder UI optimieren
Siehe die vollständige Referenz für alle verfügbaren Felder.
Neu bei der Konfiguration? Starten Sie mit openclaw onboard für eine interaktive Einrichtung oder sehen Sie sich den Leitfaden Configuration Examples mit vollständigen Copy‑&‑Paste‑Beispielen an.

​
Minimale Konfiguration

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
Konfiguration bearbeiten

openclaw onboard       # vollständiger Einrichtungsassistent
openclaw configure     # Konfigurationsassistent

​
Strikte Validierung

OpenClaw akzeptiert nur Konfigurationen, die vollständig dem Schema entsprechen. Unbekannte Schlüssel, fehlerhafte Typen oder ungültige Werte führen dazu, dass das Gateway nicht startet.
Die einzige Ausnahme auf Root‑Ebene ist $schema (String), damit Editoren JSON‑Schema‑Metadaten anhängen können.
Wenn die Validierung fehlschlägt:
  • Das Gateway startet nicht
  • Nur Diagnosebefehle funktionieren (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Führen Sie openclaw doctor aus, um die genauen Probleme zu sehen
  • Führen Sie openclaw doctor --fix (oder --yes) aus, um Reparaturen anzuwenden

​
Häufige Aufgaben

Jeder Kanal hat einen eigenen Abschnitt unter channels.<provider>.
Siehe die jeweilige Kanalseite für Einrichtungsanweisungen:Alle Kanäle verwenden dasselbe DM‑Policy‑Muster:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // nur für allowlist/open
    },
  },
}
Primäres Modell und optionale Fallbacks festlegen:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models definiert den Modellkatalog und fungiert als Allowlist für /model.
  • Modellreferenzen verwenden das Format provider/model (z. B. anthropic/claude-opus-4-6).
  • Siehe Models CLI für Modellwechsel im Chat und Model Failover für Auth‑Rotation und Fallback‑Verhalten.
  • Für benutzerdefinierte/self‑hosted Provider siehe Custom providers.
DM‑Zugriff wird pro Kanal über dmPolicy gesteuert:
  • "pairing" (Standard): Unbekannte Absender erhalten einen einmaligen Pairing‑Code
  • "allowlist": nur Absender in allowFrom
  • "open": alle eingehenden DMs erlauben (erfordert allowFrom: ["*"])
  • "disabled": alle DMs ignorieren
Für Gruppen verwenden Sie groupPolicy + groupAllowFrom oder kanalspezifische Allowlists.Siehe die vollständige Referenz.
Gruppennachrichten erfordern standardmäßig eine Erwähnung. Konfiguration pro Agent:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Metadaten‑Erwähnungen: native @‑Mentions (WhatsApp Tap‑to‑mention, Telegram @bot, etc.)
  • Textmuster: Regex‑Patterns in mentionPatterns
  • Siehe vollständige Referenz.
Sitzungen steuern Gesprächskontinuität und Isolation:
{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
Agent‑Sitzungen in isolierten Docker‑Containern ausführen:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Image einmalig bauen: scripts/sandbox-setup.shSiehe Sandboxing.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: Dauer (30m, 2h), 0m deaktiviert
  • target: last | whatsapp | telegram | discord | none
  • Siehe Heartbeat.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}
Siehe Cron jobs.
HTTP‑Webhook‑Endpunkte aktivieren:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Siehe die vollständige Referenz.
Mehrere isolierte Agenten mit separaten Workspaces:
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
Siehe Multi-Agent.
$include verwenden, um große Konfigurationen zu organisieren:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • Einzelne Datei: ersetzt das Objekt
  • Array von Dateien: Deep‑Merge in Reihenfolge
  • Geschwister‑Schlüssel: überschreiben inkludierte Werte
  • Verschachtelte Includes: bis zu 10 Ebenen
  • Relative Pfade: relativ zur inkludierenden Datei
  • Fehlerbehandlung: klare Fehlermeldungen

​
Config Hot Reload

Das Gateway überwacht ~/.openclaw/openclaw.json und wendet Änderungen automatisch an — kein manueller Neustart für die meisten Einstellungen erforderlich.

​
Reload‑Modi

ModusVerhalten
hybrid (Standard)Sichere Änderungen werden hot‑applied, kritische führen zu Neustart.
hotNur sichere Änderungen; Neustart muss manuell erfolgen.
restartNeustart bei jeder Änderung.
offDateiüberwachung deaktiviert.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}
gateway.reload und gateway.remote lösen keinen Neustart aus.

​
Environment‑Variablen

OpenClaw liest Umgebungsvariablen aus dem Elternprozess sowie:
  • .env im aktuellen Arbeitsverzeichnis
  • ~/.openclaw/.env (globaler Fallback)
Keine Datei überschreibt bestehende Variablen. 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Falls aktiviert und erwartete Schlüssel fehlen, startet OpenClaw Ihre Login‑Shell und importiert nur fehlende Variablen:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Env‑Var‑Äquivalent: OPENCLAW_LOAD_SHELL_ENV=1
Referenzieren Sie Variablen mit ${VAR_NAME}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Regeln:
  • Nur Großbuchstaben: [A-Z_][A-Z0-9_]*
  • Fehlende/leere Variablen verursachen Fehler beim Laden
  • Mit $${VAR} escapen
  • Funktioniert auch in $include‑Dateien
  • Inline‑Substitution möglich ("${BASE}/v1")
Siehe Environment.

​
Vollständige Referenz

Für die komplette Feld‑für‑Feld‑Dokumentation siehe Configuration Reference.
Verwandt: Configuration Examples · Configuration Reference · Doctor