Konfiguration

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

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

Alle Kanäle teilen dasselbe DM-Richtlinienmuster:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // nur fuer 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 Allowlist für /model.
• Verwenden Sie openclaw config set agents.defaults.models '<json>' --strict-json --merge, um Allowlist-Einträge 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 das Herunterskalieren von Transcript-/Tool-Bildern (Standard 1200); niedrigere Werte reduzieren in der Regel die Vision-Token-Nutzung bei screenshot-intensiven Durchläufen.
• Siehe Models CLI zum Wechseln von Modellen im Chat und Model Failover für Auth-Rotation und Fallback-Verhalten.
• Für benutzerdefinierte/selbst gehostete Provider siehe Benutzerdefinierte Provider in der Referenz.

Der DM-Zugriff wird pro Kanal über dmPolicy gesteuert:

• "pairing" (Standard): unbekannte Absender erhalten einen einmaligen Pairing-Code zur Freigabe
• "allowlist": nur Absender in allowFrom (oder im gekoppelten Allow-Store)
• "open": alle eingehenden DMs zulassen (erfordert allowFrom: ["*"])
• "disabled": alle DMs ignorieren

Verwenden Sie für Gruppen groupPolicy + groupAllowFrom oder kanalspezifische Allowlists.

Details pro Kanal finden Sie in der vollständigen Referenz.

Gruppennachrichten erfordern standardmäßig eine Mention. Konfigurieren Sie Trigger-Muster pro Agent, und belassen Sie sichtbare Raumantworten auf dem standardmäßigen Message-Tool-Pfad, sofern Sie nicht bewusst ältere automatische finale Antworten verwenden möchten:

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadaten-Mentions: native @-Mentions (WhatsApp „Zum Erwähnen tippen“, Telegram @bot usw.)
• Textmuster: sichere Regex-Muster in mentionPatterns
• Sichtbare Antworten: messages.visibleReplies kann Message-Tool-Sends global erzwingen; messages.groupChat.visibleReplies überschreibt dies für Gruppen/Kanäle.
• Siehe vollständige Referenz für Modi sichtbarer Antworten, Überschreibungen pro Kanal und Self-Chat-Modus.

Verwenden Sie agents.defaults.skills für eine gemeinsame Baseline, und überschreiben Sie dann bestimmte Agents mit agents.list[].skills:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Lassen Sie agents.defaults.skills aus, um Skills standardmäßig uneingeschränkt zuzulassen.
• Lassen Sie agents.list[].skills aus, um die Standards zu übernehmen.
• Setzen Sie agents.list[].skills: [], um keine Skills zuzulassen.
• Siehe Skills, Skills-Konfiguration und die Konfigurationsreferenz.

Steuern Sie, wie aggressiv das Gateway Kanäle neu startet, die veraltet wirken:

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

• Setzen Sie gateway.channelHealthCheckMinutes: 0, um Neustarts durch den Health-Monitor 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 Kanal oder Account zu deaktivieren, ohne den globalen Monitor zu deaktivieren.
• Siehe Health Checks für operatives Debugging und die vollständige Referenz für alle Felder.

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

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Standardwert ist 15000 Millisekunden.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS hat weiterhin Vorrang für einmalige Service- oder Shell-Überschreibungen.
• Beheben Sie bevorzugt zuerst Start-/Event-Loop-Blockaden; diese Option ist für Hosts gedacht, die fehlerfrei, aber beim Warmup langsam sind.

Sitzungen steuern Gesprächskontinuität und Isolation:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    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 Thread-gebundenes Sitzungs-Routing (Discord unterstützt /focus, /unfocus, /agents, /session idle und /session max-age).
• Siehe Sitzungsverwaltung für Scoping, Identitätsverknüpfungen und Senderichtlinie.
• Siehe vollständige Referenz für alle Felder.

Führen Sie Agent-Sitzungen in isolierten Sandbox-Runtimes 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 Source-Checkout scripts/sandbox-setup.sh aus, oder lesen Sie bei einer npm-Installation den eingebetteten docker build-Befehl unter Sandboxing § Images und Einrichtung.

Siehe Sandboxing für die vollständige Anleitung und vollständige Referenz für alle Optionen.

Relay-gestützter Push wird in openclaw.json konfiguriert.

Legen Sie dies in der Gateway-Konfiguration fest:

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

CLI-Entsprechung:

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

Was dies bewirkt:

• Ermöglicht dem Gateway, push.test, Wake-Nudges und Reconnect-Wakes über das externe Relay zu senden.
• Verwendet eine registrierungsbezogene Sendeberechtigung, die von der gekoppelten iOS-App weitergeleitet wird. Das Gateway benötigt kein deploymentweites 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.
• Belässt lokale/manuelle iOS-Builds bei direktem APNs. Relay-gestützte Sends gelten nur für offiziell verteilte Builds, die über das Relay registriert wurden.
• Muss mit der Relay-Basis-URL übereinstimmen, die in den offiziellen/TestFlight-iOS-Build eingebettet ist, damit Registrierungs- und Sendetraffic dieselbe Relay-Bereitstellung erreichen.

End-to-End-Ablauf:

1. Installieren Sie einen offiziellen/TestFlight-iOS-Build, der mit derselben Relay-Basis-URL kompiliert wurde.
2. Konfigurieren Sie gateway.push.apns.relay.baseUrl auf dem Gateway.
3. Koppeln Sie die iOS-App mit dem Gateway und lassen Sie sowohl Node- als auch Operator-Sitzungen verbinden.
4. Die iOS-App ruft die Gateway-Identität ab, registriert sich beim Relay mit App Attest plus App-Beleg und veröffentlicht anschließend die relay-gestützte push.apns.register-Payload an das gekoppelte Gateway.
5. Das Gateway speichert den Relay-Handle und die Sendeberechtigung und verwendet sie dann für push.test, Wake-Nudges und Reconnect-Wakes.

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, statt den alten Relay-Ursprung wiederzuverwenden.

Kompatibilitätshinweis:

• OPENCLAW_APNS_RELAY_BASE_URL und OPENCLAW_APNS_RELAY_TIMEOUT_MS funktionieren weiterhin als temporäre Env-Overrides.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true bleibt ein nur für local loopback vorgesehener Entwicklungs-Ausweg; speichern Sie keine HTTP-Relay-URLs dauerhaft in der Konfiguration.

Siehe iOS-App für den End-to-End-Ablauf und Authentifizierungs- und Vertrauensablauf für das Relay-Sicherheitsmodell.

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

• every: Dauer-String (30m, 2h). Setzen Sie 0m, um zu deaktivieren.
• target: last | none | <channel-id> (zum Beispiel discord, matrix, telegram oder whatsapp)
• directPolicy: allow (Standard) oder block für DM-artige Heartbeat-Ziele
• Siehe Heartbeat für die vollständige Anleitung.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: abgeschlossene isolierte Run-Sitzungen aus sessions.json bereinigen (Standard 24h; setzen Sie false, um zu deaktivieren).
• runLog: cron/runs/<jobId>.jsonl nach Größe und beibehaltenen Zeilen bereinigen.
• Siehe Cron-Jobs für Feature-Übersicht und CLI-Beispiele.

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 alle Hook-/Webhook-Payload-Inhalte als nicht vertrauenswürdige Eingaben.
• Verwenden Sie ein dediziertes hooks.token; verwenden Sie das gemeinsam genutzte Gateway-Token nicht erneut.
• Hook-Authentifizierung erfolgt nur über Header (Authorization: Bearer ... oder x-openclaw-token); Query-String-Token werden abgelehnt.
• hooks.path darf nicht / sein; halten Sie Webhook-Ingress auf einem dedizierten Unterpfad wie /hooks.
• Lassen Sie Bypass-Flags für unsichere Inhalte deaktiviert (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), außer bei eng begrenztem Debugging.
• Wenn Sie hooks.allowRequestSessionKey aktivieren, setzen Sie auch hooks.allowedSessionKeyPrefixes, um vom Aufrufer ausgewählte Sitzungsschlüssel zu begrenzen.
• Bevorzugen Sie für Hook-gesteuerte Agents starke moderne Modellklassen und strikte Tool-Policy (zum Beispiel nur Messaging plus Sandboxing, wo möglich).

Siehe vollständige Referenz für alle Mapping-Optionen und die Gmail-Integration.

Führen Sie mehrere isolierte Agents mit separaten Workspaces 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" } },
  ],
}

Siehe Multi-Agent und vollständige Referenz für Binding-Regeln und agentenspezifische Zugriffsprofile.

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
• Array von Dateien: wird der Reihe nach tief zusammengeführt (später gewinnt)
• Geschwister-Schlüssel: werden nach Includes zusammengeführt (überschreiben eingebundene Werte)
• Verschachtelte Includes: bis zu 10 Ebenen tief unterstützt
• Relative Pfade: werden relativ zur einbindenden Datei aufgelöst
• OpenClaw-eigene Schreibvorgänge: Wenn ein Schreibvorgang nur einen Top-Level-Abschnitt ändert, der durch einen Single-File-Include 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 Geschwister-Overrides schlagen bei OpenClaw-eigenen Schreibvorgängen geschlossen fehl, statt die Konfiguration zu verflachen
• Einschlussbegrenzung: $include-Pfade müssen unter dem Verzeichnis aufgelöst werden, das openclaw.json enthält. Um einen Baum über Maschinen oder Benutzer hinweg zu teilen, setzen Sie OPENCLAW_INCLUDE_ROOTS auf eine Pfadliste (: unter POSIX, ; unter Windows) zusätzlicher Verzeichnisse, auf die Includes verweisen dürfen. Symlinks werden aufgelöst und erneut geprüft, sodass ein Pfad, der lexikalisch in einem Konfigurationsverzeichnis liegt, dessen echtes Ziel aber jeden erlaubten Root verlässt, weiterhin abgelehnt wird.
• Fehlerbehandlung: klare Fehler bei fehlenden Dateien, Parse-Fehlern und zirkulären Includes