Chapter 8: Telegram & Signal Setup

Telegram and Signal are the most popular channels for privacy-conscious developers and teams. Telegram is the easiest OpenClaw channel to set up — zero business accounts, zero cloud setup required. Signal adds end-to-end encryption on top. This chapter covers complete setup for both.

---

Part 1: Telegram

Telegram is the recommended first channel for any developer getting started with OpenClaw. The Telegram Bot API is free, stable, well-documented, and works globally without any business approval process.

Prerequisites

• A Telegram account
• Your OpenClaw gateway running (local or remote)

That is all. No business account. No approval process. No phone number registration.

---

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Enter a display name: My OpenClaw Bot
   • Enter a username: myopenclaw_bot (must end in bot)
4. BotFather sends you a bot token: 7123456789:AAHxxxxxxxxxxxxxxxxxxxxxx

Save this token. You will put it in openclaw.json.

---

Step 2: Configure openclaw.json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}",
      "mode": "webhook",
      "webhookPath": "/webhooks/telegram",
      "allowGroups": false,
      "allowPrivate": true
    }
  }
}

Set your environment variable:

export TELEGRAM_BOT_TOKEN="7123456789:AAHxxxxxxxxxxxxxxxxxxxxxx"

---

Webhook vs. Long Polling

Webhook mode (recommended for production): Telegram sends messages to your gateway's HTTPS URL the moment they arrive. Requires a publicly accessible gateway.

Polling mode (for development behind NAT):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}",
      "mode": "polling",
      "pollInterval": 1000
    }
  }
}

In polling mode, the gateway checks Telegram for new messages every second. No public URL needed — works perfectly on a laptop behind a home router.

---

Step 3: Start and Find Your User ID

openclaw start

Send /start to your bot in Telegram. The gateway logs your Telegram user ID:

[telegram] Message from user 987654321 (@yourusername): /start
[telegram] User not in any workspace allowlist. Ignoring.

---

Step 4: Add Yourself to a Workspace

Add your numeric Telegram user ID to a workspace allowlist:

{
  "workspaces": [
    {
      "id": "personal",
      "channels": ["telegram"],
      "agent": "claude-sonnet",
      "allowlist": ["987654321"]
    }
  ]
}

Restart and send a message — you should get an AI response.

---

Telegram Groups

OpenClaw can operate inside Telegram groups (not just direct messages):

{
  "channels": {
    "telegram": {
      "allowGroups": true,
      "groupTrigger": "@myopenclaw_bot"
    }
  }
}

When allowGroups is true, the bot responds to messages in groups. Use groupTrigger so the bot only responds when explicitly mentioned, not for every group message.

In groups, workspace allowlisting works the same way — only authorized user IDs get responses.

---

Telegram Inline Buttons

OpenClaw agents can send interactive buttons in Telegram responses. Enable in your skill or system prompt:

{
  "channels": {
    "telegram": {
      "enableInlineKeyboard": true
    }
  }
}

The agent can then produce structured button responses for menu-driven interactions.

---

Telegram Quick Reference

Setting	Value
BotFather	@BotFather
Token format	1234567890:AAXXXXX...
Webhook URL	https://yourdomain.com/webhooks/telegram
User ID (numeric)	Found in gateway logs on first message
Group trigger prefix	@yourbotusername

---

Part 2: Signal

Signal provides end-to-end encrypted messaging via signal-cli — a Java-based command-line client for the Signal protocol. OpenClaw wraps signal-cli to receive and send Signal messages.

Prerequisites

• Java 17 or later installed (java -version)
• A dedicated phone number for your Signal bot (different from your personal Signal number)
• Your gateway machine (Linux or macOS recommended for signal-cli stability)

---

Step 1: Install signal-cli

Download the latest release:

# Linux / macOS
VERSION="0.13.5"
wget https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux.tar.gz
tar -xzf signal-cli-${VERSION}-Linux.tar.gz
sudo mv signal-cli-${VERSION}/bin/signal-cli /usr/local/bin/

Verify:

signal-cli --version
# signal-cli 0.13.5

---

Step 2: Register Your Phone Number with Signal

signal-cli -u +12125550100 register

Signal sends a verification SMS to +12125550100. Enter the code:

signal-cli -u +12125550100 verify 123456

Your Signal account is now registered. OpenClaw will use this number to send and receive messages.

---

Step 3: Start signal-cli in Daemon Mode

signal-cli can run as a JSON-RPC daemon that OpenClaw connects to:

signal-cli -u +12125550100 daemon --socket /tmp/signal-cli.sock &

Or via systemd for production:

[Unit]
Description=signal-cli daemon

[Service]
ExecStart=/usr/local/bin/signal-cli -u +12125550100 daemon --socket /tmp/signal-cli.sock
Restart=always

[Install]
WantedBy=multi-user.target

---

Step 4: Configure openclaw.json

{
  "channels": {
    "signal": {
      "enabled": true,
      "phoneNumber": "+12125550100",
      "socketPath": "/tmp/signal-cli.sock",
      "pollInterval": 2000
    }
  }
}

---

Step 5: Add Users to Allowlist

Signal allowlist uses international phone numbers:

{
  "workspaces": [
    {
      "id": "secure-team",
      "channels": ["signal"],
      "agent": "claude-opus",
      "allowlist": ["+923001234567", "+14155552671"]
    }
  ]
}

---

Step 6: Test the Connection

openclaw start
openclaw channel status signal

Send a Signal message to +12125550100 from an allowlisted number. The AI response should arrive within 3–5 seconds.

---

Signal Limitations

Limitation	Notes
Java dependency	Requires Java 17+ on the gateway machine
Linux/macOS only	signal-cli has limited Windows support
No group admin	Bot can be added to Signal groups but cannot manage them
Rate limits	Signal enforces rate limits on registered numbers — avoid very high volumes
One number per instance	Each gateway installation needs its own dedicated Signal number

---

Troubleshooting

Telegram

Problem	Solution
Bot not responding	Check token is correct; verify channel is enabled; check allowlist
Webhook not receiving	Confirm HTTPS; check firewall allows port 443; re-register webhook
Works locally but not in production	Switch from polling to webhook mode; set correct domain in config
Group messages not received	Set allowGroups: true and add the bot to the group

Signal

Problem	Solution
signal-cli not found	Check installation path; add to $PATH
Registration fails	Ensure phone number is not already registered on another device
Daemon socket not available	Start signal-cli daemon first before starting OpenClaw
Messages delayed	Reduce pollInterval; check signal-cli daemon is running
Java version error	Upgrade to Java 17: sudo apt install openjdk-17-jdk

---

Side-by-Side Comparison

Feature	Telegram	Signal
Setup difficulty	Very easy	Medium
Business account needed	No	No
End-to-end encrypted	Optional	Always
Works on cloud server	Yes	Yes
Works on Windows gateway	Yes	Limited
Group support	Yes	Yes
Inline buttons	Yes	No
File attachments	Yes	Yes

---

Next: Chapter 9 — Slack & Discord Setup — Connect OpenClaw to the two most popular team collaboration platforms.