Guides

>

, ,

Setting Up Discord for OpenClaw Bots

Use this path first

This guide documents the single-server Discord setup that produced the cleanest result for OpenClaw: one private Discord server, one bot application, one OpenClaw host, 1Password secret references for the bot token, and LiteLLM in front of the model layer. It keeps secrets out of local config files, keeps the bot out of public community servers, and starts with one stable default agent for the whole server.

If you are starting fresh, use this path before adding more bots, more servers, or per-channel routing.

What you need

  • One Discord user account. You do not need a second human Discord account.
  • One private Discord server dedicated to this OpenClaw bot.
  • One OpenClaw host with a working gateway.
  • One 1Password vault that supports secret references.
  • One LiteLLM endpoint that fronts the model you want Discord to use.

Step 1: Create a private Discord server

  1. Open Discord and click the + button in the server list.
  2. Select Create My Own.
  3. Choose For me and my friends.
  4. Name the server something private and specific to the bot.
  5. Do not invite anyone else yet.

Normal text channels inside the private server are fine. They do not need to be private channels if the server itself only contains you and the bot.

Step 2: Create the Discord bot application

  1. Open the Discord Developer Portal at https://discord.com/developers/applications.
  2. Click New Application and give it a clear name.
  3. Open the new application and go to Bot.
  4. Click Add Bot.
  5. Enable these privileged intents:
    • Message Content Intent
    • Server Members Intent
  6. Reset the token and copy it somewhere secure for the next step.

Step 3: Invite the bot to your private server

  1. In the same application, go to OAuth2 then URL Generator.
  2. Enable these scopes:
    • bot
    • applications.commands
  3. Enable these bot permissions:
    • View Channels
    • Send Messages
    • Read Message History
    • Embed Links
    • Attach Files
    • Add Reactions
  4. Open the generated URL and authorize the bot into the private server you created in Step 1.

Start with the minimum permissions above. Leave channel-management or configuration-writing permissions off until normal chat behavior is stable.

Step 4: Turn on Discord Developer Mode and collect the IDs you need

  1. In Discord, open Settings then Advanced.
  2. Turn on Developer Mode.
  3. Right-click your Discord user and copy your user ID.
  4. Right-click the private server icon and copy the server ID.
  5. If you want to pin a specific channel to a specific agent later, right-click that channel and copy its channel ID too.

Step 5: Store the bot token in 1Password

The cleanest pattern is a dedicated 1Password item just for the bot token.

  1. Create a new item in your 1Password vault, for example openclaw-discord-bot-token.
  2. Put the Discord bot token in the password field.
  3. If you want, store your Discord user ID and server ID in named text fields on a separate item. They are not sensitive, but keeping them together makes later edits easier.

Do not paste the token directly into .env files or your OpenClaw config.

Step 6: Add the secret references to the OpenClaw runtime environment

Add the Discord bot token and LiteLLM key as 1Password secret references in the runtime environment file your gateway loads at startup.

DISCORD_BOT_TOKEN=op://HomeLab/openclaw-discord-bot-token/password
LITELLM_API_KEY=op://HomeLab/litellm-openclaw/password

If your environment already has OPENCLAW_GATEWAY_TOKEN set, leave that in place. This guide only adds the Discord-specific lines.

Step 7: Configure OpenClaw for one Discord server and one default agent

The key behavior that worked best was simple routing: one allowed Discord server, one allowed Discord user, pairing enabled for DMs, configuration writes disabled, and one stable default agent for the whole server.

{
  "auth": {
    "defaultProfile": "litellm:default"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "litellm/local-model"
      }
    },
    "hasmaster": {
      "model": {
        "primary": "litellm/local-model"
      }
    }
  },
  "channels": {
    "discord": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "guilds": ["YOUR_SERVER_ID"],
      "allowUsers": ["YOUR_DISCORD_USER_ID"],
      "configWrites": false
    }
  },
  "bindings": {
    "defaults": {
      "discord": {
        "agent": "hasmaster"
      }
    }
  }
}

Keep the Discord-facing default agent on one stable chat model through LiteLLM. For a private or low-cost setup, use a local alias such as litellm/local-model. If you want a cloud-backed business lane later, swap only the model alias, not the Discord layout.

Do not start by pointing the default Discord agent at an experimental coder model or a mixed provider path. Discord chat behaves best when the default route goes to one stable chat model.

Step 8: Restart the gateway and confirm Discord is connected

Restart the OpenClaw gateway using the wrapper or startup command your host uses. On the reference setup, the commands looked like this:

/home/parsons/1password-runtime/openclaw-op.sh gateway restart
/home/parsons/1password-runtime/openclaw-op.sh gateway health

The health output should show the gateway as healthy and Discord as connected.

Step 9: Pair the bot by DM

  1. Open the private server.
  2. Find the bot in the member list.
  3. Right-click the bot and choose Message.
  4. Send a short message such as hi.
  5. The bot should return a pairing code and your Discord user ID.
  6. Approve the code from the host shell using the command the bot shows you, for example:
openclaw pairing approve discord YOUR_CODE

Bots are not normal friend accounts. You do not add them as friends. You DM them from a server where the bot is already present.

Step 10: Validate the result

  1. Run gateway health again and confirm Discord is still reported as connected.
  2. Send the bot a DM and confirm it replies.
  3. Send a short message in the private server and confirm the default agent replies there too.
  4. Only after that should you add extra channels, channel-to-agent bindings, or channel-management permissions.

What finally mattered

  • Use a dedicated private Discord server instead of adding the bot to an existing community server.
  • Keep the bot token in 1Password and reference it from the runtime environment file.
  • Put LiteLLM in front of the model layer and give the Discord-facing default agent one stable chat model.
  • Start with one default agent for the whole server. Add per-channel routing later.
  • Leave configWrites off at first.
  • Use normal text channels inside the private server unless other humans will join later.

This is the shortest path to a clean first result: one server, one bot, one default agent, one secret reference, one stable model route.

Categories:

, ,

|

Domains:

|

Use Cases:

|

Tags: