​

Dokumentacja konfiguracji

• openclaw config schema wypisuje bieżący schemat JSON używany do walidacji i Control UI, z dołączonymi metadanymi bundled/Plugin/kanałów, gdy są dostępne
• config.schema.lookup zwraca jeden węzeł schematu o zakresie jednej ścieżki dla narzędzi do szczegółowej analizy
• pnpm config:docs:check / pnpm config:docs:gen weryfikują hash bazowy dokumentacji konfiguracji względem bieżącej powierzchni schematu

• Dokumentacja konfiguracji pamięci dla agents.defaults.memorySearch.*, memory.qmd.*, memory.citations oraz konfiguracji Dreaming w plugins.entries.memory-core.config.dreaming
• Slash Commands dla bieżącego katalogu wbudowanych + bundled poleceń
• strony właścicieli kanałów/Pluginów dla powierzchni poleceń specyficznych dla kanału

​

Kanały

​

Dostęp do DM i grup

​

Nadpisania modeli dla kanałów

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Domyślne ustawienia kanałów i Heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: zapasowa zasada grup, gdy groupPolicy na poziomie dostawcy nie jest ustawione.
• channels.defaults.contextVisibility: domyślny tryb widoczności dodatkowego kontekstu dla wszystkich kanałów. Wartości: all (domyślna, uwzględnia cały kontekst cytatu/wątku/historii), allowlist (uwzględnia tylko kontekst od nadawców z listy dozwolonych), allowlist_quote (tak samo jak allowlist, ale zachowuje jawny kontekst cytatu/odpowiedzi). Nadpisanie per kanał: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: uwzględnia zdrowe stany kanałów w wyjściu Heartbeat.
• channels.defaults.heartbeat.showAlerts: uwzględnia stany pogorszone/błędów w wyjściu Heartbeat.
• channels.defaults.heartbeat.useIndicator: renderuje kompaktowe wyjście Heartbeat w stylu wskaźnika.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      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 | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token bota: channels.telegram.botToken lub channels.telegram.tokenFile (tylko zwykły plik; dowiązania symboliczne są odrzucane), z TELEGRAM_BOT_TOKEN jako wartością zapasową dla konta domyślnego.
• Opcjonalne channels.telegram.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• W konfiguracjach z wieloma kontami (2+ identyfikatory kont) ustaw jawne konto domyślne (channels.telegram.defaultAccount lub channels.telegram.accounts.default), aby uniknąć routingu zapasowego; openclaw doctor ostrzega, gdy tego brakuje lub jest nieprawidłowe.
• configWrites: false blokuje zapisy konfiguracji inicjowane z Telegrama (migracje identyfikatorów supergrup, /config set|unset).
• Wpisy najwyższego poziomu bindings[] z type: "acp" konfigurują trwałe powiązania ACP dla tematów forum (użyj kanonicznego chatId:topic:topicId w match.peer.id). Semantyka pól jest współdzielona z ACP Agents.
• Podglądy strumieniowe Telegram używają sendMessage + editMessageText (działa w czatach bezpośrednich i grupowych).
• Zasady ponawiania: zobacz Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      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", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          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", // length | newline
      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, z DISCORD_BOT_TOKEN jako wartością zapasową dla konta domyślnego.
• Bezpośrednie wywołania wychodzące, które przekazują jawny token Discorda, używają tego tokena do wywołania; ustawienia ponawiania/zasad konta nadal pochodzą z wybranego konta w aktywnej migawce środowiska uruchomieniowego.
• Opcjonalne channels.discord.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• Używaj user:<id> (DM) lub channel:<id> (kanał serwera) jako celów dostarczenia; same numeryczne identyfikatory są odrzucane.
• Slugi serwerów są pisane małymi literami, a spacje są zastępowane przez -; klucze kanałów używają nazwy w postaci slugu (bez #). Preferuj identyfikatory serwerów.
• Wiadomości napisane przez bota są domyślnie ignorowane. allowBots: true je włącza; użyj allowBots: "mentions", aby akceptować tylko wiadomości botów, które wspominają bota (własne wiadomości nadal są filtrowane).
• channels.discord.guilds.<id>.ignoreOtherMentions (oraz nadpisania na poziomie kanału) odrzuca wiadomości, które wspominają innego użytkownika lub rolę, ale nie bota (z wyłączeniem @everyone/@here).
• maxLinesPerMessage (domyślnie 17) dzieli wysokie wiadomości nawet wtedy, gdy mają mniej niż 2000 znaków.
• channels.discord.threadBindings steruje routowaniem związanym z wątkami Discorda:
  • enabled: nadpisanie Discorda dla funkcji sesji związanych z wątkami (/focus, /unfocus, /agents, /session idle, /session max-age oraz dostarczanie/routowanie związane z powiązaniem)
  • idleHours: nadpisanie Discorda dla automatycznego zdejmowania fokusu po bezczynności w godzinach (0 wyłącza)
  • maxAgeHours: nadpisanie Discorda dla twardego maksymalnego wieku w godzinach (0 wyłącza)
  • spawnSubagentSessions: przełącznik opt-in dla automatycznego tworzenia/powiązania wątków przez sessions_spawn({ thread: true })
• Wpisy najwyższego poziomu bindings[] z type: "acp" konfigurują trwałe powiązania ACP dla kanałów i wątków (użyj identyfikatora kanału/wątku w match.peer.id). Semantyka pól jest współdzielona z ACP Agents.
• channels.discord.ui.components.accentColor ustawia kolor akcentu dla kontenerów komponentów Discord v2.
• channels.discord.voice włącza rozmowy w kanałach głosowych Discorda oraz opcjonalne automatyczne dołączanie i nadpisania TTS.
• channels.discord.voice.daveEncryption oraz channels.discord.voice.decryptionFailureTolerance są przekazywane do opcji DAVE @discordjs/voice (true i 24 domyślnie).
• OpenClaw dodatkowo próbuje odzyskać odbiór głosu przez opuszczenie i ponowne dołączenie do sesji głosowej po powtarzających się błędach odszyfrowywania.
• channels.discord.streaming jest kanonicznym kluczem trybu strumieniowania. Starsze wartości streamMode i logiczne streaming są automatycznie migrowane.
• channels.discord.autoPresence mapuje dostępność środowiska uruchomieniowego na status obecności bota (healthy => online, degraded => idle, exhausted => dnd) i pozwala na opcjonalne nadpisania tekstu statusu.
• channels.discord.dangerouslyAllowNameMatching ponownie włącza dopasowywanie po zmiennej nazwie/tagu (awaryjny tryb zgodności).
• channels.discord.execApprovals: natywne dla Discorda dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających.
  • enabled: true, false lub "auto" (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozwiązać z approvers lub commands.ownerAllowFrom.
  • approvers: identyfikatory użytkowników Discorda, którym wolno zatwierdzać żądania exec. Gdy pominięte, używa wartości zapasowej z commands.ownerAllowFrom.
  • agentFilter: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
  • sessionFilter: opcjonalne wzorce kluczy sesji (podciąg lub regex).
  • target: gdzie wysyłać prośby o zatwierdzenie. "dm" (domyślnie) wysyła do DM zatwierdzających, "channel" wysyła do kanału źródłowego, "both" wysyła do obu. Gdy target zawiera "channel", przycisków mogą używać tylko rozwiązani zatwierdzający.
  • cleanupAfterResolve: gdy true, usuwa DM z zatwierdzeniem po zatwierdzeniu, odrzuceniu lub przekroczeniu limitu czasu.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      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,
    },
  },
}

• JSON konta usługi: osadzony (serviceAccount) lub oparty na pliku (serviceAccountFile).
• SecretRef konta usługi jest również obsługiwany (serviceAccountRef).
• Wartości zapasowe ze środowiska: GOOGLE_CHAT_SERVICE_ACCOUNT lub GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Używaj spaces/<spaceId> lub users/<userId> jako celów dostarczenia.
• channels.googlechat.dangerouslyAllowNameMatching ponownie włącza dopasowywanie po zmiennym adresie e-mail principal (awaryjny tryb zgodności).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, 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", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Tryb socket wymaga zarówno botToken, jak i appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN jako zapasowe wartości środowiskowe dla konta domyślnego).
• Tryb HTTP wymaga botToken oraz signingSecret (w korzeniu lub per konto).
• botToken, appToken, signingSecret i userToken akceptują jawne ciągi znaków lub obiekty SecretRef.
• Migawki kont Slacka udostępniają pola źródła/statusu per poświadczenie, takie jak botTokenSource, botTokenStatus, appTokenStatus oraz, w trybie HTTP, signingSecretStatus. configured_unavailable oznacza, że konto jest skonfigurowane przez SecretRef, ale bieżąca ścieżka polecenia/środowiska uruchomieniowego nie mogła rozwiązać wartości sekretu.
• configWrites: false blokuje zapisy konfiguracji inicjowane ze Slacka.
• Opcjonalne channels.slack.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• channels.slack.streaming.mode jest kanonicznym kluczem trybu strumieniowania Slacka. channels.slack.streaming.nativeTransport kontroluje natywny transport strumieniowania Slacka. Starsze wartości streamMode, logiczne streaming i nativeStreaming są automatycznie migrowane.
• Używaj user:<id> (DM) lub channel:<id> jako celów dostarczenia.

• Natywne strumieniowanie Slacka oraz status w stylu asystenta Slacka „is typing…” w wątku wymagają celu odpowiedzi będącego wątkiem. DM najwyższego poziomu domyślnie pozostają poza wątkiem, więc używają typingReaction lub zwykłego dostarczania zamiast podglądu w stylu wątku.
• typingReaction dodaje tymczasową reakcję do przychodzącej wiadomości Slacka, gdy odpowiedź jest w trakcie generowania, a następnie usuwa ją po zakończeniu. Użyj skrótu emoji Slacka, takiego jak "hourglass_flowing_sand".
• channels.slack.execApprovals: natywne dla Slacka dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających. Ten sam schemat co w Discordzie: enabled (true/false/"auto"), approvers (identyfikatory użytkowników Slacka), agentFilter, sessionFilter i target ("dm", "channel" lub "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath musi być ścieżką (na przykład /api/channels/mattermost/command), a nie pełnym URL-em.
• commands.callbackUrl musi wskazywać na punkt końcowy Gateway OpenClaw i być osiągalny z serwera Mattermost.
• Natywne wywołania zwrotne slash są uwierzytelniane tokenami per polecenie zwracanymi przez Mattermost podczas rejestracji poleceń slash. Jeśli rejestracja się nie powiedzie lub żadne polecenia nie zostaną aktywowane, OpenClaw odrzuci wywołania zwrotne z komunikatem Unauthorized: invalid command token.
• Dla prywatnych/tailnet/wewnętrznych hostów callbacków Mattermost może wymagać, aby ServiceSettings.AllowedUntrustedInternalConnections zawierało host/domenę callbacku. Używaj wartości hosta/domeny, a nie pełnych URL-i.
• channels.mattermost.configWrites: zezwala lub zabrania zapisów konfiguracji inicjowanych z Mattermost.
• channels.mattermost.requireMention: wymaga @mention przed odpowiedzią w kanałach.
• channels.mattermost.groups.<channelId>.requireMention: nadpisanie wymagania wzmianki per kanał ("*" dla wartości domyślnej).
• Opcjonalne channels.mattermost.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: przypina uruchamianie kanału do określonej tożsamości konta Signal.
• channels.signal.configWrites: zezwala lub zabrania zapisów konfiguracji inicjowanych z Signal.
• Opcjonalne channels.signal.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Główne ścieżki kluczy omawiane tutaj: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Opcjonalne channels.bluebubbles.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• Wpisy najwyższego poziomu bindings[] z type: "acp" mogą wiązać rozmowy BlueBubbles z trwałymi sesjami ACP. Użyj uchwytu BlueBubbles lub ciągu docelowego (chat_id:*, chat_guid:*, chat_identifier:*) w match.peer.id. Współdzielona semantyka pól: ACP Agents.
• Pełna konfiguracja kanału BlueBubbles jest opisana w BlueBubbles.

​

iMessage

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

• Opcjonalne channels.imessage.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• Wymaga Full Disk Access do bazy danych Messages.
• Preferuj cele chat_id:<id>. Użyj imsg chats --limit 20, aby wyświetlić listę czatów.
• cliPath może wskazywać na wrapper SSH; ustaw remoteHost (host lub user@host) dla pobierania załączników przez SCP.
• attachmentRoots i remoteAttachmentRoots ograniczają ścieżki przychodzących załączników (domyślnie: /Users/*/Library/Messages/Attachments).
• SCP używa ścisłego sprawdzania klucza hosta, więc upewnij się, że klucz hosta przekaźnika już istnieje w ~/.ssh/known_hosts.
• channels.imessage.configWrites: zezwala lub zabrania zapisów konfiguracji inicjowanych z iMessage.
• Wpisy najwyższego poziomu bindings[] z type: "acp" mogą wiązać rozmowy iMessage z trwałymi sesjami ACP. Użyj znormalizowanego uchwytu lub jawnego celu czatu (chat_id:*, chat_guid:*, chat_identifier:*) w match.peer.id. Współdzielona semantyka pól: ACP Agents.

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

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Uwierzytelnianie tokenem używa accessToken; uwierzytelnianie hasłem używa userId + password.
• channels.matrix.proxy kieruje ruch HTTP Matrix przez jawny serwer proxy HTTP(S). Nazwane konta mogą to nadpisać przez channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork zezwala na prywatne/wewnętrzne homeservery. proxy i to sieciowe opt-in są niezależnymi mechanizmami kontroli.
• channels.matrix.defaultAccount wybiera preferowane konto w konfiguracjach z wieloma kontami.
• channels.matrix.autoJoin domyślnie ma wartość off, więc zaproszone pokoje i nowe zaproszenia w stylu DM są ignorowane, dopóki nie ustawisz autoJoin: "allowlist" z autoJoinAllowlist albo autoJoin: "always".
• channels.matrix.execApprovals: natywne dla Matrix dostarczanie zatwierdzeń exec i autoryzacja zatwierdzających.
  • enabled: true, false lub "auto" (domyślnie). W trybie auto zatwierdzenia exec aktywują się, gdy zatwierdzających można rozwiązać z approvers lub commands.ownerAllowFrom.
  • approvers: identyfikatory użytkowników Matrix (np. @owner:example.org) uprawnione do zatwierdzania żądań exec.
  • agentFilter: opcjonalna lista dozwolonych identyfikatorów agentów. Pomiń, aby przekazywać zatwierdzenia dla wszystkich agentów.
  • sessionFilter: opcjonalne wzorce kluczy sesji (podciąg lub regex).
  • target: gdzie wysyłać prośby o zatwierdzenie. "dm" (domyślnie), "channel" (pokój źródłowy) lub "both".
  • Nadpisania per konto: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope kontroluje, jak DM Matrix są grupowane w sesje: per-user (domyślnie) współdzieli według kierowanego peera, a per-room izoluje każdy pokój DM.
• Sondy statusu Matrix i wyszukiwania w katalogu na żywo używają tej samej polityki proxy co ruch środowiska uruchomieniowego.
• Pełna konfiguracja Matrix, reguły targetowania i przykłady konfiguracji są opisane w Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Główne ścieżki kluczy omawiane tutaj: channels.msteams, channels.msteams.configWrites.
• Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest opisana w Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Główne ścieżki kluczy omawiane tutaj: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• Opcjonalne channels.irc.defaultAccount nadpisuje wybór konta domyślnego, jeśli pasuje do skonfigurowanego identyfikatora konta.
• Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/wymaganie wzmianki) jest opisana w IRC.

​

Wiele kont (wszystkie kanały)

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

• default jest używane, gdy accountId jest pominięte (CLI + routing).
• Tokeny środowiskowe mają zastosowanie tylko do konta default.
• Bazowe ustawienia kanału mają zastosowanie do wszystkich kont, chyba że zostaną nadpisane per konto.
• Użyj bindings[].match.accountId, aby kierować każde konto do innego agenta.
• Jeśli dodasz konto inne niż domyślne przez openclaw channels add (lub onboarding kanału), gdy nadal używasz jednokontowej konfiguracji najwyższego poziomu dla kanału, OpenClaw najpierw promuje jednokontowe wartości najwyższego poziomu o zakresie konta do mapy kont kanału, aby oryginalne konto nadal działało. Większość kanałów przenosi je do channels.<channel>.accounts.default; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel.
• Istniejące powiązania tylko-kanałowe (bez accountId) nadal dopasowują się do konta domyślnego; powiązania o zakresie konta pozostają opcjonalne.
• openclaw doctor --fix również naprawia mieszane kształty, przenosząc jednokontowe wartości najwyższego poziomu o zakresie konta do promowanego konta wybranego dla tego kanału. Większość kanałów używa accounts.default; Matrix może zamiast tego zachować istniejący pasujący nazwany/domyslny cel.

​

Inne kanały rozszerzeń

​

Wymaganie wzmianki w czatach grupowych

• Wzmianki z metadanych: natywne wzmianki @ platformy. Ignorowane w trybie self-chat WhatsApp.
• Wzorce tekstowe: bezpieczne wzorce regex w agents.list[].groupChat.mentionPatterns. Nieprawidłowe wzorce i niebezpieczne zagnieżdżone powtórzenia są ignorowane.
• Wymaganie wzmianki jest egzekwowane tylko wtedy, gdy wykrycie jest możliwe (natywne wzmianki lub co najmniej jeden wzorzec).

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

​

Limity historii DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Tryb self-chat

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Polecenia (obsługa poleceń czatu)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Domyślne ustawienia agenta

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

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

• Pomiń agents.defaults.skills, aby domyślnie nie ograniczać Skills.
• Pomiń agents.list[].skills, aby dziedziczyć wartości domyślne.
• Ustaw agents.list[].skills: [], aby nie mieć żadnych Skills.
• Niepusta lista agents.list[].skills jest końcowym zestawem dla tego agenta; nie łączy się z wartościami domyślnymi.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": bezpieczne tury kontynuacji (po zakończonej odpowiedzi asystenta) pomijają ponowne wstrzyknięcie bootstrap workspace, zmniejszając rozmiar prompt. Uruchomienia Heartbeat i ponowne próby po Compaction nadal przebudowują kontekst.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": nigdy nie wstrzykuje tekstu ostrzeżenia do system prompt.
• "once": wstrzykuje ostrzeżenie raz dla każdego unikalnego podpisu obcięcia (zalecane).
• "always": wstrzykuje ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

Mapa właścicieli budżetu kontekstu

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: zwykłe wstrzykiwanie bootstrap workspace.
• agents.defaults.startupContext.*: jednorazowe preludium startowe /new i /reset, w tym ostatnie dzienne pliki memory/*.md.
• skills.limits.*: kompaktowa lista Skills wstrzykiwana do system prompt.
• agents.defaults.contextLimits.*: ograniczone wycinki środowiska uruchomieniowego i wstrzykiwane bloki należące do runtime.
• memory.qmd.limits.*: rozmiar fragmentów wyszukiwania zaindeksowanej pamięci i wstrzyknięć.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: domyślny limit wycinka memory_get przed dodaniem metadanych obcięcia i informacji o kontynuacji.
• memoryGetDefaultLines: domyślne okno wierszy memory_get, gdy lines jest pominięte.
• toolResultMaxChars: limit wyników narzędzi na żywo używany dla utrwalonych wyników i odzyskiwania po przepełnieniu.
• postCompactionMaxChars: limit wycinka AGENTS.md używany podczas wstrzykiwania odświeżenia po Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Forma ciągu ustawia tylko model podstawowy.
  • Forma obiektu ustawia model podstawowy oraz uporządkowane modele przełączania awaryjnego.
• imageModel: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez ścieżkę narzędzia image jako konfiguracja modelu vision.
  • Używany także jako routing zapasowy, gdy wybrany/domyslny model nie może przyjąć wejścia obrazu.
• imageGenerationModel: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną funkcję generowania obrazów i każdą przyszłą powierzchnię narzędzia/Pluginu generującą obrazy.
  • Typowe wartości: google/gemini-3.1-flash-image-preview dla natywnego generowania obrazów Gemini, fal/fal-ai/flux/dev dla fal lub openai/gpt-image-1 dla OpenAI Images.
  • Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj również pasujące uwierzytelnianie/klucz API dostawcy (na przykład GEMINI_API_KEY lub GOOGLE_API_KEY dla google/*, OPENAI_API_KEY dla openai/*, FAL_KEY dla fal/*).
  • Jeśli pominięte, image_generate nadal może wywnioskować domyślną wartość dostawcy opartą na uwierzytelnieniu. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania obrazów w kolejności identyfikatorów dostawców.
• musicGenerationModel: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną funkcję generowania muzyki i wbudowane narzędzie music_generate.
  • Typowe wartości: google/lyria-3-clip-preview, google/lyria-3-pro-preview lub minimax/music-2.5+.
  • Jeśli pominięte, music_generate nadal może wywnioskować domyślną wartość dostawcy opartą na uwierzytelnieniu. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania muzyki w kolejności identyfikatorów dostawców.
  • Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj również pasujące uwierzytelnianie/klucz API dostawcy.
• videoGenerationModel: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną funkcję generowania wideo i wbudowane narzędzie video_generate.
  • Typowe wartości: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash lub qwen/wan2.7-r2v.
  • Jeśli pominięte, video_generate nadal może wywnioskować domyślną wartość dostawcy opartą na uwierzytelnieniu. Najpierw próbuje bieżącego domyślnego dostawcy, a potem pozostałych zarejestrowanych dostawców generowania wideo w kolejności identyfikatorów dostawców.
  • Jeśli wybierzesz bezpośrednio provider/model, skonfiguruj również pasujące uwierzytelnianie/klucz API dostawcy.
  • Bundled dostawca generowania wideo Qwen obsługuje maksymalnie 1 wyjściowe wideo, 1 wejściowy obraz, 4 wejściowe filmy, czas trwania do 10 sekund oraz opcje na poziomie dostawcy size, aspectRatio, resolution, audio i watermark.
• pdfModel: akceptuje albo ciąg znaków ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez narzędzie pdf do routingu modelu.
  • Jeśli pominięty, narzędzie PDF przechodzi awaryjnie do imageModel, a następnie do rozwiązanego modelu sesji/domyslnego.
• pdfMaxBytesMb: domyślny limit rozmiaru PDF dla narzędzia pdf, gdy maxBytesMb nie jest przekazane w czasie wywołania.
• pdfMaxPages: domyślna maksymalna liczba stron uwzględnianych przez tryb awaryjnej ekstrakcji w narzędziu pdf.
• verboseDefault: domyślny poziom verbose dla agentów. Wartości: "off", "on", "full". Domyślnie: "off".
• elevatedDefault: domyślny poziom wyjścia elevated dla agentów. Wartości: "off", "on", "ask", "full". Domyślnie: "on".
• model.primary: format provider/model (np. openai/gpt-5.4). Jeśli pominiesz dostawcę, OpenClaw najpierw próbuje aliasu, potem unikalnego dopasowania dokładnego identyfikatora modelu w skonfigurowanych dostawcach, a dopiero potem wraca do skonfigurowanego domyślnego dostawcy (przestarzałe zachowanie zgodności, więc preferuj jawne provider/model). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw przechodzi awaryjnie do pierwszego skonfigurowanego dostawcy/modelu zamiast ujawniać przestarzałą wartość domyślną usuniętego dostawcy.
• models: skonfigurowany katalog modeli i lista dozwolonych dla /model. Każdy wpis może zawierać alias (skrót) i params (specyficzne dla dostawcy, na przykład temperature, maxTokens, cacheRetention, context1m).
• params: globalne domyślne parametry dostawcy stosowane do wszystkich modeli. Ustawiane w agents.defaults.params (np. { cacheRetention: "long" }).
• Priorytet scalania params (konfiguracja): agents.defaults.params (globalna baza) jest nadpisywane przez agents.defaults.models["provider/model"].params (per model), a następnie agents.list[].params (pasujący identyfikator agenta) nadpisuje po kluczu. Szczegóły znajdziesz w Prompt Caching.
• embeddedHarness: domyślna polityka niskopoziomowego runtime wbudowanego agenta. Użyj runtime: "auto", aby pozwolić zarejestrowanym harnessom Pluginów przejmować obsługiwane modele, runtime: "pi", aby wymusić wbudowany harness PI, albo zarejestrowanego identyfikatora harnessu, np. runtime: "codex". Ustaw fallback: "none", aby wyłączyć automatyczny zapasowy fallback PI.
• Pisarze konfiguracji, którzy mutują te pola (na przykład /models set, /models set-image oraz polecenia dodawania/usuwania fallbacków), zapisują kanoniczną formę obiektu i w miarę możliwości zachowują istniejące listy fallbacków.
• maxConcurrent: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" lub identyfikator zarejestrowanego harnessu Pluginu. Bundled Plugin Codex rejestruje codex.
• fallback: "pi" lub "none". "pi" zachowuje wbudowany harness PI jako fallback zgodności. "none" powoduje, że brakujący lub nieobsługiwany wybór harnessu Pluginu kończy się błędem zamiast cichego użycia PI.
• Nadpisania środowiskowe: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> nadpisuje runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none wyłącza fallback PI dla tego procesu.
• Dla wdrożeń tylko z Codex ustaw model: "codex/gpt-5.4", embeddedHarness.runtime: "codex" i embeddedHarness.fallback: "none".
• To kontroluje tylko wbudowany harness czatu. Generowanie mediów, vision, PDF, muzyka, wideo i TTS nadal używają swoich ustawień dostawcy/modelu.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Backendy CLI są przede wszystkim tekstowe; narzędzia są zawsze wyłączone.
• Sesje są obsługiwane, gdy ustawione jest sessionArg.
• Przekazywanie obrazów jest obsługiwane, gdy imageArg akceptuje ścieżki plików.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: ciąg czasu trwania (ms/s/m/h). Domyślnie: 30m (uwierzytelnianie kluczem API) lub 1h (uwierzytelnianie OAuth). Ustaw 0m, aby wyłączyć.
• includeSystemPromptSection: gdy ma wartość false, pomija sekcję Heartbeat w system prompt i pomija wstrzykiwanie HEARTBEAT.md do kontekstu bootstrap. Domyślnie: true.
• suppressToolErrorWarnings: gdy ma wartość true, ukrywa ładunki ostrzeżeń o błędach narzędzi podczas uruchomień Heartbeat.
• timeoutSeconds: maksymalny czas w sekundach dozwolony dla tury agenta Heartbeat przed jej przerwaniem. Pozostaw nieustawione, aby użyć agents.defaults.timeoutSeconds.
• directPolicy: zasada dostarczania bezpośredniego/DM. allow (domyślnie) zezwala na dostarczanie do celu bezpośredniego. block blokuje dostarczanie do celu bezpośredniego i emituje reason=dm-blocked.
• lightContext: gdy ma wartość true, uruchomienia Heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko HEARTBEAT.md z plików bootstrap workspace.
• isolatedSession: gdy ma wartość true, każde uruchomienie Heartbeat odbywa się w świeżej sesji bez wcześniejszej historii rozmowy. Ten sam wzorzec izolacji co Cron sessionTarget: "isolated". Zmniejsza koszt tokenów na Heartbeat z około 100K do około 2-5K tokenów.
• Per agent: ustaw agents.list[].heartbeat. Gdy dowolny agent definiuje heartbeat, Heartbeat uruchamiają tylko te agenty.
• Heartbeat uruchamia pełne tury agenta — krótsze interwały zużywają więcej tokenów.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        notifyUser: true, // send a brief notice when compaction starts (default: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default lub safeguard (podsumowywanie porcjami dla długiej historii). Zobacz Compaction.
• provider: identyfikator zarejestrowanego Pluginu dostawcy Compaction. Gdy ustawione, wywoływane jest summarize() dostawcy zamiast wbudowanego podsumowywania LLM. W razie błędu wraca do wbudowanego trybu. Ustawienie dostawcy wymusza mode: "safeguard". Zobacz Compaction.
• timeoutSeconds: maksymalna liczba sekund dozwolona dla pojedynczej operacji Compaction, po której OpenClaw ją przerywa. Domyślnie: 900.
• identifierPolicy: strict (domyślnie), off lub custom. strict dodaje na początku wbudowane wskazówki dotyczące zachowywania nieprzezroczystych identyfikatorów podczas podsumowywania Compaction.
• identifierInstructions: opcjonalny własny tekst zachowania identyfikatorów używany, gdy identifierPolicy=custom.
• postCompactionSections: opcjonalne nazwy sekcji H2/H3 z AGENTS.md do ponownego wstrzyknięcia po Compaction. Domyślnie ["Session Startup", "Red Lines"]; ustaw [], aby wyłączyć ponowne wstrzyknięcie. Gdy nieustawione lub jawnie ustawione na tę domyślną parę, starsze nagłówki Every Session/Safety są również akceptowane jako zgodność wsteczna.
• model: opcjonalne nadpisanie provider/model-id tylko dla podsumowywania Compaction. Użyj tego, gdy główna sesja ma pozostać przy jednym modelu, ale podsumowania Compaction mają działać na innym; gdy nieustawione, Compaction używa modelu podstawowego sesji.
• notifyUser: gdy true, wysyła krótkie powiadomienie do użytkownika, gdy rozpoczyna się Compaction (na przykład „Trwa kompaktowanie kontekstu…” ). Domyślnie wyłączone, aby Compaction pozostawał cichy.
• memoryFlush: cicha agentowa tura przed automatycznym Compaction, aby zapisać trwałe wspomnienia. Pomijane, gdy workspace jest tylko do odczytu.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Strumieniowanie blokowe

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Kanały inne niż Telegram wymagają jawnego *.blockStreaming: true, aby włączyć odpowiedzi blokowe.
• Nadpisania kanału: channels.<channel>.blockStreamingCoalesce (oraz warianty per konto). Signal/Slack/Discord/Google Chat domyślnie używają minChars: 1500.
• humanDelay: losowa pauza między odpowiedziami blokowymi. natural = 800–2500 ms. Nadpisanie per agent: agents.list[].humanDelay.

​

Wskaźniki pisania

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Wartości domyślne: instant dla czatów bezpośrednich/wzmianek, message dla niewzmiankowanych czatów grupowych.
• Nadpisania per sesja: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

​

agents.list (nadpisania per agent)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: stabilny identyfikator agenta (wymagany).
• default: gdy ustawionych jest wiele, wygrywa pierwszy (zapisywane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy.
• model: forma ciągu nadpisuje tylko primary; forma obiektu { primary, fallbacks } nadpisuje oba ([] wyłącza globalne fallbacki). Zadania Cron, które nadpisują tylko primary, nadal dziedziczą domyślne fallbacki, chyba że ustawisz fallbacks: [].
• params: parametry strumienia per agent scalane ponad wybranym wpisem modelu w agents.defaults.models. Użyj tego do nadpisań specyficznych dla agenta, takich jak cacheRetention, temperature lub maxTokens, bez duplikowania całego katalogu modeli.
• skills: opcjonalna lista dozwolonych Skills per agent. Jeśli pominięta, agent dziedziczy agents.defaults.skills, gdy jest ustawione; jawna lista zastępuje wartości domyślne zamiast je scalać, a [] oznacza brak Skills.
• thinkingDefault: opcjonalny domyślny poziom thinking per agent (off | minimal | low | medium | high | xhigh | adaptive). Nadpisuje agents.defaults.thinkingDefault dla tego agenta, gdy nie jest ustawione nadpisanie per wiadomość ani per sesję.
• reasoningDefault: opcjonalna domyślna widoczność reasoning per agent (on | off | stream). Stosowane, gdy nie ma nadpisania reasoning per wiadomość ani per sesję.
• fastModeDefault: opcjonalna wartość domyślna per agent dla fast mode (true | false). Stosowane, gdy nie ma nadpisania fast mode per wiadomość ani per sesję.
• embeddedHarness: opcjonalne nadpisanie polityki niskopoziomowego harnessu per agent. Użyj { runtime: "codex", fallback: "none" }, aby jeden agent był tylko Codex, a pozostałe zachowały domyślny fallback PI.
• runtime: opcjonalny deskryptor runtime per agent. Użyj type: "acp" z domyślnymi ustawieniami runtime.acp (agent, backend, mode, cwd), gdy agent ma domyślnie używać sesji harnessu ACP.
• identity.avatar: ścieżka względna do workspace, URL http(s) lub URI data:.
• identity wyprowadza wartości domyślne: ackReaction z emoji, mentionPatterns z name/emoji.
• subagents.allowAgents: lista dozwolonych identyfikatorów agentów dla sessions_spawn (["*"] = dowolny; domyślnie: tylko ten sam agent).
• Zabezpieczenie dziedziczenia sandboxa: jeśli sesja żądająca jest sandboxowana, sessions_spawn odrzuca cele, które działałyby bez sandboxa.
• subagents.requireAgentId: gdy true, blokuje wywołania sessions_spawn, które pomijają agentId (wymusza jawny wybór profilu; domyślnie: false).

​

Routing wielu agentów

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

​

Pola dopasowania binding

• type (opcjonalne): route dla zwykłego routingu (brak typu domyślnie oznacza route), acp dla trwałych powiązań rozmów ACP.
• match.channel (wymagane)
• match.accountId (opcjonalne; * = dowolne konto; pominięte = konto domyślne)
• match.peer (opcjonalne; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcjonalne; zależne od kanału)
• acp (opcjonalne; tylko dla type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (dokładne, bez peer/guild/team)
5. match.accountId: "*" (na cały kanał)
6. Agent domyślny

​

Profile dostępu per agent

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

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

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

​

Sesja

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}