Setting Up Your First Channel

A channel in ClawDesk is a bidirectional bridge between an external messaging platform and an AI agent. Messages flow in from the platform, get routed to the configured agent and provider, and responses flow back out.

ClawDesk supports 12 channel types: Telegram, Discord, Slack, WhatsApp, Signal, iMessage, WebChat, Matrix, LINE, Google Chat, Microsoft Teams, and Nostr. This guide walks through the three most common setups.

---

Setting Up Telegram

1. Create a Bot with BotFather

Open Telegram and message @BotFather:

1. Send /newbot
2. Choose a display name (e.g., "My ClawDesk Bot")
3. Choose a username ending in bot (e.g., my_clawdesk_bot)
4. BotFather replies with your bot token

Done! Congratulations on your new bot.
Use this token to access the HTTP API:
7123456789:AAF-xxxxxxxxxxxxxxxxxxxxxxxxxxx

warning

Keep your bot token secret. Anyone with the token can control your bot. If compromised, regenerate it via /revokentoken in BotFather.

2. Configure the Channel

Add the Telegram channel to your clawdesk.toml:

clawdesk.toml

[channels.telegram]
type = "telegram"
enabled = true
token = "${TELEGRAM_BOT_TOKEN}"
agent = "default"
webhook_path = "/webhook/telegram"
allowed_users = []                    # Empty = allow all users
rate_limit = 30                       # Max messages per minute per user

Set the environment variable:

export TELEGRAM_BOT_TOKEN="7123456789:AAF-xxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Choose a Connection Mode

ClawDesk supports two modes for Telegram:

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

For local development, ClawDesk uses long polling — no public URL required:

[channels.telegram]
type = "telegram"
enabled = true
token = "${TELEGRAM_BOT_TOKEN}"
agent = "default"
mode = "polling"                      # Default for local dev
poll_interval_secs = 1

Start the gateway:

clawdesk-cli gateway

INFO  clawdesk_channels::telegram > Telegram bot connected via long polling
INFO  clawdesk_channels::telegram > Bot username: @my_clawdesk_bot

For production, use webhooks — Telegram pushes updates to your server:

[channels.telegram]
type = "telegram"
enabled = true
token = "${TELEGRAM_BOT_TOKEN}"
agent = "default"
mode = "webhook"
webhook_url = "https://your-domain.com/webhook/telegram"
webhook_path = "/webhook/telegram"

info

Webhooks require a publicly accessible HTTPS URL. Use a reverse proxy (nginx, Caddy) or a tunnel (ngrok, Cloudflare Tunnel) during development.

Set the webhook automatically on startup:

clawdesk-cli gateway

INFO  clawdesk_channels::telegram > Webhook set: https://your-domain.com/webhook/telegram
INFO  clawdesk_channels::telegram > Telegram bot connected via webhook

4. Test It

Open Telegram, find your bot by username, and send a message:

You: Hello!
Bot: Hello! I'm your ClawDesk AI assistant. How can I help you?

---

Setting Up Discord

1. Create a Bot Application

1. Go to the Discord Developer Portal
2. Click New Application → name it (e.g., "ClawDesk Bot")
3. Go to Bot → click Add Bot
4. Under Token, click Copy to get your bot token
5. Enable these Privileged Gateway Intents:
   • ✅ Message Content Intent
   • ✅ Server Members Intent (optional)

2. Invite the Bot to Your Server

Generate an invite URL with the required permissions:

1. Go to OAuth2 → URL Generator
2. Select scopes: bot, applications.commands
3. Select permissions:
   • Send Messages
   • Read Message History
   • Embed Links
   • Attach Files
   • Use Slash Commands
4. Copy the generated URL and open it in your browser
5. Select your server and authorize

3. Get Your Guild ID

1. In Discord, go to User Settings → Advanced → enable Developer Mode
2. Right-click your server name → Copy Server ID

4. Configure the Channel

clawdesk.toml

[channels.discord]
type = "discord"
enabled = true
token = "${DISCORD_BOT_TOKEN}"
guild_id = "${DISCORD_GUILD_ID}"
agent = "default"
command_prefix = "!"                  # Prefix for commands (e.g., !ask)
respond_to_mentions = true            # Reply when @mentioned
respond_to_dms = true                 # Reply to direct messages
allowed_channels = []                 # Empty = all channels

Set the environment variables:

export DISCORD_BOT_TOKEN="MTIxNjM..."
export DISCORD_GUILD_ID="1234567890123456789"

5. Start and Test

clawdesk-cli gateway

INFO  clawdesk_channels::discord > Discord bot connected as ClawDesk Bot#1234
INFO  clawdesk_channels::discord > Listening in guild: My Server (1234567890123456789)
INFO  clawdesk_channels::discord > Registered 0 slash commands

In Discord, test with:

• Mention: @ClawDesk Bot hello!
• Prefix command: !ask What is Rust?
• Direct message: DM the bot directly

---

Setting Up Slack

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App → From a manifest
3. Select your workspace
4. Paste this manifest:

Slack App Manifest

display_information:
  name: ClawDesk Bot
  description: AI Agent powered by ClawDesk
  background_color: "#1a1a2e"

features:
  bot_user:
    display_name: ClawDesk
    always_online: true
  app_home:
    messages_tab_enabled: true

oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - channels:read
      - chat:write
      - groups:history
      - groups:read
      - im:history
      - im:read
      - im:write
      - mpim:history
      - users:read

settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true

2. Collect Credentials

After creating the app, gather three values:

Credential	Location
Bot Token (xoxb-...)	OAuth & Permissions → Install to Workspace → Bot User OAuth Token
App Token (xapp-...)	Basic Information → App-Level Tokens → Generate Token (scope: connections:write)
Signing Secret	Basic Information → App Credentials → Signing Secret

3. Configure the Channel

clawdesk.toml

[channels.slack]
type = "slack"
enabled = true
bot_token = "${SLACK_BOT_TOKEN}"
app_token = "${SLACK_APP_TOKEN}"
signing_secret = "${SLACK_SIGNING_SECRET}"
agent = "default"
respond_to_mentions = true            # Reply when @mentioned
respond_to_dms = true                 # Reply to DMs
thread_replies = true                 # Reply in threads

Set the environment variables:

export SLACK_BOT_TOKEN="xoxb-1234567890-..."
export SLACK_APP_TOKEN="xapp-1-A0..."
export SLACK_SIGNING_SECRET="abc123..."

info

ClawDesk uses Socket Mode for Slack by default, which doesn't require a public URL. This works for both development and production.

4. Start and Test

clawdesk-cli gateway

INFO  clawdesk_channels::slack > Slack bot connected via Socket Mode
INFO  clawdesk_channels::slack > Bot user: @ClawDesk (U0123456789)
INFO  clawdesk_channels::slack > Workspace: My Workspace

In Slack, test with:

• Mention: @ClawDesk what's the weather like?
• Direct message: Open a DM with the bot

---

Testing Channel Connections

Use the CLI to verify channel status without starting the full gateway:

clawdesk-cli channels status

📡 Channel Status
──────────────────────────────────────────────
Channel      Type       Status    Agent
──────────────────────────────────────────────
telegram     Telegram   ✅ Online  default
discord      Discord    ✅ Online  default
slack        Slack      ✅ Online  default
webchat      WebChat    ✅ Online  default
whatsapp     WhatsApp   ⏸ Disabled —
──────────────────────────────────────────────
3 online, 1 enabled, 1 disabled

Test a specific channel:

clawdesk-cli channels test telegram

🧪 Testing Telegram channel...
   ✅ Token valid
   ✅ Bot info: @my_clawdesk_bot (ID: 7123456789)
   ✅ Webhook reachable (if configured)
   ✅ Agent "default" available
   Test passed!

---

Troubleshooting Common Issues

Telegram

Issue	Cause	Solution
401 Unauthorized	Invalid or revoked token	Regenerate token via BotFather /revokentoken
Bot doesn't respond	Bot not added to group, or privacy mode enabled	Add bot to group; disable privacy via BotFather /setprivacy
Webhook fails	URL not HTTPS or unreachable	Use a valid HTTPS URL; check firewall rules
Duplicate messages	Multiple instances running	Ensure only one gateway instance per bot token

Discord

Issue	Cause	Solution
Authentication failed	Invalid token	Regenerate token in Developer Portal
Bot online but silent	Missing Message Content Intent	Enable in Developer Portal → Bot → Privileged Intents
Missing Permissions	Bot lacks channel permissions	Re-invite with correct permissions or adjust channel overrides
Slash commands missing	Commands not registered	Run clawdesk-cli channels sync discord

Slack

Issue	Cause	Solution
invalid_auth	Wrong or expired bot token	Reinstall app to workspace to get a new token
missing_scope	Bot lacks required OAuth scopes	Add scopes in app settings and reinstall
Socket Mode fails	No app-level token or wrong scope	Generate token with connections:write scope
Bot doesn't respond	Not subscribed to events	Check Event Subscriptions in app settings

General

tip

Enable debug logging to diagnose connection issues:

CLAWDESK_LOG=debug clawdesk-cli gateway

This prints detailed request/response logs for all channel interactions.

danger

If a channel repeatedly fails to connect, ClawDesk implements exponential backoff (1s, 2s, 4s, ... up to 5 minutes). Check logs for Reconnecting in Xs messages. To force an immediate reconnect:

clawdesk-cli channels restart telegram

---

Multiple Channels, Multiple Agents

You can route different channels to different agents for specialized behavior:

clawdesk.toml

[agents.support]
name = "support"
provider = "anthropic"
system_prompt = "You are a customer support agent. Be polite and helpful."
temperature = 0.5

[agents.dev]
name = "dev"
provider = "anthropic"
model = "claude-sonnet-4-20250514"
system_prompt = "You are a developer assistant. Help with code and technical questions."
temperature = 0.3

# Customer-facing channels → support agent
[channels.telegram]
type = "telegram"
enabled = true
token = "${TELEGRAM_BOT_TOKEN}"
agent = "support"

[channels.webchat]
type = "webchat"
enabled = true
agent = "support"

# Internal team channel → dev agent
[channels.discord]
type = "discord"
enabled = true
token = "${DISCORD_BOT_TOKEN}"
guild_id = "${DISCORD_GUILD_ID}"
agent = "dev"

---

Next Steps

• Configuration → — Fine-tune channel settings, rate limits, and security.
• Agent Pipeline — Create specialized agents with custom system prompts and tools.
• Plugin System — Add web search, code execution, and more to your agents.
• Architecture Overview — Learn about cron jobs, scheduling, and more.