# 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](https://discord.com/developers/applications)
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`:

```bash
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)

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
# 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