Slack

​

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
• Two credentials to paste: the Bot User OAuth Token (xoxb-…, shown after Install to Workspace) and the Signing Secret (under Basic Information). No app-level token — v2 doesn’t use Socket Mode.
• A way to expose port 3000 publicly — ngrok, Cloudflare Tunnel, or a reverse proxy on a VPS

​

Install

​

Platform notes

• Webhook delivery — the bridge registers Slack on the shared webhook server (port 3000, configurable via WEBHOOK_PORT), which routes /webhook/slack to the adapter. Requests are authenticated with your signing secret. The public URL must stay reachable — if your tunnel dies, the bot silently stops hearing messages.
• 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 through the Interactivity request URL (same /webhook/slack route) and the card updates in place to show the selection. If buttons do nothing, 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 without webhooks; inbound doesn’t. Check that your public URL is up, Event Subscriptions is enabled with a verified Request URL, and the bot events are subscribed. Slack’s 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.