Plugin kancaları

​

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ı hook başına bütçe. Ayarlandığında, hook çalıştırıcısı bütçe dolduktan sonra o işleyiciyi iptal eder ve yavaş kurulum ya da hatırlama işinin çağıranın yapılandırılmış model zaman aşımını tüketmesine izin vermek yerine sonrakiyle devam eder. Hook çalıştırıcısının genel olarak uyguladığı varsayılan gözlem/karar zaman aşımını kullanmak için bunu atlayın.

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

​

Hook kataloğu

• before_model_resolve - oturum mesajları yüklenmeden önce sağlayıcıyı veya modeli geçersiz kılın
• agent_turn_prepare - kuyruğa alınmış Plugin tur enjeksiyonlarını tüketin ve istem hook’larından önce aynı tura bağlam ekleyin
• before_prompt_build - model çağrısından önce dinamik bağlam veya sistem istemi metni ekleyin
• before_agent_start - yalnızca uyumluluk amaçlı birleşik aşama; yukarıdaki iki hook’u tercih edin
• before_agent_run - model gönderiminden önce son istemi ve oturum mesajlarını inceleyin ve isteğe bağlı olarak çalıştırmayı engelleyin
• before_agent_reply - model turunu sentetik bir yanıtla veya sessizlikle kısa devre edin
• before_agent_finalize - doğal son yanıtı inceleyin ve bir model geçişi daha isteyin
• agent_end - son mesajları, başarı durumunu ve çalıştırma süresini gözlemleyin
• heartbeat_prompt_contribution - arka plan izleyici ve yaşam döngüsü Plugin’leri için yalnızca Heartbeat bağlamı ekleyin

• model_call_started / model_call_ended - istem veya yanıt içeriği olmadan temizlenmiş sağlayıcı/model çağrısı meta verilerini, zamanlamayı, sonucu ve sınırlı istek kimliği hash’lerini gözlemleyin
• llm_input - sağlayıcı girdisini (sistem istemi, istem, geçmiş) gözlemleyin
• llm_output - sağlayıcı çıktısını, kullanımı ve mevcut olduğunda çözümlenmiş contextTokenBudget değerini gözlemleyin

• before_tool_call - araç parametrelerini yeniden yazın, yürütmeyi engelleyin veya onay isteyin
• after_tool_call - araç sonuçlarını, hataları ve süreyi gözlemleyin
• resolve_exec_env - Plugin’in sahip olduğu ortam değişkenlerini exec için katkıda bulunun
• tool_result_persist - araç sonucundan üretilen asistan mesajını yeniden yazın
• before_message_write - devam eden bir mesaj yazımını inceleyin veya engelleyin (nadir)

• inbound_claim - ajan yönlendirmesinden önce gelen bir mesajı sahiplenin (sentetik yanıtlar)
• message_received — gelen içeriği, göndereni, iş parçacığını ve meta verileri gözlemleyin
• message_sending — giden içeriği yeniden yazın veya teslimatı iptal edin
• reply_payload_sending — teslimattan önce normalleştirilmiş yanıt yüklerini değiştirin veya iptal edin
• message_sent — giden teslimat başarısını veya hatasını gözlemleyin
• before_dispatch - kanal devrinden önce giden bir dispatch’i inceleyin veya yeniden yazın
• reply_dispatch - son yanıt dispatch hattına katılın

• session_start / session_end - oturum yaşam döngüsü sınırlarını takip edin. 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 transkript depoları gibi), aksi halde yeniden başlatmalar arasında açık durumda kalacak hayalet satırları sonlandırabilir. Sonlandırıcı sınırlıdır, bu nedenle yavaş bir Plugin SIGTERM/SIGINT’i engelleyemez.
• before_compaction / after_compaction - Compaction döngülerini gözlemleyin veya açıklama ekleyin
• before_reset - oturum sıfırlama olaylarını gözlemleyin (/reset, programatik sıfırlamalar)

• subagent_spawned / subagent_ended - alt ajan başlatmayı ve tamamlanmayı gözlemleyin.
• subagent_delivery_target - çekirdek oturum bağlaması bir rota yansıtamadığında tamamlama teslimi için uyumluluk hook’u.
• subagent_spawning - kullanımdan kaldırılmış uyumluluk hook’u. Çekirdek artık subagent_spawned tetiklenmeden önce kanal oturum bağlama bağdaştırıcıları üzerinden thread: true alt ajan bağlamalarını hazırlar.
• subagent_spawned, OpenClaw başlatmadan önce alt oturumun yerel modelini çözdüğünde resolvedModel ve resolvedProvider içerir.
• subagent_ended, targetSessionKey (kimlik — bu, subagent_spawned.childSessionKey ile eşleşir), targetKind ("subagent" veya "acp"), reason, isteğe bağlı outcome ("ok", "error", "timeout", "killed", "reset" veya "deleted"), isteğe bağlı error, runId, endedAt, accountId ve sendFarewell taşır. agentId veya childSessionKey içermez; karşılık gelen subagent_spawned olayıyla ilişkilendirmek için targetSessionKey kullanın.

• gateway_start / gateway_stop - Gateway ile Plugin’in sahip olduğu hizmetleri başlatın veya durdurun
• deactivate - gateway_stop için kullanımdan kaldırılmış uyumluluk takma adı; yeni Plugin’lerde gateway_stop kullanın
• cron_changed - Gateway’in sahip olduğu Cron yaşam döngüsü değişikliklerini gözlemleyin (eklendi, güncellendi, kaldırıldı, başlatıldı, tamamlandı, zamanlandı)
• before_install - yüklenmiş bir Plugin çalışma zamanından hazırlanmış Skills veya Plugin kurulum malzemesini inceleyin

​

Çalışma zamanı hook’larında hata ayıklama

​

Araç çağrısı ilkesi

• event.toolName
• event.params
• isteğe bağlı event.toolKind ve event.toolInputKind; bilerek aynı adları paylaşan araçlar için host tarafından yetkili ayırt ediciler. Örneğin, dış kod modu exec çağrıları toolKind: "code_mode_exec" kullanır ve giriş dili bilindiğinde toolInputKind: "javascript" | "typescript" içerir
• isteğe bağlı event.derivedPaths; apply_patch gibi iyi bilinen araç zarfları için host tarafından en iyi çabayla türetilmiş hedef yol ipuçlarını içerir. Mevcut olduğunda bu yollar eksik olabilir veya aracın gerçekten dokunacağı şeyi fazla yaklaşık gösterebilir (örneğin hatalı biçimlendirilmiş 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 sürülen çalıştırmalarda ayarlanır), ctx.toolKind, ctx.toolInputKind ve tanılama 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";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "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 değerlendirilir.
• params, yürütme için araç parametrelerini yeniden yazar.
• requireApproval, ajan çalıştırmasını duraklatır ve Plugin onayları üzerinden kullanıcıya sorar. /approve komutu hem exec hem de Plugin onaylarını onaylayabilir. Codex app-server report-mode yerel PreToolUse aktarımlarında bu, eşleşen app-server onay isteğine ertelenir; bkz. Codex harness çalışma zamanı.
• Daha düşük öncelikli bir block: true, daha yüksek öncelikli bir hook onay istemiş olsa bile hâlâ engelleyebilir.
• onResolution, çözümlenmiş onay kararını alır - allow-once, allow-always, deny, timeout veya cancelled.

​

Exec ortamı hook’u

• event.sessionKey
• event.toolName, şu anda her zaman "exec"
• event.host, "gateway", "sandbox" veya "node" değerlerinden biri
• ctx.agentId, ctx.sessionKey, ctx.messageProvider ve ctx.channelId gibi bağlam alanları

​

Araç sonucu kalıcılığı

• OpenClaw, meta verilerin model bağlamına dönüşmemesi için provider yeniden oynatmasından ve compaction girdisinden önce toolResult.details alanını çıkarır.
• Kalıcı session girdileri yalnızca sınırlandırılmış details tutar. Aşırı büyük ayrıntılar 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. Hook’lar yine de döndürülen details alanını küçük tutmalı ve prompt ile ilgili metni yalnızca details içine koymaktan kaçınmalıdır; modelin görebileceği araç çıktısını content içine koyun.

​

Prompt ve model hook’ları

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

• ctx.senderId — kanal kapsamlı gönderen ID’si (ör. Feishu open_id, Discord kullanıcı ID’si). Çalışma, bilinen gönderen meta verilerine sahip bir kullanıcı mesajından kaynaklandığında doldurulur.
• ctx.chatId — taşıma yerel konuşma tanımlayıcısı (ör. Feishu chat_id, Telegram chat_id). Kaynak kanal yerel bir konuşma ID’si sağladığında doldurulur.
• ctx.channelContext.sender.id — ctx.senderId ile aynı gönderen ID’si; plugin’lerin kanala özgü alanlarla genişletebileceği, kanal sahipli bir nesnenin altında bulunur.
• ctx.channelContext.chat.id — ctx.chatId ile aynı konuşma ID’si; plugin’lerin kanala özgü alanlarla genişletebileceği, kanal sahipli bir nesnenin altında bulunur.

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
        }
      }
    }
  }
}

​

Session genişletmeleri ve sonraki turn enjeksiyonları

​

Mesaj hook’ları

• message_received: gelen içeriği, göndereni, threadId, messageId, senderId, isteğe bağlı çalışma/session korelasyonunu ve meta verileri gözlemler.
• message_sending: content değerini yeniden yazar veya { cancel: true } döndürür.
• reply_payload_sending: normalleştirilmiş ReplyPayload nesnelerini (presentation, delivery, medya ref’leri ve metin dahil) yeniden yazar veya { cancel: true } döndürür.
• message_sent: son başarıyı veya hatayı gözlemler.

• cancel: true ile message_sending terminaldir.
• cancel: false ile message_sending karar yok olarak değerlendirilir.
• Yeniden yazılan content, daha sonra gelen bir hook teslimatı iptal etmediği sürece daha düşük öncelikli hook’lara devam eder.
• reply_payload_sending, yük normalleştirmesinden sonra ve kanal teslimatından önce çalışır; kaynak kanala geri yönlendirilen yanıtlar buna dahildir. İşleyiciler sıralı çalışır ve her işleyici, daha yüksek öncelikli işleyiciler tarafından üretilen en son yükü görür.
• reply_payload_sending yükleri, trustedLocalMedia gibi çalışma zamanı güven işaretlerini açığa çıkarmaz; plugin’ler yük şeklini düzenleyebilir ancak yerel medya güveni veremez.
• message_sending, bir iptalle birlikte cancelReason ve sınırlı metadata döndürebilir. Yeni ileti yaşam döngüsü API’leri bunu cancelled_by_message_sending_hook nedeni ile bastırılmış teslimat sonucu olarak açığa çıkarır; eski doğrudan teslimat, uyumluluk için boş sonuç dizisi döndürmeye devam eder.
• message_sent yalnızca gözlem amaçlıdır. İşleyici hataları günlüğe kaydedilir ve teslimat sonucunu değiştirmez.

​

Kurulum hook’ları

​

Gateway yaşam döngüsü

​

Yaklaşan kullanımdan kaldırmalar

• inbound_claim ve message_received işleyicilerindeki 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 faz yerine before_model_resolve ve before_prompt_build kullanmalıdır.
• subagent_spawning eski plugin’lerle uyumluluk için kalır, ancak yeni plugin’ler buradan thread yönlendirmesi döndürmemelidir. Core, subagent_spawned tetiklenmeden önce kanal oturum bağlama adaptörleri üzerinden thread: true subagent bağlamalarını hazırlar.
• deactivate, 2026-08-16 sonrasına kadar kullanımdan kaldırılmış bir temizleme uyumluluk takma adı olarak kalır. Yeni plugin’ler gateway_stop kullanmalıdır.
• before_tool_call içindeki onResolution artık serbest biçimli bir 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ç işleyişi