SwarmPath Claude Code Bridge v2.5.5

手机远程控制 Mac 本地 Claude Code — 一行命令连接，自动登录，支持 Chat + Terminal + Computer Use 三模式。

快速开始

# 第一步：配置（仅首次）
npx swarmpath-claudecode-bridge@latest --setup

# 第二步：启动（任意项目目录下）
cd ~/my-project
npx swarmpath-claudecode-bridge@latest

# 第三步：手机 SwarmPath Chat 输入配对码
/connect XXXXXX

npm 包地址：https://www.npmjs.com/package/swarmpath-claudecode-bridge

双模式

Chat 模式（默认）

在 Bridge session 中发消息，Claude Code 以 claude -p 非交互模式执行，流式返回结果。适合手机端使用。

Terminal 模式（v2.5 新增）

点击 header 栏的 >_ 按钮切换到 Terminal 模式，在网页中嵌入真正的终端（xterm.js），通过 PTY 双向通信，获得和本地终端完全一致的 Claude Code 体验：

• 完整交互式 TUI（进度条、颜色、动画）
• 支持 / 命令（/help、/compact 等）
• 窗口 resize 自适应
• 建议在桌面端使用（手机屏幕较小）

手机/桌面 xterm.js              SwarmPath 服务器         Mac 本地
    |                              |                      |
    |-- ws {input} --------------->|-- ws terminal_input ->|
    |                              |                       | node-pty → claude 交互模式
    |<-- ws {data} ----------------|<-- ws terminal_data --|
    |-- ws {resize} -------------->|-- ws terminal_resize >|

安装 & 配置

前置条件

• Claude Code CLI（终端输入 claude --version 验证）
• Node.js 18+（Terminal 模式需要编译 node-pty 原生模块）
• SwarmPath Chat 账号

首次配置

npx swarmpath-claudecode-bridge@latest --setup

交互式输入：

🔧 SwarmPath Claude Code Bridge — 初始配置

SwarmPath 服务器地址 [wss://www.swarmpathchat.com]:
用户名: XXXXX
密码: ****

✅ 配置已保存到 ~/.swarmpath-bridge.json
✅ 登录成功!

配置保存到 ~/.swarmpath-bridge.json，后续启动自动读取，无需重复配置。

使用

启动

# 当前目录
npx swarmpath-claudecode-bridge@latest

# 指定项目目录
npx swarmpath-claudecode-bridge@latest --cwd /Users/apple/my-project

输出：

🌐 SwarmPath Claude Code Bridge
📁 Working directory: /Users/apple/my-project
🔑 自动登录成功

🔗 Connecting to wss://www.swarmpathchat.com ...
✅ Connected to SwarmPath server

═══════════════════════════════════════════
   配对码 (Pairing Code):  F8USY4
   有效期: 300 秒
═══════════════════════════════════════════

在 SwarmPath Chat 中输入: /connect F8USY4

手机端配对

方式 1：一键连接（推荐）

侧栏底部 📡 按钮自动出现 → 点击 → 选择要连接的 bridge → 完成

方式 2：手动输入配对码

在 SwarmPath Chat 任意对话中输入：

/connect F8USY4

Chat 模式对话

在 Bridge session 中直接发消息：

• 帮我看看当前目录有什么文件
• 帮我写一个 hello.py
• 运行测试

Terminal 模式

点击 header 右侧 >_ 图标切换到 Terminal 模式，直接使用 Claude Code 交互式界面。

Computer Use 模式（v2.5.5 新增）

切换模型到 Server API（如 claude-sonnet-4-6）后，AI 可以通过 bridge 操控 Mac 桌面：

• 截图 — 查看当前屏幕内容
• 鼠标操作 — 点击、双击、右键、移动、滚动
• 键盘输入 — 文字输入、快捷键组合
• 每次操作后自动截图，AI "看到" 结果后决定下一步

前提：Mac 需在 系统设置 → 隐私与安全 → 辅助功能 中授权终端。

切换模型

• Terminal 模式：点击模型名选择 Claude Code Sonnet/Opus/Haiku（本地 CLI）
• Chat 模式：选择 Server API 模型（如 claude-sonnet-4-6）启用 Computer Use

切换工作目录

/cd /Users/apple/another-project
/cd ..

重新连接

bridge 重启后，在同一个 Bridge session 中输入新配对码即可重连（不创建新 session，历史保留）：

/connect XXXXXX

参数

| 参数 | 说明 | |------|------| | --setup | 交互式首次配置 | | --cwd <path> | 指定工作目录（默认当前目录） | | --server <url> | 覆盖服务器地址 | | --token <jwt> | 手动指定 token（跳过自动登录） |

环境变量：

export SWARMPATH_SERVER=wss://www.swarmpathchat.com
export SWARMPATH_TOKEN=eyJ...

特性

| 特性 | 说明 | |------|------| | Chat + Terminal + Computer Use | Chat 适合手机，Terminal 提供完整 TUI，Computer Use 操控桌面 | | 内置 cliclick | bin/cliclick 预编译二进制，无需 brew install，精确鼠标控制 | | 自动登录 | 首次 --setup 后，后续启动自动用存储的凭据登录 | | Token 自动续期 | 每 12 分钟自动刷新，无需手动干预 | | 断线重连 | WebSocket 断开后自动重连（指数退避 5s → 60s） | | Token 过期自动恢复 | 4001 断开时自动重新登录并重连 | | 长对话上下文 | --resume 复用 Claude session，多轮对话保持上下文 | | 远程文件浏览 | 资源管理器远程浏览 Mac 文件（只读） | | /cd 切目录 | 动态切换工作目录，自动重置 session |

安全

• 凭据存储在本地 ~/.swarmpath-bridge.json（权限 600 建议）
• 配对码 6 位加密随机，5 分钟有效，一次性
• 所有通信通过 WSS 加密
• 服务器仅转发，不存储文件内容
• 远程资源管理器只读

退出

终端按 Ctrl+C 优雅退出。