Konfiguration

Jeder Kanal hat unter channels.<provider> einen eigenen Konfigurationsabschnitt. Einrichtungsschritte finden Sie auf der jeweiligen Kanalseite:

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Alle Kanäle verwenden dasselbe Richtlinienmuster für Direktnachrichten:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // nur für allowlist/open    },  },}

Legen Sie das primäre Modell und optionale Fallbacks fest:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models definiert den Modellkatalog und dient als Zulassungsliste für /model; provider/*-Einträge beschränken /model, /models und Modellauswahlelemente auf ausgewählte Provider, während weiterhin die dynamische Modellerkennung verwendet wird.
• Verwenden Sie openclaw config set agents.defaults.models '<json>' --strict-json --merge, um Einträge zur Zulassungsliste hinzuzufügen, ohne vorhandene Modelle zu entfernen. Einfache Ersetzungen, die Einträge entfernen würden, werden abgelehnt, sofern Sie nicht --replace übergeben.
• Modellreferenzen verwenden das Format provider/model (z. B. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx steuert die Herunterskalierung von Bildern in Transkripten und Tools (Standardwert 1200); niedrigere Werte reduzieren bei Durchläufen mit vielen Screenshots normalerweise die Nutzung von Vision-Tokens.
• Informationen zum Wechseln von Modellen im Chat finden Sie unter Modelle über die CLI, Informationen zur Authentifizierungsrotation und zum Fallback-Verhalten unter Modell-Failover.
• Informationen zu benutzerdefinierten oder selbst gehosteten Providern finden Sie unter Benutzerdefinierte Provider in der Referenz.

Der Zugriff auf Direktnachrichten wird pro Kanal über dmPolicy gesteuert (Standardwert "pairing"):

• "pairing": Unbekannte Absender erhalten einen einmaligen Kopplungscode zur Genehmigung
• "allowlist": Nur Absender in allowFrom (oder im Speicher gekoppelter zugelassener Absender)
• "open": Alle eingehenden Direktnachrichten zulassen (erfordert allowFrom: ["*"])
• "disabled": Alle Direktnachrichten ignorieren

Verwenden Sie für Gruppen groupPolicy ("allowlist" | "open" | "disabled") zusammen mit groupAllowFrom oder kanalspezifischen Zulassungslisten.

Kanalspezifische Details finden Sie in der vollständigen Referenz.

Gruppennachrichten erfordern standardmäßig eine Erwähnung. Konfigurieren Sie Auslösemuster pro Agent. Normale Gruppen-/Kanalantworten werden automatisch veröffentlicht; aktivieren Sie den Pfad über das Nachrichten-Tool für gemeinsam genutzte Räume, in denen der Agent entscheiden soll, wann er sich äußert:

{  messages: {    visibleReplies: "automatic", // auf "message_tool" setzen, um überall Sendevorgänge über das Nachrichten-Tool zu verlangen    groupChat: {      visibleReplies: "message_tool", // explizit aktiviert; sichtbare Ausgabe erfordert message(action=send)      unmentionedInbound: "room_event", // nicht erwähnte, dauerhaft aktive Gruppenunterhaltung dient als stiller Kontext    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Metadaten-Erwähnungen: native @-Erwähnungen (Antippen zum Erwähnen in WhatsApp, Telegram-@bot usw.)
• Textmuster: sichere reguläre Ausdrücke in mentionPatterns
• Sichtbare Antworten: messages.visibleReplies kann Sendevorgänge über das Nachrichten-Tool global vorschreiben; messages.groupChat.visibleReplies überschreibt dies für Gruppen/Kanäle.
• Informationen zu Modi für sichtbare Antworten, kanalspezifischen Überschreibungen und dem Selbstchat-Modus finden Sie in der vollständigen Referenz.

Verwenden Sie agents.defaults.skills als gemeinsame Basis und überschreiben Sie anschließend bestimmte Agenten mit agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // übernimmt github, weather      { id: "docs", skills: ["docs-search"] }, // ersetzt die Standardwerte      { id: "locked-down", skills: [] }, // keine Skills    ],  },}

• Lassen Sie agents.defaults.skills weg, damit Skills standardmäßig nicht beschränkt sind.
• Lassen Sie agents.list[].skills weg, um die Standardwerte zu übernehmen.
• Legen Sie agents.list[].skills: [] fest, um keine Skills zuzulassen.
• Weitere Informationen finden Sie unter Skills, Skills-Konfiguration und in der Konfigurationsreferenz.

Steuern Sie, wie aggressiv das Gateway Kanäle neu startet, die veraltet zu sein scheinen:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Die angezeigten Werte sind die Standardwerte. Legen Sie gateway.channelHealthCheckMinutes: 0 fest, um durch die Zustandsüberwachung ausgelöste Neustarts global zu deaktivieren.
• channelStaleEventThresholdMinutes sollte größer oder gleich dem Prüfintervall sein.
• Verwenden Sie channels.<provider>.healthMonitor.enabled oder channels.<provider>.accounts.<id>.healthMonitor.enabled, um automatische Neustarts für einen einzelnen Kanal oder ein einzelnes Konto zu deaktivieren, ohne die globale Überwachung zu deaktivieren.
• Informationen zur betrieblichen Fehlerdiagnose finden Sie unter Zustandsprüfungen, alle Felder in der vollständigen Referenz.

Geben Sie lokalen Clients auf ausgelasteten oder leistungsschwachen Hosts mehr Zeit, den WebSocket-Handshake vor der Authentifizierung abzuschließen:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Der Standardwert beträgt 15000 Millisekunden.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS hat für einmalige Überschreibungen in Diensten oder Shells weiterhin Vorrang.
• Beheben Sie vorzugsweise zuerst Verzögerungen beim Start oder in der Ereignisschleife; diese Einstellung ist für Hosts vorgesehen, die ordnungsgemäß funktionieren, aber während der Aufwärmphase langsam sind.

Sitzungen steuern die Kontinuität und Isolation von Unterhaltungen:

{  session: {

    dmScope: "per-channel-peer",  // empfohlen für mehrere Benutzer

    threadBindings: {

      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },

    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (gemeinsam genutzt) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: Globale Standardwerte für das Routing Thread-gebundener Sitzungen. /focus, /unfocus, /agents, /session idle und /session max-age binden diese Einstellung pro Sitzung, heben die Bindung auf, listen sie auf und passen sie an (Discord bindet Threads, Telegram bindet Themen/Unterhaltungen).
• Weitere Informationen zu Geltungsbereichen, Identitätsverknüpfungen und Senderichtlinien finden Sie unter Sitzungsverwaltung.
• Alle Felder finden Sie in der vollständigen Referenz.

Führen Sie Agent-Sitzungen in isolierten Sandbox-Laufzeitumgebungen aus:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Erstellen Sie zuerst das Image – führen Sie aus einem Quellcode-Checkout scripts/sandbox-setup.sh aus, oder verwenden Sie bei einer npm-Installation den eingebetteten Befehl docker build unter Sandboxing § Images und Einrichtung.

Die vollständige Anleitung finden Sie unter Sandboxing und alle Optionen in der vollständigen Referenz.

Relay-gestützte Push-Benachrichtigungen für öffentliche App-Store-Builds verwenden das gehostete OpenClaw-Relay: https://ios-push-relay.openclaw.ai.

Benutzerdefinierte Relay-Bereitstellungen erfordern einen bewusst getrennten iOS-Build-/Bereitstellungspfad, dessen Relay-URL mit der Relay-URL des Gateways übereinstimmt. Wenn Sie einen benutzerdefinierten Relay-Build verwenden, legen Sie Folgendes in der Gateway-Konfiguration fest:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Standardwert: 10000          timeoutMs: 10000,        },      },    },  },}

CLI-Entsprechung:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Funktionsweise:

• Ermöglicht dem Gateway, push.test, Aktivierungsimpulse und Aktivierungen zur Wiederherstellung der Verbindung über das externe Relay zu senden.
• Verwendet eine registrierungsspezifische Sendeberechtigung, die von der gekoppelten iOS-App weitergeleitet wird. Das Gateway benötigt kein bereitstellungsweites Relay-Token.
• Bindet jede Relay-gestützte Registrierung an die Gateway-Identität, mit der die iOS-App gekoppelt wurde, sodass ein anderes Gateway die gespeicherte Registrierung nicht wiederverwenden kann.
• Verwendet für lokale/manuelle iOS-Builds weiterhin direkte APNs. Relay-gestützte Sendungen gelten nur für offiziell verteilte Builds, die über das Relay registriert wurden.
• Muss mit der in den iOS-Build integrierten Relay-Basis-URL übereinstimmen, damit Registrierungs- und Sendedatenverkehr dieselbe Relay-Bereitstellung erreichen.

End-to-End-Ablauf:

1. Installieren Sie die offizielle iOS-App.
2. Optional: Konfigurieren Sie gateway.push.apns.relay.baseUrl auf dem Gateway nur, wenn Sie bewusst einen separaten benutzerdefinierten Relay-Build verwenden.
3. Koppeln Sie die iOS-App mit dem Gateway und lassen Sie sowohl die Node- als auch die Operator-Sitzung eine Verbindung herstellen.
4. Die iOS-App ruft die Gateway-Identität ab, registriert sich mithilfe von App Attest und dem App-Beleg beim Relay und veröffentlicht anschließend die Relay-gestützte push.apns.register-Nutzlast auf dem gekoppelten Gateway.
5. Das Gateway speichert das Relay-Handle und die Sendeberechtigung und verwendet sie anschließend für push.test, Aktivierungsimpulse und Aktivierungen zur Wiederherstellung der Verbindung.

Betriebshinweise:

• Wenn Sie die iOS-App auf ein anderes Gateway umstellen, verbinden Sie die App erneut, damit sie eine neue, an dieses Gateway gebundene Relay-Registrierung veröffentlichen kann.
• Wenn Sie einen neuen iOS-Build ausliefern, der auf eine andere Relay-Bereitstellung verweist, aktualisiert die App ihre zwischengespeicherte Relay-Registrierung, anstatt den alten Relay-Ursprung wiederzuverwenden.

Kompatibilitätshinweis:

• OPENCLAW_APNS_RELAY_BASE_URL und OPENCLAW_APNS_RELAY_TIMEOUT_MS funktionieren weiterhin als temporäre Umgebungsüberschreibungen.
• Benutzerdefinierte Gateway-Relay-URLs müssen mit der in den iOS-Build integrierten Relay-Basis-URL übereinstimmen; der öffentliche App-Store-Veröffentlichungskanal lehnt benutzerdefinierte Überschreibungen der iOS-Relay-URL ab.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true bleibt ein ausschließlich für Loopback bestimmter Entwicklungsnotausgang; speichern Sie keine HTTP-Relay-URLs dauerhaft in der Konfiguration.

Den End-to-End-Ablauf finden Sie unter iOS-App, das Relay-Sicherheitsmodell unter Authentifizierungs- und Vertrauensablauf.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: Zeichenfolge für die Dauer (30m, 2h). Setzen Sie den Wert zum Deaktivieren auf 0m. Standard: 30m.
• target: last | none | <channel-id> (zum Beispiel discord, matrix, telegram oder whatsapp)
• directPolicy: allow (Standard) oder block für DM-artige Heartbeat-Ziele
• Die vollständige Anleitung finden Sie unter Heartbeat.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // Standardwert; Cron-Weiterleitung + isolierte Ausführung von Cron-Agent-Turns    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: Sitzungen abgeschlossener isolierter Ausführungen aus den SQLite-Sitzungszeilen entfernen (Standardwert 24h; zum Deaktivieren auf false setzen).
• runLog: Aufbewahrte Zeilen des Cron-Ausführungsverlaufs pro Job entfernen. Der Verlauf wird in SQLite gespeichert; maxBytes (Standardwert 2_000_000) wird für die Kompatibilität mit älteren dateibasierten Ausführungsprotokollen beibehalten, keepLines hat den Standardwert 2000.
• Eine Funktionsübersicht und CLI-Beispiele finden Sie unter Cron-Jobs.

Aktivieren Sie HTTP-Webhook-Endpunkte am Gateway:

{  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,      },    ],  },}

Sicherheitshinweis:

• Behandeln Sie sämtliche Inhalte von Hook-/Webhook-Nutzdaten als nicht vertrauenswürdige Eingaben.
• Verwenden Sie ein dediziertes hooks.token; verwenden Sie keine aktiven Gateway-Authentifizierungsgeheimnisse (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN oder gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD) erneut.
• Die Hook-Authentifizierung erfolgt ausschließlich über Header (Authorization: Bearer ... oder x-openclaw-token); Tokens in Abfragezeichenfolgen werden abgelehnt.
• hooks.path darf nicht / sein; verwenden Sie für eingehende Webhooks einen dedizierten Unterpfad wie /hooks.
• Lassen Sie Flags zur Umgehung der Prüfung unsicherer Inhalte (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) deaktiviert, außer bei eng begrenzter Fehlerdiagnose.
• Wenn Sie hooks.allowRequestSessionKey aktivieren, legen Sie außerdem hooks.allowedSessionKeyPrefixes fest, um die vom Aufrufer ausgewählten Sitzungsschlüssel einzugrenzen.
• Bevorzugen Sie für Hook-gesteuerte Agenten leistungsfähige moderne Modellklassen und eine strikte Tool-Richtlinie (beispielsweise ausschließlich Nachrichtenfunktionen sowie Sandboxing, sofern möglich).

Alle Zuordnungsoptionen und die Gmail-Integration finden Sie in der vollständigen Referenz.

Führen Sie mehrere isolierte Agenten mit separaten Arbeitsbereichen und Sitzungen aus:

{  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" } },  ],}

Bindungsregeln und agentenspezifische Zugriffsprofile finden Sie unter Multi-Agent und in der vollständigen Referenz.

Verwenden Sie $include, 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 umgebende Objekt
• Datei-Array: wird der Reihe nach tief zusammengeführt (spätere Werte haben Vorrang), bis zu 10 verschachtelte Ebenen
• Gleichgeordnete Schlüssel: werden nach den Includes zusammengeführt (überschreiben eingebundene Werte)
• Relative Pfade: werden relativ zur einbindenden Datei aufgelöst
• Pfadformat: Include-Pfade dürfen keine Nullbytes enthalten und müssen vor und nach der Auflösung strikt kürzer als 4096 Zeichen sein
• Von OpenClaw ausgeführte Schreibvorgänge: Wenn ein Schreibvorgang nur einen Abschnitt der obersten Ebene ändert, der durch ein Include einer einzelnen Datei wie plugins: { $include: "./plugins.json5" } gestützt wird, aktualisiert OpenClaw diese eingebundene Datei und lässt openclaw.json unverändert
• Nicht unterstütztes Durchschreiben: Root-Includes, Include-Arrays und Includes mit gleichgeordneten Überschreibungen werden bei von OpenClaw ausgeführten Schreibvorgängen sicher abgelehnt, anstatt die Konfiguration zu verflachen
• Einschränkung: $include-Pfade müssen innerhalb des Verzeichnisses aufgelöst werden, das openclaw.json enthält. Um eine Verzeichnisstruktur über mehrere Rechner oder Benutzer hinweg gemeinsam zu verwenden, setzen Sie OPENCLAW_INCLUDE_ROOTS auf eine Pfadliste (: unter POSIX, ; unter Windows) mit zusätzlichen Verzeichnissen, auf die Includes verweisen dürfen. Symbolische Links werden aufgelöst und erneut geprüft. Daher wird ein Pfad weiterhin abgelehnt, der sich lexikalisch in einem Konfigurationsverzeichnis befindet, dessen tatsächliches Ziel jedoch außerhalb aller zulässigen Wurzelverzeichnisse liegt.
• Fehlerbehandlung: eindeutige Fehler bei fehlenden Dateien, Parsing-Fehlern, zirkulären Includes, ungültigem Pfadformat und übermäßiger Länge