From ec01cd0ceb5594f55f164392e2aedba8b91f0c26 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 01:46:53 +0900 Subject: [PATCH] fix: tidy plugin update override docs (#60066) (thanks @huntharo) --- CHANGELOG.md | 2 ++ docs/automation/hooks.md | 69 ---------------------------------------- 2 files changed, 2 insertions(+), 69 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6bdaf6edd4..086094682e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,7 @@ Docs: https://docs.openclaw.ai - Gateway/connect: omit admin-scoped config and auth metadata from lower-privilege `hello-ok` snapshots while preserving those fields for admin reconnects. (#58469) Thanks @eleqtrizit. - iOS/canvas: restrict A2UI bridge trust to the bundled scaffold and exact capability-backed remote canvas URLs, so generic `canvas.navigate` and `canvas.present` loads no longer gain action-dispatch authority. (#58471) Thanks @eleqtrizit. - Agents/tool policy: preserve restrictive plugin-only allowlists instead of silently widening access to core tools, and keep allowlist warnings aligned with the enforced policy. (#58476) Thanks @eleqtrizit. +<<<<<<< HEAD - Hooks/session_end: preserve deterministic reason metadata for custom reset aliases and overlapping idle-plus-daily rollovers so plugins can rely on lifecycle reason reporting. (#59715) Thanks @jalehman. - Tools/image generation: stop inferring unsupported resolution overrides for OpenAI reference-image edits when no explicit `size` or `resolution` is provided, so default edit flows no longer fail before the provider request is sent. - Agents/sessions: release embedded runner session locks even when teardown cleanup throws, so timed-out or failed cleanup paths no longer leave sessions wedged until the stale-lock watchdog recovers them. (#59194) Thanks @samzong. @@ -76,6 +77,7 @@ Docs: https://docs.openclaw.ai - Control UI/skills: clear stale ClawHub results immediately when the search query changes, so debounced searches cannot keep outdated install targets visible. Related #60134. - Discord/ack reactions: keep automatic ACK reaction auth on the active hydrated Discord account so SecretRef-backed and non-default-account reactions stop falling back to stale default config resolution. (#60081) Thanks @FunJim. - Telegram/model switching: render non-default `/model` callback confirmations with HTML formatting so Telegram shows the selected model in bold instead of raw `**...**` markers. (#60042) Thanks @GitZhangChi. +- Plugins/update: allow `openclaw plugins update` to use `--dangerously-force-unsafe-install` for built-in dangerous-code false positives during plugin updates. (#60066) Thanks @huntharo. ## 2026.4.2 diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md index e586228464f..71a239eb510 100644 --- a/docs/automation/hooks.md +++ b/docs/automation/hooks.md @@ -168,75 +168,6 @@ openclaw hooks enable Extracts the last 15 user/assistant messages, generates a descriptive filename slug via LLM, and saves to `/memory/YYYY-MM-DD-slug.md`. Requires `workspace.dir` to be configured. -- **`tool_result_persist`**: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or `undefined` to keep it as-is. See [Agent Loop](/concepts/agent-loop). - -### Plugin Hook Events - -#### before_tool_call - -Runs before each tool call. Plugins can modify parameters, block the call, or request user approval. - -Return fields: - -- **`params`**: Override tool parameters (merged with original params) -- **`block`**: Set to `true` to block the tool call -- **`blockReason`**: Reason shown to the agent when blocked -- **`requireApproval`**: Pause execution and wait for user approval via channels - -The `requireApproval` field triggers native platform approval (Telegram buttons, Discord components, `/approve` command) instead of relying on the agent to cooperate: - -```typescript -{ - requireApproval: { - title: "Sensitive operation", - description: "This tool call modifies production data", - severity: "warning", // "info" | "warning" | "critical" - timeoutMs: 120000, // default: 120s - timeoutBehavior: "deny", // "allow" | "deny" (default) - onResolution: async (decision) => { - // Called after the user resolves: "allow-once", "allow-always", "deny", "timeout", or "cancelled" - }, - } -} -``` - -The `onResolution` callback is invoked with the final decision string after the approval resolves, times out, or is cancelled. It runs in-process within the plugin (not sent to the gateway). Use it to persist decisions, update caches, or perform cleanup. - -The `pluginId` field is stamped automatically by the hook runner from the plugin registration. When multiple plugins return `requireApproval`, the first one (highest priority) wins. - -`block` takes precedence over `requireApproval`: if the merged hook result has both `block: true` and a `requireApproval` field, the tool call is blocked immediately without triggering the approval flow. This ensures a higher-priority plugin's block cannot be overridden by a lower-priority plugin's approval request. - -If the gateway is unavailable or does not support plugin approvals, the tool call falls back to a soft block using the `description` as the block reason. - -#### before_install - -Runs after the built-in install security scan and before installation continues. OpenClaw fires this hook for interactive skill installs as well as plugin bundle, package, and single-file installs. - -Default behavior differs by target type: - -- Plugin install/update flows fail closed on built-in scan `critical` findings and scan errors unless the operator explicitly uses `openclaw plugins install --dangerously-force-unsafe-install` or `openclaw plugins update --dangerously-force-unsafe-install`. -- Skill installs still surface built-in scan findings and scan errors as warnings and continue by default. - -Return fields: - -- **`findings`**: Additional scan findings to surface as warnings -- **`block`**: Set to `true` to block the install -- **`blockReason`**: Human-readable reason shown when blocked - -Event fields: - -- **`targetType`**: Install target category (`skill` or `plugin`) -- **`targetName`**: Human-readable skill name or plugin id for the install target -- **`sourcePath`**: Absolute path to the install target content being scanned -- **`sourcePathKind`**: Whether the scanned content is a `file` or `directory` -- **`origin`**: Normalized install origin when available (for example `openclaw-bundled`, `openclaw-workspace`, `plugin-bundle`, `plugin-package`, or `plugin-file`) -- **`request`**: Provenance for the install request, including `kind`, `mode`, and optional `requestedSpecifier` -- **`builtinScan`**: Structured result of the built-in scanner, including `status`, summary counts, findings, and optional `error` -- **`skill`**: Skill install metadata when `targetType` is `skill`, including `installId` and the selected `installSpec` -- **`plugin`**: Plugin install metadata when `targetType` is `plugin`, including the canonical `pluginId`, normalized `contentType`, optional `packageName` / `manifestId` / `version`, and `extensions` - -Example event (plugin package install): - ### bootstrap-extra-files config ```json