通过 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（默认带 Tunnel） |
| 查看当前 Gateway 状态 |
| 停止 Gateway |
| 重新生成认证 token |
| 启动带 Tunnel 的 Gateway |
Gateway 支持两种网络模式，适应不同的使用场景：
通过 Cloudflare Quick Tunnel 自动分配一个临时公网域名（*.trycloudflare.com），无需任何额外配置即可从公网访问。
适用场景：
从外部网络（如手机移动网络）远程访问
不想配置端口转发或 VPN
需要安装 cloudflared：
# 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 参数 |
|
Cookie | 登录后自动设置，后续访问无需重复认证 |
Bearer Token |
|
密码可通过 /gateway token 命令重新生成。重新生成后，之前的密码立即失效。
为防止暴力破解，认证中间件内置了登录限流机制：
每分钟最多允许 2 次失败尝试
每小时额外允许 12 次失败尝试
超出限制后将暂时拒绝登录请求
通过远程控制执行的任务自动以 bypassPermissions 模式运行，即工具执行不需要逐一审批。这是因为远程场景下无法进行交互式审批。请确保仅将访问链接分享给受信任的人。
Gateway 默认允许以下来源的跨域请求：
服务自身监听端口的本地回环来源（localhost、127.0.0.1、[::1] + 实际端口）
Tunnel 分配的公网地址
通过 gateway.corsOrigins 配置的额外来源
注意：
其他端口的 localhost 页面不再自动放行（避免本机任意端口上的页面跨源调用执行进程 / 文件读写接口），需在 gateway.corsOrigins 或 CODEBUDDY_CODE_CORS_ORIGINS 中显式声明。
支持三种配置模式：
精确匹配：https://example.com
子域通配：https://*.example.com（匹配所有子域，包括多级子域如 a.b.example.com）
全部允许：*
Web UI 提供了完整的 CodeBuddy Code 交互界面，包括：
对话界面：发送消息、查看 Agent 回复、监控工具调用
终端面板：内置 Web 终端，直接在浏览器中操作远程终端
实例管理：查看和管理多个 CodeBuddy Code 实例
主题切换：支持亮色/暗色主题
多语言：支持中英文界面切换
Web UI 基于 ACP（Agent Client Protocol）与本地 Agent 通信，保证了与终端交互完全一致的体验。
在 ~/.codebuddy/settings.json 中可以配置 Gateway 相关选项：
{ "gateway": { "auth": "password", "password": "your-custom-password", "corsOrigins": ["https://your-domain.com", "https://*.example.com"], "maxConnections": 5, "tokenTtlMs": 86400000 }}
配置键 | 说明 | 默认值 |
| 认证模式， |
|
| 自定义密码。为空时首次启动自动生成 | 自动生成 |
| 额外允许的 CORS 来源列表。支持精确 origin、 |
|
| ACP 最大并发连接数 |
|
| ACP Session Token 有效期（毫秒） |
|
环境变量 | 说明 |
| 额外的 CORS 允许来源（逗号分隔）。支持精确 origin、 |
当您在多个项目目录中运行 CodeBuddy Code 时，每个实例会自动注册到本地实例注册表（~/.codebuddy/instances.json）。Web UI 的实例管理面板可以查看所有活跃的实例，并在它们之间切换。
实例信息包括：
工作目录
本地/Tunnel 地址
操作系统和架构
启动时间和运行状态
Gateway 提供了 Webhook 端点，支持接入企业通讯平台机器人：
{gateway-url}/gateway/webhook/:platform
支持的平台适配器：
平台 | 标识 |
企业微信 |
|
钉钉 |
|
飞书 |
|
通用 |
|
配置企业机器人的 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 时仅限同一网络内的设备访问
Quick Tunnel 默认每次启动 cloudflared 都会分配一个新的随机域名。通过指定固定端口，可以让域名在多次 CLI 重启之间保持不变。
使用 --port 参数指定固定端口启动 CLI：
codebuddy --port 8321
这样每次启动都使用相同端口，/gateway 会自动复用上一次的 cloudflared 进程和域名。
说明：
如果不指定 --port，系统会随机分配端口，每次端口不同导致无法匹配已有的 cloudflared 进程。
执行 /gateway stop 会终止 cloudflared 进程并清理状态。下次启动将分配新域名。
如果只是退出 CLI（Ctrl+C 或 /exit），cloudflared 进程会继续运行，等待下次 CLI 启动时复用。
设置配置：配置 Gateway 相关选项
Hooks：配置工具执行前后的自定义命令
权限管理：了解权限模式和规则
