Hook Plugin

​

Mulai cepat

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});

• priority - pengurutan handler (nilai lebih tinggi berjalan lebih dulu).
• timeoutMs - anggaran opsional per hook. Jika diatur, runner hook membatalkan handler tersebut setelah anggaran berlalu dan melanjutkan ke handler berikutnya, alih-alih membiarkan setup yang lambat atau pekerjaan recall menghabiskan timeout model yang dikonfigurasi pemanggil. Hilangkan untuk menggunakan timeout observasi/keputusan default yang diterapkan runner hook secara umum.

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}

​

Katalog hook

• before_model_resolve - override penyedia atau model sebelum pesan sesi dimuat
• agent_turn_prepare - konsumsi injeksi giliran Plugin yang mengantre dan tambahkan konteks giliran yang sama sebelum hook prompt
• before_prompt_build - tambahkan konteks dinamis atau teks prompt sistem sebelum panggilan model
• before_agent_start - fase gabungan khusus kompatibilitas; utamakan dua hook di atas
• before_agent_run - periksa prompt final dan pesan sesi sebelum pengiriman model dan secara opsional blokir run
• before_agent_reply - pintas giliran model dengan balasan sintetis atau diam
• before_agent_finalize - periksa jawaban final alami dan minta satu pass model lagi
• agent_end - observasi pesan final, status sukses, dan durasi run
• heartbeat_prompt_contribution - tambahkan konteks khusus Heartbeat untuk Plugin pemantau latar belakang dan siklus hidup

• model_call_started / model_call_ended - observasi metadata panggilan penyedia/model yang disanitasi, waktu, hasil, dan hash id permintaan yang dibatasi tanpa konten prompt atau respons
• llm_input - observasi input penyedia (prompt sistem, prompt, riwayat)
• llm_output - observasi output penyedia, penggunaan, dan contextTokenBudget yang diselesaikan jika tersedia

• before_tool_call - tulis ulang parameter alat, blokir eksekusi, atau wajibkan persetujuan
• after_tool_call - observasi hasil alat, error, dan durasi
• resolve_exec_env - kontribusikan variabel lingkungan milik Plugin ke exec
• tool_result_persist - tulis ulang pesan asisten yang dihasilkan dari hasil alat
• before_message_write - periksa atau blokir penulisan pesan yang sedang berlangsung (jarang)

• inbound_claim - klaim pesan masuk sebelum perutean agen (balasan sintetis)
• message_received — observasi konten masuk, pengirim, thread, dan metadata
• message_sending — tulis ulang konten keluar atau batalkan pengiriman
• reply_payload_sending — mutasi atau batalkan payload balasan yang dinormalisasi sebelum pengiriman
• message_sent — observasi keberhasilan atau kegagalan pengiriman keluar
• before_dispatch - periksa atau tulis ulang dispatch keluar sebelum handoff kanal
• reply_dispatch - ikut serta dalam pipeline dispatch balasan final

• session_start / session_end - lacak batas siklus hidup sesi. reason peristiwa adalah salah satu dari new, reset, idle, daily, compaction, deleted, shutdown, restart, atau unknown. Nilai shutdown dan restart dipicu dari finalizer shutdown Gateway ketika proses dihentikan atau dimulai ulang saat sesi masih aktif, sehingga Plugin hilir (seperti penyimpanan memori atau transkrip) dapat memfinalisasi baris ghost yang jika tidak akan tertinggal dalam keadaan terbuka lintas restart. Finalizer dibatasi sehingga Plugin yang lambat tidak dapat memblokir SIGTERM/SIGINT.
• before_compaction / after_compaction - observasi atau anotasi siklus Compaction
• before_reset - observasi peristiwa reset sesi (/reset, reset terprogram)

• subagent_spawned / subagent_ended - observasi peluncuran dan penyelesaian subagen.
• subagent_delivery_target - hook kompatibilitas untuk pengiriman penyelesaian ketika tidak ada binding sesi inti yang dapat memproyeksikan rute.
• subagent_spawning - hook kompatibilitas yang dideprekasi. Inti sekarang menyiapkan binding subagen thread: true melalui adaptor binding sesi kanal sebelum subagent_spawned dipicu.
• subagent_spawned menyertakan resolvedModel dan resolvedProvider ketika OpenClaw telah menyelesaikan model native sesi anak sebelum peluncuran.
• subagent_ended membawa targetSessionKey (identitas — ini cocok dengan subagent_spawned.childSessionKey), targetKind ("subagent" atau "acp"), reason, outcome opsional ("ok", "error", "timeout", "killed", "reset", atau "deleted"), error opsional, runId, endedAt, accountId, dan sendFarewell. Ini tidak menyertakan agentId atau childSessionKey; gunakan targetSessionKey untuk mengorelasikan dengan peristiwa subagent_spawned yang sesuai.

• gateway_start / gateway_stop - mulai atau hentikan layanan milik Plugin bersama Gateway
• deactivate - alias kompatibilitas yang dideprekasi untuk gateway_stop; gunakan gateway_stop di Plugin baru
• cron_changed - observasi perubahan siklus hidup Cron milik Gateway (ditambahkan, diperbarui, dihapus, dimulai, selesai, dijadwalkan)
• before_install - periksa material instalasi Skills atau Plugin yang distaging dari runtime Plugin yang dimuat

​

Debug hook runtime

​

Kebijakan panggilan alat

• event.toolName
• event.params
• event.toolKind dan event.toolInputKind opsional, diskriminator otoritatif host untuk alat yang sengaja berbagi nama; misalnya, panggilan exec mode kode luar menggunakan toolKind: "code_mode_exec" dan menyertakan toolInputKind: "javascript" | "typescript" ketika bahasa input diketahui
• event.derivedPaths opsional, berisi petunjuk path target turunan host secara upaya terbaik untuk envelope alat yang dikenal seperti apply_patch; ketika ada, path ini mungkin tidak lengkap atau mungkin melebih-lebihkan apa yang sebenarnya akan disentuh alat (misalnya, dengan input yang salah bentuk atau parsial)
• event.runId opsional
• event.toolCallId opsional
• field konteks seperti ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (diatur pada run yang digerakkan Cron), ctx.toolKind, ctx.toolInputKind, dan ctx.trace diagnostik

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true bersifat terminal dan melewati handler berprioritas lebih rendah.
• block: false diperlakukan sebagai tanpa keputusan.
• params menulis ulang parameter alat untuk eksekusi.
• requireApproval menjeda run agen dan meminta pengguna melalui persetujuan Plugin. Perintah /approve dapat menyetujui persetujuan exec maupun Plugin. Dalam relay PreToolUse native mode laporan app-server Codex, ini ditunda ke permintaan persetujuan app-server yang cocok; lihat runtime harness Codex.
• block: true berprioritas lebih rendah masih dapat memblokir setelah hook berprioritas lebih tinggi meminta persetujuan.
• onResolution menerima keputusan persetujuan yang diselesaikan - allow-once, allow-always, deny, timeout, atau cancelled.

​

Hook lingkungan exec

• event.sessionKey
• event.toolName, saat ini selalu "exec"
• event.host, salah satu dari "gateway", "sandbox", atau "node"
• field konteks seperti ctx.agentId, ctx.sessionKey, ctx.messageProvider, dan ctx.channelId

​

Persistensi hasil tool

• OpenClaw menghapus toolResult.details sebelum replay provider dan input compaction agar metadata tidak menjadi konteks model.
• Entri sesi yang dipersistensikan hanya menyimpan details yang dibatasi. Detail yang terlalu besar diganti dengan ringkasan ringkas dan persistedDetailsTruncated: true.
• tool_result_persist dan before_message_write berjalan sebelum batas persistensi final. Hook tetap harus menjaga details yang dikembalikan tetap kecil dan menghindari penempatan teks yang relevan dengan prompt hanya di details; letakkan output tool yang terlihat model di content.

​

Hook prompt dan model

• before_model_resolve: hanya menerima prompt saat ini dan metadata attachment. Kembalikan providerOverride atau modelOverride.
• agent_turn_prepare: menerima prompt saat ini, pesan sesi yang sudah disiapkan, dan setiap injeksi antrean tepat-sekali yang dikuras untuk sesi ini. Kembalikan prependContext atau appendContext.
• before_prompt_build: menerima prompt saat ini dan pesan sesi. Kembalikan prependContext, appendContext, systemPrompt, prependSystemContext, atau appendSystemContext.
• heartbeat_prompt_contribution: hanya berjalan untuk giliran heartbeat dan mengembalikan prependContext atau appendContext. Ini ditujukan untuk monitor latar belakang yang perlu merangkum status saat ini tanpa mengubah giliran yang diinisiasi pengguna.

• ctx.senderId — ID pengirim dalam cakupan channel (mis. Feishu open_id, ID pengguna Discord). Diisi saat run berasal dari pesan pengguna dengan metadata pengirim yang diketahui.
• ctx.chatId — pengidentifikasi percakapan native transport (mis. Feishu chat_id, Telegram chat_id). Diisi saat channel asal menyediakan ID percakapan native.
• ctx.channelContext.sender.id — ID pengirim yang sama dengan ctx.senderId, di bawah objek milik channel yang dapat diperluas plugin dengan field khusus channel.
• ctx.channelContext.chat.id — ID percakapan yang sama dengan ctx.chatId, di bawah objek milik channel yang dapat diperluas plugin dengan field khusus channel.

declare module "openclaw/plugin-sdk/channel-inbound" {
  interface PluginHookChannelSenderContext {
    unionId?: string;
    userId?: string;
  }
}

buildChannelInboundEventContext({
  // ...
  channelContext: {
    sender: { id: senderOpenId, unionId, userId },
    chat: { id: chatId },
  },
});

type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

​

Ekstensi sesi dan injeksi giliran berikutnya

​

Hook pesan

• message_received: mengamati konten inbound, pengirim, threadId, messageId, senderId, korelasi run/sesi opsional, dan metadata.
• message_sending: menulis ulang content atau mengembalikan { cancel: true }.
• reply_payload_sending: menulis ulang objek ReplyPayload yang dinormalisasi (termasuk presentation, delivery, referensi media, dan teks) atau mengembalikan { cancel: true }.
• message_sent: mengamati keberhasilan atau kegagalan final.

• message_sending dengan cancel: true bersifat terminal.
• message_sending dengan cancel: false diperlakukan sebagai tanpa keputusan.
• content yang ditulis ulang terus diteruskan ke hook berprioritas lebih rendah kecuali hook berikutnya membatalkan pengiriman.
• reply_payload_sending berjalan setelah normalisasi payload dan sebelum pengiriman channel, termasuk balasan yang dirutekan kembali ke channel asal. Handler berjalan berurutan dan setiap handler melihat payload terbaru yang dihasilkan oleh handler berprioritas lebih tinggi.
• Payload reply_payload_sending tidak mengekspos penanda kepercayaan runtime seperti trustedLocalMedia; plugin dapat mengedit bentuk payload tetapi tidak dapat memberikan kepercayaan media lokal.
• message_sending dapat mengembalikan cancelReason dan metadata terbatas dengan pembatalan. API siklus hidup pesan baru mengekspos ini sebagai hasil pengiriman yang ditekan dengan alasan cancelled_by_message_sending_hook; pengiriman langsung legacy tetap mengembalikan array hasil kosong demi kompatibilitas.
• message_sent hanya untuk observasi. Kegagalan handler dicatat dan tidak mengubah hasil pengiriman.

​

Hook instalasi

​

Siklus hidup Gateway

​

Depresiasi mendatang

• Envelope channel teks biasa di handler inbound_claim dan message_received. Baca BodyForAgent dan blok konteks pengguna terstruktur alih-alih mem-parsing teks envelope datar. Lihat Envelope channel teks biasa → BodyForAgent.
• before_agent_start tetap ada demi kompatibilitas. Plugin baru sebaiknya menggunakan before_model_resolve dan before_prompt_build alih-alih fase gabungan.
• subagent_spawning tetap ada demi kompatibilitas dengan plugin lama, tetapi plugin baru tidak boleh mengembalikan perutean thread darinya. Core menyiapkan binding subagent thread: true melalui adapter binding sesi channel sebelum subagent_spawned dipicu.
• deactivate tetap ada sebagai alias kompatibilitas pembersihan yang didepresiasi hingga setelah 2026-08-16. Plugin baru sebaiknya menggunakan gateway_stop.
• onResolution dalam before_tool_call kini menggunakan union bertipe PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) alih-alih string bentuk bebas.

​

Terkait

• Migrasi Plugin SDK - depresiasi aktif dan linimasa penghapusan
• Membangun plugin
• Ikhtisar Plugin SDK
• Titik masuk Plugin
• Hook internal
• Internal arsitektur Plugin