This guide will help you connect QClaw to Slack, so you can control QClaw and receive responses directly through Slack messages.
Prerequisites
Before getting started, make sure you have:
QClaw installed on your computer
A Slack account
A Slack workspace where you have permissions to install apps (Admin approval may be required depending on your workspace settings)
If you don't have a Slack workspace, you can create one for free at slack.com. Click "Create a new workspace" and follow the setup instructions.
-----------------------------------------
Setup Flow
Overall Process
Create a Slack App -> Get the Bot Token -> Invite the App to Your Workspace -> Configure QClaw
-----------------------------------------
Detailed Steps:
Step 1: Create a Slack App
1. Go to the Slack API Portal and log in with your Slack account.
2. Click "Create New App" on the page.
3. Select "From Scratch" in the dialog that appears.
4. Enter a name for your app (e.g., QClaw Bot) and click select the Slack workspace you want to use, then click "Create App".
This name will be visible to other members of your workspace when they interact with the bot, so choose something recognizable.
5. (Optional) Upload an icon and add a description for your app under Basic Information page.
-----------------------------------------
Step 2: Enable Socket Mode
1. In the left sidebar, click "Socket Mode".
2. Toggle on "Enable Socket Mode"; this must be enabled to allow communication between the QClaw and Slack.
-----------------------------------------
Step 3: Get the Bot Token
1. In the left sidebar, click "OAuth & Permissions".
2. Scroll down to the Scope section and under Bot Token Scopes, click "Add an OAuth Scope". Add the following scopes (and other permission if you want. e.g. file read for qclaw via messages):
3. Scroll back to the top of the OAuth & Permissions page and click "Install to Work", then click "Allow" to authorize.
Security Notice: Keep your bot token private. Anyone with this token can control your bot. Do not share it or commit it to public repositories.
4. Get Bot User OAuth Token(it starts with xoxb-) on OAuth & Permissions Page
5. Save this token, you will need it when configuring QClaw.
-----------------------------------------
Step 4: Enable Event Subscriptions
1. In the left sidebar, click "Event Subscriptions" and toggle Enable Events to On.
2. Under Subscribe to bot events, click "Add Bot User Event" and add:
message.channels (optional, for public channel messages)
any other permission you want
3. Click "Save Changes".
-----------------------------------------
Step 5: Get App Level Tokens
1. In the left sidebar, click "Basic Informtion" and scroll down to App-Level Tokens.
2. Click "Generate Token and Scopes" and "Add Scope" select:
connections:write
3. Click "Generate" and copy your App-Level Token which would be used in following configuration.
-----------------------------------------
Step 6: Configure QClaw
1. Open QClaw on your computer.
2. Click the Channels button in the bottom-left corner.
3. Select "Slack" from the list of platforms, then click "Configure".
4. Paste the Bot Token & the App-Level Token you copied in previous steps into the token field.
5. Click "Connect" to complete the setup.
6. Now, you have Slack Connected to your QClaw
-----------------------------------------
Start Using
QClaw on Slack supports two usage modes: Direct Message (DM) and Channel.
1. Direct Message (DM): Open Slack and find your bot in your Direct Messages in the left side bar. Send it a message, for example, "Hello", to test the connection. If configured correctly, QClaw will receive the message and reply in Slack.
2. Channel: Go to any channel in your workspace where the bot has been added. Mention the bot using @BotName followed by your message. If configured correctly, QClaw will receive the mention and reply in the channel.
If the bot replies successfully, you have completed the QClaw–Slack integration! 🎉
-----------------------------------------
Frequently Asked Questions
1. The bot doesn't respond — what should I check?
Check your bot token: Make sure the token pasted in QClaw is correct and hasn't been regenerated. If you reinstall the app in the Slack API Portal, a new token is issued and you'll need to update it in QClaw.
Check QClaw is running: The bot only works when QClaw is actively running on your computer.Check channel permissions: Make sure the bot has been added to the channel and has the correct OAuth scopes enabled.
2. The bot appears offline in my workspace — what's wrong?
This usually means QClaw is not running, or the bot token in QClaw is incorrect. Check that QClaw is open on your computer and that the token matches the one shown in the Slack API Portal under OAuth & Permissions.
3. I can't DM the bot, it says "Sending messages to this app has been turned off" in the chatbox
Please check your App Home settings to ensure that users are allowed to send slash commands and messages in the "Messages" tab.