Slack integration

Add Slack as a messaging channel for NanoClaw. Perfect for team workspaces and professional communication.

Overview

The Slack integration uses @slack/bolt with Socket Mode, which means no public URL is required. The bot connects directly to Slack from your machine.

Features

Socket Mode - No webhooks or public URLs needed
Public and private channels - Respond in any channel the bot is added to
Direct messages - Users can DM the bot directly
Multi-channel support - Monitor multiple channels simultaneously
Channel metadata sync - Automatically syncs channel names
Thread flattening - Reads threaded replies (responds in main channel)

Adding Slack

Use the /add-slack skill to add Slack support:

Run the skill

claude
/add-slack

Choose deployment mode

Replace WhatsApp - Slack becomes the only channel
Alongside - Both WhatsApp and Slack run simultaneously

Apply code changes

The skill runs the skills engine which:

Adds src/channels/slack.ts (SlackChannel implementation)
Adds src/channels/slack.test.ts (46 unit tests)
Merges multi-channel support into src/index.ts
Adds Slack config to src/config.ts
Installs the @slack/bolt NPM package

Create Slack app

Set up a Slack app with Socket Mode and proper scopes

Configure environment

Add both tokens to .env and sync to container

Get channel IDs and register them with NanoClaw

Creating a Slack app

The setup process requires two tokens: a Bot Token (xoxb-) and an App-Level Token (xapp-).

Quick setup

Create the app

Go to api.slack.com/apps
Click Create New App → From scratch
Enter app name and select workspace

Enable Socket Mode

Go to Socket Mode in sidebar
Toggle Enable Socket Mode to On
Generate token with name nanoclaw
Copy the App-Level Token (starts with xapp-)

Subscribe to events

Go to Event Subscriptions
Toggle Enable Events to On
Add bot events:
- message.channels (public channels)
- message.groups (private channels)
- message.im (direct messages)
Click Save Changes

Add OAuth scopes

Go to OAuth & Permissions
Add these Bot Token Scopes:
- chat:write (send messages)
- channels:history (read public channels)
- groups:history (read private channels)
- im:history (read DMs)
- channels:read (list channels)
- groups:read (list private channels)
- users:read (look up display names)

Install to workspace

Go to Install App
Click Install to Workspace
Review permissions and click Allow
Copy the Bot User OAuth Token (starts with xoxb-)

For detailed setup with screenshots, see the SLACK_SETUP.md guide.

Configuration

Environment variables

Add to .env:

SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here

If you chose to replace WhatsApp:

SLACK_ONLY=true

Token reference

Token	Prefix	Where to find it
Bot User OAuth Token	`xoxb-`	OAuth & Permissions → Bot User OAuth Token
App-Level Token	`xapp-`	Basic Information → App-Level Tokens

Sync to container

mkdir -p data/env && cp .env data/env/env

Build and restart

npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Adding bot to channels

The bot only receives messages from channels it has been explicitly added to.

Open channel details

Click the channel name at the top of Slack

Add integration

Go to Integrations → Add apps

Search and add

Search for your bot name and add it to the channel

Repeat for each channel you want the bot to monitor.

Registering channels

Get channel ID

Option A - From URL: Open the channel in Slack on the web. The URL looks like:

https://app.slack.com/client/TXXXXXXX/C0123456789

The C0123456789 part is the channel ID. Option B - Right-click: Right-click the channel name → Copy link → extract the C... ID from the URL Option C - Via API:

curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'

Register the channel

The JID format is slack: followed by the channel ID. For your main channel (responds to all messages):

registerGroup("slack:C0123456789", {
  name: "#general",
  folder: "main",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: false,
});

For additional channels (trigger-only):

registerGroup("slack:C9876543210", {
  name: "#team-chat",
  folder: "team-chat",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: true,
});

Testing the connection

Send a message in your registered Slack channel:

For main channel: Any message works
For non-main channels: Include your trigger pattern (e.g., @Andy hello)

The bot should respond within a few seconds.

Check logs

tail -f logs/nanoclaw.log

Look for:

Connected to Slack
Received message from slack:C0123456789
Agent response queued

JID format

Slack channels use the slack: prefix:

Public channel: slack:C0123456789
Private channel: slack:G0123456789
Direct message: slack:D0123456789

Channel types

The Slack integration supports:

Public channels - Bot must be added to the channel
Private channels - Bot must be invited to the channel
Direct messages - Users can DM the bot directly
Multi-channel - Can monitor multiple channels simultaneously

Implementation details

The Slack channel implements the Channel interface using Socket Mode:

export class SlackChannel implements Channel {
  name = 'slack';
  
  async connect(): Promise<void> {
    this.app = new App({
      token: process.env.SLACK_BOT_TOKEN,
      appToken: process.env.SLACK_APP_TOKEN,
      socketMode: true,
    });
    
    this.app.message(async ({ message, client }) => {
      const channelJid = `slack:${message.channel}`;
      
      this.opts.onMessage(channelJid, {
        id: message.ts,
        chat_jid: channelJid,
        sender: message.user,
        sender_name: await this.getUserName(message.user),
        content: message.text,
        timestamp: new Date(parseFloat(message.ts) * 1000).toISOString(),
        is_from_me: false,
        is_bot_message: message.bot_id !== undefined,
      });
    });
    
    await this.app.start();
  }
}

Troubleshooting

Bot not responding

Check these items:

Both tokens are set in .env AND synced to data/env/env

Channel is registered:

sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'slack:%'"

For non-main channels: message must include trigger pattern
Service is running:
```
launchctl list | grep nanoclaw
```

Bot not receiving messages

Verify these settings:

Socket Mode is enabled (Slack app settings)
Bot is subscribed to correct events:
- message.channels
- message.groups
- message.im
Bot has been added to the channel
Bot has required OAuth scopes

Missing scope errors

If logs show missing_scope errors:

Go to OAuth & Permissions in Slack app settings
Add the missing scope listed in the error
Reinstall the app to workspace (scope changes require reinstall)
Copy the new Bot Token (it changes on reinstall)
Update .env and sync: cp .env data/env/env
Restart: launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Wrong token used

Verify token format:

Bot tokens start with xoxb-
App tokens start with xapp-

If your token doesn’t match, you may have copied the wrong one.

Known limitations

Threads are flattened - Threaded replies appear as regular channel messages. Responses go to main channel, not back into threads.
No typing indicator - Slack’s Bot API doesn’t expose a typing indicator endpoint.
Naive message splitting - Long messages split at 4000 chars, may break mid-sentence.
No file handling - Only text content is processed. File uploads and rich blocks are ignored.
Unbounded metadata sync - Channel list pagination has no upper bound, may be slow in large workspaces.

Removing Slack

To remove the Slack integration:

Delete channel files

rm src/channels/slack.ts
rm src/channels/slack.test.ts

Revert code changes

Remove SlackChannel import and creation from src/index.ts
Remove Slack config from src/config.ts
Remove Slack JID tests from src/routing.test.ts

Remove registrations

sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'slack:%'"

Uninstall dependency

npm uninstall @slack/bolt

Rebuild and restart

npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Next steps

Add Gmail

Add Gmail integration to your installation

Add Discord

Add Discord support to your installation

Skills system

Learn more about how skills work

Get Started

Core Concepts

Features

Integrations

Advanced

Slack integration

Overview

Features

Adding Slack

Creating a Slack app

Quick setup

Configuration

Environment variables

Token reference

Sync to container

Build and restart

Adding bot to channels

Registering channels

Get channel ID

Register the channel

Testing the connection

Check logs

JID format

Channel types

Implementation details

Troubleshooting

Known limitations

Removing Slack

Next steps

Add Gmail

Add Discord

Skills system

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Integrations

Advanced

​Overview

​Features

​Adding Slack

​Creating a Slack app

​Quick setup

​Configuration

​Environment variables

​Token reference

​Sync to container

​Build and restart

​Adding bot to channels

​Registering channels

​Get channel ID

​Register the channel

​Testing the connection

​Check logs

​JID format

​Channel types

​Implementation details

​Troubleshooting

​Known limitations

​Removing Slack

​Next steps

Add Gmail

Add Discord

Skills system

Build docs developers (and LLMs) love

Overview

Features

Adding Slack

Creating a Slack app

Quick setup

Configuration

Environment variables

Token reference

Sync to container

Build and restart

Adding bot to channels

Registering channels

Get channel ID

Register the channel

Testing the connection

Check logs

JID format

Channel types

Implementation details

Troubleshooting

Known limitations

Removing Slack

Next steps