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:

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Tüm kanallar aynı DM ilkesi kalıbını paylaşır:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // yalnızca allowlist/open için    },  },}

Birincil modeli ve isteğe bağlı yedek modelleri 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 takma adları ve model başına ayarları saklar; bir girdi eklemek /model veya --model geçersiz kılmalarını hiçbir zaman kısıtlamaz.
• agents.defaults.modelPolicy.allow, geçersiz kılmalar ve model seçiciler için açık izin listesidir. Kesin başvuruları ve provider/* joker karakterlerini kabul eder; herhangi bir modele izin vermek için bunu atlayın veya [] kullanın.
• Model başvuruları provider/model biçimini kullanır (ör. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx, transkript/araç görüntülerinin küçültülmesini denetler (varsayılan 1200); daha düşük değerler, ekran görüntüsü ağırlıklı çalıştırmalarda genellikle görsel token kullanımını azaltır.
• Sohbette model değiştirmek için Modeller CLI'sına, kimlik doğrulama dönüşümü 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 aracılığıyla denetlenir (varsayılan "pairing"):

• "pairing": bilinmeyen gönderenler, onaylanması için tek kullanımlık bir eşleştirme kodu alır
• "allowlist": yalnızca allowFrom içindeki (veya eşleştirilmiş izin deposundaki) gönderenler
• "open": gelen tüm DM'lere izin verir (allowFrom: ["*"] gerektirir)
• "disabled": tüm DM'leri yok sayar

Gruplar için groupPolicy ("allowlist" | "open" | "disabled") ile birlikte 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 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ı odalarda mesaj aracı yolunu etkinleştirin:

{  messages: {    visibleReplies: "automatic", // her yerde mesaj aracı gönderimlerini zorunlu kılmak için "message_tool" olarak ayarlayın    groupChat: {      visibleReplies: "message_tool", // isteğe bağlı; görünür çıktı message(action=send) gerektirir      unmentionedInbound: "room_event", // bahsetme içermeyen, sürekli grup konuşmaları sessiz bağlamdır    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Meta veri bahsetmeleri: yerel @bahsetmeleri (WhatsApp dokunarak bahsetme, Telegram @bot vb.)
• Metin kalıpları: mentionPatterns içindeki güvenli düzenli ifade kalıpları
• 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 aracıları agents.entries.*.skills ile geçersiz kılın:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // github ve weather öğelerini devralır      { id: "docs", skills: ["docs-search"] }, // varsayılanların yerini alır      { id: "locked-down", skills: [] }, // Skills yok    ],  },}

• Varsayılan olarak sınırsız Skills için agents.defaults.skills öğesini atlayın.
• Varsayılanları devralmak için agents.entries.*.skills öğesini atlayın.
• Skills olmaması için agents.entries.*.skills: [] ayarlayın.
• Skills, Skills yapılandırması ve Yapılandırma Başvurusuna bakın.

Bir kanal veya hesap için otomatik sistem durumu yeniden başlatmalarını devre dışı bırakın ya da etkinleştirin:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Bir kanal veya hesap için otomatik yeniden başlatmaları denetlemek üzere channels.<provider>.healthMonitor.enabled ya da channels.<provider>.accounts.<id>.healthMonitor.enabled kullanın.
• Operasyonel hata ayıklama için Sistem Durumu Denetimleri, tüm alanlar için tam başvuruya bakın.

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

{  session: {    dmScope: "per-channel-peer",  // çok kullanıcılı kullanım için önerilir    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: ileti dizisine bağlı oturum yönlendirmesinin genel varsayılanları. /focus, /unfocus, /agents, /session idle ve /session max-age, bunu her oturum için bağlar, bağlantısını kaldırır, listeler ve ayarlar (Discord ileti dizilerini, Telegram ise konuları/konuşmaları bağlar).
• Kapsamlandırma, kimlik bağlantıları ve gönderim politikası 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ış korumalı alan ç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 kod deposundan çalışıyorsanız scripts/sandbox-setup.sh komutunu çalıştırın; npm kurulumundan çalışıyorsanız Korumalı Alan § İmajlar ve kurulum bölümündeki satır içi docker build komutuna bakın.

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

Herkese açık App Store derlemelerinde aktarıcı destekli anlık bildirimler, barındırılan OpenClaw aktarıcısını kullanır: https://ios-push-relay.openclaw.ai.

Özel aktarıcı dağıtımları, aktarıcı URL'si gateway aktarıcı URL'siyle eşleşen, bilinçli olarak ayrı tutulmuş bir iOS derleme/dağıtım yolu gerektirir. Özel bir aktarıcı derlemesi kullanıyorsanız gateway yapılandırmasında şunu ayarlayın:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // İsteğe bağlı. Varsayılan: 10000          timeoutMs: 10000,        },      },    },  },}

CLI eşdeğeri:

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

Bunun yaptığı işlemler:

• Gateway'in push.test, uyandırma dürtmeleri ve yeniden bağlantı uyandırmalarını haricî aktarıcı üzerinden göndermesini sağlar.
• Eşleştirilmiş iOS uygulamasının ilettiği, kayıt kapsamlı bir gönderim izni kullanır. Gateway'in dağıtım genelinde geçerli bir aktarıcı belirtecine ihtiyacı yoktur.
• Aktarıcı destekli her kaydı, iOS uygulamasının eşleştirildiği gateway kimliğine bağlar; böylece başka bir gateway saklanan kaydı yeniden kullanamaz.
• Yerel/elle oluşturulan iOS derlemelerinin doğrudan APNs kullanmasını sürdürür. Aktarıcı destekli gönderimler yalnızca aktarıcı üzerinden kaydolmuş resmî dağıtım derlemelerine uygulanır.
• Kayıt ve gönderim trafiğinin aynı aktarıcı dağıtımına ulaşması için iOS derlemesine gömülü aktarıcı temel URL'siyle eşleşmelidir.

Uçtan uca akış:

1. Resmî iOS uygulamasını yükleyin.
2. İsteğe bağlı: yalnızca bilinçli olarak ayrı tutulmuş özel bir aktarıcı derlemesi kullanırken gateway üzerinde gateway.push.apns.relay.baseUrl yapılandırmasını yapı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 makbuzunu kullanarak aktarıcıya kaydolur, ardından aktarıcı destekli push.apns.register yükünü eşleştirilmiş gateway'e yayımlar.
5. Gateway, aktarıcı tanıtıcısını ve gönderim iznini saklar; ardından bunları push.test, uyandırma dürtmeleri ve yeniden bağlantı uyandırmaları için kullanır.

İşletim notları:

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

Uyumluluk notu:

• OPENCLAW_APNS_RELAY_BASE_URL ve OPENCLAW_APNS_RELAY_TIMEOUT_MS, geçici ortam değişkeni geçersiz kılmaları olarak çalışmaya devam eder.
• Özel gateway aktarıcı URL'leri, iOS derlemesine gömülü aktarıcı temel URL'siyle eşleşmelidir; herkese açık App Store sürüm hattı, özel iOS aktarıcı URL'si geçersiz kılmalarını reddeder.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true, yalnızca geri döngüye yönelik bir geliştirme kaçış yolu olmaya devam eder; HTTP aktarıcı URL'lerini yapılandırmada kalıcı olarak saklamayın.

Uçtan uca akış için iOS Uygulaması, aktarıcı 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 olarak ayarlayın. Varsayılan: 30m.
• 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,    sessionRetention: "24h",  },}

• sessionRetention: tamamlanan yalıtılmış çalıştırma oturumlarını SQLite oturum satırlarından temizler (varsayılan 24h; devre dışı bırakmak için false olarak ayarlayın).
• Çalıştırma geçmişi, iş başına en yeni 2000 terminal satırını otomatik olarak tutar; kayıp satırlar 24 saatlik temizleme sürelerini korur.
• Özelliğe genel bakış 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 değerlendirin.
• Özel bir hooks.token kullanın; etkin Gateway kimlik doğrulama gizli bilgilerini (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN veya gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD) yeniden kullanmayın.
• Hook kimlik doğrulaması yalnızca üstbilgiyle yapılır (Authorization: Bearer ... veya x-openclaw-token); sorgu dizesi belirteçleri reddedilir.
• hooks.path, / olamaz; webhook girişini /hooks gibi özel bir alt yolda tutun.
• Sıkı kapsamlı hata ayıklama yapmadığınız sürece güvenli olmayan içerik atlama bayraklarını (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) devre dışı tutun.
• hooks.allowRequestSessionKey özelliğini etkinleştirirseniz çağıranın seçtiği oturum anahtarlarını sınırlamak için hooks.allowedSessionKeyPrefixes değerini de ayarlayın.
• Hook ile çalıştırılan aracılar için güçlü ve modern model katmanlarını ve sıkı bir araç politikasını tercih edin (örneğin yalnızca mesajlaşma ve mümkün olduğunda korumalı alan).

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

Ayrı çalışma alanları ve oturumları olan 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ş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: kapsayıcı nesnenin yerini alır
• Dosya dizisi: sırayla derinlemesine birleştirilir (sonraki kazanır), en fazla 10 iç içe düzey
• Eş düzey anahtarlar: eklemelerden sonra birleştirilir (eklenen değerleri geçersiz kılar)
• Göreli yollar: eklemeyi yapan dosyaya göre çözümlenir
• Yol biçimi: ekleme yolları null baytları içermemeli ve çözümlemeden önce ve sonra kesinlikle 4096 karakterden kısa olmalıdır
• OpenClaw'a ait yazma işlemleri: bir yazma işlemi yalnızca plugins: { $include: "./plugins.json5" } gibi tek dosyalı bir eklemeyle desteklenen bir üst düzey bölümü değiştirdiğinde OpenClaw, eklenen bu dosyayı günceller ve openclaw.json dosyasını olduğu gibi bırakır
• Desteklenmeyen doğrudan yazma: kök eklemeler, ekleme dizileri ve eş düzey geçersiz kılmaları olan eklemeler, yapılandırmayı düzleştirmek yerine OpenClaw'a ait yazma işlemlerinde güvenli biçimde başarısız olur
• Sınırlandırma: $include yolları, openclaw.json dosyasını içeren dizinin altında çözümlenmelidir. Bir dizin ağacını makineler veya kullanıcılar arasında paylaşmak için OPENCLAW_INCLUDE_ROOTS değerini, eklemelerin başvurabileceği ek dizinlerden oluşan bir yol listesine (POSIX'te :, Windows'ta ;) ayarlayın. Sembolik bağlantılar çözümlenir ve yeniden denetlenir; bu nedenle sözcüksel olarak bir yapılandırma dizininde bulunan ancak gerçek hedefi izin verilen tüm köklerin dışına çıkan bir yol yine de reddedilir.
• Hata işleme: eksik dosyalar, ayrıştırma hataları, döngüsel eklemeler, geçersiz yol biçimi ve aşırı uzunluk için açık hatalar