Remote Control

这是什么

Remote Control 让本地的 qsdashi 会话不再局限于当前终端：CLI 会把自己注册成一个 bridge 环境，持续长轮询等待任务；你可以从浏览器（甚至手机）打开 Web UI，选中该环境后 创建会话、发指令、审批工具权限。本地终端成为「执行者」，控制面在浏览器里。

中间层是 Remote Control Server (RCS)——一个纯内存的中间服务，负责环境注册、工作轮询、 消息双向传输与会话管理。它有两种部署形态：

两种形态都要求构建时启用 BRIDGE_MODE feature flag。自托管模式的核心优势是： 只要设置了 CLAUDE_BRIDGE_BASE_URL，代码里的 isSelfHostedBridge() 即返回 true，无需 claude.ai 账户即可使用。

RCS 的职责：

• 接收 CLI 的环境注册与工作轮询（长轮询 + 心跳保活）
• 接收 acp-link 的 ACP agent 注册，支持 WebSocket relay 桥接
• 提供 Web UI 供操作者远程监控与审批
• 通过 WebSocket / SSE 双向传输消息，管理会话、环境与权限请求

前置条件

• 服务器：一台能被 CLI 与浏览器同时访问的机器（物理机 / VM / 容器均可）。
• Docker：容器化部署 RCS 时需要；若用 bun run rcs 本地启动，则只需 Bun。
• 启用 BRIDGE_MODE 的构建：dev 模式默认启用；build 模式的默认 feature 列表也包含 BRIDGE_MODE。运行时可用 FEATURE_BRIDGE_MODE=1 显式开启。
• 自托管模式不需要 claude.ai 账户，只需要一组与服务器端 RCS_API_KEYS 匹配的令牌。

安装与启动

任选一种方式部署 RCS，然后按「实战示例」用 CLI 连接。

# 构建镜像
docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .

# 启动容器
docker run -d \
  --name rcs \
  -p 3000:3000 \
  -e RCS_API_KEYS=sk-rcs-your-secret-key-here \
  -e RCS_BASE_URL=https://rcs.example.com \
  -v rcs-data:/app/data \
  --restart unless-stopped \
  rcs:latest

services:
  rcs:
    build:
      context: .
      dockerfile: packages/remote-control-server/Dockerfile
      args:
        VERSION: "0.1.0"
    ports:
      - "3000:3000"
    environment:
      - RCS_API_KEYS=sk-rcs-your-secret-key-here
      - RCS_BASE_URL=https://rcs.example.com
    volumes:
      - rcs-data:/app/data
    restart: unless-stopped

volumes:
  rcs-data:

docker compose up -d

# 默认监听 3000 端口
bun run rcs

# 覆盖端口与密钥
RCS_API_KEYS=key1,key2 RCS_PORT=4000 bun run rcs

curl https://rcs.example.com/health
# 预期: {"status":"ok","version":"0.1.0"}

配置

服务器端环境变量（由 packages/remote-control-server/src/config.ts 读取）：

客户端（qsdashi CLI）环境变量：

常用命令与参数

CLI 子命令（cli.tsx 快速路径，均需 BRIDGE_MODE 启用）：

其他相关入口：

已连接后再次执行 /remote-control 会弹出对话框，包含 Disconnect this session（断开远程连接）、Show QR code（显示 / 隐藏二维码）、 Continue（保持连接继续使用）三个选项。

实战示例

1. 在 CLI 所在机器设置连接变量：

export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"

2. 启动并注册环境：在 REPL 中执行 /remote-control， 或直接用子命令启动。环境型 Remote Control 注册成功后会打印连接 URL：

# 发布版默认包含 BRIDGE_MODE
CLAUDE_BRIDGE_BASE_URL=https://rcs.example.com \
CLAUDE_BRIDGE_OAUTH_TOKEN=sk-rcs-your-secret-key-here \
qsdashi

# REPL 内执行
/remote-control

# 终端会显示环境 URL：
# https://rcs.example.com/code?bridge=<environmentId>
# 某些桥接模式下给出会话 URL：https://rcs.example.com/code/session_<id>

3. 在浏览器打开 URL 操控。两种 URL 都能直接打开；只有 environment 模式会出现在 Web UI 的环境列表中。Web UI 位于 /code/* 路径，基于 React + Vite + Radix UI， 可查看运行环境、创建会话、实时查看对话与工具调用、审批权限、选择权限模式与模型、 查看 Plan 可视化，并支持 QR 码扫描跳转 ACP 直连视图。

4.（可选）把 ACP agent 接入 RCS：

ACP_RCS_URL=http://localhost:3000 \
ACP_RCS_TOKEN=sk-rcs-your-key \
acp-link qsdashi -- --acp

注册后 ACP session 会在 Web UI 中显示品牌色标签，与普通 qsdashi session 区分。 详见 ACP 页面。

常见问题排错