> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avibe.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> 把 Telegram chat 和 group 用作本地 AI agent 的移动协作空间。

# Telegram

Telegram 是一种轻量方式，可以从手机、群组或论坛话题给本地 AI agent 委托工作。

## 你会得到什么

* 从私信、群组或论坛向本地 AI agent 发任务。
* 从任意地方控制，同时保持本地运行。

## 创建 bot

1. 在 Telegram 里打开 [@BotFather](https://t.me/BotFather)，发 `/newbot`，起一个显示名，再起一个以 `bot` 结尾的用户名。复制 token。
2. 在 Avibe 向导里选择 **Telegram**，粘贴 token，**Validate**。（如果你所在地区封锁 Telegram，在这一步验证前先填代理 URL，见下文。）
3. 回到 **@BotFather**，设好决定 bot 在群里行为的几个开关：
   * **`/setprivacy` → Disable**——让 bot 能看到群里的普通消息，而不只是 mention。*这是头号坑。*
   * **`/setjoingroups` → Enable**——如果你要在群组或论坛里用。
   * **`/setcommands`**——发布 `start`、`settings`、`new`、`resume`。

## 先 bind，再发现 chat

Telegram 没有「列出所有 chat」的 API，所以 Avibe 从收到的消息里发现 chat。首次按这个顺序：

1. 完成设置并启动服务。
2. 从最后的总结页复制 bind 命令。
3. 私信 bot 发 `bind <code>` 成为第一个管理员，再发 `/start` 确认。
4. 要用群组或论坛，先把 bot 加进去、发一条消息，然后在群设置里 **刷新 Telegram chat 列表** 并启用它。论坛自动话题需要管理员 / 话题管理权限。

## 群组默认项

向导里有两个 Telegram 默认项：**群里要求显式指向 bot**（只回应命令、mention 或回复——适合热闹的群），以及 **论坛自动话题模式**（一条顶层消息会新开一个话题；需要管理员 / 话题权限）。

## 冒烟测试

```text theme={null}
Say hello and tell me which project directory you can see.
```

如果 bot 不回复，运行：

```bash theme={null}
vibe doctor
```

## 出站代理

如果你所在地区封锁 Telegram，设置 `proxy_url`——最方便是在向导验证前的 Proxy 字段里填，或在 Web UI 的 Telegram 配置块里填。支持 HTTP/HTTPS 和任意 `socks*://` 协议（`socks4`、`socks4a`、`socks5`、`socks5h`）。保存只会持久化变更；执行 `vibe restart --delay-seconds 60` 让它生效。注意：代理挂掉时 Avibe **不会** 自动回退到直连——修好或移除 `proxy_url` 才能恢复。

## 常见问题

| 症状              | 检查                                          |
| --------------- | ------------------------------------------- |
| 群消息被忽略          | `/setprivacy` 是否设成了 **Disable**             |
| 私信能用但群里不行       | `/setjoingroups` 是否为 **Enable**             |
| Chat 没列出来       | 先在那里发一条消息，再刷新 discovered chats              |
| Agent 缺失        | 所选后端 CLI 是否已安装并在 PATH 上可见                   |
| 机器无法访问 Telegram | Telegram 配置上的 `proxy_url`；查看日志中的防火墙或 TLS 错误 |