ce07a19b61
- Add Kook chat platform integration via WebSocket - Support private messages and channel messages - Implement user allowlist (allowedUserId) for security - Add automatic message chunking for long messages - Include auto-reconnection mechanism - Add comprehensive documentation
140 lines
4.4 KiB
Markdown
140 lines
4.4 KiB
Markdown
---
|
|
summary: "Kook bot support status, capabilities, and configuration"
|
|
read_when:
|
|
- Working on Kook channel features
|
|
---
|
|
# Kook (Bot API)
|
|
|
|
|
|
Status: production-ready for bot DMs + channels via WebSocket.
|
|
|
|
## Quick setup (beginner)
|
|
1) Create a bot on the [Kook Developer Platform](https://developer.kookapp.cn/bot/) and copy the token.
|
|
2) Set the token:
|
|
- Env: `KOOK_BOT_TOKEN=...`
|
|
- Or config: `channels.kook.token: "..."`.
|
|
- If both are set, config takes precedence (env fallback is default-account only).
|
|
3) Start the gateway.
|
|
4) **Security**: Set `channels.kook.allowedUserId` to restrict bot access to your user ID only.
|
|
|
|
Minimal config:
|
|
```json5
|
|
{
|
|
channels: {
|
|
kook: {
|
|
enabled: true,
|
|
token: "your-bot-token",
|
|
allowedUserId: "your-user-id" // strongly recommended for security
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## What it is
|
|
- A Kook Bot API channel owned by the Gateway.
|
|
- Deterministic routing: replies go back to Kook; the model never chooses channels.
|
|
- DMs share the agent's main session; channels stay isolated (`agent:<agentId>:kook:channel:<channelId>`).
|
|
|
|
## Setup (fast path)
|
|
### 1) Create a bot token
|
|
1) Visit the [Kook Developer Platform](https://developer.kookapp.cn/bot/).
|
|
2) Create a new bot application and copy the Bot Token.
|
|
3) Store the token safely.
|
|
|
|
### 2) Configure the token (env or config)
|
|
Example:
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
kook: {
|
|
enabled: true,
|
|
token: "your-bot-token",
|
|
allowedUserId: "your-user-id"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Env option: `KOOK_BOT_TOKEN=...` (works for the default account).
|
|
If both env and config are set, config takes precedence.
|
|
|
|
### 3) Get your user ID (for security)
|
|
**Method 1**: Enable Developer Mode in Kook
|
|
1. Open Kook → Personal Settings → Advanced Settings → Developer Mode → Enable
|
|
2. Right-click your avatar in any server channel → Copy ID
|
|
|
|
**Method 2**: Check logs
|
|
Send a message to the bot and check the gateway logs for `authorId`.
|
|
|
|
### 4) Start the gateway
|
|
```bash
|
|
moltbot gateway
|
|
```
|
|
|
|
Kook channel starts when a token is resolved (config first, env fallback) and `channels.kook.enabled` is not `false`.
|
|
|
|
## Features
|
|
- **WebSocket connection**: Real-time message delivery via Kook's WebSocket API
|
|
- **Private messages**: Support for direct messages with the bot
|
|
- **Channel messages**: Support for messages in server channels
|
|
- **User allowlist**: `allowedUserId` restricts bot control to specific users (security)
|
|
- **Message chunking**: Automatically splits long messages to fit Kook's limits
|
|
- **Auto-reconnection**: Handles connection drops and reconnects automatically
|
|
|
|
## Security
|
|
- **Strongly recommended**: Set `channels.kook.allowedUserId` to your Kook user ID
|
|
- Without `allowedUserId`, anyone who can DM the bot or is in the same channel can control it
|
|
- The bot will only respond to messages from the specified user ID(s)
|
|
|
|
## Configuration reference
|
|
|
|
### Core settings
|
|
```json5
|
|
{
|
|
channels: {
|
|
kook: {
|
|
enabled: true, // Enable/disable the Kook channel
|
|
token: "YOUR_BOT_TOKEN", // Required: Bot token from developer platform
|
|
allowedUserId: "USER_ID" // Strongly recommended: Your Kook user ID
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Environment variables
|
|
- `KOOK_BOT_TOKEN`: Bot token (fallback for default account)
|
|
|
|
## Troubleshooting
|
|
|
|
### Bot not responding
|
|
1. Check that `channels.kook.enabled` is `true`
|
|
2. Verify your bot token is correct
|
|
3. Check gateway logs for connection errors
|
|
4. Ensure `allowedUserId` matches your Kook user ID
|
|
|
|
### Connection issues
|
|
- Kook WebSocket connection requires stable internet
|
|
- The bot automatically reconnects on connection drops
|
|
- Check gateway logs for WebSocket connection status
|
|
|
|
### Message not sent
|
|
- Verify the bot has permission to send messages in the channel
|
|
- Check if message length exceeds limits (automatically chunked)
|
|
- Review gateway logs for delivery errors
|
|
|
|
## Message routing
|
|
- **Private messages**: Collapse into the agent's main session (default `agent:main:main`)
|
|
- **Channel messages**: Isolated per channel (`agent:<agentId>:kook:channel:<channelId>`)
|
|
- Replies always go back to the channel they arrived on (deterministic routing)
|
|
|
|
## Known limitations
|
|
- Kook API rate limits apply (handled automatically with retries)
|
|
- Message formatting may differ from other platforms
|
|
- Rich media support depends on Kook API capabilities
|
|
|
|
## See also
|
|
- [Channels overview](/channels/)
|
|
- [Configuration reference](/gateway/configuration)
|
|
- [Security guidelines](/security/)
|