fix(telegram): expose proxy setup in WebUI (#5033)

2026-07-23 14:18:49 +08:00
parent 3647875aba
commit 01cdfc8100
17 changed files with 472 additions and 24 deletions
@@ -109,7 +109,24 @@ If `nanobot channels status` does not show the channel as enabled, the config sn
 <details>
 <summary><b>Telegram</b></summary>

-**Install the optional channel dependency**
+**Recommended WebUI setup**
+
+1. Create a bot with `@BotFather` and copy its token.
+2. Run `nanobot webui`, then open **Settings → Channels → Telegram**.
+3. Paste the token. If the gateway cannot reach Telegram directly, expand
+   **Advanced** and add an HTTP or SOCKS proxy.
+4. Save and enable Telegram, then send the bot a direct message.
+
+The configuration badge means nanobot found a saved token. The live connection
+check is separate, so a temporary Telegram or proxy outage does not make an
+existing configuration disappear. Saved tokens and proxy URLs remain masked.
+
+See the [step-by-step Telegram guide](./guides/telegram-ai-agent.md) for pairing
+and troubleshooting.
+
+**Manual setup**
+
+Install the optional channel dependency:

 ```bash
 nanobot plugins enable telegram
@@ -134,6 +151,21 @@ nanobot plugins enable telegram
 }
 ```

+If the gateway cannot reach Telegram directly, add a proxy to the same section:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "proxy": "http://127.0.0.1:7890"
+    }
+  }
+}
+```
+
+HTTP, HTTPS, SOCKS5, and SOCKS5H proxy URLs are accepted. Treat a proxy URL
+containing a username or password as a secret.
+
 > You can find your **User ID** in Telegram settings. It is shown as `@yourUserId`. Copy this value **without the `@` symbol** and paste it into the config file.
 >
 > `richMessages` defaults to `false`. Set it to `true` only if your Telegram client supports Bot API 10.1 rich messages and you want richer markdown rendering; keep it disabled for Telegram Web, which may show unsupported-message errors for rich messages.
@@ -1,8 +1,7 @@
-# Build a Telegram AI Agent with nanobot
+# Connect Telegram to nanobot

-This guide connects nanobot to Telegram so a paired Telegram user can message a
-self-hosted AI agent backed by your normal nanobot config, tools, memory, and
-workspace.
+This guide connects one Telegram bot to nanobot. Messages sent to that bot use
+your normal nanobot model, tools, memory, and workspace.

 ## What this guide builds

@@ -29,27 +28,55 @@ python -m pip install nanobot-ai
 nanobot onboard --wizard
 ```

-## Enable the Telegram channel
+## Connect Telegram in the WebUI

-Install the optional channel dependency:
+Start the WebUI:
+
+```bash
+nanobot webui
+```
+
+Open **Settings → Channels → Telegram**:
+
+1. If Telegram support is not installed, turn on its switch and confirm the
+   installation.
+2. Paste the token from BotFather.
+3. If the gateway cannot reach Telegram directly, expand **Advanced** and enter
+   an HTTP or SOCKS proxy such as `http://127.0.0.1:7890`.
+4. Save and enable Telegram.
+
+The configuration badge appears as soon as a bot token is saved. A connection
+check is separate: if Telegram is temporarily unreachable, the saved
+configuration remains valid and the bot can continue working in environments
+where the gateway has network access.
+
+Saved tokens and proxy URLs are masked. A proxy entered here is used both for
+the connection check and for normal Telegram traffic.
+
+## Manual setup
+
+For a headless installation, install Telegram support:

 ```bash
 nanobot plugins enable telegram
 ```

-Merge this snippet into `~/.nanobot/config.json`:
+Then merge this snippet into `~/.nanobot/config.json`:

 ```json
 {
  "channels": {
    "telegram": {
      "enabled": true,
-      "token": "YOUR_BOT_TOKEN"
+      "token": "YOUR_BOT_TOKEN",
+      "proxy": "http://127.0.0.1:7890"
    }
  }
 }
 ```

+Omit `proxy` when the gateway can reach Telegram directly.
+
 Omitting `allowFrom` enables pairing-only mode. The first DM from a new user
 gets a pairing code instead of agent access.

@@ -95,8 +122,13 @@ workspace as your local CLI check.

 - If the channel is not listed, run `nanobot plugins enable telegram` again in
  the same Python environment.
- If messages do not arrive, run `nanobot gateway --verbose` and check the bot
-  token.
+- If the WebUI shows a saved configuration but the live check cannot reach Telegram,
+  the token is still saved. Confirm the gateway can reach `api.telegram.org`,
+  or open **Advanced → Network proxy** and enter a proxy.
+- If Telegram rejects the token, copy the current token from BotFather or
+  regenerate it.
+- If messages do not arrive, run `nanobot gateway --verbose` and confirm the
+  Telegram channel is enabled.
 - If a first DM returns a pairing code, that is expected. Approve the code before
  testing normal agent replies.
 - If Telegram Web shows unsupported rich messages, keep `richMessages` disabled.
@@ -275,7 +275,9 @@ Then check:
 |---|---|
 | Bot never replies | Gateway is not running, the channel is not enabled, or the bot/app token is wrong. |
 | Unknown sender ignored | Configure `allowFrom`, pairing, or the channel-specific allow list. |
-| Telegram fails | Confirm the BotFather token and `allowFrom` user ID. |
+| Telegram shows a saved configuration but cannot complete a live check | The token is saved. Confirm the gateway can reach `api.telegram.org`, or open **Settings → Channels → Telegram → Advanced → Network proxy** and enter an HTTP or SOCKS proxy. |
+| Telegram rejects the token | Copy the current token from BotFather or regenerate it. |
+| Telegram receives no messages | Confirm the channel is enabled, the gateway is running, and the sender is paired or listed in `allowFrom`. |
 | Discord replies missing | Enable Message Content intent and invite the bot with the required permissions. |
 | WhatsApp or WeChat login expired | Re-run `nanobot channels login whatsapp` or `nanobot channels login weixin`. |
 | Chat app works but WebUI does not | The provider and gateway are likely fine; debug the WebSocket channel separately. |