1. 项目概述Claude Code 订阅的远程访问桥梁如果你和我一样订阅了 Claude Code 的 MAX 或 PRO 套餐每个月花着 100 到 200 美元却发现自己被“绑定”在了安装 Claude CLI 的那台主力电脑上那这个项目绝对值得你花时间研究。claude-bridge-mcp本质上是一个“桥梁”服务器它把你的本地 Claude Code 命令行工具CLI的能力通过 HTTP 和 Server-Sent Events 协议暴露出来。这样一来任何支持 MCP 协议的客户端——无论是另一台电脑上的 OpenClaw 智能体、Claude Desktop 应用还是你自己写的自动化脚本——都能远程调用你那昂贵的 Claude Code 订阅执行代码生成、文件操作、Git 状态查询等一系列任务。简单来说它解决了“算力订阅与使用场景不匹配”的核心痛点。我订阅 Claude Code PRO 是为了获得顶级的代码生成和推理能力但我并不总在主力机前工作。有时我在笔记本上写文档有时在云服务器上调试有时甚至想用平板电脑发起一个复杂的重构请求。claude-bridge-mcp让我能在任何设备、任何地点通过网络安全地“借用”主力机上 Claude Code 的全部能力相当于把我的订阅从一个本地许可证变成了一个可远程调用的私有 API 服务。这对于有多设备工作流、或需要在隔离环境如测试服务器中使用 AI 编码助手的开发者来说价值巨大。2. 核心原理与架构设计解析2.1 MCP 协议AI 工具交互的“通用语”要理解这个桥接器首先得弄懂 MCP。Model Context Protocol 是由 Anthropic 牵头推出的一种开放标准旨在为 AI 模型如 Claude和各种工具、数据源之间建立一套标准化的通信方式。你可以把它想象成 AI 世界的 USB 协议或者 gRPC。在 MCP 框架下工具比如一个数据库、一个文件系统、或者这里的 Claude CLI被封装成“服务器”而 AI 客户端如 Claude Desktop通过标准的 JSON-RPC over HTTP/SSE 来调用这些工具。claude-bridge-mcp扮演的角色正是一个 MCP 服务器。它没有重新发明轮子去模拟 Claude Code 的功能而是选择了一个更优雅、更稳定的方案作为本地claudeCLI 命令的“包装器”和“转发器”。当远程的 MCP 客户端例如 OpenClaw通过/sse端点建立连接后发起的每一个工具调用请求如claude_execute都会被桥接器接收然后桥接器在本地操作系统上以子进程的形式启动真正的claude命令并将客户端的输入任务描述作为标准输入stdin传递给这个进程。2.2 工作流与数据流转剖析整个数据流转路径是理解其稳定性的关键。假设你在远程的 OpenClaw 中要求“为当前目录的app.js文件添加错误处理逻辑”请求发起OpenClaw 智能体通过 MCP 协议向http://你的主力机IP:3100/messages发送一个 JSON-RPC 请求调用claude_execute工具并附上任务描述。桥接器接收与排队claude-bridge-mcp服务器接收到请求。它首先会进行一系列安全检查IP白名单、令牌验证、目录权限。然后请求被放入一个 FIFO先进先出执行队列。这是为了防止多个并发请求压垮系统你可以通过BRIDGE_MAX_CONCURRENT环境变量控制同时运行的 Claude CLI 进程数默认2个。本地 CLI 执行一旦队列轮到该请求桥接器会在后台启动一个claude子进程。它会将当前工作目录切换到允许的目录之一并把任务描述通过 stdin 管道发送给 Claude CLI。此时Claude CLI 开始运行它会像在终端里一样读取文件、思考、并可能执行写文件或运行命令的操作。流式输出与返回Claude CLI 的执行输出包括思考过程、代码块、命令执行结果是实时流式产生的。桥接器会捕获这些 stdout 和 stderr 流并通过之前建立的 SSE 连接将这些数据块实时地、逐条地推送回远程的 OpenClaw 客户端。客户端呈现OpenClaw 接收到这些流式数据后便能以几乎实时的方式在界面上展示 Claude 的思考过程和生成结果体验与直接使用本地 Claude CLI 无异。这种架构的优势在于“职责分离”。桥接器只负责网络通信、安全、调度和协议转换最核心、最复杂的 AI 推理和代码执行工作完全交由官方维护、稳定可靠的 Claude CLI 来完成。这极大地降低了桥接器本身的复杂度和出错概率。2.3 为什么选择 HTTP SSE 而非 WebSocket项目采用了 HTTP 长轮询升级的 Server-Sent Events 作为数据传输主力而非更常见的 WebSocket这是一个值得深思的设计选择。SSE 是一种基于 HTTP 的单向服务器推送技术。对于 MCP 这种典型的“客户端请求-服务器流式响应”模型SSE 非常契合。简单性SSE 协议本身比 WebSocket 更简单客户端使用标准的 EventSource API 即可连接服务器端实现也直观。HTTP 友好SSE 基于 HTTP能天然兼容现有的 HTTP 基础设施如负载均衡器、代理服务器Nginx/Apache和监控工具配置 CORS 等策略也更统一。自动重连EventSource 内置了自动重连机制在网络不稳定时能提供更好的鲁棒性。单向流的高效性在 MCP 交互中虽然请求是双向的客户端发请求服务器回响应但响应往往是长时间的、服务器向客户端的流式数据推送。SSE 专为这种场景优化。对于客户端的请求完全可以通过另一个独立的 HTTP POST 端点如/messages来处理实现请求/响应的分离。相比之下WebSocket 是全双工的能力更强但也更重。在主要数据流方向明确且以服务器推送为主的场景下SSE 是更轻量、更专注的选择。这个设计体现了开发者对协议特性的精准把握。3. 环境准备与详细部署指南3.1 基础环境搭建部署claude-bridge-mcp前需要确保主力机运行桥接器的机器满足以下条件我将以 Ubuntu 22.04 和 macOS 为例进行说明Node.js 18这是运行桥接器的基石。Ubuntu建议使用 NodeSource 的 PPA 安装最新 LTS 版本。curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node --version # 验证版本 18macOS使用 Homebrew 是最佳选择。brew install node node --versionClaude Code CLI 安装与认证这是桥接器能力的源泉。访问 Anthropic 官方文档安装 CLI。通常是一条curl或npm命令。安装后在终端运行claude auth按照提示完成登录和授权。务必确保在终端中直接输入claude命令能正常启动并关联到你付费的 MAX/PRO 订阅账号。你可以用一个简单命令测试claude “hello”看是否能得到响应。网络环境考量由于涉及远程访问你需要考虑如何让远程机器能访问到你主力机的 3100 端口。同一局域网最简单的情况直接使用主力机的局域网 IP 即可。跨网络访问推荐这是核心场景。强烈建议使用 Tailscale或类似的零信任组网工具。它能在你的所有设备间建立一个加密的虚拟局域网无需复杂的端口转发和公网 IP安全性极高。安装 Tailscale 并在主力机和远程机器上登录同一账号它们就会获得一个固定的 Tailscale IP如100.xx.yy.zz可以像在局域网内一样互访。3.2 桥接器安装与启动安装过程极其简单体现了 Node.js 生态的优势。# 方法一使用 npx 直接运行无需永久安装 npx claude-bridge-mcp # 默认会在 http://0.0.0.0:3100 启动 # 方法二全局安装便于随时启动 npm install -g claude-bridge-mcp claude-bridge-mcp启动后你应该在终端看到服务器启动的日志。打开另一个终端用curl http://localhost:3100/health测试如果返回{status:ok}说明服务运行正常。注意直接这样启动使用的是默认配置没有任何安全限制仅适合在完全可信的本地网络或用于初步测试。切勿将默认配置的服务暴露在公网3.3 生产级安全配置安全是远程服务的生命线。claude-bridge-mcp提供了多层防护必须逐一配置。首先在项目目录或你打算运行服务的目录创建.env文件。你可以复制示例文件cp .env.example .env。然后编辑.env文件关键配置如下# .env 配置文件示例 BRIDGE_HOST0.0.0.0 BRIDGE_PORT3100 # 1. IP 白名单这是第一道防火墙 # 假设你的远程机器 Tailscale IP 是 100.123.456.78主力机自身是 192.168.1.100 BRIDGE_ALLOWED_IPS100.123.456.78,192.168.1.100,127.0.0.1 # 注意127.0.0.1localhost通常隐式允许但显式写出更清晰。 # 2. API 令牌第二道身份验证 # 生成一个强随机令牌例如使用 openssl rand -hex 32 BRIDGE_API_TOKEN你的强随机令牌字符串 # 3. 目录白名单限制 Claude CLI 可访问的文件系统范围 # 只允许访问 /home/yourname/projects 和 /tmp 目录 BRIDGE_ALLOWED_DIRS/home/yourname/projects,/tmp # 4. 执行控制防止资源滥用 BRIDGE_TIMEOUT300000 # 单次任务超时时间5分钟 BRIDGE_MAX_CONCURRENT2 # 最大并发执行数根据主力机性能调整 BRIDGE_QUEUE_TIMEOUT60000 # 队列等待超时1分钟配置解读与实操心得BRIDGE_ALLOWED_IPS如果你使用 Tailscale务必在这里填写远程设备的 Tailscale IP。你可以通过tailscale ip -4在远程设备上查看。不要留空留空意味着允许任何 IP 访问。BRIDGE_API_TOKEN这个令牌用于 HTTP Bearer Token 认证。在客户端配置时需要以Authorization: Bearer token的格式在请求头中携带。这是防止 IP 白名单被意外突破后的重要防线。BRIDGE_ALLOWED_DIRS这是最关键的安全配置之一。Claude Code CLI 在被桥接器调用时其工作目录会被限制在此列表中的路径下。这意味着即使远程请求被恶意构造试图读取/etc/passwd或删除系统文件也会因为路径不在允许列表中而被桥接器拒绝。永远不要将根目录/加入允许列表。执行队列BRIDGE_MAX_CONCURRENT默认是 2对于大多数个人使用场景足够了。如果你同时从多个客户端发起大量请求超过此数量的请求会排队。BRIDGE_QUEUE_TIMEOUT设置了排队的最长等待时间超时则返回错误避免请求无限期挂起。配置完成后通过claude-bridge-mcp命令启动服务它会自动读取同目录下的.env文件。4. 客户端连接与工具使用全解桥接器部署好后下一步就是让远程的 MCP 客户端连接上来。这里以最典型的两个客户端 OpenClaw 和 Claude Desktop 为例。4.1 配置 OpenClaw 客户端OpenClaw 是一个开源的、可高度定制的 AI 智能体平台它原生支持 MCP。假设你的 OpenClaw 运行在另一台 IP 为100.123.456.78的机器上。找到 OpenClaw 的配置文件通常位于~/.openclaw/openclaw.jsonLinux/macOS或%USERPROFILE%\.openclaw\openclaw.jsonWindows。在mcpServers部分添加claude-bridge的配置。这里的关键是使用mcp-remote这个特殊的“命令”来连接远程 SSE 端点。{ mcpServers: { claude-bridge: { command: npx, args: [ -y, mcp-remote, http://你的主力机IP:3100/sse, --header, Authorization: Bearer 你的BRIDGE_API_TOKEN ] } } }重要参数说明command: “npx”告诉 OpenClaw 使用 npx 来运行一个命令。args数组“-y”让 npx 在安装包时自动确认。“mcp-remote”这是一个专门用于连接远程 MCP SSE 服务器的工具包。npx 会自动下载并运行它。“http://...”你的claude-bridge-mcp服务器的/sse端点地址。将你的主力机IP替换为实际的 Tailscale IP 或局域网 IP。“--header”, “Authorization: Bearer ...”这是传递 API 令牌的方式。如果你的BRIDGE_API_TOKEN环境变量不为空则此项必须配置且令牌必须正确否则连接会被拒绝。保存配置文件并重启 OpenClaw 应用。在 OpenClaw 的日志或工具列表中你应该能看到claude-bridge服务器已连接并提供了claude_execute,claude_query等工具。4.2 配置 Claude Desktop 客户端Claude Desktop 是 Anthropic 官方的桌面应用同样支持 MCP。配置方式类似但配置文件路径不同。找到 Claude Desktop 的 MCP 配置文件。路径通常为macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑该 JSON 文件添加服务器配置。格式与 OpenClaw 几乎完全相同。{ mcpServers: { claude-bridge: { command: npx, args: [ -y, mcp-remote, http://100.123.456.78:3100/sse, --header, Authorization: Bearer 你的强令牌 ] } } }保存文件并完全重启 Claude Desktop 应用不是关闭聊天窗口而是退出整个应用再重新打开。重启后在聊天界面你应该能发现 Claude 模型可以使用新的工具了。4.3 四大核心工具实战详解连接成功后客户端无论是 OpenClaw 的智能体还是 Claude Desktop 中的 Claude 模型就可以调用桥接器暴露的四个工具了。理解每个工具的用途和差异能让你用得更加得心应手。claude_execute全能执行引擎这是最强大、最常用的工具。你给它一个自然语言描述的任务它会驱动本地的 Claude Code CLI 去思考并执行。这意味着 Claude 不仅可以生成代码还可以直接运行命令、读写文件、进行 Git 操作。典型用例“为当前目录下的server.py添加一个/healthAPI 端点并运行python server.py测试是否成功。”内部过程桥接器收到请求后会在允许的目录下启动claudeCLI并将任务描述传入。Claude 会分析现有代码生成新的代码然后自动执行python server.py等命令并将执行结果流式返回。这是一个具有实际执行能力的“智能体”操作。注意事项由于具有执行能力务必通过BRIDGE_ALLOWED_DIRS严格限制其操作范围避免对系统造成意外修改。claude_query只读分析专家这个工具用于向 Claude Code 提问但它是“只读”模式。Claude 会分析你指定的代码、文件或问题给出解释、建议或答案但不会执行任何写文件或运行命令的操作。典型用例“解释一下src/utils/目录下auth.js文件中validateToken函数的逻辑。” 或者 “我这段 Rust 代码为什么编译报错error[E0382]”优势速度通常比claude_execute快因为它不需要准备执行环境。适合快速的代码审查、逻辑理解和调试咨询。claude_read_file远程文件查看器这是一个简单的工具用于读取远程主力机上指定路径的文件内容。虽然claude_execute和claude_query在分析时也能读取文件但这个工具提供了更直接、更可控的文件访问方式。典型用例智能体需要查看一个配置文件如docker-compose.yml的内容来决定下一步操作。安全边界读取路径同样受BRIDGE_ALLOWED_DIRS限制并且会解析符号链接的真实路径realpath防止目录遍历攻击。claude_git_status版本控制状态感知这个工具会执行git status和git log等命令获取当前工作目录的 Git 仓库状态信息包括当前分支、暂存区/工作区的变更文件列表、以及最近的提交历史。典型用例在开始一项代码重构任务前让 AI 先了解当前的代码状态和最近的修改历史使它的建议更具上下文。依赖显然你允许访问的目录BRIDGE_ALLOWED_DIRS下需要是一个 Git 仓库。实操心得工具的选择策略在实际使用中我形成了这样的习惯当需要 AI不仅出主意还要动手干时用claude_execute。比如创建新文件、运行测试、安装依赖。当只需要 AI分析、解释或提供建议时用claude_query。这样更快且没有意外执行的风险。当工作流中需要 AI 主动获取特定文件内容时会用到claude_read_file。claude_git_status通常在开始一个复杂的、与现有代码库相关的任务前自动调用为 AI 提供项目上下文。5. 高级配置、监控与故障排查5.1 性能调优与稳定性配置默认配置适用于大多数场景但在高强度使用或特定环境下你可能需要调整。BRIDGE_MAX_CONCURRENT这个值决定了能同时处理几个 Claude CLI 进程。每个进程都会占用相当的内存和 CPU。如果你的主力机性能一般比如 8GB 内存的轻薄本保持默认值 2 是稳妥的。如果是在一台拥有 32GB 内存的 Mac Studio 或服务器上运行可以适当提高到 3 或 4以提升并行处理能力。不建议设置过高因为 Anthropic 的 API 本身可能有速率限制过多的并发也可能导致 CLI 响应变慢。BRIDGE_TIMEOUT默认 120 秒2分钟。对于绝大多数编码任务足够了。但如果你的任务是“分析整个大型代码库并生成重构报告”可能会超时。可以酌情增加到 3000005分钟或更长。但同时也要注意一个长时间运行的任务会占用一个并发槽位。BRIDGE_QUEUE_TIMEOUT默认 30 秒。如果所有并发槽位都被占用新请求会排队等待这个时长。如果超时客户端会收到一个队列超时错误。在网络延迟较高的环境下如果任务本身很短但排队请求多可以稍微增加这个值。5.2 监控与日志claude-bridge-mcp提供了一些内置的监控端点。/health最基本的健康检查。任何情况都可访问返回{“status”:”ok”}表示服务器进程存活。/metrics这是一个非常有用的端点返回 Prometheus 格式的指标数据。你可以用curl http://localhost:3100/metrics查看内容可能包括bridge_requests_total总请求数。bridge_requests_duration_seconds请求耗时分布。bridge_queue_size当前队列长度。bridge_concurrent_executions当前正在执行的 Claude 进程数。 这些数据可以集成到 Grafana 等监控系统中用于观察服务负载、发现异常如队列持续过长。日志服务器运行时的日志会输出到控制台。建议在生产环境中使用pm2、systemd或 Docker 来运行服务并将日志重定向到文件便于后期排查问题。日志中会记录连接、断开、工具调用、错误等信息。5.3 常见问题与排查实录在部署和使用过程中我遇到过一些典型问题以下是排查思路问题一客户端连接失败提示“连接被拒绝”或“超时”。排查步骤检查主力机服务是否运行在主力机上运行curl http://localhost:3100/health。如果不通说明桥接器没启动或启动失败。检查 Node.js 版本、Claude CLI 是否在 PATH 中。检查 IP 和端口确认客户端配置的 IP 地址和端口默认 3100完全正确。如果使用 Tailscale确保两端设备都显示为 “Online”。检查防火墙主力机的防火墙如ufw、Windows Defender 防火墙可能阻止了 3100 端口的入站连接。需要添加规则允许该端口或暂时关闭防火墙测试。检查 IP 白名单确认客户端的 IP 地址如果是 Tailscale用tailscale ip -4查看已经添加到BRIDGE_ALLOWED_IPS环境变量中并且没有拼写错误。问题二连接成功但调用工具时返回“认证失败”或“未授权”。排查步骤检查 API 令牌确认BRIDGE_API_TOKEN环境变量已在主力机设置并且客户端配置中Authorization: Bearer后面的令牌与之完全一致注意大小写和空格。检查目录权限调用claude_execute或claude_read_file时如果请求中隐含或指定的路径不在BRIDGE_ALLOWED_DIRS列表内会被拒绝。确保你尝试操作的项目目录已被添加。问题三工具调用成功但 Claude CLI 执行出错或没反应。排查步骤查看桥接器日志这是最重要的信息源。日志会显示它启动claude子进程的命令和参数以及子进程的退出码和错误输出。手动测试 Claude CLI在主力机上切换到BRIDGE_ALLOWED_DIRS中的目录手动运行claude命令执行一个简单任务如claude “list files here”看是否正常工作。这能排除 Claude CLI 本身安装或认证的问题。检查超时设置如果任务复杂可能超过了BRIDGE_TIMEOUT设置。尝试增加超时时间或在任务描述中让 Claude 分步骤执行。问题四性能缓慢响应延迟高。可能原因网络延迟如果客户端和主力机物理距离很远网络延迟会叠加在 AI 推理时间上。使用 Tailscale 等工具通常能提供优化路径。主力机资源不足检查主力机的 CPU 和内存使用情况。每个并发的 Claude CLI 进程都是资源消耗大户。确保有足够的空闲资源。队列阻塞通过/metrics端点查看bridge_queue_size。如果持续大于 0说明请求在排队可能需要减少并发请求频率或适当增加BRIDGE_MAX_CONCURRENT如果硬件允许。5.4 在云服务器或 Docker 中运行对于希望拥有一个“永远在线”的桥接服务的用户可以考虑将其部署在云服务器或 Docker 容器中。云服务器部署在 VPS如 AWS EC2、DigitalOcean Droplet上安装 Node.js、Claude CLI 并完成认证然后按照上述步骤配置和运行claude-bridge-mcp即可。安全警告在公网云服务器上运行时必须配置好BRIDGE_ALLOWED_IPS仅允许你的个人设备 IP和BRIDGE_API_TOKEN并且考虑使用云服务商的安全组/防火墙进一步限制 3100 端口的访问源。Docker 部署项目本身没有提供官方 Docker 镜像但可以自行构建。难点在于如何在容器内完成 Claude CLI 的交互式认证。一种方案是先在宿主机认证然后将 Claude 的配置文件通常位于~/.config/claude/挂载到容器内。Dockerfile 示例和运行命令需要根据你的认证方式调整这是一个相对进阶的用法。我个人更倾向于在本地主力机如台式机或始终开机的 Mac Mini上运行桥接器通过 Tailscale 访问。这样既利用了本地已认证的环境又无需在公网服务器上管理敏感的 AI 服务凭据安全性更高。