Plugin 훅

​

빠른 시작

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 - 핸들러 순서 지정(높을수록 먼저 실행).
• timeoutMs - 선택적 훅별 예산입니다. 설정하면 훅 실행기는 예산이 경과한 뒤 해당 핸들러를 중단하고 다음 핸들러로 계속 진행합니다. 느린 설정이나 회상 작업이 호출자가 구성한 모델 타임아웃을 소비하게 두지 않습니다. 생략하면 훅 실행기가 일반적으로 적용하는 기본 관찰/결정 타임아웃을 사용합니다.

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

​

훅 카탈로그

• before_model_resolve - 세션 메시지가 로드되기 전에 공급자 또는 모델 재정의
• agent_turn_prepare - 대기 중인 Plugin 턴 주입을 소비하고 프롬프트 훅 전에 동일 턴 컨텍스트 추가
• before_prompt_build - 모델 호출 전에 동적 컨텍스트 또는 시스템 프롬프트 텍스트 추가
• before_agent_start - 호환성 전용 결합 단계입니다. 위의 두 훅을 선호하세요
• before_agent_run - 모델 제출 전에 최종 프롬프트와 세션 메시지를 검사하고 선택적으로 실행 차단
• before_agent_reply - 합성 응답 또는 침묵으로 모델 턴 단락
• before_agent_finalize - 자연스러운 최종 답변을 검사하고 모델 패스 한 번 더 요청
• agent_end - 최종 메시지, 성공 상태, 실행 시간 관찰
• heartbeat_prompt_contribution - 백그라운드 모니터 및 수명 주기 Plugin을 위한 Heartbeat 전용 컨텍스트 추가

• model_call_started / model_call_ended - 프롬프트 또는 응답 콘텐츠 없이 정리된 공급자/모델 호출 메타데이터, 타이밍, 결과, 제한된 요청 ID 해시 관찰
• llm_input - 공급자 입력(시스템 프롬프트, 프롬프트, 기록) 관찰
• llm_output - 공급자 출력, 사용량, 사용 가능한 경우 확인된 contextTokenBudget 관찰

• before_tool_call - 도구 매개변수 재작성, 실행 차단 또는 승인 요구
• after_tool_call - 도구 결과, 오류, 기간 관찰
• resolve_exec_env - Plugin 소유 환경 변수를 exec에 제공
• tool_result_persist - 도구 결과에서 생성된 어시스턴트 메시지 재작성
• before_message_write - 진행 중인 메시지 쓰기 검사 또는 차단(드문 경우)

• inbound_claim - 에이전트 라우팅 전 인바운드 메시지 클레임(합성 응답)
• message_received — 인바운드 콘텐츠, 발신자, 스레드, 메타데이터 관찰
• message_sending — 아웃바운드 콘텐츠 재작성 또는 전달 취소
• reply_payload_sending — 전달 전 정규화된 응답 페이로드 변경 또는 취소
• message_sent — 아웃바운드 전달 성공 또는 실패 관찰
• before_dispatch - 채널 인계 전 아웃바운드 디스패치 검사 또는 재작성
• reply_dispatch - 최종 응답 디스패치 파이프라인에 참여

• session_start / session_end - 세션 수명 주기 경계 추적. 이벤트의 reason은 new, reset, idle, daily, compaction, deleted, shutdown, restart, unknown 중 하나입니다. shutdown 및 restart 값은 세션이 아직 활성 상태인 동안 프로세스가 중지되거나 재시작될 때 Gateway 종료 파이널라이저에서 발생하므로, 메모리 또는 트랜스크립트 저장소 같은 다운스트림 Plugin이 재시작 후에도 열린 상태로 남을 수 있는 고스트 행을 마무리할 수 있습니다. 파이널라이저는 제한되어 있어 느린 Plugin이 SIGTERM/SIGINT를 차단할 수 없습니다.
• before_compaction / after_compaction - Compaction 주기 관찰 또는 주석 추가
• before_reset - 세션 재설정 이벤트(/reset, 프로그래밍 방식 재설정) 관찰

• subagent_spawned / subagent_ended - 하위 에이전트 시작 및 완료 관찰.
• subagent_delivery_target - 코어 세션 바인딩이 경로를 투영할 수 없을 때 완료 전달을 위한 호환성 훅.
• subagent_spawning - 사용 중단된 호환성 훅입니다. 이제 코어는 subagent_spawned가 발생하기 전에 채널 세션 바인딩 어댑터를 통해 thread: true 하위 에이전트 바인딩을 준비합니다.
• subagent_spawned에는 OpenClaw가 시작 전에 자식 세션의 네이티브 모델을 확인한 경우 resolvedModel 및 resolvedProvider가 포함됩니다.
• subagent_ended는 targetSessionKey(ID — 이는 subagent_spawned.childSessionKey와 일치), targetKind("subagent" 또는 "acp"), reason, 선택적 outcome("ok", "error", "timeout", "killed", "reset" 또는 "deleted"), 선택적 error, runId, endedAt, accountId, sendFarewell을 전달합니다. agentId 또는 childSessionKey는 포함하지 않습니다. 해당 subagent_spawned 이벤트와 연결하려면 targetSessionKey를 사용하세요.

• gateway_start / gateway_stop - Gateway와 함께 Plugin 소유 서비스 시작 또는 중지
• deactivate - gateway_stop의 사용 중단된 호환성 별칭입니다. 새 Plugin에서는 gateway_stop을 사용하세요
• cron_changed - Gateway 소유 Cron 수명 주기 변경(추가, 업데이트, 제거, 시작, 완료, 예약) 관찰
• before_install - 로드된 Plugin 런타임에서 준비된 Skill 또는 Plugin 설치 자료 검사

​

런타임 훅 디버그

​

도구 호출 정책

• event.toolName
• event.params
• 선택적 event.toolKind 및 event.toolInputKind, 의도적으로 이름을 공유하는 도구를 위한 호스트 권한 판별자입니다. 예를 들어 외부 코드 모드 exec 호출은 toolKind: "code_mode_exec"를 사용하며, 입력 언어를 알 수 있으면 toolInputKind: "javascript" | "typescript"를 포함합니다
• 선택적 event.derivedPaths, apply_patch 같은 잘 알려진 도구 봉투에 대해 호스트가 최선 노력으로 파생한 대상 경로 힌트를 포함합니다. 존재하는 경우 이러한 경로는 불완전하거나 도구가 실제로 건드릴 범위를 과대 추정할 수 있습니다(예: 잘못되었거나 부분적인 입력)
• 선택적 event.runId
• 선택적 event.toolCallId
• ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId(Cron 기반 실행에서 설정), ctx.toolKind, ctx.toolInputKind, 진단용 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";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true는 터미널이며 더 낮은 우선순위 핸들러를 건너뜁니다.
• block: false는 결정 없음으로 처리됩니다.
• params는 실행을 위해 도구 매개변수를 재작성합니다.
• requireApproval은 에이전트 실행을 일시 중지하고 Plugin 승인을 통해 사용자에게 묻습니다. /approve 명령은 exec 승인과 Plugin 승인을 모두 승인할 수 있습니다. Codex 앱 서버 보고 모드 네이티브 PreToolUse 릴레이에서는 일치하는 앱 서버 승인 요청으로 지연됩니다. Codex 하네스 런타임을 참조하세요.
• 더 낮은 우선순위의 block: true는 더 높은 우선순위 훅이 승인을 요청한 뒤에도 여전히 차단할 수 있습니다.
• onResolution은 확인된 승인 결정(allow-once, allow-always, deny, timeout 또는 cancelled)을 받습니다.

​

Exec 환경 훅

• event.sessionKey
• event.toolName, 현재 항상 "exec"
• event.host, "gateway", "sandbox" 또는 "node" 중 하나
• ctx.agentId, ctx.sessionKey, ctx.messageProvider, ctx.channelId 같은 컨텍스트 필드

​

도구 결과 지속성

• OpenClaw는 제공자 리플레이와 compaction 입력 전에 toolResult.details를 제거하여 메타데이터가 모델 컨텍스트가 되지 않게 합니다.
• 지속된 세션 항목은 제한된 details만 유지합니다. 너무 큰 details는 간결한 요약과 persistedDetailsTruncated: true로 대체됩니다.
• tool_result_persist와 before_message_write는 최종 지속성 한도 전에 실행됩니다. Hooks는 여전히 반환되는 details를 작게 유지해야 하며, 프롬프트 관련 텍스트를 details에만 넣지 않아야 합니다. 모델에 보이는 도구 출력은 content에 넣으세요.

​

프롬프트 및 모델 hooks

• before_model_resolve: 현재 프롬프트와 첨부 파일 메타데이터만 받습니다. providerOverride 또는 modelOverride를 반환합니다.
• agent_turn_prepare: 현재 프롬프트, 준비된 세션 메시지, 그리고 이 세션에 대해 비워진 정확히 한 번 큐 주입을 받습니다. prependContext 또는 appendContext를 반환합니다.
• before_prompt_build: 현재 프롬프트와 세션 메시지를 받습니다. prependContext, appendContext, systemPrompt, prependSystemContext 또는 appendSystemContext를 반환합니다.
• heartbeat_prompt_contribution: Heartbeat 턴에서만 실행되며 prependContext 또는 appendContext를 반환합니다. 사용자 시작 턴을 변경하지 않고 현재 상태를 요약해야 하는 백그라운드 모니터를 위한 것입니다.

• ctx.senderId — 채널 범위 발신자 ID(예: Feishu open_id, Discord 사용자 ID). 실행이 알려진 발신자 메타데이터가 있는 사용자 메시지에서 시작될 때 채워집니다.
• ctx.chatId — 전송 네이티브 대화 식별자(예: Feishu chat_id, Telegram chat_id). 원본 채널이 네이티브 대화 ID를 제공할 때 채워집니다.
• ctx.channelContext.sender.id — ctx.senderId와 같은 발신자 ID이며, plugins가 채널별 필드로 확장할 수 있는 채널 소유 객체 아래에 있습니다.
• ctx.channelContext.chat.id — ctx.chatId와 같은 대화 ID이며, plugins가 채널별 필드로 확장할 수 있는 채널 소유 객체 아래에 있습니다.

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

​

세션 확장 및 다음 턴 주입

​

메시지 hooks

• message_received: 인바운드 콘텐츠, 발신자, threadId, messageId, senderId, 선택적 실행/세션 상관관계, 메타데이터를 관찰합니다.
• message_sending: content를 다시 작성하거나 { cancel: true }를 반환합니다.
• reply_payload_sending: 정규화된 ReplyPayload 객체(presentation, delivery, 미디어 참조, 텍스트 포함)를 다시 작성하거나 { cancel: true }를 반환합니다.
• message_sent: 최종 성공 또는 실패를 관찰합니다.

• cancel: true가 있는 message_sending은 종결 상태입니다.
• cancel: false가 있는 message_sending은 결정 없음으로 처리됩니다.
• 다시 작성된 content는 이후 후크가 전달을 취소하지 않는 한 더 낮은 우선순위의 후크로 계속 전달됩니다.
• reply_payload_sending은 페이로드 정규화 이후, 채널 전달 이전에 실행되며, 원래 채널로 다시 라우팅되는 답장도 포함됩니다. 핸들러는 순차적으로 실행되며 각 핸들러는 더 높은 우선순위의 핸들러가 생성한 최신 페이로드를 봅니다.
• reply_payload_sending 페이로드는 trustedLocalMedia 같은 런타임 신뢰 마커를 노출하지 않습니다. plugins는 페이로드 형태를 수정할 수 있지만 로컬 미디어 신뢰를 부여할 수는 없습니다.
• message_sending은 취소와 함께 cancelReason 및 제한된 metadata를 반환할 수 있습니다. 새 메시지 수명 주기 API는 이를 이유가 cancelled_by_message_sending_hook인 억제된 전달 결과로 노출하며, 레거시 직접 전달은 호환성을 위해 계속 빈 결과 배열을 반환합니다.
• message_sent는 관찰 전용입니다. 핸들러 실패는 로그에 기록되며 전달 결과를 변경하지 않습니다.

​

설치 후크

​

Gateway 수명 주기

​

예정된 사용 중단

• inbound_claim 및 message_received 핸들러의 평문 채널 엔벨로프. 평면 엔벨로프 텍스트를 파싱하는 대신 BodyForAgent와 구조화된 사용자 컨텍스트 블록을 읽으세요. 평문 채널 엔벨로프 → BodyForAgent를 참조하세요.
• **before_agent_start**는 호환성을 위해 남아 있습니다. 새 plugins는 결합된 단계 대신 before_model_resolve 및 before_prompt_build를 사용해야 합니다.
• **subagent_spawning**은 이전 plugins와의 호환성을 위해 남아 있지만, 새 plugins는 여기서 스레드 라우팅을 반환해서는 안 됩니다. 코어는 subagent_spawned가 발생하기 전에 채널 세션 바인딩 어댑터를 통해 thread: true 하위 에이전트 바인딩을 준비합니다.
• **deactivate**는 2026-08-16 이후까지 사용 중단된 정리 호환성 별칭으로 남아 있습니다. 새 plugins는 gateway_stop을 사용해야 합니다.
• **before_tool_call의 onResolution**은 이제 자유 형식 string 대신 타입 지정된 PluginApprovalResolution 유니언(allow-once / allow-always / deny / timeout / cancelled)을 사용합니다.

​

관련 항목

• Plugin SDK 마이그레이션 - 활성 사용 중단 및 제거 일정
• plugins 빌드
• Plugin SDK 개요
• Plugin 진입점
• 내부 후크
• Plugin 아키텍처 내부 구조