Aetheel/docs/slack-setup.md

Slack Bot Setup Guide

Complete guide to creating a Slack bot and connecting it to Aetheel.

---

Table of Contents

1. Overview
2. Create a Slack App
3. Configure Bot Permissions
4. Enable Socket Mode
5. Enable Event Subscriptions
6. Install the App to Your Workspace
7. Get Your Tokens
8. Configure Aetheel
9. Run and Test
10. Troubleshooting
11. Architecture Reference

---

Overview

Aetheel connects to Slack using Socket Mode, which means:

• ✅ No public URL needed — works behind firewalls and NAT
• ✅ No webhook setup — Slack pushes events via WebSocket
• ✅ Real-time — instant message delivery
• ✅ Secure — encrypted WebSocket connection

This is the same approach used by OpenClaw (see src/slack/monitor/provider.ts), where they use @slack/bolt with socketMode: true.

What You'll Need

Item	Description
Slack Workspace	A Slack workspace where you have admin permissions
Bot Token	xoxb-... — for API calls (sending messages, reading info)
App Token	xapp-... — for Socket Mode connection
Python 3.10+	Runtime for the Aetheel service

---

Step 1: Create a Slack App

1. Go to https://api.slack.com/apps
2. Click "Create New App"
3. Choose "From scratch"
4. Fill in:
   • App Name: Aetheel (or any name you prefer)
   • Workspace: Select your workspace
5. Click "Create App"

You'll be taken to your app's Basic Information page.

---

Step 2: Configure Bot Permissions

Navigate to OAuth & Permissions in the left sidebar.

Scroll down to Scopes → Bot Token Scopes and add the following:

Required Scopes

Scope	Purpose
app_mentions:read	Receive @mentions in channels
channels:history	Read messages in public channels
channels:read	View basic channel info
chat:write	Send messages
groups:history	Read messages in private channels
groups:read	View private channel info
im:history	Read direct messages
im:read	View DM info
im:write	Open DM conversations
mpim:history	Read group DMs
mpim:read	View group DM info
users:read	Look up user info (for display names)

Optional Scopes (for future features)

Scope	Purpose
files:read	Read files shared in messages
files:write	Upload files
reactions:read	Read emoji reactions
reactions:write	Add emoji reactions

Tip: You can always add more scopes later, but you'll need to reinstall the app.

---

Step 3: Enable Socket Mode

1. Navigate to Socket Mode in the left sidebar
2. Toggle "Enable Socket Mode" to ON
3. You'll be prompted to create an App-Level Token:
   • Token Name: aetheel-socket (or any name)
   • Scopes: Add connections:write
4. Click "Generate"
5. ⚠️ Copy the xapp-... token now! You won't be able to see it again.
   • Save it somewhere safe — you'll need it in Step 6.

---

Step 4: Enable Event Subscriptions

1. Navigate to Event Subscriptions in the left sidebar
2. Toggle "Enable Events" to ON
3. Under Subscribe to bot events, add:

Event	Description
message.channels	Messages in public channels the bot is in
message.groups	Messages in private channels the bot is in
message.im	Direct messages to the bot
message.mpim	Group DMs that include the bot
app_mention	When someone @mentions the bot

4. Click "Save Changes"

Note: With Socket Mode enabled, you do NOT need a Request URL.

---

Step 5: Install the App to Your Workspace

1. Navigate to Install App in the left sidebar
2. Click "Install to Workspace"
3. Review the permissions and click "Allow"
4. You'll see the Bot User OAuth Token (xoxb-...) — copy it!

After installation, invite the bot to any channels where you want it to respond:

• In Slack, go to the channel
• Type /invite @Aetheel (or your bot's name)

---

Step 6: Get Your Tokens

After completing the steps above, you should have two tokens:

Token	Format	Where to Find
Bot Token	xoxb-1234-5678-abc...	OAuth & Permissions → Bot User OAuth Token
App Token	xapp-1-A0123-456...	Basic Information → App-Level Tokens (or from Step 3)

---

Step 7: Configure Aetheel

Option A: Using .env file (recommended)

# Copy the example env file
cp .env.example .env

# Edit .env with your tokens

Edit .env:

SLACK_BOT_TOKEN=xoxb-your-actual-bot-token
SLACK_APP_TOKEN=xapp-your-actual-app-token
LOG_LEVEL=INFO

Option B: Export environment variables

export SLACK_BOT_TOKEN="xoxb-your-actual-bot-token"
export SLACK_APP_TOKEN="xapp-your-actual-app-token"

---

Step 8: Run and Test

Install dependencies

pip install -r requirements.txt

Run the bot

# Start with smart handler (default)
python main.py

# Start in test/echo mode
python main.py --test

# Start with debug logging
python main.py --log DEBUG

Test sending and receiving

# Run the test suite — sends test messages to a channel
python test_slack.py --channel C0123456789

# Or send a DM test
python test_slack.py --dm U0123456789

# Send-only (no listening)
python test_slack.py --channel C0123456789 --send-only

Verify it's working

1. In Slack, go to a channel where the bot is invited
2. Type @Aetheel help — you should see the help response
3. Type @Aetheel status — you should see the bot's status
4. Send a DM to the bot — it should echo back with details

---

Troubleshooting

❌ "Slack bot token is required"

Problem: SLACK_BOT_TOKEN is not set or empty.

Fix:

1. Check your .env file exists and contains the token
2. Make sure there are no extra spaces or quotes around the token
3. Verify the token starts with xoxb-

❌ "Slack app-level token is required for Socket Mode"

Problem: SLACK_APP_TOKEN is not set.

Fix:

1. Go to your Slack app → Basic Information → App-Level Tokens
2. If no token exists, generate one with connections:write scope
3. Add it to your .env file

❌ "not_authed" or "invalid_auth"

Problem: The bot token is invalid or revoked.

Fix:

1. Go to OAuth & Permissions → check the Bot User OAuth Token
2. If it says "Not installed", reinstall the app
3. If you recently changed scopes, you need to reinstall

❌ Bot doesn't respond in channels

Problem: The bot is not invited to the channel, or you're not @mentioning it.

Fix:

1. In the Slack channel, type /invite @Aetheel
2. Make sure you @mention the bot: @Aetheel hello
3. For DMs, just message the bot directly — no @mention needed

❌ "channel_not_found" when sending

Problem: Using a channel name instead of ID, or bot isn't in the channel.

Fix:

1. Use channel ID not name. Find it in Slack:
   • Right-click the channel name → "View channel details"
   • The ID is at the bottom (starts with C)
2. Invite the bot to the channel first

❌ Socket Mode connection drops

Problem: The WebSocket connection is unstable.

Fix:

1. Check your internet connection
2. The SDK automatically reconnects — this is usually transient
3. If persistent, check Slack's status page

❌ "missing_scope"

Problem: The bot token doesn't have the required OAuth scopes.

Fix:

1. Go to OAuth & Permissions → Bot Token Scopes
2. Add the missing scope mentioned in the error
3. Reinstall the app (scope changes require reinstallation)

---

Architecture Reference

How It Works

┌──────────────────────┐
│     Your Slack       │
│     Workspace        │
│                      │
│  #general            │
│  #random             │
│  DMs                 │
└──────┬───────────────┘
       │ WebSocket (Socket Mode)
       │
┌──────▼───────────────┐
│  Aetheel Slack       │
│  Adapter             │
│                      │
│  • Token resolution  │
│  • Event handling    │
│  • Thread isolation  │
│  • Message chunking  │
│  • User/channel      │
│    name resolution   │
└──────┬───────────────┘
       │ Callback
       │
┌──────▼───────────────┐
│  Message Handler     │
│                      │
│  • Echo (test)       │
│  • Smart (commands)  │
│  • AI (future)       │
└──────────────────────┘

Key Files

File	Purpose
adapters/slack_adapter.py	Core Slack adapter (Socket Mode, send/receive)
main.py	Entry point with echo and smart handlers
test_slack.py	Integration test suite
.env	Your Slack tokens (not committed to git)
.env.example	Token template
requirements.txt	Python dependencies

Comparison with OpenClaw

Feature	OpenClaw (TypeScript)	Aetheel (Python)
Library	@slack/bolt	slack_bolt (official Python SDK)
Mode	Socket Mode (socketMode: true)	Socket Mode (SocketModeHandler)
Auth	auth.test() for identity	auth_test() for identity
Sending	chat.postMessage with chunking	chat_postMessage with chunking
Threading	thread_ts for conversation isolation	thread_ts for conversation isolation
DM Handling	conversations.open for user DMs	conversations_open for user DMs
Text Limit	4000 chars (chunked)	4000 chars (chunked)
Config	JSON5 config file	.env file
Accounts	Multi-account support	Single account (MVP)

---

Next Steps

Once the Slack adapter is working, you can:

1. Connect AI — Replace the echo handler with an AI-powered handler (Claude API)
2. Add Memory — Integrate the memory system for conversation context
3. Add Heartbeat — Set up proactive notifications via Slack
4. Add Skills — Load skills from the .claude/skills/ directory

See the main OpenClaw Analysis for the full architecture plan.