From 04b7e4894d72b06353d58a5393587752b5b7c30e Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 4 May 2026 18:30:11 -0700 Subject: [PATCH] docs(channels): add Socket vs HTTP comparison and explain shared URL fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Slack docs jumped straight from intro into the Quick Setup tabs without telling readers when to pick each transport. Add a Choosing Socket Mode or HTTP Request URLs section above Quick Setup with a concern-by-concern table (public URL, outbound network, tokens, dev laptops, scaling, multi-account, slash command transport, signing, recovery) plus a Note pointing at the right default for each shape. Also add an Info block under the HTTP Quick Setup manifest explaining why the manifest carries three url fields (slash_commands[].url, event_subscriptions.request_url, interactivity.request_url) — Slack's manifest schema requires them spelled out separately even though OpenClaw routes by payload type, and slash commands silently no-op without their url field in HTTP mode. --- docs/channels/slack.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 055a8df10c3..dbb99cc3d9f 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -19,6 +19,28 @@ Production-ready for DMs and channels via Slack app integrations. Default mode i +## Choosing Socket Mode or HTTP Request URLs + +Both transports are production-ready and reach feature parity for messaging, slash commands, App Home, and interactivity. Pick by deployment shape, not features. + +| Concern | Socket Mode (default) | HTTP Request URLs | +| ---------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | +| Public Gateway URL | Not required | Required (DNS, TLS, reverse proxy or tunnel) | +| Outbound network | Outbound WSS to `wss-primary.slack.com` must be reachable | No outbound WS; inbound HTTPS only | +| Tokens needed | Bot token (`xoxb-...`) + App-Level Token (`xapp-...`) with `connections:write` | Bot token (`xoxb-...`) + Signing Secret | +| Dev laptop / behind firewall | Works as-is | Needs a public tunnel (ngrok, Cloudflare Tunnel, Tailscale Funnel) or staging Gateway | +| Horizontal scaling | One Socket Mode session per app per host; multiple Gateways need separate Slack apps | Stateless POST handler; multiple Gateway replicas can share one app behind a load balancer | +| Multi-account on one Gateway | Supported; each account opens its own WS | Supported; each account needs a unique `webhookPath` (default `/slack/events`) so registrations do not collide | +| Slash command transport | Delivered over the WS connection; `slash_commands[].url` is ignored | Slack POSTs to `slash_commands[].url`; field is required for the command to dispatch | +| Request signing | Not used (auth is the App-Level Token) | Slack signs every request; OpenClaw verifies with `signingSecret` | +| Recovery on connection drop | Slack SDK auto-reconnects; the gateway's pong-timeout transport tuning applies | No persistent connection to drop; retries are per-request from Slack | + + + **Pick Socket Mode** for single-Gateway hosts, dev laptops, and on-prem networks that can reach `*.slack.com` outbound but cannot accept inbound HTTPS. + +**Pick HTTP Request URLs** when running multiple Gateway replicas behind a load balancer, when outbound WSS is blocked but inbound HTTPS is allowed, or when you already terminate Slack webhooks at a reverse proxy. + + ## Quick setup @@ -364,6 +386,10 @@ openclaw gateway **Recommended** matches the bundled Slack plugin's full feature set; **Minimal** drops files, reactions, pins, group-DM (`mpim:*`), `emoji:read`, and `usergroups:read` for restrictive workspaces. See [Manifest and scope checklist](#manifest-and-scope-checklist) for per-scope rationale. + + The three URL fields (`slash_commands[].url`, `event_subscriptions.request_url`, and `interactivity.request_url` / `message_menu_options_url`) all point at the same OpenClaw endpoint. Slack's manifest schema requires them named separately, but OpenClaw routes by payload type so a single `webhookPath` (default `/slack/events`) is enough. Slash commands without `slash_commands[].url` will silently no-op in HTTP mode. + + After Slack creates the app: - **Basic Information → App Credentials**: copy the **Signing Secret** for request verification.