mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-19 18:39:20 -05:00
docs(discord): replace quick setup and add recommended guild setup (#20088)
Co-authored-by: Shadow <shadow@openclaw.ai>
This commit is contained in:
Pejman Pour-Moezzi
committed by
GitHub
GitHub
parent
6a19654c4a
commit
a0d904dc23
@@ -528,6 +528,7 @@ Docs: https://docs.openclaw.ai
|
||||
- Tools/web_search: support `freshness` for the Perplexity provider by mapping `pd`/`pw`/`pm`/`py` to Perplexity `search_recency_filter` values and including freshness in the Perplexity cache key. (#15343) Thanks @echoVic.
|
||||
- Clawdock: avoid Zsh readonly variable collisions in helper scripts. (#15501) Thanks @nkelner.
|
||||
- Memory: switch default local embedding model to the QAT `embeddinggemma-300m-qat-Q8_0` variant for better quality at the same footprint. (#15429) Thanks @azade-c.
|
||||
- Docs/Discord: expand quick setup and clarify guild workspace guidance. (#20088) Thanks @pejmanjohn, @thewilloftheshadow.
|
||||
- Docs/Mermaid: remove hardcoded Mermaid init theme blocks from four docs diagrams so dark mode inherits readable theme defaults. (#15157) Thanks @heytulsiprasad.
|
||||
- Security/Pairing: generate 256-bit base64url device and node pairing tokens and use byte-safe constant-time verification to avoid token-compare edge-case failures. (#16535) Thanks @FaizanKolega, @gumadeiras.
|
||||
|
||||
|
||||
@@ -23,16 +23,98 @@ Status: ready for DMs and guild channels via the official Discord gateway.
|
||||
|
||||
## Quick setup
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Discord bot and enable intents">
|
||||
Create an application in the Discord Developer Portal, add a bot, then enable:
|
||||
You will need to create a new application with a bot, add the bot to your server, and pair it to OpenClaw. We recommend adding your bot to your own private server. If you don't have one yet, [create one first](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (choose **Create My Own > For me and my friends**).
|
||||
|
||||
- **Message Content Intent**
|
||||
- **Server Members Intent** (required for role allowlists and role-based routing; recommended for name-to-ID allowlist matching)
|
||||
<Steps>
|
||||
<Step title="Create a Discord application and bot">
|
||||
Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**. Name it something like "OpenClaw".
|
||||
|
||||
Click **Bot** on the sidebar. Set the **Username** to whatever you call your OpenClaw agent.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure token">
|
||||
<Step title="Enable privileged intents">
|
||||
Still on the **Bot** page, scroll down to **Privileged Gateway Intents** and enable:
|
||||
|
||||
- **Message Content Intent** (required)
|
||||
- **Server Members Intent** (recommended; required for role allowlists and name-to-ID matching)
|
||||
- **Presence Intent** (optional; only needed for presence updates)
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Copy your bot token">
|
||||
Scroll back up on the **Bot** page and click **Reset Token**.
|
||||
|
||||
<Note>
|
||||
Despite the name, this generates your first token — nothing is being "reset."
|
||||
</Note>
|
||||
|
||||
Copy the token and save it somewhere. This is your **Bot Token** and you will need it shortly.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Generate an invite URL and add the bot to your server">
|
||||
Click **OAuth2** on the sidebar. You'll generate an invite URL with the right permissions to add the bot to your server.
|
||||
|
||||
Scroll down to **OAuth2 URL Generator** and enable:
|
||||
|
||||
- `bot`
|
||||
- `applications.commands`
|
||||
|
||||
A **Bot Permissions** section will appear below. Enable:
|
||||
|
||||
- View Channels
|
||||
- Send Messages
|
||||
- Read Message History
|
||||
- Embed Links
|
||||
- Attach Files
|
||||
- Add Reactions (optional)
|
||||
|
||||
Copy the generated URL at the bottom, paste it into your browser, select your server, and click **Continue** to connect. You should now see your bot in the Discord server.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Enable Developer Mode and collect your IDs">
|
||||
Back in the Discord app, you need to enable Developer Mode so you can copy internal IDs.
|
||||
|
||||
1. Click **User Settings** (gear icon next to your avatar) → **Advanced** → toggle on **Developer Mode**
|
||||
2. Right-click your **server icon** in the sidebar → **Copy Server ID**
|
||||
3. Right-click your **own avatar** → **Copy User ID**
|
||||
|
||||
Save your **Server ID** and **User ID** alongside your Bot Token — you'll send all three to OpenClaw in the next step.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Allow DMs from server members">
|
||||
For pairing to work, Discord needs to allow your bot to DM you. Right-click your **server icon** → **Privacy Settings** → toggle on **Direct Messages**.
|
||||
|
||||
This lets server members (including bots) send you DMs. Keep this enabled if you want to use Discord DMs with OpenClaw. If you only plan to use guild channels, you can disable DMs after pairing.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Step 0: Set your bot token securely (do not send it in chat)">
|
||||
Your Discord bot token is a secret (like a password). Set it on the machine running OpenClaw before messaging your agent.
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
|
||||
openclaw config set channels.discord.enabled true --json
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
If OpenClaw is already running as a background service, use `openclaw gateway restart` instead.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw and pair">
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ask your agent">
|
||||
Chat with your OpenClaw agent on any existing channel (e.g. Telegram) and tell it. If Discord is your first channel, use the CLI / config tab instead.
|
||||
|
||||
> "I already set my Discord bot token in config. Please finish Discord setup with User ID `<user_id>` and Server ID `<server_id>`."
|
||||
</Tab>
|
||||
<Tab title="CLI / config">
|
||||
If you prefer file-based config, set:
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -45,32 +127,40 @@ Status: ready for DMs and guild channels via the official Discord gateway.
|
||||
}
|
||||
```
|
||||
|
||||
Env fallback for the default account:
|
||||
Env fallback for the default account:
|
||||
|
||||
```bash
|
||||
DISCORD_BOT_TOKEN=...
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Invite the bot and start gateway">
|
||||
Invite the bot to your server with message permissions.
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Approve first DM pairing">
|
||||
Wait until the gateway is running, then DM your bot in Discord. It will respond with a pairing code.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ask your agent">
|
||||
Send the pairing code to your agent on your existing channel:
|
||||
|
||||
> "Approve this Discord pairing code: `<CODE>`"
|
||||
</Tab>
|
||||
<Tab title="CLI">
|
||||
|
||||
```bash
|
||||
openclaw pairing list discord
|
||||
openclaw pairing approve discord <CODE>
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Pairing codes expire after 1 hour.
|
||||
|
||||
You should now be able to chat with your agent in Discord via DM.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@@ -78,6 +168,87 @@ openclaw pairing approve discord <CODE>
|
||||
Token resolution is account-aware. Config token values win over env fallback. `DISCORD_BOT_TOKEN` is only used for the default account.
|
||||
</Note>
|
||||
|
||||
## Recommended: Set up a guild workspace
|
||||
|
||||
Once DMs are working, you can set up your Discord server as a full workspace where each channel gets its own agent session with its own context. This is recommended for private servers where it's just you and your bot.
|
||||
|
||||
<Steps>
|
||||
<Step title="Add your server to the guild allowlist">
|
||||
This enables your agent to respond in any channel on your server, not just DMs.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ask your agent">
|
||||
> "Add my Discord Server ID `<server_id>` to the guild allowlist"
|
||||
</Tab>
|
||||
<Tab title="Config">
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
groupPolicy: "allowlist",
|
||||
guilds: {
|
||||
YOUR_SERVER_ID: {
|
||||
requireMention: true,
|
||||
users: ["YOUR_USER_ID"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Allow responses without @mention">
|
||||
By default, your agent only responds in guild channels when @mentioned. For a private server, you probably want it to respond to every message.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ask your agent">
|
||||
> "Allow my agent to respond on this server without having to be @mentioned"
|
||||
</Tab>
|
||||
<Tab title="Config">
|
||||
Set `requireMention: false` in your guild config:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
guilds: {
|
||||
YOUR_SERVER_ID: {
|
||||
requireMention: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Plan for memory in guild channels">
|
||||
By default, long-term memory (MEMORY.md) only loads in DM sessions. Guild channels do not auto-load MEMORY.md.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Ask your agent">
|
||||
> "When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md."
|
||||
</Tab>
|
||||
<Tab title="Manual">
|
||||
If you need shared context in every channel, put the stable instructions in `AGENTS.md` or `USER.md` (they are injected for every session). Keep long-term notes in `MEMORY.md` and access them on demand with memory tools.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Now create some channels on your Discord server and start chatting. Your agent can see the channel name, and each channel gets its own isolated session — so you can set up `#coding`, `#home`, `#research`, or whatever fits your workflow.
|
||||
|
||||
## Runtime model
|
||||
|
||||
- Gateway owns the Discord connection.
|
||||
|
||||
Reference in New Issue
Block a user