Móc nối của Plugin

Documentation Index

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

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

​

Bắt đầu nhanh

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 — thứ tự trình xử lý (cao hơn chạy trước).
• timeoutMs — ngân sách tùy chọn cho từng hook. Khi được đặt, trình chạy hook hủy trình xử lý đó sau khi hết ngân sách và tiếp tục với trình xử lý tiếp theo, thay vì để tác vụ thiết lập chậm hoặc truy xuất hồi ức tiêu tốn thời gian chờ model đã cấu hình của bên gọi. Bỏ qua để dùng thời gian chờ quan sát/quyết định mặc định mà trình chạy hook áp dụng chung.

​

Danh mục hook

• before_model_resolve — ghi đè provider hoặc model trước khi thông điệp phiên được tải
• agent_turn_prepare — tiêu thụ các lần chèn lượt plugin đang xếp hàng và thêm ngữ cảnh cùng lượt trước các hook prompt
• before_prompt_build — thêm ngữ cảnh động hoặc văn bản system prompt trước lệnh gọi model
• before_agent_start — pha kết hợp chỉ để tương thích; ưu tiên hai hook ở trên
• before_agent_reply — rút ngắn lượt model bằng phản hồi tổng hợp hoặc im lặng
• before_agent_finalize — kiểm tra câu trả lời cuối tự nhiên và yêu cầu thêm một lượt model nữa
• agent_end — quan sát các thông điệp cuối, trạng thái thành công và thời lượng chạy
• heartbeat_prompt_contribution — thêm ngữ cảnh chỉ dành cho Heartbeat cho plugin giám sát nền và vòng đời

• model_call_started / model_call_ended — quan sát siêu dữ liệu lệnh gọi provider/model đã được làm sạch, thời gian, kết quả và mã băm request-id giới hạn mà không có nội dung prompt hoặc phản hồi
• llm_input — quan sát đầu vào provider (system prompt, prompt, lịch sử)
• llm_output — quan sát đầu ra provider

• before_tool_call — viết lại tham số công cụ, chặn thực thi hoặc yêu cầu phê duyệt
• after_tool_call — quan sát kết quả công cụ, lỗi và thời lượng
• tool_result_persist — viết lại thông điệp assistant được tạo từ kết quả công cụ
• before_message_write — kiểm tra hoặc chặn thao tác ghi thông điệp đang diễn ra (hiếm gặp)

• inbound_claim — nhận xử lý một tin nhắn đến trước khi định tuyến agent (phản hồi tổng hợp)
• message_received — quan sát nội dung đến, người gửi, luồng và siêu dữ liệu
• message_sending — viết lại nội dung gửi đi hoặc hủy phân phối
• message_sent — quan sát việc phân phối gửi đi thành công hoặc thất bại
• before_dispatch — kiểm tra hoặc viết lại một dispatch gửi đi trước khi bàn giao cho kênh
• reply_dispatch — tham gia vào pipeline dispatch phản hồi cuối

• session_start / session_end — theo dõi các ranh giới vòng đời phiên
• before_compaction / after_compaction — quan sát hoặc chú thích các chu kỳ Compaction
• before_reset — quan sát sự kiện đặt lại phiên (/reset, đặt lại theo chương trình)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended — điều phối định tuyến subagent và phân phối khi hoàn tất

• gateway_start / gateway_stop — khởi động hoặc dừng các dịch vụ do plugin sở hữu cùng với Gateway
• cron_changed — quan sát các thay đổi vòng đời Cron do gateway sở hữu (đã thêm, đã cập nhật, đã xóa, đã bắt đầu, đã hoàn tất, đã lên lịch)
• before_install — kiểm tra lượt quét cài đặt skill hoặc plugin và tùy chọn chặn

​

Chính sách lệnh gọi công cụ

• event.toolName
• event.params
• event.runId tùy chọn
• event.toolCallId tùy chọn
• các trường ngữ cảnh như ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (được đặt trên các lượt chạy do Cron điều khiển), và ctx.trace chẩn đoán

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 là quyết định kết thúc và bỏ qua các trình xử lý có mức ưu tiên thấp hơn.
• block: false được coi là không có quyết định.
• params viết lại tham số công cụ để thực thi.
• requireApproval tạm dừng lượt chạy agent và hỏi người dùng thông qua phê duyệt plugin. Lệnh /approve có thể phê duyệt cả phê duyệt exec và plugin.
• Một block: true có mức ưu tiên thấp hơn vẫn có thể chặn sau khi hook có mức ưu tiên cao hơn đã yêu cầu phê duyệt.
• onResolution nhận quyết định phê duyệt đã phân giải — allow-once, allow-always, deny, timeout, hoặc cancelled.

​

Lưu bền kết quả công cụ

• OpenClaw loại bỏ toolResult.details trước khi phát lại cho provider và đầu vào Compaction để siêu dữ liệu không trở thành ngữ cảnh model.
• Các mục phiên đã lưu bền chỉ giữ details có giới hạn. Details quá lớn được thay bằng tóm tắt gọn và persistedDetailsTruncated: true.
• tool_result_persist và before_message_write chạy trước giới hạn lưu bền cuối cùng. Hook vẫn nên giữ details trả về ở mức nhỏ và tránh đặt văn bản liên quan đến prompt chỉ trong details; đặt đầu ra công cụ mà model nhìn thấy trong content.

​

Hook prompt và model

• before_model_resolve: chỉ nhận prompt hiện tại và siêu dữ liệu tệp đính kèm. Trả về providerOverride hoặc modelOverride.
• agent_turn_prepare: nhận prompt hiện tại, thông điệp phiên đã chuẩn bị, và mọi lần chèn xếp hàng đúng một lần đã được rút cho phiên này. Trả về prependContext hoặc appendContext.
• before_prompt_build: nhận prompt hiện tại và thông điệp phiên. Trả về prependContext, appendContext, systemPrompt, prependSystemContext, hoặc appendSystemContext.
• heartbeat_prompt_contribution: chỉ chạy cho các lượt Heartbeat và trả về prependContext hoặc appendContext. Hook này dành cho các trình giám sát nền cần tóm tắt trạng thái hiện tại mà không thay đổi các lượt do người dùng khởi tạo.

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

​

Phần mở rộng phiên và lần chèn lượt tiếp theo

​

Hook tin nhắn

• message_received: quan sát nội dung đến, người gửi, threadId, messageId, senderId, tương quan lượt chạy/phiên tùy chọn, và siêu dữ liệu.
• message_sending: viết lại content hoặc trả về { cancel: true }.
• message_sent: quan sát thành công hoặc thất bại cuối cùng.

• message_sending với cancel: true là quyết định cuối cùng.
• message_sending với cancel: false được xem là không có quyết định.
• content đã ghi lại tiếp tục chuyển đến các hook có độ ưu tiên thấp hơn trừ khi một hook sau đó hủy việc gửi.

​

Hook cài đặt

​

Vòng đời Gateway

​

Các tính năng sắp ngừng hỗ trợ

• Phong bì kênh văn bản thuần túy trong các trình xử lý inbound_claim và message_received. Đọc BodyForAgent và các khối ngữ cảnh người dùng có cấu trúc thay vì phân tích văn bản phong bì phẳng. Xem Phong bì kênh văn bản thuần túy → BodyForAgent.
• before_agent_start vẫn tồn tại để tương thích. Plugin mới nên dùng before_model_resolve và before_prompt_build thay vì pha kết hợp.
• onResolution trong before_tool_call hiện dùng union có kiểu PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) thay vì string dạng tự do.

​

Liên quan

• Di chuyển Plugin SDK — các tính năng đang ngừng hỗ trợ và mốc thời gian gỡ bỏ
• Xây dựng Plugin
• Tổng quan Plugin SDK
• Điểm vào Plugin
• Hook nội bộ
• Nội bộ kiến trúc Plugin