/new, /reset, /stop gibi komutlar, oturum Compaction’ı, Gateway yaşam döngüsü ve mesaj akışı. Dizinlerden keşfedilir ve openclaw hooks ile yönetilirler. Gateway, dahili Hook’ları yalnızca Hook’ları etkinleştirdikten veya en az bir Hook girdisi, Hook paketi, eski işleyici ya da ek Hook dizini yapılandırdıktan sonra yükler.
OpenClaw’da iki tür Hook vardır:
- Dahili Hook’lar (bu sayfa): agent olayları tetiklendiğinde Gateway içinde çalışır.
- Webhook’lar: diğer sistemlerin OpenClaw’da iş tetiklemesini sağlayan harici HTTP uç noktalarıdır. Bkz. Webhook’lar.
openclaw hooks list, hem bağımsız Hook’ları hem de plugin tarafından yönetilen Hook’ları (plugin:<id> olarak gösterilir) görüntüler.
Doğru yüzeyi seçme
OpenClaw, birbirine benzeyen ancak farklı sorunları çözen çeşitli genişletme yüzeylerine sahiptir:
Küçük ve kurulu bir entegrasyon gibi davranan otomasyon istediğinizde dahili Hook’ları kullanın. Çalışma zamanı yaşam döngüsü denetimine ihtiyaç duyduğunuzda türü belirlenmiş plugin Hook’larını kullanın.
Hızlı başlangıç
Olay türleri
Hook’lar bu tablodaki belirli bir anahtara veya o ailedeki her eylemi almak için yalnızca aile adına (command, session, agent, gateway, message)
abone olur. OpenClaw çekirdeği başka hiçbir şey yayınlamaz; bu nedenle diğer
adlar neredeyse her zaman Hook’un sessizce etkisiz kalmasına neden olan yazım
hatalarıdır (yalnızca özel olay yayınlayan bir plugin bunu tetikleyebilir).
Hook yükleyici bu tür adlar için bir uyarıyı günlüğe kaydeder (örneğin
command:nwe) ve openclaw hooks info <name> bunları işaretler; dolayısıyla hiç
çalışmayan bir Hook’un nedeni belirlenebilir.
Hook yazma
Hook yapısı
Her Hook, iki dosya içeren bir dizindir:handler.ts, handler.js, index.ts veya index.js olabilir.
HOOK.md biçimi
metadata.openclaw):
İşleyici uygulaması
type, action, sessionKey, timestamp, messages ve context (olaya özgü veriler). Agent ve araç Hook’ları için türü belirlenmiş plugin Hook bağlamları, plugin’lerin OTEL korelasyonu amacıyla yapılandırılmış günlüklere aktarabileceği, salt okunur ve W3C uyumlu bir tanılama izleme bağlamı olan trace öğesini de içerebilir.
event.messages öğesine eklenen dizeler, yalnızca
command:new ve command:reset için (kaynak konuşmaya yanıt olarak
yönlendirilir) ve session:compact:before / session:compact:after için
(Compaction durum bildirimleri olarak gönderilir) sohbete geri iletilir.
command:stop, message:*, agent:bootstrap, session:patch ve
gateway:* dâhil diğer tüm olaylar, eklenen mesajları yok sayar.
Olay bağlamının önemli noktaları
Komut olayları (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.
Komut olayları (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.
Mesaj olayları (message:received): context.from, context.content, context.channelId, context.media (sıralı, aşamalandırılmış ek bilgileri), uzak medya henüz yerel olarak aşamalandırılmadığında context.originalMedia ile birlikte context.mediaStagingPending ve context.metadata (senderId, senderName, guildId dâhil sağlayıcıya özgü veriler). context.content, komut benzeri mesajlarda boş olmayan bir komut gövdesini tercih eder; ardından ham gelen gövdeye ve genel gövdeye geri döner. İleti dizisi geçmişi veya bağlantı özetleri gibi yalnızca agent’a yönelik zenginleştirmeleri içermez. metadata içindeki eski medya diğer adları kullanımdan kaldırılmıştır.
Mesaj olayları (message:sent): context.to, context.content, context.success, context.channelId ve gönderim başarısız olduğunda context.error.
Mesaj olayları (message:transcribed): context.transcript, context.from, context.channelId ve context.media. context.mediaPath ve context.mediaType, ilk bilgi için kullanımdan kaldırılmış diğer adlar olarak kalır.
Mesaj olayları (message:preprocessed): context.bodyForAgent (nihai zenginleştirilmiş gövde), context.from, context.channelId.
Önyükleme olayları (agent:bootstrap): context.bootstrapFiles (değiştirilebilir dizi), context.agentId.
Oturum yama olayları (session:patch): context.sessionEntry, context.patch (yalnızca değiştirilen alanlar), context.cfg. Yama olaylarını yalnızca ayrıcalıklı istemciler tetikleyebilir; bağlam bir kopyadır, bu nedenle işleyiciler canlı oturum girdisini değiştiremez.
Compaction olayları: session:compact:before, messageCount ve tokenCount öğelerini içerir. session:compact:after; compactedCount, summaryLength, tokensBefore ve tokensAfter öğelerini ekler.
command:stop, kullanıcının /stop komutunu vermesini gözlemler; bu,
bir agent sonlandırma geçidi değil, iptal/komut yaşam döngüsüdür. Doğal bir
nihai yanıtı incelemesi ve agent’dan bir geçiş daha istemesi gereken plugin’ler
bunun yerine türü belirlenmiş before_agent_finalize plugin Hook’unu kullanmalıdır.
Bkz. Plugin Hook’ları.
Gateway yaşam döngüsü olayları: gateway:shutdown, reason ve restartExpectedMs öğelerini içerir ve Gateway kapatma işlemi başladığında tetiklenir. gateway:pre-restart aynı bağlamı içerir, ancak yalnızca kapatma beklenen bir yeniden başlatmanın parçasıysa ve sonlu bir restartExpectedMs değeri sağlanmışsa tetiklenir. Kapatma sırasında her yaşam döngüsü Hook’u için bekleme, en iyi çaba esasına göre ve sınırlı olarak gerçekleştirilir; böylece bir işleyici takılırsa kapatma devam eder. Varsayılan bekleme bütçesi gateway:shutdown için 5 saniye, gateway:pre-restart için 10 saniyedir.
Kanallar hâlâ kullanılabilir durumdayken kısa yeniden başlatma bildirimleri için gateway:pre-restart kullanın:
gateway:shutdown (veya gateway:pre-restart) olayı ile kapatma dizisinin geri kalanı arasında Gateway, süreç durduğunda hâlâ etkin olan her oturum için türü belirlenmiş bir session_end plugin Hook’u da tetikler. Olayın reason değeri, normal bir SIGTERM/SIGINT durdurması için shutdown; kapatma beklenen bir yeniden başlatmanın parçası olarak planlandığında ise restart olur. Bu boşaltma işlemi sınırlıdır; böylece yavaş bir session_end işleyicisi sürecin çıkışını engelleyemez. Çift tetiklemeyi önlemek için replace / reset / delete / Compaction aracılığıyla zaten sonlandırılmış oturumlar atlanır.
Hook keşfi
Hook’lar dört kaynaktan keşfedilir:- Paketlenmiş hook’lar: OpenClaw ile birlikte sunulur
- Plugin hook’ları: yüklü plugin’lerin içinde paketlenmiştir; aynı ada sahip paketlenmiş hook’ları geçersiz kılabilir
- Yönetilen hook’lar:
~/.openclaw/hooks/(kullanıcı tarafından yüklenir, çalışma alanları arasında paylaşılır); paketlenmiş hook’ları ve plugin hook’larını geçersiz kılabilir.hooks.internal.load.extraDirsiçindeki ek dizinler de bu önceliğe sahiptir. - Çalışma alanı hook’ları:
<workspace>/hooks/(ajan başına, açıkça etkinleştirilene kadar varsayılan olarak devre dışıdır)
openclaw hooks enable <name> ile paketlenmiş veya yönetilen bir hook’u etkinleştirin, bir hook paketi yükleyin ya da katılmak için hooks.internal.enabled=true ayarını yapın. Adlandırılmış bir hook’u etkinleştirdiğinizde Gateway yalnızca o hook’un işleyicisini yükler; hooks.internal.enabled=true, ek hook dizinleri ve eski işleyiciler geniş kapsamlı keşfi etkinleştirir.
Hook paketleri
Hook paketleri,package.json içindeki openclaw.hooks aracılığıyla hook’ları dışa aktaran npm paketleridir. Şununla yükleyin:
openclaw hooks install ve openclaw hooks update komutları, openclaw plugins install / openclaw plugins update için kullanımdan kaldırılmış takma adlardır.
Paketlenmiş hook’lar
Paketlenmiş herhangi bir hook’u etkinleştirin:
session-memory ayrıntıları
Son kullanıcı/asistan mesajlarını çıkarır (varsayılan 15,hooks.internal.entries.session-memory.messages ile yapılandırılabilir) ve ana makinenin yerel tarihini kullanarak <workspace>/memory/YYYY-MM-DD-HHMM.md konumuna kaydeder. Bellek yakalama arka planda çalıştığından /new ve /reset onayları, transkript okumaları veya isteğe bağlı kısa ad oluşturma nedeniyle gecikmez. Açıklayıcı dosya adı kısa adları oluşturmak için hooks.internal.entries.session-memory.llmSlug: true ayarını yapın ve isteğe bağlı olarak hooks.internal.entries.session-memory.model değerini sonnet gibi yapılandırılmış bir takma ada, ajanın varsayılan sağlayıcısındaki yalın bir model kimliğine veya bir provider/model referansına ayarlayın. model belirtilmediğinde kısa ad oluşturma, ajanın varsayılan modelini kullanır ve kullanılamadığında zaman damgası kısa adlarına geri döner. workspace.dir yapılandırmasının yapılmasını gerektirir.
bootstrap-extra-files yapılandırması
patterns ve files, paths için takma ad olarak kabul edilir. Yollar çalışma alanına göre çözümlenir ve çalışma alanının içinde kalmalıdır. Yalnızca tanınan başlangıç temel adları yüklenir (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
command-logger ayrıntıları
Her eğik çizgi komutunu bir JSON satırı (zaman damgası, eylem, oturum anahtarı, gönderen kimliği, kaynak) olarak~/.openclaw/logs/commands.log konumuna kaydeder.
compaction-notifier ayrıntıları
OpenClaw oturum transkriptini sıkıştırmaya başladığında ve sıkıştırmayı bitirdiğinde mevcut görüşmeye kısa durum mesajları gönderir. Böylece kullanıcı, asistanın bağlamı özetlediğini ve Compaction sonrasında devam edeceğini görebildiği için sohbet yüzeylerindeki uzun dönüşler daha az kafa karıştırıcı olur.boot-md ayrıntıları
Dosya, ajanın çözümlenmiş çalışma alanında mevcutsa yapılandırılmış her ajan kapsamı için Gateway başlangıcındaBOOT.md çalıştırır.
Plugin hook’ları
Plugin’ler, daha derin entegrasyon için Plugin SDK üzerinden türü belirlenmiş hook’lar kaydedebilir: araç çağrılarına müdahale etme, istemleri değiştirme, mesaj akışını denetleme ve daha fazlası.before_tool_call, before_agent_reply,
before_install veya diğer işlem içi yaşam döngüsü hook’larına ihtiyaç duyduğunuzda plugin hook’larını kullanın.
Plugin tarafından yönetilen dahili hook’lar farklıdır: bu sayfadaki
genel komut/yaşam döngüsü olay sistemine katılır ve openclaw hooks list içinde
plugin:<id> olarak görünür. Bunları sıralı ara yazılım veya ilke geçitleri için değil,
yan etkiler ve hook paketleriyle uyumluluk için kullanın.
Eksiksiz plugin hook’u referansı için Plugin hook’ları bölümüne bakın.
Yapılandırma
requires.env uygunluk kontrollerini (işlem ortamıyla birlikte) karşılar ve işleyiciler bunları hook yapılandırma girdilerinden okuyabilir:
Eski
hooks.internal.handlers dizi yapılandırma biçimi geriye dönük uyumluluk için hâlâ desteklenmektedir, ancak yeni hook’lar keşif tabanlı sistemi kullanmalıdır.CLI referansı
En iyi uygulamalar
- İşleyicileri hızlı tutun. Hook’lar komut işleme sırasında çalışır. Ağır işleri
void processInBackground(event)ile başlatıp beklemeden devam edin. - Hataları düzgün biçimde işleyin. Riskli işlemleri try/catch içine alın; diğer işleyicilerin çalışabilmesi için hata fırlatmayın.
- Olayları erkenden filtreleyin. Olay türü/eylem ilgili değilse hemen dönün.
- Belirli olay anahtarları kullanın. Ek yükü azaltmak için
"events": ["command"]yerine"events": ["command:new"]tercih edin.
Sorun giderme
Hook keşfedilmiyor
Hook uygun değil
Hook çalışmıyor
- Hook’un etkinleştirildiğini doğrulayın:
openclaw hooks list - Hook’ların yeniden yüklenmesi için Gateway işleminizi yeniden başlatın.
- Gateway günlüklerini kontrol edin:
openclaw logs --follow | grep -i hook
İlgili
- CLI Referansı: hook’lar
- Webhook’lar
- Plugin hook’ları — işlem içi plugin yaşam döngüsü hook’ları
- Yapılandırma