ByteNoteByteNote
字

字节笔记本

2026年2月22日

Claude Telegram Bot：将 Claude Code 变成你的个人 Telegram 助手

#Claude Code

本文介绍 Claude Telegram Bot，一个开源项目，让你能够通过 Telegram 随时随地访问 Claude Code，将其变成你的个人智能助手。该项目由 Fabrizio Rinaldi（linuz90）开发，在 GitHub 上已获得 375+ stars。

项目简介

Claude Telegram Bot 是一个基于 TypeScript 开发的 Telegram 机器人，它将 Claude Code 的强大功能扩展到移动端。通过这个机器人，你可以：

  • 在手机上与 Claude 进行自然对话
  • 发送语音消息、图片、文档给 Claude 分析
  • 让 Claude 帮你处理文件、编写代码、管理任务
  • 随时随地访问你的个人助手

虽然 Claude Code 被描述为一个强大的 AI 编程代理，但当给予正确的指令、上下文和工具时，它实际上也是一个非常有能力的通用代理。

核心特性

  • 💬 文本对话：提问、给出指令、进行对话
  • 🎤 语音支持：自然语音交流 - 通过 OpenAI 转录后由 Claude 处理
  • 📸 图片分析：发送截图、文档或任何视觉内容进行分析
  • 📄 文档处理：PDF、文本文件和压缩包（ZIP、TAR）会被提取并分析
  • 🎵 音频处理：音频文件（mp3、m4a、ogg、wav 等）通过 OpenAI 转录后处理
  • 🎬 视频支持：处理视频消息和视频笔记
  • 🔄 会话持久化：跨消息继续对话
  • 📨 消息队列：Claude 工作时可以发送多条消息 - 它们会自动排队。使用 ! 前缀或 /stop 命令可中断并立即发送
  • 🧠 扩展思考：使用 "think" 或 "reason" 等词触发 Claude 的推理能力 - 你会看到它的思考过程（可通过 THINKING_TRIGGER_KEYWORDS 配置）
  • 🔘 交互式按钮：Claude 可以通过内置的 ask_user MCP 工具将选项显示为可点击的内联按钮

技术栈

  • TypeScript (99.8%) - 主要开发语言
  • Bun - 运行时和包管理器
  • @anthropic-ai/claude-agent-sdk - Claude Agent SDK
  • node-telegram-bot-api - Telegram Bot API
  • OpenAI API - 语音转录功能

安装指南

前置要求

  • Bun 1.0+ - 安装 Bun
  • Claude Agent SDK - @anthropic-ai/claude-agent-sdk（通过 bun install 安装）
  • Telegram Bot Token - 从 @BotFather 获取
  • OpenAI API Key（可选，用于语音转录）

快速开始

bash
# 克隆仓库
git clone https://github.com/linuz90/claude-telegram-bot.git
cd claude-telegram-bot

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入你的凭证

# 安装依赖
bun install

# 启动机器人
bun run src/index.ts

Claude 认证方式

该机器人支持两种认证方式：

方式适用场景设置方法
CLI Auth（推荐）高频使用，成本效益高运行 claude 一次完成认证
API KeyCI/CD、无 Claude Code 的环境在 .env 中设置 ANTHROPIC_API_KEY

CLI Auth（推荐）：SDK 自动使用你的 Claude Code 登录。只需确保至少运行过一次 claude 并完成认证。这使用你的 Claude Code 订阅，对于高频使用来说更具成本效益。

API Key：适用于未安装 Claude Code 的环境。从 console.anthropic.com 获取密钥并添加到 .env：

ANTHROPIC_API_KEY=sk-ant-api03-...

注意：API 使用按 token 计费，高频使用可能产生较高费用。

配置说明

1. 创建机器人

  1. 在 Telegram 上打开 @BotFather
  2. 发送 /newbot 并按照提示创建机器人
  3. 复制 token（格式如 1234567890:ABC-DEF...）

然后发送 /setcommands 给 BotFather 并粘贴以下命令列表：

text
start - 显示状态和用户 ID
new - 开始新会话
resume - 从最近 5 个会话中选择恢复
stop - 中断当前查询
status - 检查 Claude 正在做什么
restart - 重启机器人

2. 配置环境变量

创建 .env 文件：

bash
# 必需
TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF...  # 从 @BotFather 获取
TELEGRAM_ALLOWED_USERS=123456789          # 你的 Telegram 用户 ID

# 推荐
CLAUDE_WORKING_DIR=/path/to/your/folder   # Claude 运行的工作目录
OPENAI_API_KEY=sk-...                     # 用于语音转录

查找 Telegram 用户 ID：在 Telegram 上向 @userinfobot 发送消息。

文件访问路径：默认情况下，Claude 可以访问：

  • CLAUDE_WORKING_DIR（或未设置时的主目录）
  • ~/Documents、~/Downloads、~/Desktop
  • ~/.claude（用于 Claude Code 计划和设置）

如需自定义，在 .env 中设置 ALLOWED_PATHS（逗号分隔）。注意：这会覆盖所有默认值，如需使用计划模式，请包含 ~/.claude：

bash
ALLOWED_PATHS=/your/project,/other/path,~/.claude

3. 配置 MCP 服务器（可选）

复制并编辑 MCP 配置：

bash
cp mcp-config.example.ts mcp-config.local.ts
# 编辑 mcp-config.local.ts 添加你的 MCP 服务器

机器人包含一个内置的 ask_user MCP 服务器，让 Claude 可以将选项显示为可点击的内联键盘按钮。你可以添加自己的 MCP 服务器（Things、Notion、Typefully 等）来让 Claude 访问你的工具。

机器人命令

命令描述
/start显示状态和用户 ID
/new开始新会话
/resume从最近 5 个会话中选择恢复（带摘要）
/stop中断当前查询
/status检查 Claude 正在做什么
/restart重启机器人

作为服务运行（macOS）

bash
# 复制并编辑 plist 文件
cp launchagent/com.claude-telegram-ts.plist.template ~/Library/LaunchAgents/com.claude-telegram-ts.plist

# 编辑 plist 填入你的路径和环境变量
# 加载服务
launchctl load ~/Library/LaunchAgents/com.claude-telegram-ts.plist

机器人将在登录时自动启动，崩溃时自动重启。

防止休眠：要让机器人在 Mac 空闲时保持运行，前往系统设置 → 电池 → 选项，启用"当显示器关闭时防止自动休眠"（使用电源适配器时）。

日志查看：

bash
tail -f /tmp/claude-telegram-bot-ts.log    # 标准输出
tail -f /tmp/claude-telegram-bot-ts.err    # 标准错误

Shell 别名（添加到 ~/.zshrc 或 ~/.bashrc）：

bash
alias cbot='launchctl list | grep com.claude-telegram-ts'
alias cbot-stop='launchctl bootout gui/$(id -u)/com.claude-telegram-ts 2>/dev/null && echo "Stopped"'
alias cbot-start='launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-telegram-ts.plist 2>/dev/null && echo "Started"'
alias cbot-restart='launchctl kickstart -k gui/$(id -u)/com.claude-telegram-ts && echo "Restarted"'
alias cbot-logs='tail -f /tmp/claude-telegram-bot-ts.log'

安全说明

⚠️ 重要提示：该机器人运行 Claude Code 时绕过所有权限提示。Claude 可以在允许的路径内无需确认地读取、写入和执行命令。这是为了无缝的移动体验而有意设计的，但在部署前你应该了解其影响。

多层保护防止滥用：

  • 用户白名单 - 只有你的 Telegram ID 可以使用机器人
  • 意图分类 - AI 过滤器阻止危险请求
  • 路径验证 - 文件访问限制在 ALLOWED_PATHS
  • 命令安全 - 阻止 rm -rf / 等破坏性模式
  • 速率限制 - 防止失控使用
  • 审计日志 - 所有交互记录到 /tmp/claude-telegram-audit.log

阅读完整的安全模型文档了解权限工作原理和保护措施。

故障排除

机器人无响应

  • 验证你的用户 ID 是否在 TELEGRAM_ALLOWED_USERS 中
  • 检查机器人 token 是否正确
  • 查看日志：tail -f /tmp/claude-telegram-bot-ts.err
  • 确保机器人进程正在运行

Claude 认证问题

  • CLI 认证：在终端运行 claude 验证是否已登录
  • API Key：检查 ANTHROPIC_API_KEY 是否设置且以 sk-ant-api03- 开头
  • 在 console.anthropic.com 验证 API 密钥有余额

语音消息失败

  • 确保 .env 中设置了 OPENAI_API_KEY
  • 验证密钥有效且有余额

Claude 无法访问文件

  • 检查 CLAUDE_WORKING_DIR 指向存在的目录
  • 验证 ALLOWED_PATHS 包含你想要 Claude 访问的目录
  • 确保机器人进程有读写权限

MCP 工具不工作

  • 验证 mcp-config.ts 存在并正确导出
  • 检查 MCP 服务器依赖是否已安装
  • 在日志中查找 MCP 错误

个人助手指南

作者提供了详细的个人助手指南，介绍如何设置 Claude Code 作为个人助手，包括：

  • 创建包含个人偏好、笔记位置、工作流程的 CLAUDE.md
  • 根据需求设置工具和脚本
  • 配置 MCP 服务器扩展功能

项目链接

许可证

MIT License

Claude Code
上一篇

Linux 统计文件行数 - wc 命令详解

下一篇

Claude Telegram Bot：将 Claude Code 变成你的个人 Telegram 助手

分享: