Kancalar

Hook'lar, Gateway içinde bir şey olduğunda çalışan küçük betiklerdir. Dizinlerden keşfedilebilir ve openclaw hooks ile incelenebilirler. 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 içinde iki tür hook vardır:

• Dahili hook'lar (bu sayfa): /new, /reset, /stop gibi ajan olayları veya yaşam döngüsü olayları tetiklendiğinde Gateway içinde çalışır.
• Webhook'lar: diğer sistemlerin OpenClaw içinde iş tetiklemesini sağlayan harici HTTP uç noktalarıdır. Bkz. Webhook'lar.

Hook'lar Plugin'lerin içine de paketlenebilir. openclaw hooks list hem bağımsız hook'ları hem de Plugin tarafından yönetilen hook'ları gösterir.

Doğru yüzeyi seçin

OpenClaw, benzer görünen ancak farklı sorunları çözen birkaç genişletme yüzeyine sahiptir:

Küçük bir kurulu entegrasyon gibi davranan otomasyon istediğinizde dahili hook'ları kullanın. Çalışma zamanı yaşam döngüsü denetimine ihtiyacınız olduğunda tipli Plugin hook'larını kullanın.

Hızlı başlangıç

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

Olay türleri

Hook yazma

Hook yapısı

Her hook, iki dosya içeren bir dizindir:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

HOOK.md biçimi

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

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 (yanıt verilebilir yüzeylerde yanıtları buraya itin) ve context (olaya özgü veri). Ajan ve araç Plugin hook bağlamları ayrıca, Plugin'lerin OTEL korelasyonu için yapılandırılmış günlüklere geçirebileceği salt okunur W3C uyumlu tanılama iz bağlamı olan trace içerebilir.

event.messages yalnızca command:* ve message:received gibi yanıt verilebilir yüzeylerde otomatik olarak teslim edilir. agent:bootstrap, session:*, gateway:* veya message:sent gibi yalnızca yaşam döngüsü olaylarının yanıt kanalı yoktur ve itilen mesajları yok sayar.

Olay bağlamı öne çıkanları

Komut olayları (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg.

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 mesajlar için önce boş olmayan bir komut gövdesini tercih eder, ardından ham gelen gövdeye ve genel gövdeye geri döner; ileti geçmişi veya bağlantı özetleri gibi yalnızca ajana özgü zenginleştirmeleri içermez.

Mesaj olayları (message:sent): context.to, context.content, context.success, context.channelId.

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.

Bootstrap olayları (agent:bootstrap): context.bootstrapFiles (değiştirilebilir dizi), context.agentId.

Oturum yaması olayları (session:patch): context.sessionEntry, context.patch (yalnızca değişen alanlar), context.cfg. Yama olaylarını yalnızca ayrıcalıklı istemciler tetikleyebilir.

Compaction olayları: session:compact:before, messageCount, tokenCount içerir. session:compact:after, compactedCount, summaryLength, tokensBefore, tokensAfter ekler.

command:stop, kullanıcının /stop vermesini gözlemler; bu, iptal/komut yaşam döngüsüdür, ajan sonlandırma kapısı değildir. Doğal bir son yanıtı incelemesi ve ajandan bir tur daha istemesi gereken Plugin'ler bunun yerine tipli Plugin hook'u before_agent_finalize kullanmalıdır. Bkz. Plugin hook'ları.

Gateway yaşam döngüsü olayları: gateway:shutdown, reason ve restartExpectedMs 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ı olduğunda ve sonlu bir restartExpectedMs değeri sağlandığında tetiklenir. Kapatma sırasında her yaşam döngüsü hook beklemesi en iyi çabadır ve sınırlıdır; 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ılabilirken kısa yeniden başlatma bildirimleri 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 tipli bir session_end Plugin hook'u da tetikler. Olayın reason değeri düz bir SIGTERM/SIGINT durdurması için shutdown, kapatma beklenen bir yeniden başlatmanın parçası olarak zamanlandığında restart olur. Bu boşaltma sınırlıdır; bu nedenle yavaş bir session_end işleyicisi süreç çıkışını engelleyemez ve değiştirme / sıfırlama / silme / Compaction yoluyla zaten sonlandırılmış oturumlar çift tetiklemeyi önlemek için atlanır.

Hook keşfi

Hook'lar, artan geçersiz kılma önceliği sırasıyla şu dizinlerden keşfedilir:

1. Paketle gelen hook'lar: OpenClaw ile gönderilir
2. Plugin hook'ları: kurulu Plugin'lerin içine paketlenmiş hook'lar
3. Yönetilen hook'lar: ~/.openclaw/hooks/ (kullanıcı tarafından kurulur, çalışma alanları arasında paylaşılır). hooks.internal.load.extraDirs içindeki ek dizinler 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ışı)

Çalışma alanı hook'ları yeni hook adları ekleyebilir ancak aynı ada sahip paketle gelen, 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ıçta dahili hook keşfini atlar. Dahili veya yönetilen bir hook'u openclaw hooks enable <name> ile etkinleştirin, bir hook paketi kurun veya katılmak için hooks.internal.enabled=true ayarlayın. Bir adlandırılmış 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ş keşfe katılır.

Hook paketleri

Hook paketleri, package.json içinde openclaw.hooks üzerinden hook 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.

Paketle gelen hook'lar

Herhangi bir paketli kancayı etkinleştirin:

openclaw hooks enable <hook-name>

session-memory ayrıntıları

Son 15 kullanıcı/asistan mesajını çıkarır ve ana makinenin yerel tarihini kullanarak <workspace>/memory/YYYY-MM-DD-HHMM.md dosyasına kaydeder. Bellek yakalama arka planda çalışır, böylece /new ve /reset onayları transkript okumaları veya isteğe bağlı slug üretimi nedeniyle gecikmez. Yapılandırılmış modelle açıklayıcı dosya adı slug'ları oluşturmak için hooks.internal.entries.session-memory.llmSlug: true ayarlayın. 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"]        }      }    }  }}

Yollar çalışma alanına göre çözümlenir. Yalnızca tanınan bootstrap 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 slash komutunu ~/.openclaw/logs/commands.log içine kaydeder.

compaction-notifier ayrıntıları

OpenClaw oturum transkriptini Compaction işlemine başlattığında ve bitirdiğinde mevcut konuşmaya kısa durum mesajları gönderir. Bu, sohbet yüzeylerinde uzun dönüşleri daha az kafa karıştırıcı hale getirir; çünkü kullanıcı asistanın bağlamı özetlediğini ve Compaction sonrasında devam edeceğini görebilir.

boot-md ayrıntıları

Gateway başladığında etkin çalışma alanından BOOT.md çalıştırır.

Plugin kancaları

Plugin'ler, daha derin entegrasyon için Plugin SDK üzerinden türlenmiş kancalar kaydedebilir: araç çağrılarını yakalama, istemleri değiştirme, mesaj akışını denetleme ve daha fazlası. before_tool_call, before_agent_reply, before_install veya diğer süreç içi yaşam döngüsü kancalarına ihtiyaç duyduğunuzda Plugin kancalarını kullanın.

Plugin tarafından yönetilen dahili kancalar farklıdır: bu sayfanın kaba komut/yaşam döngüsü olay sistemine katılırlar ve openclaw hooks list içinde plugin:<id> olarak görünürler. Bunları sıralı middleware veya ilke kapıları için değil, yan etkiler ve kanca paketleriyle uyumluluk için kullanın.

Eksiksiz Plugin kancası başvurusu için Plugin kancaları bölümüne bakın.

Yapılandırma

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

Kanca başına ortam değişkenleri:

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

Ek kanca dizinleri:

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

CLI başvurusu

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

En iyi uygulamalar

• İşleyicileri hızlı tutun. Kancalar komut işleme sırasında çalışır. Ağır işleri void processInBackground(event) ile başlatıp sonucu beklemeden sürdürün.
• Hataları zarifçe ele alın. Riskli işlemleri try/catch ile sarın; diğer işleyicilerin çalışabilmesi için hata fırlatmayın.
• Olayları erken 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

Kanca keşfedilmedi

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

Kanca 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 denetleyin.

Kanca çalışmıyor

1. Kancanın etkin olduğunu doğrulayın: openclaw hooks list
2. Kancaların yeniden yüklenmesi için Gateway sürecinizi yeniden başlatın.
3. Gateway günlüklerini denetleyin: ./scripts/clawlog.sh | grep hook

İlgili

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