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 existing channels - Slack becomes the only channel
Alongside - Add Slack alongside existing channels

Apply code changes

The skill merges the skill/slack branch which adds:

src/channels/slack.ts (SlackChannel implementation)
src/channels/slack.test.ts (46 unit tests)
Multi-channel support in src/index.ts
Slack config in src/config.ts
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 existing channels:

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.

Message formatting

Slack uses mrkdwn syntax, which differs from standard Markdown. NanoClaw includes a /slack-formatting container skill that provides the agent with a complete mrkdwn reference. Key differences from standard Markdown:

*bold* instead of **bold**
<url|text> instead of [text](url)
• bullets instead of numbered lists
No ## headings — use *Bold text* instead
:emoji: shortcodes for emoji

The formatting rules are also embedded in the group CLAUDE.md files so agents always have access to them, even without invoking the skill directly.

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

Since Slack was added via a git merge, you remove it by reverting the merge commit:

Find the merge commit

git log --merges --oneline | grep slack

Look for a commit like abc1234 Merge remote-tracking branch 'upstream/skill/slack'.

Revert the merge

git revert -m 1 <merge-commit>

This creates a new commit that undoes all of Slack’s code changes.

Remove registrations

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

Rebuild and restart

npm install
npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
# or: systemctl --user restart nanoclaw (Linux)

If you later want to re-apply Slack after reverting, you must revert the revert first — git treats reverted changes as “already applied and undone”. Claude handles this automatically when you run /add-slack again.

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

Changelog

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

Message formatting

Known limitations

Removing Slack

Next steps

Add Gmail

Add Discord

Skills system

Get Started

Core Concepts

Features

Integrations

Advanced

Changelog

​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

​Message formatting

​Known limitations

​Removing Slack

​Next steps

Add Gmail

Add Discord

Skills system

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

Message formatting

Known limitations

Removing Slack

Next steps