Kancalar

Hooks, Gateway içinde bir şey olduğunda çalışan küçük betiklerdir. Dizinlerden keşfedilebilir ve openclaw hooks ile incelenebilirler. Gateway, dahili hooks öğelerini yalnızca hooks öğelerini etkinleştirdikten veya en az bir hook girdisi, hook paketi, eski handler ya da ek hook dizini yapılandırdıktan sonra yükler.

OpenClaw içinde iki tür hooks vardır:

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

Hooks, plugins içinde de paketlenebilir. openclaw hooks list hem bağımsız hooks öğelerini hem de plugin tarafından yönetilen hooks öğelerini gösterir.

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

Hooks 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.

Metadata alanları (metadata.openclaw):

Handler 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 message to user  event.messages.push("Hook executed!");}; export default handler;

Her olay şunları içerir: type, action, sessionKey, timestamp, messages (kullanıcıya göndermek için push edin) ve context (olaya özgü veriler). Agent ve araç plugin hook bağlamları ayrıca trace içerebilir; bu, plugins öğelerinin OTEL korelasyonu için yapılandırılmış günlüklere aktarabileceği salt okunur W3C uyumlu bir tanılama izleme bağlamıdır.

Olay bağlamı öne çıkanları

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

İleti 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 iletiler için boş olmayan bir komut gövdesini tercih eder, ardından ham gelen gövdeye ve genel gövdeye geri döner; thread geçmişi veya bağlantı özetleri gibi yalnızca agent'a ait zenginleştirmeleri içermez.

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

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

İleti 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 patch olayları (session:patch): context.sessionEntry, context.patch (yalnızca değişen alanlar), context.cfg. Patch 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, bir agent sonlandırma kapısı değil, iptal/komut yaşam döngüsüdür. Doğal bir son yanıtı incelemesi ve agent'tan bir geçiş daha istemesi gereken plugins, bunun yerine typed plugin hook before_agent_finalize kullanmalıdır. Bkz. Plugin hooks.

Gateway yaşam döngüsü olayları: gateway:shutdown, reason ve restartExpectedMs içerir ve gateway kapatması 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 best-effort ve sınırlıdır; böylece bir handler takılsa bile kapatma devam eder.

gateway:shutdown (veya gateway:pre-restart) olayı ile kapatma dizisinin geri kalanı arasında, gateway ayrıca süreç durduğunda hâlâ etkin olan her oturum için typed session_end plugin hook 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ıysa restart olur. Bu boşaltma sınırlıdır; böylece yavaş bir session_end handler süreç çıkışını engelleyemez ve replace / reset / delete / compaction üzerinden zaten sonlandırılmış oturumlar çift tetiklemeyi önlemek için atlanır.

Hook keşfi

Hooks, artan override önceliği sırasıyla şu dizinlerden keşfedilir:

1. Paketlenmiş hooks: OpenClaw ile gönderilir
2. Plugin hooks: kurulu plugins içinde paketlenmiş hooks
3. Yönetilen hooks: ~/.openclaw/hooks/ (kullanıcı tarafından kurulur, çalışma alanları arasında paylaşılır). hooks.internal.load.extraDirs üzerinden gelen ek dizinler bu önceliği paylaşır.
4. Çalışma alanı hooks: <workspace>/hooks/ (agent başına, açıkça etkinleştirilene kadar varsayılan olarak devre dışı)

Çalışma alanı hooks yeni hook adları ekleyebilir, ancak aynı ada sahip paketlenmiş, yönetilen veya plugin tarafından sağlanan hooks öğelerini override edemez.

Gateway, dahili hooks yapılandırılana kadar başlangıçta dahili hook keşfini atlar. Katılmak için openclaw hooks enable <name> ile paketlenmiş veya yönetilen bir hook etkinleştirin, bir hook paketi kurun ya da hooks.internal.enabled=true ayarlayın. Adlandırılmış bir hook etkinleştirdiğinizde Gateway yalnızca o hook'un handler öğesini yükler; hooks.internal.enabled=true, ek hook dizinleri ve eski handlers geniş keşfe katılır.

Hook paketleri

Hook paketleri, package.json içindeki openclaw.hooks üzerinden hooks export eden npm paketleridir. Şununla kurun:

openclaw plugins install <path-or-spec>

Npm spec'leri yalnızca registry'dendir (paket adı + isteğe bağlı tam sürüm veya dist-tag). Git/URL/file spec'leri ve semver aralıkları reddedilir.

Paketlenmiş hooks

Herhangi bir paketlenmiş hook etkinleştirin:

openclaw hooks enable <hook-name>

session-memory ayrıntıları

Son 15 kullanıcı/assistant iletisini çıkarır ve host yerel tarihini kullanarak <workspace>/memory/YYYY-MM-DD-HHMM.md içine kaydeder. Bellek yakalama arka planda çalışır; böylece /new ve /reset onayları transcript 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ülür. Yalnızca tanınan bootstrap basename'leri 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 günlüğe kaydeder.

compaction-notifier ayrıntıları

OpenClaw oturum transcript'ini compact etmeye başladığında ve bitirdiğinde mevcut konuşmaya kısa durum iletileri gönderir. Bu, sohbet yüzeylerinde uzun turları daha az kafa karıştırıcı hale getirir; çünkü kullanıcı, assistant'ı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 hooks

Plugins daha derin entegrasyon için Plugin SDK üzerinden typed hooks kaydedebilir: araç çağrılarını yakalama, prompt'ları değiştirme, ileti 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ü hooks gerektiğinde plugin hooks kullanın.

Eksiksiz plugin hook başvurusu için bkz. Plugin hooks.

Yapılandırma

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

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

{  "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

# 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 arka planda bırakın.
• Hataları düzgün şekilde ele alın. Riskli işlemleri try/catch içine alı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ını kullanın. Ek yükü azaltmak için "events": ["command"] yerine "events": ["command:new"] tercih edin.

Sorun giderme

Kanca keşfedilmiyor

# 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 kontrol edin.

Kanca yürütülmüyor

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

İlgili

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