Plugin hooks

Plugin hooks are in-process extension points for OpenClaw plugins. Use them when a plugin needs to inspect or change agent runs, tool calls, message flow, session lifecycle, subagent routing, installs, or Gateway startup.

Use internal hooks instead when you want a small operator-installed

script for command and Gateway events such as , , , , or .

Quick start

Register typed plugin hooks with

from your plugin entry:

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

Hook handlers run sequentially in descending

. Same-priority hooks keep registration order.

accepts:

• text

  Copy

  priority
  — handler ordering (higher runs first).
• text

  Copy

  timeoutMs
  — optional per-hook budget. When set, the hook runner aborts that handler after the budget elapses and continues with the next one, instead of letting slow setup or recall work consume the caller's configured model timeout. Omit it to use the default observation/decision timeout that the hook runner applies generically.

Each hook receives

, the resolved config for the plugin that registered that handler. Use it for hook decisions that need current plugin options; OpenClaw injects it per handler without mutating the shared event object seen by other plugins.

Hook catalog

Hooks are grouped by the surface they extend. Names in bold accept a decision result (block, cancel, override, or require approval); all others are observation-only.

Agent turn

• text

  Copy

  before_model_resolve
  — override provider or model before session messages load
• text

  Copy

  agent_turn_prepare
  — consume queued plugin turn injections and add same-turn context before prompt hooks
• text

  Copy

  before_prompt_build
  — add dynamic context or system-prompt text before the model call
• text

  Copy

  before_agent_start
  — compatibility-only combined phase; prefer the two hooks above
• text

  Copy

  before_agent_reply
  — short-circuit the model turn with a synthetic reply or silence
• text

  Copy

  before_agent_finalize
  — inspect the natural final answer and request one more model pass
• text

  Copy

  agent_end
  — observe final messages, success state, and run duration
• text

  Copy

  heartbeat_prompt_contribution
  — add heartbeat-only context for background monitor and lifecycle plugins

Conversation observation

• text

  Copy

  model_call_started
  /
  text

  Copy

  model_call_ended
  — observe sanitized provider/model call metadata, timing, outcome, and bounded request-id hashes without prompt or response content
• text

  Copy

  llm_input
  — observe provider input (system prompt, prompt, history)
• text

  Copy

  llm_output
  — observe provider output

Tools

• text

  Copy

  before_tool_call
  — rewrite tool params, block execution, or require approval
• text

  Copy

  after_tool_call
  — observe tool results, errors, and duration
• text

  Copy

  tool_result_persist
  — rewrite the assistant message produced from a tool result
• text

  Copy

  before_message_write
  — inspect or block an in-progress message write (rare)

Messages and delivery

• text

  Copy

  inbound_claim
  — claim an inbound message before agent routing (synthetic replies)
• text

  Copy

  message_received
  — observe inbound content, sender, thread, and metadata
• text

  Copy

  message_sending
  — rewrite outbound content or cancel delivery
• text

  Copy

  message_sent
  — observe outbound delivery success or failure
• text

  Copy

  before_dispatch
  — inspect or rewrite an outbound dispatch before channel handoff
• text

  Copy

  reply_dispatch
  — participate in the final reply-dispatch pipeline

Sessions and compaction

• text

  Copy

  session_start
  /
  text

  Copy

  session_end
  — track session lifecycle boundaries
• text

  Copy

  before_compaction
  /
  text

  Copy

  after_compaction
  — observe or annotate compaction cycles
• text

  Copy

  before_reset
  — observe session-reset events (
  text

  Copy

  /reset
  , programmatic resets)

Subagents

• text

  Copy

  subagent_spawning
  /
  text

  Copy

  subagent_delivery_target
  /
  text

  Copy

  subagent_spawned
  /
  text

  Copy

  subagent_ended
  — coordinate subagent routing and completion delivery

Lifecycle

• text

  Copy

  gateway_start
  /
  text

  Copy

  gateway_stop
  — start or stop plugin-owned services with the Gateway
• text

  Copy

  cron_changed
  — observe gateway-owned cron lifecycle changes (added, updated, removed, started, finished, scheduled)
• text

  Copy

  before_install
  — inspect skill or plugin install scans and optionally block

Tool call policy

receives:

• text

  Copy

  event.toolName
• text

  Copy

  event.params
• optional
  text

  Copy

  event.runId
• optional
  text

  Copy

  event.toolCallId
• context fields such as
  text

  Copy

  ctx.agentId
  ,
  text

  Copy

  ctx.sessionKey
  ,
  text

  Copy

  ctx.sessionId
  ,
  text

  Copy

  ctx.runId
  ,
  text

  Copy

  ctx.jobId
  (set on cron-driven runs), and diagnostic
  text

  Copy

  ctx.trace

It can return:

typescript
Copy
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;
  };
};

Rules:

• text

  Copy

  block: true
  is terminal and skips lower-priority handlers.
• text

  Copy

  block: false
  is treated as no decision.
• text

  Copy

  params
  rewrites the tool parameters for execution.
• text

  Copy

  requireApproval
  pauses the agent run and asks the user through plugin approvals. The
  text

  Copy

  /approve
  command can approve both exec and plugin approvals.
• A lower-priority
  text

  Copy

  block: true
  can still block after a higher-priority hook requested approval.
• text

  Copy

  onResolution
  receives the resolved approval decision —
  text

  Copy

  allow-once
  ,
  text

  Copy

  allow-always
  ,
  text

  Copy

  deny
  ,
  text

  Copy

  timeout
  , or
  text

  Copy

  cancelled
  .

Bundled plugins that need host-level policy can register trusted tool policies with

. These run before ordinary hooks and before external plugin decisions. Use them only for host-trusted gates such as workspace policy, budget enforcement, or reserved workflow safety. External plugins should use normal hooks.

Tool result persistence

Tool results can include structured

for UI rendering, diagnostics, media routing, or plugin-owned metadata. Treat as runtime metadata, not prompt content:

• OpenClaw strips
  text

  Copy

  toolResult.details
  before provider replay and compaction input so metadata does not become model context.
• Persisted session entries keep only bounded
  text

  Copy

  details
  . Oversized details are replaced with a compact summary and
  text

  Copy

  persistedDetailsTruncated: true
  .
• text

  Copy

  tool_result_persist
  and
  text

  Copy

  before_message_write
  run before the final persistence cap. Hooks should still keep returned
  text

  Copy

  details
  small and avoid placing prompt-relevant text only in
  text

  Copy

  details
  ; put model-visible tool output in
  text

  Copy

  content
  .

Prompt and model hooks

Use the phase-specific hooks for new plugins:

• text

  Copy

  before_model_resolve
  : receives only the current prompt and attachment metadata. Return
  text

  Copy

  providerOverride
  or
  text

  Copy

  modelOverride
  .
• text

  Copy

  agent_turn_prepare
  : receives the current prompt, prepared session messages, and any exactly-once queued injections drained for this session. Return
  text

  Copy

  prependContext
  or
  text

  Copy

  appendContext
  .
• text

  Copy

  before_prompt_build
  : receives the current prompt and session messages. Return
  text

  Copy

  prependContext
  ,
  text

  Copy

  appendContext
  ,
  text

  Copy

  systemPrompt
  ,
  text

  Copy

  prependSystemContext
  , or
  text

  Copy

  appendSystemContext
  .
• text

  Copy

  heartbeat_prompt_contribution
  : runs only for heartbeat turns and returns
  text

  Copy

  prependContext
  or
  text

  Copy

  appendContext
  . It is intended for background monitors that need to summarize current state without changing user-initiated turns.

remains for compatibility. Prefer the explicit hooks above so your plugin does not depend on a legacy combined phase.

and include when OpenClaw can identify the active run. The same value is also available on . Cron-driven runs also expose (the originating cron job id) so plugin hooks can scope metrics, side effects, or state to a specific scheduled job.

is an observation hook and runs fire-and-forget after the turn. The hook runner applies a 30 second timeout so a wedged plugin or embedding endpoint cannot leave the hook promise pending forever. A timeout is logged and OpenClaw continues; it does not cancel plugin-owned network work unless the plugin also uses its own abort signal.

Use

and for provider-call telemetry that should not receive raw prompts, history, responses, headers, request bodies, or provider request IDs. These hooks include stable metadata such as , , , , optional /, terminal /, and when OpenClaw can derive a bounded provider request-id hash.

runs only when a harness is about to accept a natural final assistant answer. It is not the cancellation path and does not run when the user aborts a turn. Return to ask the harness for one more model pass before finalization, to force finalization, or omit a result to continue. Codex native hooks are relayed into this hook as OpenClaw decisions.

Non-bundled plugins that need

, , , or must set:

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

Prompt-mutating hooks and durable next-turn injections can be disabled per plugin with

.

Session extensions and next-turn injections

Workflow plugins can persist small JSON-compatible session state with

and update it through the Gateway method. Session rows project registered extension state through , letting Control UI and other clients render plugin-owned status without learning plugin internals.

Use

when a plugin needs durable context to reach the next model turn exactly once. OpenClaw drains queued injections before prompt hooks, drops expired injections, and deduplicates by per plugin. This is the right seam for approval resumes, policy summaries, background monitor deltas, and command continuations that should be visible to the model on the next turn but should not become permanent system prompt text.

Cleanup semantics are part of the contract. Session extension cleanup and runtime lifecycle cleanup callbacks receive

, , , or . The host removes the owning plugin's persistent session extension state and pending next-turn injections for reset/delete/disable; restart keeps durable session state while cleanup callbacks let plugins release scheduler jobs, run context, and other out-of-band resources for the old runtime generation.

Message hooks

Use message hooks for channel-level routing and delivery policy:

• text

  Copy

  message_received
  : observe inbound content, sender,
  text

  Copy

  threadId
  ,
  text

  Copy

  messageId
  ,
  text

  Copy

  senderId
  , optional run/session correlation, and metadata.
• text

  Copy

  message_sending
  : rewrite
  text

  Copy

  content
  or return
  text

  Copy

  { cancel: true }
  .
• text

  Copy

  message_sent
  : observe final success or failure.

For audio-only TTS replies,

may contain the hidden spoken transcript even when the channel payload has no visible text/caption. Rewriting that updates the hook-visible transcript only; it is not rendered as a media caption.

Message hook contexts expose stable correlation fields when available:

, , , , , , , , and . Prefer these first-class fields before reading legacy metadata.

Prefer typed

and fields before using channel-specific metadata.

Decision rules:

• text

  Copy

  message_sending
  with
  text

  Copy

  cancel: true
  is terminal.
• text

  Copy

  message_sending
  with
  text

  Copy

  cancel: false
  is treated as no decision.
• Rewritten
  text

  Copy

  content
  continues to lower-priority hooks unless a later hook cancels delivery.

Install hooks

runs after the built-in scan for skill and plugin installs. Return additional findings or to stop the install.

is terminal. is treated as no decision.

Gateway lifecycle

Use

for plugin services that need Gateway-owned state. The context exposes , , and for cron inspection and updates. Use to clean up long-running resources.

Do not rely on the internal

hook for plugin-owned runtime services.

fires for gateway-owned cron lifecycle events with a typed event payload covering , , , , , and reasons. The event carries a snapshot (including , , and when present) plus a of | | | . Removed events still carry the deleted job snapshot so external schedulers can reconcile state. Use and from the runtime context when syncing external wake schedulers, and keep OpenClaw as the source of truth for due checks and execution.

Upcoming deprecations

A few hook-adjacent surfaces are deprecated but still supported. Migrate before the next major release:

• Plaintext channel envelopes in
  text

  Copy

  inbound_claim
  and
  text

  Copy

  message_received
  handlers. Read
  text

  Copy

  BodyForAgent
  and the structured user-context blocks instead of parsing flat envelope text. See Plaintext channel envelopes → BodyForAgent.
• text

  Copy

  before_agent_start
  remains for compatibility. New plugins should use
  text

  Copy

  before_model_resolve
  and
  text

  Copy

  before_prompt_build
  instead of the combined phase.
• text

  Copy

  onResolution
  in
  text

  Copy

  before_tool_call
  now uses the typed
  text

  Copy

  PluginApprovalResolution
  union (
  text

  Copy

  allow-once
  /
  text

  Copy

  allow-always
  /
  text

  Copy

  deny
  /
  text

  Copy

  timeout
  /
  text

  Copy

  cancelled
  ) instead of a free-form
  text

  Copy

  string
  .

For the full list — memory capability registration, provider thinking profile, external auth providers, provider discovery types, task runtime accessors, and the

→ rename — see Plugin SDK migration → Active deprecations.

Related

• Plugin SDK migration — active deprecations and removal timeline
• Building plugins
• Plugin SDK overview
• Plugin entry points
• Internal hooks
• Plugin architecture internals