/new, /reset, /stop, Compaction sesi, siklus hidup Gateway, dan alur pesan. Hook ditemukan dari direktori dan dikelola dengan openclaw hooks. Gateway memuat hook internal hanya setelah Anda mengaktifkan hook atau mengonfigurasi setidaknya satu entri hook, paket hook, penangan lama, atau direktori hook tambahan.
Ada dua jenis hook di OpenClaw:
- Hook internal (halaman ini): berjalan di dalam Gateway ketika peristiwa agen dipicu.
- Webhook: titik akhir HTTP eksternal yang memungkinkan sistem lain memicu pekerjaan di OpenClaw. Lihat Webhook.
openclaw hooks list menampilkan hook mandiri maupun hook yang dikelola Plugin (ditampilkan sebagai plugin:<id>).
Pilih permukaan yang tepat
OpenClaw memiliki beberapa permukaan ekstensi yang terlihat serupa tetapi menyelesaikan masalah yang berbeda:
Gunakan hook internal jika Anda menginginkan automasi yang berperilaku seperti integrasi kecil yang terpasang. Gunakan hook Plugin bertipe jika Anda memerlukan kendali siklus hidup waktu proses.
Mulai cepat
Jenis peristiwa
Hook berlangganan ke kunci tertentu dari tabel ini, atau ke nama keluarga saja (command, session, agent, gateway, message) untuk menerima setiap tindakan
dalam keluarga tersebut. Inti OpenClaw tidak memancarkan peristiwa lain, sehingga nama lainnya hampir
selalu merupakan salah ketik yang membuat hook diam-diam tidak aktif (hanya Plugin yang memancarkan
peristiwa khusus yang dapat memicunya). Pemuat hook mencatat peringatan untuk nama tersebut
(misalnya command:nwe), dan openclaw hooks info <name> menandainya, sehingga
hook yang tidak pernah berjalan dapat didiagnosis.
Menulis hook
Struktur hook
Setiap hook adalah direktori yang berisi dua berkas:handler.ts, handler.js, index.ts, atau index.js.
Format HOOK.md
metadata.openclaw):
Implementasi penangan
type, action, sessionKey, timestamp, messages, dan context (data khusus peristiwa). Konteks hook Plugin bertipe untuk hook agen dan alat juga dapat mencakup trace, yaitu konteks jejak diagnostik hanya-baca yang kompatibel dengan W3C dan dapat diteruskan oleh Plugin ke log terstruktur untuk korelasi OTEL.
String yang ditambahkan ke event.messages dikirim kembali ke percakapan hanya untuk
command:new dan command:reset (dirutekan sebagai balasan ke percakapan
asal) serta untuk session:compact:before / session:compact:after
(dikirim sebagai pemberitahuan status Compaction). Semua peristiwa lainnya, termasuk
command:stop, message:*, agent:bootstrap, session:patch, dan
gateway:*, mengabaikan pesan yang ditambahkan.
Sorotan konteks peristiwa
Peristiwa perintah (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.
Peristiwa perintah (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.
Peristiwa pesan (message:received): context.from, context.content, context.channelId, context.metadata (data khusus penyedia termasuk senderId, senderName, guildId). context.content mengutamakan isi perintah yang tidak kosong untuk pesan menyerupai perintah, lalu beralih ke isi pesan masuk mentah dan isi generik; nilai ini tidak menyertakan pengayaan khusus agen seperti riwayat utas atau ringkasan tautan.
Peristiwa pesan (message:sent): context.to, context.content, context.success, context.channelId, serta context.error ketika pengiriman gagal.
Peristiwa pesan (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.
Peristiwa pesan (message:preprocessed): context.bodyForAgent (isi akhir yang telah diperkaya), context.from, context.channelId.
Peristiwa bootstrap (agent:bootstrap): context.bootstrapFiles (larik yang dapat diubah), context.agentId.
Peristiwa tambalan sesi (session:patch): context.sessionEntry, context.patch (hanya bidang yang berubah), context.cfg. Hanya klien berhak istimewa yang dapat memicu peristiwa tambalan; konteksnya berupa klona, sehingga penangan tidak dapat mengubah entri sesi aktif.
Peristiwa Compaction: session:compact:before mencakup messageCount, tokenCount. session:compact:after menambahkan compactedCount, summaryLength, tokensBefore, tokensAfter.
command:stop mengamati saat pengguna memberikan /stop; ini merupakan siklus hidup
pembatalan/perintah, bukan gerbang finalisasi agen. Plugin yang perlu memeriksa
jawaban akhir alami dan meminta agen melakukan satu lintasan lagi harus menggunakan hook
Plugin bertipe before_agent_finalize. Lihat Hook Plugin.
Peristiwa siklus hidup Gateway: gateway:shutdown mencakup reason dan restartExpectedMs, serta dipicu ketika penonaktifan Gateway dimulai. gateway:pre-restart mencakup konteks yang sama, tetapi hanya dipicu ketika penonaktifan merupakan bagian dari mulai ulang yang direncanakan dan nilai restartExpectedMs terbatas diberikan. Selama penonaktifan, setiap penantian hook siklus hidup dilakukan dengan upaya terbaik dan dibatasi agar penonaktifan tetap berlanjut jika penangan terhenti. Anggaran waktu tunggu bawaan adalah 5 detik untuk gateway:shutdown dan 10 detik untuk gateway:pre-restart.
Gunakan gateway:pre-restart untuk pemberitahuan singkat mulai ulang saat kanal masih tersedia:
gateway:shutdown (atau gateway:pre-restart) dan rangkaian penonaktifan lainnya, Gateway juga memicu hook Plugin bertipe session_end untuk setiap sesi yang masih aktif ketika proses berhenti. reason peristiwa tersebut adalah shutdown untuk penghentian SIGTERM/SIGINT biasa dan restart ketika penutupan dijadwalkan sebagai bagian dari mulai ulang yang direncanakan. Pengurasan ini dibatasi agar penangan session_end yang lambat tidak dapat menghalangi keluarnya proses, dan sesi yang telah difinalisasi melalui penggantian / pengaturan ulang / penghapusan / Compaction dilewati untuk menghindari pemicuan ganda.
Penemuan hook
Hook ditemukan dari empat sumber:- Hook bawaan: dikirim bersama OpenClaw
- Hook Plugin: dibundel di dalam Plugin yang terpasang; dapat menggantikan hook bawaan dengan nama yang sama
- Hook terkelola:
~/.openclaw/hooks/(dipasang pengguna, digunakan bersama di seluruh ruang kerja); dapat menggantikan hook bawaan dan hook Plugin. Direktori tambahan darihooks.internal.load.extraDirsmemiliki prioritas yang sama. - Hook ruang kerja:
<workspace>/hooks/(per agen, dinonaktifkan secara bawaan hingga diaktifkan secara eksplisit)
openclaw hooks enable <name>, pasang paket hook, atau tetapkan hooks.internal.enabled=true untuk memilih ikut serta. Ketika Anda mengaktifkan satu hook bernama, Gateway hanya memuat penangan hook tersebut; hooks.internal.enabled=true, direktori hook tambahan, dan penangan lama memilih ikut serta dalam penemuan luas.
Paket hook
Paket hook adalah paket npm yang mengekspor hook melaluiopenclaw.hooks di package.json. Pasang dengan:
openclaw hooks install dan openclaw hooks update merupakan alias usang untuk openclaw plugins install / openclaw plugins update.
Hook bawaan
Aktifkan hook bawaan apa pun:
Detail session-memory
Mengekstrak pesan terakhir pengguna/asisten (bawaan 15, dapat dikonfigurasi denganhooks.internal.entries.session-memory.messages) dan menyimpannya ke <workspace>/memory/YYYY-MM-DD-HHMM.md menggunakan tanggal lokal host. Pengambilan memori berjalan di latar belakang sehingga konfirmasi /new dan /reset tidak tertunda oleh pembacaan transkrip atau pembuatan slug opsional. Atur hooks.internal.entries.session-memory.llmSlug: true untuk menghasilkan slug nama file yang deskriptif, dan secara opsional atur hooks.internal.entries.session-memory.model ke alias yang telah dikonfigurasi seperti sonnet, ID model polos pada penyedia bawaan agen, atau referensi provider/model. Pembuatan slug menggunakan model bawaan agen saat model tidak ditentukan dan beralih ke slug stempel waktu jika tidak tersedia. Mengharuskan workspace.dir dikonfigurasi.
Konfigurasi bootstrap-extra-files
patterns dan files diterima sebagai alias untuk paths. Jalur diuraikan relatif terhadap ruang kerja dan harus tetap berada di dalamnya. Hanya nama dasar bootstrap yang dikenali yang dimuat (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
Detail command-logger
Mencatat setiap perintah garis miring sebagai satu baris JSON (stempel waktu, tindakan, kunci sesi, ID pengirim, sumber) ke~/.openclaw/logs/commands.log.
Detail compaction-notifier
Mengirim pesan status singkat ke percakapan saat ini ketika OpenClaw memulai dan menyelesaikan Compaction transkrip sesi. Ini membuat giliran panjang tidak terlalu membingungkan pada antarmuka obrolan karena pengguna dapat melihat bahwa asisten sedang merangkum konteks dan akan melanjutkan setelah Compaction.Detail boot-md
MenjalankanBOOT.md saat Gateway dimulai untuk setiap cakupan agen yang dikonfigurasi, jika file tersebut ada di ruang kerja agen yang telah diuraikan.
Hook Plugin
Plugin dapat mendaftarkan hook bertipe melalui Plugin SDK untuk integrasi yang lebih mendalam: mencegat pemanggilan alat, memodifikasi prompt, mengendalikan alur pesan, dan lainnya. Gunakan hook Plugin saat Anda memerlukanbefore_tool_call, before_agent_reply,
before_install, atau hook siklus hidup dalam proses lainnya.
Hook internal yang dikelola Plugin berbeda: hook tersebut berpartisipasi dalam sistem
peristiwa perintah/siklus hidup tingkat kasar di halaman ini dan muncul dalam openclaw hooks list sebagai
plugin:<id>. Gunakan hook tersebut untuk efek samping dan kompatibilitas dengan paket hook, bukan
untuk middleware berurutan atau gerbang kebijakan.
Untuk referensi lengkap hook Plugin, lihat Hook Plugin.
Konfigurasi
requires.env milik hook (bersama lingkungan proses), dan penangan dapat membacanya dari entri konfigurasi hook:
Format konfigurasi array lama
hooks.internal.handlers masih didukung untuk kompatibilitas mundur, tetapi hook baru sebaiknya menggunakan sistem berbasis penemuan.Referensi CLI
Praktik terbaik
- Jaga agar penangan tetap cepat. Hook berjalan selama pemrosesan perintah. Jalankan pekerjaan berat tanpa menunggu hasilnya dengan
void processInBackground(event). - Tangani kesalahan dengan baik. Bungkus operasi berisiko dalam try/catch; jangan melempar kesalahan agar penangan lain dapat berjalan.
- Filter peristiwa sejak awal. Segera kembali jika jenis/tindakan peristiwa tidak relevan.
- Gunakan kunci peristiwa yang spesifik. Utamakan
"events": ["command:new"]daripada"events": ["command"]untuk mengurangi beban tambahan.
Pemecahan masalah
Hook tidak ditemukan
Hook tidak memenuhi syarat
Hook tidak dijalankan
- Pastikan hook diaktifkan:
openclaw hooks list - Mulai ulang proses Gateway Anda agar hook dimuat ulang.
- Periksa log Gateway:
openclaw logs --follow | grep -i hook
Terkait
- Referensi CLI: hook
- Webhook
- Hook Plugin — hook siklus hidup Plugin dalam proses
- Konfigurasi