> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/NemoClaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the Telegram bridge

> Forward messages between a Telegram bot and the OpenClaw agent running inside the sandbox.

# Set up the Telegram bridge

The Telegram bridge forwards messages between a Telegram bot and the OpenClaw agent running inside the NemoClaw sandbox. You send a message to your bot; the bridge runs it through the agent and returns the response. When the agent needs external network access, the OpenShell TUI prompts for approval.

The bridge is an auxiliary service managed by `nemoclaw start` and `nemoclaw stop`.

## Prerequisites

* A running NemoClaw sandbox, either local or remote.
* `NVIDIA_API_KEY` set in your environment.
* A Telegram bot token from [@BotFather](https://t.me/BotFather).

## Create a Telegram bot

<Steps>
  <Step title="Open BotFather">
    In Telegram, start a conversation with [@BotFather](https://t.me/BotFather).
  </Step>

  <Step title="Create a new bot">
    Send the `/newbot` command. BotFather will ask for a display name and a username, then issue a bot token that looks like:

    ```
    1234567890:AAEhBOweik8ad4b7FelRnTmFqtXRNPEOPio
    ```
  </Step>

  <Step title="Copy the bot token">
    Save the token. You will need it in the next step.
  </Step>
</Steps>

## Configure and start the bridge

<Steps>
  <Step title="Set the environment variables">
    Export the bot token and your NVIDIA API key:

    ```bash theme={null}
    export TELEGRAM_BOT_TOKEN=<your-bot-token>
    export NVIDIA_API_KEY=nvapi-...
    ```

    The bridge script requires both variables at startup. It exits immediately if either is missing.
  </Step>

  <Step title="Start auxiliary services">
    Start the Telegram bridge and the cloudflared tunnel:

    ```bash theme={null}
    nemoclaw start
    ```

    `nemoclaw start` launches the following services:

    * **Telegram bridge** — forwards Telegram messages to the agent and returns responses. Only started when `TELEGRAM_BOT_TOKEN` is set.
    * **cloudflared tunnel** — provides external access to the sandbox over a public URL.
  </Step>

  <Step title="Verify the bridge is running">
    Check the status of all auxiliary services:

    ```bash theme={null}
    nemoclaw status
    ```

    The output shows whether the Telegram bridge and tunnel are running. When the bridge starts successfully, it prints a startup banner:

    ```
      ┌─────────────────────────────────────────────────────┐
      │  NemoClaw Telegram Bridge                          │
      │                                                     │
      │  Bot:      @YourBotUsername                        │
      │  Sandbox:  nemoclaw                                │
      │  Model:    nvidia/nemotron-3-super-120b-a12b       │
      │                                                     │
      │  Messages are forwarded to the OpenClaw agent      │
      │  inside the sandbox. Run 'openshell term' in       │
      │  another terminal to monitor + approve egress.     │
      └─────────────────────────────────────────────────────┘
    ```
  </Step>
</Steps>

## Send a message

Open Telegram, find your bot, and send a message. The bridge forwards the text to the OpenClaw agent inside the sandbox and sends the agent's response back to you.

The following built-in commands are handled by the bridge before reaching the agent:

| Command  | Effect                                                      |
| -------- | ----------------------------------------------------------- |
| `/start` | Sends a welcome message describing the bot and the sandbox. |
| `/reset` | Clears the active session history for your chat.            |

## Restrict access to specific chat IDs

By default, the bridge accepts messages from any Telegram chat. To restrict access to specific users or groups, set the `ALLOWED_CHAT_IDS` environment variable to a comma-separated list of Telegram chat IDs:

```bash theme={null}
export ALLOWED_CHAT_IDS="123456789,987654321"
nemoclaw start
```

Messages from chats not in the list are silently ignored.

<Tip>
  To find a chat ID, send a message to your bot and inspect the `chat.id` field in the Telegram `getUpdates` response, or use a bot like [@userinfobot](https://t.me/userinfobot).
</Tip>

## Monitor bridge activity

While the bridge is running, open the OpenShell TUI in a separate terminal to monitor sandbox network activity and approve egress requests triggered by the agent:

```bash theme={null}
openshell term
```

For a remote sandbox:

```bash theme={null}
ssh my-gpu-box 'cd /home/ubuntu/nemoclaw && . .env && openshell term'
```

## Stop the services

Stop the Telegram bridge and all other auxiliary services:

```bash theme={null}
nemoclaw stop
```

## How the bridge works

When a message arrives, the bridge:

1. Checks the chat ID against `ALLOWED_CHAT_IDS` (if set).
2. Sends a typing indicator to Telegram.
3. Fetches the sandbox SSH config with `openshell sandbox ssh-config nemoclaw`.
4. SSHs into the sandbox and runs `openclaw agent --agent main --local -m '<message>' --session-id 'tg-<chatId>'`.
5. Strips setup log lines from the output and returns the agent response to Telegram.
6. Repeats the typing indicator every 4 seconds while the agent is running.

Long responses are split into 4,000-character chunks to stay within Telegram's message size limit. Markdown formatting is applied where possible, with a plain-text fallback.

<Info>
  Each Telegram chat uses its own `--session-id`, so conversation history is isolated per chat. Use `/reset` to clear a session.
</Info>

## Related topics

<CardGroup cols={2}>
  <Card title="Deploy to a remote GPU" icon="server" href="/deployment/deploy-to-remote-gpu">
    Run NemoClaw on a Brev GPU instance with the Telegram bridge enabled.
  </Card>

  <Card title="Approve network requests" icon="shield-check" href="/network-policy/approve-network-requests">
    Monitor and approve egress requests from the agent while it responds to Telegram messages.
  </Card>
</CardGroup>