​

Referencja konfiguracji

​

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 grupowa, gdy groupPolicy na poziomie dostawcy nie jest ustawione.
• channels.defaults.contextVisibility: domyślny tryb widoczności kontekstu uzupełniającego dla wszystkich kanałów. Wartości: all (domyślnie, uwzględnia cały kontekst cytatów/wątków/historii), allowlist (uwzględnia tylko kontekst od nadawców z listy dozwolonych), allowlist_quote (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 obniżonej sprawności/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, // niebieskie haczyki (false w trybie self-chat)
      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: "Odpowiedzi powinny być krótkie.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Trzymaj się tematu.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Kopia zapasowa Git" },
        { command: "generate", description: "Utwórz obraz" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (domyślnie: off; włącz jawnie, aby uniknąć limitów szybkości podglądu-edycji)
      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; symlinki są odrzucane), z TELEGRAM_BOT_TOKEN jako wartością zapasową dla konta domyślnego.
• Opcjonalne channels.telegram.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
• W konfiguracjach wielokontowych (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 przez Telegram (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 w ACP Agents.
• Podglądy strumieni Telegram używają sendMessage + editMessageText (działa w czatach bezpośrednich i grupowych).
• Zasada ponawiania: zobacz Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      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: "Tylko krótkie odpowiedzi.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress mapuje się do partial w Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in dla 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 podają jawny token Discord, używają tego tokena dla wywołania; ustawienia ponawiania/zasad konta nadal pochodzą z wybranego konta w aktywnym snapshotcie środowiska uruchomieniowego.
• Opcjonalne channels.discord.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
• Używaj user:<id> (DM) lub channel:<id> (kanał guild) jako celów dostarczenia; same numeryczne identyfikatory są odrzucane.
• Slugi guild są pisane małymi literami, a spacje zastępowane przez -; klucze kanałów używają nazwy w postaci slug (bez #). Preferuj identyfikatory guild.
• Wiadomości autorstwa botów 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 kanałów) 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 kontroluje routing powiązany z wątkami Discord:
  • enabled: nadpisanie Discord dla funkcji sesji powiązanych z wątkiem (/focus, /unfocus, /agents, /session idle, /session max-age oraz dostarczenie/routing powiązany)
  • idleHours: nadpisanie Discord dla automatycznego odfokusowania po bezczynności w godzinach (0 wyłącza)
  • maxAgeHours: nadpisanie Discord dla sztywnego maksymalnego wieku w godzinach (0 wyłącza)
  • spawnSubagentSessions: przełącznik opt-in dla automatycznego tworzenia/powiązywania 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 w ACP Agents.
• channels.discord.ui.components.accentColor ustawia kolor akcentu dla kontenerów Discord components v2.
• channels.discord.voice włącza rozmowy w kanałach głosowych Discord oraz opcjonalne automatyczne dołączanie i nadpisania TTS.
• channels.discord.voice.daveEncryption i channels.discord.voice.decryptionFailureTolerance są przekazywane do opcji DAVE w @discordjs/voice (domyślnie true i 24).
• 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 deszyfrowania.
• channels.discord.streaming to kanoniczny klucz trybu strumieniowania. Starsze wartości streamMode oraz logiczne streaming są automatycznie migrowane.
• channels.discord.autoPresence mapuje dostępność środowiska uruchomieniowego na obecność 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 (tryb zgodności break-glass).
• channels.discord.execApprovals: natywne dostarczanie zatwierdzeń exec przez Discord 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 Discord, którzy mogą zatwierdzać żądania exec. Gdy pominięte, następuje powrót do 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ć prompty zatwierdzeń. "dm" (domyślnie) wysyła do DM zatwierdzających, "channel" wysyła do kanału źródłowego, "both" wysyła do obu. Gdy cel obejmuje "channel", przycisków mogą używać tylko rozwiązani zatwierdzający.
  • cleanupAfterResolve: gdy true, usuwa DM-y zatwierdzeń po zatwierdzeniu, odrzuceniu lub upływie 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: inline (serviceAccount) lub z pliku (serviceAccountFile).
• SecretRef konta usługi jest również obsługiwany (serviceAccountRef).
• Zapasowe wartości z env: 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 principal email (tryb zgodności break-glass).

​

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: "Tylko krótkie odpowiedzi.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      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: "partial", // off | partial | block | progress (tryb podglądu)
      nativeStreaming: true, // użyj natywnego API strumieniowania Slack, gdy streaming=partial
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode wymaga zarówno botToken, jak i appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN jako zapasowe wartości env dla konta domyślnego).
• HTTP mode wymaga botToken plus signingSecret (na poziomie głównym lub per konto).
• botToken, appToken, signingSecret i userToken akceptują jawne stringi lub obiekty SecretRef.
• Snapshoty kont Slack udostępniają pola źródła/statusu poświadczeń, takie jak botTokenSource, botTokenStatus, appTokenStatus, a w trybie HTTP także 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 przez Slack.
• Opcjonalne channels.slack.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
• channels.slack.streaming to kanoniczny klucz trybu strumieniowania. Starsze wartości streamMode oraz logiczne streaming są automatycznie migrowane.
• Używaj user:<id> (DM) lub channel:<id> jako celów dostarczenia.

• typingReaction dodaje tymczasową reakcję do przychodzącej wiadomości Slack podczas generowania odpowiedzi, a po zakończeniu ją usuwa. Użyj skrótu emoji Slack, takiego jak "hourglass_flowing_sand".
• channels.slack.execApprovals: natywne dostarczanie zatwierdzeń exec przez Slack i autoryzacja zatwierdzających. Ten sam schemat co Discord: enabled (true/false/"auto"), approvers (identyfikatory użytkowników Slack), 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",
        // Opcjonalny jawny URL dla wdrożeń z reverse proxy/publicznych
        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ć endpoint gateway OpenClaw i być osiągalny z serwera Mattermost.
• Natywne callbacki slash są uwierzytelniane tokenami per polecenie zwróconymi przez Mattermost podczas rejestracji poleceń slash. Jeśli rejestracja się nie powiedzie lub nie aktywowano żadnych poleceń, OpenClaw odrzuca callbacki z Unauthorized: invalid command token.
• W przypadku prywatnych/tailnet/internal hostów callbacków Mattermost może wymagać, aby ServiceSettings.AllowedUntrustedInternalConnections zawierało host/domenę callbacku. Używaj wartości host/domena, a nie pełnych URL-i.
• channels.mattermost.configWrites: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych przez Mattermost.
• channels.mattermost.requireMention: wymagaj @mention przed odpowiedzią w kanałach.
• channels.mattermost.groups.<channelId>.requireMention: nadpisanie gatingu wzmiankami per kanał ("*" dla domyślnego).
• Opcjonalne channels.mattermost.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // opcjonalne powiązanie konta
      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 konkretnej tożsamości konta Signal.
• channels.signal.configWrites: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych przez Signal.
• Opcjonalne channels.signal.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, kontrola grup i zaawansowane akcje:
      // zobacz /channels/bluebubbles
    },
  },
}

• Kluczowe ścieżki rdzeniowe omówione tutaj: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Opcjonalne channels.bluebubbles.defaultAccount nadpisuje domyślny wybór konta, gdy 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 udokumentowana 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 domyślny wybór konta, gdy 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ć 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łej kontroli klucza hosta, więc upewnij się, że klucz hosta przekaźnika już istnieje w ~/.ssh/known_hosts.
• channels.imessage.configWrites: zezwalaj lub odmawiaj zapisów konfiguracji inicjowanych przez 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 proxy HTTP(S). Nazwane konta mogą go nadpisać przez channels.matrix.accounts.<id>.proxy.
• channels.matrix.allowPrivateNetwork zezwala na prywatne/wewnętrzne homeserwery. proxy i allowPrivateNetwork to niezależne mechanizmy kontroli.
• channels.matrix.defaultAccount wybiera preferowane konto w konfiguracjach wielokontowych.
• channels.matrix.execApprovals: natywne dostarczanie zatwierdzeń exec przez Matrix 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) mogące zatwierdzać żądania 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ć prompty zatwierdzeń. "dm" (domyślnie), "channel" (pokój źródłowy) lub "both".
  • Nadpisania per konto: channels.matrix.accounts.<id>.execApprovals.
• Sondy stanu Matrix i wyszukiwania katalogowe na żywo używają tej samej polityki proxy co ruch środowiska uruchomieniowego.
• Pełna konfiguracja Matrix, reguły targetowania i przykłady konfiguracji są udokumentowane w Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, zasady zespołów/kanałów:
      // zobacz /channels/msteams
    },
  },
}

• Kluczowe ścieżki rdzeniowe omówione tutaj: channels.msteams, channels.msteams.configWrites.
• Pełna konfiguracja Teams (poświadczenia, webhook, zasady DM/grup, nadpisania per zespół/per kanał) jest udokumentowana 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",
      },
    },
  },
}

• Kluczowe ścieżki rdzeniowe omówione tutaj: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• Opcjonalne channels.irc.defaultAccount nadpisuje domyślny wybór konta, gdy pasuje do skonfigurowanego identyfikatora konta.
• Pełna konfiguracja kanału IRC (host/port/TLS/kanały/listy dozwolonych/gating wzmiankami) jest udokumentowana w IRC.

​

Wielokontowość (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 zostanie pominięte (CLI + routing).
• Tokeny env 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 skierować każde konto do innego agenta.
• Jeśli dodasz konto inne niż domyślne przez openclaw channels add (lub onboarding kanału), będąc nadal przy jednokontowej konfiguracji kanału na poziomie głównym, OpenClaw najpierw promuje 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 cel named/default.
• Istniejące powiązania tylko kanałowe (bez accountId) nadal pasują do konta domyślnego; powiązania o zakresie konta pozostają opcjonalne.
• openclaw doctor --fix naprawia też mieszane kształty, przenosząc wartości jednokontowe najwyższego poziomu o zakresie konta do promowanego konta wybranego dla danego kanału. Większość kanałów używa accounts.default; Matrix może zamiast tego zachować istniejący pasujący cel named/default.

​

Inne kanały rozszerzeń

​

Gating wzmiankami w czatach grupowych

• Wzmianki w 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.
• Gating wzmiankami jest egzekwowany 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"] },
      },
    ],
  },
}

​

Commands (obsługa poleceń czatu)

{
  commands: {
    native: "auto", // rejestruj natywne polecenia, gdy są obsługiwane
    text: true, // parsuj /commands w wiadomościach czatu
    bash: false, // zezwalaj na ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // zezwalaj na /config
    debug: false, // zezwalaj na /debug
    restart: false, // zezwalaj na /restart + narzędzie restartu gateway
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Domyślne ustawienia agentów

​

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" }, // dziedziczy github, weather
      { id: "docs", skills: ["docs-search"] }, // zastępuje wartości domyślne
      { id: "locked-down", skills: [] }, // bez Skills
    ],
  },
}

• Pomiń agents.defaults.skills, aby domyślnie Skills nie były ograniczone.
• 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 ostatecznym zestawem dla danego agenta; nie jest scalana z wartościami domyślnymi.

​

agents.defaults.skipBootstrap

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

​

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 promptu.
• "once": wstrzykuje ostrzeżenie raz na unikalną sygnaturę obcięcia (zalecane).
• "always": wstrzykuje ostrzeżenie przy każdym uruchomieniu, gdy istnieje obcięcie.

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

​

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" }, // globalne domyślne parametry dostawcy
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: akceptuje albo string ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Forma string ustawia tylko model główny.
  • Forma obiektu ustawia model główny plus uporządkowane modele failover.
• imageModel: akceptuje albo string ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez ścieżkę narzędzia image jako konfiguracja modelu vision.
  • Używany też jako routing zapasowy, gdy wybrany/domyslny model nie akceptuje wejścia obrazowego.
• imageGenerationModel: akceptuje albo string ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną funkcję generowania obrazów i każdą przyszłą powierzchnię narzędzi/pluginów 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 dostawcę/model, skonfiguruj też 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ślnego dostawcę z uwierzytelniania. 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.
• videoGenerationModel: akceptuje albo string ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez współdzieloną funkcję generowania wideo.
  • 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.
  • Ustaw to jawnie przed użyciem współdzielonego generowania wideo. W przeciwieństwie do imageGenerationModel, środowisko uruchomieniowe generowania wideo nie wywnioskuje jeszcze domyślnego dostawcy.
  • Jeśli wybierzesz bezpośrednio dostawcę/model, skonfiguruj też pasujące uwierzytelnianie/klucz API dostawcy.
  • Dołączony dostawca generowania wideo Qwen obsługuje obecnie maksymalnie 1 wideo wyjściowe, 1 obraz wejściowy, 4 wideo wejściowe, 10 sekund czasu trwania oraz opcje na poziomie dostawcy size, aspectRatio, resolution, audio i watermark.
• pdfModel: akceptuje albo string ("provider/model"), albo obiekt ({ primary, fallbacks }).
  • Używany przez narzędzie pdf do routingu modeli.
  • Jeśli pominięty, narzędzie PDF wraca 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 podczas wywołania.
• pdfMaxPages: domyślna maksymalna liczba stron uwzględnianych przez tryb zapasowy 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 skonfigurowanego dostawcy dla dokładnie tego identyfikatora modelu, a dopiero potem wraca do skonfigurowanego dostawcy domyślnego (przestarzałe zachowanie zgodności, więc preferuj jawne provider/model). Jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, OpenClaw wraca do pierwszego skonfigurowanego dostawcy/modelu zamiast eksponować nieaktualną 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, np. 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), następnie agents.list[].params (dla pasującego identyfikatora agenta) nadpisuje per klucz. Szczegóły: Prompt Caching.
• Mechanizmy zapisu konfiguracji, które modyfikują te pola (na przykład /models set, /models set-image i polecenia add/remove fallback), zapisują kanoniczną formę obiektową i w miarę możliwości zachowują istniejące listy fallback.
• maxConcurrent: maksymalna liczba równoległych uruchomień agentów między sesjami (każda sesja nadal jest serializowana). Domyślnie: 4.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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ą ukierunkowane na tekst; narzędzia są zawsze wyłączone.
• Sesje są obsługiwane, gdy ustawiono sessionArg.
• Przekazywanie obrazów jest obsługiwane, gdy imageArg akceptuje ścieżki plików.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m wyłącza
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        lightContext: false, // domyślnie: false; true zachowuje tylko HEARTBEAT.md z plików bootstrap workspace
        isolatedSession: false, // domyślnie: false; true uruchamia każdy heartbeat w nowej sesji (bez historii rozmowy)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (domyślnie) | block
        target: "none", // domyślnie: none | opcje: last | whatsapp | telegram | discord | ...
        prompt: "Przeczytaj HEARTBEAT.md, jeśli istnieje...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every: ciąg czasu (ms/s/m/h). Domyślnie: 30m (uwierzytelnianie kluczem API) lub 1h (uwierzytelnianie OAuth). Ustaw 0m, aby wyłączyć.
• suppressToolErrorWarnings: gdy true, tłumi ładunki ostrzeżeń o błędach narzędzi podczas uruchomień heartbeat.
• directPolicy: zasada dostarczania bezpośredniego/DM. allow (domyślnie) pozwala na dostarczanie do celu bezpośredniego. block tłumi dostarczanie do celu bezpośredniego i emituje reason=dm-blocked.
• lightContext: gdy true, uruchomienia heartbeat używają lekkiego kontekstu bootstrap i zachowują tylko HEARTBEAT.md z plików bootstrap workspace.
• isolatedSession: gdy true, każde uruchomienie heartbeat odbywa się w nowej 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 ~2-5K tokenów.
• Per agent: ustaw agents.list[].heartbeat. Gdy jakikolwiek agent definiuje heartbeat, heartbeat uruchamia się tylko dla tych agentów.
• Heartbeat wykonują pełne tury agenta — krótsze interwały zużywają więcej tokenów.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Zachowaj dokładnie identyfikatory wdrożeń, identyfikatory ticketów i pary host:port.", // używane, gdy identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] wyłącza ponowne wstrzykiwanie
        model: "openrouter/anthropic/claude-sonnet-4-6", // opcjonalne nadpisanie modelu tylko do kompaktowania
        notifyUser: true, // wyślij krótkie powiadomienie, gdy rozpoczyna się kompaktowanie (domyślnie: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Sesja zbliża się do kompaktowania. Zapisz trwałe wspomnienia teraz.",
          prompt: "Zapisz trwałe notatki do memory/YYYY-MM-DD.md; odpowiedz dokładnym cichym tokenem NO_REPLY, jeśli nie ma nic do zapisania.",
        },
      },
    },
  },
}

• mode: default lub safeguard (sumaryzacja kawałkami dla długich historii). Zobacz Compaction.
• timeoutSeconds: maksymalna liczba sekund dozwolona dla jednej operacji kompaktowania, zanim OpenClaw ją przerwie. Domyślnie: 900.
• identifierPolicy: strict (domyślnie), off lub custom. strict poprzedza sumaryzację kompaktowania wbudowanymi wskazówkami zachowania nieprzezroczystych identyfikatorów.
• 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 kompaktowaniu. Domyślnie ["Session Startup", "Red Lines"]; ustaw [], aby wyłączyć ponowne wstrzykiwanie. Gdy nieustawione lub ustawione jawnie na tę domyślną parę, starsze nagłówki Every Session/Safety są również akceptowane jako zapasowa zgodność.
• model: opcjonalne nadpisanie provider/model-id tylko dla sumaryzacji kompaktowania. Użyj tego, gdy główna sesja powinna pozostać przy jednym modelu, ale podsumowania kompaktowania powinny działać na innym; gdy nieustawione, kompaktowanie używa modelu głównego sesji.
• notifyUser: gdy true, wysyła użytkownikowi krótkie powiadomienie, gdy rozpoczyna się kompaktowanie (na przykład „Compacting context…”). Domyślnie wyłączone, aby kompaktowanie pozostało ciche.
• memoryFlush: cicha agentska tura przed automatycznym kompaktowaniem w celu zapisania trwałych wspomnień. Pomijana, gdy workspace jest tylko do odczytu.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // czas trwania (ms/s/m/h), domyślna jednostka: minuty
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Treść starego wyniku narzędzia wyczyszczona]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Block streaming

{
  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 (użyj minMs/maxMs)
    },
  },
}

• Kanały inne niż Telegram wymagają jawnego *.blockStreaming: true, aby włączyć odpowiedzi blokowe.
• Nadpisania kanałów: 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,
    },
  },
}

• Domyślnie: instant dla czatów bezpośrednich/wzmianek, message dla niewspomnianych 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",
          // SecretRef i zawartość inline również są obsługiwane:
          // 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", // opcjonalnie
          gatewayEndpoint: "https://lab.example", // opcjonalnie
          policy: "strict", // opcjonalny identyfikator polityki OpenShell
          providers: ["openai"], // opcjonalnie
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # główny obraz sandbox
scripts/sandbox-browser-setup.sh   # opcjonalny obraz przeglądarki

​

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", // lub { primary, fallbacks }
        thinkingDefault: "high", // nadpisanie poziomu thinking per agent
        reasoningDefault: "on", // nadpisanie widoczności reasoning per agent
        fastModeDefault: false, // nadpisanie fast mode per agent
        params: { cacheRetention: "none" }, // nadpisuje kluczem pasujące defaults.models params
        skills: ["docs-search"], // zastępuje agents.defaults.skills, gdy ustawione
        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 ustawiono wiele, wygrywa pierwszy (zapisywane jest ostrzeżenie). Jeśli żaden nie jest ustawiony, domyślny jest pierwszy wpis listy.
• model: forma string nadpisuje tylko primary; forma obiektowa { 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 nad wybranym wpisem modelu w agents.defaults.models. Używaj 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ęte, 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 ustawiono nadpisania per wiadomość lub per sesję.
• reasoningDefault: opcjonalna domyślna widoczność reasoning per agent (on | off | stream). Ma zastosowanie, gdy nie ustawiono nadpisania reasoning per wiadomość lub per sesję.
• fastModeDefault: opcjonalna domyślna wartość fast mode per agent (true | false). Ma zastosowanie, gdy nie ustawiono fast mode per wiadomość lub per sesję.
• runtime: opcjonalny deskryptor środowiska uruchomieniowego per agent. Użyj type: "acp" z wartościami domyślnymi runtime.acp (agent, backend, mode, cwd), gdy agent ma domyślnie używać sesji harness ACP.
• identity.avatar: ścieżka względna względem 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).
• Guard dziedziczenia sandbox: 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 powiązania

• type (opcjonalne): route dla normalnego 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; specyficzne dla 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: "*" (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, // pomiń fork wątku nadrzędnego powyżej tej liczby tokenów (0 wyłącza)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // czas trwania lub false
      maxDiskBytes: "500mb", // opcjonalny sztywny budżet
      highWaterBytes: "400mb", // opcjonalny cel czyszczenia
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // domyślne automatyczne odfokusowanie po bezczynności w godzinach (`0` wyłącza)
      maxAgeHours: 0, // domyślny sztywny maksymalny wiek w godzinach (`0` wyłącza)
    },
    mainKey: "main", // starsze (środowisko uruchomieniowe zawsze używa "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Wiadomości

{
  messages: {
    responsePrefix: "🦞", // lub "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 wyłącza
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefiks odpowiedzi

​

Reakcja ack

• Domyślnie używa identity.emoji aktywnego agenta, w przeciwnym razie "👀". Ustaw "", aby wyłączyć.
• Nadpisania per kanał: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Kolejność rozstrzygania: konto → kanał → messages.ackReaction → wartość zapasowa z identity.
• Zakres: group-mentions (domyślnie), group-all, direct, all.
• removeAckAfterReply: usuwa ack po odpowiedzi w Slack, Discord i Telegram.
• messages.statusReactions.enabled: włącza reakcje statusu cyklu życia w Slack, Discord i Telegram. W Slack i Discord brak ustawienia utrzymuje reakcje statusu włączone, gdy aktywne są reakcje ack. W Telegram ustaw to jawnie na true, aby włączyć reakcje statusu cyklu życia.

​

Debounce przychodzących

​

TTS (text-to-speech)

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

• auto kontroluje auto-TTS. /tts off|always|inbound|tagged nadpisuje per sesję.
• summaryModel nadpisuje agents.defaults.model.primary dla automatycznego podsumowania.
• modelOverrides jest domyślnie włączone; modelOverrides.allowProvider domyślnie ma wartość false (opt-in).
• Klucze API wracają do ELEVENLABS_API_KEY/XI_API_KEY oraz OPENAI_API_KEY.
• openai.baseUrl nadpisuje endpoint OpenAI TTS. Kolejność rozstrzygania to config, potem OPENAI_TTS_BASE_URL, a następnie https://api.openai.com/v1.
• Gdy openai.baseUrl wskazuje endpoint inny niż OpenAI, OpenClaw traktuje go jako serwer TTS zgodny z OpenAI i łagodzi walidację modelu/głosu.

​

Talk

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

• talk.provider musi odpowiadać kluczowi w talk.providers, gdy skonfigurowano wielu dostawców Talk.
• Starsze płaskie klucze Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) służą wyłącznie zgodności i są automatycznie migrowane do talk.providers.<provider>.
• Identyfikatory głosów wracają do ELEVENLABS_VOICE_ID lub SAG_VOICE_ID.
• providers.*.apiKey akceptuje jawne stringi lub obiekty SecretRef.
• Wartość zapasowa ELEVENLABS_API_KEY ma zastosowanie tylko wtedy, gdy nie skonfigurowano klucza API Talk.
• providers.*.voiceAliases pozwala dyrektywom Talk używać przyjaznych nazw.
• silenceTimeoutMs kontroluje, jak długo tryb Talk czeka po ciszy użytkownika przed wysłaniem transkryptu. Brak ustawienia zachowuje domyślne okno pauzy platformy (700 ms na macOS i Android, 900 ms na iOS).

​

Narzędzia

​

Profile narzędzi

​

Grupy narzędzi

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}