openboatmobile-ai/docs/DISCORD_SETUP.md

Discord Setup

OpenBoatmobile can configure Discord integration during deployment.

Why Discord Integration?

Channel	Pros	Cons
Discord	Real-time, familiar interface, mobile push	Requires bot setup
Control UI	Full featured, direct	No push notifications
CLI	Scriptable	No mobile access

Recommended: Discord for mobile notifications and quick interactions.

Prerequisites

• A Discord account
• A Discord server where you can add bots
• Permission to create bots in that server

Step 1: Create Discord Application

1. Go to Discord Developer Portal
2. Click New Application
3. Name it (e.g., "OpenClaw Agent")
4. Click Create

Step 2: Create Bot User

1. In your application, go to Bot in the left sidebar
2. Click Add Bot
3. Confirm the popup
4. Copy the token immediately (click "Reset Token" if needed)
5. Save this token — you'll need it for .env

Bot Permissions

Under Privileged Gateway Intents, enable:

• Message Content Intent (required to read messages)
• Server Members Intent (optional, for user info)

Step 3: Invite Bot to Server

1. Go to OAuth2 → URL Generator in the left sidebar
2. Under Scopes, check:
   • bot
   • applications.commands
3. Under Bot Permissions, check:
   • Send Messages
   • Read Messages/View Channels
   • Read Message History
   • Mention Everyone (optional)
   • Use Slash Commands
4. Copy the generated URL at the bottom
5. Open the URL in your browser
6. Select your server and authorize

Step 4: Get Server and User IDs

Server ID

1. In Discord, go to User Settings (gear icon)
2. Go to Advanced → Enable Developer Mode
3. Right-click your server name
4. Click Copy Server ID

User ID

1. Right-click your username in Discord
2. Click Copy User ID

Step 5: Configure OpenBoatmobile

In .env:

TF_VAR_discord_bot_token=your-bot-token-here
TF_VAR_discord_server_id=123456789012345678
TF_VAR_discord_user_id='["123456789012345678", "another-user-id"]'

Step 6: Deploy (or Update)

# Initial deployment
terraform apply

# If already deployed, update:
terraform apply -var="discord_bot_token=..." -var="discord_server_id=..." -var="discord_user_id=[\"user1\", \"user2\"]"

Step 7: Pair the Gateway

After deployment, the gateway needs to be paired with Discord:

If Tailscale is Enabled

1. Visit https://<hostname>.<tailnet>.ts.net/
2. If device pairing is required:
   • You'll see a pairing code
   • On the server: openclaw pairing approve device <CODE>

If Using SSH Tunnel

# Create tunnel
ssh -L 18789:localhost:18789 openclaw@<server-ip>

# Open browser
# http://localhost:18789

Channel Configuration

By default, the bot is configured for:

• All channels in the server (using wildcard *)
• No mention required (bot responds to all messages)
• Only your user ID in allowlist

To customize, edit openclaw.json after deployment:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "groupPolicy": "allowlist",
      "guilds": {
        "SERVER_ID": {
          "requireMention": false,
          "users": ["YOUR_USER_ID"],
          "channels": {
            "*": { "allow": true }
          }
        }
      }
    }
  }
}

Testing

Test Bot is Working

1. In Discord, go to any channel in your server
2. Type a message
3. The bot should respond (if requireMention is false)
4. Or: Mention the bot with @OpenClaw Agent hello

Check Gateway Logs

On the server:

# Check gateway is running
systemctl status openclaw-gateway

# View logs
journalctl -u openclaw-gateway -f

Troubleshooting

Bot doesn't respond

1. Check bot token is correct
2. Verify bot has Message Content Intent enabled
3. Check server ID and user IDs are correct
4. Verify bot is in your server

"Unauthorized" in gateway logs

• Verify discord_user_id list contains your actual Discord IDs
• Check each user ID is in the server's member list

Gateway shows pairing code

If you see a pairing code:

1. SSH into the server
2. Run: openclaw pairing approve device <CODE>
3. Refresh the browser

Bot joins but doesn't respond

• Check requireMention setting
• Verify your user ID is in the allowlist
• Check gateway logs for errors

Security Notes

• The bot token provides full access to the bot — keep it secret
• Regenerate the token if compromised: Discord Dev Portal → Bot → Reset Token
• The user ID allowlist ensures only you can interact with the agent
• For team access, add multiple user IDs to the users array