第二十一篇：Bridge 远程会话系统，Claude Code 如何实现安全的远程控制

本文是《Claude Code 源码分析 100 篇》系列的第二十一篇。前一篇我们分析了 MCP 协议集成，本篇深入 Bridge 系统——这是 Claude Code 实现远程控制、跨设备协作的核心模块。

---

一、Bridge 系统解决了什么问题

Claude Code 本质是一个本地 CLI 工具，但在团队协作、远程开发、多设备场景下，需要从另一台机器"远程连接"并控制它。Bridge 系统就是这个能力的技术实现：

你的电脑A（控制端）  ←→  Bridge协议  ←→  电脑B（Claude Code运行端）

Bridge 支持两种模式：

• Headless 永久模式：claude --bridge 启动后持续在后台运行，远程可随时连接
• 按需启动模式：远程命令触发才启动一个会话

---

二、核心文件架构

src/bridge/ 目录是整个系统的核心，共约 7000 行代码：

bridgeMain.ts       # 主入口：runBridgeLoop、bridgeMain、runBridgeHeadless（2999行）
replBridge.ts       # REPL 通信协议：消息编解码、双工流（2406行）
remoteBridgeCore.ts # 远程桥接核心逻辑：Worker注册、心跳、消息路由（1008行）
sessionRunner.ts    # 会话生成器：工作树隔离、Spawn模式（550行）
trustedDevice.ts    # 信任设备认证：Keychain存储、90天滚动Token（131行）
bridgeApi.ts        # 与CCR v2 API通信：JWT刷新、Worker注册
bridgeMessaging.ts  # 消息处理：入站/出站消息队列
peerSessions.ts     # 对等会话管理
types.ts           # 类型定义

---

三、主循环 runBridgeLoop

bridgeMain.ts 的核心是 runBridgeLoop 函数（141行开始），它是一个 长轮询主循环：

export async function runBridgeLoop(
  bridgeConfig: BridgeConfig,
  opts: BridgeOpts,
): Promise<never> {
  // 1. 建立 WebSocket 或轮询连接
  // 2. 注册 Worker（上报设备信息、Session ID）
  // 3. 进入主循环：poll → process → ack
  while (true) {
    const activity = await pollActivity(pollInterval)
    if (activity.type === 'result' || activity.type === 'error') {
      // 任务结果，写入stdout
    } else if (activity.type === 'tool_start') {
      // 工具调用，通过 REPL 发送给本地 Claude Code 执行
    }
    await ackActivity(activity.id)
  }
}

关键设计：Bridge 使用轮询而非 WebSocket，因为：

• 更易穿透企业防火墙
• 无需维护持久连接状态
• 可以在任何网络条件下工作

---

四、信任设备认证 Trusted Device

trustedDevice.ts 实现了 零接触远程认证：

4.1 为什么需要信任设备

远程连接如果只靠 JWT Token，有两个问题：

1. Token 可能被盗用
2. 每次连接都需要重新登录

Claude Code 的解决方案：设备级别信任。首次登录时，服务器颁发一个 trustedDeviceToken（90天滚动过期），存储在本地 Keychain（macOS）或等效安全存储。远程连接时，携带这个 Token，服务器验证设备历史，无需重新登录。

4.2 核心实现

// 信任设备认证门控（服务端分级部署）
const TRUSTED_DEVICE_GATE = 'tengu_sessions_elevated_auth_enforcement'

export function getTrustedDeviceToken(): string | undefined {
  if (!isGateEnabled()) {
    return undefined  // 功能未开启，不发送Token
  }
  return readStoredToken()  // 读取Keychain
}

// Token存储结构
interface SecureStorageData {
  trustedDeviceToken?: string
  jwt?: string
  // ...
}

两段式门控是安全发布的经典模式：

• 第一步：CLI 端开始发送 X-Trusted-Device-Token 请求头（服务器暂时忽略）
• 第二步：服务器功能开启，Token 正式生效

这样可以先灰度 CLI，再灰度服务端，风险可控。

4.3 注册时机

注册发生在 /login 流程中（enrollTrustedDevice），原因是服务端限制了注册条件：

// 服务端要求：account_session.created_at < 10分钟
// 所以注册必须在登录时完成，不能延迟
export async function enrollTrustedDevice(): Promise<void> {
  await axios.post('/auth/trusted_devices', {
    deviceId: getDeviceId(),
    hostname: hostname(),
    enrolledAt: Date.now(),
  })
}

---

五、会话生成器 SessionRunner

sessions.ts 控制 Claude Code 如何"生成"一个会话来执行任务：

export async function createSessionSpawner(): Promise<SessionSpawner> {
  return {
    spawn: async (opts: SessionSpawnOpts) => {
      if (opts.mode === 'worktree') {
        // 创建独立的Git worktree隔离环境
        const worktreePath = await createAgentWorktree(opts.projectRoot)
        return spawnClaudeInWorktree(worktreePath)
      } else {
        // 经典单会话模式
        return spawnClassicSession(opts)
      }
    }
  }
}

Spawn 模式

模式	说明	适用场景
worktree	Git worktree 隔离	避免污染主分支
classic	标准单会话	快速任务
resume	恢复已有会话	断点续传

---

六、REPL 桥接通信协议

replBridge.ts 定义了 Bridge 与本地 Claude Code 实例之间的通信协议。消息通过 stdin/stdout 传递：

// 消息类型
type BridgeMessage =
  | { 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 SecurityTier=ELEVATED            │
│  GrowthBook 功能门控分级发布              │
├─────────────────────────────────────────┤
│  Layer 4: 隔离                           │
│  Git worktree 任务隔离                   │
└─────────────────────────────────────────┘

---

八、总结

Bridge 系统是 Claude Code 的"远程控制中心"，它：

1. 长轮询架构：通过 HTTP 轮询实现可靠的远程通信，穿透企业防火墙
2. 零接触认证：信任设备 Token 存储在 Keychain，90天滚动有效期，无需每次输入密码
3. 会话隔离：支持 Git worktree 模式，远程任务不会污染本地 Git 状态
4. 安全分级发布：CLI 和服务端功能门控解耦，灰度风险可控

理解 Bridge 有助于理解 Claude Code 的分布式架构，也为团队协作场景提供了技术底气。

---

下一篇预告：第二十二篇我们将深入 AppState 状态管理，分析 Claude Code 如何管理复杂的前端状态与持久化。