Slack

Give each NanoClaw agent its own identity in Slack. You can talk to an agent in a direct message, bring several agents into one shared room, and use a room canvas as shared working context. When you choose Slack in the setup wizard, NanoClaw creates the Slack app for you. Setup asks to open the perks dashboard in your browser. There you sign in with your NanoClaw account and pick the workspace. NanoClaw then creates the app, installs it, and stores its tokens. If you say no to the browser question, setup goes back to the channel list. You can connect Slack later. To create the app yourself at api.slack.com/apps, run /add-slack from Claude Code. It walks you through each screen.

What you get

/add-slack installs the base Slack channel:

One Slack app and one bot identity
Direct messages with per-thread agent sessions for newly created wirings
Public channels, private channels, and threaded conversations
File delivery, reactions, interactive questions, and Slack-native formatting

The agents feature adds per-agent identities, rooms, and canvases:

A separate Slack identity for each agent you create
Shared group-DM rooms where a human and several agents can work together
A canvas in each room for plans, decisions, and shared context
Direct-message onboarding prompts and the Slack section of the welcome tour
The create_room and add_to_room actions, plus the extended create_agent tool

Two things gate the agents feature. First, the feature skills. Setup applies the in-tree slack-a2a-rooms and then slack-agent-flow skills after /add-slack. You can also apply both skills on top of an existing /add-slack install. If either skill is missing from the checkout, setup warns and skips that capability. Second, a provisioning credential. Signing in with a NanoClaw account is enough, and the managed path is the common case. SLACK_MANAGER_TOKEN is the operator-supplied alternative. Without either one, agent creation still succeeds, but the Slack leg reports no-credentials and prints a finish command. A manually created app can run the agents feature. Add these Bot Token Scopes to it, because the manual checklist below does not include them:

app_mentions:read
mpim:write
mpim:history
canvases:read
canvases:write

Without those scopes, room creation and canvases fail. Also subscribe the app to these Bot Events:

message.mpim
member_joined_channel
member_left_channel

Without those events, the app cannot receive room messages or track room membership changes.

Before you start

You need:

A working NanoClaw install
Permission to install apps in the target Slack workspace

Managed setup also needs a NanoClaw account. Setup walks you through signing in from the portal link, then stores the install token at ~/.config/nanoclaw/account.json. You never create or paste that token yourself. The manual app path needs no account. Slack workspace policy still applies. A workspace that turns on Slack’s Admin Approved Apps policy refuses the automatic install, and a workspace admin has to approve the app before you can finish setup.

Set up the first agent

Managed setup
Manual app

Start setup

Run the installer:

bash nanoclaw.sh

Choose Slack

Select Slack when the setup wizard asks for a channel. When it asks How should this Slack account be registered?, choose Owner for your own account. The other options are for adding teammates later.

Connect your workspace

Answer yes to open the perks dashboard. Setup prints a link and opens it in your browser. Sign in with your NanoClaw account if asked, pick the Slack workspace where the agent should live, and turn on Slack. Terminal says Setup continues automatically as soon as it is enabled. and moves on by itself.

Let NanoClaw create the app

NanoClaw creates a Socket Mode app in that workspace and saves its tokens. The install finishes in the background, so setup can carry on with the next step.If your workspace needs an admin to approve new apps, get that approval and follow progress in the portal. Setup keeps waiting for it for up to 7 days.

Open the agent DM

When the install finishes, NanoClaw stores the tokens in .env, wires your direct message to the first agent group, restarts the service, and the agent sends you a welcome message in Slack. If Terminal says the Slack installation needs attention, open the portal to see what happened, then run pnpm exec tsx setup/portal.ts --stage slack from the nanoclaw folder to resume.

Use this path when you do not want managed provisioning or your workspace requires a self-managed app.

Create the app

Go to api.slack.com/apps, select Create New App, then select From scratch.

Add bot scopes

Under OAuth & Permissions, add these Bot Token Scopes:

chat:write
im:write
channels:history
groups:history
im:history
channels:read
groups:read
mpim:read
users:read
reactions:write
files:read
files:write

Enable direct messages

Under App Home, enable the Messages Tab. Then enable Allow users to send Slash commands and messages from the messages tab.

Choose event delivery

For Socket Mode, create an App-Level Token with connections:write, enable Socket Mode, and subscribe to message.channels, message.groups, message.im, and app_mention. Socket Mode needs no public URL.For webhook delivery, keep the Signing Secret and point Event Subscriptions and Interactivity to https://<your-public-host>/webhook/slack. Your public HTTPS endpoint must reach NanoClaw’s webhook port, which defaults to 3000.

Install and connect

Install the app to the workspace. Run /add-slack from Claude Code, $add-slack from Codex, or load add-slack with your harness’s skill tool. Choose the same delivery mode and paste the credentials when prompted.

The manual checklist matches the base /add-slack app. A managed app is created with the full scope and event set for group-DM agent rooms, canvases, onboarding, and membership updates. To run the agents feature on a manually created app, add the extra scopes and events listed under “What you get” above.

Create agents from Slack

The slack-agent-flow skill extends create_agent for sessions that start in Slack. Ask an existing Slack agent in plain language:

Create an agent called Research to compare the three deployment options.

Resolve the operator

NanoClaw identifies the Slack user making the request. That user needs a slack:U… identity in user_roles. Grant one with ncl roles grant if the flow reports operator-identity.

Verify the current bot

NanoClaw checks the originating bot’s token against Slack before it provisions anything.

Provision the new Slack app

NanoClaw creates a Slack app for the new agent, then writes its bot and app tokens to .env under the SLACK_INSTANCES key scheme.

Start the new adapter

NanoClaw registers the slack-<slug> adapter and starts it in the running host. No restart is needed.

Open the operator DM

The new bot opens a direct message with the operator and wires it to the new agent group.

Open the shared room

The new bot opens a group DM holding the operator, the originating bot, and itself. NanoClaw allowlists that room for agent-to-agent messages and creates the room canvas.

A canvas failure never blocks the flow. If another step fails, the agent group still exists and stays reachable through NanoClaw’s agent-to-agent messaging, and the error carries an idempotent finish command:

pnpm exec tsx scripts/slack-agent-flow-finish.ts --group <group-id> --name <slug> --source-group <source-group-id>

Agent-enabled Slack apps do not work for workspace guests. Ask for guest access when creating the agent to provision a plain Slack app instead.

Build a team in one room

For a team of agents, create each agent without an individual room. Then create one room for the whole team:

Create Research and QA as separate agents without rooms. Then create one room with both of them.

The slack-agent-flow skill adds two room actions:

create_room creates one shared room with several agents.
add_to_room adds another agent to an existing room.

In rooms created by the agents feature, each agent responds only when mentioned. Other room messages accumulate as context for its next mentioned turn. Bot-to-bot turns are mention-driven, and NanoClaw stops further bot-authored turns after six consecutive hops by default. A human message resets the counter.

Slack behavior

Conversations and threads

New Slack DM and channel wirings use per-thread sessions. Each Slack thread gets its own agent session, while the channel timeline provides surrounding context. Existing wirings keep the session behavior they were created with. The bot responds automatically in a direct message. In channels and shared rooms, mention the bot to start or resume its participation in that thread.

Rooms and membership

The agents feature adds room membership handling. When a Slack user invites an agent bot into a room, NanoClaw can adopt the room and create the required messaging group. The current Chat SDK does not dispatch bot-departure events, so removing a bot does not reliably update its NanoClaw wiring automatically. Shared agent rooms admit bot-authored messages only when the room is on the SLACK_A2A_ROOMS allowlist; bot messages remain blocked everywhere else.

Canvases

Agent rooms use a Slack canvas as shared, durable context. Agents can create, read, and edit canvas sections through the bot identity attached to the current session. Use the canvas for plans and decisions that should remain visible outside the message stream. The canvas tool and its container skill install with /slack-agent-flow.

Files and formatting

Agents can receive files, send generated files, and add reactions. Slack uses mrkdwn, not standard Markdown. The base /add-slack payload installs the slack-formatting container skill, so formatting guidance reaches agent containers without the agents feature. Pasted Slack tables are recovered from the platform payload as readable text for the agent.

Configuration reference

Variable	Purpose
`SLACK_BOT_TOKEN`	Bot User OAuth Token for the default Slack identity. Starts with `xoxb-`.
`SLACK_APP_TOKEN`	App-Level Token for Socket Mode. Starts with `xapp-`. When present, the adapter uses Socket Mode.
`SLACK_SIGNING_SECRET`	Verifies incoming requests in webhook mode. Not required for Socket Mode.
`SLACK_MANAGER_TOKEN`	Advanced alternative to the managed service. Supply your own Slack workspace manager token to create apps directly against Slack. Setup never produces one. It is not passed into agent containers. When it is set, the setup wizard first asks How do you want to create the Slack app? with Create it for me and I will create it myself; without it, setup goes straight to the portal flow.
`SLACK_SERVICE_BASE`	Overrides the managed Slack service URL. Most installs should leave it unset.
`SLACK_INSTANCES`	Comma-separated names for additional Slack bot identities, such as `research,qa`.
`SLACK_BOT_TOKEN_<NAME>`	Bot token for a named identity. Uppercase the name and replace dashes with underscores.
`SLACK_APP_TOKEN_<NAME>`	Socket Mode app token for a named identity.
`SLACK_SIGNING_SECRET_<NAME>`	Webhook signing secret for a named identity.
`SLACK_A2A_ROOMS`	Comma-separated Slack conversation IDs that admit messages from sibling bots. Re-read within about 30 seconds.
`SLACK_A2A_MAX_HOPS`	Consecutive bot-authored messages allowed before a human must speak. Default `6`.

After editing instance tokens by hand, restart NanoClaw so the adapter registers the new identity. Programmatically created agents are hot-started and do not need that restart.

Troubleshooting

Slack asks for admin approval — ask a workspace admin to approve the app. Setup finishes in the background once the approval lands (it waits up to 7 days), and the agent then DMs you in Slack. If the saved install shows as failed, check its progress in the portal and resume with pnpm exec tsx setup/portal.ts --stage slack. If it shows as expired, review the existing app in the portal before restarting Slack setup. Provisioning does not bypass the workspace policy.
The welcome DM arrives, but replies disappear — for Socket Mode, confirm SLACK_APP_TOKEN is set, Socket Mode is enabled, and the four bot events are subscribed. For webhook mode, confirm the public URL is reachable and uses the matching Signing Secret.
The token is rejected — use the Bot User OAuth Token from OAuth & Permissions, not a user token. A bot token starts with xoxb-; an App-Level Token starts with xapp-.
A new agent exists but has no Slack bot — follow the finish command in the failure message. The agent group remains usable while the Slack provisioning leg is retried.
Agents do not answer each other in a room — confirm the room ID is in SLACK_A2A_ROOMS, mention the next bot explicitly, and verify that the sender is permitted by the room’s access policy.
A manually added instance does not connect — verify its name is present in SLACK_INSTANCES, check the matching suffixed token keys, then restart the service.

For service logs, restarts, and wiring checks, see Troubleshooting. For the general agent collaboration model, see Multi-agent swarm.

Get started

Channels

Operate

Build with agents

Templates

Extend

Understand

Changelog

What you get

Before you start

Set up the first agent

Create agents from Slack

Build a team in one room

Slack behavior

Conversations and threads

Rooms and membership

Canvases

Files and formatting

Configuration reference

Troubleshooting

​What you get

​Before you start

​Set up the first agent

​Create agents from Slack

​Build a team in one room

​Slack behavior

​Conversations and threads

​Rooms and membership

​Canvases

​Files and formatting

​Configuration reference

​Troubleshooting

What you get

Before you start

Set up the first agent

Create agents from Slack

Build a team in one room

Slack behavior

Conversations and threads

Rooms and membership

Canvases

Files and formatting

Configuration reference

Troubleshooting