Dotyczy OpenClaw v2026.2 | Artykuł dla osób, które ukończyły podstawową konfigurację i chcą lepiej zrozumieć architekturę. Zalecane wcześniejsze ukończenie 3 pierwszych poradników.

TL;DR: Gateway to centralna płaszczyzna sterowania OpenClaw. Session to kontener kontekstu rozmowy (main/channel/group), Message Router decyduje o routingu wiadomości, Tool Registry zarządza uprawnieniami narzędzi, Skills to gotowe rozszerzenia. Endpoint WebSocket: ws://127.0.0.1:18789/ws, przydatne komendy: openclaw gateway/doctor/config. Zrozumienie tych koncepcji jest podstawą zaawansowanej konfiguracji.

Przegląd architektury

Ogólna architektura

flowchart TB
    subgraph Clients["Warstwa klientów"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Warstwa Gateway"]
        WS[Serwer WebSocket]
        HTTP[Serwer HTTP]
        MR[Router wiadomości]
        SM[Menedżer sesji]
        TR[Rejestr narzędzi]
        EM[Menedżer zdarzeń]
        CFG[Magazyn konfiguracji]
    end
    
    subgraph Agent["Warstwa agenta"]
        PI[Pi Agent]
        PROMPT[Silnik promptów]
        TOOLS[Executor narzędzi]
        SKILLS[Menedżer Skills]
    end
    
    subgraph External["Usługi zewnętrzne"]
        FS[System plików]
        BR[Przeglądarka]
        API[Usługi API]
        DB[Baza danych]
        CAL[Harmonogram Cron]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

Odpowiedzialności komponentów

Przepływ danych

sequenceDiagram
    participant U as Użytkownik
    participant C as Kanał
    participant WS as WebSocket
    participant MR as Router
    participant SM as Sesja
    participant A as Agent
    participant T as Narzędzia
    
    U->>C: Wysłanie wiadomości
    C->>WS: Push wiadomości
    WS->>MR: Żądanie routingu
    MR->>SM: Wyszukanie/utworzenie sesji
    SM-->>MR: Zwrócenie sesji
    MR->>A: Dostarczenie wiadomości
    A->>A: Przetwarzanie wiadomości
    A->>T: Wywołanie narzędzia (opcjonalne)
    T-->>A: Zwrócenie wyniku
    A-->>MR: Wygenerowanie odpowiedzi
    MR->>WS: Wysłanie odpowiedzi
    WS->>C: Push odpowiedzi
    C-->>U: Wyświetlenie wiadomości

Model sesji (Session)

Czym jest sesja?

Session to jedno z najważniejszych pojęć w OpenClaw. Każda sesja reprezentuje niezależny kontekst rozmowy zawierający:

Typy sesji

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}

Cykl życia sesji

stateDiagram-v2
    [*] --> Created: Nadeszła wiadomość
    Created --> Active: Pierwsza odpowiedź
    Active --> Active: Interakcja
    Active --> Idle: Brak aktywności
    Idle --> Active: Nowa wiadomość
    Idle --> Compacted: Automatyczna kompresja
    Compacted --> Active: Kontynuacja rozmowy
    Active --> Reset: Komenda /reset
    Reset --> Created: Start od nowa
    Active --> Pruned: Czyszczenie sesji
    Idle --> Pruned: Czyszczenie po timeout
    Pruned --> [*]

Komendy sesji

Komendy do zarządzania sesjami wysyłane w czacie:

Konfiguracja sesji

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}

Router wiadomości (Message Router)

Reguły routingu

Message Router odpowiada za kierowanie wiadomości do odpowiedniej sesji:

flowchart TB
    MSG[Nadeszła wiadomość] --> CH{Typ kanału?}
    CH -->|Prywatna| DM[Wyodrębnienie ID nadawcy]
    CH -->|Grupowa| GRP[Wyodrębnienie ID grupy]
    CH -->|WebChat/CLI| MAIN[Użycie sesji main]
    
    DM --> SID[Sesja: channel:user:id]
    GRP --> GID[Sesja: channel:group:id]
    
    SID --> EXISTS{Sesja istnieje?}
    GID --> EXISTS
    
    EXISTS -->|Tak| LOAD[Załadowanie sesji]
    EXISTS -->|Nie| CREATE[Utworzenie nowej sesji]
    
    CREATE --> LOAD
    LOAD --> AGENT[Dostarczenie do agenta]

Konfiguracja routingu

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

Strategie aktywacji grup

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Rejestr narzędzi (Tool Registry)

Wbudowane narzędzia

OpenClaw posiada bogaty zestaw wbudowanych narzędzi:

Kontrola uprawnień narzędzi

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}

Szczegóły konfiguracji sandbox

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

System umiejętności (Skills)

Architektura Skills

flowchart LR
    subgraph Skills["Katalog Skills"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Menedżer Skills"]
        DISC[Odkrywanie]
        LOAD[Ładowanie]
        EXEC[Wykonanie]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Wstrzyknięcie do promptu]
        TOOLS[Rejestracja narzędzi]
        RES[Zwrócenie wyników]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Struktura katalogu Skills

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # Definicja umiejętności
│   ├── package.json      # Zależności (opcjonalne)
│   └── src/
│       └── index.js      # Implementacja (opcjonalna)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

Struktura SKILL.md

# Gmail Skill

## Description
Send and read Gmail messages through OpenClaw.

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
When the user wants to send an email:
1. Ask for recipient, subject, and body
2. Use the gmail_send tool
3. Confirm the email was sent

When the user wants to check emails:
1. Use the gmail_list tool
2. Summarize the results

## Tools
- gmail_list: List recent emails
- gmail_send: Send an email
- gmail_read: Read a specific email

## Examples
User: "Check my email"
Action: Use gmail_list tool

User: "Send an email to [email protected]"
Action: Ask for subject and body, then use gmail_send

Instalacja Skills

# Instalacja z ClawHub
openclaw skill install gmail

# Instalacja z GitHub
openclaw skill install github:user/repo/skill-name

# Ręczna instalacja
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Konfiguracja Skills

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}

Protokół WebSocket

Endpoint połączenia

ws://127.0.0.1:18789/ws

Format wiadomości

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // Zawartość wiadomości
  }
}

Typy wiadomości klienta

Typy wiadomości serwera

Przykład: Wysyłanie wiadomości

// Połączenie WebSocket
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// Wysłanie wiadomości
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'Cześć, przedstaw się'
  }
}));

// Odbiór odpowiedzi
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // Przykładowy wynik:
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: 'Cześć! Jestem Twoim asystentem OpenClaw...',
  //     session: 'main'
  //   }
  // }
};

System zdarzeń (Event System)

Wbudowane zdarzenia

Konfiguracja Webhook

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Payload Webhook

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "Cześć",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Zadania cykliczne (Cron)

Przykład konfiguracji

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Podaj mi dzisiejszy harmonogram",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Wygeneruj podsumowanie tygodnia pracy",
      "enabled": true
    }
  ]
}

Wyrażenia Cron

┌───────────── minuta (0 - 59)
│ ┌───────────── godzina (0 - 23)
│ │ ┌───────────── dzień miesiąca (1 - 31)
│ │ │ ┌───────────── miesiąc (1 - 12)
│ │ │ │ ┌───────────── dzień tygodnia (0 - 6, 0 = niedziela)
│ │ │ │ │
* * * * *

Popularne przykłady

Hierarchia i priorytety konfiguracji

Kolejność priorytetów

Parametry CLI > Zmienne środowiskowe > Plik konfiguracyjny > Wartości domyślne

Źródła konfiguracji

Przykład łączenia konfiguracji

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# Nadpisanie zmienną środowiskową
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# Nadpisanie parametrem CLI (najwyższy priorytet)
openclaw gateway --model "anthropic/claude-opus-4"

Aktualizacja konfiguracji na żywo

# Aktualizacja konfiguracji (bez restartu)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# Przeładowanie pliku konfiguracyjnego
openclaw config reload

# Weryfikacja konfiguracji
openclaw config get agent.model

Podręczna ściągawka poleceń

Zarządzanie Gateway

# Uruchomienie Gateway
openclaw gateway

# Z określonym portem
openclaw gateway --port 18790

# W tle
openclaw gateway --daemon

# Szczegółowe logi
openclaw gateway --verbose

# Health check
openclaw health

Zarządzanie sesjami

# Lista wszystkich sesji
openclaw session list

# Szczegóły sesji
openclaw session show main
openclaw session show telegram:user:123456789

# Reset sesji
openclaw session reset main

# Usunięcie sesji
openclaw session delete telegram:user:123456789

Zarządzanie konfiguracją

# Podgląd konfiguracji
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# Ustawienie konfiguracji
openclaw config set agent.thinkingLevel high

# Lista wszystkich ustawień
openclaw config list

# Walidacja konfiguracji
openclaw config validate

Narzędzia diagnostyczne

# Pełna diagnostyka
openclaw doctor

# Sprawdzenie konkretnego elementu
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# Podgląd logów
openclaw logs
openclaw logs --follow
openclaw logs --level error

Rozwiązywanie problemów

Gateway nie uruchamia się

# Sprawdzenie zajętości portu
lsof -i :18789
netstat -tlnp | grep 18789

# Sprawdzenie składni konfiguracji
openclaw config validate

# Szczegółowy błąd
openclaw gateway --verbose 2>&1 | tee gateway.log

Utrata sesji

# Sprawdzenie katalogu sesji
ls -la ~/.openclaw/sessions/

# Sprawdzenie konfiguracji czyszczenia
openclaw config get sessionPruning

# Wyłączenie automatycznego czyszczenia
openclaw config set sessionPruning.enabled false

Niepowodzenie wywołania narzędzia

# Sprawdzenie konfiguracji sandbox
openclaw config get agents.defaults.sandbox

# Tymczasowe wyłączenie sandbox
openclaw config set agents.defaults.sandbox.mode off

# Logi narzędzi
openclaw logs --filter tool

Niepowodzenie połączenia WebSocket

# Sprawdzenie statusu Gateway
curl http://127.0.0.1:18789/health

# Sprawdzenie endpointu WebSocket
wscat -c ws://127.0.0.1:18789/ws

# Sprawdzenie firewalla
sudo ufw status
sudo iptables -L -n | grep 18789

Podsumowanie

Zrozumienie kluczowych koncepcji Gateway jest kluczem do opanowania OpenClaw:

• Session: kontener kontekstu rozmowy, z izolacją typów
• Message Router: rdzeń routingu wiadomości, decyduje o kierunku
• Tool Registry: centrum rejestracji narzędzi, kontroluje zdolności agenta
• Skills: system rozszerzeń umiejętności, szybkie powiększanie funkcjonalności
• WebSocket: protokół komunikacji w czasie rzeczywistym, wsparcie dla własnych klientów
• System zdarzeń: mechanizm dystrybucji zdarzeń, obsługa Webhook i Cron

Te koncepcje będą się powtarzać w kolejnych artykułach — ich głębokie zrozumienie pomoże Ci lepiej konfigurować i używać OpenClaw.

Podsumowanie artykułu:

• Poznałeś ogólną architekturę Gateway i odpowiedzialności komponentów
• Zrozumiałeś model sesji i cykl życia
• Nauczyłeś się routingu wiadomości i strategii aktywacji grup
• Poznałeś uprawnienia narzędzi i konfigurację sandbox
• Opanowałeś protokół WebSocket i system zdarzeń

Historia zmian:

• 2026-02-26: Pierwsza wersja, na podstawie OpenClaw v2026.2

Nawigacja po serii:

• ← Poprzedni artykuł: Konfiguracja kanałów: zaczynamy od Telegrama
• → Następny artykuł: Konfiguracja i przełączanie wielu modeli