# Telegram + Agent Teams 整合指南

> 版本: v1.0
> 日期: 2026-03-23
> 狀態: 實驗功能

## 概述

透過 Claude Code Channels 功能，讓統帥可以從 Telegram 遠端控制 Agent Teams。

## 前置需求

| 項目 | 需求 |
|------|------|
| Claude Code | >= 2.1.32 (目前: 2.1.81 ✅) |
| Agent Teams | 已啟用 ✅ |
| Telegram Bot | 已建立 (Token 在 .env) |

## 設定步驟

### 步驟 1: 確認環境變數

```bash
# 確認已加入 ~/.zshrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# 驗證
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS  # 應顯示 1
```

### 步驟 2: 安裝 Telegram Plugin

```bash
# 啟動 Claude Code
claude

# 在 Claude 對話中執行
/plugin install telegram@claude-plugins-official
```

### 步驟 3: 配置 Bot Token

```bash
# Token 只能從 owner 受控密碼庫注入，不得寫入文件、commit 或對話。
# 注意：使用 Claude Code 專用 Bot，不要用 OpenClaw Bot。
# Claude Code Bot: @wooowooowooobot
/telegram:configure <TELEGRAM_BOT_TOKEN_FROM_OWNER_SECRET_STORE>
```

### 步驟 4: 以 Channels 模式啟動

```bash
# 重新啟動 Claude Code with Telegram Channel
claude --channels plugin:telegram@claude-plugins-official
```

### 步驟 5: 配對 Telegram

1. 在 Telegram 找到你的 Bot，發送任意訊息
2. Bot 會回傳配對碼 (例如: `ABC123`)
3. 在 Claude Code 中執行：
   ```
   /telegram:access pair ABC123
   ```
4. 鎖定白名單：
   ```
   /telegram:access policy allowlist
   ```

## 使用方式

### 從 Telegram 發指令

```
# 建立 Agent Team
Create an agent team with 3 teammates:
- Architect: docs/ + memory/
- Frontend: apps/web/
- Backend: apps/api/

# 查詢狀態
show task status

# 審查程式碼
review apps/web/ for i18n violations
```

### 遠端批准操作

當 Claude 需要批准時，Telegram 會收到請求：

```
[Claude Code] 需要批准：
執行 kubectl apply -n awoooi-prod

回覆 "yes XXXXX" 批准，或 "no" 拒絕
```

回覆：
```
yes XXXXX
```

## 安全機制

| 機制 | 說明 |
|------|------|
| Sender Allowlist | 只有配對的 Telegram 用戶能發指令 |
| Permission Relay | 危險操作需遠端批准 |
| Local Listener | 不暴露公開 URL |

## 整合 AWOOOI 工作流

```
┌─────────────────────────────────────────────────┐
│  統帥 Telegram                                   │
│  ┌─────────────────────────────────────────┐   │
│  │  「審查今天的 PR」                         │   │
│  └─────────────────────────────────────────┘   │
│                    ↓                            │
│  Claude Code + Agent Teams                      │
│  ├── @security 資安審查                         │
│  ├── @quality 代碼品質                          │
│  └── 彙整 → Telegram 通知                       │
│                    ↓                            │
│  ┌─────────────────────────────────────────┐   │
│  │  「審查完成：2 個 P1 問題，已自動修復」     │   │
│  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
```

## Hooks 整合 (任務完成通知)

在 `~/.claude/settings.json` 加入：

```json
{
  "hooks": {
    "TaskCompleted": [
      {
        "type": "command",
        "command": "curl -X POST https://api.telegram.org/bot$OPENCLAW_TG_BOT_TOKEN/sendMessage -d chat_id=$OPENCLAW_TG_CHAT_ID -d text='[Claude Code] 任務完成'"
      }
    ]
  }
}
```

## 故障排除

| 問題 | 解決 |
|------|------|
| Plugin 安裝失敗 | 確認 Claude Code >= 2.1.32 |
| 配對碼無效 | 重新發送訊息給 Bot |
| 指令無回應 | 確認 `--channels` 模式啟動 |

## 相關文檔

- [Claude Code Channels 官方文檔](https://code.claude.com/docs/en/channels.md)
- [Agent Teams 官方文檔](https://code.claude.com/docs/en/agent-teams.md)
- [Memory: reference_agent_teams.md](../../.claude/projects/-Users-ogt-awoooi/memory/reference_agent_teams.md)