Konfiguration

Jeder Kanal besitzt unter channels.<provider> einen eigenen Konfigurationsabschnitt. Die Schritte zur Einrichtung 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 Muster für DM-Richtlinien:

{  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 Ausweichmodelle 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 speichert Aliasse und modellspezifische Einstellungen; das Hinzufügen eines Eintrags schränkt Überschreibungen durch /model oder --model niemals ein.
• agents.defaults.modelPolicy.allow ist die explizite Zulassungsliste für Überschreibungen und Modellauswahlfelder. Sie akzeptiert exakte Referenzen und provider/*-Platzhalter; lassen Sie sie weg oder verwenden Sie [], um jedes Modell zuzulassen.
• 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 üblicherweise die Nutzung von Vision-Tokens.
• Informationen zum Wechseln von Modellen im Chat finden Sie unter Modelle-CLI, Informationen zur Rotation der Authentifizierung und zum Ausweichverhalten unter Modell-Failover.
• Informationen zu benutzerdefinierten oder selbst gehosteten Providern finden Sie unter Benutzerdefinierte Provider in der Referenz.

Der DM-Zugriff 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 für gekoppelte Zulassungen)
• "open": Alle eingehenden DMs zulassen (erfordert allowFrom: ["*"])
• "disabled": Alle DMs 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.

Für Gruppennachrichten ist standardmäßig eine Erwähnung erforderlich. Konfigurieren Sie die Auslösemuster pro Agent. Normale Gruppen- und Kanalantworten werden automatisch veröffentlicht; aktivieren Sie für gemeinsam genutzte Räume, in denen der Agent selbst entscheiden soll, wann er spricht, ausdrücklich den Pfad über das Nachrichten-Tool:

{  messages: {    visibleReplies: "automatic", // auf "message_tool" setzen, um überall Sends über das Nachrichten-Tool zu verlangen    groupChat: {      visibleReplies: "message_tool", // Opt-in; sichtbare Ausgabe erfordert message(action=send)      unmentionedInbound: "room_event", // nicht erwähnte, ständig 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 Sends über das Nachrichten-Tool global verlangen; messages.groupChat.visibleReplies überschreibt dies für Gruppen/Kanäle.
• Informationen zu Modi für sichtbare Antworten, kanalspezifischen Überschreibungen und dem Selbstchatmodus finden Sie in der vollständigen Referenz.

Verwenden Sie agents.defaults.skills für eine gemeinsame Ausgangsbasis und überschreiben Sie anschließend bestimmte Agenten mit agents.entries.*.skills:

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

• Lassen Sie agents.defaults.skills weg, um Skills standardmäßig nicht einzuschränken.
• Lassen Sie agents.entries.*.skills weg, um die Standardwerte zu erben.
• Legen Sie agents.entries.*.skills: [] fest, um keine Skills zuzulassen.
• Weitere Informationen finden Sie unter Skills, Skills-Konfiguration und in der Konfigurationsreferenz.

Deaktivieren oder aktivieren Sie automatische Neustarts bei Zustandsproblemen für einen Kanal oder ein Konto:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• 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 steuern.
• Informationen zur betrieblichen Fehlerdiagnose finden Sie unter Zustandsprüfungen, alle Felder in der vollständigen Referenz.

Sitzungen steuern die Kontinuität und Isolation von Unterhaltungen:

{  session: {    dmScope: "per-channel-peer",  // für mehrere Benutzer empfohlen    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, lösen, listen und konfigurieren dies pro Sitzung (Discord bindet Threads, Telegram bindet Themen/Unterhaltungen).
• Informationen zu Geltungsbereichen, Identitätsverknüpfungen und Senderichtlinien finden Sie unter Sitzungsverwaltung.
• Alle Felder finden Sie in der vollständigen Referenz.

Führen Sie Agentensitzungen 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, 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- und 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,        },      },    },  },}

Entsprechender CLI-Befehl:

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

Funktionsweise:

• Ermöglicht dem Gateway, push.test, Aktivierungsimpulse und Aktivierungen zur Wiederverbindung über das externe Relay zu senden.
• Verwendet eine auf die Registrierung beschränkte 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 kein anderes Gateway die gespeicherte Registrierung wiederverwenden kann.
• Lokale/manuelle iOS-Builds verwenden weiterhin direkte APNs. Relay-gestütztes Senden gilt nur für offiziell verteilte Builds, die über das Relay registriert wurden.
• Muss mit der im iOS-Build eingebetteten 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 einen bewusst getrennten benutzerdefinierten Relay-Build verwenden.
3. Koppeln Sie die iOS-App mit dem Gateway und lassen Sie sowohl Node- als auch Operatorsitzungen eine Verbindung herstellen.
4. Die iOS-App ruft die Gateway-Identität ab, registriert sich mittels App Attest und App-Beleg beim Relay und veröffentlicht anschließend die Relay-gestützte push.apns.register-Nutzlast an das gekoppelte Gateway.
5. Das Gateway speichert das Relay-Handle und die Sendeberechtigung und verwendet sie anschließend für push.test, Aktivierungsimpulse und Aktivierungen zur Wiederverbindung.

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 im iOS-Build eingebetteten Relay-Basis-URL übereinstimmen; der öffentliche App-Store-Release-Kanal 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 HTTP-Relay-URLs nicht 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: Zeitdauerzeichenfolge (30m, 2h). Setzen Sie 0m, um die Funktion zu deaktivieren. Standardwert: 30m.
• target: last | none | <channel-id> (zum Beispiel discord, matrix, telegram oder whatsapp)
• directPolicy: allow (Standardwert) oder block für DM-artige Heartbeat-Ziele
• Die vollständige Anleitung finden Sie unter Heartbeat.

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: Entfernt abgeschlossene isolierte Ausführungssitzungen aus SQLite-Sitzungszeilen (Standardwert 24h; zum Deaktivieren false festlegen).
• Der Ausführungsverlauf bewahrt automatisch die neuesten 2000 Terminalzeilen pro Aufgabe auf; verlorene Zeilen behalten ihr 24-stündiges Bereinigungsfenster.
• Eine Funktionsübersicht und CLI-Beispiele finden Sie unter Cron-Aufgaben.

Aktivieren Sie HTTP-Webhook-Endpunkte auf dem 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 Hook-/Webhook-Nutzlastinhalte als nicht vertrauenswürdige Eingaben.
• Verwenden Sie ein dediziertes hooks.token; verwenden Sie keine aktiven Gateway-Authentifizierungsgeheimnisse erneut (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN oder gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Die Hook-Authentifizierung erfolgt ausschließlich über Header (Authorization: Bearer ... oder x-openclaw-token); Token in Abfragezeichenfolgen werden abgelehnt.
• hooks.path darf nicht / sein; belassen Sie den Webhook-Eingang auf einem dedizierten Unterpfad wie /hooks.
• Lassen Sie Flags zum Umgehen der Prüfung unsicherer Inhalte deaktiviert (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), außer bei eng begrenzter Fehlerdiagnose.
• Wenn Sie hooks.allowRequestSessionKey aktivieren, legen Sie außerdem hooks.allowedSessionKeyPrefixes fest, um die vom Aufrufer gewählten Sitzungsschlüssel einzugrenzen.
• Bevorzugen Sie für Hook-gesteuerte Agenten leistungsfähige moderne Modellstufen und strenge Tool-Richtlinien (zum Beispiel ausschließlich Messaging sowie nach Möglichkeit Sandboxing).

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

Führen Sie mehrere isolierte Agenten mit getrennten 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 umfangreiche 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 enthaltende Objekt
• Datei-Array: Wird der Reihe nach tief zusammengeführt (spätere Werte haben Vorrang), bis zu 10 verschachtelte Ebenen
• Schwesterschlüssel: Werden nach den Einbindungen zusammengeführt (überschreiben eingebundene Werte)
• Relative Pfade: Werden relativ zur einbindenden Datei aufgelöst
• Pfadformat: Einbindungspfade dürfen keine Nullbytes enthalten und müssen vor und nach der Auflösung strikt kürzer als 4096 Zeichen sein
• OpenClaw-eigene Schreibvorgänge: Wenn ein Schreibvorgang nur einen Abschnitt der obersten Ebene ändert, der durch eine Einbindung 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-Einbindungen, Einbindungs-Arrays und Einbindungen mit Schwesterschlüssel-Überschreibungen schlagen bei OpenClaw-eigenen Schreibvorgängen sicher fehl, anstatt die Konfiguration zu verflachen
• Einschränkung: $include-Pfade müssen unterhalb des Verzeichnisses aufgelöst werden, das openclaw.json enthält. Um einen Verzeichnisbaum über Computer oder Benutzer hinweg gemeinsam zu verwenden, legen Sie OPENCLAW_INCLUDE_ROOTS auf eine Pfadliste (: unter POSIX, ; unter Windows) mit zusätzlichen Verzeichnissen fest, auf die Einbindungen verweisen dürfen. Symbolische Links werden aufgelöst und erneut geprüft. Daher wird ein Pfad weiterhin abgelehnt, der lexikalisch in einem Konfigurationsverzeichnis liegt, dessen tatsächliches Ziel jedoch aus allen zulässigen Wurzelverzeichnissen herausführt.
• Fehlerbehandlung: Eindeutige Fehler bei fehlenden Dateien, Analysefehlern, zirkulären Einbindungen, ungültigem Pfadformat und übermäßiger Länge