Konfiguration

OpenClaw liest eine optionale JSON5-Konfiguration aus ~/.openclaw/openclaw.json (Kommentare + abschließende Kommas erlaubt).

Wenn die Datei fehlt, verwendet OpenClaw sichere Standardwerte (eingebetteter Pi Agent + Sessions pro Absender + Workspace ~/.openclaw/workspace). Du brauchst normalerweise nur eine Konfiguration, um:

einzuschränken, wer den Bot auslösen kann (channels.whatsapp.allowFrom, channels.telegram.allowFrom, usw.)
Gruppen-Allowlists + Mention-Verhalten zu steuern (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
Nachrichtenpräfixe anzupassen (messages)
den Workspace des Agents festzulegen (agents.defaults.workspace oder agents.list[].workspace)
die eingebetteten Agent-Defaults (agents.defaults) und das Session-Verhalten (session) anzupassen
die Identität pro Agent festzulegen (agents.list[].identity)

Neu bei der Konfiguration? Schau dir die Konfigurationsbeispiele an für vollständige Beispiele mit detaillierten Erklärungen!

Strikte Konfigurationsvalidierung

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 aus Sicherheitsgründen nicht startet.

Wenn die Validierung fehlschlägt:

Das Gateway startet nicht.
Nur Diagnose-Befehle sind erlaubt (zum Beispiel: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
Führe openclaw doctor aus, um die genauen Probleme zu sehen.
Führe openclaw doctor --fix (oder --yes) aus, um Migrationen/Reparaturen anzuwenden.

Doctor schreibt niemals Änderungen, es sei denn, du entscheidest dich explizit für --fix/--yes.

Schema + UI-Hinweise

Das Gateway stellt eine JSON-Schema-Repräsentation der Konfiguration über config.schema für UI-Editoren bereit. Die Control UI rendert ein Formular aus diesem Schema, mit einem Raw JSON-Editor als Ausweichmöglichkeit.

Channel-Plugins und Erweiterungen können Schema + UI-Hinweise für ihre Konfiguration registrieren, sodass Channel-Einstellungen schema-gesteuert über Apps hinweg bleiben, ohne hartcodierte Formulare.

Hinweise (Labels, Gruppierung, sensible Felder) werden zusammen mit dem Schema ausgeliefert, damit Clients bessere Formulare rendern können, ohne Konfigurationswissen hartzucodieren.

Apply + Restart (RPC)

Verwende config.apply, um die vollständige Konfiguration zu validieren + zu schreiben und das Gateway in einem Schritt neu zu starten. Es schreibt einen Restart-Sentinel und pingt die letzte aktive Session, nachdem das Gateway zurückkommt.

Warnung: config.apply ersetzt die gesamte Konfiguration. Wenn du nur einige Schlüssel ändern möchtest, verwende config.patch oder openclaw config set. Behalte ein Backup von ~/.openclaw/openclaw.json.

Parameter:

raw (string) — JSON5-Payload für die gesamte Konfiguration
baseHash (optional) — Konfigurations-Hash von config.get (erforderlich, wenn bereits eine Konfiguration existiert)
sessionKey (optional) — letzter aktiver Session-Key für den Wake-up-Ping
note (optional) — Notiz für den Restart-Sentinel
restartDelayMs (optional) — Verzögerung vor dem Neustart (Standard 2000)

Beispiel (via gateway call):

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Partielle Updates (RPC)

Verwende config.patch, um ein partielles Update in die bestehende Konfiguration zu mergen, ohne unzusammenhängende Schlüssel zu überschreiben. Es wendet JSON-Merge-Patch-Semantik an:

Objekte werden rekursiv gemergt
null löscht einen Schlüssel
Arrays ersetzen Wie config.apply validiert es, schreibt die Konfiguration, speichert einen Restart-Sentinel und plant den Gateway-Neustart (mit optionalem Wake, wenn sessionKey angegeben ist).

Parameter:

raw (string) — JSON5-Payload mit nur den zu ändernden Schlüsseln
baseHash (erforderlich) — Konfigurations-Hash von config.get
sessionKey (optional) — letzter aktiver Session-Key für den Wake-up-Ping
note (optional) — Notiz für den Restart-Sentinel
restartDelayMs (optional) — Verzögerung vor dem Neustart (Standard 2000)

Beispiel:

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Minimale Konfiguration (empfohlener Startpunkt)

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

Erstelle das Standard-Image einmalig mit:

scripts/sandbox-setup.sh

Self-Chat-Modus (empfohlen für Gruppensteuerung)

Um zu verhindern, dass der Bot auf WhatsApp @-Mentions in Gruppen antwortet (nur auf bestimmte Text-Trigger reagieren):

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist gilt nur für DMs; deine eigene Nummer einzuschließen aktiviert den Self-Chat-Modus.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Config Includes (`$include`)

Teile deine Konfiguration in mehrere Dateien mit der $include-Direktive auf. Das ist nützlich für:

Organisation großer Konfigurationen (z.B. Agent-Definitionen pro Client)
Teilen gemeinsamer Einstellungen über Umgebungen hinweg
Sensible Konfigurationen separat halten

Grundlegende Verwendung

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Eine einzelne Datei einbinden (ersetzt den Wert des Schlüssels)
  agents: { $include: "./agents.json5" },

  // Mehrere Dateien einbinden (deep-merged in Reihenfolge)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

Merge-Verhalten

Einzelne Datei: Ersetzt das Objekt, das $include enthält
Array von Dateien: Deep-Merge der Dateien in Reihenfolge (spätere Dateien überschreiben frühere)
Mit Geschwister-Schlüsseln: Geschwister-Schlüssel werden nach Includes gemergt (überschreiben eingebundene Werte)
Geschwister-Schlüssel + Arrays/Primitive: Nicht unterstützt (eingebundener Inhalt muss ein Objekt sein)

// Geschwister-Schlüssel überschreiben eingebundene Werte
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99, // Ergebnis: { a: 1, b: 99 }
}

Verschachtelte Includes

Eingebundene Dateien können selbst $include-Direktiven enthalten (bis zu 10 Ebenen tief):

// clients/mueller.json5
{
  agents: { $include: "./mueller/agents.json5" },
  broadcast: { $include: "./mueller/broadcast.json5" },
}

Pfadauflösung

Relative Pfade: Werden relativ zur einbindenden Datei aufgelöst
Absolute Pfade: Werden unverändert verwendet
Übergeordnete Verzeichnisse: ../-Referenzen funktionieren wie erwartet

{ "$include": "./sub/config.json5" }      // relativ
{ "$include": "/etc/openclaw/base.json5" } // absolut
{ "$include": "../shared/common.json5" }   // übergeordnetes Verzeichnis

Fehlerbehandlung

Fehlende Datei: Klare Fehlermeldung mit aufgelöstem Pfad
Parse-Fehler: Zeigt, welche eingebundene Datei fehlgeschlagen ist
Zirkuläre Includes: Werden erkannt und mit Include-Kette gemeldet

Beispiel: Multi-Client-Setup für Anwaltskanzlei

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Gemeinsame Agent-Defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Agent-Listen von allen Clients mergen
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Broadcast-Konfigurationen mergen
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" },
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"],
}

Allgemeine Optionen

Umgebungsvariablen + `.env`

OpenClaw liest Umgebungsvariablen vom übergeordneten Prozess (Shell, launchd/systemd, CI, usw.).

Zusätzlich lädt es:

.env aus dem aktuellen Arbeitsverzeichnis (falls vorhanden)
eine globale Fallback-.env aus ~/.openclaw/.env (auch bekannt als $OPENCLAW_STATE_DIR/.env)

Keine der .env-Dateien überschreibt bestehende Umgebungsvariablen.

Du kannst auch Inline-Umgebungsvariablen in der Konfiguration angeben. Diese werden nur angewendet, wenn die Prozess-Umgebung den Schlüssel nicht enthält (gleiche Nicht-Überschreiben-Regel):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Siehe /environment für vollständige Priorität und Quellen.

`env.shellEnv` (optional)

Opt-in-Komfort: Wenn aktiviert und keiner der erwarteten Schlüssel bereits gesetzt ist, führt OpenClaw deine Login-Shell aus und importiert nur die fehlenden erwarteten Schlüssel (überschreibt niemals). Das sourct effektiv dein Shell-Profil.

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

Umgebungsvariablen-Äquivalent:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Umgebungsvariablen-Substitution in der Konfiguration

Du kannst Umgebungsvariablen direkt in jedem Konfigurations-String-Wert mit ${VAR_NAME}-Syntax referenzieren. Variablen werden beim Laden der Konfiguration substituiert, vor der Validierung.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

Regeln:

Nur Großbuchstaben-Umgebungsvariablennamen werden gematcht: [A-Z_][A-Z0-9_]*
Fehlende oder leere Umgebungsvariablen werfen einen Fehler beim Laden der Konfiguration
Escape mit $${VAR}, um ein literales ${VAR} auszugeben
Funktioniert mit $include (eingebundene Dateien bekommen auch Substitution)

Inline-Substitution:

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1", // → "https://api.example.com/v1"
      },
    },
  },
}

Auth-Speicherung (OAuth + API-Keys)

OpenClaw speichert pro-Agent Auth-Profile (OAuth + API-Keys) in:

<agentDir>/auth-profiles.json (Standard: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

Siehe auch: /concepts/oauth

Legacy-OAuth-Importe:

~/.openclaw/credentials/oauth.json (oder $OPENCLAW_STATE_DIR/credentials/oauth.json)

Der eingebettete Pi Agent pflegt einen Runtime-Cache unter:

<agentDir>/auth.json (automatisch verwaltet; nicht manuell bearbeiten)

Legacy-Agent-Verzeichnis (vor Multi-Agent):

~/.openclaw/agent/* (migriert von openclaw doctor nach ~/.openclaw/agents/<defaultAgentId>/agent/*)

Überschreibungen:

OAuth-Verzeichnis (nur Legacy-Import): OPENCLAW_OAUTH_DIR
Agent-Verzeichnis (Standard-Agent-Root-Überschreibung): OPENCLAW_AGENT_DIR (bevorzugt), PI_CODING_AGENT_DIR (Legacy)

Bei der ersten Verwendung importiert OpenClaw oauth.json-Einträge in auth-profiles.json.

`auth`

Optionale Metadaten für Auth-Profile. Dies speichert keine Secrets; es mappt Profil-IDs auf einen Provider + Modus (und optionale E-Mail) und definiert die Provider- Rotationsreihenfolge für Failover.

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"],
    },
  },
}

`agents.list[].identity`

Optionale pro-Agent-Identität für Defaults und UX. Dies wird vom macOS-Onboarding-Assistenten geschrieben.

Wenn gesetzt, leitet OpenClaw Defaults ab (nur wenn du sie nicht explizit gesetzt hast):

messages.ackReaction vom identity.emoji des aktiven Agents (Fallback auf 👀)
agents.list[].groupChat.mentionPatterns vom identity.name/identity.emoji des Agents (sodass “@Samantha” in Gruppen über Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp funktioniert)
identity.avatar akzeptiert einen workspace-relativen Bildpfad oder eine Remote-URL/Data-URL. Lokale Dateien müssen im Agent-Workspace liegen.

identity.avatar akzeptiert:

Workspace-relativer Pfad (muss im Agent-Workspace bleiben)
http(s)-URL
data:-URI

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

`wizard`

Metadaten, die von CLI-Wizards geschrieben werden (onboard, configure, doctor).

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

`logging`

Standard-Logdatei: /tmp/openclaw/openclaw-YYYY-MM-DD.log
Wenn du einen stabilen Pfad möchtest, setze logging.file auf /tmp/openclaw/openclaw.log.
Konsolenausgabe kann separat angepasst werden via:
- logging.consoleLevel (Standard info, erhöht sich auf debug bei --verbose)
- logging.consoleStyle (pretty | compact | json)
Tool-Zusammenfassungen können redigiert werden, um Secrets nicht preiszugeben:
- logging.redactSensitive (off | tools, Standard: tools)
- logging.redactPatterns (Array von Regex-Strings; überschreibt Defaults)

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Beispiel: Defaults mit eigenen Regeln überschreiben.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
    ],
  },
}

`channels.whatsapp.dmPolicy`

Steuert, wie WhatsApp-Direktchats (DMs) behandelt werden:

"pairing" (Standard): Unbekannte Absender erhalten einen Pairing-Code; der Besitzer muss genehmigen
"allowlist": Nur Absender in channels.whatsapp.allowFrom erlauben (oder gepaarter Allow-Store)
"open": Alle eingehenden DMs erlauben (erfordert channels.whatsapp.allowFrom mit "*")
"disabled": Alle eingehenden DMs ignorieren

Pairing-Codes laufen nach 1 Stunde ab; der Bot sendet nur einen Pairing-Code, wenn eine neue Anfrage erstellt wird. Ausstehende DM-Pairing-Anfragen sind standardmäßig auf 3 pro Channel begrenzt.

Pairing-Genehmigungen:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

`channels.whatsapp.allowFrom`

Allowlist von E.164-Telefonnummern, die WhatsApp-Auto-Antworten auslösen dürfen (nur DMs). Wenn leer und channels.whatsapp.dmPolicy="pairing", erhalten unbekannte Absender einen Pairing-Code. Für Gruppen verwende channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // optionale ausgehende Chunk-Größe (Zeichen)
      chunkMode: "length", // optionaler Chunking-Modus (length | newline)
      mediaMaxMb: 50, // optionale eingehende Medien-Obergrenze (MB)
    },
  },
}

`channels.whatsapp.sendReadReceipts`

Steuert, ob eingehende WhatsApp-Nachrichten als gelesen markiert werden (blaue Häkchen). Standard: true.

Self-Chat-Modus überspringt immer Lesebestätigungen, auch wenn aktiviert.

Pro-Account-Überschreibung: channels.whatsapp.accounts.<id>.sendReadReceipts.

{
  channels: {
    whatsapp: { sendReadReceipts: false },
  },
}

`channels.whatsapp.accounts` (Multi-Account)

Mehrere WhatsApp-Accounts in einem Gateway betreiben:

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // optional; hält die Standard-ID stabil
        personal: {},
        biz: {
          // Optionale Überschreibung. Standard: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Hinweise:

Ausgehende Befehle verwenden standardmäßig Account default, falls vorhanden; andernfalls die erste konfigurierte Account-ID (sortiert).
Das Legacy-Single-Account-Baileys-Auth-Verzeichnis wird von openclaw doctor nach whatsapp/default migriert.

`channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

Mehrere Accounts pro Channel betreiben (jeder Account hat seine eigene accountId und optionalen name):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

Hinweise:

default wird verwendet, wenn accountId weggelassen wird (CLI + Routing).
Umgebungs-Tokens gelten nur für den Standard-Account.
Basis-Channel-Einstellungen (Gruppenrichtlinie, Mention-Gating, usw.) gelten für alle Accounts, sofern nicht pro Account überschrieben.
Verwende bindings[].match.accountId, um jeden Account zu verschiedenen agents.defaults zu routen.

Gruppenchat-Mention-Gating (`agents.list[].groupChat` + `messages.groupChat`)

Gruppennachrichten erfordern standardmäßig Mention (entweder Metadaten-Mention oder Regex-Patterns). Gilt für WhatsApp, Telegram, Discord, Google Chat und iMessage-Gruppenchats.

Mention-Typen:

Metadaten-Mentions: Native Plattform-@-Mentions (z.B. WhatsApp Tap-to-Mention). Werden im WhatsApp-Self-Chat-Modus ignoriert (siehe channels.whatsapp.allowFrom).
Text-Patterns: Regex-Patterns definiert in agents.list[].groupChat.mentionPatterns. Werden immer geprüft, unabhängig vom Self-Chat-Modus.
Mention-Gating wird nur erzwungen, wenn Mention-Erkennung möglich ist (native Mentions oder mindestens ein mentionPattern).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit setzt den globalen Standard für Gruppen-History-Kontext. Channels können mit channels.<channel>.historyLimit überschreiben (oder channels.<channel>.accounts.*.historyLimit für Multi-Account). Setze 0, um History-Wrapping zu deaktivieren.

DM-History-Limits

DM-Konversationen verwenden session-basierte History, die vom Agent verwaltet wird. Du kannst die Anzahl der pro DM-Session behaltenen User-Turns begrenzen:

{
  channels: {
    telegram: {
      dmHistoryLimit: 30, // DM-Sessions auf 30 User-Turns begrenzen
      dms: {
        "123456789": { historyLimit: 50 }, // pro-User-Überschreibung (User-ID)
      },
    },
  },
}

Auflösungsreihenfolge:

Pro-DM-Überschreibung: channels.<provider>.dms[userId].historyLimit
Provider-Standard: channels.<provider>.dmHistoryLimit
Kein Limit (gesamte History wird behalten)

Unterstützte Provider: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Pro-Agent-Überschreibung (hat Vorrang wenn gesetzt, auch []):

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } },
    ],
  },
}

Mention-Gating-Defaults leben pro Channel (channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups, channels.discord.guilds). Wenn *.groups gesetzt ist, fungiert es auch als Gruppen-Allowlist; füge "*" hinzu, um alle Gruppen zu erlauben.

Um nur auf bestimmte Text-Trigger zu antworten (native @-Mentions ignorieren):

{
  channels: {
    whatsapp: {
      // Deine eigene Nummer einschließen aktiviert den Self-Chat-Modus (native @-Mentions ignorieren).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // Nur diese Text-Patterns lösen Antworten aus
          mentionPatterns: ["reisponde", "@openclaw"],
        },
      },
    ],
  },
}

Gruppenrichtlinie (pro Channel)

Verwende channels.*.groupPolicy, um zu steuern, ob Gruppen-/Raumnachrichten überhaupt akzeptiert werden:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"],
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: {
          channels: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
  },
}

Hinweise:

"open": Gruppen umgehen Allowlists; Mention-Gating gilt weiterhin.
"disabled": Alle Gruppen-/Raumnachrichten blockieren.
"allowlist": Nur Gruppen/Räume erlauben, die der konfigurierten Allowlist entsprechen.
channels.defaults.groupPolicy setzt den Standard, wenn groupPolicy eines Providers nicht gesetzt ist.
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams verwenden groupAllowFrom (Fallback: explizites allowFrom).
Discord/Slack verwenden Channel-Allowlists (channels.discord.guilds.*.channels, channels.slack.channels).
Gruppen-DMs (Discord/Slack) werden weiterhin von dm.groupEnabled + dm.groupChannels gesteuert.
Standard ist groupPolicy: "allowlist" (sofern nicht von channels.defaults.groupPolicy überschrieben); wenn keine Allowlist konfiguriert ist, werden Gruppennachrichten blockiert.

Multi-Agent-Routing (`agents.list` + `bindings`)

Mehrere isolierte Agents (separater Workspace, agentDir, Sessions) in einem Gateway betreiben. Eingehende Nachrichten werden über Bindings an einen Agent geroutet.

agents.list[]: pro-Agent-Überschreibungen.
- id: stabile Agent-ID (erforderlich).
- default: optional; wenn mehrere gesetzt sind, gewinnt der erste und eine Warnung wird geloggt. Wenn keiner gesetzt ist, ist der erste Eintrag in der Liste der Standard-Agent.
- name: Anzeigename für den Agent.
- workspace: Standard ~/.openclaw/workspace-<agentId> (für main Fallback auf agents.defaults.workspace).
- agentDir: Standard ~/.openclaw/agents/<agentId>/agent.
- model: pro-Agent-Standardmodell, überschreibt agents.defaults.model für diesen Agent.
  - String-Form: "provider/model", überschreibt nur agents.defaults.model.primary
  - Objekt-Form: { primary, fallbacks } (Fallbacks überschreiben agents.defaults.model.fallbacks; [] deaktiviert globale Fallbacks für diesen Agent)
- identity: pro-Agent Name/Theme/Emoji (verwendet für Mention-Patterns + Ack-Reactions).
- groupChat: pro-Agent Mention-Gating (mentionPatterns).
- sandbox: pro-Agent Sandbox-Konfiguration (überschreibt agents.defaults.sandbox).
  - mode: "off" | "non-main" | "all"
  - workspaceAccess: "none" | "ro" | "rw"
  - scope: "session" | "agent" | "shared"
  - workspaceRoot: benutzerdefinierter Sandbox-Workspace-Root
  - docker: pro-Agent Docker-Überschreibungen (z.B. image, network, env, setupCommand, Limits; ignoriert bei scope: "shared")
  - browser: pro-Agent Sandboxed-Browser-Überschreibungen (ignoriert bei scope: "shared")
  - prune: pro-Agent Sandbox-Pruning-Überschreibungen (ignoriert bei scope: "shared")
- subagents: pro-Agent Sub-Agent-Defaults.
  - allowAgents: Allowlist von Agent-IDs für sessions_spawn von diesem Agent (["*"] = alle erlauben; Standard: nur gleicher Agent)
- tools: pro-Agent Tool-Einschränkungen (angewendet vor Sandbox-Tool-Policy).
  - profile: Basis-Tool-Profil (angewendet vor allow/deny)
  - allow: Array erlaubter Tool-Namen
  - deny: Array verbotener Tool-Namen (deny gewinnt)
agents.defaults: gemeinsame Agent-Defaults (Modell, Workspace, Sandbox, usw.).
bindings[]: routet eingehende Nachrichten zu einer agentId.
- match.channel (erforderlich)
- match.accountId (optional; * = jeder Account; weggelassen = Standard-Account)
- match.peer (optional; { kind: dm|group|channel, id })
- match.guildId / match.teamId (optional; channel-spezifisch)

Deterministische Match-Reihenfolge:

match.peer
match.guildId
match.teamId
match.accountId (exakt, kein peer/guild/team)
match.accountId: "*" (channel-weit, kein peer/guild/team)
Standard-Agent (agents.list[].default, sonst erster Listeneintrag, sonst "main")

Innerhalb jeder Match-Stufe gewinnt der erste passende Eintrag in bindings.

Pro-Agent-Zugriffsprofile (Multi-Agent)

Jeder Agent kann seine eigene Sandbox + Tool-Policy mitbringen. Verwende dies, um Zugriffsebenen in einem Gateway zu mischen:

Voller Zugriff (persönlicher Agent)
Nur-Lesen-Tools + Workspace
Kein Dateisystemzugriff (nur Messaging/Session-Tools)

Siehe Multi-Agent Sandbox & Tools für Priorität und zusätzliche Beispiele.

Voller Zugriff (keine Sandbox):

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

Nur-Lesen-Tools + Nur-Lesen-Workspace:

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "ro",
        },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

Kein Dateisystemzugriff (Messaging/Session-Tools aktiviert):

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: {
          mode: "all",
          scope: "agent",
          workspaceAccess: "none",
        },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

Beispiel: zwei WhatsApp-Accounts → zwei Agents:

{
  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" } },
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      },
    },
  },
}

`tools.agentToAgent` (optional)

Agent-zu-Agent-Messaging ist Opt-in:

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

`messages.queue`

Steuert, wie eingehende Nachrichten sich verhalten, wenn bereits ein Agent-Run aktiv ist.

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },
}

`messages.inbound`

Debounce schnelle eingehende Nachrichten vom gleichen Absender, sodass mehrere aufeinanderfolgende Nachrichten zu einem einzigen Agent-Turn werden. Debouncing ist pro Channel + Konversation begrenzt und verwendet die neueste Nachricht für Reply-Threading/IDs.

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 deaktiviert
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

Hinweise:

Debounce bündelt nur Text-Nachrichten; Medien/Anhänge werden sofort geflusht.
Steuerungsbefehle (z.B. /queue, /new) umgehen Debouncing, damit sie eigenständig bleiben.

`commands` (Chat-Befehlsverarbeitung)

Steuert, wie Chat-Befehle über Connectors hinweg aktiviert werden.

{
  commands: {
    native: "auto", // native Befehle registrieren wenn unterstützt (auto)
    text: true, // Slash-Befehle in Chat-Nachrichten parsen
    bash: false, // ! (Alias: /bash) erlauben (nur Host; erfordert tools.elevated Allowlists)
    bashForegroundMs: 2000, // Bash-Vordergrund-Fenster (0 backgroundet sofort)
    config: false, // /config erlauben (schreibt auf Disk)
    debug: false, // /debug erlauben (nur Runtime-Überschreibungen)
    restart: false, // /restart + Gateway-Restart-Tool erlauben
    useAccessGroups: true, // Access-Group-Allowlists/Policies für Befehle erzwingen
  },
}

Hinweise:

Text-Befehle müssen als eigenständige Nachricht gesendet werden und das führende / verwenden (keine Klartext-Aliase).
commands.text: false deaktiviert das Parsen von Chat-Nachrichten nach Befehlen.
commands.native: "auto" (Standard) aktiviert native Befehle für Discord/Telegram und lässt Slack aus; nicht unterstützte Channels bleiben nur Text.
Setze commands.native: true|false, um alle zu erzwingen, oder überschreibe pro Channel mit channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool oder "auto"). false löscht zuvor registrierte Befehle auf Discord/Telegram beim Start; Slack-Befehle werden in der Slack-App verwaltet.
channels.telegram.customCommands fügt zusätzliche Telegram-Bot-Menüeinträge hinzu. Namen werden normalisiert; Konflikte mit nativen Befehlen werden ignoriert.
commands.bash: true aktiviert ! <cmd>, um Host-Shell-Befehle auszuführen (/bash <cmd> funktioniert auch als Alias). Erfordert tools.elevated.enabled und Allowlisting des Absenders in tools.elevated.allowFrom.<channel>.
commands.bashForegroundMs steuert, wie lange Bash wartet, bevor es in den Hintergrund geht. Während ein Bash-Job läuft, werden neue ! <cmd>-Anfragen abgelehnt (einer nach dem anderen).
commands.config: true aktiviert /config (liest/schreibt openclaw.json).
channels.<provider>.configWrites gatet Konfigurations-Mutationen, die von diesem Channel initiiert werden (Standard: true). Dies gilt für /config set|unset plus provider-spezifische Auto-Migrationen (Telegram-Supergruppen-ID-Änderungen, Slack-Channel-ID-Änderungen).
commands.debug: true aktiviert /debug (nur Runtime-Überschreibungen).
commands.restart: true aktiviert /restart und die Gateway-Tool-Restart-Aktion.
commands.useAccessGroups: false erlaubt Befehlen, Access-Group-Allowlists/Policies zu umgehen.
Slash-Befehle und Direktiven werden nur für autorisierte Absender berücksichtigt. Autorisierung wird aus Channel-Allowlists/Pairing plus commands.useAccessGroups abgeleitet.

`web` (WhatsApp Web Channel Runtime)

WhatsApp läuft über den Web-Channel des Gateways (Baileys Web). Er startet automatisch, wenn eine verknüpfte Session existiert. Setze web.enabled: false, um ihn standardmäßig ausgeschaltet zu lassen.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

`channels.telegram` (Bot-Transport)

OpenClaw startet Telegram nur, wenn ein channels.telegram-Konfigurationsabschnitt existiert. Das Bot-Token wird aus channels.telegram.botToken (oder channels.telegram.tokenFile) aufgelöst, mit TELEGRAM_BOT_TOKEN als Fallback für den Standard-Account. Setze channels.telegram.enabled: false, um den automatischen Start zu deaktivieren. Multi-Account-Unterstützung liegt unter channels.telegram.accounts (siehe Multi-Account-Abschnitt oben). Umgebungs-Tokens gelten nur für den Standard-Account. Setze channels.telegram.configWrites: false, um Telegram-initiierte Konfigurations-Schreibvorgänge zu blockieren (einschließlich Supergruppen-ID-Migrationen und /config set|unset).

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // optional; "open" erfordert ["*"]
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streamMode: "partial", // off | partial | block
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: false,
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

Draft-Streaming-Hinweise:

Verwendet Telegram sendMessageDraft (Draft-Bubble, keine echte Nachricht).
Erfordert private Chat-Topics (message_thread_id in DMs; Bot hat Topics aktiviert).
/reasoning stream streamt Reasoning in den Draft, dann sendet die finale Antwort. Retry-Policy-Defaults und Verhalten sind in Retry Policy dokumentiert.

`channels.discord` (Bot-Transport)

Konfiguriere den Discord-Bot durch Setzen des Bot-Tokens und optionalem Gating: Multi-Account-Unterstützung liegt unter channels.discord.accounts (siehe Multi-Account-Abschnitt oben). Umgebungs-Tokens gelten nur für den Standard-Account.

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["1234567890", "steipete"],
        groupEnabled: false,
        groupChannels: ["openclaw-dm"],
      },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length",
      maxLinesPerMessage: 17,
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

OpenClaw startet Discord nur, wenn ein channels.discord-Konfigurationsabschnitt existiert. Das Token wird aus channels.discord.token aufgelöst, mit DISCORD_BOT_TOKEN als Fallback für den Standard-Account (sofern channels.discord.enabled nicht false ist). Verwende user:<id> (DM) oder channel:<id> (Guild-Channel) bei der Angabe von Zustellzielen für Cron/CLI-Befehle; bloße numerische IDs sind mehrdeutig und werden abgelehnt. Guild-Slugs sind kleingeschrieben mit Leerzeichen ersetzt durch -; Channel-Keys verwenden den slugged Channel-Namen (ohne führendes #). Bevorzuge Guild-IDs als Keys, um Umbenennungs-Mehrdeutigkeiten zu vermeiden. Bot-verfasste Nachrichten werden standardmäßig ignoriert. Aktiviere mit channels.discord.allowBots (eigene Nachrichten werden weiterhin gefiltert, um Self-Reply-Loops zu verhindern). Reaction-Notification-Modi:

off: keine Reaction-Events.
own: Reactions auf die eigenen Nachrichten des Bots (Standard).
all: alle Reactions auf alle Nachrichten.
allowlist: Reactions von guilds.<id>.users auf alle Nachrichten (leere Liste deaktiviert). Ausgehender Text wird durch channels.discord.textChunkLimit (Standard 2000) gechunkt. Setze channels.discord.chunkMode="newline", um an Leerzeilen (Absatzgrenzen) vor dem Längen-Chunking zu splitten. Discord-Clients können sehr hohe Nachrichten abschneiden, daher splittet channels.discord.maxLinesPerMessage (Standard 17) lange mehrzeilige Antworten, auch wenn sie unter 2000 Zeichen sind. Retry-Policy-Defaults und Verhalten sind in Retry Policy dokumentiert.

`channels.googlechat` (Chat API Webhook)

Google Chat läuft über HTTP-Webhooks mit App-Level-Auth (Service Account). Multi-Account-Unterstützung liegt unter channels.googlechat.accounts (siehe Multi-Account-Abschnitt oben). Umgebungsvariablen gelten nur für den Standard-Account.

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Hinweise:

Service-Account-JSON kann inline (serviceAccount) oder dateibasiert (serviceAccountFile) sein.
Umgebungs-Fallbacks für den Standard-Account: GOOGLE_CHAT_SERVICE_ACCOUNT oder GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
audienceType + audience müssen mit der Webhook-Auth-Konfiguration der Chat-App übereinstimmen.
Verwende spaces/<spaceId> oder users/<userId|email> beim Setzen von Zustellzielen.

`channels.slack` (Socket Mode)

Slack läuft im Socket Mode und erfordert sowohl ein Bot-Token als auch ein App-Token:

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["U123", "U456", "*"],
        groupEnabled: false,
        groupChannels: ["G123"],
      },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off",
      thread: {
        historyScope: "thread",
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

Multi-Account-Unterstützung liegt unter channels.slack.accounts (siehe Multi-Account-Abschnitt oben). Umgebungs-Tokens gelten nur für den Standard-Account.

OpenClaw startet Slack, wenn der Provider aktiviert ist und beide Tokens gesetzt sind (via Konfiguration oder SLACK_BOT_TOKEN + SLACK_APP_TOKEN). Verwende user:<id> (DM) oder channel:<id> bei der Angabe von Zustellzielen für Cron/CLI-Befehle. Setze channels.slack.configWrites: false, um Slack-initiierte Konfigurations-Schreibvorgänge zu blockieren (einschließlich Channel-ID-Migrationen und /config set|unset).

Bot-verfasste Nachrichten werden standardmäßig ignoriert. Aktiviere mit channels.slack.allowBots oder channels.slack.channels.<id>.allowBots.

Reaction-Notification-Modi:

off: keine Reaction-Events.
own: Reactions auf die eigenen Nachrichten des Bots (Standard).
all: alle Reactions auf alle Nachrichten.
allowlist: Reactions von channels.slack.reactionAllowlist auf alle Nachrichten (leere Liste deaktiviert).

Thread-Session-Isolation:

channels.slack.thread.historyScope steuert, ob Thread-History pro Thread (thread, Standard) oder über den Channel geteilt (channel) ist.
channels.slack.thread.inheritParent steuert, ob neue Thread-Sessions das Parent-Channel-Transkript erben (Standard: false).

Slack-Action-Gruppen (gaten slack-Tool-Aktionen):

Action-Gruppe	Standard	Hinweise
reactions	aktiviert	React + Reactions auflisten
messages	aktiviert	Lesen/Senden/Bearbeiten/Löschen
pins	aktiviert	Pin/Unpin/Auflisten
memberInfo	aktiviert	Member-Info
emojiList	aktiviert	Custom-Emoji-Liste

`channels.mattermost` (Bot-Token)

Mattermost wird als Plugin ausgeliefert und ist nicht im Core-Install enthalten. Installiere es zuerst: openclaw plugins install @openclaw/mattermost (oder ./extensions/mattermost aus einem Git-Checkout).

Mattermost erfordert ein Bot-Token plus die Basis-URL für deinen Server:

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall",
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

OpenClaw startet Mattermost, wenn der Account konfiguriert ist (Bot-Token + Basis-URL) und aktiviert ist. Das Token + die Basis-URL werden aus channels.mattermost.botToken + channels.mattermost.baseUrl oder MATTERMOST_BOT_TOKEN + MATTERMOST_URL für den Standard-Account aufgelöst (sofern channels.mattermost.enabled nicht false ist).

Chat-Modi:

oncall (Standard): auf Channel-Nachrichten nur antworten, wenn @mentioned.
onmessage: auf jede Channel-Nachricht antworten.
onchar: antworten, wenn eine Nachricht mit einem Trigger-Präfix beginnt (channels.mattermost.oncharPrefixes, Standard [">", "!"]).

Zugriffskontrolle:

Standard-DMs: channels.mattermost.dmPolicy="pairing" (unbekannte Absender erhalten einen Pairing-Code).
Öffentliche DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].
Gruppen: channels.mattermost.groupPolicy="allowlist" standardmäßig (mention-gated). Verwende channels.mattermost.groupAllowFrom, um Absender einzuschränken.

Multi-Account-Unterstützung liegt unter channels.mattermost.accounts (siehe Multi-Account-Abschnitt oben). Umgebungsvariablen gelten nur für den Standard-Account. Verwende channel:<id> oder user:<id> (oder @username) bei der Angabe von Zustellzielen; bloße IDs werden als Channel-IDs behandelt.

`channels.signal` (signal-cli)

Signal-Reactions können System-Events emittieren (gemeinsames Reaction-Tooling):

{
  channels: {
    signal: {
      reactionNotifications: "own",
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

Reaction-Notification-Modi:

off: keine Reaction-Events.
own: Reactions auf die eigenen Nachrichten des Bots (Standard).
all: alle Reactions auf alle Nachrichten.
allowlist: Reactions von channels.signal.reactionAllowlist auf alle Nachrichten (leere Liste deaktiviert).

`channels.imessage` (imsg CLI)

OpenClaw spawnt imsg rpc (JSON-RPC über stdio). Kein Daemon oder Port erforderlich.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

Multi-Account-Unterstützung liegt unter channels.imessage.accounts (siehe Multi-Account-Abschnitt oben).

Hinweise:

Erfordert Full Disk Access zur Messages-DB.
Der erste Send wird nach Messages-Automation-Berechtigung fragen.
Bevorzuge chat_id:<id>-Ziele. Verwende imsg chats --limit 20, um Chats aufzulisten.
channels.imessage.cliPath kann auf ein Wrapper-Script zeigen (z.B. ssh zu einem anderen Mac, der imsg rpc ausführt); verwende SSH-Keys, um Passwort-Prompts zu vermeiden.
Für Remote-SSH-Wrapper setze channels.imessage.remoteHost, um Anhänge via SCP zu fetchen, wenn includeAttachments aktiviert ist.

Beispiel-Wrapper:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

`agents.defaults.workspace`

Setzt das einzelne globale Workspace-Verzeichnis, das vom Agent für Dateioperationen verwendet wird.

Standard: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Wenn agents.defaults.sandbox aktiviert ist, können Nicht-Main-Sessions dies mit ihren eigenen pro-Scope-Workspaces unter agents.defaults.sandbox.workspaceRoot überschreiben.

`agents.defaults.repoRoot`

Optionaler Repository-Root, der in der Runtime-Zeile des System-Prompts angezeigt wird. Wenn nicht gesetzt, versucht OpenClaw ein .git-Verzeichnis zu erkennen, indem es vom Workspace (und aktuellen Arbeitsverzeichnis) aufwärts geht. Der Pfad muss existieren, um verwendet zu werden.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

`agents.defaults.skipBootstrap`

Deaktiviert die automatische Erstellung der Workspace-Bootstrap-Dateien (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md und BOOTSTRAP.md).

Verwende dies für vorbereitete Deployments, bei denen deine Workspace-Dateien aus einem Repo kommen.

{
  agents: { defaults: { skipBootstrap: true } },
}

`agents.defaults.bootstrapMaxChars`

Maximale Zeichen jeder Workspace-Bootstrap-Datei, die in den System-Prompt injiziert werden, bevor sie abgeschnitten wird. Standard: 20000.

Wenn eine Datei dieses Limit überschreitet, loggt OpenClaw eine Warnung und injiziert einen abgeschnittenen Head/Tail mit einem Marker.

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

`agents.defaults.userTimezone`

Setzt die Zeitzone des Benutzers für System-Prompt-Kontext (nicht für Timestamps in Nachrichten-Envelopes). Wenn nicht gesetzt, verwendet OpenClaw die Host-Zeitzone zur Laufzeit.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

`agents.defaults.timeFormat`

Steuert das Zeitformat, das im Abschnitt “Current Date & Time” des System-Prompts angezeigt wird. Standard: auto (OS-Präferenz).

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

`messages`

Steuert eingehende/ausgehende Präfixe und optionale Ack-Reactions. Siehe Messages für Queueing, Sessions und Streaming-Kontext.

{
  messages: {
    responsePrefix: "🦞", // oder "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

responsePrefix wird auf alle ausgehenden Antworten angewendet (Tool-Zusammenfassungen, Block- Streaming, finale Antworten) über Channels hinweg, sofern nicht bereits vorhanden.

Wenn messages.responsePrefix nicht gesetzt ist, wird standardmäßig kein Präfix angewendet. WhatsApp-Self-Chat- Antworten sind die Ausnahme: sie verwenden standardmäßig [{identity.name}] wenn gesetzt, andernfalls [openclaw], damit Same-Phone-Konversationen lesbar bleiben. Setze es auf "auto", um [{identity.name}] für den gerouteten Agent abzuleiten (wenn gesetzt).

Template-Variablen

Der responsePrefix-String kann Template-Variablen enthalten, die dynamisch aufgelöst werden:

Variable	Beschreibung	Beispiel
`{model}`	Kurzer Modellname	`claude-opus-4-5`, `gpt-4o`
`{modelFull}`	Voller Modell-Identifier	`anthropic/claude-opus-4-5`
`{provider}`	Provider-Name	`anthropic`, `openai`
`{thinkingLevel}`	Aktuelles Thinking-Level	`high`, `low`, `off`
`{identity.name}`	Agent-Identity-Name	(wie `"auto"`-Modus)

Variablen sind case-insensitive ({MODEL} = {model}). {think} ist ein Alias für {thinkingLevel}. Nicht aufgelöste Variablen bleiben als literaler Text.

{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

Beispiel-Ausgabe: [claude-opus-4-5 | think:high] Here's my response...

WhatsApp-Inbound-Präfix wird über channels.whatsapp.messagePrefix konfiguriert (veraltet: messages.messagePrefix). Standard bleibt unverändert: "[openclaw]" wenn channels.whatsapp.allowFrom leer ist, andernfalls "" (kein Präfix). Bei Verwendung von "[openclaw]" verwendet OpenClaw stattdessen [{identity.name}], wenn der geroutete Agent identity.name gesetzt hat.

ackReaction sendet eine Best-Effort-Emoji-Reaction, um eingehende Nachrichten auf Channels zu bestätigen, die Reactions unterstützen (Slack/Discord/Telegram/Google Chat). Standard ist das identity.emoji des aktiven Agents wenn gesetzt, andernfalls "👀". Setze es auf "", um zu deaktivieren.

ackReactionScope steuert, wann Reactions feuern:

group-mentions (Standard): nur wenn eine Gruppe/ein Raum Mentions erfordert und der Bot erwähnt wurde
group-all: alle Gruppen-/Raumnachrichten
direct: nur Direktnachrichten
all: alle Nachrichten

removeAckAfterReply entfernt die Ack-Reaction des Bots nach dem Senden einer Antwort (nur Slack/Discord/Telegram/Google Chat). Standard: false.

`messages.tts`

Aktiviere Text-to-Speech für ausgehende Antworten. Wenn aktiviert, generiert OpenClaw Audio mit ElevenLabs oder OpenAI und hängt es an Antworten an. Telegram verwendet Opus- Voice-Notes; andere Channels senden MP3-Audio.

{
  messages: {
    tts: {
      auto: "always",
      mode: "final",
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

Hinweise:

messages.tts.auto steuert Auto-TTS (off, always, inbound, tagged).
/tts off|always|inbound|tagged setzt den pro-Session Auto-Modus (überschreibt Konfiguration).
messages.tts.enabled ist Legacy; Doctor migriert es zu messages.tts.auto.
prefsPath speichert lokale Überschreibungen (Provider/Limit/Summarize).
maxTextLength ist ein hartes Limit für TTS-Input; Zusammenfassungen werden abgeschnitten, um zu passen.
summaryModel überschreibt agents.defaults.model.primary für Auto-Summary.
- Akzeptiert provider/model-Refs oder Aliase aus agents.defaults.models.
modelOverrides aktiviert modellgesteuerte Überschreibungen wie [[tts:...]]-Tags (standardmäßig an).
/tts limit und /tts summary steuern pro-User-Summarization-Einstellungen.
apiKey-Werte fallen zurück auf ELEVENLABS_API_KEY/XI_API_KEY und OPENAI_API_KEY.
elevenlabs.baseUrl überschreibt die ElevenLabs-API-Basis-URL.
elevenlabs.voiceSettings unterstützt stability/similarityBoost/style (0..1), useSpeakerBoost und speed (0.5..2.0).

`talk`

Defaults für Talk-Modus (macOS/iOS/Android). Voice-IDs fallen zurück auf ELEVENLABS_VOICE_ID oder SAG_VOICE_ID wenn nicht gesetzt. apiKey fällt zurück auf ELEVENLABS_API_KEY (oder das Shell-Profil des Gateways) wenn nicht gesetzt. voiceAliases lässt Talk-Direktiven freundliche Namen verwenden (z.B. "voice":"Clawd").

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true,
  },
}

`agents.defaults`

Steuert die eingebettete Agent-Runtime (Modell/Thinking/Verbose/Timeouts). agents.defaults.models definiert den konfigurierten Modellkatalog (und fungiert als Allowlist für /model). agents.defaults.model.primary setzt das Standardmodell; agents.defaults.model.fallbacks sind globale Failover. agents.defaults.imageModel ist optional und wird nur verwendet, wenn das primäre Modell keinen Bild-Input hat. Jeder agents.defaults.models-Eintrag kann enthalten:

alias (optionaler Modell-Shortcut, z.B. /opus).
params (optionale provider-spezifische API-Parameter, die an die Modellanfrage durchgereicht werden).

params wird auch auf Streaming-Runs angewendet (eingebetteter Agent + Compaction). Heute unterstützte Keys: temperature, maxTokens. Diese werden mit Call-Time-Optionen gemergt; vom Aufrufer bereitgestellte Werte gewinnen. temperature ist ein fortgeschrittener Regler — lass ihn ungesetzt, es sei denn, du kennst die Defaults des Modells und brauchst eine Änderung.

Beispiel:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 },
        },
        "openai/gpt-5.2": {
          params: { maxTokens: 8192 },
        },
      },
    },
  },
}

Z.AI GLM-4.x-Modelle aktivieren automatisch Thinking-Modus, es sei denn, du:

setzt --thinking off, oder
definierst agents.defaults.models["zai/<model>"].params.thinking selbst.

OpenClaw liefert auch einige eingebaute Alias-Shortcuts. Defaults gelten nur, wenn das Modell bereits in agents.defaults.models vorhanden ist:

opus -> anthropic/claude-opus-4-5
sonnet -> anthropic/claude-sonnet-4-5
gpt -> openai/gpt-5.2
gpt-mini -> openai/gpt-5-mini
gemini -> google/gemini-3-pro-preview
gemini-flash -> google/gemini-3-flash-preview

Wenn du denselben Alias-Namen (case-insensitive) selbst konfigurierst, gewinnt dein Wert (Defaults überschreiben nie).

Beispiel: Opus 4.5 primär mit MiniMax M2.1 Fallback (gehostetes MiniMax):

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"],
      },
    },
  },
}

MiniMax-Auth: setze MINIMAX_API_KEY (Umgebung) oder konfiguriere models.providers.minimax.

Weiter: Agent Runtime

Konfiguration

Strikte Konfigurationsvalidierung

Schema + UI-Hinweise

Apply + Restart (RPC)

Partielle Updates (RPC)

Minimale Konfiguration (empfohlener Startpunkt)

Self-Chat-Modus (empfohlen für Gruppensteuerung)

Config Includes ($include)

Grundlegende Verwendung

Merge-Verhalten

Verschachtelte Includes

Pfadauflösung

Fehlerbehandlung

Beispiel: Multi-Client-Setup für Anwaltskanzlei

Allgemeine Optionen

Umgebungsvariablen + .env

env.shellEnv (optional)

Umgebungsvariablen-Substitution in der Konfiguration

Auth-Speicherung (OAuth + API-Keys)

auth

agents.list[].identity

wizard

logging

channels.whatsapp.dmPolicy

channels.whatsapp.allowFrom

channels.whatsapp.sendReadReceipts

channels.whatsapp.accounts (Multi-Account)

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

Gruppenchat-Mention-Gating (agents.list[].groupChat + messages.groupChat)

DM-History-Limits

Gruppenrichtlinie (pro Channel)

Multi-Agent-Routing (agents.list + bindings)

Pro-Agent-Zugriffsprofile (Multi-Agent)

tools.agentToAgent (optional)

messages.queue

messages.inbound

commands (Chat-Befehlsverarbeitung)

web (WhatsApp Web Channel Runtime)

channels.telegram (Bot-Transport)

channels.discord (Bot-Transport)

channels.googlechat (Chat API Webhook)

channels.slack (Socket Mode)

channels.mattermost (Bot-Token)

channels.signal (signal-cli)

channels.imessage (imsg CLI)

agents.defaults.workspace

agents.defaults.repoRoot

agents.defaults.skipBootstrap

agents.defaults.bootstrapMaxChars

agents.defaults.userTimezone

agents.defaults.timeFormat

messages

Template-Variablen

messages.tts

talk

agents.defaults

Config Includes (`$include`)

Umgebungsvariablen + `.env`

`env.shellEnv` (optional)

`auth`

`agents.list[].identity`

`wizard`

`logging`

`channels.whatsapp.dmPolicy`

`channels.whatsapp.allowFrom`

`channels.whatsapp.sendReadReceipts`

`channels.whatsapp.accounts` (Multi-Account)

`channels.telegram.accounts` / `channels.discord.accounts` / `channels.googlechat.accounts` / `channels.slack.accounts` / `channels.mattermost.accounts` / `channels.signal.accounts` / `channels.imessage.accounts`

Gruppenchat-Mention-Gating (`agents.list[].groupChat` + `messages.groupChat`)

Multi-Agent-Routing (`agents.list` + `bindings`)

`tools.agentToAgent` (optional)

`messages.queue`

`messages.inbound`

`commands` (Chat-Befehlsverarbeitung)

`web` (WhatsApp Web Channel Runtime)

`channels.telegram` (Bot-Transport)

`channels.discord` (Bot-Transport)

`channels.googlechat` (Chat API Webhook)

`channels.slack` (Socket Mode)

`channels.mattermost` (Bot-Token)

`channels.signal` (signal-cli)

`channels.imessage` (imsg CLI)

`agents.defaults.workspace`

`agents.defaults.repoRoot`

`agents.defaults.skipBootstrap`

`agents.defaults.bootstrapMaxChars`

`agents.defaults.userTimezone`

`agents.defaults.timeFormat`

`messages`

`messages.tts`

`talk`

`agents.defaults`