Konfiguracja

Każdy kanał ma własną sekcję konfiguracji w channels.<provider>. Instrukcje konfiguracji znajdują się na stronie poświęconej danemu kanałowi:

• Discord — channels.discord
• Feishu — channels.feishu
• Google Chat — channels.googlechat
• iMessage — channels.imessage
• Mattermost — channels.mattermost
• Microsoft Teams — channels.msteams
• Signal — channels.signal
• Slack — channels.slack
• Telegram — channels.telegram
• WhatsApp — channels.whatsapp

Wszystkie kanały korzystają z tego samego wzorca zasad wiadomości prywatnych:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // tylko dla allowlist/open    },  },}

Należy ustawić model podstawowy i opcjonalne modele zastępcze:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models definiuje katalog modeli i pełni funkcję listy dozwolonych dla /model; wpisy provider/* ograniczają /model, /models i selektory modeli do wybranych dostawców, nadal korzystając z dynamicznego wykrywania modeli.
• Aby dodać wpisy do listy dozwolonych bez usuwania istniejących modeli, należy użyć openclaw config set agents.defaults.models '<json>' --strict-json --merge. Zwykłe zastąpienia, które spowodowałyby usunięcie wpisów, są odrzucane, chyba że przekazano --replace.
• Odwołania do modeli używają formatu provider/model (np. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx steruje zmniejszaniem rozdzielczości obrazów w transkrypcjach i narzędziach (domyślnie 1200); niższe wartości zazwyczaj ograniczają użycie tokenów wizyjnych podczas przebiegów z dużą liczbą zrzutów ekranu.
• Informacje o przełączaniu modeli na czacie znajdują się w CLI modeli, a informacje o rotacji uwierzytelniania i działaniu modeli zastępczych — w Przełączaniu awaryjnym modeli.
• Informacje o niestandardowych lub samodzielnie hostowanych dostawcach znajdują się w sekcji Niestandardowi dostawcy dokumentacji referencyjnej.

Dostęp do wiadomości prywatnych jest kontrolowany osobno dla każdego kanału za pomocą dmPolicy (domyślnie "pairing"):

• "pairing": nieznani nadawcy otrzymują jednorazowy kod parowania wymagający zatwierdzenia
• "allowlist": dostęp mają tylko nadawcy z allowFrom (lub ze sparowanego magazynu dozwolonych)
• "open": zezwala na wszystkie przychodzące wiadomości prywatne (wymaga allowFrom: ["*"])
• "disabled": ignoruje wszystkie wiadomości prywatne

W przypadku grup należy użyć groupPolicy ("allowlist" | "open" | "disabled") wraz z groupAllowFrom lub listami dozwolonych właściwymi dla kanału.

Szczegóły dotyczące poszczególnych kanałów znajdują się w pełnej dokumentacji referencyjnej.

Wiadomości grupowe domyślnie wymagają wzmianki. Wzorce wyzwalające konfiguruje się osobno dla każdego agenta. Zwykłe odpowiedzi w grupie lub kanale są publikowane automatycznie; w pokojach współdzielonych, w których agent powinien decydować, kiedy się odezwać, należy włączyć ścieżkę narzędzia wiadomości:

{  messages: {    visibleReplies: "automatic", // ustaw "message_tool", aby wszędzie wymagać wysyłania przez narzędzie wiadomości    groupChat: {      visibleReplies: "message_tool", // opcjonalne; widoczny wynik wymaga message(action=send)      unmentionedInbound: "room_event", // niewspomniane, stale aktywne rozmowy grupowe stanowią cichy kontekst    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Wzmianki w metadanych: natywne wzmianki @ (dotknięcie wzmianki w WhatsApp, @bot w Telegramie itp.)
• Wzorce tekstowe: bezpieczne wzorce wyrażeń regularnych w mentionPatterns
• Widoczne odpowiedzi: messages.visibleReplies może globalnie wymagać wysyłania za pomocą narzędzia wiadomości; messages.groupChat.visibleReplies zastępuje to ustawienie dla grup i kanałów.
• Tryby widocznych odpowiedzi, ustawienia zastępujące dla poszczególnych kanałów i tryb czatu z samym sobą opisano w pełnej dokumentacji referencyjnej.

Należy użyć agents.defaults.skills jako wspólnej konfiguracji bazowej, a następnie zastąpić ją dla określonych agentów za pomocą agents.list[].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    ],  },}

• Aby domyślnie nie ograniczać Skills, należy pominąć agents.defaults.skills.
• Aby odziedziczyć wartości domyślne, należy pominąć agents.list[].skills.
• Aby wyłączyć Skills, należy ustawić agents.list[].skills: [].
• Zobacz Skills, Konfiguracja Skills oraz Dokumentacja referencyjna konfiguracji.

Można określić, jak agresywnie Gateway ma ponownie uruchamiać kanały, które wydają się nieaktywne:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Przedstawione wartości są domyślne. Aby globalnie wyłączyć ponowne uruchamianie przez monitor stanu, należy ustawić gateway.channelHealthCheckMinutes: 0.
• channelStaleEventThresholdMinutes powinno być większe lub równe interwałowi sprawdzania.
• Aby wyłączyć automatyczne ponowne uruchamianie pojedynczego kanału lub konta bez wyłączania globalnego monitora, należy użyć channels.<provider>.healthMonitor.enabled lub channels.<provider>.accounts.<id>.healthMonitor.enabled.
• Informacje o debugowaniu operacyjnym znajdują się w Kontrolach stanu, a opis wszystkich pól — w pełnej dokumentacji referencyjnej.

Lokalnym klientom można zapewnić więcej czasu na ukończenie uzgadniania WebSocket poprzedzającego uwierzytelnianie na obciążonych hostach lub hostach o małej mocy:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Wartość domyślna to 15000 milisekund.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS nadal ma pierwszeństwo w przypadku jednorazowych nadpisań usługi lub powłoki.
• Najpierw należy usunąć zastoje podczas uruchamiania lub w pętli zdarzeń; to ustawienie jest przeznaczone dla hostów, które działają prawidłowo, ale wolno podczas rozgrzewania.

Sesje kontrolują ciągłość i izolację konwersacji:

{  session: {    dmScope: "per-channel-peer",  // zalecane dla wielu użytkowników    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (współdzielone) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: globalne wartości domyślne routingu sesji powiązanych z wątkami. /focus, /unfocus, /agents, /session idle i /session max-age odpowiednio wiążą, usuwają powiązanie, wyświetlają listę i dostosowują to ustawienie dla poszczególnych sesji (Discord wiąże wątki, Telegram wiąże tematy/konwersacje).
• Informacje o zakresach, powiązaniach tożsamości i zasadach wysyłania zawiera sekcja Zarządzanie sesjami.
• Wszystkie pola opisano w pełnej dokumentacji.

Sesje agentów można uruchamiać w izolowanych środowiskach piaskownicy:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Najpierw należy zbudować obraz — w repozytorium źródłowym należy uruchomić scripts/sandbox-setup.sh, a w przypadku instalacji z npm użyć wbudowanego polecenia docker build opisanego w sekcji Piaskownica § Obrazy i konfiguracja.

Pełny przewodnik zawiera sekcja Piaskownica, a wszystkie opcje opisano w pełnej dokumentacji.

Przekazywane powiadomienia push w publicznych kompilacjach z App Store korzystają z hostowanej usługi przekazywania OpenClaw: https://ios-push-relay.openclaw.ai.

Niestandardowe wdrożenia usługi przekazywania wymagają celowo oddzielnej ścieżki kompilacji i wdrażania iOS, której adres URL usługi przekazywania jest zgodny z adresem URL usługi przekazywania Gateway. W przypadku korzystania z niestandardowej kompilacji usługi przekazywania należy ustawić w konfiguracji Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Opcjonalne. Wartość domyślna: 10000          timeoutMs: 10000,        },      },    },  },}

Odpowiednik w CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Działanie:

• Umożliwia Gateway wysyłanie push.test, sygnałów wybudzania i wybudzeń ponownego połączenia przez zewnętrzną usługę przekazywania.
• Używa uprawnienia do wysyłania ograniczonego do rejestracji, przekazanego przez sparowaną aplikację iOS. Gateway nie wymaga tokenu usługi przekazywania obejmującego całe wdrożenie.
• Wiąże każdą rejestrację korzystającą z usługi przekazywania z tożsamością Gateway, z którą sparowano aplikację iOS, dzięki czemu inny Gateway nie może ponownie użyć zapisanej rejestracji.
• Pozostawia lokalne/ręczne kompilacje iOS przy bezpośrednim korzystaniu z APNs. Wysyłanie przez usługę przekazywania dotyczy tylko oficjalnie dystrybuowanych kompilacji zarejestrowanych za jej pośrednictwem.
• Musi odpowiadać bazowemu adresowi URL usługi przekazywania wbudowanemu w kompilację iOS, aby ruch rejestracyjny i wysyłania trafiał do tego samego wdrożenia usługi przekazywania.

Przepływ kompleksowy:

1. Zainstalować oficjalną aplikację iOS.
2. Opcjonalnie: skonfigurować gateway.push.apns.relay.baseUrl w Gateway wyłącznie w przypadku korzystania z celowo oddzielnej, niestandardowej kompilacji usługi przekazywania.
3. Sparować aplikację iOS z Gateway i umożliwić połączenie sesji Node oraz operatora.
4. Aplikacja iOS pobiera tożsamość Gateway, rejestruje się w usłudze przekazywania przy użyciu App Attest oraz potwierdzenia zakupu aplikacji, a następnie publikuje do sparowanego Gateway ładunek push.apns.register obsługiwany przez usługę przekazywania.
5. Gateway zapisuje uchwyt usługi przekazywania i uprawnienie do wysyłania, a następnie używa ich dla push.test, sygnałów wybudzania i wybudzeń ponownego połączenia.

Uwagi operacyjne:

• Po przełączeniu aplikacji iOS na inny Gateway należy ponownie połączyć aplikację, aby mogła opublikować nową rejestrację usługi przekazywania powiązaną z tym Gateway.
• W przypadku wydania nowej kompilacji iOS wskazującej inne wdrożenie usługi przekazywania aplikacja odświeża rejestrację usługi przekazywania w pamięci podręcznej zamiast ponownie używać starego źródła usługi.

Uwaga dotycząca zgodności:

• OPENCLAW_APNS_RELAY_BASE_URL i OPENCLAW_APNS_RELAY_TIMEOUT_MS nadal działają jako tymczasowe nadpisania za pomocą zmiennych środowiskowych.
• Niestandardowe adresy URL usługi przekazywania Gateway muszą odpowiadać bazowemu adresowi URL wbudowanemu w kompilację iOS; publiczny kanał wydań App Store odrzuca nadpisania niestandardowego adresu URL usługi przekazywania iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true pozostaje mechanizmem awaryjnym przeznaczonym wyłącznie do programowania w pętli zwrotnej; nie należy trwale zapisywać adresów URL usługi przekazywania HTTP w konfiguracji.

Kompleksowy przepływ opisano w sekcji Aplikacja iOS, a model zabezpieczeń usługi przekazywania w sekcji Przepływ uwierzytelniania i zaufania.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: ciąg określający czas trwania (30m, 2h). Aby wyłączyć, należy ustawić 0m. Wartość domyślna: 30m.
• target: last | none | <channel-id> (na przykład discord, matrix, telegram lub whatsapp)
• directPolicy: allow (domyślnie) lub block dla celów Heartbeat typu DM
• Pełny przewodnik zawiera sekcja Heartbeat.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // wartość domyślna; wysyłanie cron + wykonanie izolowanego przebiegu agenta cron    sessionRetention: "24h",  },}

• sessionRetention: usuwa zakończone sesje izolowanych przebiegów z wierszy sesji SQLite (domyślnie 24h; aby wyłączyć, należy ustawić false).
• Historia przebiegów automatycznie zachowuje najnowsze 2000 końcowych wierszy na zadanie; utracone wiersze zachowują 24-godzinne okno usuwania.
• Omówienie funkcji i przykłady użycia CLI zawiera sekcja Zadania Cron.

Włączanie punktów końcowych HTTP Webhook na Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

Uwaga dotycząca bezpieczeństwa:

• Całą zawartość ładunków hooków/Webhooków należy traktować jako niezaufane dane wejściowe.
• Należy użyć dedykowanego hooks.token; nie należy ponownie używać aktywnych sekretów uwierzytelniających Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ani gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Uwierzytelnianie hooków odbywa się wyłącznie za pomocą nagłówka (Authorization: Bearer ... lub x-openclaw-token); tokeny w ciągu zapytania są odrzucane.
• hooks.path nie może mieć wartości /; ruch przychodzący Webhooków należy utrzymywać w dedykowanej podścieżce, takiej jak /hooks.
• Flagi pomijania zabezpieczeń dla niebezpiecznej zawartości (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) powinny pozostać wyłączone, z wyjątkiem ściśle ograniczonego debugowania.
• W przypadku włączenia hooks.allowRequestSessionKey należy także ustawić hooks.allowedSessionKeyPrefixes, aby ograniczyć klucze sesji wybierane przez wywołującego.
• W przypadku agentów uruchamianych przez hooki zaleca się zaawansowane, nowoczesne poziomy modeli i rygorystyczne zasady dotyczące narzędzi (na przykład tylko obsługa wiadomości oraz piaskownica, gdy jest to możliwe).

Wszystkie opcje mapowania i integrację z Gmailem opisano w pełnej dokumentacji.

Uruchamianie wielu izolowanych agentów z oddzielnymi obszarami roboczymi i sesjami:

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

Reguły powiązań i profile dostępu poszczególnych agentów opisano w sekcjach Wielu agentów i pełna dokumentacja.

Duże konfiguracje można porządkować za pomocą $include:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• Pojedynczy plik: zastępuje obiekt zawierający
• Tablica plików: scalana głęboko w kolejności (późniejsze wartości mają pierwszeństwo), maksymalnie do 10 poziomów zagnieżdżenia
• Klucze równorzędne: scalane po dołączeniu plików (nadpisują dołączone wartości)
• Ścieżki względne: rozwiązywane względem pliku dołączającego
• Format ścieżki: ścieżki dołączanych plików nie mogą zawierać bajtów null i muszą mieć ściśle mniej niż 4096 znaków przed i po rozwiązaniu
• Zapisy wykonywane przez OpenClaw: gdy zapis zmienia tylko jedną sekcję najwyższego poziomu opartą na dołączeniu pojedynczego pliku, takim jak plugins: { $include: "./plugins.json5" }, OpenClaw aktualizuje ten dołączony plik i pozostawia openclaw.json bez zmian
• Nieobsługiwane przekazywanie zapisu: dołączenia główne, tablice dołączeń oraz dołączenia z równorzędnymi nadpisaniami są bezpiecznie odrzucane podczas zapisów wykonywanych przez OpenClaw zamiast spłaszczania konfiguracji
• Ograniczenie: ścieżki $include muszą rozwiązywać się w katalogu zawierającym openclaw.json. Aby współdzielić drzewo między komputerami lub użytkownikami, należy ustawić OPENCLAW_INCLUDE_ROOTS na listę ścieżek (: w systemach POSIX, ; w systemie Windows) do dodatkowych katalogów, do których mogą odwoływać się dołączenia. Dowiązania symboliczne są rozwiązywane i ponownie sprawdzane, dlatego ścieżka, która leksykalnie znajduje się w katalogu konfiguracji, ale której rzeczywisty cel wychodzi poza każdy dozwolony katalog główny, nadal jest odrzucana.
• Obsługa błędów: czytelne błędy dotyczące brakujących plików, błędów analizy składni, cyklicznych dołączeń, nieprawidłowego formatu ścieżki i nadmiernej długości