Konfiguration

Jeder Kanal hat seinen eigenen Konfigurationsabschnitt unter `channels.<provider>`. Die Setup-Schritte findest du auf der jeweiligen Kanal-Seite:

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

Alle Kanäle verwenden das gleiche DM-Policy-Muster:

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

Primärmodell und optionale Fallbacks festlegen:

```json5
{
  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`).
- `agents.defaults.imageMaxDimensionPx` steuert die Transkript-/Tool-Bild-Verkleinerung (Standard `1200`); niedrigere Werte reduzieren in der Regel den Vision-Token-Verbrauch bei screenshot-lastigen Runs.
- Unter [Models CLI](/docs/concepts/models) findest du Infos zum Modellwechsel im Chat und unter [Model Failover](/docs/concepts/model-failover) das Auth-Rotations- und Fallback-Verhalten.
- Für benutzerdefinierte/selbst gehostete Anbieter siehe [Benutzerdefinierte Anbieter](/docs/gateway/configuration-reference#custom-providers-and-base-urls) in der Referenz.

DM-Zugang wird pro Kanal über `dmPolicy` gesteuert:

- `"pairing"` (Standard): Unbekannte Absender erhalten einen einmaligen Pairing-Code zur Genehmigung
- `"allowlist"`: Nur Absender in `allowFrom` (oder dem Pairing-Allow-Store)
- `"open"`: Alle eingehenden DMs erlauben (erfordert `allowFrom: ["*"]`)
- `"disabled"`: Alle DMs ignorieren

Für Gruppen verwende `groupPolicy` + `groupAllowFrom` oder kanalspezifische Allowlists.

Die [vollständige Referenz](/docs/gateway/configuration-reference#dm-and-group-access) enthält Details pro Kanal.

Gruppennachrichten erfordern standardmäßig eine **Erwähnung**. Konfiguriere Muster pro Agent:

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **Metadaten-Erwähnungen**: Native @-Erwähnungen (WhatsApp Antippen-zum-Erwähnen, Telegram @bot usw.)
- **Textmuster**: Regex-Muster in `mentionPatterns`
- Unter [vollständige Referenz](/docs/gateway/configuration-reference#group-chat-mention-gating) findest du kanalspezifische Overrides und den Self-Chat-Modus.

Sessions steuern die Gesprächskontinuität und -isolation:

```json5
{
  session: {
    dmScope: "per-channel-peer",  // empfohlen für Mehrbenutzer
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`: `main` (geteilt) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: Globale Standards für Thread-gebundenes Session-Routing (Discord unterstützt `/focus`, `/unfocus`, `/agents`, `/session idle` und `/session max-age`).
- Unter [Session Management](/docs/concepts/session) findest du Scoping, Identity-Links und Send-Policy.
- Unter [vollständige Referenz](/docs/gateway/configuration-reference#session) findest du alle Felder.

Agent-Sessions in isolierten Docker-Containern ausführen:

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

Baue zuerst das Image: `scripts/sandbox-setup.sh`

Unter [Sandboxing](/docs/gateway/sandboxing) findest du den vollständigen Guide und unter [vollständige Referenz](/docs/gateway/configuration-reference#sandbox) alle Optionen.

Relay-basierter Push wird in `openclaw.json` konfiguriert.

Setze das in der Gateway-Konfiguration:

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

CLI-Äquivalent:

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

Was das bewirkt:

- Ermöglicht dem Gateway, `push.test`, Wake-Nudges und Reconnect-Wakes über das externe Relay zu senden.
- Verwendet einen registrierungsgebundenen Send-Grant, der von der gepaarten iOS-App weitergeleitet wird. Das Gateway benötigt keinen deploymentweiten Relay-Token.
- Bindet jede Relay-basierte Registrierung an die Gateway-Identität, mit der sich die iOS-App gepairt hat, sodass ein anderes Gateway die gespeicherte Registrierung nicht wiederverwenden kann.
- Behält lokale/manuelle iOS-Builds auf direktem APNs bei. Relay-basierte Sends gelten nur für offiziell verteilte Builds, die sich über das Relay registriert haben.
- Muss mit der Relay-Base-URL übereinstimmen, die in den offiziellen/TestFlight iOS-Build eingebaut ist, damit Registrierungs- und Send-Verkehr dasselbe Relay-Deployment erreichen.

End-to-End-Flow:

1. Installiere einen offiziellen/TestFlight iOS-Build, der mit derselben Relay-Base-URL kompiliert wurde.
2. Konfiguriere `gateway.push.apns.relay.baseUrl` auf dem Gateway.
3. Paire die iOS-App mit dem Gateway und lass sowohl Node- als auch Operator-Sessions verbinden.
4. Die iOS-App ruft die Gateway-Identität ab, registriert sich beim Relay mittels App Attest plus App Receipt und veröffentlicht dann den Relay-basierten `push.apns.register`-Payload an das gepaarte Gateway.
5. Das Gateway speichert den Relay-Handle und Send-Grant und verwendet sie für `push.test`, Wake-Nudges und Reconnect-Wakes.

Betriebshinweise:

- Wenn du die iOS-App auf ein anderes Gateway umstellst, verbinde die App erneut, damit sie eine neue Relay-Registrierung gebunden an dieses Gateway veröffentlichen kann.
- Wenn du einen neuen iOS-Build veröffentlichst, der auf ein anderes Relay-Deployment zeigt, aktualisiert die App ihre gecachte 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 Env-Overrides.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` bleibt ein Loopback-only-Entwicklungs-Escape-Hatch; persistiere keine HTTP-Relay-URLs in der Konfiguration.

Unter [iOS App](/docs/platforms/ios#relay-backed-push-for-official-builds) findest du den End-to-End-Flow und unter [Authentifizierungs- und Trust-Flow](/docs/platforms/ios#authentication-and-trust-flow) das Relay-Sicherheitsmodell.

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

- `every`: Duration-String (`30m`, `2h`). Setze `0m` zum Deaktivieren.
- `target`: `last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`: `allow` (Standard) oder `block` für DM-artige Heartbeat-Ziele
- Unter [Heartbeat](/docs/gateway/heartbeat) findest du den vollständigen Guide.

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`: Bereinigt abgeschlossene isolierte Run-Sessions aus `sessions.json` (Standard `24h`; setze `false` zum Deaktivieren).
- `runLog`: Bereinigt `cron/runs/<jobId>.jsonl` nach Größe und behaltenen Zeilen.
- Unter [Cron-Jobs](/docs/automation/cron-jobs) findest du die Feature-Übersicht und CLI-Beispiele.

HTTP-Webhook-Endpoints auf dem Gateway aktivieren:

```json5
{
  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:
- Behandle alle Hook-/Webhook-Payload-Inhalte als nicht vertrauenswürdige Eingabe.
- Halte Unsafe-Content-Bypass-Flags deaktiviert (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), sofern du nicht eng begrenztes Debugging durchführst.
- Bevorzuge für Hook-gesteuerte Agenten starke moderne Modell-Tiers und strikte Tool-Policies (z. B. nur Messaging plus Sandboxing wo möglich).

Unter [vollständige Referenz](/docs/gateway/configuration-reference#hooks) findest du alle Mapping-Optionen und die Gmail-Integration.

Mehrere isolierte Agenten mit separaten Workspaces und Sessions betreiben:

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

Unter [Multi-Agent](/docs/concepts/multi-agent) und [vollständige Referenz](/docs/gateway/configuration-reference#multi-agent-routing) findest du Binding-Regeln und pro-Agent-Zugriffsprofile.

Verwende `$include`, um umfangreiche Konfigurationen zu organisieren:

```json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
```

- **Einzeldatei**: Ersetzt das enthaltende Objekt
- **Array von Dateien**: Deep-Merge in Reihenfolge (spätere gewinnt)
- **Geschwister-Schlüssel**: Nach Includes zusammengeführt (überschreiben importierte Werte)
- **Verschachtelte Includes**: Unterstützt bis zu 10 Ebenen tief
- **Relative Pfade**: Relativ zur einschließenden Datei aufgelöst
- **Fehlerbehandlung**: Klare Fehler bei fehlenden Dateien, Parse-Fehlern und zirkulären Includes

Validiert + schreibt die gesamte Konfiguration und startet das Gateway in einem Schritt neu.

> **Warnung:** `config.apply` ersetzt die **gesamte Konfiguration**. Verwende `config.patch` für teilweise Updates oder `openclaw config set` für einzelne Schlüssel.

Parameter:

- `raw` (String) — JSON5-Payload für die gesamte Konfiguration
- `baseHash` (optional) — Konfigurations-Hash aus `config.get` (erforderlich wenn Konfiguration existiert)
- `sessionKey` (optional) — Session-Key für den Post-Neustart-Wake-up-Ping
- `note` (optional) — Notiz für den Neustart-Sentinel
- `restartDelayMs` (optional) — Verzögerung vor dem Neustart (Standard 2000)

Neustart-Anfragen werden zusammengefasst, wenn bereits eine pending/in-flight ist, und ein 30-Sekunden-Cooldown gilt zwischen Neustart-Zyklen.

```bash
openclaw gateway call config.get --params '{}'  # payload.hash erfassen
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

Führt ein teilweises Update in die bestehende Konfiguration ein (JSON-Merge-Patch-Semantik):

- Objekte werden rekursiv zusammengeführt
- `null` löscht einen Schlüssel
- Arrays ersetzen

Parameter:

- `raw` (String) — JSON5 mit nur den zu ändernden Schlüsseln
- `baseHash` (erforderlich) — Konfigurations-Hash aus `config.get`
- `sessionKey`, `note`, `restartDelayMs` — wie bei `config.apply`

Neustart-Verhalten entspricht `config.apply`: zusammengefasste Pending-Neustarts plus ein 30-Sekunden-Cooldown zwischen Neustart-Zyklen.

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

Wenn aktiviert und erwartete Schlüssel nicht gesetzt sind, startet OpenClaw deine Login-Shell und importiert nur die fehlenden Schlüssel:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Umgebungsvariablen-Äquivalent: OPENCLAW_LOAD_SHELL_ENV=1

Referenziere Umgebungsvariablen in jedem Konfigurationsstringwert mit ${VAR_NAME}:

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Regeln:

• Nur Großbuchstabennamen werden gematcht: [A-Z_][A-Z0-9_]*
• Fehlende/leere Variablen werfen einen Fehler beim Laden
• Escape mit $${VAR} für wörtliche Ausgabe
• Funktioniert innerhalb von $include-Dateien
• Inline-Substitution: "${BASE}/v1" → "https://api.example.com/v1"

Für Felder, die SecretRef-Objekte unterstützen, kannst du verwenden:

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef-Details (einschließlich secrets.providers für env/file/exec) findest du unter Secrets Management. Unterstützte Credential-Pfade sind unter SecretRef Credential Surface aufgelistet.