Konfiguracja

Każdy kanał ma własną sekcję konfiguracji w channels.<provider>. Zobacz dedykowaną stronę kanału z krokami 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 główny 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.
• 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 steruje zmniejszaniem obrazów z transkrypcji/narzędzi (domyślnie 1200); niższe wartości zwykle zmniejszają użycie tokenów wizji w przebiegach z dużą liczbą zrzutów ekranu.
• Zobacz CLI modeli, aby przełączać modele w czacie, oraz Przełączanie awaryjne modeli, aby poznać rotację uwierzytelniania i zachowanie zapasowe.
• W przypadku niestandardowych/samodzielnie hostowanych dostawców zobacz Niestandardowi dostawcy w dokumentacji referencyjnej.

Dostęp do wiadomości prywatnych jest kontrolowany osobno 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": zezwól na wszystkie przychodzące wiadomości prywatne (wymaga allowFrom: ["*"])
• "disabled": ignoruj wszystkie wiadomości prywatne

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

Szczegóły dla poszczególnych kanałów znajdziesz w pełnej dokumentacji.

Wiadomości grupowe domyślnie wymagają wzmianki. Skonfiguruj wzorce wyzwalaczy dla poszczególnych agentów 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", // ustaw "message_tool", aby wszędzie wymagać wysyłania przez narzędzie wiadomości
    groupChat: {
      visibleReplies: "message_tool", // domyślnie; użyj "automatic" dla starszych odpowiedzi w pokoju
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Wzmianki w metadanych: natywne @-wzmianki (WhatsApp dotknij-aby-wspomnieć, Telegram @bot itd.)
• Wzorce tekstowe: bezpieczne wzorce regex w mentionPatterns
• Widoczne odpowiedzi: messages.visibleReplies może globalnie wymagać wysyłania przez narzędzie wiadomości; messages.groupChat.visibleReplies zastępuje 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 podstawy, a następnie nadpisz konkretnych 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: [] }, // brak 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 nieaktywne:

{
  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ę, aby poznać wszystkie pola.

Daj klientom lokalnym więcej czasu na ukończenie przedautoryzacyjnego uzgadniania WebSocket 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 dla jednorazowych nadpisań usługi lub powłoki.
• Najpierw najlepiej naprawić zacięcia uruchamiania/pętli zdarzeń; to ustawienie jest przeznaczone dla hostów, które są zdrowe, ale wolne 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ólne) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: globalne wartości domyślne dla trasowania 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ę, aby poznać wszystkie pola.

Uruchamiaj sesje agentów w izolowanych środowiskach wykonawczych sandbox:

{
  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 przy instalacji z npm zobacz wbudowane polecenie docker build w Sandboxing § Obrazy i konfiguracja.

Pełny przewodnik znajdziesz w Sandboxing, a wszystkie opcje w pełnej referencji.

Push wspierany przez relay konfiguruje się 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, pobudki wake nudges i pobudki ponownego połączenia przez zewnętrzny relay.
• Używa grantu wysyłania o zakresie rejestracji, przekazanego przez sparowaną aplikację iOS. Gateway nie potrzebuje tokenu relay obowiązującego dla całego wdrożenia.
• Wiąże każdą rejestrację wspieraną przez relay 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 buildy iOS przy bezpośrednim APNs. Wysyłki wspierane przez relay dotyczą tylko oficjalnie dystrybuowanych buildów, które zarejestrowały się przez relay.
• Musi odpowiadać bazowemu URL relay wbudowanemu w oficjalny/TestFlight build iOS, aby ruch rejestracji i wysyłania trafiał do tego samego wdrożenia relay.

Przepływ end-to-end:

1. Zainstaluj oficjalny/TestFlight build iOS skompilowany z tym samym bazowym URL relay.
2. Skonfiguruj gateway.push.apns.relay.baseUrl na gateway.
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 relay z użyciem App Attest oraz paragonu aplikacji, a następnie publikuje payload push.apns.register wspierany przez relay do sparowanego gateway.
5. Gateway zapisuje uchwyt relay i grant wysyłania, a następnie używa ich dla push.test, pobudek wake nudges i pobudek ponownego połączenia.

Uwagi operacyjne:

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

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 awaryjną furtką deweloperską tylko dla local loopback; nie zapisuj URL-i relay HTTP w konfiguracji.

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

{
  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
• Pełny przewodnik znajdziesz w Heartbeat.

{
  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 zachowywanych wierszy.
• Zobacz Zadania Cron, aby poznać przegląd 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łą zawartość payloadów hook/Webhook jako niezaufane dane wejściowe.
• Użyj dedykowanego hooks.token; nie używaj ponownie współdzielonego tokenu Gateway.
• Uwierzytelnianie hooków działa tylko przez nagłówki (Authorization: Bearer ... albo x-openclaw-token); tokeny w query string są odrzucane.
• hooks.path nie może mieć wartości /; utrzymuj ingress Webhook na dedykowanej podścieżce, takiej jak /hooks.
• Pozostaw wyłączone flagi omijania 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ć wybierane przez wywołującego klucze sesji.
• Dla agentów sterowanych hookami preferuj mocne nowoczesne poziomy modeli i ścisłą politykę narzędzi (na przykład tylko wiadomości plus sandboxing tam, gdzie to możliwe).

Zobacz pełną referencję, 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 Multi-Agent i pełną referencję, aby poznać reguły powiązań i profile dostępu 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: głęboko scalana po kolei (późniejszy wygrywa)
• Klucze równorzędne: scalane po include (nadpisują dołączone wartości)
• 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
• Zapisy zarządzane przez 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ługiwany zapis przez include: include w katalogu głównym, tablice include oraz include z nadpisaniami równorzędnymi kończą się bezpiecznym błędem dla zapisów zarządzanych przez 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) do dodatkowych katalogów, do których include mogą się odwoływać. Dowiązania symboliczne są rozwiązywane i ponownie sprawdzane, 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 i cyklicznych include