本指南覆盖 macOS、Linux、Windows 的主流安装方式。
- 这页适合谁：刚准备安装 NullClaw，或者要确认本机环境、容器部署、升级与卸载路径的人。
- 看完去哪里：安装完成后先看 配置指南；想直接跑一遍常用命令看 使用与运维；想先浏览 CLI 入口看 命令参考。
- 如果你是从某页来的：从 README 来，这页就是落地安装的第一站；从 命令参考 来，适合回头补齐本机安装与 PATH；从 开发指南 来，可把本页当作本地环境准备清单。
- 如果走源码构建：必须使用 Zig 0.16.0。
- Git（源码安装需要）。
检查 Zig 版本：
zig version输出必须是 0.16.0。
brew install nullclaw
nullclaw --help如果命令可用，说明安装成功。
从发布页下载 Windows .zip 压缩包并解压后，即可直接在命令行中运行其中的 nullclaw.exe。
比如检查nullclaw版本号的命令如下：
x:\path\nullclaw.exe --versionNullClaw 当前提供官方 OCI 镜像：ghcr.io/nullclaw/nullclaw。
容器内的持久化目录统一放在 /nullclaw-data：
- 配置文件：
/nullclaw-data/config.json - 工作区：
/nullclaw-data/workspace
镜像内自带的初始配置已经使用当前配置结构（agents.defaults.model.primary 和 models.providers），因此在你填入 provider 凭证之前，latest 也应能正常启动。
docker run --rm -it \
-v nullclaw-data:/nullclaw-data \
ghcr.io/nullclaw/nullclaw:latest status交互式初始化配置：
docker run --rm -it \
-v nullclaw-data:/nullclaw-data \
ghcr.io/nullclaw/nullclaw:latest onboard --interactive运行交互式 agent：
docker run --rm -it \
-v nullclaw-data:/nullclaw-data \
ghcr.io/nullclaw/nullclaw:latest agent运行 HTTP gateway：
docker run --rm -it \
-p 127.0.0.1:3000:3000 \
-v nullclaw-data:/nullclaw-data \
ghcr.io/nullclaw/nullclaw:latest仓库根目录自带 docker-compose.yml，默认直接使用官方镜像。
交互式初始化：
docker compose --profile agent run --rm agent onboard --interactive在官方容器流程里，workspace 提示直接回车即可保留挂载卷里的默认路径：
- 工作区：
/nullclaw-data/workspace
交互式 agent 会话：
docker compose --profile agent run --rm agent长期运行 gateway：
docker compose --profile gateway up -d gatewayProfile 含义：
agent：一次性的交互式 CLI 容器gateway：长期运行的 HTTP gateway，默认发布到宿主机回环地址3000
如果你需要局域网或公网访问，请显式修改发布地址，并先阅读 安全指南。
如果你要固定版本标签，或者以后切换到其他镜像仓库，可以覆盖 NULLCLAW_IMAGE：
NULLCLAW_IMAGE=ghcr.io/nullclaw/nullclaw:v2026.3.11 docker compose --profile gateway up -d gatewaygit clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all构建产物：
zig-out/bin/nullclaw
有三种常见路径：
- 直接下载官方发布的 Android / Termux 预构建二进制
- 在手机上的 Termux 里原生构建
- 在另一台机器上交叉编译 Android 二进制
pkg update
pkg install git zig
git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig version
zig build -Doptimize=ReleaseSmall
./zig-out/bin/nullclaw --help说明：
- 必须使用 Zig 0.16.0
- 如果
zig build一开始就失败，先确认 Zig 版本 - Termux 原生构建使用当前环境的 native target，通常不需要手动传
-Dtarget - 在 Android / Termux 上，建议先跑前台命令（如
agent、gateway），确认没问题后再考虑后台托管 - 官方 release 提供
aarch64、armv7、x86_64的 Android / Termux 预构建二进制 - 更完整的说明和排错见 Termux 指南。
如果你是在另一台机器上给 Android / Termux 设备构建，需要显式传入 Zig target，并提供 Android 的 libc/sysroot 文件；只传 -Dtarget 还不够：
zig build -Dtarget=aarch64-linux-android.24 -Doptimize=ReleaseSmall --libc /path/to/android-libc-aarch64.txt常见 Android targets：
aarch64-linux-android.24arm-linux-androideabi.24，配合-Dcpu=baseline+v7ax86_64-linux-android.24
选择与目标手机或模拟器架构匹配的 target。完整的 --libc 文件生成示例可参考 .github/workflows/release.yml。官方 release 也附带基于 Android API 24 构建的对应二进制。
zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# bash 用户改为 ~/.bashrc
source ~/.zshrczig build -Doptimize=ReleaseSmall -p "$HOME\.local"
$bin = "$HOME\.local\bin"
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not ($user_path -split ";" | Where-Object { $_ -eq $bin })) {
[Environment]::SetEnvironmentVariable("Path", "$user_path;$bin", "User")
}
$env:Path = "$env:Path;$bin"从发布页下载 Windows .zip 压缩包并解压后，可在管理员权限的 Powershell 中执行如下命令，将 nullclaw.exe 所在目录加入 Windows 的 PATH 环境变量：
$old = [Environment]::GetEnvironmentVariable("Path", "Machine")
$new = "$old;x:\path\to\nullclaw"
[Environment]::SetEnvironmentVariable("Path", $new, "Machine")nullclaw --help
nullclaw --version
nullclaw status若 status 能正常输出组件状态，说明安装与运行环境基本可用。
brew update
brew upgrade nullclaw
brew uninstall nullclaw- 升级：
nullclaw update - 卸载：直接删除nullclaw二进制文件。 检查系统变量PATH，若存在就将nullclaw二进制文件的所在目录从中删除。
- 升级：
git pull后重新执行zig build -Doptimize=ReleaseSmall - 卸载：删除安装位置中的
nullclaw二进制，并移除 PATH 配置行