远程控制（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（可选）

启动远程控制 ​

在 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
  • 监听地址：0.0.0.0（所有网络接口）

安全机制 ​

认证 ​

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

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

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

登录限流 ​

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

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

权限 ​

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

CORS 策略 ​

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

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

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"],
    "maxConnections": 5,
    "tokenTtlMs": 86400000
  }
}
配置键说明默认值
auth认证模式，"password" 或 "none""none"
password自定义密码。为空时首次启动自动生成自动生成
corsOrigins额外允许的 CORS 来源列表[]
maxConnectionsACP 最大并发连接数5
tokenTtlMsACP Session Token 有效期（毫秒）86400000（24 小时）

环境变量 ​

环境变量说明
CODEBUDDY_CORS_ORIGINS额外的 CORS 允许来源（逗号分隔）

实例管理 ​

当您在多个项目目录中运行 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 域名稳定）

限制 ​

  • 每个会话一个 Gateway：每个 CodeBuddy Code 实例同时只支持一个 Gateway 服务
  • 终端需保持运行：Gateway 作为本地进程运行。关闭终端或停止 CodeBuddy Code 进程后，远程连接会断开。使用 /gateway 重新启动
  • Quick Tunnel 域名临时性：Quick Tunnel 域名在 cloudflared 进程存活期间保持不变。使用固定端口启动可以跨 CLI 重启复用 cloudflared 进程（参见保持 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 启动时复用。

相关文档 ​