> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord

> Connect a Discord bot to your Suji instance.

Connecting Discord to your Suji instance lets your OpenClaw bot join a Discord server and respond to messages. Once connected, your bot will appear as a member of the server and can read and reply to messages in any channel it has access to.

## What You'll Need

Before you start, make sure you have:

* A Discord account
* A Discord server where you have **Administrator** or **Manage Server** permission (you need this to invite the bot)
* A running [OpenClaw install](/marketplace/openclaw) on a Suji VM

<Tip>
  If you don't have a Discord server yet, you can create one for free. Open Discord, click the **+** button in the left sidebar, and choose **Create My Own**.
</Tip>

## Create a Discord Application

Discord bots are managed through the **Discord Developer Portal**. You'll create an "application," add a bot to it, configure its permissions, and then invite it to your server.

<Steps>
  <Step title="Open the Developer Portal">
    Go to [discord.com/developers/applications](https://discord.com/developers/applications) and log in with your Discord account.

    If this is your first time here, you'll see an empty applications list. This is where all your bot applications will be managed.
  </Step>

  <Step title="Create a new application">
    Click the **New Application** button in the top-right corner. Enter a name for your application (for example, `Acme Support Bot`) and click **Create**.

    This name is what users will see as the bot's display name in your server. You can change it later.

    <Note>
      The application name and the bot's display name are different things. The application name is what you see in the Developer Portal. The bot's display name (which users see in Discord) can be customized separately under the **Bot** settings.
    </Note>
  </Step>

  <Step title="Set up the bot">
    In the left sidebar, click **Bot**. This page is where you configure your bot's settings.

    You'll see your bot's username and an option to change its avatar. The bot is created automatically when you create the application — you don't need to click "Add Bot" separately.
  </Step>

  <Step title="Copy the bot token">
    On the **Bot** page, find the **Token** section and click **Reset Token**. Discord will ask you to confirm — click **Yes, do it!**.

    Discord will display your bot token. It looks something like this:

    ```
    MTIzNDU2Nzg5MDEyMzQ1Njc4.GAbCdE.abcdefghijklmnopqrstuvwxyz1234567890
    ```

    **Copy this token immediately.** Discord only shows it once — if you navigate away without copying it, you'll need to reset it again.

    <Warning>
      **Keep your bot token secret.** Anyone with this token can control your bot. Never share it publicly, commit it to a code repository, or post it in a Discord channel. If your token is ever exposed, reset it immediately on this page.
    </Warning>
  </Step>

  <Step title="Enable Privileged Gateway Intents">
    Still on the **Bot** page, scroll down to the **Privileged Gateway Intents** section. You'll see three toggles:

    * **Presence Intent** — Lets the bot see when users are online/offline. **Not required** for Suji.
    * **Server Members Intent** — Lets the bot see the member list and receive events when members join or leave. **Optional** — only enable this if your OpenClaw agent needs to know about server members.
    * **Message Content Intent** — Lets the bot read the content of messages. **Required** for Suji.

    **You must enable Message Content Intent.** Without it, your bot will receive message events but the message content will be empty, so your OpenClaw agent won't be able to read or respond to what users say.

    Toggle on **Message Content Intent** (and optionally **Server Members Intent**), then click **Save Changes** at the bottom of the page.

    <Warning>
      If you skip this step, your bot will appear online in Discord but won't respond to any messages. This is the most common setup mistake.
    </Warning>
  </Step>

  <Step title="Generate an invite URL">
    In the left sidebar, click **OAuth2**. On this page, find the **OAuth2 URL Generator** section.

    First, under **Scopes**, check the box for:

    * **bot** — This tells Discord your application needs a bot user in the server

    After selecting the `bot` scope, a **Bot Permissions** panel will appear below. Select the following permissions:

    * **Read Messages/View Channels** — Lets the bot see channels and read messages
    * **Send Messages** — Lets the bot send messages in channels
    * **Read Message History** — Lets the bot read older messages in channels

    <Tip>
      You can add more permissions later if your use case requires them (such as **Embed Links**, **Attach Files**, or **Add Reactions**). Start with the basics and adjust as needed.
    </Tip>

    At the bottom of the page, Discord generates an invite URL. Click **Copy** to copy it.
  </Step>

  <Step title="Invite the bot to your server">
    Open the URL you just copied in your browser. Discord will show you an authorization screen:

    1. Select the server you want to add the bot to from the **Add to Server** dropdown. Only servers where you have **Administrator** or **Manage Server** permission will appear in this list.
    2. Review the permissions listed and click **Authorize**.
    3. Complete the CAPTCHA if prompted.

    After authorizing, the bot will appear in your server's member list. It will show as **offline** until you connect it to Suji in the next step.

    <Note>
      If you don't see your server in the dropdown, make sure you're logged into the correct Discord account and that you have admin permissions on the server.
    </Note>
  </Step>
</Steps>

## Connect to Suji

Now that your Discord bot is set up and invited to your server, paste its token into OpenClaw.

### During install

In the OpenClaw install form, tick **Discord** in the **Channels** multiselect and paste your bot token into the **Discord bot token** field. Click **Deploy** — OpenClaw connects on first boot and your bot appears **online** in your server.

### After install

Install detail page → **Edit Install** → tick **Discord** → paste the token → **Save**. Suji redeploys OpenClaw with the new env. Existing channels keep working through the redeploy.

## Verify

Once the bot shows as **online** in your Discord server:

1. Open any text channel the bot has access to.
2. Send a message — your OpenClaw agent should reply.

<Tip>
  Make sure OpenClaw has finished its [first-connection setup](/marketplace/openclaw#first-connection-two-extra-steps) before testing. An unconfigured agent may not respond as expected.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot is online but not responding to messages">
    This is almost always caused by the **Message Content Intent** not being enabled. Without it, the bot receives message events but can't read the actual text.

    To fix this:

    1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
    2. Select your application
    3. Click **Bot** in the left sidebar
    4. Scroll to **Privileged Gateway Intents**
    5. Make sure **Message Content Intent** is toggled **on**
    6. Click **Save Changes**

    After enabling the intent, restart the OpenClaw install (Install detail page → Restart) so the bot picks up the new gateway capabilities.

    If intents are already enabled, also check:

    * The VM and the OpenClaw install are both in a `running` state.
    * The bot has **Send Messages** and **Read Messages/View Channels** permissions in the channel.
    * The install's Logs tab doesn't show any errors when you send a message.
  </Accordion>

  <Accordion title="Bot appears offline in Discord">
    * **Token is wrong / revoked.** Reset it in the Developer Portal, then in Suji: install detail → **Edit Install** → paste the new token → **Save**.
    * **VM or install isn't running.** Both must be `running`.
    * **Logs tab.** Open the install's Logs and look for `[discord]` lines — they'll often say "invalid token" or "intents missing".
  </Accordion>

  <Accordion title="Permission errors or bot can't send messages">
    If the bot is online but gets permission errors or can't send messages in certain channels:

    * **Re-invite the bot** — Generate a new OAuth2 URL in the Developer Portal with the correct permissions (**Read Messages/View Channels**, **Send Messages**, **Read Message History**) and use it to update the bot's permissions. You don't need to kick the bot first — re-authorizing will update its permissions.
    * **Check server-level role permissions** — In your Discord server, go to **Server Settings > Roles**. Find the bot's role (usually named after the bot) and make sure it has the necessary permissions enabled.
    * **Check channel-level overrides** — Individual channels can override role permissions. Right-click the channel, go to **Edit Channel > Permissions**, and make sure the bot's role isn't denied access.
  </Accordion>

  <Accordion title="Bot can't see messages in specific channels">
    Discord lets server admins restrict which channels a bot can access. If your bot responds in some channels but not others:

    1. Right-click the channel where the bot isn't working
    2. Click **Edit Channel**
    3. Go to the **Permissions** tab
    4. Check if the bot's role has been explicitly denied **View Channel** or **Read Messages** permission
    5. Either remove the deny override or explicitly grant the bot access

    Also check if the channel is in a **category** with restricted permissions. Category-level permission overrides apply to all channels within that category unless the channel has its own overrides.

    <Tip>
      An easy way to test is to check if the bot appears in the member list on the right side of the channel. If you don't see the bot listed there, it doesn't have access to that channel.
    </Tip>
  </Accordion>

  <Accordion title="Rate limiting — bot responses are slow or failing">
    Discord enforces rate limits on bots to prevent abuse. If your bot is sending too many messages too quickly, Discord will temporarily throttle it, causing delayed or failed responses.

    Signs of rate limiting:

    * Responses are significantly slower than usual
    * Some messages get replies while others don't
    * The instance logs show HTTP 429 errors

    To reduce rate limiting:

    * **Avoid high-traffic channels** — If the bot is in a channel with many active users, every message triggers the bot, which can hit rate limits quickly.
    * **Limit the bot's channel access** — Restrict the bot to only the channels where you actually need it by adjusting channel permissions.
    * **Check your OpenClaw agent configuration** — If the agent sends multiple messages per response, each one counts against the rate limit. Simplify responses where possible.

    Discord's rate limits reset automatically after a short cooldown period (usually a few seconds to a minute). No manual action is needed — the bot will resume normal operation once the limit resets.
  </Accordion>
</AccordionGroup>