1. 项目概述Multi-CLI MCP一个让AI们“开会”的桥梁如果你同时在使用多个AI命令行工具比如Claude Code、Gemini CLI、Codex CLI或者OpenCode那你肯定遇到过这样的场景你在和Claude讨论一个复杂的代码重构方案突然想听听Gemini的意见于是你不得不手动切换到另一个终端窗口重新输入问题再把结果复制回来。这个过程不仅打断了你的思路也让跨模型协作变得异常繁琐。Multi-CLI MCP这个项目就是为了彻底解决这个痛点而生的。简单来说Multi-CLI MCP是一个基于Model Context ProtocolMCP的服务器。它的核心功能是充当一个“翻译官”和“调度员”让你正在对话的任何一个AI客户端都能直接调用其他已安装的AI CLI工具。想象一下你在Claude的对话窗口里直接输入“问问Gemini对这个算法有什么看法”Claude就能通过Multi-CLI把问题转交给Gemini并把答案带回来整个过程无缝衔接就像Claude自己多了一个“咨询同事”的能力。这个工具特别适合开发者、技术写作者、研究员等需要综合多方AI意见进行复杂问题分析和决策的深度用户。这个项目的巧妙之处在于它的“自举”和“自维护”特性。根据项目描述它本身就是由它所连接的这些AIClaude, Gemini, Codex, OpenCode协作编写和维护的。更酷的是它有一个自动化的CI流程每天都会检查各个AI CLI的最新模型列表一旦发现变化比如有新模型发布或旧模型下线就会自动发布新版本的Multi-CLI。这意味着你安装的工具几乎总是与最新的AI能力保持同步避免了手动更新的麻烦。接下来我将从一个实际使用者的角度带你深入拆解它的设计思路、安装配置的每一个细节、实际使用中的技巧以及如何排查那些你可能遇到的“坑”。2. 核心设计思路与架构解析2.1 为什么是MCP协议层的统一是关键Multi-CLI选择基于Model Context ProtocolMCP来构建这是一个非常关键且明智的设计决策。MCP本质上是一个开放协议旨在为AI应用程序和工具之间提供标准化的通信方式。你可以把它想象成AI世界的“USB协议”或者“HTTP协议”——它定义了一套通用的“插口”和“数据格式”让不同的AI客户端和工具能够互相识别和对话。在没有MCP之前每个AI CLI命令行界面都是一个信息孤岛。Claude Code有自己的一套内部机制来调用它的工具Gemini CLI有另一套它们之间互不兼容。如果你想自己写一个脚本让它们互相调用你需要分别研究每个CLI的SDK、API格式和输出解析逻辑工作量巨大且脆弱。MCP的出现为所有这些工具提供了一个统一的“插座”。Multi-CLI MCP服务器就扮演了一个“多功能插排”的角色它一端通过标准的MCP接口连接到你的主AI客户端比如Claude Code另一端则通过执行系统命令的方式去调用其他AI CLI如geminicodex命令。这种架构带来了几个核心优势对客户端透明对于Claude Code这样的AI客户端来说Multi-CLI看起来就像一个普通的MCP工具服务器。它不需要知道背后调用的到底是Gemini还是Codex它只需要按照MCP协议发送请求和接收响应。扩展性极强只要一个新的AI CLI支持命令行调用理论上就可以被集成到Multi-CLI中。服务器只需要增加一个对应的“适配器”将其命令行参数和输出格式映射成MCP工具的定义即可。避免了“自我调用”的悖论Multi-CLI在设计上有一个聪明的逻辑它会自动隐藏调用者自身的工具。例如当Claude Code连接上Multi-CLI时服务器会检测到系统安装了claude命令但不会向Claude Code提供Ask-Claude工具。这样就防止了AI陷入“自己问自己”的无意义循环确保了工具列表的清晰和有用。2.2 双模式运行Stdio与HTTP服务的权衡Multi-CLI支持两种运行模式这是为了适配不同AI客户端的连接需求和稳定性考量。Stdio标准输入/输出模式这是MCP最经典、最轻量的连接方式。AI客户端如Gemini CLI, Codex CLI会作为一个父进程启动Multi-CLI通过npx作为子进程。两者通过进程间的标准输入、标准输出和标准错误流进行JSON格式的MCP消息通信。这种模式的优点是部署简单几乎无需配置npx命令会自动获取最新版本。但缺点也很明显连接生命周期与客户端进程绑定。如果AI客户端崩溃或主动断开连接Multi-CLI子进程也会被终止。对于某些客户端频繁的工具调用可能导致进程管理开销。HTTP服务模式这是为Claude Code等客户端推荐的更稳定的模式。在这种模式下Multi-CLI以一个独立的、常驻后台的HTTP服务器运行。它监听本机的127.0.0.1环回地址确保外部无法访问并提供/mcp端点供客户端连接。Claude Code则通过HTTP协议与这个常驻服务通信。提示为什么Claude Code推荐HTTP模式根据社区经验Claude Code在处理长时间运行的Stdio子进程时有时会因为资源管理策略导致非预期的断开连接。HTTP服务模式将Multi-CLI作为独立的系统服务运行与Claude Code进程解耦大大提升了连接的可靠性和持久性。服务模式还带来了日志集中管理、连接状态监控等运维上的便利。这两种模式体现了工程上的权衡Stdio追求简单和轻量适合工具型CLIHTTP服务追求稳定和持久适合IDE集成或桌面应用类客户端。Multi-CLI同时支持两者让用户可以根据自己的主要使用场景和客户端特性做出最佳选择。2.3 自动化与自维护项目可持续性的基石这个项目最让我欣赏的一点是它的“自维护”设计。很多开源工具在发布初期功能光鲜但随着依赖的底层API或CLI更新很快就因为无人维护而变得不可用。Multi-CLI通过一套自动化流程从根本上试图解决这个问题。其核心机制是一个定时例如每天运行的CI/CD流水线。这个流水线会做以下几件事主动探测在一个干净的环境中安装各个AI CLIanthropic-ai/claude-code,google/gemini-cli等的最新稳定版。获取模型列表运行类似claude models list、gemini models list这样的命令获取每个CLI当前支持的所有模型名称和标识符。差异对比将获取到的最新模型列表与项目代码仓库中存储的模型列表进行对比diff。自动发布如果发现任何差异新增了模型或移除了旧模型CI流水线会自动修改项目内的模型定义文件提交代码并触发一个新的版本发布例如从1.2.3升级到1.2.4。这意味着只要上游的AI提供商发布了新模型通常在24小时内Multi-CLI就会自动更新以支持它。同样如果某个旧模型被弃用Multi-CLI也会自动将其从工具列表中移除避免用户调用失效的工具。这种设计将维护成本从人类开发者转移到了自动化脚本上极大地保证了项目的长期活力也让用户能始终用上最新的AI能力。3. 详细安装与配置指南虽然项目提供了一键安装脚本但理解手动安装的每一步对于排查问题和进行高级配置至关重要。下面我将分客户端详细拆解并补充一些官方文档中未明确提及的细节和注意事项。3.1 环境准备与前置检查在开始安装任何客户端配置之前必须确保基础环境就绪。Node.js版本Multi-CLI要求Node.js版本大于等于20。我建议使用nvmNode Version Manager来管理Node.js版本这样可以轻松切换和测试。# 检查当前Node.js版本 node --version # 如果低于20使用nvm安装并切换需先安装nvm nvm install 20 nvm use 20至少安装一个AI CLIMulti-CLI本身只是一个桥梁它需要实际的“乘客”AI CLI才能发挥作用。你必须至少安装一个项目支持的CLI。虽然安装一个也能运行但只有安装两个或以上时跨模型调用的价值才能体现。# 示例安装Claude Code和Gemini CLI npm install -g anthropic-ai/claude-code npm install -g google/gemini-cli # 安装后验证命令是否在PATH中 which claude which gemini注意这些AI CLI的安装通常需要你拥有相应的API密钥并完成初始配置如claude auth login。请确保你在安装Multi-CLI之前已经能够独立使用这些CLI工具。Multi-CLI只是调用它们不负责认证过程。3.2 为Claude Code配置推荐HTTP服务模式对于Claude Code用户我强烈推荐使用HTTP服务模式以获得最稳定的体验。以下是详细步骤和原理说明。第一步全局安装Multi-CLInpm install -g osanoai/multicli全局安装-g是关键。HTTP服务模式需要一个持久化的、可执行文件路径固定的Multi-CLI实例。使用npx临时运行的方式不适合作为系统服务安装因为服务管理器需要知道确切的二进制文件位置。第二步安装并配置后台服务multicli service install --configure-claude这个命令做了很多事情我们拆开看创建服务单元根据你的操作系统它会创建对应的服务配置文件。macOS在~/Library/LaunchAgents/下创建一个.plist文件这是一个launchd服务。Linux (systemd)在~/.config/systemd/user/下创建一个.service文件。Windows创建一个在用户登录时启动的定时任务Scheduled Task。生成环境文件服务会在一个特定的目录如~/.multicli/service/生成一个环境配置文件.env。这个文件非常重要它包含了服务运行所需的环境变量比如PATH。如果你的AI CLI安装在了非标准路径或者需要特定的API密钥环境变量你需要手动编辑这个文件。配置Claude Code--configure-claude参数会自动修改Claude Code的用户级MCP服务器配置将其指向本地运行的HTTP服务http://127.0.0.1:37420并设置一个随机的认证令牌Bearer Token。这个令牌会同时写入服务环境配置和Claude的配置中确保通信安全。启动服务尝试启动服务并设置为开机自启。第三步验证服务状态安装后使用以下命令进行健康检查multicli service status # 查看服务运行状态 multicli service doctor # 运行诊断检查CLI是否可被检测到、端口是否被占用等 multicli service logs # 查看服务日志对于排查问题非常有用如果doctor命令报告“No usable AI CLIs detected”请检查你的AI CLI是否已正确安装并位于PATH中必要时可以重启终端或注销/登录用户会话来刷新环境变量。关于Stdio模式的补充 如果你因为某些原因坚持使用Stdio模式命令如下claude mcp add --scope user Multi-CLI -- npx -y osanoai/multiclilatest但请做好心理准备你可能会遇到Claude Code在长时间对话后与MCP服务器断开连接的情况。此时你需要手动重启Claude Code或重新添加工具。3.3 为Gemini CLI、Codex CLI、OpenCode配置Stdio模式对于这些以命令行交互为主的工具使用轻量的Stdio模式是更合适的选择。配置过程大同小异。Gemini CLI:gemini mcp add --scope user Multi-CLI npx -y osanoai/multiclilatest这条命令会在Gemini CLI的用户配置中添加一个名为“Multi-CLI”的MCP服务器使用npx实时拉取最新版本运行。Codex CLI:codex mcp add Multi-CLI -- npx -y osanoai/multiclilatest注意Codex CLI的命令参数格式略有不同。OpenCode:OpenCode的mcp add命令是交互式的因此直接修改其JSON配置文件更可靠。找到配置文件~/.config/opencode/opencode.jsonLinux/macOS或%APPDATA%\opencode\opencode.jsonWindows。在配置文件中找到或创建mcp对象并添加如下条目{ mcp: { Multi-CLI: { type: local, command: [npx, -y, osanoai/multiclilatest] } // ... 其他已有的MCP服务器配置 } }保存文件并重启OpenCode。配置后的验证为这些CLI配置完成后启动相应的CLI并尝试列出可用的工具。例如在Gemini CLI中你可能会有一个命令如/tools或通过界面查看应该能看到来自Multi-CLI的Ask-Claude、Ask-Codex等工具但不会看到Ask-Gemini。3.4 一键安装脚本解析对于macOS和Linux用户项目提供了一个便捷的一行安装脚本curl -fsSL https://raw.githubusercontent.com/osanoai/multicli/main/install.sh | bash这个脚本本质上是一个自动化流程它做了以下几件事环境检查检查Node.js版本和已安装的AI CLI。安装Multi-CLI通过npm全局安装osanoai/multicli。智能配置如果检测到Claude Code它会自动执行multicli service install --configure-claude为其设置HTTP服务。对于检测到的其他CLIGemini, Codex, OpenCode它会尝试使用各自的mcp add命令添加Stdio模式的配置。结果报告最后输出一个安装总结告诉你为哪些客户端配置了Multi-CLI。实操心得虽然一键脚本很方便但我建议新手先尝试手动为1-2个客户端配置以理解其背后的原理。当你在多个机器上部署或需要定制化时手动配置的知识会非常有用。另外脚本可能会修改你的配置文件如果你有高度定制化的MCP设置建议提前备份相关配置文件如Claude的claude_desktop_config.json。4. 工具详解与高级使用技巧安装配置成功后你的AI客户端就获得了一套新的“超能力”。我们来深入看看这些工具具体怎么用以及如何用得更好。4.1 工具列表与功能解析Multi-CLI会根据检测到的已安装CLI动态提供以下四类工具再次强调它会隐藏调用者自身的工具工具类别工具名称核心功能与使用场景模型列表List-AI-Models获取目标AI所有可用模型的列表及其简要描述如上下文长度、特长。使用场景在发起正式询问前先了解对方有哪些“专家”可供选择。例如List-Gemini-Models可以帮你决定是使用擅长代码的gemini-2.0-flash还是更通用的gemini-2.0-pro。核心问答Ask-AI向目标AI提出一个问题或下达一个任务。这是最常用的工具。输入是一个自然语言提示词prompt输出是目标AI的完整回答。使用场景任何需要跨模型咨询的场景如代码评审、方案对比、创意发散、错误诊断等。分块获取Fetch-Chunk这是一个特殊工具主要用于处理Gemini CLI可能返回的超长、分块chunked响应。大多数情况下Ask-Gemini会处理妥当但在极端情况下可能需要此工具手动获取后续内容。普通用户较少直接使用。帮助信息AI-Help获取目标AI CLI的内置帮助信息。这相当于在终端里运行gemini --help或claude --help。使用场景当你忘记某个CLI的具体命令语法或参数时可以直接让当前AI帮你查询。关于“任务感知”Task-Aware工具项目提到Ask-*工具是“任务感知”的。这是MCP的一个高级特性。对于支持MCP Tasks的客户端一个耗时的Ask-*请求可以被包装成一个后台任务客户端可以轮询任务状态而不会阻塞主对话线程。对于不支持Tasks的旧客户端这些工具则退化为普通的同步调用。这对用户是透明的你只需要正常使用Ask-*工具即可。4.2 高效使用模式与提示词技巧仅仅知道有这些工具还不够关键在于如何将它们融入你的工作流发挥“112”的效果。模式一专家会诊当你遇到一个棘手问题时可以同时召集多位“AI专家”进行会诊。提示词示例对Claude说“我正在优化一段Python数据处理的性能瓶颈。这是当前的代码片段[粘贴代码]。请分别咨询Gemini和Codex让它们从代码风格、算法效率和潜在bug的角度给出评审意见并汇总成一个对比报告给我。”操作解析Claude会依次调用Ask-Gemini和Ask-Codex将你的问题和代码传递给它们。然后Claude会收到两份独立的回复并基于你的指令进行汇总、对比和分析最终给你一个综合了多方视角的答案。这比你自己手动操作三次要高效得多。模式二接力创作利用不同AI的专长进行内容创作的流水线作业。场景撰写一篇技术博客。先让Claude擅长结构化思考和长文本生成一个详细的大纲和核心论点。然后让Gemini可能在代码示例生成上更强为大纲中的技术点生成准确的代码片段。最后让Codex专注于代码对所有生成的代码进行一轮检查和优化。提示词技巧在每次调用Ask-*工具时提供清晰的上下文。例如让Gemini生成代码时可以加上“根据以下Claude生成的文章大纲第二部分‘性能优化’的主题生成一个演示缓存机制的Python代码示例。”模式三交叉验证与纠偏当你不确定某个AI给出的答案是否准确时可以立即让另一个AI进行验证。提示词示例“我刚从Codex那里得到一个关于使用asyncio处理网络超时的建议[粘贴建议]。请让Gemini评估一下这个建议的可靠性和是否存在更好的替代方案”注意事项AI也会“犯错”或给出有争议的答案。交叉验证不是为了寻找“唯一正确”答案而是为了让你获得更全面的信息从而做出更明智的判断。有时两个AI会给出截然不同的建议这本身就是一个有价值的信号提示你需要深入查阅官方文档或人类知识。模式四工具链自动化你可以将Multi-CLI集成到你的脚本或自动化流程中。虽然Multi-CLI本身是一个MCP服务器需要与交互式AI客户端配合但你可以构思这样的场景一个自动化脚本利用Claude Code的API如果提供结合Multi-CLI定期让多个AI分析日志、生成报告等。这需要更深入的集成开发。4.3 环境变量与性能调优Multi-CLI提供了丰富的环境变量让你可以精细控制其行为。这些变量主要在两种情况下使用调试与排查问题通过设置MULTICLI_LOG_LEVELdebug来获取最详细的日志。调整超时和资源根据你的网络环境和任务复杂度调整超时时间。以下是一些关键的环境变量及其应用场景环境变量默认值说明与调优建议MULTICLI_ASK_TIMEOUT_MS未设置依赖子进程控制Ask-*工具的最长等待时间。如果经常遇到超时错误尤其是询问复杂问题时可以适当增加这个值例如120000表示2分钟。MULTICLI_LOG_LEVELdebug(文件日志)控制输出到日志文件的详细程度。info级别通常足够debug会记录完整的请求和响应体有助于复现问题但日志文件会增长很快。MULTICLI_STDERR_LOG_LEVELerror控制输出到标准错误流通常是你终端的日志级别。保持error可以在运行时保持界面整洁只在出问题时看到信息。MULTICLI_HTTP_SESSION_IDLE_MS未设置对于HTTP服务模式设置会话空闲多久后关闭。对于长期不关机的机器设置一个合理的值如36000001小时可以释放资源。MULTICLI_KILL_GRACE_MS未设置在强制终止一个CLI子进程前等待的毫秒数。如果某些CLI清理较慢可以适当调大。如何设置环境变量对于Stdio模式在启动Multi-CLI的命令前设置。但这通常由AI客户端控制不易修改。更常见的是通过系统环境变量全局设置。对于HTTP服务模式这是最主要的方式。编辑服务生成的环境文件如~/.multicli/service/.env在文件中添加你需要的变量例如MULTICLI_ASK_TIMEOUT_MS180000 MULTICLI_LOG_LEVELinfo保存后重启Multi-CLI服务使其生效multicli service restart5. 故障排查与常见问题实录即使按照指南操作你也可能会遇到一些问题。下面是我在部署和使用过程中遇到的一些典型情况及其解决方案。5.1 安装与连接类问题问题1运行multicli service install后multicli service doctor报告“No usable AI CLIs detected”。排查思路确认CLI已安装在终端直接运行claude --version、gemini --version等看命令是否有效。检查PATH服务运行在独立的用户环境中可能无法继承你终端里的完整PATH。使用multicli service logs查看启动日志看是否有“command not found”之类的错误。编辑服务环境文件找到~/.multicli/service/.env文件手动添加AI CLI可执行文件所在的目录到PATH变量中。例如如果你用nvm管理NodeCLI可能是全局安装的路径类似/Users/yourname/.nvm/versions/node/v20.x.x/bin。将这一行加入.env文件PATH/usr/local/bin:/usr/bin:/bin:/Users/yourname/.nvm/versions/node/v20.x.x/bin保存后运行multicli service restart。根本原因系统服务如launchd或systemd --user在启动时加载的环境变量与交互式Shell不同特别是当AI CLI通过非系统包管理器如nvm、conda安装时其路径不会被自动包含。问题2Claude Code连接不上Multi-CLI HTTP服务提示“Connection refused”或“Authentication failed”。排查步骤检查服务状态multicli service status确保服务是running状态。检查端口占用multicli service doctor通常会检查端口37420是否被占用。你也可以手动检查lsof -i :37420(macOS/Linux)。验证配置查看Claude Code的MCP配置。对于HTTP服务模式配置应该指向http://127.0.0.1:37420并包含一个authToken。这个token必须与~/.multicli/service/.env文件中的MULTICLI_HTTP_AUTH_TOKEN值一致。如果怀疑不一致可以运行multicli service refresh --configure-claude来重新生成和同步token。查看防火墙虽然服务只绑定127.0.0.1但极少数情况下本地防火墙规则可能会阻止回环地址的通信。可以临时禁用防火墙测试。实操心得99%的HTTP连接问题都与token不匹配或服务未启动有关。multicli service refresh --configure-claude是修复此类问题的“万能钥匙”。问题3工具调用成功但返回结果非常慢甚至超时。可能原因与解决网络问题Ask-*工具需要调用本地的AI CLI这些CLI会去访问对应的云API。慢可能是你的网络或API服务本身慢。可以先用对应的CLI直接在终端执行一个简单命令测试速度。模型负载如果你请求的是如claude-3-opus或gemini-2.0-pro等大型、热门模型API响应时间本身可能较长。调整超时如前所述在服务环境文件中增加MULTICLI_ASK_TIMEOUT_MS变量并设置一个更大的值例如300000即5分钟。提示词过长或复杂过长的上下文或极其复杂的任务会导致AI处理时间变长。尝试将问题拆解分步询问。5.2 使用与功能类问题问题4在Claude Code里我看不到任何Multi-CLI提供的工具。排查步骤确认连接在Claude Code的设置或MCP服务器列表中查看Multi-CLI的状态是否为“已连接”或“可用”。检查检测结果运行multicli service doctor确认它至少检测到了另一个AI CLI不是Claude自己。如果只检测到ClaudeMulti-CLI不会提供任何工具避免自我调用。重启客户端有时Claude Code的UI需要重启才能正确加载新的或更新的工具列表。查看日志multicli service logs中可能会有工具注册失败的错误信息。问题5调用Ask-Gemini时返回的结果不完整似乎被截断了。原因这可能是因为Gemini CLI对于超长输出使用了分块chunked响应机制而Multi-CLI的默认工具处理逻辑可能没有完整地拼接所有分块。解决方案首先尝试在提问时要求Gemini“请用更简洁的语言回答”或“分点列出”从源头控制输出长度。如果问题依然存在这可能是一个潜在的兼容性问题。查看multicli service logs的debug日志看是否有关于分块的记录。你也可以在项目中提一个Issue因为Fetch-Chunk工具可能就是为处理这种情况设计的但其自动调用逻辑可能需要优化。问题6升级AI CLI如npm update -g google/gemini-cli后Multi-CLI似乎没有感知到新模型。解释Multi-CLI的模型列表更新依赖于其自身的自动化发布流程而不是实时读取你本地CLI的输出。你本地CLI升级后只是具备了调用新模型的能力但Multi-CLI工具列表中“有哪些模型可选”这个信息需要等待Multi-CLI项目自身的CI检测到上游变化并发布新版本后你更新Multi-CLI本身才能获得。行动你可以手动更新Multi-CLI来获取可能已发布的新版本npm update -g osanoai/multicli。然后重启Multi-CLI服务如果使用HTTP模式。即使模型列表暂时未更新只要底层CLI支持你仍然可以通过在提示词中指定模型名称来尝试调用新模型但这取决于Ask-*工具的实现是否允许传递模型参数。5.3 服务管理命令速查表对于使用HTTP服务模式的用户以下命令是日常维护中最常用的命令功能使用场景multicli service status查看服务运行状态运行中/停止/错误。快速检查服务是否正常。multicli service start启动服务。安装后首次启动或手动停止后需要启动。multicli service stop停止服务。需要临时停止Multi-CLI或进行维护前。multicli service restart重启服务。修改了环境变量.env文件或配置后使更改生效。multicli service logs查看服务的实时日志。排查任何问题的首要步骤查看错误信息和详细过程。multicli service doctor运行诊断检查。检查CLI可执行性、端口占用、配置完整性等。multicli service refresh刷新服务配置。重新生成服务文件和环境变量常用于修复配置。multicli service uninstall卸载服务。彻底移除Multi-CLI的后台服务。我个人习惯在每次修改.env文件后都执行一次multicli service restart。在遇到任何连接或工具调用问题时第一个动作就是打开两个终端一个执行multicli service logs -f-f表示跟随输出实时查看日志另一个去执行触发问题的操作这样能最直观地定位问题根源。