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 politikası kalıbını 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 görevi görür; provider/* girdileri, dinamik model keşfini kullanmaya devam ederken /model, /models ve model seçicileri seçili sağlayıcılarla sınırlar.
• 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 iletilmediği sürece reddedilir.
• Model başvuruları provider/model biçimini kullanır (ör. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx, transkript/araç görsel küçültmesini denetler (varsayılan 1200); daha düşük değerler, ekran görüntüsü yoğun çalıştırmalarda genellikle vision-token kullanımını azaltır.
• Sohbette model değiştirme için Modeller CLI, kimlik doğrulama rotasyonu ve yedek davranışı için Model Yük Devretme 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 kullanımlık bir eşleştirme kodu alır
• "allowlist": yalnızca allowFrom içindeki gönderenler (veya eşlenmiş izin deposu)
• "open": gelen tüm 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. Tetikleme kalıplarını aracı başına yapılandırın. Normal grup/kanal yanıtları otomatik olarak gönderilir; aracının ne zaman konuşacağına karar vermesi gereken paylaşımlı odalar için message-tool yoluna katılın:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  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 kalıpları: mentionPatterns içinde güvenli regex kalıpları
• Görünür yanıtlar: messages.visibleReplies genel olarak message-tool gönderimlerini gerektirebilir; messages.groupChat.visibleReplies gruplar/kanallar için bunu geçersiz kılar.
• Görünür yanıt modları, kanal başına geçersiz kılmalar ve kendiyle sohbet modu için tam başvuruya bakın.

Paylaşılan bir temel için agents.defaults.skills kullanın, ardından belirli aracıları 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 alanını atlayın.
• Varsayılanları devralmak için agents.list[].skills alanını atlayın.
• Hiç Skills olmaması için agents.list[].skills: [] ayarlayın.
• Skills, Skills yapılandırması ve Yapılandırma Başvurusu sayfalarına bakın.

Eski görünen kanalların Gateway tarafından ne kadar agresif yeniden başlatılacağını denetleyin:

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

• Sağlık izleyici 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 sayfasına ve tüm alanlar için tam başvuruya bakın.

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

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Varsayılan 15000 milisaniyedir.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS, tek seferlik hizmet veya shell geçersiz kılmaları için hâlâ önceliklidir.
• Önce başlatma/event-loop duraksamalarını düzeltmeyi tercih edin; bu düğme 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.

Aracı oturumlarını yalıtılmış sandbox çalışma zamanları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 üzerinden scripts/sandbox-setup.sh çalıştırın veya npm kurulumundan Sandboxing § İmajlar ve kurulum içindeki satır içi docker build komutuna bakın.

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

Herkese açık App Store derlemeleri için relay destekli push, barındırılan OpenClaw relay'ini kullanır: https://ios-push-relay.openclaw.ai.

Özel relay dağıtımları, relay URL'si Gateway relay URL'siyle eşleşen, bilerek ayrı tutulmuş bir iOS derleme/dağıtım yolu gerektirir. Özel bir relay derlemesi kullanıyorsanız bunu Gateway yapılandırmasında ayarlayın:

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

CLI karşılığı:

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

Bunun yaptığı:

• Gateway'in push.test, uyandırma dürtmeleri ve yeniden bağlanma uyandırmalarını harici relay üzerinden göndermesine izin verir.
• Eşleştirilmiş iOS uygulaması tarafından iletilen, kayıt kapsamlı bir gönderme izni kullanır. Gateway, dağıtım genelinde geçerli bir relay token'ına ihtiyaç duymaz.
• Her relay destekli kaydı, iOS uygulamasının eşleştirildiği Gateway kimliğine bağlar; böylece başka bir Gateway depolanan 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.
• iOS derlemesine gömülü 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. Resmi iOS uygulamasını yükleyin.
2. İsteğe bağlı: gateway.push.apns.relay.baseUrl değerini yalnızca bilerek ayrı tutulmuş özel bir relay derlemesi kullanırken Gateway üzerinde 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 makbuzuyla relay'e kaydolur, ardından relay destekli push.apns.register yükünü eşleştirilmiş Gateway'e yayımlar.
5. Gateway relay handle'ını ve gönderme iznini depolar, 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, uygulamanın 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 hâlâ çalışır.
• Özel Gateway relay URL'leri, iOS derlemesine gömülü relay temel URL'siyle eşleşmelidir. Herkese açık App Store yayın hattı özel iOS relay URL geçersiz kılmalarını reddeder.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true, yalnızca loopback geliştirme kaçış yolu olarak kalır; HTTP relay URL'lerini yapılandırmada kalıcı hale getirmeyin.

Uçtan uca akış için iOS Uygulaması bölümüne, 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: 8, // default; 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 dosyasından budar (varsayılan 24h; devre dışı bırakmak için false ayarlayın).
• runLog: iş başına saklanan Cron çalıştırma geçmişi satırlarını budar. maxBytes, eski dosya destekli çalıştırma günlükleri için kabul edilmeye devam eder.
• Ö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.
• Ayrı bir hooks.token kullanın; etkin Gateway kimlik doğrulama sırlarını (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN veya gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD) yeniden kullanmayın.
• Hook kimlik doğrulaması yalnızca header üzerindendir (Authorization: Bearer ... veya x-openclaw-token); query-string token'ları reddedilir.
• hooks.path, / olamaz; Webhook girişini /hooks gibi ayrılmış bir alt yolda tutun.
• Sıkı kapsamlı hata ayıklama yapmıyorsanız güvenli olmayan içerik bypass bayraklarını devre dışı tutun (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent).
• hooks.allowRequestSessionKey etkinleştirirseniz, çağıranın seçtiği oturum anahtarlarını sınırlamak için hooks.allowedSessionKeyPrefixes değerini de ayarlayın.
• Hook güdümlü aracılar için güçlü modern model katmanlarını ve katı araç ilkesini tercih edin (örneğin mümkün olduğunda yalnızca mesajlaşma ve sandboxing).

Tüm eşleme seçenekleri ve Gmail entegrasyonu için tam başvuruya bakın.

Ayrı çalışma alanları ve oturumlarla birden çok yalıtılmış aracı ç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 aracı başına erişim profilleri için Çok Aracılı ve tam başvuruya 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 yerini alır
• 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
• Yol biçimi: include yolları null byte içermemeli ve çözümlemeden önce ve sonra 4096 karakterden kesinlikle kısa olmalıdır
• OpenClaw'a ait yazmalar: bir yazma yalnızca plugins: { $include: "./plugins.json5" } gibi tek dosyalı bir include tarafından desteklenen tek bir üst düzey bölümü değiştirdiğinde, OpenClaw bu dahil edilen dosyayı günceller ve openclaw.json dosyasını olduğu gibi bırakır
• Desteklenmeyen write-through: kök include'lar, include dizileri ve kardeş geçersiz kılmaları olan include'lar, yapılandırmayı düzleştirmek yerine OpenClaw'a ait yazmalar için fail closed olur
• Sınırlama: $include yolları openclaw.json dosyasını tutan dizinin altında çözümlenmelidir. Bir ağacı makineler veya kullanıcılar arasında 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 denetlenir; bu yüzden sözcüksel olarak bir yapılandırma dizininde bulunan ancak gerçek hedefi izin verilen her kökten kaçan bir yol yine de reddedilir.
• Hata işleme: eksik dosyalar, ayrıştırma hataları, döngüsel include'lar, geçersiz yol biçimi ve aşırı uzunluk için net hatalar