CodeNomad 直接远程访问
直接访问使用服务器密码连接 CodeNomad 的 HTTP/HTTPS 监听器。它与远程控制分开：配对不需要局域网绑定或入站端口，两条路径都不会静默回退到另一条。
选择访问路径
| 路径 | 需要管理的内容 |
|---|---|
| 同机浏览器 | 保持回环绑定；使用打印的本地 URL。 |
| 局域网或 VPN | 绑定可达接口，将防火墙限制到目标客户端，并使用可信 HTTPS。VPN 不会替你配置 CodeNomad 监听器。 |
| SSH 转发 | 保持后端回环绑定；转发其实际打印端口。隧道保护传输，但不替代 CodeNomad 认证。 |
| 反向代理 | 保持后端位于私有/回环接口；在代理终止可信 TLS，保护上游链路，并支持长期 SSE 及直接访问工具所需的 WebSocket。 |
| 远程控制 | 从主机配对设备；其较窄界面和生命周期参阅远程控制。 |
绑定不会创建防火墙规则、端口转发、DNS 或 VPN。不要向互联网发布未认证 HTTP 监听器。工作区根目录不是安全沙箱；公开服务器前阅读安全。
启用直接访问
- 在主机打开设置 → 远程访问，展开直接访问（局域网，高级）。
- 在服务器密码下选择设置密码或修改密码，输入新密码和确认密码，然后选择保存密码。运行时提供的密码不能在此更改；参阅安全。
- 在监听模式下开启允许其他 IP 连接。阅读重启警告，只有准备好接受临时中断时才选择立即重启。
- 重启后使用刷新，检查可访问地址。在另一设备打开可达 HTTPS 地址，或在主机选择显示二维码并用另一设备扫描，然后登录。
这更改主机直接监听模式，而非单个项目，也不影响远程控制。服务器监听范围超出 localhost 时，折叠区域自动打开。不能自动重启时，请手动重启 CodeNomad；独立部署必须一致地设置启动时 --host。移除暴露时，关闭开关并重启，或用回环绑定重启 CLI。这不会撤销已配对远程控制设备。
监听器绑定矩阵
--host 默认为 127.0.0.1；localhost 会规范化为该地址。以下规则适用于已启用监听器：
| 启动/模式 | HTTP 绑定到 | HTTPS 绑定到 |
|---|---|---|
| 独立，仅 HTTPS（默认） | 仅私有回环监听器（见下文） | --host |
| 独立，仅 HTTP | --host，包括局域网/通配地址 |
未启用 |
| 独立，双监听器 | 127.0.0.1，不受 --host 影响 |
--host |
| 原生桌面后端 | HTTP 监听器始终在 127.0.0.1，包括宿主内部监听器 |
启用 HTTPS 时为 --host |
每个后端还会在 127.0.0.1 上保留一个 HTTP 监听器，供 CodeNomad 自身内置的 OpenCode 插件（如任务）使用。如果未请求 HTTP，或所请求的 HTTP 监听器绑定到 127.0.0.1 或 0.0.0.0 以外的地址，后端会在随机的 127.0.0.1 端口上添加一个私有 HTTP 监听器。它绝不会被打印或作为连接地址提供，其他机器无法访问，并提供同一个需认证的应用。
具体局域网地址不一定接受回环连接。0.0.0.0 表示所有 IPv4 接口；:: 是双栈通配监听器。浏览器中使用实际可达地址，不要使用通配地址。--host 不支持 IPv6 区域标识符。
独立 HTTPS 部署请通过初始化流程设置密码，然后运行：
codenomad --host 0.0.0.0 --https=true --http=false
仅回环 HTTP，例如位于本地可信代理之后：
codenomad --host 127.0.0.1 --https=false --http=true
不要假定端口是 9898 或 9899：省略端口时，繁忙会回退。显式非零的 --https-port，或启用 HTTP 时的 --http-port，会固定端口，无法绑定则失败；0 请求操作系统分配。本次运行以打印的 Local Connection URL、Remote Connection URL 和刷新的可访问地址为准。参阅完整服务器 CLI 参考。
配置可信 TLS
提供自己的证书
- 获取证书，其主体备用名称（SAN）须覆盖客户端实际使用的主机名或 IP。
- 同时提供 PEM 格式的
--tls-key <path>和--tls-cert <path>。部署需要 CA 链/证书包时，添加--tls-ca <path>。 - 重启 CodeNomad，从客户端设备验证证书及打印的 HTTPS 地址。
自定义证书文件在启动时读取，CodeNomad 绝不重写。续期及加载续期文件所需重启由你负责。--tlsSANs 配置生成的证书，无法为提供的证书添加名称。保护私钥，只信任已验证主机身份的证书。
使用生成的本地 CA
启用 HTTPS 且未提供密钥/证书对时，CodeNomad 会在配置根目录下创建本地 CA 和服务器证书：
| 文件 | 用途 |
|---|---|
tls/ca-cert.pem |
公共 CA 证书，可安全分发给你管理的客户端。 |
tls/ca-key.pem |
CA 私钥；绝不分发。 |
tls/server-cert.pem |
服务器证书。 |
tls/server-key.pem |
服务器私钥；绝不分发。 |
- 使用
--tlsSANs "host.example.test,192.0.2.10"添加每个面向客户端的 DNS 名/IP。通配绑定不会发现所有局域网地址并加入 SAN。 - 重启后端以生成/重新检查证书。
- 通过可信渠道验证主机/CA，然后向每个目标客户端/浏览器信任库导入仅 CA 证书。也可使用公开受信任证书或 TLS 反向代理。
生成的服务器证书有效 30 天。启动时会在距离过期三天内、缺少必需 SAN、证书检查失败或私钥文件缺失时续期。生成的 CA 有效 365 天，会在过期、证书检查失败或私钥文件缺失时替换；替换也会重新签发服务器证书。已有但损坏、不可读或不匹配的私钥不会自动修复。客户端必须信任替换 CA。进程内不会持续续期：长期运行部署请在过期前安排明确重启。
客户端报告证书警告时，请停止并检查主机名、SAN、信任库和有效期。不要禁用验证，也不要将点击绕过警告作为部署流程。远程浏览器功能，如 PWA 安装和麦克风访问，也要求可信 HTTPS。
保存远程服务器
- 在桌面主页选择连接 CodeNomad 服务器。空的服务器标签页和设置 → 远程访问 → 服务器中也有同一按钮。
- 在连接到服务器中，输入服务器名称和使用可信 HTTPS 来源的服务器 URL。不要勾选为自签名证书跳过 TLS 验证。；应建立信任。
- 选择保存添加书签，或选择连接保存并打开。在该服务器上登录。
在主页的服务器标签页中选择已保存的服务器即可再次打开它。书签属于此 CodeNomad 配置，而非远程服务器项目。保存 URL 不会启动服务器或授予访问。删除已保存服务器移除书签，而非远程对话、后端或凭据。
使用远程控制时，改为将新配对链接粘贴到服务器 URL。书签仅保留隧道来源，绝不保留一次性配对码；设备 cookie 丢失后的重新配对请参阅远程控制。