From a0d904dc23167c51680340ddeedabf1950cf7747 Mon Sep 17 00:00:00 2001 From: Pejman Pour-Moezzi Date: Wed, 18 Feb 2026 08:39:09 -0700 Subject: [PATCH] docs(discord): replace quick setup and add recommended guild setup (#20088) Co-authored-by: Shadow --- CHANGELOG.md | 1 + docs/channels/discord.md | 201 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 187 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fa240adb59..fcc278847d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/channels/discord.md b/docs/channels/discord.md index 336157e047..774a0eba1a 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -23,16 +23,98 @@ Status: ready for DMs and guild channels via the official Discord gateway. ## Quick setup - - - 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) + + + 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. - + + 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) + + + + + Scroll back up on the **Bot** page and click **Reset Token**. + + + Despite the name, this generates your first token — nothing is being "reset." + + + Copy the token and save it somewhere. This is your **Bot Token** and you will need it shortly. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + 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. + + + + + + + + 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 `` and Server ID ``." + + + 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=... ``` - - - - Invite the bot to your server with message permissions. - -```bash -openclaw gateway -``` + + + Wait until the gateway is running, then DM your bot in Discord. It will respond with a pairing code. + + + + Send the pairing code to your agent on your existing channel: + + > "Approve this Discord pairing code: ``" + + ```bash openclaw pairing list discord openclaw pairing approve discord ``` + + + Pairing codes expire after 1 hour. + You should now be able to chat with your agent in Discord via DM. + @@ -78,6 +168,87 @@ openclaw pairing approve discord Token resolution is account-aware. Config token values win over env fallback. `DISCORD_BOT_TOKEN` is only used for the default account. +## 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. + + + + This enables your agent to respond in any channel on your server, not just DMs. + + + + > "Add my Discord Server ID `` to the guild allowlist" + + + +```json5 +{ + channels: { + discord: { + groupPolicy: "allowlist", + guilds: { + YOUR_SERVER_ID: { + requireMention: true, + users: ["YOUR_USER_ID"], + }, + }, + }, + }, +} +``` + + + + + + + + By default, your agent only responds in guild channels when @mentioned. For a private server, you probably want it to respond to every message. + + + + > "Allow my agent to respond on this server without having to be @mentioned" + + + Set `requireMention: false` in your guild config: + +```json5 +{ + channels: { + discord: { + guilds: { + YOUR_SERVER_ID: { + requireMention: false, + }, + }, + }, + }, +} +``` + + + + + + + + By default, long-term memory (MEMORY.md) only loads in DM sessions. Guild channels do not auto-load MEMORY.md. + + + + > "When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md." + + + 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. + + + + + + +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.