CodeNomad 远程控制
远程控制让已配对浏览器或桌面客户端无需开放入站网络端口即可使用运行中的 CodeNomad 后端。无需服务器密码、非回环 --host 或 VPN。它是独立于直接连接的访问路径。
启动和配对
- 在主机打开设置 → 远程访问。
- 选择启动远程控制。等待已准备好远程连接；首次使用可能需要时间配置隧道身份和证书。
- 在连接其他设备下扫描二维码或选择复制链接，然后在目标设备打开该一次性链接。
- 保留已配对浏览器的站点数据。后端运行时重新打开隧道地址即可重连。
链接有效期为五分钟，只能成功使用一次。请将其视为凭据：任何消费它的人都能成为配对设备。配对码位于 URL 片段，而非查询字符串。创建新的配对链接会立即使上一个未使用链接失效。停止、后端关闭和隧道失败会取消未使用的配对链接。
要配对另一个桌面 CodeNomad，在其主页选择连接 CodeNomad 服务器，将链接粘贴到服务器 URL，然后选择连接。即使选择保存，配对链接也会打开其窗口，因为打开链接才会消费配对码。书签仅保存隧道来源；不保留配对码。配对链接始终启用 TLS 验证。
管理配对设备
- 在主机返回设置 → 远程访问 → 远程控制。
- 检查已配对设备及其上次活动时间。每台设备以配对时所用的平台和浏览器命名，例如
iPhone · Safari。 - 对不应继续连接的设备选择撤销。
撤销会终止该设备当前的 HTTP/SSE 连接及未来访问。使用新链接重新配对即可恢复访问。设备连续 30 天未使用后过期。达到 32 台设备上限时，新配对会替换最久未见的设备并关闭其连接。
后端在配置根目录的 remote-control-devices.json 中存储凭据哈希，而非原始设备凭据。客户端持有按主机限定的 Secure、HttpOnly、SameSite=Lax 设备 cookie。浏览器中的有效期可能长于服务器 30 天不活动期限；以注册表为准。清除站点数据、切换浏览器配置文件或使用隐私浏览可能需要重新配对。
更改直接访问密码不会撤销设备。停止远程控制会断开隧道，但保留已配对设备列表；要移除授权请使用撤销。
不丢失当前位置地重新配对
- 如果客户端显示重新配对此设备，请保持该页面打开。
- 在主机选择创建新的配对链接，在同一客户端浏览器/配置文件中打开。对于已保存的桌面服务器，使用新配对链接重新连接，以复用其现有远程窗口存储。
- 返回等待页面并选择检查连接；页面重新获得焦点时也会再次检查。
恢复会保留打开页面和草稿；不会重放失败操作。重试发送、回答或删除之前，请检查是否已生效。直接访问密码无法恢复远程控制配对。
可用性与生命周期
| 操作/状态 | 影响 |
|---|---|
| 启动远程控制 | 连接此后端并记住选择，供后续启动使用。 |
| 关闭远程浏览器 | 不停止主机后端，也不撤销设备。 |
| 停止远程控制 | 断开访问并清除自动启动恢复；保留设备记录。 |
| 后端关闭 / 最后一个桌面窗口关闭且应用退出 | 远程控制离线。OpenCode 共享服务可继续运行，但无法通过已停止后端提供此界面。 |
| 保持远程控制启动状态后再次启动 | 后台重连，不签发新配对链接。从未启动过的安装不会自行启用。 |
| 恢复失败或隧道致命错误 | 保留已记住的选择，主机会显示错误；远程控制卡片的刷新图标会重新读取其状态。启动远程控制会立即重试；停止远程控制会清除该选择。否则，下次启动时会重试。 |
自动启动恢复限制为每个配置目录一个后端。不要用同一配置启动相互竞争的主机来增加隧道容量。若桌面退出后主机仍须可达，请部署单独管理的独立服务器；远程控制不是独立守护进程。
可用和不可用界面
配对设备可以使用普通项目/对话 API、发送提示词、检查文件和回答权限/Form，并受相同归属检查约束。配对是强大访问权限，而非只读共享链接。即使隧道在主机内部转发流量，也绝不授予回环特权。
| 界面 | 通过远程控制 |
|---|---|
| 普通已认证界面、工作区、对话和 SSE | 配对设备可用。 |
| 密码登录/退出、密码更改、本地令牌初始化 | 不可用；即使禁用直接认证，仍需要设备凭据。 |
| 远程控制状态 | 配对设备可读；管理不可用。启动/停止、创建配对、设备列表和撤销保留在主机访问路径上。 |
| 桌面远程窗口/服务器管理及代理路由 | 不可用（/api/remote-servers/、/api/remote-proxy/）。 |
| SideCar 内容代理 | 不可用（/sidecars/）。这不表示所有 SideCar API 都被阻止：配对客户端仍可访问 /api/sidecars 注册 API。 |
| 网页预览内容 | 主机上设置 → 远程访问 → 远程控制中的网页预览开启时（默认）可用。每个预览地址无需配对即可打开对应页面，请勿泄露。关闭该开关会停止已提供的预览及其 WebSocket；已配对设备重新加载后不再显示打开网页预览。 |
| 自动化桥接 | 不可用（/api/opencode-plugin/）。原生桌面能力不会变成浏览器能力。 |
| WebSocket 升级 | 仅适用于网页预览。 |
工作流程需要被阻止的代理/WebSocket 界面时，使用妥善保护的直接连接。远程控制不会自动切换到该路径。
中继与隐私
CodeNomad 使用 OpenTunnel，在机器共享的默认隧道身份上申请一条随机路由。停止会释放 CodeNomad 桥接，而非其他应用使用的共享身份。
TLS 在 CodeNomad 后端终止。中继转发密文，无法读取应用内容，但可观察主机名、连接时间和流量大小。隧道证书/私钥保留在主机上。请将主机隧道存储和 CodeNomad 配置作为凭据保护；难以猜测的地址不等于授权。
CODENOMAD_REMOTE_CONTROL_API 选择自托管 OpenTunnel API；未设置则使用托管服务。这改变隧道部署，而非配对要求或被阻止的界面。凭据和诊断信息处理请参阅安全。