远程设置 (WSS)

将工作站上的 zerocode 连接到运行在另一台机器（Raspberry Pi、家庭服务器、VPS 等）上的守护进程。

有关涵盖三种拓扑（直接、守护进程到中继以及客户端经中继）的完整逐项参数指南，请参阅 安全传输（端到端配置）。

WSS 平面采用双向 TLS 身份验证（mTLS）。 每个客户端都必须提供证书；不存在仅验证服务器/未经过身份验证的路径。获取客户端证书的简单方式是注册（如下所述）——无需手动管理证书。如果你更愿意自行签发一个证书，请参阅下文“在你的工作站上”中的自带证书步骤。--tls-skip-verify 只会放宽对自签名守护进程证书的_服务器_证书验证；无论哪种情况，仍然需要客户端证书。

注册（推荐）

首次以交互方式连接无证书客户端时，zerocode 会自动注册：

zerocode --connect wss://<remote-host>:9781

它会提示输入守护进程的一次性配对代码（启动时打印在守护进程日志中），显示一个短认证字符串 (SAS)，供你与守护进程控制台中的字符串进行确认（这样即可检测到中间人 CA），然后获取客户端证书并将其缓存在 <config-dir>/tls 下。后续运行无需配置，证书会在其生命周期约达到 50% 时自动续期。要以非交互方式注册，请使用 zerocode --enroll --connect wss://<remote-host>:9781。

未注册就访问 WSS 平面的无证书客户端会收到可操作的“请先注册”消息（同时，守护进程会记录被拒绝的未迁移客户端）——绝不会无提示地挂起。已撤销的证书会在握手时被拒绝（由已签发证书台账驱动），因此撤销丢失设备的证书会在其下次连接时生效。

[enroll] 部分中的 allow_unpaired_enrollment 预留用于未来无需代码的迁移流程。此版本会在守护进程启动时拒绝任何非空值；请将其留空，并使用打印出的配对代码。

在远程主机上（守护进程端）

1. 启用 WSS。 通过 Config 面板（或网关 / zeroclaw config set）设置 wss 配置：

   [wss]
   enabled = true
   

   将 cert_path / key_path 留空（默认值）：守护进程会在首次启动时在 <data_dir>/tls/ 下自动生成自己的 CA 和服务器证书，因此无需自行运行 openssl。仅在使用自己的服务器证书时设置这两个参数，并且无论哪种情况都要使用绝对路径；配置不会展开 ~。

2. 打开防火墙端口：

   sh

   sudo ufw allow 9781/tcp
   

   默认的 WSS 端口为 9781。可在 [wss] 部分使用 port = <number> 进行修改。

3. 启动（或重启）守护进程：

   sh

   zeroclaw daemon
   

   你应该会看到一行日志，确认 WSS 监听器已在 0.0.0.0:9781 上启动。

在您的工作站上（zerocode 端）

上文所述的注册是获取客户端证书最快的方式。如果您希望使用自己的客户端证书，而不是以交互方式完成注册：

1. 在守护进程主机上签发客户端证书，使用守护进程的 mTLS CA：

   zeroclaw security issue-client-cert --name my-laptop --out-dir /tmp/my-laptop-tls
   

   此操作会将 ca.crt、client.crt 和 client.key 写入 --out-dir。添加 --force 可覆盖该名称的现有证书。

2. 将这三个文件复制到工作站的 <config-dir>/tls/（这样 zerocode --connect wss://<remote-ip>:9781 就会自动找到它们），或者显式指定它们：

   sh

   zerocode --connect wss://<remote-ip>:9781 \
     --tls-ca-cert     /path/ca.crt \
     --tls-client-cert /path/client.crt \
     --tls-client-key  /path/client.key
   

   由于 ca.crt 就是为守护进程服务器证书签名的同一个 CA，因此这也会验证服务器；只有在跳过 --tls-ca-cert、并连接到尚未固定的自签名守护进程证书时，才需要 --tls-skip-verify。

就这样。如果连接中断，zerocode 会自动重新连接。

配置参考

wss 部分：