OpenClaw v2026.2 için geçerlidir | Bu makale, temel yapılandırmayı tamamlamış ve mimariyi derinlemesine anlamak isteyen kullanıcılar için uygundur. İlk 3 eğitimin tamamlanması önerilir.

TL;DR: Gateway, OpenClaw’ın temel kontrol düzlemidir. Session, konuşma bağlam kapsayıcısıdır (main/channel/group), Message Router mesaj yönlendirmesini belirler, Tool Registry araç yetkilerini yönetir, Skills önceden paketlenmiş yetenek genişletmeleridir. WebSocket uç noktası ws://127.0.0.1:18789/ws, yaygın komutlar openclaw gateway/doctor/config. Bu kavramları anlamak, ileri düzey yapılandırmanın temelidir.

Mimari Genel Bakış

Genel Mimari

flowchart TB
    subgraph Clients["İstemci Katmanı"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end
    
    subgraph Gateway["Gateway Katmanı"]
        WS[WebSocket Sunucusu]
        HTTP[HTTP Sunucusu]
        MR[Mesaj Yönlendiricisi]
        SM[Oturum Yöneticisi]
        TR[Araç Kaydı]
        EM[Olay Yöneticisi]
        CFG[Yapılandırma Deposu]
    end
    
    subgraph Agent["Agent Katmanı"]
        PI[Pi Agent]
        PROMPT[Prompt Motoru]
        TOOLS[Araç Yürütücüsü]
        SKILLS[Beceri Yöneticisi]
    end
    
    subgraph External["Harici Servisler"]
        FS[Dosya Sistemi]
        BR[Tarayıcı]
        API[API Servisleri]
        DB[Veritabanı]
        CAL[Cron Zamanlayıcı]
    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

Bileşen Görevleri

Veri Akışı

sequenceDiagram
    participant U as Kullanıcı
    participant C as Kanal
    participant WS as WebSocket
    participant MR as Yönlendirici
    participant SM as Oturum
    participant A as Agent
    participant T as Araçlar
    
    U->>C: Mesaj gönder
    C->>WS: Mesaj gönder
    WS->>MR: Yönlendirme isteği
    MR->>SM: Oturumu bul/oluştur
    SM-->>MR: Oturumu döndür
    MR->>A: Mesajı ilet
    A->>A: Mesajı işle
    A->>T: Araç çağır (isteğe bağlı)
    T-->>A: Sonucu döndür
    A-->>MR: Yanıt oluştur
    MR->>WS: Yanıt gönder
    WS->>C: Yanıtı gönder
    C-->>U: Mesajı göster

Session Oturum Modeli

Session Nedir?

Session, OpenClaw’daki en temel kavramlardan biridir. Her Session bağımsız bir konuşma bağlamını temsil eder ve şunları içerir:

Session Türleri

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

Session Yaşam Döngüsü

stateDiagram-v2
    [*] --> Created: Mesaj ulaştı
    Created --> Active: İlk yanıt
    Active --> Active: Mesaj etkileşimi
    Active --> Idle: Aktivite yok
    Idle --> Active: Yeni mesaj
    Idle --> Compacted: Otomatik sıkıştırma
    Compacted --> Active: Sohbete devam
    Active --> Reset: /reset komutu
    Reset --> Created: Yeniden başla
    Active --> Pruned: Oturum temizliği
    Idle --> Pruned: Zaman aşımı temizliği
    Pruned --> [*]

Session Komutları

Sohbette aşağıdaki komutları göndererek oturumları yönetin:

Session Yapılandırması

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

Message Router Mesaj Yönlendirme

Yönlendirme Kuralları

Message Router, gelen mesajları doğru Session’a yönlendirmekten sorumludur:

flowchart TB
    MSG[Mesaj ulaştı] --> CH{Kanal türü?}
    CH -->|Özel sohbet| DM[Gönderen ID'sini çıkar]
    CH -->|Grup sohbeti| GRP[Grup ID'sini çıkar]
    CH -->|WebChat/CLI| MAIN[main oturumunu kullan]
    
    DM --> SID[Session: channel:user:id]
    GRP --> GID[Session: channel:group:id]
    
    SID --> EXISTS{Oturum mevcut mu?}
    GID --> EXISTS
    
    EXISTS -->|Evet| LOAD[Oturumu yükle]
    EXISTS -->|Hayır| CREATE[Yeni oturum oluştur]
    
    CREATE --> LOAD
    LOAD --> AGENT[Agent'a ilet]

Yönlendirme Yapılandırması

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

Grup Aktivasyon Stratejisi

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

Tool Registry Araç Kaydı

Yerleşik Araçlar

OpenClaw zengin yerleşik araçlara sahiptir:

Araç Yetki Kontrolü

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

Sandbox Yapılandırma Detayları

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

Skills Beceri Sistemi

Skills Mimarisi

flowchart LR
    subgraph Skills["Beceri Dizini"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Beceri Yöneticisi"]
        DISC[Keşif]
        LOAD[Yükleme]
        EXEC[Yürütme]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Prompt'a Enjekte Et]
        TOOLS[Araçları Kaydet]
        RES[Sonuç Döndür]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Skills Dizin Yapısı

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # Beceri tanımı
│   ├── package.json      # Bağımlılıklar (isteğe bağlı)
│   └── src/
│       └── index.js      # Uygulama (isteğe bağlı)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

SKILL.md Yapısı

# 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

Skills Kurulum Yöntemleri

# ClawHub'dan kur
openclaw skill install gmail

# GitHub'dan kur
openclaw skill install github:user/repo/skill-name

# Manuel kurulum
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Skills Yapılandırması

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

WebSocket Protokolü

Bağlantı Uç Noktası

ws://127.0.0.1:18789/ws

Mesaj Formatı

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // Mesaj içeriği
  }
}

İstemci Mesaj Türleri

Sunucu Mesaj Türleri

Örnek: Mesaj Gönderme

// WebSocket'e bağlan
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// Mesaj gönder
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'Merhaba, lütfen kendini tanıt'
  }
}));

// Yanıtı al
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // Örnek çıktı:
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: 'Merhaba! Ben senin OpenClaw asistanınım...',
  //     session: 'main'
  //   }
  // }
};

Event System Olay Sistemi

Yerleşik Olaylar

Webhook Yapılandırması

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

Webhook Yükü

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

Cron Zamanlanmış Görevler

Yapılandırma Örneği

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Bugünkü takvim planımı ver",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Bu haftanın çalışma özetini oluştur",
      "enabled": true
    }
  ]
}

Cron İfadesi

┌───────────── Dakika (0 - 59)
│ ┌───────────── Saat (0 - 23)
│ │ ┌───────────── Gün (1 - 31)
│ │ │ ┌───────────── Ay (1 - 12)
│ │ │ │ ┌───────────── Haftanın günü (0 - 6, 0 = Pazar)
│ │ │ │ │
* * * * *

Yaygın Örnekler

Yapılandırma Hiyerarşisi ve Önceliği

Öncelik Sırası

CLI parametreleri > Ortam değişkenleri > Yapılandırma dosyası > Varsayılan değerler

Yapılandırma Kaynakları

Yapılandırma Birleştirme Örneği

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

# Ortam değişkeni ile geçersiz kıl
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# CLI parametresi ile geçersiz kıl (en yüksek öncelik)
openclaw gateway --model "anthropic/claude-opus-4"

Yapılandırma Canlı Güncellemesi

# Yapılandırmayı güncelle (yeniden başlatma gerekmez)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# Yapılandırma dosyasını yeniden yükle
openclaw config reload

# Yapılandırmayı doğrula
openclaw config get agent.model

Yaygın Komutlar Referansı

Gateway Yönetimi

# Gateway'i başlat
openclaw gateway

# Port belirt
openclaw gateway --port 18790

# Arka planda çalıştır
openclaw gateway --daemon

# Ayrıntılı günlük
openclaw gateway --verbose

# Sağlık kontrolü
openclaw health

Oturum Yönetimi

# Tüm oturumları listele
openclaw session list

# Oturum detaylarını görüntüle
openclaw session show main
openclaw session show telegram:user:123456789

# Oturumu sıfırla
openclaw session reset main

# Oturumu sil
openclaw session delete telegram:user:123456789

Yapılandırma Yönetimi

# Yapılandırmayı görüntüle
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# Yapılandırmayı ayarla
openclaw config set agent.thinkingLevel high

# Tüm yapılandırmaları listele
openclaw config list

# Yapılandırmayı doğrula
openclaw config validate

Tanılama Araçları

# Tam tanılama
openclaw doctor

# Belirli öğeyi kontrol et
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# Günlükleri görüntüle
openclaw logs
openclaw logs --follow
openclaw logs --level error

Sorun Giderme

Gateway Başlatılamıyor

# Port kullanımını kontrol et
lsof -i :18789
netstat -tlnp | grep 18789

# Yapılandırma sözdizimini kontrol et
openclaw config validate

# Ayrıntılı hatayı görüntüle
openclaw gateway --verbose 2>&1 | tee gateway.log

Oturum Kayboldu

# Oturum dizinini kontrol et
ls -la ~/.openclaw/sessions/

# Temizleme yapılandırmasını kontrol et
openclaw config get sessionPruning

# Otomatik temizlemeyi devre dışı bırak
openclaw config set sessionPruning.enabled false

Araç Çağrısı Başarısız

# Sandbox yapılandırmasını kontrol et
openclaw config get agents.defaults.sandbox

# Sandbox'u geçici olarak devre dışı bırak
openclaw config set agents.defaults.sandbox.mode off

# Araç günlüklerini görüntüle
openclaw logs --filter tool

WebSocket Bağlantısı Başarısız

# Gateway durumunu kontrol et
curl http://127.0.0.1:18789/health

# WebSocket uç noktasını kontrol et
wscat -c ws://127.0.0.1:18789/ws

# Güvenlik duvarını kontrol et
sudo ufw status
sudo iptables -L -n | grep 18789

Özet

Gateway temel kavramlarını anlamak, OpenClaw’a hakim olmanın anahtarıdır:

• Session: Konuşma bağlamının kapsayıcısı, tür izolasyonunu destekler
• Message Router: Mesaj yönlendirmenin çekirdeği, mesajın nereye gideceğini belirler
• Tool Registry: Araç kayıt merkezi, Agent yeteneklerini kontrol eder
• Skills: Beceri genişletme sistemi, işlevleri hızla artırır
• WebSocket: Gerçek zamanlı iletişim protokolü, özel istemcileri destekler
• Event System: Olay dağıtım mekanizması, Webhook ve Cron’u destekler

Bu kavramlar sonraki makalelerde tekrar tekrar karşınıza çıkacaktır; bunları derinlemesine anlamak, OpenClaw’ı daha iyi yapılandırmanıza ve kullanmanıza yardımcı olacaktır.

Bu Bölümün Özeti:

• Gateway genel mimarisi ve bileşen görevlerini öğrendiniz
• Session oturum modeli ve yaşam döngüsünü anladınız
• Mesaj yönlendirme ve grup aktivasyon stratejisini öğrendiniz
• Araç yetkileri ve sandbox yapılandırmasını kavradınız
• WebSocket protokolü ve olay sistemini öğrendiniz

Güncelleme Kayıtları:

• 2026-02-26: İlk sürüm yayınlandı, OpenClaw v2026.2 temel alınmıştır

Seri Navigasyonu:

• ← Önceki makale: Kanal Yapılandırma: Telegram ile Başla
• → Sonraki makale: Çoklu Model Yapılandırma ve Geçiş