#5036: docs: improve Slack setup and troubleshooting guide
docs
channel: slack
Cluster:
Slack Integration Improvements
## Summary
This PR significantly improves the Slack integration documentation by adding comprehensive troubleshooting guidance and clearer setup instructions.
## Changes Made
### New Sections Added
- **Quick Start Checklist** - Prerequisites to avoid common setup issues
- **Comprehensive Troubleshooting** - Solutions for the most common problems:
- Bot not responding in channels (groupPolicy, bindings, bot invitations)
- Gateway crashes (undefined auth tokens, mixed workspace tokens)
- Token conflicts and workspace consistency issues
- **Group Policy Deep Dive** - Clear explanation of policy hierarchy and options
- **Multi-account Setup Examples** - Better examples with proper bindings
- **Debugging Commands** - Useful commands for troubleshooting
### Improvements Made
- Clarify that agent **bindings are required** for message routing
- Add security notes about gateway auth token configuration
- Improve multi-account examples with clear workspace separation
- Better explain groupPolicy hierarchy (account > channel > global)
- Add token format validation guidance
## Problem This Solves
Based on real troubleshooting experience, these are the most common issues users face:
1. **Gateway crashes** due to undefined auth tokens
2. **Bot ignores channel messages** due to wrong groupPolicy or missing bindings
3. **Authentication conflicts** from mixing tokens across workspaces
4. **User confusion** about pairing and approval process
## Testing
This documentation update is based on successfully resolving all these issues in a real deployment.
## Impact
This will significantly reduce setup friction for new users and provide clear troubleshooting paths when issues arise. Andrew (and other users) should now be able to set up Slack integration without hitting the common pitfalls.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates `docs/channels/slack.md` to make Slack setup more “copy/paste correct” and to add troubleshooting guidance for the most common integration failures. It adds a quick-start checklist, updates the minimal socket-mode config examples to include `groupPolicy` and required `bindings`, adds a multi-workspace `channels.slack.accounts` example, and introduces a new troubleshooting section (channel messages not handled, startup crashes, token conflicts) with a handful of debugging commands.
Overall, it aligns with the existing Slack docs by focusing on configuration patterns OpenClaw already uses (per-account configs + routing via bindings) and by documenting operational checks users typically need during first-time setup.
<h3>Confidence Score: 4/5</h3>
- Safe to merge; changes are documentation-only with a few wording/accuracy fixes recommended.
- The PR only changes Slack documentation and doesn’t affect runtime behavior. The main remaining risks are user-confusion from a couple of over-specific/incorrect token-format and workspace-ID examples, plus slightly fragile heading anchors due to emoji in a heading.
- docs/channels/slack.md
<!-- greptile_other_comments_section -->
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#7656: docs(slack): improve skill documentation with thread support and AP...
by pswpswpsw · 2026-02-03
81.7%
#8024: fix(slack): resolve channel names via directory for cross-account m...
by emma-digital-assistant · 2026-02-03
81.3%
#10894: Docs: fix legacy branding, add config reference, expand cron troubl...
by biv0711 · 2026-02-07
79.6%
#9166: Fix: Use userToken for Slack file downloads
by vishaltandale00 · 2026-02-04
79.6%
#21757: Docs/telegram inbound troubleshooting
by alanparesys · 2026-02-20
79.5%
#13881: fix: Address Greptile feedback - test isolation and channel resolution
by trevorgordon981 · 2026-02-11
79.1%
#11915: Docs: Docker + reverse proxy deployment notes and pairing pitfalls
by walshd1 · 2026-02-08
78.5%
#15863: fix: route agent-to-agent Slack messages to bound sessions
by MisterGuy420 · 2026-02-14
78.0%
#13486: fix: allow Slack HTTP mode without app token
by SepehrShapouri · 2026-02-10
77.7%
#2917: Slack: fix thread context + prevent reply spillover
by SocialNerd42069 · 2026-01-27
77.6%