sutong/cc-connect
1
0
Fork 0
Code Issues Pull Requests Actions 2 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/discord.md
+309
View File
@@ -0,0 +1,309 @@
# Discord Setup Guide
This guide walks you through connecting **cc-connect** to Discord, so you can chat with your local Claude Code via a Discord bot.
## Prerequisites
- A Discord account
- A machine that can run cc-connect (no public IP needed)
- Claude Code installed and configured
> 💡 **Advantage**: Uses Gateway (WebSocket) — no public IP, no domain, no reverse proxy needed.
---
## Step 1: Create a Discord Application
### 1.1 Open the Developer Portal
Go to [Discord Developer Portal](https://discord.com/developers/applications) and sign in.
### 1.2 Create a New Application
1. Click "New Application" in the top right
2. Enter an application name (e.g. `cc-connect`)
3. Agree to the Terms of Service
4. Click "Create"
---
## Step 2: Create a Bot User
### 2.1 Go to Bot Settings
In the left sidebar, click "Bot".
### 2.2 Add a Bot
1. Click "Add Bot"
2. Confirm the action
### 2.3 Configure Bot Info
| Field | Suggested Value |
|-------|----------------|
| Username | `cc-connect` |
| Avatar | Upload an icon you like |
---
## Step 3: Get the Bot Token
### 3.1 Generate Token
On the Bot page:
1. Click "Reset Token"
2. You may need to enter a 2FA code
3. Click "Copy" to copy the token
> ⚠️ The token is only shown once — save it immediately! Format: `MTk4NjIyNDgzNDcOTY3NDUxMg.G8vKqh.xxx...`
### 3.2 Lost Your Token?
Click "Reset Token" at any time to regenerate. The old token will be invalidated immediately.
---
## Step 4: Configure Privileged Intents (Important!)
### 4.1 What Are Intents?
Intents control which events your bot can receive from Discord's Gateway.
### 4.2 Enable Required Intents
On the Bot page, under "Privileged Gateway Intents", enable:
| Intent | Purpose | Required? |
|--------|---------|-----------|
| **Message Content Intent** | Read message content | ✅ **Required** |
| Presence Intent | Read user status | Optional |
| Server Members Intent | Read server members | Optional |
> ⚠️ **You must enable Message Content Intent**, or the bot won't be able to read messages!
### 4.3 Save Changes
Click "Save Changes".
---
## Step 5: Configure cc-connect
Add the token 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 = "discord"
[projects.platforms.options]
token = "MTk4NjIyNDgzNDcOTY3NDUxMg.G8vKqh.xxx..."
# thread_isolation = true # Optional: isolate each agent session in its own Discord thread
# progress_style = "legacy" # Optional: legacy | compact | card
```
> cc-connect automatically configures the required Intents (MESSAGE_CONTENT, GUILD_MESSAGES, DIRECT_MESSAGES).
> With `thread_isolation = true`, cc-connect creates or reuses a Discord thread for each session and routes follow-up messages by thread channel ID.
> `progress_style = "compact"` merges thinking/tool updates into one editable message; `progress_style = "card"` renders a Discord-native embed progress card and still sends the final answer as a normal message.
---
## Step 6: Generate an Invite Link
### 6.1 Go to OAuth2 Settings
In the left sidebar, click "OAuth2" → "URL Generator".
### 6.2 Select Scopes
Under "Scopes", check:
- ✅ `bot`
### 6.3 Select Permissions
Under "Bot Permissions", check:
| Permission | Purpose |
|------------|---------|
| Read Messages/View Channels | Read messages |
| Send Messages | Send messages |
| Create Public Threads | Create a new thread for a fresh agent session |
| Send Messages in Threads | Send messages in threads |
| Read Message History | Read message history |
### 6.4 Copy the Link
1. The invite link will be generated at the bottom of the page
2. Click "Copy"
---
## Step 7: Invite the Bot to Your Server
### 7.1 Open the Invite Link
Open the copied URL in your browser and sign in to Discord.
### 7.2 Select a Server
Choose the server you want to add the bot to from the dropdown.
### 7.3 Authorize
Review the permissions and click "Authorize". Complete the CAPTCHA if prompted.
---
## 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="discord: connected" bot=cc-connect#0000
level=INFO msg="platform started" project=my-project platform=discord
level=INFO msg="cc-connect is running" projects=1
```
---
## Step 9: Start Chatting
### 9.1 Channel Usage
Send a message in any channel where the bot has permissions.
### 9.2 Direct Message
1. Click the bot's avatar
2. Send a DM
---
## Usage Example
```
User: Help me analyze the current project structure
cc-connect: 🤔 Thinking...
cc-connect: 🔧 Tool: Bash(ls -la)
cc-connect: Here's the project structure...
```
If you enable `progress_style = "card"`, Discord shows one editable progress embed during the turn, then the final answer arrives as a separate normal message. This reduces channel noise compared with the legacy multi-message flow.
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Discord Cloud │
│ │
│ User Message ──→ Discord Gateway ◄── WebSocket │
│ │ │
└─────────────────────────┼────────────────────────────────────┘
│
│ WebSocket (no public IP needed)
▼
┌─────────────────────────────────────────────────────────────┐
│ Your Local Machine │
│ │
│ cc-connect ◄──► Claude Code CLI ◄──► Your Project Code │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Discord Gateway Features
| Feature | Details |
|---------|---------|
| **Connection** | WebSocket |
| **Public IP** | ❌ Not needed |
| **Heartbeat** | Automatic keepalive |
| **Reconnection** | Automatic on disconnect |
| **Intents** | Must declare required event types |
| **Message limit** | 2000 characters per message (auto-split by cc-connect) |
| **Markdown** | Full native support |
---
## FAQ
### Q: Bot can't read message content?
**Most common issue**: Message Content Intent is not enabled!
Fix:
1. Go to Discord Developer Portal
2. Select your app → Bot
3. Enable "Message Content Intent"
4. Save changes
5. Restart cc-connect
### Q: Bot connects then immediately disconnects?
Check:
1. Is the bot token correct?
2. Are intents configured properly?
3. Are you hitting Discord rate limits? (from frequent reconnects)
### Q: Bot doesn't appear in the server?
1. Make sure you used the invite link to add the bot
2. Check if the bot was kicked from the server
### Q: How to regenerate the token?
1. Go to Discord Developer Portal
2. Select your app → Bot
3. Click "Reset Token"
4. Update your config.toml
### Q: Bot has insufficient permissions?
1. Generate a new invite link with the correct permissions
2. Re-invite the bot to the server
---
## References
- [Discord Developer Portal](https://discord.com/developers/applications)
- [Discord API Documentation](https://discord.com/developers/docs/intro)
- [Bot Getting Started Guide](https://discord.com/developers/docs/getting-started)
- [Gateway Intents](https://discord.com/developers/docs/topics/gateway#privileged-intents)
- [OAuth2 Scopes](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes)
---
## See Also
- [Feishu Setup](./feishu.md)
- [DingTalk Setup](./dingtalk.md)
- [Weibo Setup](./weibo.md)
- [Telegram Setup](./telegram.md)
- [Slack Setup](./slack.md)
- [Back to README](../README.md)