# Cài Telegram Bot cho OpenClaw

### Mục tiêu

Cấu hình Telegram Bot để chat với OpenClaw qua DM.

Luồng hoạt động:

- Bạn
- → Telegram DM Bot
- → OpenClaw Gateway
- → Model
- → trả lời lại Telegram

### Tóm tắt nhanh

Các bước chính:

1. Tạo bot bằng @BotFather
2. Copy Telegram Bot Token
3. Thêm TELEGRAM\_BOT\_TOKEN vào Portainer
4. Cài plugin @openclaw/telegram nếu chưa có
5. Bật channels.telegram
6. Restart OpenClaw Gateway
7. DM bot để lấy pairing code
8. Approve pairing code
9. Chat với OpenClaw qua Telegram DM

### Tạo Telegram Bot

Mở Telegram, tìm: `<span class="editor-theme-code">@BotFather</span>` &gt; gửi `<span class="editor-theme-code">/newbot</span>`

Làm theo hướng dẫn:

- Đặt tên hiển thị cho bot
- Đặt username cho bot, bắt buộc kết thúc bằng bot

Sau khi tạo xong, BotFather sẽ trả về token dạng `<span class="editor-theme-code">1234567890:ABCDEF_xxxxxxxxxxxxxxxxx</span>`

Lưu token lại. Không gửi token cho người khác.

### Thêm token vào Portainer Stack

**Portainer** → Stacks → openclaw → Editor

Trong phần Environment variables, thêm:

- `<span class="editor-theme-code">TELEGRAM_BOT_TOKEN=token_telegram_bot_của_bạn</span>`

Trong compose, thêm vào service openclaw-gateway.environment:

- `<span class="editor-theme-code">TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}</span>`

**Update the stack.**

### Kiểm tra token trong container

Chạy:

```
docker exec -it openclaw-gateway sh -lc '
if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
  echo "OK: TELEGRAM_BOT_TOKEN is set"
else
  echo "ERROR: TELEGRAM_BOT_TOKEN is empty"
fi
'
```

Test token với Telegram API:

```
docker exec -it openclaw-gateway sh -lc '
node -e "
fetch(\"https://api.telegram.org/bot\" + process.env.TELEGRAM_BOT_TOKEN + \"/getMe\")
.then(async r => {
  console.log(\"status\", r.status);
  console.log(await r.text());
})
.catch(e => {
  console.error(e);
  process.exit(1);
});
"
'
```

Kết quả đúng:

```
status 200
{"ok":true,...}
```

Nếu `<span class="editor-theme-code">ok:false</span>` hoặc lỗi `<span class="editor-theme-code">401</span>`, token sai hoặc đã bị reset.

### Cài plugin Telegram

Kiểm tra trạng thái Telegram channel:

```
docker exec -it openclaw-gateway \
  node dist/index.js channels list --all | grep -i telegram
```

Nếu thấy `<span class="editor-theme-code">not installed</span>`, cài plugin:

```
docker exec -it openclaw-gateway \
  node dist/index.js plugins install @openclaw/telegram
```

Kiểm tra lại:

```
docker exec -it openclaw-gateway \
  node dist/index.js channels list --all | grep -i telegram
```

## Bật Telegram channel

Ghi config Telegram:

```
docker exec -it openclaw-gateway \
  node dist/index.js config set --batch-json '[
    {
      "path": "channels.telegram.enabled",
      "value": true
    },
    {
      "path": "channels.telegram.dmPolicy",
      "value": "pairing"
    },
    {
      "path": "channels.telegram.groupPolicy",
      "value": "allowlist"
    }
  ]'
```

Ý nghĩa:

```
// Người nhắn DM lần đầu cần pairing code.
dmPolicy = pairing 

// Không cho bot hoạt động tự do trong group nếu chưa cấu hình.
groupPolicy = allowlist
```

Restart OpenClaw

`<span class="editor-theme-code">docker restart openclaw-gateway</span>`

### Pair Telegram DM

Mở Telegram, nhắn cho bot `<span class="editor-theme-code">/start</span>` hoặc `<span class="editor-theme-code">hello</span>`

Bot sẽ trả về pairing code.

Trên Docker host, xem pairing request:

```
docker exec -it openclaw-gateway \
  node dist/index.js pairing list telegram
```

Approve code:

```
docker exec -it openclaw-gateway \
  node dist/index.js pairing approve telegram <CODE>
```

Ví dụ:

```
docker exec -it openclaw-gateway \
  node dist/index.js pairing approve telegram ABCD1234
```

Pairing code thường hết hạn sau khoảng 1 giờ.

### Test chat

Trong Telegram DM với bot, gửi tin nhắn bất kỳ.

Nếu bot trả lời được, Telegram đã hoạt động.

### Troubleshooting

#### Bot không trả lời

Kiểm tra channel:

```
docker exec -it openclaw-gateway \
  node dist/index.js channels list --all | grep -i telegram
```

Xem log channel:

```
docker exec -it openclaw-gateway \
  node dist/index.js channels logs --channel telegram --lines 200
```

#### Token rỗng

```
docker exec -it openclaw-gateway sh -lc '
if [ -n "$TELEGRAM_BOT_TOKEN" ]; then echo OK; else echo EMPTY; fi
'
```

Nếu ra `<span class="editor-theme-code">EMPTY</span>`, kiểm tra lại Portainer Environment variables và compose.

#### Token sai

Test lại Telegram API:

```
docker exec -it openclaw-gateway sh -lc '
node -e "
fetch(\"https://api.telegram.org/bot\" + process.env.TELEGRAM_BOT_TOKEN + \"/getMe\")
.then(async r => {
  console.log(\"status\", r.status);
  console.log(await r.text());
})
"
'
```

Nếu response có lỗi `<span class="editor-theme-code">401</span>`, tạo/reset token trong BotFather rồi cập nhật lại Portainer.

#### Bot trả pairing code nhưng approve xong vẫn không trả lời

Kiểm tra pairing:

```
docker exec -it openclaw-gateway \
  node dist/index.js pairing list telegram
```

Xem log:

```
docker logs --tail 160 openclaw-gateway | grep -iE "telegram|pairing|error"
```