Gateway-Konfiguration: Beispiele und Best Practices

Es ist frustrierend: Du willst dein Gateway schnell in Betrieb nehmen, aber die Konfiguration hält dich auf. Oft passen die kopierten Snippets nicht zur aktuellen Version oder Parameter haben sich stillschweigend geändert.

Anstatt Zeit mit der Suche nach Syntaxfehlern zu verschwenden, solltest du dich an Vorlagen halten, die exakt zum aktuellen Schema passen. Das spart Nerven und bringt deinen Service schneller online.

Voraussetzungen

Zugriff auf das aktuelle Config Schema
Eine laufende Gateway-Instanz

Schnellstart

In 5 Minuten zur fertigen Konfiguration:

Rufe die Konfigurations-Referenz auf.
Wähle ein Beispiel aus, das zu deinem spezifischen Anwendungsfall passt.
Kopiere den Code direkt in deine lokale Konfigurationsdatei.
Starte dein Gateway neu, um die Änderungen zu übernehmen.

Fehlerbehebung

Die bereitgestellten Beispiele sind strikt auf das aktuelle Config Schema ausgerichtet. Falls deine Konfiguration nicht geladen wird, prüfe, ob deine Gateway-Version veraltet ist. Inkompatible Felder oder Parameter lassen sich fast immer durch ein Update auf die neueste Version beheben.

Brauchst du Hilfe bei einem speziellen Setup? Frag den AI Setup Assistant.

Nächste Schritte

Detaillierte Konfigurations-Referenz

Jeder Entwickler kennt das: Du willst eine neue Idee ausprobieren, aber hängst erst mal ewig in der Konfiguration fest. Es ist frustrierend, wenn der Setup-Prozess komplexer wirkt als das eigentliche Projekt.

## Voraussetzungen

- Zugriff auf das Verzeichnis `~/.openclaw/`
- Eine WhatsApp-Nummer für die Kommunikation mit dem Bot

## Schnellstart

Ich empfehle dir, mit einer minimalen Konfiguration zu starten, um die Verbindung zu testen, und dann auf das empfohlene Setup zu wechseln.

### Das absolute Minimum

Erstelle die Datei `~/.openclaw/openclaw.json` und füge diesen Code ein:

```json
{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Speichere die Datei ab. Du kannst dem Bot jetzt direkt eine DM von der angegebenen Nummer aus schicken.

Empfohlener Starter

Wenn die Basis steht, solltest du diese Konfiguration nutzen. Sie ist mein Favorit, da sie deinem Bot eine Identität gibt und die Interaktion in Gruppen präziser steuert:

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Mit diesem Setup nutzt der Bot das anthropic/claude-sonnet-4-5 Model und reagiert in Gruppen nur, wenn er explizit erwähnt wird.

Du hast Fragen zum Setup oder brauchst Hilfe bei der Konfiguration? Nutze den AI Setup Assistant.

Nächste Schritte

---
title: "Fortgeschrittene Konfiguration: Das große Beispiel"
description: "Ein tiefer Einblick in die erweiterten Konfigurationsoptionen von OpenClaw, von Auth-Profilen bis hin zu komplexen Channel-Settings."
---

Du kennst das: Dein Projekt wächst und plötzlich reicht eine minimale Config-Datei nicht mehr aus. Du jonglierst mit verschiedenen API-Keys, willst spezifische Timeouts für Shell-Umgebungen setzen oder Sessions je nach Channel unterschiedlich handhaben. Es ist oft mühsam, alle Optionen einzeln zusammenzusuchen, wenn man eigentlich nur ein komplexeres Setup zum Laufen bringen will.

Ich empfehle dir, direkt mit JSON5 zu arbeiten. Es erlaubt dir Kommentare und Trailing Commas, was die Wartung deiner Config deutlich entspannter macht. Hier ist ein Beispiel, das zeigt, wie du das volle Potenzial der Major Options ausschöpfst.

## Voraussetzungen

*   Eine installierte OpenClaw-Umgebung.
*   Gültige API-Keys für Provider wie OpenRouter, Groq oder Google (Gemini).
*   Zugangsdaten für die jeweiligen Channels (Telegram Bot Token, Discord Token etc.).
*   Optional: Tailscale für sicheres Networking.

## Schnellstart

1.  Erstelle eine Datei namens `openclaw.json5` in deinem Projektverzeichnis.
2.  Kopiere das untenstehende Beispiel in die Datei.
3.  Ersetze die Platzhalter (wie `YOUR_TELEGRAM_BOT_TOKEN`) durch deine echten Daten.
4.  Starte OpenClaw; das System erkennt die JSON5-Struktur automatisch.

```json
{
  // Environment + shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Auth profile metadata (secrets live in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
      "openai-codex": ["openai-codex:default"],
    },
  },

  // Identity
  identity: {
    name: "Samantha",
    theme: "helpful sloth",
    emoji: "🦥",
  },

  // Logging
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Message formatting
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
  },

  // Routing + queue
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50,
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
        signal: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },

  // Tooling
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // Optional CLI fallback (Whisper binary):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Session behavior
  session: {
    scope: "per-sender",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/default/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Channels
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["steipete"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { allow: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Agent runtime
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-5",
        target: "last",
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        perSession: true,
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["steipete"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Custom model providers
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Cron jobs
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "./transforms/gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      topic: "projects/\<project-id\>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
    },
  },

  // Gateway + networking
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

Fehlerbehebung

JSON-Fehler: Wenn du kein JSON5 nutzt, achte darauf, alle Kommentare zu entfernen und keine Trailing Commas am Ende von Listen oder Objekten zu setzen. Reguläres JSON ist strenger.
Media Processing: Falls die Cloud-Modelle bei Audio scheitern, kannst du einen lokalen CLI-Fallback wie Whisper nutzen (siehe auskommentiertes Beispiel im tools.media.audio Bereich).

Noch Fragen zum Setup? Der AI Setup Assistant hilft dir gerne weiter.

Nächste Schritte

Es nervt, wenn man für jedes neue Projekt die komplette Bot-Infrastruktur neu aufbauen muss. Besonders die Verwaltung von Berechtigungen über verschiedene Messenger hinweg oder das Handling von API-Limits kann schnell Zeit fressen, die du lieber in die eigentliche Logik stecken würdest.

Hier sind die gängigsten Konfigurationsmuster, mit denen du deinen Agenten schnell und stabil zum Laufen bringst.

Voraussetzungen

Ein definiertes workspace-Verzeichnis für deinen Agenten
API-Tokens für die gewünschten Channels (Telegram, Discord, Slack oder WhatsApp)
Provider-Zugangsdaten (Anthropic OAuth oder API-Keys)
Optional: Eine lokale Instanz von LM Studio für lokale Modelle

Schnellstart

Diese Beispiele zeigen dir, wie du spezifische Anforderungen mit wenigen Zeilen in der Konfiguration umsetzt.

Multi-Plattform Setup

Wenn du deinen Bot über mehrere Messenger gleichzeitig erreichen willst, ist dies das Basis-Pattern. Du definierst für jeden Channel individuelle Zugriffsbeschränkungen über allowFrom.

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["yourname"] },
    },
  },
}

Sicherer DM-Modus (Shared Inbox)

Falls mehrere Personen mit deinem Bot per DM interagieren (z. B. bei einer dmPolicy: "open" oder mehreren Einträgen in allowFrom), solltest du den Secure DM Mode aktivieren. Das verhindert, dass verschiedene Nutzer denselben Kontext teilen.

Ich empfehle dieses Setup für alle Agenten, die sensible Daten verarbeiten oder von Teams genutzt werden.

{
  // Secure DM mode (empfohlen für Multi-User oder sensible DMs)
  session: { dmScope: "per-channel-peer" },

  channels: {
    // Beispiel: WhatsApp Multi-User Inbox
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Beispiel: Discord Multi-User Inbox
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["alice", "bob"] },
    },
  },
}

OAuth mit API Key Failover

Dieses Muster ist ideal, wenn du primär dein persönliches Anthropic-Abo via OAuth nutzen möchtest, aber einen API-Key als Rückfallebene brauchst, falls die Session abläuft oder Limits erreicht werden.

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

Work Bot mit eingeschränktem Zugriff

Für einen Bot im professionellen Umfeld solltest du den Zugriff auf spezifische Slack-Channels beschränken und sicherstellen, dass der Agent keine administrativen Rechte im Dateisystem hat (elevated: { enabled: false }).

{
  identity: {
    name: "WorkBot",
    theme: "professional assistant",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

Rein lokaler Betrieb

Wenn du keine externen APIs nutzen möchtest, kannst du OpenClaw so konfigurieren, dass ausschließlich lokale Modelle (z. B. via LM Studio) angesprochen werden.

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.1-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Fehlerbehebung

Problem: DMs von verschiedenen Nutzern vermischen sich oder der Bot erinnert sich an Nachrichten anderer Personen. Lösung: Das passiert, wenn kein individueller Scope für Sessions gesetzt ist. Nutze session: { dmScope: "per-channel-peer" } in deiner Konfiguration, um die Kontexte sauber zu trennen.

Problem: Der Bot antwortet nicht mehr, wenn das Anthropic-Kontingent erschöpft ist. Lösung: Implementiere das Failover-Muster mit auth.order und füge einen zweiten Provider oder einen API-Key als Backup hinzu.

Du brauchst Hilfe bei einem spezifischen Setup? Frag den AI Setup Assistant.

Nächste Schritte

Erfahre mehr über die Authentication Profiles
Details zur Channel-Konfiguration
So bindest du eigene Tools ein

Kennst du das? Du sitzt an der Konfiguration, eigentlich sieht alles richtig aus, aber die Nachrichten gehen einfach nicht durch. Oft liegt es an winzigen Details in der Policy oder einem falschen ID-Format, die man im Eifer des Gefechts übersieht.

Voraussetzungen

Bevor du startest, stelle sicher, dass du diese Dinge bereit hast:

Zugriff auf deine Gateway-Konfiguration
Die spezifische Dokumentation deines Providers

Schnellstart

Damit dein Setup direkt funktioniert, solltest du auf diese zwei Punkte besonders achten:

dmPolicy richtig setzen: Wenn du dich entscheidest, dmPolicy: "open" zu nutzen, musst du zwingend "*" in deine allowFrom Liste aufnehmen. Ohne diesen Wildcard-Eintrag wird der Zugriff blockiert, obwohl die Policy auf “open” steht.
Provider IDs validieren: Jede Plattform kocht ihr eigenes Süppchen. Provider IDs können sehr unterschiedlich aussehen:
- Telefonnummern
- User IDs
- Channel IDs

Geh am besten direkt in die Providers Dokumentation, um das exakte Format für deinen Dienst zu bestätigen.

Falls du dein Setup später erweitern willst, kannst du diese optionalen Sektionen hinzufügen: web, browser, ui, discovery, canvasHost, talk, signal, imessage.

Fehlerbehebung

Falls es hakt, liegt es meistens an den IDs oder den Berechtigungen. Wenn die Verbindung fehlschlägt, ist der erste Schritt immer der Abgleich der Provider-Vorgaben für IDs. Weitere Details dazu findest du auf der Troubleshooting Seite.

Brauchst du Hilfe bei der Implementierung? Frag den AI Setup Assistant.

Nächste Schritte

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.