From a08449b83f7352bb68481f6380cd837ad193e8fe Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 18:27:27 +0100 Subject: [PATCH] docs: refresh approval fallback refs --- docs/channels/telegram.md | 10 ++++++++++ docs/plugins/building-plugins.md | 2 +- docs/tools/exec-approvals.md | 7 ++++++- 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index e98a6014ef7..16de8d6cb8e 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -832,6 +832,16 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Only resolved approvers can approve or deny. Non-approvers cannot use `/approve` and cannot use Telegram approval buttons. + Approval resolution behavior: + + - IDs prefixed with `plugin:` always resolve through plugin approvals. + - Other approval IDs try `exec.approval.resolve` first. + - If Telegram is also authorized for plugin approvals and the gateway says + the exec approval is unknown/expired, Telegram retries once through + `plugin.approval.resolve`. + - Real exec approval denials/errors do not silently fall through to plugin + approval resolution. + Channel delivery shows the command text in the chat, so only enable `channel` or `both` in trusted groups/topics. When the prompt lands in a forum topic, OpenClaw preserves the topic for both the approval prompt and the post-approval follow-up. Exec approvals expire after 30 minutes by default. Inline approval buttons also depend on `channels.telegram.capabilities.inlineButtons` allowing the target surface (`dm`, `group`, or `all`). diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index 56fea5ed3c5..28d04f0a5b5 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -179,7 +179,7 @@ Hook guard semantics to keep in mind: - `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers. - `message_sending`: `{ cancel: false }` is treated as no decision. -The `/approve` command handles both exec and plugin approvals with automatic fallback. Plugin approval forwarding can be configured independently via `approvals.plugin` in config. +The `/approve` command handles both exec and plugin approvals with bounded fallback: when an exec approval id is not found, OpenClaw retries the same id through plugin approvals. Plugin approval forwarding can be configured independently via `approvals.plugin` in config. See [SDK Overview hook decision semantics](/plugins/sdk-overview#hook-decision-semantics) for details. diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index 45e2b6f9487..cd71b44dd64 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -456,7 +456,7 @@ Reply in chat: /approve deny ``` -The `/approve` command handles both exec approvals and plugin approvals. If the ID does not match a pending exec approval, it automatically checks plugin approvals. +The `/approve` command handles both exec approvals and plugin approvals. If the ID does not match a pending exec approval, it automatically checks plugin approvals instead. ### Plugin approval forwarding @@ -499,6 +499,10 @@ separate native delivery adapter just to stay pending. Discord and Telegram also support same-chat `/approve`, but those channels still use their resolved approver list for authorization even when native approval delivery is disabled. +For Telegram and other native approval clients that call the Gateway directly, +this fallback is intentionally bounded to "approval not found" failures. A real +exec approval denial/error does not silently retry as a plugin approval. + ### Native approval delivery Some channels can also act as native approval clients. Native clients add approver DMs, origin-chat @@ -540,6 +544,7 @@ Shared behavior: - Slack approvers can be explicit (`execApprovals.approvers`) or inferred from `commands.ownerAllowFrom` - the requester does not need to be an approver - the originating chat can approve directly with `/approve` when that chat already supports commands and replies +- native Telegram approval buttons follow the same bounded exec-to-plugin fallback as `/approve` - when native `target` enables origin-chat delivery, approval prompts include the command text - pending exec approvals expire after 30 minutes by default - if no operator UI or configured approval client can accept the request, the prompt falls back to `askFallback`