~/.openclaw/openclaw.json konumundan isteğe bağlı bir yapılandırması okur.
Etkin yapılandırma yolu normal bir dosya olmalıdır. Symlink kullanılan openclaw.json
düzenleri, OpenClaw tarafından sahip olunan yazmalar için desteklenmez; atomik yazma,
symlink’i korumak yerine yolu değiştirebilir. Yapılandırmayı varsayılan durum
dizininin dışında tutuyorsanız, OPENCLAW_CONFIG_PATH değerini doğrudan gerçek dosyaya yönlendirin.
Dosya yoksa OpenClaw güvenli varsayılanları kullanır. Yapılandırma eklemenin yaygın nedenleri:
- Kanalları bağlamak ve bota kimlerin mesaj gönderebileceğini denetlemek
- Modelleri, araçları, sandbox kullanımını veya otomasyonu (cron, hook’lar) ayarlamak
- Oturumları, medyayı, ağı veya UI’ı ayarlamak
config.schema.lookup kullanmalıdır. Bu sayfayı görev odaklı
rehberlik için, Yapılandırma başvurusu sayfasını ise daha geniş
alan haritası ve varsayılanlar için kullanın.
Minimal yapılandırma
Yapılandırmayı düzenleme
- Etkileşimli sihirbaz
- CLI (tek satırlık komutlar)
- Denetim UI'ı
- Doğrudan düzenleme
Katı doğrulama
openclaw config schema, Denetim UI’ı ve doğrulama tarafından kullanılan kanonik JSON Schema’yı
yazdırır. config.schema.lookup, ayrıntılı inceleme araçları için tek bir yol kapsamlı
düğümü ve alt özetleri getirir. Alan title/description dokümantasyon meta verileri
iç içe nesneler, joker karakter (*), dizi öğesi ([]) ve anyOf/
oneOf/allOf dalları boyunca taşınır. Çalışma zamanı Plugin ve kanal şemaları,
manifest kayıt defteri yüklendiğinde birleştirilir.
Doğrulama başarısız olduğunda:
- Gateway başlatılmaz
- Yalnızca tanılama komutları çalışır (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Kesin sorunları görmek için
openclaw doctorçalıştırın - Onarımları uygulamak için
openclaw doctor --fix(veya--yes) çalıştırın
openclaw.json
doğrulamadan geçemezse (Plugin’e yerel doğrulama dahil), Gateway başlatması başarısız olur veya
yeniden yükleme atlanır ve geçerli çalışma zamanı son kabul edilen yapılandırmayı korur.
Öneklenmiş/üzerine yazılmış yapılandırmayı onarmak veya son-bilinen-iyi kopyayı geri yüklemek için
openclaw doctor --fix (veya --yes) çalıştırın. Aday *** gibi
maskelenmiş gizli yer tutucular içerdiğinde son-bilinen-iyi sürümüne yükseltme atlanır.
Yaygın görevler
Bir kanal kurma (WhatsApp, Telegram, Discord vb.)
Bir kanal kurma (WhatsApp, Telegram, Discord vb.)
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
Modelleri seçme ve yapılandırma
Modelleri seçme ve yapılandırma
agents.defaults.modelsmodel kataloğunu tanımlar ve/modeliçin izin listesi görevi görür;provider/*girdileri, dinamik model keşfini kullanmaya devam ederken/model,/modelsve 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 --mergekullanın. Girdileri kaldıracak düz değiştirmeler,--replaceiletilmediği sürece reddedilir. - Model başvuruları
provider/modelbiçimini kullanır (ör.anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPx, transkript/araç görsel küçültmesini denetler (varsayılan1200); 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.
Bota kimlerin mesaj gönderebileceğini denetleme
Bota kimlerin mesaj gönderebileceğini denetleme
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ızcaallowFromiç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
groupPolicy + groupAllowFrom veya kanala özgü izin listelerini kullanın.Kanal başına ayrıntılar için tam başvuruya bakın.Grup sohbeti bahsetme kapısını ayarlama
Grup sohbeti bahsetme kapısını ayarlama
- Meta veri bahsetmeleri: yerel @-bahsetmeler (WhatsApp dokunarak bahsetme, Telegram @bot vb.)
- Metin kalıpları:
mentionPatternsiçinde güvenli regex kalıpları - Görünür yanıtlar:
messages.visibleRepliesgenel olarak message-tool gönderimlerini gerektirebilir;messages.groupChat.visibleRepliesgruplar/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.
Aracı başına Skills kısıtlama
Aracı başına Skills kısıtlama
agents.defaults.skills kullanın, ardından belirli
aracıları agents.list[].skills ile geçersiz kılın:- Varsayılan olarak kısıtlanmamış Skills için
agents.defaults.skillsalanını atlayın. - Varsayılanları devralmak için
agents.list[].skillsalanı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.
Gateway kanal sağlık izlemesini ayarlama
Gateway kanal sağlık izlemesini ayarlama
- Sağlık izleyici yeniden başlatmalarını genel olarak devre dışı bırakmak için
gateway.channelHealthCheckMinutes: 0ayarlayı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.enabledveyachannels.<provider>.accounts.<id>.healthMonitor.enabledkullanın. - Operasyonel hata ayıklama için Sağlık Denetimleri sayfasına ve tüm alanlar için tam başvuruya bakın.
Gateway WebSocket el sıkışma zaman aşımını ayarlama
Gateway WebSocket el sıkışma zaman aşımını ayarlama
- Varsayılan
15000milisaniyedir. 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ı ve sıfırlamaları yapılandırma
Oturumları ve sıfırlamaları yapılandırma
dmScope:main(paylaşılan) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: iş parçacığına bağlı oturum yönlendirmesi için genel varsayılanlar (Discord/focus,/unfocus,/agents,/session idleve/session max-agedestekler).- 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.
Sandboxing'i etkinleştir
Sandboxing'i etkinleştir
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.Resmi iOS derlemeleri için relay destekli push'u etkinleştir
Resmi iOS derlemeleri için relay destekli push'u etkinleştir
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’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.
- Resmi iOS uygulamasını yükleyin.
- İsteğe bağlı:
gateway.push.apns.relay.baseUrldeğerini yalnızca bilerek ayrı tutulmuş özel bir relay derlemesi kullanırken Gateway üzerinde yapılandırın. - iOS uygulamasını Gateway ile eşleştirin ve hem node hem de operatör oturumlarının bağlanmasına izin verin.
- iOS uygulaması Gateway kimliğini alır, App Attest ve uygulama makbuzuyla relay’e kaydolur, ardından relay destekli
push.apns.registeryükünü eşleştirilmiş Gateway’e yayımlar. - 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.
- 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.
OPENCLAW_APNS_RELAY_BASE_URLveOPENCLAW_APNS_RELAY_TIMEOUT_MSgeç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.
Heartbeat'i ayarla (periyodik yoklamalar)
Heartbeat'i ayarla (periyodik yoklamalar)
every: süre dizesi (30m,2h). Devre dışı bırakmak için0mayarlayın.target:last|none|<channel-id>(örneğindiscord,matrix,telegramveyawhatsapp)directPolicy: DM tarzı Heartbeat hedefleri içinallow(varsayılan) veyablock- Tam kılavuz için Heartbeat bölümüne bakın.
Cron işlerini yapılandır
Cron işlerini yapılandır
sessionRetention: tamamlanmış yalıtılmış çalıştırma oturumlarınısessions.jsondosyasından budar (varsayılan24h; devre dışı bırakmak içinfalseayarlayı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.
Webhook'ları ayarla (hooks)
Webhook'ları ayarla (hooks)
- Tüm hook/Webhook yük içeriğini güvenilmeyen girdi olarak ele alın.
- Ayrı bir
hooks.tokenkullanın; etkin Gateway kimlik doğrulama sırlarını (gateway.auth.token/OPENCLAW_GATEWAY_TOKENveyagateway.auth.password/OPENCLAW_GATEWAY_PASSWORD) yeniden kullanmayın. - Hook kimlik doğrulaması yalnızca header üzerindendir (
Authorization: Bearer ...veyax-openclaw-token); query-string token’ları reddedilir. hooks.path,/olamaz; Webhook girişini/hooksgibi 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.allowRequestSessionKeyetkinleştirirseniz, çağıranın seçtiği oturum anahtarlarını sınırlamak içinhooks.allowedSessionKeyPrefixesdeğ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).
Çok aracılı yönlendirmeyi yapılandır
Çok aracılı yönlendirmeyi yapılandır
Yapılandırmayı birden çok dosyaya böl ($include)
Yapılandırmayı birden çok dosyaya böl ($include)
$include kullanın:- 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 veopenclaw.jsondosyası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:
$includeyollarıopenclaw.jsondosyasını tutan dizinin altında çözümlenmelidir. Bir ağacı makineler veya kullanıcılar arasında paylaşmak içinOPENCLAW_INCLUDE_ROOTSdeğ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
Yapılandırma hot reload
Gateway,~/.openclaw/openclaw.json dosyasını izler ve değişiklikleri otomatik olarak uygular - çoğu ayar için manuel yeniden başlatma gerekmez.
Doğrudan dosya düzenlemeleri doğrulanana kadar güvenilmeyen kabul edilir. İzleyici, editör geçici yazma/yeniden adlandırma hareketliliğinin durulmasını bekler, son dosyayı okur ve geçersiz harici düzenlemeleri openclaw.json dosyasını yeniden yazmadan reddeder. OpenClaw’a ait yapılandırma yazmaları, yazmadan önce aynı şema geçidini kullanır; gateway.mode değerini düşürmek veya dosyayı yarıdan fazla küçültmek gibi yıkıcı ezmeler reddedilir ve inceleme için .rejected.* olarak kaydedilir.
config reload skipped (invalid config) görürseniz veya başlangıç Invalid config bildirirse yapılandırmayı inceleyin, openclaw config validate çalıştırın, ardından onarım için openclaw doctor --fix çalıştırın. Kontrol listesi için Gateway sorun giderme bölümüne bakın.
Yeniden yükleme modları
| Mod | Davranış |
|---|---|
hybrid (varsayılan) | Güvenli değişiklikleri anında hot-apply eder. Kritik olanlar için otomatik olarak yeniden başlatır. |
hot | Yalnızca güvenli değişiklikleri hot-apply eder. Yeniden başlatma gerektiğinde uyarı günlüğe yazar - bunu siz halledersiniz. |
restart | Güvenli olsun veya olmasın herhangi bir yapılandırma değişikliğinde Gateway’i yeniden başlatır. |
off | Dosya izlemeyi devre dışı bırakır. Değişiklikler bir sonraki manuel yeniden başlatmada etkili olur. |
Neler hot-apply edilir, neler yeniden başlatma gerektirir
Çoğu alan kesinti olmadan hot-apply edilir.hybrid modunda, yeniden başlatma gerektiren değişiklikler otomatik olarak işlenir.
| Kategori | Alanlar | Yeniden başlatma gerekli mi? |
|---|---|---|
| Kanallar | channels.*, web (WhatsApp) - tüm yerleşik ve plugin kanalları | Hayır |
| Aracı ve modeller | agent, agents, models, routing | Hayır |
| Otomasyon | hooks, cron, agent.heartbeat | Hayır |
| Oturumlar ve mesajlar | session, messages | Hayır |
| Araçlar ve medya | tools, browser, skills, mcp, audio, talk | Hayır |
| UI ve çeşitli | ui, logging, identity, bindings | Hayır |
| Gateway sunucusu | gateway.* (port, bind, auth, tailscale, TLS, HTTP) | Evet |
| Altyapı | discovery, plugins | Evet |
gateway.reload ve gateway.remote istisnadır - bunları değiştirmek yeniden başlatmayı tetiklemez.Yeniden yükleme planlaması
$include üzerinden başvurulan bir kaynak dosyayı düzenlediğinizde OpenClaw,
yeniden yüklemeyi düzleştirilmiş bellek içi görünümden değil, kaynakta yazılmış
yerleşimden planlar. Bu, tek bir üst düzey bölüm
plugins: { $include: "./plugins.json5" } gibi kendi dahil edilen dosyasında
yer alsa bile hot-reload kararlarını (sıcak uygulama ve yeniden başlatma)
öngörülebilir tutar. Kaynak yerleşim belirsizse yeniden yükleme planlaması
güvenli tarafta kalarak başarısız olur.
Config RPC (programatik güncellemeler)
Gateway API üzerinden config yazan araçlar için şu akışı tercih edin:- Bir alt ağacı incelemek için
config.schema.lookup(sığ şema düğümü + alt özetler) - Geçerli anlık görüntüyü ve
hashdeğerini almak içinconfig.get - Kısmi güncellemeler için
config.patch(JSON merge patch: nesneler birleştirilir,nullsiler, diziler yalnızca girdiler kaldırılacaksareplacePathsile açıkça onaylandığında değiştirilir) - Yalnızca config dosyasının tamamını değiştirmeyi amaçladığınızda
config.apply - Açık self-update ve yeniden başlatma için
update.run; yeniden başlatma sonrası oturum bir takip turu çalıştırmalıysacontinuationMessageekleyin - En son güncelleme yeniden başlatma sentinel değerini incelemek ve yeniden
başlatmadan sonra çalışan sürümü doğrulamak için
update.status
config.schema.lookup kullanmalıdır. Daha geniş config haritasına, varsayılanlara
veya özel alt sistem referanslarına bağlantılara ihtiyaç duyduklarında
Yapılandırma referansı kullanın.
config.apply, config.patch, update.run)
deviceId+clientIp başına 60 saniyede 3 istekle sınırlandırılır. Yeniden
başlatma istekleri birleştirilir ve ardından yeniden başlatma döngüleri arasında
30 saniyelik bekleme süresi uygular. update.status salt okunurdur ancak
yönetici kapsamındadır, çünkü yeniden başlatma sentinel değeri güncelleme adımı
özetlerini ve komut çıktısı sonlarını içerebilir.config.apply hem de config.patch raw, baseHash, sessionKey,
note ve restartDelayMs kabul eder. Bir config zaten varsa her iki yöntem için
de baseHash gereklidir.
config.patch ayrıca dizi değişiminin kasıtlı olduğu config yollarından oluşan
bir dizi olan replacePaths kabul eder. Bir patch, mevcut bir diziyi daha az
girdiyle değiştirecek veya silecekse Gateway, tam olarak o yol replacePaths
içinde görünmediği sürece yazmayı reddeder; dizi girdileri altındaki iç içe
diziler agents.list[].skills gibi [] kullanır. Bu, kırpılmış config.get
anlık görüntülerinin yönlendirme veya izin listesi dizilerini sessizce bozmasını
önler. Tam config dosyasını değiştirmeyi amaçladığınızda config.apply kullanın.
Ortam değişkenleri
OpenClaw env vars değerlerini üst süreçten ve ayrıca şunlardan okur:- Geçerli çalışma dizininden
.env(varsa) ~/.openclaw/.env(genel fallback)
Shell env import (optional)
Shell env import (optional)
OPENCLAW_LOAD_SHELL_ENV=1Env var substitution in config values
Env var substitution in config values
${VAR_NAME} ile başvurun:- Yalnızca büyük harfli adlar eşleşir:
[A-Z_][A-Z0-9_]* - Eksik/boş değişkenler yükleme sırasında hata fırlatır
- Literal çıktı için
$${VAR}ile escape edin $includedosyalarının içinde çalışır- Satır içi ikame:
"${BASE}/v1"→"https://api.example.com/v1"
Secret refs (env, file, exec)
Secret refs (env, file, exec)
env/file/exec için secrets.providers dahil)
Gizli Bilgi Yönetimi içinde yer alır.
Desteklenen kimlik bilgisi yolları SecretRef Kimlik Bilgisi Yüzeyi içinde listelenmiştir.Tam referans
Eksiksiz alan alan başvurusu için Yapılandırma Referansı bölümüne bakın.İlgili: Yapılandırma Örnekleri · Yapılandırma Referansı · Doctor