diff --git a/docs/channels/discord.md b/docs/channels/discord.md index 6a83acbe398..1952963839a 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -959,6 +959,9 @@ Default slash command settings: When `target` is `channel` or `both`, the approval prompt is visible in the channel. Only resolved approvers can use the buttons; other users receive an ephemeral denial. Approval prompts include the command text, so only enable channel delivery in trusted channels. If the channel ID cannot be derived from the session key, OpenClaw falls back to DM delivery. Discord also renders the shared approval buttons used by other chat channels. The native Discord adapter mainly adds approver DM routing and channel fanout. + When those buttons are present, they are the primary approval UX; OpenClaw + should only include a manual `/approve` command when the tool result says + chat approvals are unavailable or manual approval is the only path. Gateway auth for this handler uses the same shared credential resolution contract as other Gateway clients: diff --git a/docs/channels/slack.md b/docs/channels/slack.md index aefb5f5be23..0dc0bc1b45f 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -512,6 +512,9 @@ Slack can act as a native approval client with interactive buttons and interacti - Approver authorization is still enforced: only users identified as approvers can approve or deny requests through Slack. This uses the same shared approval button surface as other channels. When `interactivity` is enabled in your Slack app settings, approval prompts render as Block Kit buttons directly in the conversation. +When those buttons are present, they are the primary approval UX; OpenClaw +should only include a manual `/approve` command when the tool result says chat +approvals are unavailable or manual approval is the only path. Config path: diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index d7f69f188b3..f7ade62ae5a 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -823,6 +823,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Approvers must be numeric Telegram user IDs. Telegram auto-enables native exec approvals when `enabled` is unset or `"auto"` and at least one approver can be resolved, either from `execApprovals.approvers` or from the account's numeric owner config (`allowFrom` and direct-message `defaultTo`). Set `enabled: false` to disable Telegram as a native approval client explicitly. Approval requests otherwise fall back to other configured approval routes or the exec approval fallback policy. Telegram also renders the shared approval buttons used by other chat channels. The native Telegram adapter mainly adds approver DM routing, channel/topic fanout, and typing hints before delivery. + When those buttons are present, they are the primary approval UX; OpenClaw + should only include a manual `/approve` command when the tool result says + chat approvals are unavailable or manual approval is the only path. Delivery rules: diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index 932daf1cdca..246244478b8 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -53,6 +53,11 @@ The Tooling section also includes runtime guidance for long-running work: Safety guardrails in the system prompt are advisory. They guide model behavior but do not enforce policy. Use tool policy, exec approvals, sandboxing, and channel allowlists for hard enforcement; operators can disable these by design. +On channels with native approval cards/buttons, the runtime prompt now tells the +agent to rely on that native approval UI first. It should only include a manual +`/approve` command when the tool result says chat approvals are unavailable or +manual approval is the only path. + ## Prompt modes OpenClaw can render smaller system prompts for sub-agents. The runtime sets a diff --git a/docs/help/faq.md b/docs/help/faq.md index ddb7cccb990..521d9cc405f 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -206,6 +206,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - If the chat already supports commands and replies, same-chat `/approve` works through the shared path. - If a supported native channel can infer approvers safely, OpenClaw now auto-enables DM-first native approvals when `channels..execApprovals.enabled` is unset or `"auto"`. + - When native approval cards/buttons are available, that native UI is the primary path; the agent should only include a manual `/approve` command if the tool result says chat approvals are unavailable or manual approval is the only path. - Use `approvals.exec` only when prompts must also be forwarded to other chats or explicit ops rooms. - Use `channels..execApprovals.target: "channel"` or `"both"` only when you explicitly want approval prompts posted back into the originating room/topic. - Plugin approvals are separate again: they use same-chat `/approve` by default, optional `approvals.plugin` forwarding, and only some native channels keep plugin-approval-native handling on top. diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index e4dff612eb0..c2331e155f0 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -509,6 +509,11 @@ Some channels can also act as native approval clients. Native clients add approv fanout, and channel-specific interactive approval UX on top of the shared same-chat `/approve` flow. +When native approval cards/buttons are available, that native UI is the primary +agent-facing path. The agent should not also echo a duplicate plain chat +`/approve` command unless the tool result says chat approvals are unavailable or +manual approval is the only remaining path. + Generic model: - host exec policy still decides whether exec approval is required diff --git a/docs/tools/exec.md b/docs/tools/exec.md index 76feed094fb..ae1c64444af 100644 --- a/docs/tools/exec.md +++ b/docs/tools/exec.md @@ -134,6 +134,10 @@ When approvals are required, the exec tool returns immediately with `status: "approval-pending"` and an approval id. Once approved (or denied / timed out), the Gateway emits system events (`Exec finished` / `Exec denied`). If the command is still running after `tools.exec.approvalRunningNoticeMs`, a single `Exec running` notice is emitted. +On channels with native approval cards/buttons, the agent should rely on that +native UI first and only include a manual `/approve` command when the tool +result explicitly says chat approvals are unavailable or manual approval is the +only path. ## Allowlist + safe bins