Kancalar

Hook'lar, ajan olayları tetiklendiğinde Gateway içinde çalışan küçük betiklerdir: /new, /reset, /stop gibi komutlar, oturum sıkıştırması, 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): ajan olayları tetiklendiğinde Gateway içinde çalışır.
• Webhook'lar: diğer sistemlerin OpenClaw'da iş tetiklemesine olanak tanıyan harici HTTP uç noktalarıdır. Bkz. Webhook'lar.

Hook'lar, Plugin'lerin içinde de paketlenebilir. openclaw hooks list, hem bağımsız Hook'ları hem de Plugin tarafından yönetilen Hook'ları (plugin:<id> olarak gösterilir) listeler.

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 belirtilmiş Plugin Hook'larını kullanın.

Hızlı başlangıç

# Kullanılabilir Hook'ları listeleopenclaw hooks list # Bir Hook'u etkinleştiropenclaw hooks enable session-memory # Hook durumunu denetleopenclaw hooks check # Ayrıntılı bilgi alopenclaw hooks info session-memory

Olay türleri

Hook'lar bu tablodaki belirli bir anahtara veya ilgili ailedeki tüm eylemleri almak için yalnızca aile adına (command, session, agent, gateway, message) abone olur. OpenClaw çekirdeği bunların dışında hiçbir şey yaymaz; bu nedenle başka herhangi bir ad, neredeyse her zaman Hook'un hiçbir uyarı vermeden çalışmamasına neden olan bir yazım hatasıdır (yalnızca özel olay yayan bir Plugin bunu tetikleyebilir). Hook yükleyicisi bu tür adlar için (örneğin command:nwe) uyarı kaydeder ve openclaw hooks info <name> bunları işaretler; böylece hiç çalışmayan bir Hook tanılanabilir.

Hook yazma

Hook yapısı

Her Hook, iki dosya içeren bir dizindir:

my-hook/├── HOOK.md          # Meta veriler + belgeler└── handler.ts       # İşleyici uygulaması

İşleyici dosyası handler.ts, handler.js, index.ts veya index.js olabilir.

HOOK.md biçimi

---name: my-hookdescription: "Bu Hook'un ne yaptığının kısa açıklaması"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Hook'um Ayrıntılı belgeler buraya gelir.

Meta veri alanları (metadata.openclaw):

İşleyici uygulaması

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

Her olay şunları içerir: type, action, sessionKey, timestamp, messages ve context (olaya özgü veriler). Ajan ve araç Hook'ları için tür belirtilmiş Plugin Hook bağlamları, Plugin'lerin OTEL bağıntısı amacıyla yapılandırılmış günlüklere aktarabileceği, salt okunur ve W3C uyumlu bir tanılama izleme bağlamı olan trace alanını da 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:* dahil olmak üzere diğer tüm olaylar eklenen mesajları yok sayar.

Olay bağlamının öne çıkanları

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.metadata (senderId, senderName, guildId dahil sağlayıcıya özgü veriler). context.content, komut benzeri mesajlarda öncelikle boş olmayan komut gövdesini kullanır; ardından ham gelen gövdeye ve genel gövdeye geri döner. İş parçacığı geçmişi veya bağlantı özetleri gibi yalnızca ajana yönelik zenginleştirmeleri içermez.

Mesaj olayları (message:sent): context.to, context.content, context.success, context.channelId ve gönderim başarısız olduğunda ayrıca context.error.

Mesaj olayları (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.

Mesaj olayları (message:preprocessed): context.bodyForAgent (son 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 alanlarını içerir. session:compact:after, bunlara compactedCount, summaryLength, tokensBefore ve tokensAfter alanlarını ekler.

command:stop, kullanıcının /stop komutunu vermesini gözlemler; bu bir iptal/komut yaşam döngüsü olayıdır, ajan sonlandırma geçidi değildir. Doğal bir nihai yanıtı inceleyip ajandan bir geçiş daha yapmasını istemesi gereken Plugin'ler bunun yerine tür belirtilmiş 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 alanlarını içerir ve Gateway kapatma işlemi başladığında tetiklenir. gateway:pre-restart aynı bağlamı içerir ancak yalnızca kapatma işlemi beklenen bir yeniden başlatmanın parçası olduğunda ve sonlu bir restartExpectedMs değeri sağlandığında tetiklenir. Kapatma sırasında, bir işleyici takılırsa kapatma işleminin devam edebilmesi için her yaşam döngüsü Hook beklemesi en iyi çaba esaslı ve sınırlıdır. Varsayılan bekleme bütçesi gateway:shutdown için 5 saniye, gateway:pre-restart için 10 saniyedir.

Kanallar hâlâ kullanılabilirken kısa yeniden başlatma bildirimleri göndermek için gateway:pre-restart kullanın:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

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 belirtilmiş bir session_end Plugin Hook'u da tetikler. Olayın reason değeri, normal bir SIGTERM/SIGINT durdurması için shutdown, kapatma işlemi beklenen bir yeniden başlatmanın parçası olarak zamanlandıysa 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 değiştirme / sıfırlama / silme / Compaction yoluyla zaten sonlandırılmış oturumlar atlanır.

Hook keşfi

Hook'lar dört kaynaktan keşfedilir:

1. Paketlenmiş Hook'lar: OpenClaw ile birlikte sunulur
2. Plugin Hook'ları: kurulu Plugin'lerin içinde paketlenir; aynı ada sahip paketlenmiş Hook'ları geçersiz kılabilir
3. Yönetilen Hook'lar: ~/.openclaw/hooks/ (kullanıcı tarafından kurulur, çalışma alanları arasında paylaşılır); paketlenmiş ve Plugin Hook'larını geçersiz kılabilir. hooks.internal.load.extraDirs içindeki ek dizinler de bu önceliği paylaşır.
4. Çalışma alanı Hook'ları: <workspace>/hooks/ (ajan başına, açıkça etkinleştirilene kadar varsayılan olarak devre dışıdır)

Çalışma alanı Hook'ları yeni Hook adları ekleyebilir ancak aynı ada sahip paketlenmiş, yönetilen veya Plugin tarafından sağlanan Hook'ları geçersiz kılamaz.

Gateway, dahili Hook'lar yapılandırılana kadar başlangıç sırasında dahili Hook keşfini atlar. Katılmak için openclaw hooks enable <name> ile paketlenmiş veya yönetilen bir Hook'u etkinleştirin, bir Hook paketi kurun ya da hooks.internal.enabled=true değerini ayarlayı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 kurun:

openclaw plugins install <path-or-spec>

Npm belirtimleri yalnızca kayıt defteriyle sınırlıdır (paket adı + isteğe bağlı tam sürüm veya dist-tag). Git/URL/dosya belirtimleri ve semver aralıkları reddedilir. Eski openclaw hooks install ve openclaw hooks update komutları, openclaw plugins install / openclaw plugins update için kullanımdan kaldırılmış takma adlardır.

Paketle gelen hook'lar

Paketle gelen herhangi bir hook'u etkinleştirin:

openclaw hooks enable <hook-name>

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ışır; böylece /new ve /reset onayları, döküm 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 başvurusuna ayarlayın. Kısa ad oluşturma, model belirtilmediğinde ajanın varsayılan modelini kullanır ve bu model kullanılamıyorsa zaman damgalı kısa adlara geri döner. workspace.dir yapılandırılmış olmalıdır.

bootstrap-extra-files yapılandırması

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

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 önyükleme temel dosya 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 dosyasına kaydeder.

compaction-notifier ayrıntıları

OpenClaw oturum dökümünü sıkıştırmaya başladığında ve sıkıştırmayı tamamladığında mevcut konuşmaya 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ğinden, sohbet yüzeylerindeki uzun turlar 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ında BOOT.md dosyasını çalıştırır.

Plugin hook'ları

Plugin'ler daha derin entegrasyon için Plugin SDK aracılığıyla tür belirtilmiş hook'lar kaydedebilir: araç çağrılarını engelleme, 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 başvurusu için Plugin hook'ları bölümüne bakın.

Yapılandırma

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Hook başına ortam değerleri, bir hook'un requires.env uygunluk denetimlerini (işlem ortamıyla birlikte) karşılar ve işleyiciler bunları kendi hook yapılandırma girdilerinden okuyabilir:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

Ek hook dizinleri:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

CLI başvurusu

# Tüm hook'ları listele (--eligible, --verbose veya --json ekleyin)openclaw hooks list # Bir hook hakkında ayrıntılı bilgi gösteropenclaw hooks info <hook-name> # Uygunluk özetini gösteropenclaw hooks check # Etkinleştir/devre dışı bırakopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

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 sonucunu beklemeden devam edin.
• Hataları kontrollü biçimde yönetin. 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ü/eylemi 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

# Dizin yapısını doğrulals -la ~/.openclaw/hooks/my-hook/# Şunları göstermelidir: HOOK.md, handler.ts # Keşfedilen tüm hook'ları listeleopenclaw hooks list

Hook uygun değil

openclaw hooks info my-hook

Eksik ikili dosyaları (PATH), ortam değişkenlerini, yapılandırma değerlerini veya işletim sistemi uyumluluğunu kontrol edin.

Hook çalışmıyor

1. Hook'un etkinleştirildiğini doğrulayın: openclaw hooks list
2. Hook'ların yeniden yüklenmesi için Gateway işleminizi yeniden başlatın.
3. Gateway günlüklerini kontrol edin: openclaw logs --follow | grep -i hook

İlgili

• CLI Başvurusu: hook'lar
• Webhook'lar
• Plugin hook'ları — işlem içi Plugin yaşam döngüsü hook'ları
• Yapılandırma