8000 occ/TELEGRAM-SETUP.md at v3.2.0 · damoahdominic/occ · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
159 lines (115 loc) · 4.66 KB

TELEGRAM-SETUP.md

File metadata and controls

159 lines (115 loc) · 4.66 KB

Setting Up Telegram with OpenClaw

Step-by-step guide using the Gateway UI


Before You Start

You need:

  • OCcode installed and open
  • OpenClaw installed (via the Home panel Install button)
  • A Telegram account on your phone

Step 1 — Create Your Telegram Bot

You must create a bot via Telegram's official BotFather before anything else.

  1. Open Telegram on your phone or desktop
  2. Search for @BotFather and open the chat
  3. Send the command:
    /newbot
    
  4. BotFather will ask for a name — this is the display name (e.g. My OpenClaw Bot)
  5. BotFather will then ask for a username — must end in bot (e.g. myopenclawbot)
  6. BotFather will reply with your Bot Token — it looks like:
    8328341297:AAESucIDOoHTt3Wers28iqKERjjyRmAt6_k
    
    Copy this — you will need it in the next step.

Step 2 — Open the Gateway UI

  1. Open OCcode (the editor)
  2. The OpenClaw Home panel opens automatically on the right
  3. Make sure the status shows Gateway: Running
    • If not, click Start Gateway
    • Wait for the green status indicator
  4. Click the Configure OpenClaw button
  5. The Gateway Control UI opens inside the editor

Step 3 — Log In to the Gateway

The first time you open the Gateway UI you will be asked to authenticate.

  1. When prompted, enter the gateway token from your config:
    • Run this in Terminal to find it: < 5DF4 div class="highlight highlight-source-shell notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="cat ~/.openclaw/openclaw.json | grep token">
      cat ~/.openclaw/openclaw.json | grep token
  • It looks like: 70048f4f333c4ef75e7408144f6cdc1f1da5d60dd149ed35
  • Paste the token into the Gateway UI login screen
  • Click Connect
  • Tip: The token is saved in your browser's local storage so you only need to do this once per machine.


    Step 4 — Go to the Channels Tab

    Once logged in to the Gateway UI:

    1. Click Channels in the left navigation
    2. You will see cards for all supported messaging platforms:
      • Telegram, WhatsApp, Discord, Slack, Signal, iMessage, and more
    3. Find the Telegram card

    Step 5 — Enter Your Bot Token

    In the Telegram card:

    1. You will see a config form with a Bot Token field
    2. Paste the bot token you copied from BotFather in Step 1
    3. Click Save

    The Telegram card will update to show:

    • Configured: Yes
    • Running: Yes
    • Mode: polling or webhook

    Step 6 — Probe and Verify

    After saving:

    1. Click the Probe button in the Telegram card
    2. The card will show a probe result:
      • ✅ Probe ok — your bot token is valid and Telegram is reachable
      • ❌ Probe failed — check the bot token and try again
    3. If probe is ok, your bot's @username will appear in the card header

    Step 7 — Configure an Agent

    Now connect an AI agent to your Telegram bot:

    1. Click Agents in the left navigation
    2. Click New Agent (or use an existing one)
    3. Give your agent a name and select a model (e.g. OCC Legacy Model for free, or your API key model)
    4. Save the agent

    Step 8 — Set Up Routing (Bind Agent → Telegram)

    1. Click Bindings in the left navigation (under the Agents or Channels section)
    2. Click Add Binding
    3. Select:
      • Agent: the agent you created in Step 7
      • Channel: Telegram
    4. Set your DM Policy — how the bot responds to direct messages:
      • pairing — only responds to paired users (recommended for workshops)
      • allowlist — only responds to users on a specific list
      • open — responds to anyone
    5. Save the binding

    Step 9 — Test It

    1. Open Telegram on your phone
    2. Search for your bot by the username you gave it (e.g. @myopenclawbot)
    3. Send /start or any message
    4. Your OpenClaw agent should respond

    Troubleshooting

    Problem Fix
    Gateway not running Click "Start Gateway" on the OCcode home panel
    Probe failed Double-check the bot token — no extra spaces
    Bot not responding Check Bindings — agent must be bound to Telegram
    Token expired BotFather → /mybots → select bot → API Token → Revoke and re-issue
    Gateway UI won't load Restart gateway from home panel, wait 5s, click Configure again
    Can't log in to Gateway Run cat ~/.openclaw/openclaw.json and copy the token value

    Quick Reference

    What Where
    Create bot @BotFather on Telegram → /newbot
    Enter bot token Gateway UI → Channels → Telegram card → Bot Token field
    Test connection Gateway UI → Channels → Telegram → Probe button
    Connect AI Gateway UI → Bindings → Add Binding
    Find gateway token cat ~/.openclaw/openclaw.json | grep token
    Restart gateway OCcode Home panel → Restart Gateway button
    0