Konfiguracja

Każdy kanał ma własną sekcję konfiguracji pod channels.<provider>. Zobacz dedykowaną stronę kanału, aby poznać kroki konfiguracji:

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

Wszystkie kanały mają ten sam wzorzec zasad DM:

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

Ustaw model podstawowy i opcjonalne modele zapasowe:

{  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 działa jako lista dozwolonych dla /model; wpisy provider/* filtrują /model, /models i selektory modeli do wybranych dostawców, nadal korzystając z dynamicznego wykrywania modeli.
• Użyj openclaw config set agents.defaults.models '<json>' --strict-json --merge, aby dodać wpisy listy dozwolonych bez usuwania istniejących modeli. Zwykłe zastąpienia, które usunęłyby wpisy, są odrzucane, chyba że przekażesz --replace.
• Odwołania do modeli używają formatu provider/model (np. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx kontroluje zmniejszanie obrazów z transkrypcji/narzędzi (domyślnie 1200); niższe wartości zwykle ograniczają użycie tokenów vision w przebiegach z dużą liczbą zrzutów ekranu.
• Zobacz Models CLI, aby przełączać modele na czacie, oraz Model Failover, aby poznać rotację uwierzytelniania i zachowanie zapasowe.
• Dla niestandardowych/samodzielnie hostowanych dostawców zobacz Custom providers w dokumentacji.

Dostęp DM jest kontrolowany dla każdego kanału przez dmPolicy:

• "pairing" (domyślnie): nieznani nadawcy otrzymują jednorazowy kod parowania do zatwierdzenia
• "allowlist": tylko nadawcy w allowFrom (lub w sparowanym magazynie zezwoleń)
• "open": zezwalaj na wszystkie przychodzące DM (wymaga allowFrom: ["*"])
• "disabled": ignoruj wszystkie DM

Dla grup użyj groupPolicy + groupAllowFrom lub list dozwolonych specyficznych dla kanału.

Zobacz pełną dokumentację, aby poznać szczegóły dla poszczególnych kanałów.

Wiadomości grupowe domyślnie wymagają wzmianki. Skonfiguruj wzorce wyzwalaczy dla każdego agenta. Normalne odpowiedzi w grupach/kanałach są publikowane automatycznie; włącz ścieżkę narzędzia wiadomości dla współdzielonych pokojów, w których agent powinien decydować, kiedy się odezwać:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Wzmianki metadanych: natywne @-wzmianki (WhatsApp tap-to-mention, Telegram @bot itd.)
• Wzorce tekstowe: bezpieczne wzorce regex w mentionPatterns
• Widoczne odpowiedzi: messages.visibleReplies może wymagać wysyłania przez narzędzie wiadomości globalnie; messages.groupChat.visibleReplies nadpisuje to dla grup/kanałów.
• Zobacz pełną dokumentację, aby poznać tryby widocznych odpowiedzi, nadpisania dla poszczególnych kanałów i tryb czatu z samym sobą.

Użyj agents.defaults.skills jako wspólnej bazy, a następnie nadpisz konkretnych agentów za pomocą agents.list[].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.
• Zobacz Skills, Skills config oraz Configuration Reference.

Kontroluj, jak agresywnie Gateway restartuje kanały, które wyglądają na nieaktualne:

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

• Ustaw gateway.channelHealthCheckMinutes: 0, aby globalnie wyłączyć restarty monitora kondycji.
• channelStaleEventThresholdMinutes powinno być większe lub równe interwałowi sprawdzania.
• Użyj channels.<provider>.healthMonitor.enabled lub channels.<provider>.accounts.<id>.healthMonitor.enabled, aby wyłączyć automatyczne restarty dla jednego kanału lub konta bez wyłączania globalnego monitora.
• Zobacz Health Checks, aby debugować operacyjnie, oraz pełną dokumentację, aby poznać wszystkie pola.

Daj klientom lokalnym więcej czasu na ukończenie przeduwierzytelnieniowego uzgadniania WebSocket na obciążonych lub słabszych hostach:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Wartość domyślna to 15000 milisekund.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS nadal ma pierwszeństwo dla jednorazowych nadpisań usługi lub powłoki.
• Najpierw preferuj naprawę zacięć uruchamiania/pętli zdarzeń; ta opcja jest przeznaczona dla hostów, które są zdrowe, ale wolne podczas rozgrzewki.

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

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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ątkiem (Discord obsługuje /focus, /unfocus, /agents, /session idle i /session max-age).
• Zobacz Zarządzanie sesjami, aby poznać zakresy, powiązania tożsamości i zasady wysyłania.
• Zobacz pełną dokumentację referencyjną, aby poznać wszystkie pola.

Uruchamiaj sesje agentów w izolowanych środowiskach piaskownicy:

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

Najpierw zbuduj obraz - z checkoutu źródeł uruchom scripts/sandbox-setup.sh, a w przypadku instalacji z npm zobacz wbudowane polecenie docker build w sekcji Izolacja w piaskownicy § Obrazy i konfiguracja.

Zobacz Izolacja w piaskownicy, aby poznać pełny przewodnik, oraz pełną dokumentację referencyjną, aby poznać wszystkie opcje.

Push oparty na przekaźniku dla publicznych buildów App Store używa hostowanego przekaźnika OpenClaw: https://ios-push-relay.openclaw.ai.

Niestandardowe wdrożenia przekaźnika wymagają celowo oddzielnej ścieżki buildu/wdrożenia iOS, której adres URL przekaźnika pasuje do adresu URL przekaźnika Gateway. Jeśli używasz niestandardowego buildu przekaźnika, ustaw to w konfiguracji gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

Odpowiednik CLI:

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

Co to robi:

• Pozwala gateway wysyłać push.test, impulsy wybudzające i wybudzenia ponownego połączenia przez zewnętrzny przekaźnik.
• Używa uprawnienia wysyłania ograniczonego do rejestracji, przekazywanego przez sparowaną aplikację iOS. Gateway nie potrzebuje tokenu przekaźnika obowiązującego dla całego wdrożenia.
• Wiąże każdą rejestrację opartą na przekaźniku 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 buildy iOS przy bezpośrednim APNs. Wysyłki oparte na przekaźniku dotyczą tylko oficjalnie dystrybuowanych buildów zarejestrowanych przez przekaźnik.
• Musi pasować do bazowego adresu URL przekaźnika wbudowanego w build iOS, aby ruch rejestracji i wysyłania trafiał do tego samego wdrożenia przekaźnika.

Przepływ end-to-end:

1. Zainstaluj oficjalną aplikację iOS.
2. Opcjonalnie: skonfiguruj gateway.push.apns.relay.baseUrl na gateway tylko wtedy, gdy używasz celowo oddzielnego niestandardowego buildu przekaźnika.
3. Sparuj aplikację iOS z gateway i pozwól połączyć się zarówno sesjom Node, jak i operatora.
4. Aplikacja iOS pobiera tożsamość gateway, rejestruje się w przekaźniku za pomocą App Attest oraz potwierdzenia aplikacji, a następnie publikuje oparty na przekaźniku ładunek push.apns.register do sparowanego gateway.
5. Gateway zapisuje uchwyt przekaźnika i uprawnienie wysyłania, a następnie używa ich dla push.test, impulsów wybudzających i wybudzeń ponownego połączenia.

Uwagi operacyjne:

• Jeśli przełączysz aplikację iOS na inny gateway, połącz aplikację ponownie, aby mogła opublikować nową rejestrację przekaźnika powiązaną z tym gateway.
• Jeśli wydasz nowy build iOS wskazujący na inne wdrożenie przekaźnika, aplikacja odświeży swoją zbuforowaną rejestrację przekaźnika zamiast ponownie używać starego źródła przekaźnika.

Uwaga dotycząca zgodności:

• OPENCLAW_APNS_RELAY_BASE_URL i OPENCLAW_APNS_RELAY_TIMEOUT_MS nadal działają jako tymczasowe nadpisania env.
• Niestandardowe adresy URL przekaźnika gateway muszą pasować do bazowego adresu URL przekaźnika wbudowanego w build iOS. Publiczna ścieżka wydania App Store odrzuca niestandardowe nadpisania adresu URL przekaźnika iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true pozostaje wyłącznie deweloperską furtką dla local loopback; nie zapisuj adresów URL przekaźnika HTTP w konfiguracji.

Zobacz Aplikacja iOS, aby poznać przepływ end-to-end, oraz Uwierzytelnianie i przepływ zaufania, aby poznać model bezpieczeństwa przekaźnika.

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

• every: ciąg czasu trwania (30m, 2h). Ustaw 0m, aby wyłączyć.
• target: last | none | <channel-id> (na przykład discord, matrix, telegram lub whatsapp)
• directPolicy: allow (domyślnie) albo block dla celów Heartbeat w stylu DM
• Zobacz Heartbeat, aby poznać pełny przewodnik.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: usuwa ukończone izolowane sesje uruchomień z sessions.json (domyślnie 24h; ustaw false, aby wyłączyć).
• runLog: usuwa zachowane wiersze historii uruchomień Cron dla każdego zadania. maxBytes pozostaje akceptowane dla starszych dzienników uruchomień opartych na plikach.
• Zobacz Zadania Cron, aby poznać omówienie funkcji i przykłady CLI.

Włącz punkty końcowe HTTP Webhook w 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:

• Traktuj całą treść ładunków hook/webhook jako niezaufane dane wejściowe.
• Użyj dedykowanego hooks.token; nie używaj ponownie aktywnych sekretów uwierzytelniania Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN albo gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Uwierzytelnianie hooków odbywa się wyłącznie przez nagłówki (Authorization: Bearer ... albo x-openclaw-token); tokeny w query string są odrzucane.
• hooks.path nie może być /; utrzymuj ruch wejściowy webhooków na dedykowanej podścieżce, takiej jak /hooks.
• Pozostaw wyłączone flagi obejścia niebezpiecznej treści (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), chyba że prowadzisz ściśle ograniczone debugowanie.
• Jeśli włączysz hooks.allowRequestSessionKey, ustaw także hooks.allowedSessionKeyPrefixes, aby ograniczyć klucze sesji wybierane przez wywołującego.
• W przypadku agentów sterowanych hookami preferuj mocne nowoczesne poziomy modeli i ścisłą politykę narzędzi (na przykład tylko komunikacja plus izolacja w piaskownicy tam, gdzie to możliwe).

Zobacz pełną dokumentację referencyjną, aby poznać wszystkie opcje mapowania i integrację Gmail.

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

Zobacz Wielu agentów i pełną dokumentację referencyjną, aby poznać reguły powiązań i profile dostępu dla poszczególnych agentów.

Użyj $include, aby uporządkować duże konfiguracje:

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

• Pojedynczy plik: zastępuje zawierający go obiekt
• Tablica plików: scalana głęboko w kolejności (późniejsze wygrywają)
• Klucze równorzędne: scalane po include (nadpisują wartości z include)
• Zagnieżdżone include: obsługiwane do 10 poziomów głębokości
• Ścieżki względne: rozwiązywane względem pliku zawierającego include
• Format ścieżki: ścieżki include nie mogą zawierać bajtów null i muszą być ściśle krótsze niż 4096 znaków przed rozwiązaniem i po nim
• Zapisy należące do OpenClaw: gdy zapis zmienia tylko jedną sekcję najwyższego poziomu opartą na include pojedynczego pliku, takim jak plugins: { $include: "./plugins.json5" }, OpenClaw aktualizuje ten dołączony plik i pozostawia openclaw.json bez zmian
• Nieobsługiwane zapisy przez include: include na poziomie root, tablice include oraz include z nadpisaniami równorzędnymi kończą się zamkniętą odmową dla zapisów należących do OpenClaw zamiast spłaszczać konfigurację
• Ograniczenie: ścieżki $include muszą rozwiązywać się pod katalogiem zawierającym openclaw.json. Aby współdzielić drzewo między maszynami lub użytkownikami, ustaw OPENCLAW_INCLUDE_ROOTS na listę ścieżek (: w POSIX, ; w Windows) dodatkowych katalogów, do których mogą odwoływać się include. Dowiązania symboliczne są rozwiązywane i sprawdzane ponownie, więc ścieżka, która leksykalnie znajduje się w katalogu konfiguracji, ale której rzeczywisty cel wychodzi poza każdy dozwolony root, nadal jest odrzucana.
• Obsługa błędów: czytelne błędy dla brakujących plików, błędów parsowania, cyklicznych include, nieprawidłowego formatu ścieżki i nadmiernej długości