# Claude Code Telegram Bot 完整部署指南

> 基于现有 VPS (45.251.241.94) 的实际运行配置整理，含"正在输入"持续显示补丁和权限自动放行配置。

---

## 一、环境要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| OS | Debian 12 / Ubuntu 22+ | 其他 Linux 也可 |
| Bun | 1.3+ | Telegram 插件只支持 Bun |
| Node.js | 22+ | Claude Code 依赖 |
| tmux | 任意 | 后台保持运行 |
| python3 | 3.10+ | 报表分析用 |

---

## 二、一键部署脚本

把下面这段保存为 `deploy.sh`，在新 VPS 上 `bash deploy.sh` 即可：

```bash
#!/bin/bash
set -e

echo "===== 1. 安装系统依赖 ====="
apt update && apt install -y curl tmux python3 python3-pip git

echo "===== 2. 安装 Bun ====="
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
export PATH="$HOME/.bun/bin:$PATH"

echo "===== 3. 安装 Node.js (v22) ====="
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

echo "===== 4. 安装 Claude Code ====="
npm install -g @anthropic-ai/claude-code

echo "===== 5. 登录 Claude (需手动操作) ====="
echo ""
echo "!!! 请手动执行: claude"
echo "!!! 按提示在浏览器中完成 OAuth 登录"
echo "!!! 登录成功后按 Ctrl+C 退出，然后继续运行本脚本"
echo ""
read -p "登录完成后按 Enter 继续..."

echo "===== 6. 安装 Telegram 插件 ====="
# 启动 claude 并执行插件安装命令
claude -p "/plugin install telegram@claude-plugins-official" --no-input 2>/dev/null || true

echo "===== 7. 创建项目目录 ====="
mkdir -p /root/workspaces/report-bot/.claude

echo "===== 8. 写入项目文件 (后面会被覆盖为实际内容) ====="
echo "请手动执行后续配置步骤"

echo "===== 部署基础完成 ====="
```

---

## 三、逐步手动部署流程

### 第1步：安装系统依赖

```bash
apt update && apt install -y curl tmux python3 python3-pip git
```

### 第2步：安装 Bun

```bash
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
```

### 第3步：安装 Node.js

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs
```

### 第4步：安装 Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

### 第5步：登录 Claude

```bash
claude
```
按提示在浏览器中完成 OAuth 登录（Claude Max / Pro / Team 账号），登录成功后 `Ctrl+C` 退出。

### 第6步：安装 Telegram 插件

启动 claude 后执行：
```
/plugin install telegram@claude-plugins-official
/reload-plugins
```

### 第7步：创建 Telegram Bot

1. 在 Telegram 中找 `@BotFather`
2. 发送 `/newbot`
3. 输入 Bot 名称和用户名
4. 复制 Token（格式如 `123456789:AAHfiqksKZ8...`）

### 第8步：配置 Bot Token

在 claude 中执行：
```
/telegram:configure <你的Bot Token>
```

或者直接手动写入文件：
```bash
mkdir -p ~/.claude/channels/telegram
echo "TELEGRAM_BOT_TOKEN=<你的Bot Token>" > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env
```

### 第9步：创建项目目录和配置文件

```bash
mkdir -p /root/workspaces/report-bot/.claude
```

### 第10步：配对 Telegram 用户

```bash
claude --channels plugin:telegram@claude-plugins-official
```

启动后，在 Telegram 中给你的 Bot 发一条消息，它会返回一个 6 位配对码。在 Claude Code 中输入：
```
/telegram:access pair <6位配对码>
```

### 第11步：锁定访问权限

```
/telegram:access policy allowlist
```

然后 `Ctrl+C` 退出 Claude Code。

### 第12步：用 tmux 后台启动

```bash
tmux new -s tgbot
claude --channels plugin:telegram@claude-plugins-official
# 按 Ctrl+B 然后按 D 脱离 tmux（bot 继续后台运行）
```

---

## 四、需要写入的配置文件（直接复制）

### 文件 1：`~/.claude/settings.json`

```bash
cat > ~/.claude/settings.json << 'EOF'
{
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  },
  "enabledPlugins": {
    "telegram@claude-plugins-official": true
  }
}
EOF
```

### 文件 2：`~/.claude/settings.local.json`（全局权限放行）

```bash
cat > ~/.claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Glob(*)",
      "Grep(*)",
      "WebFetch(*)",
      "mcp__plugin_telegram_telegram__download_attachment",
      "mcp__plugin_telegram_telegram__reply",
      "mcp__plugin_telegram_telegram__react",
      "mcp__plugin_telegram_telegram__edit_message"
    ]
  }
}
EOF
```

### 文件 3：`/root/workspaces/report-bot/.claude/settings.local.json`（项目级权限）

```bash
mkdir -p /root/workspaces/report-bot/.claude
cat > /root/workspaces/report-bot/.claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(*)",
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Glob(*)",
      "Grep(*)",
      "WebFetch(*)",
      "mcp__plugin_telegram_telegram__reply",
      "mcp__plugin_telegram_telegram__react",
      "mcp__plugin_telegram_telegram__download_attachment",
      "mcp__plugin_telegram_telegram__edit_message"
    ]
  }
}
EOF
```

### 文件 4：`~/.claude/channels/telegram/access.json`（访问控制）

```bash
mkdir -p ~/.claude/channels/telegram
cat > ~/.claude/channels/telegram/access.json << 'EOF'
{
  "dmPolicy": "allowlist",
  "allowFrom": [
    "你的Telegram用户ID"
  ],
  "groups": {},
  "pending": {}
}
EOF
```

> **获取你的 Telegram 用户ID**：在 Telegram 中找 `@userinfobot`，发送任意消息即可获得你的数字ID。

### 文件 5：`/root/workspaces/report-bot/CLAUDE.md`（Bot 人设指令）

```bash
cat > /root/workspaces/report-bot/CLAUDE.md << 'EOF'
# 报表日报助手

你是一个报表和日报整理助手。所有输出使用中文。

## 职责
- 接收用户通过 Telegram 发送的原始信息（工作进展、数据、截图等）
- 识别内容类型（日报、周报、数据报表、会议纪要等）
- 整理为结构化格式输出到 Telegram 对话框

## 输出格式
- 日报：按 "今日完成 / 进行中 / 明日计划" 三段式
- 周报：按项目维度汇总，附关键指标
- 数据报表：表格化，标注趋势和异常
- 默认使用 Markdown 格式

## 行为准则
- 收到零散信息时主动归类整理，不要原样转发
- 信息不完整时追问补充
- 保持简洁，不加多余客套话
EOF
```

---

## 五、"正在输入..."持续显示补丁

原始插件只发送一次 typing 动作（5秒后消失），下面的补丁让它每4秒重复发送，直到 bot 回复为止。

### 应用方法

```bash
# 定位插件文件
PLUGIN_FILE="$HOME/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/server.ts"

# 备份原文件
cp "$PLUGIN_FILE" "${PLUGIN_FILE}.bak"

# 用 python3 打补丁
python3 << 'PYEOF'
filepath = "/root/.claude/plugins/marketplaces/claude-plugins-official/external_plugins/telegram/server.ts"
with open(filepath, 'r') as f:
    content = f.read()

# 补丁1: 在 "const bot = new Bot(TOKEN)" 后面添加 typing 循环函数
old1 = 'const bot = new Bot(TOKEN)'
new1 = '''const bot = new Bot(TOKEN)

// Repeating typing indicator — keeps "typing..." visible until bot replies
const typingIntervals = new Map<string, ReturnType<typeof setInterval>>()
function startTyping(chat_id: string) {
  stopTyping(chat_id)
  void bot.api.sendChatAction(chat_id, 'typing').catch(() => {})
  const interval = setInterval(() => {
    void bot.api.sendChatAction(chat_id, 'typing').catch(() => {})
  }, 4000)
  typingIntervals.set(chat_id, interval)
}
function stopTyping(chat_id: string) {
  const interval = typingIntervals.get(chat_id)
  if (interval) {
    clearInterval(interval)
    typingIntervals.delete(chat_id)
  }
}'''
content = content.replace(old1, new1, 1)

# 补丁2: 把单次 typing 调用替换为 startTyping
old2 = """  // Typing indicator — signals "processing" until we reply (or ~5s elapses).
  void bot.api.sendChatAction(chat_id, 'typing').catch(() => {})"""
new2 = """  // Typing indicator — repeats every 4s until bot replies.
  startTyping(String(chat_id))"""
content = content.replace(old2, new2, 1)

# 补丁3: 在 reply 处理中添加 stopTyping
old3 = """case 'reply': {
        const chat_id = args.chat_id as string
        const text = args.text as string"""
new3 = """case 'reply': {
        const chat_id = args.chat_id as string
        stopTyping(chat_id)
        const text = args.text as string"""
content = content.replace(old3, new3, 1)

with open(filepath, 'w') as f:
    f.write(content)
print('Typing patch applied successfully!')
PYEOF
```

---

## 六、完整目录结构总览

```
~/.claude/
├── settings.json                          # 插件市场 + 启用 telegram 插件
├── settings.local.json                    # 全局权限放行（MCP工具 + Bash等）
├── .credentials.json                      # OAuth 登录凭证（自动生成）
├── channels/
│   └── telegram/
│       ├── .env                           # TELEGRAM_BOT_TOKEN=xxx
│       ├── access.json                    # 访问策略 + 白名单用户ID
│       └── inbox/                         # 下载的附件存放目录
└── plugins/
    └── marketplaces/
        └── claude-plugins-official/
            └── external_plugins/
                └── telegram/
                    ├── server.ts           # MCP 服务器（已打 typing 补丁）
                    ├── package.json
                    └── node_modules/

/root/workspaces/report-bot/               # 项目工作目录（bot 从这里启动）
├── CLAUDE.md                              # Bot 人设/指令
├── IDENTITY.md                            # 可选：身份信息
├── USER.md                                # 可选：用户信息
└── .claude/
    └── settings.local.json                # 项目级权限放行
```

---

## 七、迁移到新 VPS 的快速清单

假设你已经有一台部署好的 VPS，要复制到新 VPS：

### 需要复制的文件（共6个）

| # | 文件 | 说明 | 是否需要修改 |
|---|------|------|-------------|
| 1 | `~/.claude/settings.json` | 插件配置 | 不需要 |
| 2 | `~/.claude/settings.local.json` | 全局权限 | 不需要 |
| 3 | `~/.claude/channels/telegram/.env` | Bot Token | **需要**（如果用新 Bot） |
| 4 | `~/.claude/channels/telegram/access.json` | 用户白名单 | **需要**（改用户ID） |
| 5 | `/root/workspaces/report-bot/CLAUDE.md` | Bot 人设 | 按需修改 |
| 6 | `/root/workspaces/report-bot/.claude/settings.local.json` | 项目权限 | 不需要 |

### 迁移步骤

```bash
# 在新 VPS 上执行：

# 1. 装依赖
apt update && apt install -y curl tmux python3 git
curl -fsSL https://bun.sh/install | bash && source ~/.bashrc
curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt install -y nodejs
npm install -g @anthropic-ai/claude-code

# 2. 登录（必须手动）
claude
# → 浏览器登录 → Ctrl+C

# 3. 安装插件（在 claude 中执行）
# /plugin install telegram@claude-plugins-official
# /reload-plugins
# Ctrl+C 退出

# 4. 写入上面第四节的6个配置文件

# 5. 打 typing 补丁（第五节的 python3 脚本）

# 6. 配对（如果是新 Bot）
cd /root/workspaces/report-bot
claude --channels plugin:telegram@claude-plugins-official
# → TG发消息给 bot → 得到配对码 → /telegram:access pair <码>
# → /telegram:access policy allowlist
# → Ctrl+C

# 7. 后台启动
tmux new -s tgbot
cd /root/workspaces/report-bot
claude --channels plugin:telegram@claude-plugins-official
# Ctrl+B, D 脱离
```

---

## 八、常用运维命令

```bash
# 查看 bot 是否在运行
tmux list-sessions
ps aux | grep claude

# 进入 bot 终端查看状态
tmux attach -t tgbot

# 脱离（不关闭 bot）
# 按 Ctrl+B 然后按 D

# 重启 bot
tmux attach -t tgbot
# 输入 /exit 回车
claude --channels plugin:telegram@claude-plugins-official
# Ctrl+B, D 脱离

# 查看 bot token
cat ~/.claude/channels/telegram/.env

# 查看白名单用户
cat ~/.claude/channels/telegram/access.json

# 添加新用户到白名单（手动编辑）
# 在 allowFrom 数组里加入新的 Telegram 用户ID
```

---

## 九、当前已部署实例信息

| 项目 | 值 |
|------|-----|
| VPS | 45.251.241.94:27482 |
| Bot Token | `8709300067:AAGfhBp_8JM0EZ0yzGfsfwdh2yLQXrS9OXQ` |
| 白名单用户 | `8467782635` |
| tmux session | `tgbot` |
| 项目目录 | `/root/workspaces/report-bot` |
| Claude 版本 | 2.1.92 |
| Bun 版本 | 1.3.11 |