Konfigurationsbeispiele

Die folgenden Beispiele entsprechen dem aktuellen Konfigurationsschema. Die vollständige Referenz und Hinweise zu den einzelnen Feldern finden Sie unter Konfiguration.

Schnellstart

Absolutes Minimum

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

Speichern Sie dies unter ~/.openclaw/openclaw.json; anschließend können Sie dem Bot von dieser Nummer aus eine Direktnachricht senden.

Empfohlene Startkonfiguration

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
    entries: {
      main: {
        identity: {
          name: "Clawd",
          theme: "helpful assistant",
          emoji: "🦞",
        },
      },
    },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool", // explizite Aktivierung; sichtbare Ausgabe erfordert message(action=send)
      unmentionedInbound: "room_event",
    },
  },
}

Erweitertes Beispiel (wichtigste Optionen)

Mit JSON5 können Sie Kommentare und abschließende Kommas verwenden. Reguläres JSON funktioniert ebenfalls.

{
  // Umgebung + Shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Metadaten der Authentifizierungsprofile (Geheimnisse befinden sich in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal", "openai:default"],
    },
  },

  // Die Identität wird pro Agent festgelegt — legen Sie sie unten unter agents.entries.<id>.identity fest.

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

  // Nachrichtenformatierung
  messages: {
    visibleReplies: "automatic",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // explizite Aktivierung für gemeinsam genutzte Räume mit Modellen, die Tools zuverlässig verwenden
      unmentionedInbound: "room_event",
    },
    queue: {
      mode: "followup",
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
        discord: "collect",
        slack: "collect",
        signal: "followup",
        imessage: "followup",
        webchat: "followup",
      },
    },
  },

  // Sitzungsverhalten
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer", // für Posteingänge mit mehreren Benutzern empfohlen
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/main/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // Dauer oder false
      maxDiskBytes: "500mb", // optional
      highWaterBytes: "400mb", // optional (standardmäßig 80 % von maxDiskBytes)
    },
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Kanäle
  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",
      dmPolicy: "allowlist",
      allowFrom: ["123456789012345678"],
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },

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

  // Agent-Laufzeit
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-6",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.4": { alias: "gpt" },
      },
      skills: ["github", "weather"], // wird von Agenten übernommen, bei denen list[].skills fehlt
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "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-6",
        target: "last",
        directPolicy: "allow", // allow (Standard) | block
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      sandbox: {
        mode: "non-main",
        scope: "session", // gegenüber dem veralteten perSession: true bevorzugt
        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,
        },
      },
    },
    entries: {
      main: {
        default: true,
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
        },
        // übernimmt defaults.skills -> github, weather
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
        thinkingDefault: "high", // agentspezifische Überschreibung der Denktiefe
        reasoningDefault: "on", // agentspezifische Sichtbarkeit der Schlussfolgerungen
        fastModeDefault: false, // agentspezifischer Schnellmodus
      },
      quick: {
        skills: [], // keine Skills für diesen Agenten
        fastModeDefault: true, // dieser Agent wird immer im Schnellmodus ausgeführt
        thinkingDefault: "off",
      },
    },
  },

  memory: {
    search: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "${GEMINI_API_KEY}",
      },
      extraPaths: ["../team-docs", "/srv/shared-notes"],
    },
  },

  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-4o-transcribe", capabilities: ["audio"] },
        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["video"] },
      ],
      audio: { enabled: true, maxBytes: 20971520, timeoutSeconds: 120 },
      video: { enabled: true, maxBytes: 52428800 },
    },
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSeconds: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["123456789012345678"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Benutzerdefinierte Modell-Provider
  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-Aufträge
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "Von: {{messages[0].from}}\nBetreff: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "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 + Netzwerk
  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-host.ts.net:18789", token: "remote-token" },
    reload: { mode: "hybrid" },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

Über einen symbolischen Link eingebundenes benachbartes Skill-Repository

Verwenden Sie dies, wenn das Stammverzeichnis eines integrierten Skills einen symbolischen Link zu einem benachbarten Repository enthält, beispielsweise ~/.agents/skills/manager -> ~/Projects/manager/skills.

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

extraDirs durchsucht das benachbarte Repository als explizites Skills-Stammverzeichnis.
allowSymlinkTargets ermöglicht es verknüpften Skills-Ordnern, in dieses vertrauenswürdige reale Zielstammverzeichnis aufgelöst zu werden, ohne beliebige Ausbrüche über symbolische Links zuzulassen.
Damit Skill Workshop Schreibvorgänge über dasselbe vertrauenswürdige Ziel des symbolischen Links ausführen kann, legen Sie skills.workshop.allowSymlinkTargetWrites: true fest.

Gängige Muster

Gemeinsame Skills-Basis mit einer Überschreibung

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      skills: ["github", "weather"],
    },
    entries: {
      main: { default: true },
      docs: { workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] },
    },
  },
}

agents.defaults.skills ist die gemeinsame Basis.
agents.entries.*.skills ersetzt diese Basis für einen Agenten.
Verwenden Sie skills: [], wenn ein Agent keine Skills sehen soll.

Plattformübergreifende Einrichtung

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"], responsePrefix: "[openclaw]" },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      allowFrom: ["123456789012345678"],
    },
  },
}

Automatische Genehmigung im vertrauenswürdigen Node-Netzwerk

Lassen Sie die Gerätekopplung manuell, sofern Sie den Netzwerkpfad nicht kontrollieren. Für ein dediziertes Labor- oder Tailnet-Subnetz können Sie die automatische Genehmigung von Node-Geräten bei der ersten Kopplung mit exakten CIDRs oder IPs aktivieren:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
    },
  },
}

Wenn diese Option nicht festgelegt ist, bleibt sie deaktiviert. Sie gilt nur für eine erstmalige role: node-Kopplung ohne angeforderte Geltungsbereiche. Operator-/Browser-Clients sowie Aktualisierungen von Rolle, Geltungsbereich, Metadaten oder öffentlichen Schlüsseln erfordern weiterhin eine manuelle Genehmigung.

Sicherer DM-Modus (gemeinsamer Posteingang / Mehrbenutzer-DMs)

Wenn mehr als eine Person Ihrem Bot eine DM senden kann (mehrere Einträge in allowFrom, Kopplungsgenehmigungen für mehrere Personen oder dmPolicy: "open"), aktivieren Sie den sicheren DM-Modus, damit DMs verschiedener Absender nicht standardmäßig denselben Kontext verwenden:

{
  // Sicherer DM-Modus (für Mehrbenutzer- oder sensible DM-Agenten empfohlen)
  session: { dmScope: "per-channel-peer" },

  channels: {
    // Beispiel: WhatsApp-Mehrbenutzer-Posteingang
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Beispiel: Discord-Mehrbenutzer-Posteingang
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      allowFrom: ["123456789012345678", "987654321098765432"],
    },
  },
}

Für Discord/Google Chat/IRC/Mattermost/Microsoft Teams/Slack erfolgt die Absenderautorisierung standardmäßig primär anhand der ID. Aktivieren Sie den direkten Abgleich veränderlicher Namen/E-Mail-Adressen/Spitznamen über dangerouslyAllowNameMatching: true des jeweiligen Kanals nur, wenn Sie dieses Risiko ausdrücklich akzeptieren.

Anthropic-API-Schlüssel + MiniMax-Fallback

{
  auth: {
    profiles: {
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
    },
  },
}

Arbeits-Bot (eingeschränkter Zugriff)

{
  agents: {
    defaults: {
      workspace: "~/work-openclaw",
      elevatedDefault: "off",
    },
    entries: {
      main: {
        identity: {
          name: "WorkBot",
          theme: "professioneller Assistent",
        },
      },
    },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { enabled: true, requireMention: true },
        "#general": { enabled: true, requireMention: true },
      },
    },
  },
}

Nur lokale Modelle

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "lmstudio/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Lokales Modell",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Tipps

Wenn Sie dmPolicy: "open" festlegen, muss die entsprechende allowFrom-Liste "*" enthalten.
Provider-IDs unterscheiden sich (Telefonnummern, Benutzer-IDs, Kanal-IDs). Prüfen Sie das Format in der Dokumentation des Providers.
Optionale Abschnitte, die Sie später hinzufügen können: web, browser, ui, discovery, plugins, talk, signal, imessage.
Ausführlichere Hinweise zur Einrichtung finden Sie unter Provider und Fehlerbehebung.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Konfigurationsbeispiele

Schnellstart

Absolutes Minimum

Empfohlene Startkonfiguration

Erweitertes Beispiel (wichtigste Optionen)

Über einen symbolischen Link eingebundenes benachbartes Skill-Repository

Gängige Muster

Gemeinsame Skills-Basis mit einer Überschreibung

Plattformübergreifende Einrichtung

Automatische Genehmigung im vertrauenswürdigen Node-Netzwerk

Sicherer DM-Modus (gemeinsamer Posteingang / Mehrbenutzer-DMs)

Anthropic-API-Schlüssel + MiniMax-Fallback

Arbeits-Bot (eingeschränkter Zugriff)

Nur lokale Modelle

Tipps

Verwandte Themen

​Schnellstart

​Absolutes Minimum

​Empfohlene Startkonfiguration

​Erweitertes Beispiel (wichtigste Optionen)

​Über einen symbolischen Link eingebundenes benachbartes Skill-Repository

​Gängige Muster

​Gemeinsame Skills-Basis mit einer Überschreibung

​Plattformübergreifende Einrichtung

​Automatische Genehmigung im vertrauenswürdigen Node-Netzwerk

​Sicherer DM-Modus (gemeinsamer Posteingang / Mehrbenutzer-DMs)

​Anthropic-API-Schlüssel + MiniMax-Fallback

​Arbeits-Bot (eingeschränkter Zugriff)

​Nur lokale Modelle

​Tipps

​Verwandte Themen

Schnellstart

Absolutes Minimum

Empfohlene Startkonfiguration

Erweitertes Beispiel (wichtigste Optionen)

Über einen symbolischen Link eingebundenes benachbartes Skill-Repository

Gängige Muster

Gemeinsame Skills-Basis mit einer Überschreibung

Plattformübergreifende Einrichtung

Automatische Genehmigung im vertrauenswürdigen Node-Netzwerk

Sicherer DM-Modus (gemeinsamer Posteingang / Mehrbenutzer-DMs)

Anthropic-API-Schlüssel + MiniMax-Fallback

Arbeits-Bot (eingeschränkter Zugriff)

Nur lokale Modelle

Tipps

Verwandte Themen