Channels

Channels are communication interfaces that connect users to the GoClaw agent. Each channel adapts its input/output format but uses the same underlying gateway for processing.

Available Channels

Channel Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                              Channels                                  │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────┐ ┌──────┐      │
│  │Telegram│ │WhatsApp│ │  HTTP  │ │HTTP Voice│ │ TUI │ │ Cron │      │
│  │  Bot   │ │ Linked │ │ WebUI  │ │   WS     │ │Term │ │Sched │      │
│  └───┬────┘ └───┬────┘ └───┬────┘ └────┬─────┘ └──┬──┘ └──┬───┘      │
│      │          │          │           │          │       │           │
└──────┼──────────┼──────────┼───────────┼──────────┼───────┼───────────┘
       │          │          │           │          │       │
       └──────────┴──────────┴─────┬─────┴──────────┴───────┘
                                   │
                   ┌───────────────┴───────────────┐
                   │                               │
                   ▼                               ▼
          ┌────────────────┐             ┌─────────────────┐
          │    Gateway     │             │ VoiceLLM        │
          │  (Text Agent)  │             │ (Voice Agent)   │
          └────────────────┘             └─────────────────┘

Text channels (Telegram, WhatsApp, HTTP, TUI, Cron) use the main Gateway and LLM Registry.

Voice channel (HTTP Voice) uses a separate VoiceLLM Registry with per-session WebSocket connections to the configured real-time voice provider.

All channels:

1. Receive user input (messages, commands, scheduled triggers)
2. Authenticate the user
3. Call the gateway’s agent loop
4. Stream responses back to the user

Channel Commands

All text channels support the same set of slash commands:

See Channel Commands for detailed documentation.

ACP Interactive Flows

When the current GoClaw session is attached to ACP, text channels can surface ACP driver events and interactive requests.

• HTTP/Web UI renders interactive cards for questions and plan approval, plus status cards for todo, task, and generated-image events
• Telegram uses inline buttons for single-choice flows and native polls for single-question multi-select prompts
• TUI shows notice-style summaries for ACP interactive events, but responses must be handled elsewhere

ACP attachment follows the session key rather than a single frontend, so the same attached session can surface across different text channels that share that session.

See ACP Sessions for the workflow and limitations.

Channel Configuration

All channel configs live under channels in goclaw.json:

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC..."
    }
  }
}

The setup wizard can detect TELEGRAM_BOT_TOKEN from your environment.

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }
}

WhatsApp uses the linked device protocol (whatsmeow). Run goclaw whatsapp link first to scan a QR code with your phone. Session data persists in ~/.goclaw/whatsapp.db.

Note: This is your personal WhatsApp, not a business API. The agent responds as you.

HTTP/Web UI

{
  "channels": {
    "http": {
      "enabled": true,
      "listen": ":1337"
    }
  }
}

HTTP Voice

HTTP Voice is enabled via voicellm configuration (not channels):

{
  "voicellm": {
    "enabled": true,
    "default": "xai",
    "providers": {
      "xai": {
        "driver": "xai",
        "apiKey": "xai-...",
        "voice": "Charon"
      }
    }
  }
}

The /voice page route is available on the HTTP server. When VoiceLLM is enabled and initialized, the WebSocket route /voice/ws is registered for real-time audio.

See Configuration for full VoiceLLM options.

TUI

The TUI is launched via command line:

goclaw tui

Optional config:

{
  "channels": {
    "tui": {
      "showLogs": true
    }
  }
}

Cron

Cron jobs are defined separately (not under channels):

{
  "cron": {
    "enabled": true,
    "jobs": [
      {
        "name": "morning-briefing",
        "schedule": "0 8 * * *",
        "prompt": "Good morning! Give me a quick briefing.",
        "channel": "telegram"
      }
    ]
  }
}

Session Keys

Session keys are user-centric in the gateway:

• Owner users default to the primary session key (primary).
• Non-owner users default to user:<id>.
• Channels may pass an explicit session ID in some flows, which then becomes the session key for that request.

Message Tool

The message tool allows the agent to send messages to channels:

{
  "action": "send",
  "channel": "telegram",
  "chatId": "123456789",
  "text": "Hello!"
}

It also supports channel-specific features:

• Telegram: Reactions, replies, formatting
• WhatsApp: Reactions, replies, media
• HTTP: WebSocket push notifications

See Tools for message tool documentation.

Enabling Multiple Channels

You can enable multiple channels simultaneously:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "..."
    },
    "whatsapp": {
      "enabled": true
    },
    "http": {
      "enabled": true,
      "listen": ":1337"
    }
  }
}

Each channel operates independently with its own sessions, but they share:

• The same gateway instance
• The same tools and skills
• The same user registry
• The same Memory Graph

HTTP Voice Channel

HTTP Voice provides real-time voice conversations via WebSocket. Unlike text channels, it:

• Uses VoiceLLM Registry instead of the standard LLM Registry
• Maintains per-session WebSocket connections to the voice provider
• Supports interruption — user can speak while agent is talking
• Handles audio streaming in both directions

Architecture

Browser/Client                   GoClaw                    Voice Provider
    │                              │                              │
    │◄──── WebSocket ────────────►│                              │
    │      (audio chunks)          │◄──── WebSocket ────────────►│
    │                              │      (real-time voice API)   │
    │  mic audio ─────────────────►│ ─────────────────────────────►
    │◄──────────────────────────── │ ◄─────────────────────────────
    │  speaker audio               │        agent audio           │

Supported Providers

VoiceLLM vs LLM Registry

Voice uses a completely separate provider system:

See Also

• Telegram — Telegram bot setup
• WhatsApp — WhatsApp linked device
• TUI — Terminal interface
• Web UI — HTTP interface
• Voice — Real-time voice conversations
• Cron — Scheduled tasks
• Channel Commands — Slash commands
• ACP Sessions — ACP workflows across text channels
• Configuration — Full config reference