Yapılandırma

Her kanalın channels.<provider> altında kendi yapılandırma bölümü vardır. Kurulum adımları için ilgili kanal sayfasına bakın:

• 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

Tüm kanallar aynı DM ilkesi desenini paylaşır:

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

Birincil modeli ve isteğe bağlı yedekleri ayarlayın:

{
  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, model kataloğunu tanımlar ve /model için izin listesi olarak davranır.
• Mevcut modelleri kaldırmadan izin listesi girdileri eklemek için openclaw config set agents.defaults.models '<json>' --strict-json --merge kullanın. Girdileri kaldıracak düz değiştirmeler, --replace geçmediğiniz sürece reddedilir.
• Model başvuruları provider/model biçimini kullanır (ör. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx, transkript/araç görüntüsü küçültmeyi denetler (varsayılan 1200); daha düşük değerler genellikle ekran görüntüsü yoğun çalışmalarda vision-token kullanımını azaltır.
• Sohbette model değiştirmek için Models CLI sayfasına, kimlik doğrulama rotasyonu ve yedek davranışı için Model Failover sayfasına bakın.
• Özel/kendi barındırdığınız sağlayıcılar için başvurudaki Özel sağlayıcılar bölümüne bakın.

DM erişimi kanal başına dmPolicy ile denetlenir:

• "pairing" (varsayılan): bilinmeyen gönderenler onay için tek seferlik bir eşleştirme kodu alır
• "allowlist": yalnızca allowFrom içindeki gönderenler (veya eşleştirilmiş izin deposu)
• "open": tüm gelen DM'lere izin ver (allowFrom: ["*"] gerektirir)
• "disabled": tüm DM'leri yok say

Gruplar için groupPolicy + groupAllowFrom veya kanala özgü izin listelerini kullanın.

Kanal başına ayrıntılar için tam başvuruya bakın.

Grup mesajları varsayılan olarak bahsetme gerektirir. Tetikleyici desenlerini ajan başına yapılandırın ve eski otomatik son yanıtları özellikle istemiyorsanız görünür oda yanıtlarını varsayılan mesaj aracı yolunda tutun:

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

• Meta veri bahsetmeleri: yerel @-bahsetmeler (WhatsApp dokunarak bahsetme, Telegram @bot vb.)
• Metin desenleri: mentionPatterns içinde güvenli regex desenleri
• Görünür yanıtlar: messages.visibleReplies, mesaj aracı gönderimlerini genel olarak zorunlu kılabilir; messages.groupChat.visibleReplies bunu gruplar/kanallar için geçersiz kılar.
• Görünür yanıt modları, kanal başına geçersiz kılmalar ve kendi kendine sohbet modu için tam başvuruya bakın.

Paylaşılan bir temel için agents.defaults.skills kullanın, ardından belirli ajanları agents.list[].skills ile geçersiz kılın:

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• Varsayılan olarak kısıtlanmamış Skills için agents.defaults.skills öğesini atlayın.
• Varsayılanları devralmak için agents.list[].skills öğesini atlayın.
• Skills olmaması için agents.list[].skills: [] ayarlayın.
• Skills, Skills yapılandırması ve Yapılandırma Başvurusu bölümlerine bakın.

Gateway'in eski görünen kanalları ne kadar agresif biçimde yeniden başlatacağını denetleyin:

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

• Sağlık izleme yeniden başlatmalarını genel olarak devre dışı bırakmak için gateway.channelHealthCheckMinutes: 0 ayarlayın.
• channelStaleEventThresholdMinutes, denetim aralığından büyük veya ona eşit olmalıdır.
• Genel izleyiciyi devre dışı bırakmadan tek bir kanal veya hesap için otomatik yeniden başlatmaları devre dışı bırakmak üzere channels.<provider>.healthMonitor.enabled veya channels.<provider>.accounts.<id>.healthMonitor.enabled kullanın.
• Operasyonel hata ayıklama için Sağlık Denetimleri, tüm alanlar için tam başvuru bölümüne bakın.

Yüklü veya düşük güçlü ana makinelerde yerel istemcilere kimlik doğrulama öncesi WebSocket el sıkışmasını tamamlamaları için daha fazla süre verin:

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Varsayılan değer 15000 milisaniyedir.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS, tek seferlik servis veya kabuk geçersiz kılmaları için hâlâ önceliklidir.
• Önce başlatma/olay döngüsü duraklamalarını düzeltmeyi tercih edin; bu ayar, sağlıklı ancak ısınma sırasında yavaş olan ana makineler içindir.

Oturumlar konuşma sürekliliğini ve yalıtımı denetler:

{
  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 (paylaşılan) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: iş parçacığına bağlı oturum yönlendirmesi için genel varsayılanlar (Discord /focus, /unfocus, /agents, /session idle ve /session max-age destekler).
• Kapsam belirleme, kimlik bağlantıları ve gönderme ilkesi için Oturum Yönetimi bölümüne bakın.
• Tüm alanlar için tam başvuruya bakın.

Agent oturumlarını yalıtılmış sandbox çalışma ortamlarında çalıştırın:

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

Önce imajı oluşturun: kaynak checkout’tan scripts/sandbox-setup.sh çalıştırın veya npm kurulumunda Sandboxing § İmajlar ve kurulum içindeki satır içi docker build komutuna bakın.

Tam kılavuz için Sandboxing, tüm seçenekler için tam başvuru bölümüne bakın.

Relay destekli push openclaw.json içinde yapılandırılır.

Gateway yapılandırmasında bunu ayarlayın:

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

CLI eşdeğeri:

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

Bunun yaptığı:

• Gateway’in dış relay üzerinden push.test, uyandırma dürtmeleri ve yeniden bağlanma uyandırmaları göndermesini sağlar.
• Eşleştirilen iOS uygulaması tarafından iletilen, kayıt kapsamlı bir gönderme izni kullanır. Gateway’in dağıtım genelinde bir relay token’ına ihtiyacı yoktur.
• Her relay destekli kaydı, iOS uygulamasının eşleştiği Gateway kimliğine bağlar; böylece başka bir Gateway saklanan kaydı yeniden kullanamaz.
• Yerel/manuel iOS derlemelerini doğrudan APNs üzerinde tutar. Relay destekli gönderimler yalnızca relay üzerinden kaydolmuş resmi dağıtılmış derlemeler için geçerlidir.
• Resmi/TestFlight iOS derlemesine gömülen relay temel URL’siyle eşleşmelidir; böylece kayıt ve gönderme trafiği aynı relay dağıtımına ulaşır.

Uçtan uca akış:

1. Aynı relay temel URL’siyle derlenmiş bir resmi/TestFlight iOS derlemesi kurun.
2. Gateway üzerinde gateway.push.apns.relay.baseUrl yapılandırın.
3. iOS uygulamasını Gateway ile eşleştirin ve hem node hem de operatör oturumlarının bağlanmasına izin verin.
4. iOS uygulaması Gateway kimliğini alır, App Attest ve uygulama makbuzu ile relay’e kaydolur, ardından relay destekli push.apns.register yükünü eşleştirilen Gateway’e yayımlar.
5. Gateway relay tanıtıcısını ve gönderme iznini saklar, ardından bunları push.test, uyandırma dürtmeleri ve yeniden bağlanma uyandırmaları için kullanır.

Operasyonel notlar:

• iOS uygulamasını farklı bir Gateway’e geçirirseniz, o Gateway’e bağlı yeni bir relay kaydı yayımlayabilmesi için uygulamayı yeniden bağlayın.
• Farklı bir relay dağıtımını işaret eden yeni bir iOS derlemesi yayımlarsanız, uygulama eski relay kaynağını yeniden kullanmak yerine önbelleğe alınmış relay kaydını yeniler.

Uyumluluk notu:

• OPENCLAW_APNS_RELAY_BASE_URL ve OPENCLAW_APNS_RELAY_TIMEOUT_MS geçici env geçersiz kılmaları olarak çalışmaya devam eder.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true yalnızca loopback’e yönelik bir geliştirme kaçış yoludur; HTTP relay URL’lerini yapılandırmada kalıcı hale getirmeyin.

Uçtan uca akış için iOS Uygulaması, relay güvenlik modeli için Kimlik doğrulama ve güven akışı bölümüne bakın.

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

• every: süre dizesi (30m, 2h). Devre dışı bırakmak için 0m ayarlayın.
• target: last | none | <channel-id> (örneğin discord, matrix, telegram veya whatsapp)
• directPolicy: DM tarzı Heartbeat hedefleri için allow (varsayılan) veya block
• Tam kılavuz için Heartbeat bölümüne bakın.

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

• sessionRetention: tamamlanmış yalıtılmış çalıştırma oturumlarını sessions.json içinden temizler (varsayılan 24h; devre dışı bırakmak için false ayarlayın).
• runLog: cron/runs/<jobId>.jsonl dosyasını boyuta ve korunan satırlara göre temizler.
• Özellik özeti ve CLI örnekleri için Cron işleri bölümüne bakın.

Gateway üzerinde HTTP Webhook uç noktalarını etkinleştirin:

{
  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,
      },
    ],
  },
}

Güvenlik notu:

• Tüm hook/Webhook yük içeriğini güvenilmeyen girdi olarak ele alın.
• Özel bir hooks.token kullanın; paylaşılan Gateway token’ını yeniden kullanmayın.
• Hook kimlik doğrulaması yalnızca header tabanlıdır (Authorization: Bearer ... veya x-openclaw-token); query-string token’ları reddedilir.
• hooks.path / olamaz; Webhook girişini /hooks gibi özel bir alt yolda tutun.
• Sıkı kapsamlı hata ayıklama yapmadıkça güvenli olmayan içerik atlama bayraklarını (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) devre dışı tutun.
• hooks.allowRequestSessionKey etkinleştirirseniz, çağıranın seçtiği oturum anahtarlarını sınırlamak için hooks.allowedSessionKeyPrefixes de ayarlayın.
• Hook tarafından yönlendirilen agent’lar için güçlü modern model katmanlarını ve sıkı araç politikasını tercih edin (örneğin yalnızca mesajlaşma ve mümkün olduğunda sandboxing).

Tüm eşleme seçenekleri ve Gmail entegrasyonu için tam başvuru bölümüne bakın.

Ayrı çalışma alanları ve oturumlarla birden fazla yalıtılmış agent çalıştırın:

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

Bağlama kuralları ve agent başına erişim profilleri için Çoklu Agent ve tam başvuru bölümlerine bakın.

Büyük yapılandırmaları düzenlemek için $include kullanın:

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

• Tek dosya: kapsayan nesnenin yerine geçer
• Dosya dizisi: sırayla derin birleştirilir (sonraki kazanır)
• Kardeş anahtarlar: include’lardan sonra birleştirilir (dahil edilen değerleri geçersiz kılar)
• İç içe include’lar: 10 seviye derinliğe kadar desteklenir
• Göreli yollar: include eden dosyaya göre çözümlenir
• OpenClaw-owned yazmalar: bir yazma yalnızca plugins: { $include: "./plugins.json5" } gibi tek dosya include ile desteklenen tek bir üst seviye bölümü değiştirdiğinde, OpenClaw dahil edilen dosyayı günceller ve openclaw.json dosyasını olduğu gibi bırakır
• Desteklenmeyen write-through: root include’lar, include dizileri ve kardeş geçersiz kılmalara sahip include’lar, yapılandırmayı düzleştirmek yerine OpenClaw-owned yazmalar için kapalı hata verir
• Sınırlama: $include yolları openclaw.json dosyasını tutan dizinin altında çözümlenmelidir. Makineler veya kullanıcılar arasında bir ağaç paylaşmak için OPENCLAW_INCLUDE_ROOTS değerini include’ların başvurabileceği ek dizinlerden oluşan bir yol listesine (POSIX’te :, Windows’ta ;) ayarlayın. Symlink’ler çözümlenir ve yeniden kontrol edilir; bu nedenle sözdizimsel olarak bir yapılandırma dizininde bulunan ama gerçek hedefi izin verilen her root’un dışına çıkan bir yol yine de reddedilir.
• Hata işleme: eksik dosyalar, ayrıştırma hataları ve döngüsel include’lar için açık hatalar