第二十一篇Bridge 远程会话系统Claude Code 如何实现安全的远程控制本文是《Claude Code 源码分析 100 篇》系列的第二十一篇。前一篇我们分析了 MCP 协议集成本篇深入 Bridge 系统——这是 Claude Code 实现远程控制、跨设备协作的核心模块。一、Bridge 系统解决了什么问题Claude Code 本质是一个本地 CLI 工具但在团队协作、远程开发、多设备场景下需要从另一台机器远程连接并控制它。Bridge 系统就是这个能力的技术实现你的电脑A控制端 ←→ Bridge协议 ←→ 电脑BClaude Code运行端Bridge 支持两种模式Headless 永久模式claude --bridge启动后持续在后台运行远程可随时连接按需启动模式远程命令触发才启动一个会话二、核心文件架构src/bridge/目录是整个系统的核心共约 7000 行代码bridgeMain.ts # 主入口runBridgeLoop、bridgeMain、runBridgeHeadless2999行 replBridge.ts # REPL 通信协议消息编解码、双工流2406行 remoteBridgeCore.ts # 远程桥接核心逻辑Worker注册、心跳、消息路由1008行 sessionRunner.ts # 会话生成器工作树隔离、Spawn模式550行 trustedDevice.ts # 信任设备认证Keychain存储、90天滚动Token131行 bridgeApi.ts # 与CCR v2 API通信JWT刷新、Worker注册 bridgeMessaging.ts # 消息处理入站/出站消息队列 peerSessions.ts # 对等会话管理 types.ts # 类型定义三、主循环 runBridgeLoopbridgeMain.ts的核心是runBridgeLoop函数141行开始它是一个长轮询主循环exportasyncfunctionrunBridgeLoop(bridgeConfig:BridgeConfig,opts:BridgeOpts,):Promisenever{// 1. 建立 WebSocket 或轮询连接// 2. 注册 Worker上报设备信息、Session ID// 3. 进入主循环poll → process → ackwhile(true){constactivityawaitpollActivity(pollInterval)if(activity.typeresult||activity.typeerror){// 任务结果写入stdout}elseif(activity.typetool_start){// 工具调用通过 REPL 发送给本地 Claude Code 执行}awaitackActivity(activity.id)}}关键设计Bridge 使用轮询而非 WebSocket因为更易穿透企业防火墙无需维护持久连接状态可以在任何网络条件下工作四、信任设备认证 Trusted DevicetrustedDevice.ts实现了零接触远程认证4.1 为什么需要信任设备远程连接如果只靠 JWT Token有两个问题Token 可能被盗用每次连接都需要重新登录Claude Code 的解决方案设备级别信任。首次登录时服务器颁发一个trustedDeviceToken90天滚动过期存储在本地 KeychainmacOS或等效安全存储。远程连接时携带这个 Token服务器验证设备历史无需重新登录。4.2 核心实现// 信任设备认证门控服务端分级部署constTRUSTED_DEVICE_GATEtengu_sessions_elevated_auth_enforcementexportfunctiongetTrustedDeviceToken():string|undefined{if(!isGateEnabled()){returnundefined// 功能未开启不发送Token}returnreadStoredToken()// 读取Keychain}// Token存储结构interfaceSecureStorageData{trustedDeviceToken?:stringjwt?:string// ...}两段式门控是安全发布的经典模式第一步CLI 端开始发送X-Trusted-Device-Token请求头服务器暂时忽略第二步服务器功能开启Token 正式生效这样可以先灰度 CLI再灰度服务端风险可控。4.3 注册时机注册发生在/login流程中enrollTrustedDevice原因是服务端限制了注册条件// 服务端要求account_session.created_at 10分钟// 所以注册必须在登录时完成不能延迟exportasyncfunctionenrollTrustedDevice():Promisevoid{awaitaxios.post(/auth/trusted_devices,{deviceId:getDeviceId(),hostname:hostname(),enrolledAt:Date.now(),})}五、会话生成器 SessionRunnersessions.ts控制 Claude Code 如何生成一个会话来执行任务exportasyncfunctioncreateSessionSpawner():PromiseSessionSpawner{return{spawn:async(opts:SessionSpawnOpts){if(opts.modeworktree){// 创建独立的Git worktree隔离环境constworktreePathawaitcreateAgentWorktree(opts.projectRoot)returnspawnClaudeInWorktree(worktreePath)}else{// 经典单会话模式returnspawnClassicSession(opts)}}}}Spawn 模式模式说明适用场景worktreeGit worktree 隔离避免污染主分支classic标准单会话快速任务resume恢复已有会话断点续传六、REPL 桥接通信协议replBridge.ts定义了 Bridge 与本地 Claude Code 实例之间的通信协议。消息通过stdin/stdout传递// 消息类型typeBridgeMessage|{type:tool_call;id:string;tool:string;args:unknown}|{type:tool_result;id:string;result:unknown}|{type:output;stream:stdout|stderr;data:string}|{type:complete;exitCode:number}Bridge 将远程的tool_call转换为本地 Claude Code 可执行的命令写入 REPL stdin结果通过 stdout 读回。七、安全设计总结Bridge 系统的安全模型分层┌─────────────────────────────────────────┐ │ Layer 1: 传输安全 │ │ HTTPS/TLS 加密所有API通信 │ ├─────────────────────────────────────────┤ │ Layer 2: 认证 │ │ JWT Token Trusted Device Token 双因子 │ ├─────────────────────────────────────────┤ │ Layer 3: 授权 │ │ CCR v2 SecurityTierELEVATED │ │ GrowthBook 功能门控分级发布 │ ├─────────────────────────────────────────┤ │ Layer 4: 隔离 │ │ Git worktree 任务隔离 │ └─────────────────────────────────────────┘八、总结Bridge 系统是 Claude Code 的远程控制中心它长轮询架构通过 HTTP 轮询实现可靠的远程通信穿透企业防火墙零接触认证信任设备 Token 存储在 Keychain90天滚动有效期无需每次输入密码会话隔离支持 Git worktree 模式远程任务不会污染本地 Git 状态安全分级发布CLI 和服务端功能门控解耦灰度风险可控理解 Bridge 有助于理解 Claude Code 的分布式架构也为团队协作场景提供了技术底气。下一篇预告第二十二篇我们将深入AppState 状态管理分析 Claude Code 如何管理复杂的前端状态与持久化。
