Hooks

Hooks adalah skrip kecil yang berjalan ketika sesuatu terjadi di dalam Gateway. Hooks secara otomatis ditemukan dari direktori dan dapat diperiksa dengan openclaw hooks. Ada dua jenis hook di OpenClaw:

Hook internal (halaman ini): berjalan di dalam Gateway saat peristiwa agen dipicu, seperti /new, /reset, /stop, atau peristiwa siklus hidup.
Webhook: endpoint HTTP eksternal yang memungkinkan sistem lain memicu pekerjaan di OpenClaw. Lihat Webhook.

Hooks juga dapat dibundel di dalam plugin. openclaw hooks list menampilkan hook mandiri dan hook yang dikelola plugin.

Mulai cepat

# Daftar hook yang tersedia
openclaw hooks list

# Aktifkan hook
openclaw hooks enable session-memory

# Periksa status hook
openclaw hooks check

# Dapatkan informasi terperinci
openclaw hooks info session-memory

Jenis peristiwa

Peristiwa	Kapan dipicu
`command:new`	Perintah `/new` dikeluarkan
`command:reset`	Perintah `/reset` dikeluarkan
`command:stop`	Perintah `/stop` dikeluarkan
`command`	Peristiwa perintah apa pun (pendengar umum)
`session:compact:before`	Sebelum pemadatan merangkum riwayat
`session:compact:after`	Setelah pemadatan selesai
`session:patch`	Saat properti sesi dimodifikasi
`agent:bootstrap`	Sebelum file bootstrap workspace disuntikkan
`gateway:startup`	Setelah channel dimulai dan hook dimuat
`message:received`	Pesan masuk dari channel apa pun
`message:transcribed`	Setelah transkripsi audio selesai
`message:preprocessed`	Setelah semua pemahaman media dan tautan selesai
`message:sent`	Pesan keluar terkirim

Menulis hook

Struktur hook

Setiap hook adalah direktori yang berisi dua file:

my-hook/
├── HOOK.md          # Metadata + dokumentasi
└── handler.ts       # Implementasi handler

Format HOOK.md

---
name: my-hook
description: "Deskripsi singkat tentang apa yang dilakukan hook ini"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Dokumentasi terperinci ada di sini.

Bidang metadata (metadata.openclaw):

Bidang	Deskripsi
`emoji`	Emoji tampilan untuk CLI
`events`	Array peristiwa yang akan didengarkan
`export`	Named export yang digunakan (default ke `"default"`)
`os`	Platform yang diperlukan (misalnya `["darwin", "linux"]`)
`requires`	Jalur `bins`, `anyBins`, `env`, atau `config` yang diperlukan
`always`	Lewati pemeriksaan kelayakan (boolean)
`install`	Metode instalasi

Implementasi handler

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] New command triggered`);
  // Logika Anda di sini

  // Opsional kirim pesan ke pengguna
  event.messages.push("Hook executed!");
};

export default handler;

Setiap peristiwa mencakup: type, action, sessionKey, timestamp, messages (push untuk mengirim ke pengguna), dan context (data khusus peristiwa).

Sorotan konteks peristiwa

Peristiwa perintah (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg. Peristiwa pesan (message:received): context.from, context.content, context.channelId, context.metadata (data khusus provider termasuk senderId, senderName, guildId). Peristiwa pesan (message:sent): context.to, context.content, context.success, context.channelId. 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 (array yang dapat diubah), context.agentId. Peristiwa patch sesi (session:patch): context.sessionEntry, context.patch (hanya bidang yang berubah), context.cfg. Hanya klien berhak istimewa yang dapat memicu peristiwa patch. Peristiwa pemadatan: session:compact:before mencakup messageCount, tokenCount. session:compact:after menambahkan compactedCount, summaryLength, tokensBefore, tokensAfter.

Penemuan hook

Hooks ditemukan dari direktori berikut, dalam urutan prioritas penimpaan yang meningkat:

Hook bundel: dikirim bersama OpenClaw
Hook plugin: hook yang dibundel di dalam plugin yang terpasang
Hook terkelola: ~/.openclaw/hooks/ (dipasang pengguna, dibagikan di seluruh workspace). Direktori tambahan dari hooks.internal.load.extraDirs memiliki prioritas yang sama.
Hook workspace: <workspace>/hooks/ (per agen, dinonaktifkan secara default sampai diaktifkan secara eksplisit)

Hook workspace dapat menambahkan nama hook baru tetapi tidak dapat menimpa hook bundel, terkelola, atau yang disediakan plugin dengan nama yang sama.

Paket hook

Paket hook adalah paket npm yang mengekspor hook melalui openclaw.hooks di package.json. Pasang dengan:

openclaw plugins install <path-or-spec>

Spesifikasi npm hanya untuk registri (nama paket + versi tepat opsional atau dist-tag). Spesifikasi Git/URL/file dan rentang semver ditolak.

Hook bundel

Hook	Peristiwa	Fungsinya
session-memory	`command:new`, `command:reset`	Menyimpan konteks sesi ke `<workspace>/memory/`
bootstrap-extra-files	`agent:bootstrap`	Menyuntikkan file bootstrap tambahan dari pola glob
command-logger	`command`	Mencatat semua perintah ke `~/.openclaw/logs/commands.log`
boot-md	`gateway:startup`	Menjalankan `BOOT.md` saat gateway dimulai

Aktifkan hook bundel apa pun:

openclaw hooks enable <hook-name>

Detail session-memory

Mengekstrak 15 pesan pengguna/asisten terakhir, menghasilkan slug nama file deskriptif melalui LLM, dan menyimpan ke <workspace>/memory/YYYY-MM-DD-slug.md. Memerlukan workspace.dir dikonfigurasi.

Konfigurasi bootstrap-extra-files

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

Jalur diselesaikan relatif terhadap workspace. 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 slash command ke ~/.openclaw/logs/commands.log.

Detail boot-md

Menjalankan BOOT.md dari workspace aktif saat gateway dimulai.

Hook plugin

Plugin dapat mendaftarkan hook melalui Plugin SDK untuk integrasi yang lebih dalam: mencegat pemanggilan tool, memodifikasi prompt, mengontrol alur pesan, dan banyak lagi. Plugin SDK menyediakan 28 hook yang mencakup resolusi model, siklus hidup agen, alur pesan, eksekusi tool, koordinasi subagen, dan siklus hidup gateway. Untuk referensi lengkap hook plugin termasuk before_tool_call, before_agent_reply, before_install, dan semua hook plugin lainnya, lihat Arsitektur Plugin.

Konfigurasi

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

Variabel lingkungan per hook:

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

Direktori hook tambahan:

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

Format konfigurasi array hooks.internal.handlers lama masih didukung untuk kompatibilitas mundur, tetapi hook baru sebaiknya menggunakan sistem berbasis penemuan.

Referensi CLI

# Daftar semua hook (tambahkan --eligible, --verbose, atau --json)
openclaw hooks list

# Tampilkan info terperinci tentang hook
openclaw hooks info <hook-name>

# Tampilkan ringkasan kelayakan
openclaw hooks check

# Aktifkan/nonaktifkan
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

Praktik terbaik

Jaga agar handler tetap cepat. Hooks berjalan selama pemrosesan perintah. Jalankan pekerjaan berat secara fire-and-forget dengan void processInBackground(event).
Tangani error dengan baik. Bungkus operasi berisiko dalam try/catch; jangan melempar error agar handler lain tetap bisa berjalan.
Filter peristiwa lebih awal. Segera return jika tipe/aksi peristiwa tidak relevan.
Gunakan kunci peristiwa yang spesifik. Pilih "events": ["command:new"] daripada "events": ["command"] untuk mengurangi overhead.

Pemecahan masalah

Hook tidak ditemukan

# Verifikasi struktur direktori
ls -la ~/.openclaw/hooks/my-hook/
# Harus menampilkan: HOOK.md, handler.ts

# Daftar semua hook yang ditemukan
openclaw hooks list

Hook tidak memenuhi syarat

openclaw hooks info my-hook

Periksa binary yang hilang (PATH), variabel lingkungan, nilai konfigurasi, atau kompatibilitas OS.

Hook tidak berjalan

Verifikasi bahwa hook diaktifkan: openclaw hooks list
Mulai ulang proses gateway Anda agar hook dimuat ulang.
Periksa log gateway: ./scripts/clawlog.sh | grep hook

Terkait

Referensi CLI: hooks
Webhook
Arsitektur Plugin — referensi lengkap hook plugin
Konfigurasi

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Hooks

Hooks

Mulai cepat

Jenis peristiwa

Menulis hook

Struktur hook

Format HOOK.md

Implementasi handler

Sorotan konteks peristiwa

Penemuan hook

Paket hook

Hook bundel

Detail session-memory

Konfigurasi bootstrap-extra-files

Detail command-logger

Detail boot-md

Hook plugin

Konfigurasi

Referensi CLI

Praktik terbaik

Pemecahan masalah

Hook tidak ditemukan

Hook tidak memenuhi syarat

Hook tidak berjalan

Terkait

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Hooks

​Mulai cepat

​Jenis peristiwa

​Menulis hook

​Struktur hook

​Format HOOK.md

​Implementasi handler

​Sorotan konteks peristiwa

​Penemuan hook

​Paket hook

​Hook bundel

​Detail session-memory

​Konfigurasi bootstrap-extra-files

​Detail command-logger

​Detail boot-md

​Hook plugin

​Konfigurasi

​Referensi CLI

​Praktik terbaik

​Pemecahan masalah

​Hook tidak ditemukan

​Hook tidak memenuhi syarat

​Hook tidak berjalan

​Terkait

Hooks

Mulai cepat

Jenis peristiwa

Menulis hook

Struktur hook

Format HOOK.md

Implementasi handler

Sorotan konteks peristiwa

Penemuan hook

Paket hook

Hook bundel

Detail session-memory

Konfigurasi bootstrap-extra-files

Detail command-logger

Detail boot-md

Hook plugin

Konfigurasi

Referensi CLI

Praktik terbaik

Pemecahan masalah

Hook tidak ditemukan

Hook tidak memenuhi syarat

Hook tidak berjalan

Terkait