1. 项目概述将你的命令行AI助手装进Telegram如果你和我一样是个喜欢在命令行里折腾的开发者那你肯定对AI驱动的CLI工具不陌生。它们能帮你写代码、分析日志、甚至管理服务器效率提升不是一点半点。但有个问题一直挺烦人你人必须守在电脑前盯着那个终端窗口。想躺在沙发上用手机继续刚才的对话或者在外出时临时让AI帮你查个东西传统CLI工具就显得力不从心了。今天要聊的这个项目bravian1/gemini_cli_server就完美地解决了这个痛点。它的核心思路非常巧妙把一个功能强大的命令行AI工具Gemini CLI“嫁接”到Telegram这个全球流行的即时通讯应用上。简单来说它为你创建了一个专属的Telegram机器人这个机器人就是你Gemini CLI的“传声筒”和“执行臂”。你可以在任何有网络的地方通过手机或电脑上的Telegram像和朋友聊天一样向你的AI助手提问、下指令而机器人会在后台默默地调用你本机的Gemini CLI来处理请求并把结果实时推送回你的聊天窗口。这不仅仅是把聊天界面当个“壳”那么简单。项目实现了完整的双向通信、命令管理、状态监控甚至支持与更底层的MCPModel Context Protocol服务器集成让AI的能力通过Telegram得到了无损的延伸。对于需要随时随地保持“编码状态”或进行自动化操作的开发者、运维人员来说这相当于给你的生产力工具插上了移动的翅膀。2. 核心架构与交互流程拆解理解这个项目如何工作是后续部署和深度定制的基础。整个系统可以看作一个精心设计的“消息管道”由三个核心角色协同完成。2.1 三大核心组件解析1. Gemini CLI 能力核心这是整个系统的“大脑”。Gemini CLI本身是一个可以通过自然语言执行复杂命令行操作的工具。它接受一个文本提示prompt理解你的意图然后将其转化为一系列具体的系统命令或脚本去执行最后将结果返回。项目本身并不包含Gemini CLI你需要先在你的机器上安装并配置好它。它是所有智能响应的源头。2.listen.js 本地网关与调度中心这是一个用Node.js编写的HTTP服务器运行在你的本地开发机或服务器上。它的角色至关重要承担了多项任务消息接收器 它监听一个特定的本地端口默认8765等待来自外部的HTTP POST请求。Telegram机器人会把用户消息打包成JSON格式发送到这个端点。请求转发器 收到消息后它会提取出其中的文本内容然后以子进程的方式调用本地的Gemini CLI程序并将用户消息作为参数传递过去。执行模式控制 项目默认启用了--yolo模式。这是一个非常实用的设计。yolo是“You Only Live Once”的缩写在这里意味着“自动批准”。在这种模式下Gemini CLI会跳过需要人工确认的步骤比如“是否要执行这个rm -rf命令”直接执行它认为正确的操作。这对于Telegram这种异步、追求流畅对话的场景是必要的否则每个操作都要等你回Telegram点确认体验就割裂了。当然这也意味着你需要对Gemini CLI有足够的信任或者将其用于相对安全的操作环境。响应回传器 获取Gemini CLI的执行结果后listen.js会将其封装成响应发回给调用它的Telegram机器人。3.main.go Telegram机器人本体这是一个用Go语言编写的应用程序它是用户在Telegram中直接交互的对象。它的职责很清晰用户交互前端 通过Telegram Bot API与Telegram服务器保持长连接接收用户发送的文字消息或命令。消息路由中继 将用户消息通过HTTP请求转发给listen.js服务器。响应展示终端 接收listen.js返回的Gemini CLI处理结果并将其作为消息回复给用户。2.2 完整数据流一次请求的旅程让我们跟踪一条消息从发送到回复的全过程这能帮你更好地理解排错逻辑用户发起 你在Telegram中向你的机器人发送了一条消息“帮我列出当前目录下所有大于100MB的日志文件。”Bot接收main.go程序通过Telegram Bot API的getUpdates或Webhook方式实时获取到这条消息。请求转发main.go将消息内容、发送者ID等信息按照预定格式封装成JSON向配置好的GEMINI_ENDPOINT即listen.js的地址发起一个HTTP POST请求。本地处理listen.js在本地端口8765上收到这个请求。它解析JSON提取出“帮我列出...”这段文本。调用AIlisten.js在后台启动一个子进程执行类似gemini-cli --yolo “帮我列出当前目录下所有大于100MB的日志文件”的命令。执行与返回 Gemini CLI在本地运行它可能会组合使用find、du等命令来完成这个任务然后将找到的文件列表作为输出返回给listen.js子进程。响应回传listen.js获取到CLI的输出将其作为HTTP响应体发回给正在等待的main.go。用户获答main.go收到响应提取出文本内容通过Bot API将“找到的日志文件有app.log.1, error.log.2 ...”这条消息发送回你的Telegram聊天窗口。整个流程在理想情况下是秒级完成的你感受到的就是在Telegram里和一个“懂命令行”的AI助手自然对话。注意关于--yolo模式这是该项目流畅体验的关键但也带来了最高的安全风险。它相当于赋予了Gemini CLI在你系统上的“自动执行权”。在将此项目用于生产环境或存有重要数据的机器前请务必在测试环境中充分验证Gemini CLI命令的准确性和安全性或考虑修改listen.js脚本对特定高风险命令进行过滤或改为需要确认的模式。3. 从零开始部署详细步骤与避坑指南理论清晰了我们动手把它跑起来。部署过程涉及几个环境的配置我们一步一步来。3.1 前置条件准备在克隆项目代码之前你需要确保以下基础软件已经就位Node.js环境listen.js是Node.js脚本需要Node.js运行时。建议安装LTS版本如v18.x或v20.x。你可以通过node -v和npm -v来检查。Go语言环境 Telegram机器人main.go需要Go来编译运行。安装最新稳定版即可通过go version检查。Gemini CLI 这是项目的灵魂。你需要按照其官方文档在你的系统上完成安装和初步配置。通常这可能涉及获取API密钥、进行初始设置等。确保在命令行中直接输入gemini-cli或对应的命令名可以启动它。Telegram账号与BotFather 你需要一个Telegram账号并通过BotFather这个官方机器人来创建你自己的机器人。3.2 项目获取与基础配置首先将项目代码克隆到本地git clone https://github.com/bravian1/gemini_cli_server.git cd gemini_cli_server接下来是关键一步放置配置和脚本。根据项目说明你需要将项目中的commands和scripts两个文件夹复制到你的Gemini CLI配置目录通常是~/.gemini/下。cp -r commands/ scripts/ ~/.gemini/为什么这么做Gemini CLI在设计上允许用户通过特定目录下的配置文件来扩展其命令和能力。将这两个文件夹复制过去相当于为你的Gemini CLI“安装”了Telegram机器人所需的插件和监听脚本。scripts/listen.js会被直接调用而commands/listen/目录下的.toml文件则定义了Telegram机器人中可用的命令菜单。3.3 创建并配置你的Telegram机器人在Telegram中搜索并打开BotFather。发送/newbot指令按照提示操作为你的机器人起一个显示名称如My Dev Assistant。为你的机器人设置一个唯一的用户名必须以bot结尾如my_gemini_cli_bot。创建成功后BotFather会给你一串重要的HTTP API Token格式类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。务必妥善保管这相当于你机器人的密码。3.4 配置机器人应用与环境变量进入项目中的机器人目录并创建环境配置文件cd telegram_bot cp .env.example .env # 如果存在示例文件则复制它 # 或者直接创建.env文件编辑.env文件填入你的配置TELEGRAM_BOT_TOKEN1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ GEMINI_ENDPOINThttp://127.0.0.1:8765/event # TARGET_CHAT_ID # 可选初期测试可以先注释掉TELEGRAM_BOT_TOKEN 填入你从BotFather获取的令牌。GEMINI_ENDPOINT 这是listen.js服务对外的地址。目前我们先填本地地址表示机器人会和本地服务通信。这意味着main.go和listen.js必须在同一台机器上运行或者你能确保网络互通。TARGET_CHAT_ID 这是一个重要的安全选项。如果不设置理论上任何人只要知道你的机器人用户名都可以给它发消息并触发你的Gemini CLI。设置后机器人将只响应来自该特定聊天ID的消息。你可以先注释掉进行公开测试但正式使用时强烈建议设置。获取你的Chat ID的一个简单方法是先给机器人发条消息然后通过一个临时脚本或curl调用getUpdatesAPI来查看。3.5 启动服务与初步测试现在我们需要启动两个服务它们需要同时运行。第一步启动本地监听网关listen.js在一个终端窗口运行node ~/.gemini/scripts/listen.js如果一切正常你会看到服务器启动在http://127.0.0.1:8765的日志。这个终端窗口最好保持打开以便观察运行日志。第二步启动Telegram机器人main.go打开另一个终端窗口进入机器人目录并运行cd path/to/gemini_cli_server/telegram_bot go run main.go程序启动后会尝试连接Telegram服务器。你可以在Telegram中找到你的机器人通过你设置的用户名然后发送一条简单的消息比如“Hello”。如果配置正确机器人应该会回复你而回复的内容正是你的Gemini CLI对“Hello”这个提示词生成的响应。常见启动问题排查Error: Cannot find module 说明Node.js环境或项目依赖有问题。检查listen.js所在路径是否正确以及Node.js是否安装。go: command not found Go语言环境未安装或未加入PATH。机器人无响应 检查两个服务是否都在运行检查.env文件中的TELEGRAM_BOT_TOKEN是否正确检查防火墙是否阻止了本地回环地址127.0.0.1的通信。Gemini CLI未找到 确保Gemini CLI已正确安装并且其命令可以在运行listen.js的用户环境下直接执行。有时需要指定全路径或配置环境变量。4. 高级配置让机器人面向互联网与命令管理在本地跑通只是第一步。要想真正实现“随时随地”访问你需要让listen.js这个本地服务能被互联网上的Telegram服务器访问到。同时了解如何管理机器人命令能让你的助手更易用。4.1 使用Ngrok暴露本地服务由于你的listen.js运行在本地网络Telegram的服务器无法直接访问它。我们需要一个内网穿透工具ngrok是最简单流行的选择。注册并安装Ngrok 前往ngrok官网注册免费账户下载对应你系统的客户端并按照指南进行认证通常是将authtoken添加到配置中。启动隧道 在一个新的终端窗口中运行ngrok http 8765命令执行后ngrok会分配一个随机的公共URL例如https://abcd-123-456.ngrok-free.app所有发往这个URL的请求都会被转发到你本机的http://localhost:8765。更新环境变量 复制ngrok提供的https://开头的Forwarding地址。修改telegram_bot/.env文件中的GEMINI_ENDPOINTGEMINI_ENDPOINThttps://abcd-123-456.ngrok-free.app/event重启服务 重启你的main.go机器人程序让它加载新的端点配置。现在无论你身在何处只要你的本地listen.js和ngrok隧道在运行Telegram消息就能通过这个公共URL抵达你的本地AI助手。重要提示 免费版ngrok的URL每次重启都会变化且隧道可能不稳定。对于长期使用建议考虑付费计划获得固定域名或者使用更稳定的内网穿透方案如云服务器反向代理、frp等。同时暴露服务到公网会引入安全风险务必设置好TARGET_CHAT_ID来限制访问。4.2 动态命令系统详解与扩展这个项目一个非常优雅的设计是它的动态命令注册系统。Telegram机器人界面中的/listen系列命令如/listen:start,/listen:status并非硬编码在Go程序里而是通过读取配置文件动态生成的。工作原理main.go在启动时会扫描~/.gemini/commands/listen/目录也就是我们之前复制过去的目录。它会寻找所有以.toml结尾的文件。每个.toml文件对应一个Telegram命令。文件名决定了命令名文件内容中的description字段决定了命令在Telegram中的描述。如何添加一个自定义命令假设你想添加一个命令用来让机器人告诉你当前服务器的负载情况。在~/.gemini/commands/listen/目录下创建一个新文件命名为system_status.toml。注意命令名会由文件名自动生成规则是/listen:filename。编辑这个文件内容如下# ~/.gemini/commands/listen/system_status.toml description 检查当前系统的负载和运行状态重启main.go机器人程序。现在在你的Telegram机器人中输入/你应该能看到/listen:system_status这个新命令出现在建议列表里并且描述是“检查当前系统的负载和运行状态”。那么命令背后的逻辑在哪里关键在于这些/listen:命令本身并不直接定义复杂的操作。它们更像是“触发器”或“快捷方式”。当你点击/listen:system_status时机器人实际上会向listen.js发送一个预定义的、与命令名相关的消息。listen.js收到消息后会将其作为普通提示词传递给Gemini CLI。因此要让/listen:system_status真正工作你需要“教会”Gemini CLI理解这个快捷方式。这通常通过以下两种方式实现依赖Gemini CLI的上下文理解 如果你的Gemini CLI已经通过历史对话或系统提示词system prompt知道“当用户提到‘系统状态’时就运行uptime; free -h; df -h这些命令”那么它就能正确响应。在listen.js中做映射 更可控的方式是修改listen.js脚本在收到特定命令消息时将其映射为一段更精确的提示词。例如当消息是/listen:system_status时实际发送给Gemini CLI的提示词是“请执行命令查看当前系统负载、内存使用率和磁盘空间并以清晰格式返回。”这种设计将交互界面命令菜单和业务逻辑AI执行解耦使得扩展机器人功能变得非常灵活你只需要添加一个简单的配置文件并确保AI能理解对应的意图即可。5. 深度集成MCP服务器与生产环境考量项目的README最后提到了MCP集成这是一个非常强大的特性能极大扩展机器人的能力边界。5.1 MCP集成原理与价值MCPModel Context Protocol是一种协议它允许像Gemini CLI这样的AI模型客户端连接到各种“工具服务器”。这些服务器可以提供特定领域的知识和能力比如查询数据库、读取Git仓库信息、管理云资源等。当你的Gemini CLI配置了MCP服务器后它就具备了调用这些工具的能力。而gemini_cli_server项目的精妙之处在于这个集成对Telegram机器人是完全透明的。整个流程是这样的你在Telegram中说“帮我查一下最近三天Git仓库的提交记录。”消息经main.go转发给listen.js。listen.js调用gemini-cli --yolo “帮我查一下最近三天Git仓库的提交记录”。Gemini CLI在本地解析这个请求。它发现自己配置了一个“Git MCP服务器”。Gemini CLI通过MCP协议向这个Git服务器发起查询。Git MCP服务器执行git log --since3 days等真实命令将结果返回给Gemini CLI。Gemini CLI将格式化后的结果返回给listen.js。最终提交记录列表呈现在你的Telegram聊天中。这意味着任何Gemini CLI通过MCP能访问的工具现在都能通过你的Telegram机器人来调用。你可以构建一个无比强大的、通过自然语言操控的自动化中心。5.2 安全、稳定与生产化建议将这样一个能执行系统命令的AI助手暴露出去安全是头等大事。以下是一些进阶的加固和优化建议强制使用TARGET_CHAT_ID 这是最基本也是最重要的安全措施。在.env中设置此值确保只有你或你信任的聊天可以控制机器人。审查与过滤listen.js 仔细阅读listen.js的代码理解它如何调用Gemini CLI。考虑添加输入过滤逻辑例如禁止消息中出现某些危险命令关键词如rm -rf /、dd、格式化命令等或者对操作目标路径进行白名单限制。为Gemini CLI运行设置沙盒环境 不要用高权限用户如root运行listen.js和Gemini CLI。创建一个专用的、低权限的系统用户来运行这些服务并严格控制其可访问的文件和目录范围。使用更稳定的反向代理替代Ngrok 对于7x24小时运行的服务可以考虑在云服务器如AWS EC2、DigitalOcean Droplet上部署main.go和listen.js或者使用frp、bore等开源工具建立更稳定的隧道。云服务器通常有固定IP和域名更适合长期使用。实现日志与监控 为listen.js和main.go添加更详细的日志记录记录所有请求和响应注意避免记录敏感Token。可以将日志收集到journald或文件中并设置日志轮转。监控服务的进程状态确保崩溃后能自动重启可以使用systemd服务或supervisord。考虑认证层 在listen.js的HTTP端点前增加一层简单的认证例如要求请求头中包含一个预共享的密钥这可以在ngrok隧道被意外暴露时提供额外保护。部署这样一个项目就像赋予了一个数字助手以实体。从在本地终端与AI对话到通过手机在全球任何角落与它交互这种体验的升级是革命性的。它模糊了开发环境与日常通讯工具的界限让技术能力变得触手可及。当然能力越大责任越大在享受便利的同时务必构建好安全的围栏。