开发机

本文介绍如何在容器内（例如远程虚拟机或一次性“开发机”）运行 Kaiwu，并从本地设备完成认证。

开发机镜像

我们在 Docker Hub 上发布了开发机预览版镜像：

docker pull Kaiwudev/dev-box:preview

同时，该镜像也会同步发布至 GitHub Container Registry (GHCR)：

docker pull ghcr.io/Kaiwu-dev/dev-box:preview

该镜像包含：

• 已发布的 Kaiwu CLI 二进制文件
• 可选的提供商 CLI，可在首次启动时通过 kaiwu install provider 安装

镜像内不包含源码检出或 hstack；其设计初衷是在容器中运行 Kaiwu，而非用于 Kaiwu 本身的开发。

注：“dev box”仅为我们 Docker 镜像的命名，与任何特定编辑器的“devcontainer”功能无关。

可选：在首次启动时安装提供商 CLI

设置 Kaiwu_PROVIDER_CLIS 即可通过 Kaiwu CLI 安装提供商 CLI：

docker run --rm -it \
  -e Kaiwu_PROVIDER_CLIS=claude,codex \
  Kaiwudev/dev-box:preview

当前支持的值：claude、codex。

推荐做法：持久化 Kaiwu 状态

建议持久化挂载 ~/.Kaiwu，以确保凭据、设备 ID、日志等数据在容器重启后不受影响：

docker run --rm -it \
  -v Kaiwu-home:/home/Kaiwu/.Kaiwu \
  Kaiwudev/dev-box:preview

从本地 CLI 配对远程容器/主机（无需 Web UI）

如果你的本地设备已经完成认证（即 Kaiwu auth status 状态正常），可以通过 SSH 配对远程主机或容器：

Kaiwu auth pair-remote --ssh user@host

该命令的执行流程如下：

1. 在远程主机上运行 Kaiwu auth request --json。
2. 在本地使用现有令牌批准该请求（本地令牌不会发送到远程主机）。
3. 在远程主机上运行 Kaiwu auth wait --public-key ... --json，认领请求并写入凭据。

在自动化脚本中请使用 --json。如果你当前生效的中继 URL 仅为回环地址（localhost / 127.0.0.1），交互模式会提示可用于访问当前计算机的有效地址。在脚本中，请通过 --server-url-for-remote ⟦K9⟧ 传入远程主机访问当前计算机中继所用的地址（兼容旧版别名 --remote-server-url）。

手动执行方式（适合脚本集成）

如需接入自定义编排流程，可以手动分步执行：

1. 在远程主机上：

Kaiwu auth request --json

2. 在本地设备上（需已完成认证）：

Kaiwu auth approve --public-key <publicKey> --json

3. 返回远程主机：

Kaiwu auth wait --public-key <publicKey> --json