docs: refresh connector public documentation

2026-08-14 00:48:07 +00:00 · 2026-05-04 20:59:16 +08:00
parent d1e8b0e92b
commit c6aef620bc
9 changed files with 54 additions and 21 deletions
@@ -66,6 +66,7 @@ This project is designed to make **ComfyUI a reliable automation target** with a
 - Admin writes, webhook ingress, and bridge worker paths are protected as explicit trust boundaries rather than convenience-only localhost helpers.
 - Connector ingress keeps allowlist and policy checks as first-class controls, with degraded/public posture handled deliberately instead of silently widening access.
 - Interactive connector actions are treated as a security boundary too: callback-capable platforms use signed envelopes, timestamp/replay guards, dedupe, and explicit policy mapping instead of trusting button actions as implicit admin intent.
+- Connector reply visibility is policy-driven: silent, internal, tool-only, and no-mention text replies can be suppressed without bypassing allowlists, replay checks, approvals, or action-button delivery.
 - Outbound egress is constrained: callback delivery and custom LLM base URLs stay behind SSRF-safe validation, exact-host policy, scoped private-network allowance, and explicit insecure overrides.
 - Secret handling stays server-side: browser storage is not used for secrets, local secret-manager integration is opt-in, and secrets-at-rest / token lifecycle controls are treated as operational boundaries.
 - Multi-tenant mode is isolation-first: tenant mismatches fail closed across config, secret sources, connector installations, approvals, visibility, and execution budgets.
@@ -89,6 +90,16 @@ Deployment profiles and hardening references:

 <details>

+<summary><strong>Connector replay, reply visibility, and scheduled delivery behavior aligned with current chat workflows</strong></summary>
+
+- Connector event handling now distinguishes duplicate committed actions from retryable pre-delivery failures across supported chat adapters, reducing accidental re-execution while still allowing safe retries.
+- Reply visibility is now governed by a shared connector policy for direct messages, shared chats, threads, internal delivery, and tool-only contexts; suppressed text is logged as a successful no-op instead of a delivery failure.
+- Telegram topics, Slack threads/workspaces, and Feishu account/workspace context are preserved for immediate replies and delayed result or approval follow-up, while approval/action buttons remain visible.
+
+</details>
+
+<details>
+
 <summary><strong>Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime</strong></summary>

 - Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability.
@@ -132,18 +143,6 @@ Deployment profiles and hardening references:

 </details>

-<details>
-
-<summary><strong>Verification governance, config bootstrap hygiene, and connector env hardening aligned with the current runtime</strong></summary>
-
- Promoted the staged coverage-ratchet baseline to the enforced `45%` floor, added retained review-cycle evidence for hotspot families, and wired backend coverage collection through one shared local/CI helper instead of ad hoc `fail_under` edits.
- Added focused connector and config/bootstrap hotspot regressions, reviewed the governed hotspot-family coverage summaries, and retired the temporary promotion-gap exceptions now that both promotion-blocking families are represented by explicit review evidence.
- Added fail-closed test-debt governance for no-skip modules and mutation-survivor allowlist entries, with explicit `reason` and `review_after` metadata now enforced by the standard full-test flow.
- Hardened pack metadata/version fallback parsing and made config/bootstrap imports side-effect-safe, so pack version fallback stays deterministic and importing config helpers no longer creates the state directory or log file before first real use.
- Added bounded connector numeric env parsing for delivery, media, timeout, rate-limit, command-length, OAuth TTL, and bind-port settings, so malformed values degrade to documented defaults or clamps with warnings instead of crashing startup.
-
-</details>
-
 See full update history: [docs/release/recent_updates.md](docs/release/recent_updates.md)

 </details>
@@ -670,6 +669,8 @@ The connector currently remains an **optional attached subsystem inside this rep
 - **Approvals**: Approve/Reject paused workflows from your phone.
 - **Secure**: Outbound-only for Telegram/Discord. LINE/WhatsApp/WeChat/KakaoTalk/Slack require inbound HTTPS (webhook), while Slack can also use Socket Mode and Feishu can run in either webhook or long-connection mode with a dedicated callback ingress path.
 - **Telegram topics**: Forum topic commands keep their topic context for immediate replies and delayed result delivery.
+- **Replay-safe actions and replies**: Duplicate or retried platform events are acknowledged without re-running completed actions; retryable failures before delivery commit can be retried.
+- **Reply visibility policy**: Direct-message, group/channel, thread, internal, and tool-only contexts share one visible/suppressed text decision; suppressed text is treated as a successful no-op and action/approval controls stay visible.
 - **WeChat encrypted mode**: Official Account encrypted webhook mode is supported when AES settings are configured.
 - **KakaoTalk response safety**: QuickReply limits and safe fallback handling are enforced for reliable payload behavior.
 - **Slack multi-workspace and interactive mode**: Workspace installs can be handled through connector-managed OAuth install/callback routes with per-workspace token binding, fail-closed health diagnostics, and signed interactive callback handling for action payloads.
@@ -18,8 +18,9 @@ If the deployment enables remote control or bridge features, it must also pass *
 - [ ] **Admin Boundaries**:
  - [ ] Server-side admin write boundary uses `OPENCLAW_ADMIN_TOKEN` (legacy `MOLTBOT_ADMIN_TOKEN`).
  - [ ] Connector admin command paths use `OPENCLAW_CONNECTOR_ADMIN_TOKEN`, and must match server admin token when server admin auth is enabled.
- [ ] **Connector Ingress Defaults**: Platform adapters remain disabled unless required token/enable vars are configured (Telegram/Discord/LINE/WhatsApp/WeChat/Kakao/Slack).
+- [ ] **Connector Ingress Defaults**: Platform adapters remain disabled unless required token/enable vars are configured (Telegram/Discord/LINE/WhatsApp/WeChat/Kakao/Slack/Feishu).
 - [ ] **Connector Allowlists (Strict Posture)**: In `public` deployment or `hardened` runtime posture, active connector platforms must have allowlist coverage before startup (fail-closed; public check code `DP-PUBLIC-009`).
+- [ ] **Connector Replay & Visibility**: Duplicate committed connector events are no-ops, retryable pre-commit failures can be retried, and text-only reply suppression does not hide approval/action controls.
 - [ ] **Observability**: `/openclaw/logs/tail` and `/openclaw/config` require `OPENCLAW_OBSERVABILITY_TOKEN` (legacy: `MOLTBOT_OBSERVABILITY_TOKEN`) if accessed remotely, or are loopback-only.
 - [ ] **SSRF**: LLM `base_url` defaults to known providers. Custom public URLs require `OPENCLAW_ALLOW_ANY_PUBLIC_LLM_HOST=1` or explicit allowlist; private/reserved IP targets require the scoped LLM private-network setting or the broader `OPENCLAW_ALLOW_INSECURE_BASE_URL=1` override.
 - [ ] **Public Boundary Contract (S69)**: for `OPENCLAW_DEPLOYMENT_PROFILE=public`, set `OPENCLAW_PUBLIC_SHARED_SURFACE_BOUNDARY_ACK=1` only after reverse-proxy path allowlist + network ACL deny ComfyUI-native high-risk routes.
@@ -180,6 +180,8 @@ For interactive connector callbacks (actions/modals/workflow style payloads), th
 - stale timestamp, replay/duplicate request ID, payload-hash mismatch, or unknown action type are rejected
 - workspace-to-installation resolution is fail-closed on missing/ambiguous/inactive/stale-token-ref binding
 - policy mapping is explicit (`public`/`run`/`admin`) and untrusted `run` callbacks degrade to approval instead of direct privileged execution
+- duplicate committed connector events are acknowledged without re-running completed actions, while retryable failures before action/delivery commit can be retried
+- reply visibility is policy-driven; text-only silent/internal/tool-only/no-mention replies can be suppressed without suppressing approval cards, action buttons, allowlist checks, or callback replay checks

 Operational note:

@@ -22,6 +22,7 @@ The connector runs alongside ComfyUI on your machine.
 - **Strict Profile Gate**: In `public` deployment or `hardened` runtime posture, enabling connector ingress without platform allowlist coverage is fail-closed at startup/deployment checks.
 - **Local Secrets**: Bot tokens are stored in your local environment, never sent to ComfyUI.
 - **Admin Boundary**: Control-plane actions call admin endpoints on the local OpenClaw server and require connector-side admin token configuration for admin command paths.
+- **Reply Visibility**: Shared visibility policy can suppress text-only silent/internal/tool-only/no-mention replies without suppressing approval cards, action buttons, or the underlying trust checks.

 ### Installation and callback contract baseline

@@ -33,6 +34,8 @@ OpenClaw now includes a platform-agnostic baseline for multi-workspace connector
 - workspace resolution is fail-closed on missing/ambiguous/inactive/stale bindings
 - installation diagnostics can also surface stable health states such as `ok`, `invalid_token`, `revoked`, `workspace_unbound`, and `degraded`
 - interactive callback contract enforces signed envelope checks, timestamp window, payload-hash validation, replay/idempotency guardrails, and command-policy mapping (`public`/`run`/`admin`) with explicit force-approval outcomes for untrusted `run` callbacks
+- connector replay handling acknowledges duplicate committed events as no-ops while allowing retryable failures before delivery commit to be retried
+- text reply visibility is resolved through one connector policy for direct-message, shared-chat, thread, internal-delivery, and tool-only contexts; suppressed text is logged/diagnostic and treated as successful no-op delivery

 Admin diagnostics APIs:

@@ -56,6 +59,7 @@ Slack multi-workspace notes:
 - Slack lifecycle events such as `tokens_revoked`, `app_uninstalled`, and rate-limit degradation update installation health so outbound replies fail closed or degrade predictably for the affected workspace.
 - In multi-workspace mode, outbound replies and delayed result deliveries resolve the bot token by workspace binding and keep Slack thread context when replying back to the originating conversation.
 - Slack interactive callbacks use the configured interactions path, signature verification, replay/idempotency checks, and connector policy mapping before accepting action payloads.
+- Slack text replies honor the shared reply-visibility policy when context metadata is available; channel no-mention or tool-only text can be suppressed while Block Kit/action responses remain deliverable.

 Feishu / Lark notes:

@@ -63,6 +67,7 @@ Feishu / Lark notes:
 - The connector supports both `feishu` and `lark` API domains through one shared binding contract, so region-specific app hosts do not require a different adapter.
 - Websocket-mode Feishu deployments still host a callback route so interactive approval cards and command buttons remain available when message ingress itself is long-connection based.
 - Feishu callback actions are signed, replay-guarded, tenant-aware, and deduplicated. Untrusted actors pressing run-affecting buttons are downgraded to approval flow instead of executing directly.
+- Feishu text replies honor the shared reply-visibility policy when context metadata is available; group no-mention or tool-only text can be suppressed while interactive cards remain deliverable.

 ### Multi-tenant boundary behavior

@@ -75,7 +80,7 @@ When backend multi-tenant mode is enabled (`OPENCLAW_MULTI_TENANT_ENABLED=1`):

 ## Supported Platforms

- **Telegram**: Long-polling (instant response), including forum topic reply context.
+- **Telegram**: Long-polling (instant response), including forum topic reply context for immediate replies and delayed result delivery.
 - **Discord**: Gateway WebSocket (instant response).
 - **LINE**: Webhook (requires inbound HTTPS).
 - **WhatsApp**: Webhook (requires inbound HTTPS).
@@ -680,6 +685,14 @@ Notes:
  - Sender is not in `OPENCLAW_CONNECTOR_ADMIN_USERS`.
  - Fix: Add ID to `.env` and restart connector.

+- **No visible chat reply after a command**:
+  - The command may have completed in a context where text-only replies are intentionally suppressed, such as internal delivery, tool-only handling, or a shared chat/channel without an active mention.
+  - Fix: check connector logs and job/approval state. Approval cards and action buttons should still be delivered when the action requires visible operator input.
+
+- **Duplicate platform event is acknowledged but not executed again**:
+  - The connector has already committed the action and treats the retry/replay as a successful no-op.
+  - Fix: check the original event, job, or approval record instead of resending the same action payload. Retry only failures that happened before delivery/action commit.
+
 - **HTTP 403 (Admin Token)**:
  - Connector has the right user allowlist, but the upstream OpenClaw server rejected the Admin Token.
  - Fix: Ensure `OPENCLAW_CONNECTOR_ADMIN_TOKEN` matches the server's `OPENCLAW_ADMIN_TOKEN`.
@@ -165,6 +165,8 @@ Controls the `connector` sidecar process and outbound delivery.
 Connector posture rules:
 - In strict posture (`OPENCLAW_DEPLOYMENT_PROFILE=public` or `OPENCLAW_RUNTIME_PROFILE=hardened`), active connector platforms without allowlist coverage are fail-closed.
 - Public deployment profile check surfaces this as `DP-PUBLIC-009`.
+- Connector reply visibility is policy-driven and does not introduce new secret/config knobs: text-only silent/internal/tool-only/no-mention replies can be suppressed by context, while approval cards and action buttons remain deliverable.
+- Connector replay handling treats duplicate committed events as successful no-ops and allows retry only for failures before action/delivery commit.
 - Slack multi-workspace installs persist only encrypted token refs in `connector_installations.json`; raw bot/app tokens remain in encrypted secret storage and must not appear in diagnostics or exported config surfaces.
 - Feishu/Lark bindings persist normalized installation identity plus secret references only; app secrets and callback signing material must stay in encrypted/local secret storage and must not appear in diagnostics or exported config surfaces.
 - Connector service-env propagation preserves only structured env-backed SecretRef metadata for supported connector credential variables. It reports secret-blind status/reason fields and rejects raw secrets, legacy marker strings, unsupported env names, missing envs, and runtime-only auth tokens such as admin, worker, and bridge tokens. Raw token values must not be written into diagnostics or service metadata.
@@ -7,6 +7,16 @@ Newest entries appear first.

 <details>

+<summary><strong>Connector replay, reply visibility, and scheduled delivery behavior aligned with current chat workflows</strong></summary>
+
+- Connector event handling now distinguishes duplicate committed actions from retryable pre-delivery failures across supported chat adapters, reducing accidental re-execution while still allowing safe retries.
+- Reply visibility is now governed by a shared connector policy for direct messages, shared chats, threads, internal delivery, and tool-only contexts; suppressed text is logged as a successful no-op instead of a delivery failure.
+- Telegram topics, Slack threads/workspaces, and Feishu account/workspace context are preserved for immediate replies and delayed result or approval follow-up, while approval/action buttons remain visible.
+
+</details>
+
+<details>
+
 <summary><strong>Startup lifecycle diagnostics, connector SecretRef service boundaries, and internal prompt isolation aligned with the current runtime</strong></summary>

 - Health diagnostics now distinguish required startup readiness, optional warmup degradation, and fatal startup failures; optional warmups run after route registration and no longer block baseline API availability.
@@ -18,6 +18,8 @@
  - Feishu/Lark: `OPENCLAW_CONNECTOR_FEISHU_ALLOWED_USERS` / `_ALLOWED_CHATS`
 - [ ] Verify startup banner shows "No trusted users" warning if allowlists are empty.
 - [ ] For strict posture (`OPENCLAW_DEPLOYMENT_PROFILE=public` or `OPENCLAW_RUNTIME_PROFILE=hardened`), do not enable connector ingress without allowlists; startup/deployment checks fail closed.
+- [ ] Verify duplicate or retried connector events are acknowledged without re-running completed actions.
+- [ ] Verify reply-visibility suppression only applies to text-only silent/internal/tool-only/no-mention contexts and does not suppress approval cards or action buttons.

 ### 2. Webhook Security (LINE)

@@ -68,6 +70,7 @@
 | Rate limiting | Enabled | 10 req/min/user, 30 req/min/channel |
 | Debug mode | Disabled | No sensitive logging |
 | Replay protection | Enabled | LINE webhooks reject replays >5min old |
+| Connector replay and reply visibility | Enabled | Duplicate committed events are no-ops; text-only suppressed replies do not suppress approval/action controls |
 | Slack / Feishu interactive callbacks | Signed + deduped | Callback actions reject stale/replayed envelopes and degrade untrusted run actions to approval flow |

 ## 📞 Support
@@ -228,16 +228,17 @@ OPENCLAW_LOCALHOST_ALLOW_NO_ORIGIN=0
 5. Enforce split control plane in public posture (`OPENCLAW_CONTROL_PLANE_MODE=split` + external URL/TOKEN).
 6. Keep `OPENCLAW_DEBUG_REASONING_REVEAL=0`; privileged reasoning reveal is for local debugging only and must not be enabled on public user planes.
 7. If any connector platform token/enable flag is configured, set corresponding platform allowlist vars before startup (`DP-PUBLIC-009` fail-closed).
-8. Keep risky features disabled on public user-facing plane.
-9. Keep `OPENCLAW_LOCALHOST_ALLOW_NO_ORIGIN=0` in public deployments.
-9. Verify split posture from capabilities:
+8. For connector approvals/actions, verify duplicate platform retries do not re-run completed actions and text-only reply suppression does not hide approval/action controls.
+9. Keep risky features disabled on public user-facing plane.
+10. Keep `OPENCLAW_LOCALHOST_ALLOW_NO_ORIGIN=0` in public deployments.
+11. Verify split posture from capabilities:
   - `GET /openclaw/capabilities` and confirm `control_plane.mode=split`
-10. Run:
+12. Run:
    - `python scripts/check_deployment_profile.py --profile public`
-11. Validate with project test and release gates before rollout:
+13. Validate with project test and release gates before rollout:
    - `tests/TEST_SOP.md`
    - [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md)
-12. Ensure `/openclaw/admin` is blocked at public edge unless a separately hardened private admin plane is in place.
+14. Ensure `/openclaw/admin` is blocked at public edge unless a separately hardened private admin plane is in place.

 ## 6. Bridge in Public Profile (only when absolutely required)

@@ -16,5 +16,5 @@

 - Bridge APIs and connector runtime are available.
 - Connector/sidecar runtime remains an optional attached subsystem; the primary package artifact is the ComfyUI custom node pack.
- Connector extraction remains a no-go-for-split-now decision until the shared installation/callback/delivery/config seams are independently versioned; see `docs/adr/ADR-0003-connector-extraction-feasibility-and-seams.md`.
+- Connector extraction remains a no-go-for-split-now decision until the shared installation/callback/delivery/reply-visibility/config seams are independently versioned; see `docs/adr/ADR-0003-connector-extraction-feasibility-and-seams.md`.
 - Standalone sidecar/gateway evolution is tracked in `.planning/roadmap.md`.