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 współdzielą 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 do 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 transkryptu/narzędzi (domyślnie 1200); niższe wartości zwykle zmniejszają zużycie tokenów wizji w przebiegach z dużą liczbą zrzutów ekranu.
• Zobacz CLI modeli, aby przełączać modele na czacie, oraz Przełączanie awaryjne modeli, aby poznać rotację uwierzytelniania i zachowanie modeli zapasowych.
• Dla niestandardowych/samodzielnie hostowanych dostawców zobacz Dostawcy niestandardowi w dokumentacji.

Dostęp DM jest kontrolowany per kanał przez dmPolicy:

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

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

Zobacz pełną dokumentację, aby poznać szczegóły per kanał.

Wiadomości grupowe domyślnie wymagają wzmianki. Skonfiguruj wzorce wyzwalania per agent i pozostaw widoczne odpowiedzi w pokoju na domyślnej ścieżce narzędzia wiadomości, chyba że celowo chcesz używać starszych automatycznych odpowiedzi końcowych:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Wzmianki w metadanych: natywne @-wzmianki (WhatsApp tap-to-mention, Telegram @bot itp.)
• 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 per kanał i tryb self-chat.

Użyj agents.defaults.skills jako wspólnej bazy, a następnie nadpisz konkretnych agentów przez 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 używać żadnych Skills.
• Zobacz Skills, konfigurację Skills oraz dokumentację konfiguracji.

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

{  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 albo channels.<provider>.accounts.<id>.healthMonitor.enabled, aby wyłączyć automatyczne restarty dla jednego kanału lub konta bez wyłączania globalnego monitora.
• Zobacz Kontrole kondycji, aby debugować operacyjnie, oraz pełną dokumentację dla wszystkich pól.

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

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Domyślna wartość 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ń; to pokrętło jest dla hostów, które są zdrowe, ale wolne podczas rozgrzewania.

Sesje kontrolują ciągłość i izolację rozmów:

{  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ólne) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: globalne wartości domyślne routingu sesji powiązanych z wątkami (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 uruchomieniowych sandbox:

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

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

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

Powiadomienia push oparte na przekaźniku są konfigurowane w openclaw.json.

Ustaw to w konfiguracji Gateway:

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

Odpowiednik w CLI:

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

Co to robi:

• Pozwala Gateway wysyłać push.test, sygnały wybudzające i wybudzenia do ponownego połączenia przez zewnętrzny przekaźnik.
• Używa uprawnienia wysyłania ograniczonego do rejestracji, przekazanego przez sparowaną aplikację iOS. Gateway nie potrzebuje tokenu przekaźnika 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, więc inny Gateway nie może ponownie użyć zapisanej rejestracji.
• Pozostawia lokalne/ręczne kompilacje iOS przy bezpośrednim APNs. Wysyłki oparte na przekaźniku dotyczą tylko oficjalnych dystrybuowanych kompilacji, które zarejestrowały się przez przekaźnik.
• Musi pasować do bazowego URL przekaźnika wbudowanego w oficjalną kompilację iOS/TestFlight, aby ruch rejestracji i wysyłania trafiał do tego samego wdrożenia przekaźnika.

Przepływ od początku do końca:

1. Zainstaluj oficjalną kompilację iOS lub kompilację z TestFlight skompilowaną z tym samym bazowym URL przekaźnika.
2. Skonfiguruj gateway.push.apns.relay.baseUrl w Gateway.
3. Sparuj aplikację iOS z Gateway i pozwól połączyć się zarówno sesjom węzła, jak i operatora.
4. Aplikacja iOS pobiera tożsamość Gateway, rejestruje się w przekaźniku przy użyciu App Attest wraz z pokwitowaniem aplikacji, a następnie publikuje oparty na przekaźniku ładunek push.apns.register do sparowanego Gateway.
5. Gateway zapisuje uchwyt przekaźnika i uprawnienie do wysyłania, a następnie używa ich dla push.test, sygnałów wybudzających i wybudzeń do 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 nową kompilację iOS wskazującą inne wdrożenie przekaźnika, aplikacja odświeży swoją buforowaną 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.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true pozostaje deweloperskim obejściem tylko dla local loopback; nie zapisuj adresów URL przekaźnika HTTP w konfiguracji.

Zobacz Aplikacja iOS, aby poznać przepływ od początku do końca, 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: 2, // 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: przycina cron/runs/<jobId>.jsonl według rozmiaru i liczby zachowanych wierszy.
• Zobacz Zadania Cron, aby poznać opis funkcji i przykłady CLI.

Włącz punkty końcowe HTTP typu 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łą zawartość ładunków hook/Webhook jako niezaufane dane wejściowe.
• Używaj dedykowanego hooks.token; nie używaj ponownie współdzielonego tokenu Gateway.
• Uwierzytelnianie hooków działa tylko przez nagłówek (Authorization: Bearer ... albo x-openclaw-token); tokeny w ciągu zapytania są odrzucane.
• hooks.path nie może być /; trzymaj ruch przychodzący Webhook na dedykowanej podścieżce, takiej jak /hooks.
• Pozostaw wyłączone flagi obchodzenia niebezpiecznej zawartoś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.
• Dla agentów sterowanych hookami preferuj mocne nowoczesne klasy modeli i ścisłe zasady narzędzi (na przykład tylko wiadomości plus izolacja w sandboxie, gdzie to możliwe).

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

Uruchamiaj wielu izolowanych agentów z osobnymi 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 porzą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 obiekt zawierający
• Tablica plików: głęboko scalana w kolejności (późniejsze wygrywają)
• Klucze równorzędne: scalane po dołączeniach (nadpisują dołączone wartości)
• Zagnieżdżone dołączenia: obsługiwane do 10 poziomów głębokości
• Ścieżki względne: rozwiązywane względem pliku dołączającego
• 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ługiwany zapis przez include: dołączenia główne, tablice dołączeń i dołączenia z nadpisaniami przez klucze równorzędne kończą się bezpieczną odmową dla zapisów wykonywanych przez OpenClaw zamiast spłaszczać konfigurację
• Ograniczenie: ścieżki $include muszą rozwiązywać się pod katalogiem zawierającym openclaw.json. Aby udostępnić drzewo między maszynami lub użytkownikami, ustaw OPENCLAW_INCLUDE_ROOTS na listę ścieżek (: w POSIX, ; w Windows) do dodatkowych katalogów, do których dołączenia mogą się odwoływać. 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 katalog główny, nadal jest odrzucana.
• Obsługa błędów: czytelne błędy dla brakujących plików, błędów parsowania i cyklicznych dołączeń