# 第八章：跨机器与跨团队协作 -- Bridge、Remote Control、ACP

> 让 Claude 从另一台机器、浏览器或 IDE 里被操控。

## Bridge 模式与 Remote Control -- 在浏览器里用 Claude

Bridge 模式是 Claude Code 的远程控制核心。启用后，你的本地 Claude Code 会话可以被远程客户端（浏览器、Web UI、其他工具）访问和操控。这在你想从另一台机器控制本地的 Claude，或者让团队成员在浏览器里审批权限请求时特别有用。

Bridge 由 `BRIDGE_MODE` feature flag 控制，dev 模式和默认构建都已启用。你不需要额外做任何事来开启它，只需要使用对应命令即可。

有两种常见的启动方式。第一种是从 REPL 内部启动：在 Claude Code 的对话中输入 `/remote-control`，它会将当前会话桥接到远程控制服务，并在终端显示一个 URL。

```
> /remote-control
Remote Control connecting...
This session is available via Remote Control at https://rcs.example.com/code?bridge=abc123
```

再次输入 `/remote-control` 会弹出对话框，提供三个选项：断开连接、显示二维码（方便手机扫码）、或继续当前连接。

第二种方式是通过命令行直接启动，这会进入"环境型"Remote Control 模式，注册一个可被分配工作的环境：

```bash
# 以下五个命令完全等价
claude remote-control
claude rc
claude remote
claude sync
claude bridge
```

启动后，终端会持续轮询任务，等待远程客户端分配工作。浏览器打开终端显示的 URL 后即可创建会话、发送消息、审批权限请求。

### 自托管 Remote Control Server (RCS)

RCS 是 Bridge 模式的服务端，负责接收 CLI 的注册、分发任务、转发消息。它可以部署在你自己的服务器上，所有数据流经你控制的网络，不经过任何第三方基础设施。

RCS 是一个纯内存的 HTTP + WebSocket 服务，基于 Hono 框架构建。它支持两套传输协议：V1 的 WebSocket 长连接和 V2 的 SSE + HTTP POST。

部署 RCS 最简单的方式是 Docker。在项目根目录执行：

```bash
docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
```

然后启动容器：

```bash
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 \
  --restart unless-stopped \
  rcs:latest
```

也可以用 Docker Compose：

```yaml
version: "3.8"
services:
  rcs:
    build:
      context: .
      dockerfile: packages/remote-control-server/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - RCS_API_KEYS=sk-rcs-your-secret-key-here
      - RCS_BASE_URL=https://rcs.example.com
    restart: unless-stopped
```

RCS 的核心配置通过环境变量控制。`RCS_API_KEYS` 是唯一的必填项，它既是客户端认证的 API Key，也用于 JWT 令牌签名，务必设置一个足够强的密钥。

在 Claude Code 这边，连接到自托管 RCS 只需要设置两个环境变量：

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

设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码会自动识别为自托管模式，跳过所有云端门控检查，不需要 claude.ai 账户。之后正常启动 Claude Code 并执行 `/remote-control` 即可。

如果你使用反向代理（Nginx 或 Caddy），需要确保代理支持 WebSocket 升级：

```nginx
server {
    listen 443 ssl;
    server_name rcs.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
    }
}
```

Caddy 会自动处理 WebSocket 升级，配置更简单：

```
rcs.example.com {
    reverse_proxy localhost:3000
}
```

### RCS Web UI

RCS 自带一个 Web 控制面板，通过 `/code/*` 路径访问。它是一个 React 19 + Vite + Radix UI 构建的单页应用，支持暗色和亮色主题切换。

Web UI 提供的核心功能包括：

- 查看所有已注册的运行环境，区分 Claude Code 和 ACP Agent 类型
- 创建和管理远程会话，实时查看对话消息和工具调用
- 审批 Claude Code 的工具权限请求，支持六种权限模式切换
- 查看 Plan 可视化，包含进度条、状态图标和优先级标签
- 查看 Autopilot 状态（`standby` 等待下一轮、`sleeping` 模型休眠中）
- 通过 QR 码扫码快速连接

Web UI 使用 UUID 认证，无需用户账户系统，适合部署在受信任的内网环境中。

## ACP 协议 -- 把 Claude Code 接入 IDE

ACP（Agent Client Protocol）是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。Claude Code 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。

启用 ACP 模式只需要 `--acp` 参数。它是一个 CLI 快速路径（位于 `src/entrypoints/cli.tsx` 中），由 `FEATURE_ACP` feature flag 控制。

```bash
claude --acp
```

启动后，Claude Code 不再进入 REPL，而是通过 stdin/stdout 与 ACP 客户端通信。所有 console 输出都被重定向到 stderr，避免干扰 ACP 的 NDJSON 协议流。

### 在 Zed 中接入 Claude Code

Zed 是最典型的 ACP 客户端。打开 Zed 的设置（`Cmd+,`），在 `settings.json` 中添加：

```json
{
  "agent_servers": {
    "claude-code": {
      "type": "custom",
      "command": "claude",
      "args": ["--acp"]
    }
  }
}
```

如果你需要显式传入 API 凭证（而不是依赖 `settings.json` 中的配置），可以在 `env` 字段中指定：

```json
{
  "agent_servers": {
    "claude-code": {
      "command": "claude",
      "args": ["--acp"],
      "env": {
        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
      }
    }
  }
}
```

重启 Zed 后，按 `Cmd+'` 打开 Agent Panel，在顶部下拉菜单中选择 "claude-code" 即可开始对话。

在 ACP 模式下，Claude Code 支持完整的会话管理（新建、恢复、加载、分叉、关闭）、斜杠命令和 Skills（输入 `/` 查看列表，如 `/commit`、`/review`）、权限审批、模型切换和模式切换。当 Zed 重启时，之前的会话可以自动恢复并回放历史消息。

### 权限模式与 ACP 权限管道

ACP 模式下的权限系统与 REPL 模式略有不同。当 Claude 需要使用某个工具时，权限请求会被转发到 ACP 客户端（如 Zed），由用户在 IDE 中选择 Allow、Reject 或 Always Allow。

支持六种权限模式：`default`（每次确认）、`auto`（自动判断）、`acceptEdits`（自动接受文件编辑）、`plan`（规划模式）、`dontAsk`（不询问，未预批准则拒绝）、`bypassPermissions`（绕过所有权限检查，仅在非 root 或 sandbox 环境下可用）。

权限模式可以通过环境变量设置默认值：

```bash
ACP_PERMISSION_MODE=auto claude --acp
```

也可以在 ACP 客户端中动态切换。当 Claude 处于 Plan 模式并执行退出计划时，ACP 会显示一个特殊的选项面板，让你选择退出后进入哪种模式（auto、acceptEdits、default、plan、bypassPermissions）。

## acp-link -- 通过网络暴露 ACP Agent

ACP 协议本身基于 stdio，意味着 ACP agent 只能在本机使用。`acp-link` 是一个 WebSocket 代理服务器，将远程 WebSocket 客户端桥接到本地 ACP agent 的 stdio 接口，让 ACP agent 可以通过网络访问。

### 独立使用

最基本的用法：启动 acp-link，让它管理一个 ACP agent 子进程：

```bash
acp-link claude --acp
```

默认监听 `localhost:9315`。你也可以指定端口和主机：

```bash
acp-link --port 9000 --host 0.0.0.0 claude --acp
```

启用 HTTPS（自动生成自签名证书）：

```bash
acp-link --https claude --acp
```

acp-link 启动后会自动生成一个随机认证 token。WebSocket 客户端通过 `rcs.auth.<base64url-token>` 子协议传递 token。如果需要固定 token：

```bash
ACP_AUTH_TOKEN=my-fixed-token acp-link claude --acp
```

开发环境下可以禁用认证（不推荐在生产环境使用）：

```bash
acp-link --no-auth claude --acp
```

### 与 RCS 集成

acp-link 可以将 ACP agent 注册到 RCS，通过 RCS 的 Web UI 进行交互。设置两个环境变量即可：

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

注册流程分两步：首先通过 REST API 向 RCS 注册环境，然后建立 WebSocket 连接并发送 identify 消息。之后 ACP agent 会出现在 RCS Web UI 的环境列表中，与普通 Claude Code 会话一起管理和监控。

## IDE 集成 -- 在编辑器里使用 Claude Code

除了通过 ACP 协议接入 Zed 等原生 ACP 客户端，Claude Code 还提供 `/ide` 命令，帮助检测和连接正在运行的 IDE。这个命令会自动扫描本地已安装的 IDE（包括 JetBrains 系列和各种终端），并提供选择界面。

在 REPL 中输入：

```
/ide
```

Claude Code 会检测本地运行的 IDE 和支持的终端，让你选择要连接的目标。连接后，Claude Code 可以通过 IDE 的 Language Server Protocol 获取代码上下文，提供更精准的编辑建议。

## SSH 远程模式

`SSH_REMOTE` feature 允许 Claude Code 通过 SSH 在远程机器上工作。在 main.tsx 中通过 `feature('SSH_REMOTE')` 控制，当启用时会接管 `--ssh` 参数和相关的 SSH 连接逻辑。

启用 SSH 远程模式后，Claude Code 可以在远程机器上启动会话，通过 SSH 隧道保持通信。这对于在服务器或 CI 环境中使用 Claude Code 特别有用。`/remote-setup` 命令提供辅助设置流程，`/remote-env` 命令提供远程环境管理界面。

## 常见问题

**Remote Control is not available in this build** -- `BRIDGE_MODE` feature flag 未启用。使用 dev 模式（`bun run dev`）默认启用，或确保构建时包含该 flag。

**认证失败 (401 Unauthorized)** -- 检查 `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 RCS 的 `RCS_API_KEYS` 中的值完全匹配，注意排除多余空格或换行。

**WebSocket 连接中断** -- 如果使用反向代理，确认已配置 WebSocket 升级（`Upgrade` / `Connection` 头），`proxy_read_timeout` 建议设为 86400 秒。

**RCS 重启后数据丢失** -- RCS 使用纯内存存储，重启后所有会话和环境数据都会清除。`/app/data` 卷已预留但当前未使用。

## 下一步

- 想配置 Provider 和模型，看 [第二章](./02-providers.md)
- 想了解权限模式和安全配置，看 [第九章](./09-budget-caching-hooks.md)
- 想在 CI 流水线中使用 Claude Code，看 [第十一章](./11-ci-integration.md)
- 想处理连接问题和其他报错，看 [第十章](./10-troubleshooting.md)