Slack

• Socket Mode (the setup default) — the bot opens an outbound WebSocket to Slack, so events arrive over that connection and NanoClaw needs no public URL. Ideal for local dev or a host behind NAT. Setting SLACK_APP_TOKEN (xapp-…) is what flips the adapter into this mode.
• Webhook mode — Slack POSTs to /webhook/slack on NanoClaw’s shared webhook server, which needs a public HTTPS URL that reaches your machine. The adapter uses this mode whenever SLACK_APP_TOKEN is unset.

​

Prerequisites

• A Slack workspace where you can install apps
• A working NanoClaw install (quickstart)
• A Slack app created From scratch at api.slack.com/apps with these Bot Token Scopes (under OAuth & Permissions): chat:write, im:write, im:history, channels:read, channels:history, groups:read, groups:history, users:read, reactions:write, files:read, files:write
• App Home → enable the Messages Tab and check “Allow users to send slash commands and messages from the messages tab” — without this you can’t DM the bot
• The Bot User OAuth Token (xoxb-…, shown after Install to Workspace), plus the credential for your chosen mode: an App-Level Token (xapp-… with the connections:write scope, under Basic Information → App-Level Tokens) for Socket Mode, or the Signing Secret (under Basic Information) for webhook mode. In Socket Mode the signing secret is optional — Slack signs socket frames separately.
• Webhook mode only: a way to expose port 3000 publicly — ngrok, Cloudflare Tunnel, or a reverse proxy on a VPS. Socket Mode needs none of this.

​

Install

​

Platform notes

• Event delivery — in Socket Mode the bot holds an outbound WebSocket to Slack, so nothing inbound needs to be reachable. In webhook mode the bridge registers Slack on the shared webhook server (port 3000, configurable via WEBHOOK_PORT), routes /webhook/slack to the adapter, and authenticates requests with your signing secret — the public URL must stay reachable, or the bot silently stops hearing messages if your tunnel dies.
• Threads — the adapter sets supportsThreads: true, so in group channels the router forces per-thread sessions: each Slack thread gets its own agent session (unless the wiring uses agent-shared, which keeps one session across all of an agent’s messaging groups). DMs collapse sub-threads into one session. See the entity model.
• Mentions and engagement — @mentioning the bot in an unwired channel reaches the router as a platform-confirmed mention (the app_mention event); in mention-sticky wirings the bot then sticks to that thread (plain mention wirings respond per mention without subscribing). DMs are always treated as addressed to the bot.
• Interactive questions — when an agent asks a multiple-choice question, it renders as a card with buttons. Clicks arrive over the same channel as events — the socket in Socket Mode, the /webhook/slack route (via Interactivity & Shortcuts) in webhook mode — and the card updates in place to show the selection. If buttons do nothing in webhook mode, Interactivity isn’t configured.
• Attachments and reactions — file uploads are downloaded and passed to the agent as data (files:read), and the agent can react to messages (reactions:write).
• Formatting — Slack uses mrkdwn, not standard Markdown (*bold* not **bold**, <url|text> links, no headings). The slack-formatting container skill is mounted into agent containers with a full mrkdwn reference.
• No outbound chunking — the adapter doesn’t set the bridge’s maxTextLength, so long replies are posted as a single message. Slack’s message limit is high enough that this rarely matters.

​

Troubleshooting

• “Slack didn’t accept that token” — auth.test rejected it (invalid_auth or token_revoked). Copy the token again from OAuth & Permissions and retry setup. “Couldn’t reach Slack” instead means a network problem.
• Welcome DM arrived but the bot never replies — outbound works regardless; inbound depends on your mode. In Socket Mode, confirm SLACK_APP_TOKEN is set and Enable Socket Mode is toggled on in the app. In webhook mode, check that your public URL is up, Event Subscriptions is enabled with a verified Request URL, and the bot events are subscribed (URL verification fails if the signing secret in .env doesn’t match the app).
• missing_scope when opening the DM — your app lacks im:write. Add it under OAuth & Permissions, reinstall the app to the workspace, then retry setup.
• Webhook returns 404 Unknown adapter: slack — the adapter never registered, usually because SLACK_BOT_TOKEN is missing from the environment the service reads (the factory returns null without it). Verify .env and data/env/env, then restart the service.