Plugin kancaları

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.

​

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

• priority - işleyici sıralaması (daha yüksek olan önce çalışır).
• timeoutMs - isteğe bağlı kanca başına bütçe. Ayarlandığında, kanca çalıştırıcısı bütçe dolduktan sonra ilgili işleyiciyi iptal eder ve yavaş kurulumun veya hatırlama çalışmasının çağıranın yapılandırılmış model zaman aşımını tüketmesine izin vermek yerine bir sonrakine geçer. Bunu atlayarak kanca çalıştırıcısının genel olarak uyguladığı varsayılan gözlem/karar zaman aşımını kullanın.

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

​

Kanca kataloğu

• before_model_resolve - oturum mesajları yüklenmeden önce provider veya modeli geçersiz kıl
• agent_turn_prepare - kuyruğa alınmış Plugin turu eklemelerini tüket ve prompt kancalarından önce aynı tur bağlamı ekle
• before_prompt_build - model çağrısından önce dinamik bağlam veya system prompt metni ekle
• before_agent_start - yalnızca uyumluluk amaçlı birleşik faz; yukarıdaki iki kancayı tercih edin
• before_agent_run - model gönderiminden önce son prompt’u ve oturum mesajlarını incele ve isteğe bağlı olarak çalıştırmayı engelle
• before_agent_reply - model turunu sentetik bir yanıt veya sessizlikle kısa devre yap
• before_agent_finalize - doğal son yanıtı incele ve bir model geçişi daha iste
• agent_end - son mesajları, başarı durumunu ve çalıştırma süresini gözlemle
• heartbeat_prompt_contribution - arka plan izleyicisi ve yaşam döngüsü Plugin’leri için yalnızca Heartbeat bağlamı ekle

• model_call_started / model_call_ended - prompt veya yanıt içeriği olmadan temizlenmiş provider/model çağrısı meta verilerini, zamanlamayı, sonucu ve sınırlandırılmış istek kimliği hash’lerini gözlemle
• llm_input - provider girdisini gözlemle (system prompt, prompt, geçmiş)
• llm_output - provider çıktısını gözlemle

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

• inbound_claim - agent 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 teslimi iptal et
• message_sent - giden teslimin başarısını veya başarısızlığını gözlemle
• before_dispatch - kanal tesliminden önce giden bir dispatch’i incele veya yeniden yaz
• reply_dispatch - son yanıt dispatch pipeline’ına katıl

• session_start / session_end - oturum yaşam döngüsü sınırlarını izle. Olayın reason değeri new, reset, idle, daily, compaction, deleted, shutdown, restart veya unknown değerlerinden biridir. shutdown ve restart değerleri, oturumlar hâlâ etkinken süreç durdurulduğunda veya yeniden başlatıldığında gateway kapatma sonlandırıcısından tetiklenir; böylece aşağı akış Plugin’leri (bellek veya transcript depoları gibi), aksi halde yeniden başlatmalar arasında açık durumda kalacak hayalet satırları sonlandırabilir. Sonlandırıcı sınırlandırılmıştır, bu yüzden yavaş bir Plugin SIGTERM/SIGINT’i engelleyemez.
• 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 - subagent yönlendirmesini ve tamamlanma teslimini koordine et

• gateway_start / gateway_stop - Plugin’e ait servisleri Gateway ile başlat veya durdur
• cron_changed - gateway’e ait Cron yaşam döngüsü değişikliklerini gözlemle (eklendi, güncellendi, kaldırıldı, başlatıldı, tamamlandı, zamanlandı)
• before_install - skill veya Plugin kurulum taramalarını incele ve isteğe bağlı olarak engelle

​

Tool çağrısı ilkesi

• event.toolName
• event.params
• isteğe bağlı event.derivedPaths; apply_patch gibi iyi bilinen tool zarfları için en iyi çabayla ana makineden türetilmiş hedef yol ipuçları içerir; mevcut olduğunda bu yollar eksik olabilir veya tool’un gerçekte dokunacağı alanı olduğundan geniş tahmin edebilir (örneğin bozuk veya kısmi girdilerle)
• isteğe bağlı event.runId
• isteğe bağlı event.toolCallId
• ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (Cron tarafından çalıştırılan işlerde ayarlanır) gibi bağlam alanları ve tanılama ctx.trace

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

​

Tool sonucu kalıcılığı

• OpenClaw, meta verilerin model bağlamına dönüşmemesi için provider yeniden oynatımından ve Compaction girdisinden önce toolResult.details değerini çıkarır.
• Kalıcı oturum girdileri yalnızca sınırlandırılmış details tutar. Fazla büyük details, kompakt bir özet ve persistedDetailsTruncated: true ile değiştirilir.
• tool_result_persist ve before_message_write, son kalıcılık sınırından önce çalışır. Kancalar yine de döndürülen details değerlerini küçük tutmalı ve prompt ile ilgili metni yalnızca details içine koymaktan kaçınmalıdır; modelin görebileceği tool çıktısını content içine koyun.

​

Prompt ve model kancaları

• before_model_resolve: yalnızca güncel prompt’u ve ek meta verilerini alır. providerOverride veya modelOverride döndürün.
• agent_turn_prepare: güncel prompt’u, hazırlanmış oturum mesajlarını ve bu oturum için boşaltılmış tam olarak bir kez kullanılan kuyruğa alınmış eklemeleri alır. prependContext veya appendContext döndürün.
• before_prompt_build: güncel prompt’u ve oturum mesajlarını alır. prependContext, appendContext, systemPrompt, prependSystemContext veya appendSystemContext döndürün.
• heartbeat_prompt_contribution: yalnızca Heartbeat turları için çalışır ve prependContext veya appendContext döndürür. Kullanıcı tarafından başlatılan turları değiştirmeden güncel durumu özetlemesi gereken arka plan izleyicileri için tasarlanmıştır.

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

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

​

Oturum uzantıları ve sonraki tur enjeksiyonları

​

Mesaj hook’ları

• message_received: gelen içeriği, göndereni, threadId, messageId, senderId, isteğe bağlı run/session korelasyonunu ve meta veriyi gözlemleyin.
• message_sending: content öğesini yeniden yazın veya { cancel: true } döndürün.
• message_sent: nihai başarıyı veya başarısızlığı gözlemleyin.

• cancel: true içeren message_sending terminaldir.
• cancel: false içeren message_sending karar yok olarak ele alınır.
• Yeniden yazılan content, daha sonra bir hook teslimatı iptal etmediği sürece daha düşük öncelikli hook’lara devam eder.
• message_sending, iptalle birlikte cancelReason ve sınırlı metadata döndürebilir. Yeni mesaj lifecycle API’leri bunu cancelled_by_message_sending_hook gerekçesiyle bastırılmış teslim sonucu olarak açığa çıkarır; eski doğrudan teslim, uyumluluk için boş sonuç dizisi döndürmeye devam eder.
• message_sent yalnızca gözlem amaçlıdır. Handler hataları günlüğe kaydedilir ve teslim sonucunu değiştirmez.

​

Kurulum hook’ları

​

Gateway lifecycle

​

Yaklaşan kullanımdan kaldırmalar

• inbound_claim ve message_received handler’larındaki düz metin kanal zarfları. 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 (allow-once / allow-always / deny / timeout / cancelled) kullanır.

​

İlgili

• Plugin SDK geçişi - aktif kullanımdan kaldırmalar ve kaldırma zaman çizelgesi
• Plugin oluşturma
• Plugin SDK genel bakışı
• Plugin giriş noktaları
• Dahili hook’lar
• Plugin mimarisi iç yapıları