1. 项目概述将本地Claude Code打造成24小时在线的Telegram机器人如果你和我一样经常在手机或平板电脑上突然冒出一些代码调试的想法或者想远程查看一下服务器上的日志但又懒得打开电脑那么这个项目绝对值得你花时间折腾一下。claude-telegram-server本质上是一个桥梁它把运行在你本地机器Windows、macOS或Linux都行上的Claude Code变成了一个可以通过Telegram聊天窗口随时调用的AI助手。这意味着你只需要在Telegram里发条消息比如“帮我看看/home/user/project/logs/error.log里最新的错误”Claude就能在你的电脑上读取文件、分析内容并把结果直接发回你的手机。这个方案的核心价值在于“远程”和“持久化”。它不是为了替代Claude的Web界面而是扩展了它的使用场景。你可以把它部署在一台长期开机的家庭服务器、开发机甚至云端VPS上让它成为一个7x24小时待命的私人编程助手。无论是睡前突然想跑个测试还是在通勤路上想修改几行配置这个机器人都会是你最忠实的“赛博管家”。项目基于Node.js构建通过整合Telegram Bot API和Claude Code的本地能力实现了一套完整的、可交互的自动化工作流。2. 核心架构与工作原理拆解2.1 技术栈选型与角色定位这个项目不是一个简单的API转发器而是一个功能完整的AI Agent服务端。它主要依赖以下几个核心组件Node.js运行时环境作为服务端的主运行环境。选择Node.js是因为其异步非阻塞I/O模型非常适合处理Telegram Bot的Webhook请求和Claude Code的长时间运行任务同时拥有极其丰富的NPM生态方便集成各种工具。Telegraf库这是Node.js生态中最成熟、最强大的Telegram Bot框架。它封装了Telegram Bot API的所有细节让开发者可以专注于业务逻辑轻松处理消息、命令、回调查询等交互。Claude Code本地实例项目的“大脑”。它不是通过官方的Anthropic API进行云端调用而是直接与你本地安装的Claude Code桌面应用或命令行工具交互。这意味着所有代码执行、文件读写、命令运行都发生在你的本地环境数据无需出域安全性和可控性极高。进程管理与IPC进程间通信这是技术难点之一。服务端需要能够启动、监控并与Claude Code进程通信向其发送指令并获取结构化的输出。通常会采用child_process模块生成子进程并通过标准输入输出stdin/stdout、IPC通道或一个预先定义好的本地Socket/HTTP接口来交换数据。整个系统的工作流可以概括为用户发送Telegram消息 - Telegraf库接收并解析 - 服务端逻辑处理消息内容 - 服务端通过IPC驱动本地Claude Code执行相应操作读文件、写代码、运行命令- 获取Claude Code的执行结果 - 将结果格式化后通过Telegraf发送回Telegram对话。注意由于直接操作本地文件和执行命令该机器人拥有与你启动服务时所用用户账户同等的权限。因此绝对不要将机器人令牌Token分享给他人或将其添加到公开群组。务必将其视为一把打开你电脑后门的钥匙来保管。2.2 安全模型与访问控制设计任何允许远程执行本地命令的工具安全都是首要考虑。claude-telegram-server通常通过以下几种方式构建安全边界Telegram用户白名单这是最核心的访问控制。在配置文件中你需要设置一个ALLOWED_USER_IDS列表里面填入你的Telegram用户ID。机器人启动后会校验每条消息的发送者ID是否在白名单内如果不是则直接忽略或回复无权限提示。这样就确保了只有你本人或你信任的指定用户可以操作机器人。文件系统沙箱工作目录在配置中你需要指定一个WORKING_DIRECTORY。Claude Code的所有文件操作都会被限制在这个目录及其子目录下。即使攻击者通过某种方式发送了rm -rf /这样的命令由于进程的当前工作目录被锁定也无法影响到系统其他部分。最佳实践是为每个项目或用途创建一个专属目录。命令过滤与安全策略高级的实现可能会包含一个简单的命令过滤器阻止明显危险的系统命令如格式化磁盘、删除系统关键文件等。不过更可靠的安全策略依赖于上述两点受信任的用户和受限的工作目录。网络隔离服务本身只与Telegram API服务器和你本地Claude Code通信。确保它运行在可信的内部网络环境中不要将服务端口如果使用Polling模式暴露在公网。这套模型在提供强大便利性的同时将风险降到了可管理的水平。只要你妥善保管令牌并正确设置白名单其安全性是足以应对个人使用场景的。3. 从零开始的详细部署与配置指南3.1 环境准备不只是安装软件在开始之前我们需要确保三方面的基础环境就绪机器环境、Claude Code环境以及Telegram Bot。机器环境项目支持跨平台但不同系统有细微差别。对于Windows用户确保已安装Node.js建议LTS版本如18.x或20.x和Python某些Claude Code功能或依赖可能需要。对于macOS和Linux用户除了Node.js还需确保拥有常见的构建工具如gcc,make。可以通过在终端运行node --version和npm --version来验证。Claude Code环境这是项目的核心依赖。你需要从Anthropic官网下载并安装Claude Code应用程序。安装后请务必在本地成功运行一次确保其能正常启动并响应。同时你需要准备好你的Anthropic账户凭证通常是API密钥或会话令牌因为本地Claude Code在启动时可能需要认证。请将这些凭证放在安全的地方后续配置会用到。创建Telegram Bot这是与你的服务交互的“前台”。在Telegram中搜索并联系BotFather。发送/newbot命令按照提示依次输入你的机器人名称如My Claude Assistant和用户名必须以bot结尾如my_claude_assistant_bot。创建成功后BotFather会提供给你一个HTTP API访问令牌形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。请立即妥善保存此令牌它相当于你机器人的密码一旦泄露他人即可控制你的机器人。同时你需要获取自己的Telegram用户ID。一个简单的方法是向userinfobot这个机器人发送任意消息它会回复你的ID。记下这个数字ID用于后续配置白名单。3.2 项目获取与初始化配置如果你选择从源码运行推荐便于理解和自定义而不是直接使用预编译的发布包步骤如下# 1. 克隆仓库假设你有Git环境 git clone https://github.com/Hewechargeable220/claude-telegram-server.git cd claude-telegram-server # 2. 安装Node.js依赖 npm install # 3. 复制配置文件模板并开始编辑 cp config.example.json config.json接下来是关键的配置环节。打开config.json文件你会看到一个JSON结构需要填充以下几个关键字段{ telegram: { botToken: YOUR_BOT_TOKEN_HERE, // 替换为从BotFather获取的令牌 allowedUserIds: [123456789] // 替换为你的Telegram用户ID可添加多个 }, claude: { claudeCodePath: /Applications/Claude Code.app/Contents/MacOS/Claude Code, // Claude Code可执行文件路径 apiKey: your-anthropic-api-key-optional, // 有时需要取决于Claude Code启动方式 workingDirectory: /Users/YourName/Projects/ClaudeWorkspace // 核心限制文件访问的工作目录 }, server: { port: 3000, // 如果使用Webhook模式才需要 host: 0.0.0.0 } }配置详解与避坑指南claudeCodePath这是最容易出错的地方。在Windows上路径可能是C:\\Program Files\\Claude Code\\claude-code.exe在macOS上如上例所示是应用程序包内的可执行文件路径在Linux上则可能是/usr/bin/claude-code或你安装的位置。一个查找方法是在系统终端中尝试输入启动Claude Code的命令然后通过whichLinux/macOS或whereWindows命令来定位。workingDirectory强烈建议专门新建一个空文件夹作为工作目录例如~/ClaudeBotWorkspace。不要直接指向你的家目录或系统根目录。先在这个目录下放一些测试文件确保机器人有读写权限。allowedUserIds务必准确填写。你可以通过向userinfobot发消息获取ID。如果填错你自己也将无法使用机器人。3.3 服务启动与连接测试配置完成后就可以启动服务了。通常项目会提供一个启动脚本。# 在项目根目录下运行 npm start # 或者如果定义了脚本 node index.js如果一切正常终端会输出类似“Bot is starting...”、“Claude Code process started”、“Bot is listening for messages”的信息。进行首次连接测试回到Telegram找到你创建的机器人用户名如my_claude_assistant_bot。发送一条简单的命令例如/start或 “Hello”。观察终端日志应该能看到收到消息的提示。如果机器人能回复一条欢迎信息或确认收到说明Telegram连接成功。测试Claude Code集成在Telegram中向机器人发送消息ls或列出目录具体命令取决于机器人如何解析。理想情况下机器人应该回复你workingDirectory下的文件列表。如果失败请查看终端日志。常见的错误包括claudeCodePath配置错误“ENOENT”错误、Claude Code启动时需要图形界面而当前是无头环境、或者权限不足。实操心得在Linux服务器等无图形界面的环境中运行Claude Code可能是最大的挑战。某些版本的Claude Code可能需要一个虚拟显示框架如Xvfb才能运行。如果遇到相关问题需要查阅Claude Code的无头模式运行文档或者考虑使用其提供的命令行接口如果存在。4. 高级功能使用与场景化实战4.1 核心交互模式与命令设计基础的“发送消息-得到回复”只是开始。一个成熟的机器人应该能理解更复杂的意图。claude-telegram-server通常支持以下几种交互模式自然语言指令直接描述你的需求。例如“请读取server.log文件找出所有包含‘ERROR’的行并总结前三个错误。” 机器人需要解析这个指令将其转化为一系列动作定位文件、读取内容、过滤文本、分析总结。结构化命令类似命令行但更友好。例如/read config.yaml/run “npm test”/write script.py “print(‘hello’)”。这种方式意图明确易于机器人解析和执行。文件上传处理Telegram允许用户上传文件。你可以将一段代码片段.py,.js文件或一个配置文件.json,.yaml直接发送给机器人并附言“请分析这个文件的函数结构”或“用这个配置文件更新项目里的对应文件”。机器人需要能够接收并保存文件附件到工作目录然后交给Claude Code处理。上下文会话保持对话的连贯性。例如你首先说“打开project/src/main.js”然后说“在第30行后面添加一个日志语句”。机器人需要记住当前“打开”的文件并在上下文中执行第二个操作。在源码中这些功能是通过扩展Telegraf的hears监听文本、command处理命令、on(‘document’)处理文档等监听器来实现的。你可以根据自己需求修改或添加新的命令解析逻辑。4.2 典型应用场景深度演练场景一远程服务器日志监控与诊断假设你的应用运行在一台远程Linux服务器上日志文件位于/var/log/myapp/。配置将机器人的workingDirectory设置为/var/log/myapp确保运行服务的用户有读取权限。使用当应用出现问题时你在手机上向机器人发送“分析今天 error.log 中最频繁的错误类型。”背后流程机器人驱动Claude Code执行cat error.log | grep “$(date ’%Y-%m-%d’)” | awk -F’ ‘ ‘{print $4}’ | sort | uniq -c | sort -nr | head -5或类似的命令组合将结果返回给你。你无需SSH登录服务器也无需记忆复杂的grep/awk命令。场景二跨设备协同编码你在办公室电脑上写了一半的代码回家后想用平板电脑继续。配置办公室电脑上运行着此机器人workingDirectory指向你的项目目录。使用在家里的平板电脑上用Telegram发送“显示features/auth.js文件最近10次提交的diff。” 或者 “在utils/helpers.js中帮我写一个格式化日期的函数。”价值你无需在平板电脑上配置开发环境、安装Git、拉取代码。所有操作都在办公室电脑上完成你只通过Telegram接收结果和发送新指令。场景三自动化日常任务你可以将一些固定任务封装成快捷命令。定制开发修改机器人源码添加一个自定义命令/daily_report。命令逻辑当收到该命令时机器人执行一系列操作从数据库拉取昨日数据 - 用Python脚本生成分析图表 - 将图表图片和总结文本发送到Telegram。结果每天早晨你只需在Telegram里发送/daily_report一份完整的报告就会推送到你手上。4.3 性能优化与稳定运行要让这个机器人7x24小时稳定运行需要考虑以下几点进程守护简单的node index.js在终端关闭后就会停止。你需要使用进程守护工具。在Linux上可以用systemd创建服务在macOS上可以用launchd在Windows上可以用NSSM(Non-Sucking Service Manager) 或将其设置为计划任务。这样能确保服务在系统重启后自动运行并在崩溃时尝试重启。日志与监控将服务的控制台输出重定向到日志文件如npm start bot.log 21 便于问题排查。可以配置简单的健康检查例如定时向自己发送“ping”消息如果收不到回复则触发报警发送邮件或通知到另一个Telegram账号。资源管理Claude Code进程可能占用较多内存。在长时间不活动后可以考虑让机器人主动关闭Claude Code子进程待有新请求时再启动懒加载。同时注意清理工作目录中机器人产生的临时文件。网络可靠性服务端与Telegram API的通信必须稳定。如果使用Webhook模式你需要一个公网可访问的HTTPS地址并处理好网络波动。对于个人用户使用长轮询Long Polling模式更为简单可靠它由你的服务器主动向Telegram查询消息无需公网IP和SSL证书。5. 常见问题排查与进阶调试技巧即使按照指南操作也可能会遇到各种问题。下面是一个快速排查清单和解决方案。5.1 机器人无响应或报错问题现象可能原因排查步骤与解决方案发送消息后机器人完全没反应。1. 服务进程未运行。2. Bot Token配置错误。3. 网络问题无法连接Telegram API。1. 检查终端或服务管理工具确认node进程是否存在。2. 在config.json中仔细核对Bot Token确保没有多余空格或换行。3. 尝试在服务器上curl https://api.telegram.org检查网络连通性。如果是国内服务器可能需要配置网络代理。机器人回复“无权限”或忽略消息。allowedUserIds配置错误你的ID不在白名单内。1. 再次向 userinfobot 确认你的Telegram User ID。2. 检查config.json中的allowedUserIds是否为数组格式且你的ID已正确填入。例如[123456789]。服务启动后立即退出终端有错误输出。1. 依赖包安装不全。2.config.json格式错误如JSON语法错误。3. 关键配置项如claudeCodePath路径不存在。1. 删除node_modules文件夹和package-lock.json重新运行npm install。2. 使用 JSON 校验工具如在线JSON校验网站检查config.json文件。3. 逐行检查终端报错信息通常会有明确的错误提示指向问题所在。5.2 Claude Code集成失败问题现象可能原因排查步骤与解决方案机器人回复“无法启动Claude”或“执行超时”。1.claudeCodePath路径不正确。2. Claude Code需要图形界面但当前是无头环境。3. 系统权限不足无法启动子进程。1.路径验证在终端中手动执行配置的路径命令看是否能启动Claude Code。例如/Applications/Claude\ Code.app/Contents/MacOS/Claude\ Code --version如果支持。2.无头环境对于Linux服务器尝试安装xvfb并在启动命令前加上xvfb-run -a。例如在启动脚本中claudeCommand ‘xvfb-run -a ’ config.claude.claudeCodePath。这需要Claude Code本身支持在虚拟显示中运行。3.权限问题确保运行Node.js服务的用户有执行Claude Code文件的权限。可以尝试用sudo启动服务测试仅用于排查长期运行不建议用root。Claude可以启动但无法读取/写入工作目录的文件。1.workingDirectory路径配置错误。2. 运行服务的用户对该目录没有读写权限。1. 使用绝对路径并确保路径存在。可以在服务代码中启动时打印当前工作目录进行确认。2. 检查目录权限ls -la /path/to/your/workspace。确保运行服务的用户如node或你的用户名是目录的所有者或有读写权限。必要时使用chown或chmod命令修改。执行复杂命令或长时间任务时机器人停止响应。1. Claude Code进程卡死或占用资源过高。2. Telegram Bot请求超时。3. 服务端没有处理长时间任务的异步机制。1.资源监控在服务器上使用top或htop命令查看Claude Code进程的资源占用情况。2.超时设置检查Telegraf和HTTP客户端如axios是否有配置超时时间。对于长任务服务端在收到请求后应立即回复一个“正在处理”的提示然后再异步执行任务最后将结果推送回去。3.代码优化审查服务端代码确保在执行耗时操作时使用了async/await并正确处理了Promise避免阻塞主线程。5.3 进阶调试技巧当遇到复杂问题时系统化的调试方法能节省大量时间。分级日志法不要只用一个console.log。在代码中引入winston或pino等日志库设置不同级别如error,warn,info,debug。在关键函数入口、出口、网络请求前后、进程调用前后都打上debug日志。通过环境变量如LOG_LEVELdebug来控制日志详细程度。模拟测试将问题拆解。单独写一个测试脚本测试与Claude Code的IPC通信是否正常。再写一个脚本测试发送模拟Telegram消息是否能被正确解析。分而治之定位问题模块。进程状态检查在服务运行时通过ps aux | grep claude和ps aux | grep node查看相关进程的状态和PID。如果发现僵尸进程或内存泄漏需要检查代码中是否正确处理了子进程的退出信号和资源回收。网络流量嗅探谨慎使用如果怀疑是网络通信问题可以在本地开发时使用像ngrok这样的工具将本地服务暴露到公网并设置为Telegram Bot的Webhook然后在本地观察所有进出的HTTP请求和响应这对于调试复杂的交互流程非常有用。这个项目将强大的本地AI能力与最普及的通讯工具相结合创造了一种极其灵活的人机交互方式。它的上限取决于你的想象力和定制化开发能力。你可以将它视为一个可编程的、具备文件系统和命令行访问权限的AI中间件。无论是作为个人效率工具还是作为特定工作流自动化的一部分它都提供了一个极具潜力的起点。