远程设置 (WSS)

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

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

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

你需要两样东西：证书和 bearer token。 客户端证书用于保障传输安全：它证明 TLS 连接另一端是哪台设备。它并不能说明你是谁。每个远程连接还必须在 initialize 握手中提交一个 bearer token，由该 token 来标识你的身份（见下方 Bearer token）。注册（Enrollment）只会为你提供证书。仅持有证书而没有 token 的客户端会完成 TLS 握手，随后被以 AUTH_REQUIRED（-32010）拒绝。

注册（推荐）

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

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

它会提示输入守护进程的一次性配对码（在守护进程启动时打印在其日志中），并显示一个短认证字符串（SAS），供您与守护进程控制台上的内容比对确认（从而可以发现中间人 CA）。随后它会获取并缓存一个客户端证书，存放于 <config-dir>/tls 下。之后的运行会复用该证书，无需再次提示；证书会在其有效期约 50% 时自动续期。若要以非交互方式注册，请使用 zerocode --enroll --connect wss://<remote-host>:9781。

注册不会为你提供 Bearer 令牌。注册配对码与网关配对码是分开的，并且会在注册过程中被消耗掉。在守护进程接受会话之前，你仍然需要一个令牌；请参见Bearer 令牌。

未注册就访问 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。

无论哪种方式，证书都只能让你通过 TLS 验证。接下来添加 Bearer 令牌。

Bearer 令牌（每个连接都必需）

即使客户端证书有效，守护进程也会拒绝任何不包含 auth_token 的远程 initialize 请求。只需为 zerocode 提供一次令牌，它便会在每次连接和重新连接时都提交该令牌。

1. 与网关配对以获取令牌。 使用仪表板的配对页面，或者在守护进程所在主机上（网关默认监听 127.0.0.1:42617），将守护进程日志中的网关配对码 POST 到 /pair：

   curl -X POST http://127.0.0.1:42617/pair -H X-Pairing-Code: <code>
   

   响应中包含一个 zc_... 令牌。请在此处使用网关的配对码，而不是你之前提供给 zerocode 的注册码。

2. 给 zerocode 配置令牌。 推荐使用环境变量，因为这样可以避免将密钥写入配置文件：

   export ZEROCLAW_AUTH_TOKEN=zc_...
   zerocode --connect wss://<remote-host>:9781
   

   或在 zerocode 的配置中设置，可以是仅你可读的文件路径，也可以直接内联填写：

   [connection.wss]
   uri = "wss://<remote-host>:9781"
   auth_token_file = "/abs/path/zerocode-bearer"   # 或: auth_token = "zc_..."
   

   优先级依次为 ZEROCLAW_AUTH_TOKEN、auth_token_file、auth_token。其他账户可读取的令牌文件会被跳过，并输出警告。

要改用 OIDC 访问令牌而不是配对令牌，还需在 [connection.wss] 下设置 auth_provider = "oidc.<alias>"。有关文件权限规则、OIDC 以及守护进程如何处理该令牌的说明，请参阅 认证与主体。

此后，zerocode --connect wss://<remote-host>:9781（或在配置中设置了 uri 后直接运行 zerocode）无需再添加任何参数，连接断开时 zerocode 也会自动重新连接。

配置参考

wss 部分：