Hook 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ự handler (cao hơn chạy trước).
• timeoutMs - ngân sách tùy chọn cho từng hook. Khi được đặt, runner hook sẽ hủy handler đó sau khi ngân sách trôi qua và tiếp tục với handler kế tiếp, thay vì để thao tác thiết lập hoặc recall chậm tiêu thụ timeout model đã cấu hình của caller. Bỏ qua để dùng timeout quan sát/quyết định mặc định mà runner hook áp dụng chung.

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

​

Danh mục hook

• before_model_resolve - ghi đè provider hoặc model trước khi tin nhắn phiên tải
• agent_turn_prepare - tiêu thụ các lượt chèn 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 - giai đoạn kết hợp chỉ để tương thích; ưu tiên hai hook phía trên
• before_agent_run - kiểm tra prompt cuối cùng và tin nhắn phiên trước khi gửi tới model, và tùy chọn chặn lượt chạy
• before_agent_reply - chặn sớm lượt model bằng một 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
• agent_end - quan sát tin nhắn 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 các Plugin giám sát nền và vòng đời

• model_call_started / model_call_ended - quan sát metadata lệnh gọi provider/model đã được làm sạch, thời gian, kết quả, và hash request-id có 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 tin nhắn assistant được tạo từ kết quả công cụ
• before_message_write - kiểm tra hoặc chặn một thao tác ghi tin nhắn đang diễn ra (hiếm)

• 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à metadata
• 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 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 pipeline dispatch phản hồi cuối cùng

• session_start / session_end - theo dõi ranh giới vòng đời phiên. reason của sự kiện là một trong new, reset, idle, daily, compaction, deleted, shutdown, restart, hoặc unknown. Các giá trị shutdown và restart kích hoạt từ finalizer tắt Gateway khi tiến trình bị dừng hoặc khởi động lại trong lúc phiên vẫn đang hoạt động, để các Plugin hạ nguồn (như bộ nhớ hoặc kho transcript) có thể hoàn tất các hàng ghost vốn sẽ bị để lại ở trạng thái mở qua các lần khởi động lại. Finalizer có giới hạn để một Plugin chậm không thể chặn SIGTERM/SIGINT.
• 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 reset phiên (/reset, reset theo chương trình)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - phối hợp định tuyến subagent và phân phối 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 các 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
• tùy chọn event.derivedPaths, chứa các gợi ý đường dẫn mục tiêu do host suy ra theo best-effort cho các envelope công cụ quen thuộc như apply_patch; khi có mặt, các đường dẫn này có thể không đầy đủ hoặc có thể ước lượng quá rộng những gì công cụ sẽ thực sự chạm tới (ví dụ, với đầu vào sai định dạng hoặc một phần)
• tùy chọn event.runId
• tùy chọn event.toolCallId
• 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 cuối cùng và bỏ qua các handler có mức ưu tiên thấp hơn.
• block: false được xem 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ả exec và phê duyệt Plugin.
• Một block: true có mức ưu tiên thấp hơn vẫn có thể chặn sau khi một 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 kết quả công cụ

• OpenClaw loại bỏ toolResult.details trước khi replay cho provider và đầu vào Compaction để metadata không trở thành ngữ cảnh model.
• Các entry phiên được lưu chỉ giữ details có giới hạn. Details quá lớn được thay bằng một bản 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 cuối cùng. Hook vẫn nên giữ details trả về ở kích thước nhỏ và tránh đặt văn bản liên quan đến prompt chỉ trong details; hãy đặ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à metadata tệp đính kèm. Trả về providerOverride hoặc modelOverride.
• agent_turn_prepare: nhận prompt hiện tại, tin nhắn phiên đã chuẩn bị, và mọi lượt chèn đúng-một-lần đang xếp hàng đã được rút ra cho phiên này. Trả về prependContext hoặc appendContext.
• before_prompt_build: nhận prompt hiện tại và tin nhắn 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.

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

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

​

Phần mở rộng phiên và injection lượt kế tiếp

​

Hook thông điệp

• message_received: quan sát nội dung đến, người gửi, threadId, messageId, senderId, tương quan run/session tùy chọn và metadata.
• message_sending: ghi 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à 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 đến các hook có mức ưu tiên thấp hơn trừ khi hook sau đó hủy việc gửi.
• message_sending có thể trả về cancelReason và metadata có giới hạn cùng với một lệnh hủy. Các API vòng đời thông điệp mới cung cấp điều này dưới dạng kết quả gửi bị chặn với lý do cancelled_by_message_sending_hook; gửi trực tiếp kiểu cũ tiếp tục trả về mảng kết quả rỗng để tương thích.
• message_sent chỉ để quan sát. Lỗi handler được ghi log và không thay đổi kết quả gửi.

​

Hook cài đặt

​

Vòng đời Gateway

​

Sắp ngừng hỗ trợ

• Phong bì kênh dạng văn bản thuần trong các handler 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 dạng văn bản thuần → 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 cho 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ì một string tự do.

​

Liên quan

• Chuyển đổi Plugin SDK - các mục ngừng hỗ trợ đang hoạt động và lịch trình loại 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