Plugin hook'ları

​

Hızlı başlangıç

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 },
    );
  },
});

​

Hook kataloğu

• before_model_resolve — oturum mesajları yüklenmeden önce sağlayıcıyı veya modeli geçersiz kıl
• before_prompt_build — model çağrısından önce dinamik bağlam veya sistem prompt metni ekle
• before_agent_start — yalnızca uyumluluk için birleşik aşama; bunun yerine yukarıdaki iki hook’u tercih edin
• before_agent_reply — sentetik bir yanıtla model turunu kısa devreye al veya sustur
• agent_end — son mesajları, başarı durumunu ve çalıştırma süresini gözlemle

• llm_input — sağlayıcı girdisini gözlemle (sistem prompt’u, prompt, geçmiş)
• llm_output — sağlayıcı çıktısını gözlemle

• before_tool_call — araç parametrelerini yeniden yaz, yürütmeyi engelle veya onay iste
• after_tool_call — araç sonuçlarını, hataları ve süreyi gözlemle
• tool_result_persist — araç sonucundan üretilen yardımcı mesajını yeniden yaz
• before_message_write — devam eden bir mesaj yazımını incele veya engelle (nadir)

• inbound_claim — aracı yönlendirmesinden önce gelen bir mesajı sahiplen (sentetik yanıtlar)
• message_received — gelen içeriği, göndereni, thread’i ve meta verileri gözlemle
• message_sending — giden içeriği yeniden yaz veya teslimatı iptal et
• message_sent — giden teslimat başarısını veya hatasını gözlemle
• before_dispatch — kanal devrinden önce giden bir dispatch’i incele veya yeniden yaz
• reply_dispatch — son yanıt-dispatch işlem hattına katıl

• session_start / session_end — oturum yaşam döngüsü sınırlarını izle
• before_compaction / after_compaction — Compaction döngülerini gözlemle veya açıklama ekle
• before_reset — oturum sıfırlama olaylarını gözlemle (/reset, programatik sıfırlamalar)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended — alt aracı yönlendirmesini ve tamamlanma teslimatını koordine et

• gateway_start / gateway_stop — Gateway ile birlikte Plugin’e ait hizmetleri başlat veya durdur
• before_install — Skill veya Plugin kurulum taramalarını incele ve isteğe bağlı olarak engelle

​

Araç çağrısı ilkesi

• event.toolName
• event.params
• isteğe bağlı event.runId
• isteğe bağlı event.toolCallId
• ctx.agentId, ctx.sessionKey, ctx.sessionId ve tanılama amaçlı ctx.trace gibi bağlam alanları

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 nihaidir ve daha düşük öncelikli işleyicileri atlar.
• block: false karar verilmemiş olarak değerlendirilir.
• params, yürütme için araç parametrelerini yeniden yazar.
• requireApproval, aracı çalıştırmasını duraklatır ve kullanıcıya Plugin onayları üzerinden sorar. /approve komutu hem exec hem de Plugin onaylarını onaylayabilir.
• Daha düşük öncelikli bir block: true, daha yüksek öncelikli bir hook onay istemiş olsa bile yine de engelleyebilir.
• onResolution, çözümlenen onay kararını alır — allow-once, allow-always, deny, timeout veya cancelled.

​

Prompt ve model hook’ları

• before_model_resolve: yalnızca geçerli prompt’u ve ek meta verilerini alır. providerOverride veya modelOverride döndürün.
• before_prompt_build: geçerli prompt’u ve oturum mesajlarını alır. prependContext, systemPrompt, prependSystemContext veya appendSystemContext döndürün.

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

​

Mesaj hook’ları

• message_received: gelen içeriği, göndereni, threadId, messageId, senderId, isteğe bağlı çalıştırma/oturum ilişkilendirmesini ve meta verileri gözlemle.
• message_sending: content değerini yeniden yaz veya { cancel: true } döndür.
• message_sent: son başarıyı veya hatayı gözlemle.

• message_sending ile cancel: true nihaidir.
• message_sending ile cancel: false, karar verilmemiş olarak değerlendirilir.
• Yeniden yazılmış content, daha sonraki bir hook teslimatı iptal etmediği sürece daha düşük öncelikli hook’lara iletilmeye devam eder.

​

Kurulum hook’ları

​

Gateway yaşam döngüsü

​

Yaklaşan kullanımdan kaldırmalar

• Düz metin kanal zarfları, inbound_claim ve message_received işleyicilerinde. Düz zarf metnini ayrıştırmak yerine BodyForAgent ve yapılandırılmış kullanıcı bağlam bloklarını okuyun. Bkz. Düz metin kanal zarfları → BodyForAgent.
• before_agent_start uyumluluk için kalır. Yeni Plugin’ler birleşik aşama yerine before_model_resolve ve before_prompt_build kullanmalıdır.
• before_tool_call içindeki onResolution artık serbest biçimli string yerine tipli PluginApprovalResolution birleşimini kullanır (allow-once / allow-always / deny / timeout / cancelled).

​

İlgili

• Plugin SDK migration — etkin kullanımdan kaldırmalar ve kaldırma zaman çizelgesi
• Plugin oluşturma
• Plugin SDK genel bakışı
• Plugin giriş noktaları
• İç hook’lar
• Plugin architecture internals