Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Windows

在 Windows 10 / 11 上安装、更新、作为 Windows 计划任务运行以及卸载。

如果你在运行 WSL2，则可以改为遵循 Linux 设置；install.sh 在 WSL 下无需更改即可运行。

关于 setup.bat 的说明。 #6118 的硬性失败（32 位 set /a 磁盘空间溢出，以及未转义括号导致的 if/else 解析错误）已在 #6137 中修复，并随 v0.7.4 及更高版本 发布。当前版本会正常完成。不过仍有一个注意事项：setup.bat --prebuilt 在进入 prebuilt 分支之前仍会检查 cargo，因此 手动 prebuilt 路径（下方选项 1）才是真正无需 Rust 的安装方式。从源码构建（选项 3）也可以正常工作。

安装

选项 1：预构建二进制文件（推荐）

下载最新的 Windows 发行版 zip，解压 zeroclaw.exe，并将其放到你的 PATH 中。

在 PowerShell 提示符下：

# 安装和 PATH 设置具有幂等性。如果 zeroclaw 已经是最新版本且位于用户 PATH 中，
# 则会跳过这些步骤；Quickstart 仍会在最后运行。
$ver = (Invoke-RestMethod 'https://api.github.com/repos/zeroclaw-labs/zeroclaw/releases/latest').tag_name.TrimStart('v')
$dst = "$env:USERPROFILE\.zeroclaw\bin"
$exe = "$dst\zeroclaw.exe"

$current = if (Test-Path $exe) {
    ((& $exe --version 2>$null) | Select-String -Pattern '\d+\.\d+\.\d+').Matches.Value
} else { '' }

if ($current -ne $ver) {
    $url = "https://github.com/zeroclaw-labs/zeroclaw/releases/download/v$ver/zeroclaw-x86_64-pc-windows-msvc.zip"
    New-Item -ItemType Directory -Force -Path $dst | Out-Null
    Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\zeroclaw.zip" -UseBasicParsing
    Expand-Archive -Force -Path "$env:TEMP\zeroclaw.zip" -DestinationPath $dst
}

$environment = [Environment]
$userPath = $environment::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $dst) {
    $environment::SetEnvironmentVariable('Path', "$dst;$userPath", 'User')
}
if (($env:Path -split ';') -notcontains $dst) {
    $env:Path = "$dst;$env:Path"
}

& $exe quickstart

关于 Windows 预构建版本和源码安装方式所共有的稳定行为，请参阅规范安装路径。由于发布版本可用性和 PowerShell 下载代码块依赖 GitHub 上的实时资源，因此仍在此处记录。

预构建的 zip 包是自包含的；仅在从源代码构建时才需要 Visual Studio Build Tools。

安装后，验证：

zeroclaw --version    # matches the latest release

选项 2：setup.bat（来自发行版）

setup.bat --prebuilt

标志:

标志行为
--prebuilt从 GitHub Releases 下载预构建二进制文件（达到后速度最快；当前脚本仍会先检查 cargo）
--minimal仅构建核心部分（不包含通道或硬件）
--dist构建精简的发布分发功能集
--default使用 Cargo 的默认特性集构建
--all使用所有已注册的功能构建

⚠️ 已知问题（当前）。 setup.bat --prebuilt 仍会在进入预编译分支之前检查 cargo，因此选项 2 并不遵守“不需要 Rust”的承诺。如果你没有 Rust 工具链，请使用上面的 选项 1。

历史（v0.7.4 之前）。 早期版本在 #6118 中报告了两个硬停止失败和一个入门命令不匹配：一个 32 位 set /a 磁盘空间溢出（Invalid number. Numbers are limited to 32-bits of precision.）、一个未转义括号的 if/else 解析错误（.[0m was unexpected at this time.），以及最后的 zeroclaw init 提示。以上问题都已在 #6137（v0.7.4 / 0.7.5 / 0.8.0）中修复；当前版本会输出 zeroclaw quickstart 并正常完成。

选项 3：来自源代码

需要 Rust（rustup）和 Visual Studio 构建工具：

git clone https://github.com/zeroclaw-labs/zeroclaw
cd zeroclaw
cargo install --locked --path .
zeroclaw quickstart

选项 4：Scoop

scoop bucket add zeroclaw https://github.com/zeroclaw-labs/scoop-zeroclaw
scoop install zeroclaw
zeroclaw quickstart

选项 5：Docker

ZeroClaw 在 ghcr.io/zeroclaw-labs/zeroclaw:latest 发布 Linux 容器镜像（已标记发布版本则为 :vX.Y.Z）。在 Windows 上，可通过 Docker Desktop 运行，或在 WSL 发行版中使用 sudo apt install docker.io；两者都可以，且容器行为相同。

快速开始：

# config + workspace 的持久卷；容器内 ZeroClaw 的数据目录是 /zeroclaw-data
docker run -d --name zeroclaw `
  --restart=unless-stopped `
  -p 42617:42617 `
  -v zeroclaw-data:/zeroclaw-data `
  ghcr.io/zeroclaw-labs/zeroclaw:latest

# 查看首次运行日志
docker logs -f zeroclaw

# 健康检查（无需认证）
curl http://localhost:42617/health

# （可选）为客户端配对。注意：发布的镜像默认
# `require_pairing = false`，因此默认不会发出配对码，
# 且 `/api/*` 可在无需认证的情况下接受请求。要启用配对，
# 覆盖配置（在容器内的
# /zeroclaw-data/.zeroclaw/config.toml 中设置 `require_pairing = true`）并重启；
# 之后首次启动时会将一次性代码打印到 stdout，随后
# 客户端将其 POST 到 `/pair`：
curl -X POST http://localhost:42617/pair -H 'X-Pairing-Code: <code-from-logs>'

镜像事实（已针对 ghcr.io/zeroclaw-labs/zeroclaw:latest 验证）：

  • Base: gcr.io/distroless/cc-debian13:nonroot（发布阶段；dev 阶段是 debian:trixie-slim）
  • ENTRYPOINT ["zeroclaw"], CMD ["daemon"]：不带参数运行时会启动守护进程和网关
  • EXPOSE 42617：daemon 和 gateway 都监听此端口
  • 数据目录： /zeroclaw-data（配置：/zeroclaw-data/.zeroclaw/config.toml，工作区：/zeroclaw-data/workspace）。在此处挂载命名卷或绑定卷以实现持久化；请注意，这不是 /root/.zeroclaw。
  • 配对： 发布的镜像默认 require_pairing = false，因此 /api/* 开箱即用即可接受未认证请求。启用配对时（在 /zeroclaw-data/.zeroclaw/config.toml 中将 require_pairing = true 并重启），守护进程会在首次启动时向 stdout 打印一次性代码，然后客户端在任何需要认证的端点响应之前，先通过带 X-Pairing-Code 头的 POST 请求将其发送到 /pair。
  • Web 仪表盘： 默认在发布的镜像中捆绑并提供。镜像设置 gateway.web_dist_dir = "/usr/share/zeroclawlabs/web/dist"，并在其中包含已构建的前端，因此网关开箱即用地提供 SPA 回退。资源位于 /zeroclaw-data 挂载点外部，因此 -v …:/zeroclaw-data 卷挂载无法将其遮蔽（ref #6400）。

使用捆绑的 Dockerfile 从源代码构建：

git clone https://github.com/zeroclaw-labs/zeroclaw
cd zeroclaw
docker build -t zeroclaw:local -f Dockerfile.debian .

已在 Windows + Docker 上验证：

  • 容器行为与 Linux 一致。 在 Windows 11 build 26200.8313 的 WSL Debian 中拉取并运行了 ghcr.io/zeroclaw-labs/zeroclaw:latest。镜像启动正常，网关监听 :42617，/health 返回有效的 JSON。将 require_pairing = true 设置到配置中并重启容器后，/pair 上的配对码流程也如文档所述正常工作。
  • 无需 Docker Desktop 的 Docker。 使用 wsl --install 启用 WSL2，然后在 WSL 发行版内执行 sudo apt install docker.io，即可直接获得守护进程；已验证可直接拉取并运行已发布的镜像，无需修改。

主机端最佳实践：通用的 Docker + WSL2 指南，不针对 zeroclaw 作运行时声明。在适用情况下，内容来源于 Microsoft Learn 和 Docker 官方文档：

  • 卷挂载。 将 Windows 端路径（-v C:/Users/...:/zeroclaw-data）绑定挂载到 Linux 容器会跨越 WSL2 ⇄ Windows 文件系统边界；Microsoft 在 WSL 文件系统 参考文档中说明了该布局以及跨 OS 路径的影响。为获得接近原生的性能，优先使用 Docker 命名卷（-v zeroclaw-data:/zeroclaw-data），或将工作区存放在 WSL 文件系统中（\\wsl$\Debian\home\...）。

  • 网络。 默认的 WSL2 网络使用 NAT，因此容器中的服务在经过 -p 转发后，可通过 Windows 上的 localhost:<port> 访问（已在 Windows 11 + WSL2 上验证）。如果你需要从局域网中的另一台机器访问该容器，或者运行依赖容器间 DNS 的多容器环境，请按照 Microsoft 的 Mirrored mode networking 参考，将其切换为镜像模式，并在 %USERPROFILE%\.wslconfig 中添加：

    [wsl2]
networkingMode=mirrored

  • Docker 下的守护进程，而不是任务计划程序。 在容器内没有 Windows 任务计划程序。请使用 Docker 的 restart policy，如上例所示使用 --restart=unless-stopped，用于守护进程模式启动。发布的镜像以 PID 1 / nonroot 用户运行；容器本身就是服务；不要在其中运行 zeroclaw service install。

  • 通过宿主 Docker socket 的技能沙箱。 ZeroClaw 的技能执行沙箱可以调用 Docker。如果你把 ZeroClaw 本身运行在容器中，并且希望技能沙箱也使用 Docker，请挂载宿主机的 Docker socket，这样子容器就会在宿主机 daemon 上运行，而不是嵌套使用 Docker-in-Docker：

    # PowerShell / cmd.exe: 使用单个前导斜杠。
# Git Bash / MINGW: 使用 //var/run/docker.sock 以绕过 MSYS 路径重写。
-v /var/run/docker.sock:/var/run/docker.sock

    请注意，挂载 Docker 套接字会授予容器内的任何内容以等同于 root 的主机访问权限；Docker 的 Protect the Docker daemon socket 页面说明了其中的权衡。在 Windows 版 Docker Desktop 上，主机套接字是 \\.\pipe\docker_engine；上面的 bind mount 语法会正确转换。该模式具有普遍性；本文档中尚未针对 zeroclaw 的技能沙箱专门进行基准测试。

  • 资源限制。 Windows 上的 Docker Desktop 通过 %USERPROFILE%\.wslconfig 分配 RAM/CPU，其默认值为主机内存的一半。完整的配置项在 Microsoft 的 WSL 中的高级设置配置 参考文档中有说明。对于单用户 ZeroClaw 部署，一个合理的起始资源范围是：

    [wsl2]
memory=8GB
processors=4

    如果你在同一个 WSL 发行版中运行高负载的 skill 工作负载或本地 LLM 推理，可以适当调大；这是容量规划建议，不是该镜像的硬性要求。

系统依赖

Windows 构建使用 MSVC 工具链。要从源代码构建，你需要：

  • Visual Studio Build Tools（或完整的 Visual Studio），并安装“使用 C++ 的桌面开发”工作负载
  • Rust 稳定版（通过 rustup）

如果你使用 选项 1，则不需要 Rust 工具链；该二进制文件是自包含的。选项 2 (setup.bat --prebuilt) 旨在使用相同的二进制路径，但当前脚本在进入预构建分支之前仍会检查 cargo；请参见上面的已知问题。

作为服务运行

在 Windows 上，ZeroClaw 会安装为名为 ZeroClaw Daemon 的 用户作用域计划任务。当前版本中没有 Windows Service / LocalSystem 选项；无论 zeroclaw service install 是在提升权限还是非提升权限的 shell 中运行，底层代码路径始终都会安装一个计划任务。

zeroclaw service install
zeroclaw service start

这会在你的用户帐户下的 Task Scheduler (taskschd.msc) 中创建一个任务，该任务会在登录时启动。通过以下方式管理它：

zeroclaw service status
zeroclaw service restart
zeroclaw service stop
zeroclaw service logs

关于 --service-init。 该 CLI 暴露了 --service-init [auto|systemd|openrc] 标志以实现跨平台一致性，但在 Windows 上它不起作用；始终使用计划任务路径。

日志写入 %USERPROFILE%\.zeroclaw\logs\（具体而言是 <config_dir>/logs/，其中 <config_dir> 默认值为 %USERPROFILE%\.zeroclaw\）。不过，计划任务包装脚本本身位于配置文件旁边的 %USERPROFILE%\.zeroclaw\zeroclaw-daemon.cmd。只有守护进程输出文件（daemon.stdout.log / daemon.stderr.log）会写入 logs\。

服务器 / 多用户安装。 原生 Windows 服务 / LocalSystem 支持已列入路线图，但尚未实现。目前，在服务器上，请以代理应运行的账户安装 ZeroClaw；计划任务路径会在该用户登录时启动它。如果你需要在任何用户登录之前启动它，请使用 Task Scheduler → ZeroClaw Daemon → Properties → General → “Run whether user is logged on or not.”

更新

手动（选项 1 路径）

使用新的 $ver 重新运行 Option 1 中的 PowerShell 安装块。新的 zip 会就地覆盖现有的 zeroclaw.exe。然后：

zeroclaw service restart

setup.bat

重新下载最新版本并重新运行 setup.bat --prebuilt（或你最初使用的其他标志）。然后：

zeroclaw service restart

Scoop

scoop update zeroclaw
zeroclaw service restart

从源代码

cd C:\path\to\zeroclaw
git pull
cargo install --locked --path . --force
zeroclaw service restart

卸载

停止并移除计划任务：

zeroclaw service stop
zeroclaw service uninstall

移除二进制文件：

:: 选项 1（手动预构建）或 setup.bat
rmdir /s /q "%USERPROFILE%\.zeroclaw\bin"

:: Option 3 (cargo install)
del "%USERPROFILE%\.cargo\bin\zeroclaw.exe"

:: Option 4 (Scoop)
scoop uninstall zeroclaw

移除 config、workspace 和 logs（可选；这将删除对话历史记录）：

rmdir /s /q "%USERPROFILE%\.zeroclaw"

此文档的先前版本引用了 %LOCALAPPDATA%\ZeroClaw\; 当前版本不使用该路径；仅使用 %USERPROFILE%\.zeroclaw\。

注意事项

  • 长路径。 某些 Windows 文件系统仍将路径长度限制为 260 个字符。如果你在源码构建期间遇到 path too long 错误，请启用长路径支持：

    reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f

  • SmartScreen。 未签名的二进制文件在从 Explorer（双击）首次启动时可能会触发 SmartScreen。右键 → 属性 → “Unblock” 是在我们添加已签名 MSI 之前的标准临时解决方法。从 PowerShell 或 cmd.exe 启动通常不会触发 SmartScreen。

  • 任务计划程序在空闲/电池时停止。 默认情况下，Windows 可能会在空闲或电池供电时终止计划任务。已安装的 ZeroClaw Daemon 任务会禁用这些条件，但如果你是通过较旧版本安装的，可以在 任务计划程序 → ZeroClaw Daemon → 属性 → 条件 下进行验证：

    • “仅在计算机接通交流电源时启动任务”：未选中
    • “如果计算机切换到电池供电则停止”: 未选中
    • “仅在计算机空闲时才开始任务”：未选中

  • OpenSSH 密码认证。 如果你通过 SSH 远程控制 Windows，而公钥未被接受，请将你的密钥放入 C:\Users\<user>\.ssh\authorized_keys（普通用户）或 C:\ProgramData\ssh\administrators_authorized_keys（以 Administrators 成员身份登录时）。

下一个