# 远程控制（Remote Control）

> **Beta**：远程控制功能目前处于 Beta 阶段，功能和接口可能会在后续版本中发生变化。欢迎试用并反馈问题。

通过 Remote Control，您可以从手机、平板或任意浏览器远程访问本地运行的 CodeBuddy Code 会话。会话始终在您的本机执行，Web 界面只是一个远程窗口。

## 概述

Remote Control 在本地启动一个 Gateway 服务，通过 Cloudflare Tunnel 或局域网暴露一个 Web UI，让您可以从任何设备连接到正在运行的 CodeBuddy Code 会话。

使用 Remote Control，您可以：

- **远程使用完整的本地环境**：文件系统、MCP 服务器、工具配置全部保持可用
- **通过 Web UI 与 Agent 交互**：在浏览器中发送消息、查看对话、监控工具执行
- **从多设备接入**：手机扫码即可连接，支持局域网和公网访问
- **通过终端管理会话**：在终端和 Web 端同时工作，对话保持同步

## 前置条件

- 已安装并登录 CodeBuddy Code（运行 `codebuddy` 后使用 `/login` 登录）
- 若需要公网访问，需安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)（可选）

## 启动远程控制

在 CodeBuddy Code 会话中使用 `/gateway` 命令启动远程控制服务：

```
/gateway
```

启动成功后，终端会显示连接信息：

```
Gateway started

  ├─ Status   connected
  ├─ Mode     tunnel
  ├─ Local    http://127.0.0.1:8321
  ├─ Tunnel   https://xxx-xxx-xxx.trycloudflare.com
  ├─ Web UI   https://xxx-xxx-xxx.trycloudflare.com/?password=<token>
  └─ Webhook  https://xxx-xxx-xxx.trycloudflare.com/gateway/webhook/:platform

  Scan to open Web UI:

  [QR Code]
```

### 连接方式

Gateway 启动后，有以下几种方式从其他设备连接：

- **扫描二维码**：用手机扫描终端中显示的二维码，直接打开 Web UI
- **复制 Web UI 链接**：将带有认证 token 的 URL 在任意浏览器中打开
- **局域网访问**：同一网络中的设备可直接访问 Local 地址（如 `http://10.x.x.x:8321`）

### 子命令

| 命令 | 说明 |
|:-----|:-----|
| `/gateway` | 启动 Gateway（默认带 Tunnel） |
| `/gateway status` | 查看当前 Gateway 状态 |
| `/gateway stop` | 停止 Gateway |
| `/gateway token` | 重新生成认证 token |
| `/gateway tunnel` | 启动带 Tunnel 的 Gateway |

## 网络模式

Gateway 支持两种网络模式，适应不同的使用场景：

### Tunnel 模式（默认）

通过 Cloudflare Quick Tunnel 自动分配一个临时公网域名（`*.trycloudflare.com`），无需任何额外配置即可从公网访问。

适用场景：
- 从外部网络（如手机移动网络）远程访问
- 不想配置端口转发或 VPN

需要安装 `cloudflared`：

```bash
# macOS
brew install cloudflared

# Debian/Ubuntu
curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Windows
winget install Cloudflare.cloudflared
```

### 局域网模式

当 `cloudflared` 未安装或 Tunnel 启动失败时，Gateway 自动回退到局域网模式。此模式下，仅同一网络中的设备可以访问。

- 默认监听端口：`8321`
- 监听地址：默认 `127.0.0.1`（仅本机），可通过 `--host 0.0.0.0` 监听所有网络接口

## 安全机制

### 认证

Gateway 启动时会自动生成一个随机密码（token），访问 Web UI 和 API 均需要通过认证。支持以下认证方式：

| 方式 | 说明 |
|:-----|:-----|
| URL 参数 | `?password=<token>`，适合快速分享链接 |
| Cookie | 登录后自动设置，后续访问无需重复认证 |
| Bearer Token | `Authorization: Bearer <token>`，适合 API 调用 |

密码可通过 `/gateway token` 命令重新生成。重新生成后，之前的密码立即失效。

### 登录限流

为防止暴力破解，认证中间件内置了登录限流机制：

- 每分钟最多允许 2 次失败尝试
- 每小时额外允许 12 次失败尝试
- 超出限制后将暂时拒绝登录请求

### 权限

通过远程控制执行的任务自动以 `bypassPermissions` 模式运行，即工具执行不需要逐一审批。这是因为远程场景下无法进行交互式审批。请确保仅将访问链接分享给受信任的人。

### CORS 策略

Gateway 默认允许以下来源的跨域请求：

- 本地回环地址（`localhost`、`127.0.0.1`、`[::1]`）
- Tunnel 分配的公网地址
- 通过 `gateway.corsOrigins` 配置的额外来源

支持三种配置模式：

- **精确匹配**：`https://example.com`
- **子域通配**：`https://*.example.com`（匹配所有子域，包括多级子域如 `a.b.example.com`）
- **全部允许**：`*`

## Web UI

Web UI 提供了完整的 CodeBuddy Code 交互界面，包括：

- **对话界面**：发送消息、查看 Agent 回复、监控工具调用
- **终端面板**：内置 Web 终端，直接在浏览器中操作远程终端
- **实例管理**：查看和管理多个 CodeBuddy Code 实例
- **主题切换**：支持亮色/暗色主题
- **多语言**：支持中英文界面切换

Web UI 基于 ACP（Agent Client Protocol）与本地 Agent 通信，保证了与终端交互完全一致的体验。

## 配置

### Settings 配置

在 `~/.codebuddy/settings.json` 中可以配置 Gateway 相关选项：

```json
{
  "gateway": {
    "auth": "password",
    "password": "your-custom-password",
    "corsOrigins": ["https://your-domain.com", "https://*.example.com"],
    "maxConnections": 5,
    "tokenTtlMs": 86400000
  }
}
```

| 配置键 | 说明 | 默认值 |
|:------|:-----|:------|
| `auth` | 认证模式，`"password"` 或 `"none"` | `"none"` |
| `password` | 自定义密码。为空时首次启动自动生成 | 自动生成 |
| `corsOrigins` | 额外允许的 CORS 来源列表。支持精确 origin、`*.domain` 子域通配和 `*` 全开 | `[]` |
| `maxConnections` | ACP 最大并发连接数 | `5` |
| `tokenTtlMs` | ACP Session Token 有效期（毫秒） | `86400000`（24 小时） |

### 环境变量

| 环境变量 | 说明 |
|:---------|:-----|
| `CODEBUDDY_CODE_CORS_ORIGINS` | 额外的 CORS 允许来源（逗号分隔）。支持精确 origin、`*.domain` 子域通配和 `*` 全开。如 `https://*.example.com,https://specific.com` |

## 实例管理

当您在多个项目目录中运行 CodeBuddy Code 时，每个实例会自动注册到本地实例注册表（`~/.codebuddy/instances.json`）。Web UI 的实例管理面板可以查看所有活跃的实例，并在它们之间切换。

实例信息包括：

- 工作目录
- 本地/Tunnel 地址
- 操作系统和架构
- 启动时间和运行状态

## 第三方平台集成（Webhook）

Gateway 提供了 Webhook 端点，支持接入企业通讯平台机器人：

```
{gateway-url}/gateway/webhook/:platform
```

支持的平台适配器：

| 平台 | 标识 |
|:-----|:-----|
| 企业微信 | `wecom` |
| 钉钉 | `dingtalk` |
| 飞书 | `feishu` |
| 通用 | `generic` |

配置企业机器人的 Webhook 回调地址为上述端点后，即可通过企业通讯平台向 CodeBuddy Code 发送消息并接收回复。

## 连接与安全

- Gateway 仅在本地启动 HTTP 服务，不会在您的机器上打开入站端口
- 公网访问通过 Cloudflare Tunnel 的出站连接实现
- 所有 Tunnel 流量通过 Cloudflare 的 TLS 加密传输
- 使用固定端口启动时，Quick Tunnel 域名可跨 CLI 重启保持不变（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）

## 限制

- **每个会话一个 Gateway**：每个 CodeBuddy Code 实例同时只支持一个 Gateway 服务
- **终端需保持运行**：Gateway 作为本地进程运行。关闭终端或停止 CodeBuddy Code 进程后，远程连接会断开。使用 `/gateway` 重新启动
- **Quick Tunnel 域名临时性**：Quick Tunnel 域名在 cloudflared 进程存活期间保持不变。使用固定端口启动可以跨 CLI 重启复用 cloudflared 进程（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）。如果 cloudflared 进程退出（如机器重启），域名将重新分配。如需永久固定域名，可使用 Named Tunnel（需要 Cloudflare 账号）
- **局域网模式限制**：未安装 `cloudflared` 时仅限同一网络内的设备访问

## 保持 Tunnel 域名稳定

Quick Tunnel 默认每次启动 cloudflared 都会分配一个新的随机域名。通过指定固定端口，可以让域名在多次 CLI 重启之间保持不变。

### 使用固定端口

使用 `--port` 参数指定固定端口启动 CLI：

```bash
codebuddy --port 8321
```

这样每次启动都使用相同端口，`/gateway` 会自动复用上一次的 cloudflared 进程和域名。

> 如果不指定 `--port`，系统会随机分配端口，每次端口不同导致无法匹配已有的 cloudflared 进程。

### 停止 Tunnel

执行 `/gateway stop` 会终止 cloudflared 进程并清理状态。下次启动将分配新域名。

如果只是退出 CLI（Ctrl+C 或 `/exit`），cloudflared 进程会继续运行，等待下次 CLI 启动时复用。

## 相关文档

- [设置配置](settings.md)：配置 Gateway 相关选项
- [Hooks](hooks.md)：配置工具执行前后的自定义命令
- [权限管理](iam.md)：了解权限模式和规则
