How to Connect OpenClaw to Discord Without Guessing

How to Connect OpenClaw to Discord Without Guessing

Connect OpenClaw to Discord by creating a dedicated bot, granting only the message permissions it needs, storing the bot token outside chat and agent-readable files, enabling the required intent, applying a reviewed OpenClaw configuration, pairing one user, and proving a text-only round trip before enabling tools.

This guide covers OpenClaw 2026.7.1 and Discord's July 2026 developer interface. Both products change. Compare every screen and command with the current OpenClaw Discord guide and Discord developer documentation.

Complete the [[OpenClaw Security Checklist Before You Connect Anything|OpenClaw security preflight]] first. Do not use a personal work machine, production account, or existing community server for the first test.

What success looks like

The bot appears online in one private test server. One approved operator can send a direct message and receive a text response. An unknown user and an unapproved channel cannot trigger the agent. The OpenClaw gateway remains local and authenticated. The agent has no shell, browser, filesystem, scheduling, or external-account tools during the channel test.

flowchart TD
    A["Dedicated Discord application"] --> B["Least-privilege bot invitation"]
    B --> C["Protected token reference"]
    C --> D["Reviewed OpenClaw config"]
    D --> E["Local authenticated gateway"]
    E --> F["One approved pairing"]
    F --> G["Text-only request"]
    G --> H{"Reply delivered?"}
    H -->|No| I["Diagnose in fixed order"]
    H -->|Yes| J["Test denial paths"]
    J --> K["Consider one additional capability"]

Before you begin

Use a supported Node.js version, a pinned OpenClaw release, a dedicated Discord test server, and a dedicated Discord application. Record the OpenClaw version and Node version.

node --version
openclaw --version

OpenClaw's current getting-started guide lists the supported Node ranges. Do not continue past an engine-version error.

Confirm that the gateway uses loopback binding and authentication and that the first agent uses a messaging-only or stricter tool profile. Run openclaw security audit and resolve critical findings before adding the channel.

This article does not include a real token, user ID, server ID, or account. Never place those values in a screenshot, recording, prompt, public note, or repository.

1. Create a private test server

Create a new Discord server for the experiment. Limit membership to the operator. Add one private text channel for the initial test.

Do not use server privacy as the only access control. The bot still needs narrow Discord permissions and OpenClaw pairing or allowlists.

Choose a bot name that is easy to recognize and voice-type. Avoid a name that resembles another bot or person in the same server.

2. Create a dedicated Discord application

Open the Discord Developer Portal, create a new application, and create its bot user.

Use a dedicated application for the OpenClaw test. Do not reuse a production bot, normal user account, or application whose token is already deployed elsewhere.

Discord bot users are the supported automation identity. Discord's OAuth2 documentation says normal user-account automation, often called a self-bot, is not the supported bot path.

Keep the bot non-public when the portal allows the intended owner-only installation. Public availability does not make the bot respond to everyone by itself, but it creates an unnecessary distribution route.

3. Enable only the required intents

On the Bot page, enable Message Content Intent. The current OpenClaw guide requires it for the documented Discord flow.

Enable Server Members Intent only if the setup uses role allowlists, name-to-ID matching, or member-based access groups. Presence Intent is optional and unnecessary for a text-only test.

Restart the OpenClaw gateway after changing intents. Discord applies the application setting, while the bot connection must reconnect with the correct intent set.

Privileged intents increase the data Discord can deliver to the app. Enable them because the workflow needs them, not because a generic tutorial selected every switch.

4. Generate a least-privilege invitation

In Discord's OAuth2 URL Generator, select the bot and applications.commands scopes.

For a normal text channel, the current OpenClaw guide names View Channels, Send Messages, Read Message History, Embed Links, and Attach Files as the baseline. Add Reactions is optional. Add Send Messages in Threads only if the bot will use threads.

Do not select Administrator.

Open the generated URL, choose the private test server, review the requested permissions, and approve the installation. Confirm that the bot role has access only to the intended channel.

Discord's permissions guide explains that server and channel permissions determine what the bot user can do. OpenClaw policy adds a second layer; it does not reduce excessive Discord permissions after the fact.

5. Create and protect the bot token

On the Bot page, generate or reset the token. Copy it once into an approved secret destination. Treat it as exposed if it appears anywhere else.

Do not send the token to the OpenClaw agent. Do not paste it into Discord. Do not commit it in a configuration file.

For a local one-session test, set an environment variable from a trusted shell. On PowerShell:

$env:DISCORD_BOT_TOKEN = '<value-from-your-secret-store>'

On a POSIX shell:

export DISCORD_BOT_TOKEN='<value-from-your-secret-store>'

The placeholder is not a real token. Avoid shell history where that environment makes history capture likely. A persistent service should use an approved OpenClaw SecretRef or service secret mechanism rather than a human shell session.

OpenClaw's secrets documentation explains that plaintext in .env, configuration, and generated auth files may remain readable to an agent with filesystem access. Secret storage and tool restriction must work together.

6. Apply the Discord configuration through a dry run

Create a local JSON5 patch that enables Discord and references the environment variable without embedding its value.

{
  channels: {
    discord: {
      enabled: true,
      token: {
        source: "env",
        provider: "default",
        id: "DISCORD_BOT_TOKEN"
      }
    }
  }
}

Save the file outside a public repository. Review the effective change before applying it.

openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5

The --dry-run command and SecretRef form are documented in the pinned 2026.7.1 source. If the current release shows different syntax, stop and follow its official guide.

Run the secret check and security audit again.

openclaw secrets audit --check
openclaw security audit

7. Start the gateway and verify the channel process

Start the gateway through the installation mode already approved during the security preflight. Do not add a new process manager merely because the bot is offline.

Confirm that only one gateway instance is using the intended OpenClaw home and gateway credential. Confirm that only one Discord account resolves to the bot token.

Use current status and channel diagnostics before sending a message. The exact diagnostic commands can change; OpenClaw's Discord troubleshooting section is the authority for the release in use.

The bot appearing online means Discord accepted the connection. It does not prove that routing, pairing, the model, or delivery works.

8. Pair one direct-message sender

Allow Discord direct messages for the test server long enough to complete pairing. Send a direct message to the bot.

With the default pairing policy, OpenClaw returns a short-lived pairing code and does not process the original request. Approve the code from the trusted gateway host.

openclaw pairing list discord
openclaw pairing approve discord <CODE>

Pairing codes expire. Confirm the pending request belongs to the expected Discord identity before approving it.

OpenClaw's pairing guide says direct-message approval does not automatically authorize group commands or every guild location. That separation is intentional.

9. Add an explicit guild and channel boundary

Collect the operator's Discord user ID, server ID, and test-channel ID through Developer Mode. IDs are identifiers, not secret credentials, but they should not be exposed without a reason.

Configure the current OpenClaw guild and channel allowlist syntax for the pinned release. Keep mention gating enabled for shared rooms. If the official configuration schema has changed, use the current documented keys rather than copying an older example.

Test in the one approved channel. Then send a message in an unapproved channel and confirm that the agent does not run.

Do not use a wildcard guild or channel rule to avoid diagnosing an allowlist problem.

10. Prove a text-only round trip

Use a bounded prompt such as “Reply with exactly: channel test passed.” The model should not need web access, files, memory, or tools.

Record the time the message was sent, whether Discord displayed typing, the gateway and model status, the final response, and total time.

If the direct model smoke test passes but Discord does not reply, the model is not the first suspect. The failure lies in the channel, gateway, identity, routing, session, or delivery path.

Test restart behavior. Stop the gateway, confirm the bot goes offline, restart it through the intended supervisor, and repeat the bounded prompt.

Diagnose in order

When the bot does not reply, change one layer at a time.

1. Confirm the supported Node and OpenClaw versions. A runtime gate should be fixed before channel diagnosis.

2. Confirm one gateway process is running with the expected home, config, bind, and authentication.

3. Confirm the Discord token resolves for the intended account and has not been revoked. Rotate it if exposure is possible.

4. Confirm the bot appears online and the Discord application has Message Content Intent. Restart the gateway after an intent change.

5. Confirm the bot role can view the test channel, send messages, and read history. Do not grant Administrator as a diagnostic shortcut.

6. Confirm the sender pairing or allowlist, guild allowlist, channel allowlist, group policy, and mention requirement.

7. Confirm the selected model passes a direct bounded smoke test through the same gateway environment.

8. Confirm the agent has a usable session and that a previous run is not stalled. Keep tools disabled.

9. Review logs for authentication, routing, model timeout, and delivery errors. Do not paste logs into public chat because they may contain sensitive paths or content.

10. Keep timeouts finite. Adjust a provider-specific timeout only after measurement shows that model inference is the bottleneck.

This order would have separated several failures in episode 111B. Dalton's bot appeared online, the local model sometimes answered, a message timed out, and the dashboard later reported a gateway-token mismatch. Those were different layers.

Add tools only after the channel is boring

A reliable text path should feel uneventful. The same operator sends a message, the correct session receives it, the chosen model answers, and the reply returns within the operating threshold.

Only then should the operator add one bounded tool. Re-run the OpenClaw security and secret audits, verify the effective tool inventory, and test that an unapproved sender cannot reach it.

Do not connect personal email, cloud drives, browser profiles, production repositories, or payment systems as the next convenience step.

Verification boundary

The steps in this page were checked against OpenClaw 2026.7.1 source and current OpenClaw and Discord documentation. A clean editorial CLI attempt reached the OpenClaw runtime version gate and stopped before configuration because the test host's Node 24.14 was below the release requirement.

No live Discord application, token, gateway, or account was created for this article. The external account path remains a reader-executed procedure and must be verified against the current portals. The recording is evidence of one older setup experience, not proof that these current steps were completed end to end.

For the risk controls behind the procedure, use the [[OpenClaw Security Checklist Before You Connect Anything|OpenClaw Security Checklist]]. For an ordered explanation of the system, read [[What Is OpenClaw]].

Verification and disclosure

This guide was checked on July 27, 2026 against OpenClaw release 2026.7.1 at commit 2d2ddc4, its versioned Discord source documentation, current OpenClaw pairing, security, secret, and troubleshooting documentation, current Discord application, OAuth2, gateway-intent, and permission documentation, and both E111B transcripts.

Portal labels, configuration keys, permissions, defaults, and CLI commands can change. AI assisted with research organization and drafting; evidence boundaries and final editorial decisions remain Dalton Anderson's.