Kait Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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 penangan (nilai lebih tinggi berjalan lebih dulu).
• timeoutMs - anggaran opsional per hook. Jika ditetapkan, runner hook membatalkan penangan tersebut setelah anggaran berlalu dan melanjutkan ke penangan berikutnya, alih-alih membiarkan penyiapan lambat atau pekerjaan recall menghabiskan timeout model yang dikonfigurasi pemanggil. Hilangkan untuk menggunakan timeout observasi/keputusan default yang diterapkan runner hook secara generik.

{
  "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 diantrekan dan tambahkan konteks giliran yang sama sebelum hook prompt
• before_prompt_build - tambahkan konteks dinamis atau teks prompt sistem sebelum pemanggilan model
• before_agent_start - fase gabungan hanya untuk kompatibilitas; utamakan dua hook di atas
• before_agent_run - periksa prompt final dan pesan sesi sebelum pengiriman model dan opsional blokir eksekusi
• before_agent_reply - pintas giliran model dengan balasan sintetis atau senyap
• before_agent_finalize - periksa jawaban akhir natural dan minta satu lintasan model lagi
• agent_end - amati pesan final, status sukses, dan durasi eksekusi
• heartbeat_prompt_contribution - tambahkan konteks khusus Heartbeat untuk Plugin pemantau latar belakang dan siklus hidup

• model_call_started / model_call_ended - amati metadata pemanggilan penyedia/model yang disanitasi, timing, hasil, dan hash id permintaan berbatas tanpa konten prompt atau respons
• llm_input - amati input penyedia (prompt sistem, prompt, riwayat)
• llm_output - amati output penyedia

• before_tool_call - tulis ulang parameter alat, blokir eksekusi, atau minta persetujuan
• after_tool_call - amati hasil alat, error, dan durasi
• 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 - amati konten masuk, pengirim, thread, dan metadata
• message_sending - tulis ulang konten keluar atau batalkan pengiriman
• message_sent - amati keberhasilan atau kegagalan pengiriman keluar
• before_dispatch - periksa atau tulis ulang dispatch keluar sebelum handoff kanal
• reply_dispatch - berpartisipasi 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 dibiarkan dalam status terbuka lintas restart. Finalizer dibatasi sehingga Plugin yang lambat tidak dapat memblokir SIGTERM/SIGINT.
• before_compaction / after_compaction - amati atau anotasi siklus Compaction
• before_reset - amati peristiwa reset sesi (/reset, reset programatik)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - koordinasikan perutean subagen dan pengiriman penyelesaian

• gateway_start / gateway_stop - mulai atau hentikan layanan milik Plugin bersama Gateway
• cron_changed - amati perubahan siklus hidup Cron milik gateway (ditambahkan, diperbarui, dihapus, dimulai, selesai, dijadwalkan)
• before_install - periksa pemindaian instalasi skill atau Plugin dan opsional blokir

​

Kebijakan pemanggilan alat

• event.toolName
• event.params
• opsional event.derivedPaths, berisi petunjuk jalur target turunan host berbasis upaya terbaik untuk envelope alat yang dikenal seperti apply_patch; jika ada, jalur ini mungkin tidak lengkap atau mungkin memperkirakan berlebihan apa yang sebenarnya akan disentuh alat (misalnya, dengan input yang cacat atau parsial)
• opsional event.runId
• opsional event.toolCallId
• field konteks seperti ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (ditetapkan pada eksekusi yang digerakkan Cron), 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";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true bersifat terminal dan melewati penangan berprioritas lebih rendah.
• block: false diperlakukan sebagai tanpa keputusan.
• params menulis ulang parameter alat untuk eksekusi.
• requireApproval menjeda eksekusi agen dan meminta persetujuan pengguna melalui persetujuan Plugin. Perintah /approve dapat menyetujui persetujuan exec maupun Plugin.
• block: true berprioritas lebih rendah masih dapat memblokir setelah hook berprioritas lebih tinggi meminta persetujuan.
• onResolution menerima keputusan persetujuan yang terselesaikan - allow-once, allow-always, deny, timeout, atau cancelled.

​

Persistensi hasil alat

• OpenClaw menghapus toolResult.details sebelum replay penyedia dan input Compaction sehingga metadata tidak menjadi konteks model.
• Entri sesi yang dipersistensikan hanya menyimpan details berbatas. 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 alat yang terlihat model di content.

​

Hook prompt dan model

• before_model_resolve: hanya menerima prompt saat ini dan metadata lampiran. Kembalikan providerOverride atau modelOverride.
• agent_turn_prepare: menerima prompt saat ini, pesan sesi yang disiapkan, dan injeksi antrean tepat-sekali apa pun 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: berjalan hanya untuk giliran Heartbeat dan mengembalikan prependContext atau appendContext. Ini ditujukan untuk pemantau latar belakang yang perlu merangkum status saat ini tanpa mengubah giliran yang diprakarsai pengguna.

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: amati konten masuk, pengirim, threadId, messageId, senderId, korelasi run/sesi opsional, dan metadata.
• message_sending: tulis ulang content atau kembalikan { cancel: true }.
• message_sent: amati keberhasilan atau kegagalan final.

• message_sending dengan cancel: true bersifat terminal.
• message_sending dengan cancel: false diperlakukan sebagai tanpa keputusan.
• content yang ditulis ulang berlanjut ke hook prioritas lebih rendah kecuali hook berikutnya membatalkan pengiriman.
• message_sending dapat mengembalikan cancelReason dan metadata terbatas bersama 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 untuk kompatibilitas.
• message_sent hanya untuk observasi. Kegagalan handler dicatat dan tidak mengubah hasil pengiriman.

​

Hook instalasi

​

Siklus hidup Gateway

​

Penghentian mendatang

• Envelope channel teks biasa dalam handler inbound_claim dan message_received. Baca BodyForAgent dan blok konteks pengguna terstruktur alih-alih mengurai teks envelope datar. Lihat Envelope channel teks biasa → BodyForAgent.
• before_agent_start tetap ada untuk kompatibilitas. Plugin baru sebaiknya menggunakan before_model_resolve dan before_prompt_build alih-alih fase gabungan.
• 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 - penghentian aktif dan jadwal penghapusan
• Membangun plugins
• Ikhtisar Plugin SDK
• Titik masuk Plugin
• Hook internal
• Internal arsitektur Plugin