162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# 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)
|