Use Telegram when you want the fastest DM-first setup for talking to your assistant from macOS or iPhone.
Cue and OpenClaw use separate Telegram config files. Cue reads ~/.cue/config.json or ~/.cue/agents/<agent>/agent.json. OpenClaw uses ~/.openclaw/.

​
Before You Start

  • You need a Telegram account and access to @BotFather.
  • Cue Telegram runtime currently runs in the background worker for the target agent.
  • For first-time setup, start with DMs. Group setup is possible, but DM validation is shorter and easier to debug.

​
Fastest Setup

Replace <agent> with the agent you actually run. If you already use a local dev agent such as main-localhost, use that same agent here. 
export TELEGRAM_BOT_TOKEN='<BOT_TOKEN>'

cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy open \
  --json

cue --agent <agent> client restart --json
cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json
What you want to see:
  • telegram status shows enabled: true
  • channel status shows Telegram running: true

​
Step 1: Create the Bot

In Telegram:
  1. Open @BotFather.
  2. Run /newbot.
  3. Pick a display name and username.
  4. Copy the bot token.
Treat the token like a password. Do not commit it or paste it into public docs.

​
Step 2: Configure Cue

The command above is the recommended setup path because it:
  • validates the bot token with Telegram
  • writes agent-scoped config
  • stores the env var name, not the raw token

​
Non-Interactive CLI

Fastest first test: 
cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy open \
  --json
Safer DM allowlist setup: 
cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy allowlist \
  --dm-user <YOUR_TELEGRAM_USER_ID> \
  --json
Useful follow-up commands: 
cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json
cue --agent <agent> client restart --json
cue --agent <agent> telegram disable --json

​
Equivalent agent.json

If you prefer to inspect or edit the config directly, Cue writes agent-scoped config into ~/.cue/agents/<agent>/agent.json. Open DM test setup: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "account": {
        "botTokenEnv": "TELEGRAM_BOT_TOKEN"
      },
      "dm": {
        "policy": "open"
      }
    }
  }
}
Safer allowlist setup: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "account": {
        "botTokenEnv": "TELEGRAM_BOT_TOKEN"
      },
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["<YOUR_TELEGRAM_USER_ID>"]
      }
    }
  }
}
Important: enabled: true alone is not enough. dm.policy and group.policy default to disabled unless you set them.

​
Step 3: Send the First DM

Telegram bots cannot message you first. You must open the bot chat yourself: 
https://t.me/<bot_username>
Then:
  1. Tap Start
  2. Send hello
If Telegram search does not find the bot, the direct t.me link is the reliable path.

​
Step 4: Validate the Runtime

Use these checks: 
cue --agent <agent> telegram status --validate --json
cue --agent <agent> channel status --provider telegram --json
Optional outbound test:
  1. Send one DM to the bot first.
  2. Read the chat id from Telegram:
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"
  1. Look for message.chat.id, then send a test message:
cue --agent <agent> channel send --provider telegram --to <CHAT_ID> --text "telegram outbound test" --json

​
Group Setup

Start with DMs first. When that works:
  1. Add the bot to a Telegram group
  2. Enable group policy
  3. Restart the worker
cue --agent <agent> telegram setup \
  --token-env TELEGRAM_BOT_TOKEN \
  --dm-policy allowlist \
  --dm-user <YOUR_TELEGRAM_USER_ID> \
  --group-policy open \
  --json

cue --agent <agent> client restart --json
By default, Cue requires group activation by:
  • mentioning the bot with @botusername, or
  • replying to one of the bot’s messages

​
Troubleshooting

  • channel status says the worker is unavailable: Run cue --agent <agent> client restart --json. If it still fails, check cue --agent <agent> auth --json. Backend-connected agents need valid auth before the channel runtime can start.
  • telegram status looks right but channel status is not running: The config is saved, but the background worker has not restarted with it yet.
  • channel status briefly shows runtime_not_initialized right after restart: Wait a moment and run cue --agent <agent> channel status --provider telegram --json again. The worker may still be starting the provider runtime.
  • Bot exists but you cannot message it: Open the direct https://t.me/<bot_username> link and tap Start.
  • Another tool already uses the same token: Telegram long polling and webhooks cannot both own the same bot token at the same time. Use one consumer only.
  • DMs work but groups do not: Check group.policy and make sure you mentioned the bot or replied to a bot message.