sutong/cc-connect
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

初始化仓库

Browse Source
This commit is contained in:
Kaxi
2026-06-02 23:14:41 +08:00
commit 0bc3f02670
520 changed files with 191097 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/slack.md
+326
View File
@@ -0,0 +1,326 @@
# Slack Setup Guide
This guide walks you through connecting **cc-connect** to Slack, so you can chat with your local Claude Code via a Slack bot.
## Prerequisites
- A Slack workspace account (with permission to create apps)
- A machine that can run cc-connect (no public IP needed)
- Claude Code installed and configured
> 💡 **Advantage**: Uses Socket Mode (WebSocket) — no public IP, no domain, no reverse proxy needed.
---
## Step 1: Create a Slack App
### 1.1 Open the Slack API Console
Go to [Slack API](https://api.slack.com/apps) and sign in with your Slack account.
### 1.2 Create a New App
1. Click "Create New App"
2. Select "From scratch"
3. Fill in the app details:
| Field | Suggested Value |
|-------|----------------|
| App Name | `cc-connect` |
| Development Slack Workspace | Select your workspace |
4. Click "Create App"
---
## Step 2: Configure Bot User
### 2.1 Go to App Home
In the left sidebar, click "App Home".
### 2.2 Set Bot Info
1. Click "Edit" to configure the bot display name
2. Fill in:
| Field | Suggested Value |
|-------|----------------|
| Display Name (Bot Name) | `cc-connect` |
| Default Username | `cc_connect` |
### 2.3 Always Show Bot Online
Toggle on "Always Show My Bot as Online".
---
## Step 3: Configure Permissions (OAuth Scopes)
### 3.1 Go to OAuth & Permissions
In the left sidebar, click "OAuth & Permissions".
### 3.2 Add Bot Token Scopes
Under "Scopes" → "Bot Token Scopes", add:
| Scope | Purpose |
|-------|---------|
| `app_mentions:read` | Read @mention messages |
| `chat:write` | Send messages |
| `im:history` | Read DM history |
| `im:read` | Read DM list |
| `im:write` | Send DMs |
| `channels:history` | Read channel messages (optional) |
| `groups:history` | Read private channel messages (optional) |
| `users:read` | Get user info |
---
## Step 4: Enable Socket Mode
### 4.1 Go to Socket Mode Settings
In the left sidebar, click "Socket Mode".
### 4.2 Enable Socket Mode
1. Toggle on "Enable Socket Mode"
2. Click "Generate Token and Enter Socket Mode"
### 4.3 Generate App-Level Token
1. Enter a token name (e.g. `cc-connect-socket-token`)
2. Add the following scope:
- `connections:write` — establish WebSocket connections
3. Click "Generate"
### 4.4 Save the Token
The system will generate an App-Level Token (format: `xapp-xxxxxxx...`). Save it immediately.
> ⚠️ The token is only shown once — copy it now!
---
## Step 5: Configure Event Subscriptions
### 5.1 Go to Event Subscriptions
In the left sidebar, click "Event Subscriptions".
### 5.2 Enable Events
1. Toggle on "Enable Events"
2. Since we're using Socket Mode, no Request URL is needed
### 5.3 Subscribe to Bot Events
Under "Subscribe to bot events", add:
| Event | Purpose |
|-------|---------|
| `app_mention` | Triggered when the bot is @mentioned |
| `message.im` | Triggered when a DM is received |
### 5.4 Save Changes
Click "Save Changes".
---
## Step 6: Install App to Workspace
### 6.1 Install the App
In the left sidebar, click "Install App" → "Install to Workspace".
### 6.2 Authorize
Review the permissions and click "Allow".
### 6.3 Get the Bot Token
After installation, you'll see:
```
Bot User OAuth Token: xoxb-xxxxxxx...
```
> ⚠️ Save this token — you'll need it for configuration.
---
## Step 7: Configure cc-connect
Add both tokens to your `config.toml`:
```toml
[[projects]]
name = "my-project"
[projects.agent]
type = "claudecode"
[projects.agent.options]
work_dir = "/path/to/your/project"
mode = "default"
[[projects.platforms]]
type = "slack"
[projects.platforms.options]
bot_token = "xoxb-xxxxxxx..."
app_token = "xapp-xxxxxxx..."
```
### Token Reference
| Token | Prefix | Purpose |
|-------|--------|---------|
| Bot Token | `xoxb-` | Bot API authentication |
| App Token | `xapp-` | Socket Mode connection |
---
## Step 8: Start cc-connect
### 8.1 Launch
```bash
cc-connect
# Or specify a config file
cc-connect -config /path/to/config.toml
```
### 8.2 Verify Connection
You should see logs like:
```
level=INFO msg="slack: connected"
level=INFO msg="platform started" project=my-project platform=slack
level=INFO msg="cc-connect is running" projects=1
```
---
## Step 9: Start Chatting
### 9.1 Direct Message
1. Search for your bot name in Slack
2. Open a DM conversation
3. Send a message
### 9.2 Channel Usage
1. Add the bot to a channel (`/invite @cc_connect`)
2. @mention the bot: `@cc_connect help me analyze the code`
3. The bot will respond
---
## Usage Example
```
User: @cc_connect Help me analyze the current project structure
cc-connect: 🤔 Thinking...
cc-connect: 🔧 Tool: Bash(ls -la)
cc-connect: Here's the project structure...
```
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Slack Cloud │
│ │
│ User Message ──→ Slack API ──→ Socket Mode Gateway │
│ │ │
└───────────────────────────────────────┼──────────────────────┘
│
│ WebSocket (no public IP needed)
▼
┌─────────────────────────────────────────────────────────────┐
│ Your Local Machine │
│ │
│ cc-connect ◄──► Claude Code CLI ◄──► Your Project Code │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Socket Mode vs Webhook
| Feature | Socket Mode | Webhook |
|---------|-------------|---------|
| Public IP | ❌ Not needed | ✅ Required |
| Domain | ❌ Not needed | ✅ Required |
| HTTPS cert | ❌ Not needed | ✅ Required |
| Reverse proxy | ❌ Not needed | ✅ Required |
| Connection | WebSocket | HTTP callback |
| Complexity | Simple | More complex |
| Best for | Local dev, private network | Production |
---
## FAQ
### Q: Socket Mode connection fails?
Check the following:
1. Is the App Token correct? (starts with `xapp-`)
2. Does the App Token have `connections:write` scope?
3. Is Socket Mode enabled in the app settings?
### Q: Bot doesn't respond to messages?
Check the following:
1. Is the Bot Token correct? (starts with `xoxb-`)
2. Are event subscriptions configured correctly?
3. Are the required scopes added?
### Q: Changes to permissions don't take effect?
**⚠️ Important**: After modifying scopes or events, you must reinstall the app!
1. Go to "Install App"
2. Click "Reinstall to Workspace"
### Q: Bot doesn't respond in DMs?
Make sure you've subscribed to the `message.im` event.
### Q: Bot doesn't respond in channels?
Make sure:
1. You've subscribed to the `app_mention` event
2. The bot has been added to the channel
3. You @mentioned the bot in your message
---
## References
- [Slack API Documentation](https://api.slack.com/)
- [Slack App Building Guide](https://api.slack.com/start/building)
- [Socket Mode Documentation](https://api.slack.com/apis/connections/socket)
- [Bot Token Scopes](https://api.slack.com/scopes)
- [Event Types](https://api.slack.com/events)
---
## See Also
- [Feishu Setup](./feishu.md)
- [DingTalk Setup](./dingtalk.md)
- [Weibo Setup](./weibo.md)
- [Telegram Setup](./telegram.md)
- [Discord Setup](./discord.md)
- [Back to README](../README.md)