NullClaw 完整安装指南：macOS、Linux、Windows、Docker 与 Android/Termux 四路部署实战-平芜编程栈

人工智能
AI Agent
大模型
自主智能体
工具调用
RAG
Agent 记忆
MCP Clients

【免费下载链接】nullclaw

Fastest, smallest, and fully autonomous AI assistant infrastructure written in Zig

项目地址：https://gitcode.com/gh_mirrors/nu/nullclaw

本文以 NullClaw 官方中文安装文档（docs/zh/installation.md）为骨架，系统覆盖 Homebrew 二进制、官方 OCI 容器镜像、Zig 源码构建与 Android/Termux 四种主流安装路径，并结合仓库内的 Dockerfile、docker-compose.yml、build.zig 等源码级实现展开说明。读完本文，你将能根据自身平台选对安装方式、完成安装验证，并掌握升级、卸载与 PATH 配置的完整闭环。

前置要求：精确锁定 Zig 0.16.0 与 Git

安装前只需确认两样东西：

Zig 0.16.0（精确版本，仅源码构建需要）：NullClaw 的构建脚本固定在 Zig 0.16.0 上。版本不一致会直接导致构建失败，典型报错是build.zig.zon中出现expected string literal，这通常不是源码问题，而是 Zig 版本不匹配。Debian 系统的手动安装步骤见 Zig 安装指南。
Git：源码安装需要克隆仓库。

检查 Zig 版本：

zig version

输出必须是0.16.0。

从构建脚本 build.zig 可以印证这一点：CI 与容器构建通过.github/scripts/install-zig.sh下载并校验指定版本的 Zig，并在构建前执行test "$(zig version)" = "0.16.0"硬校验（见 Dockerfile）。同时build.zig还会在启用 SQLite 时对vendor/sqlite3/下的文件做 SHA-256 完整性校验（build.zig），版本不对时解析build.zig.zon会直接报错。

如果你是在全新的 Debian 上准备源码构建，可参考 Zig 安装指南的手动安装路径：apt update后安装ca-certificates wget xz-utils，从 Zig 官方发布页下载zig-x86_64-linux-0.16.0.tar.xz，用官方校验和验证压缩包，解压后将其加入PATH，最后用zig version确认输出为0.16.0。

方式一：使用预编译二进制

适合不想接触 Zig toolchain、只想尽快跑起来的用户。

Homebrew（macOS / Linux 推荐）

brew install nullclaw nullclaw --help

如果nullclaw命令可用，说明安装成功。Homebrew 直接安装预构建包，本机完全不需要 Zig toolchain。

Windows：从发布页下载 zip

从发布页下载 Windows.zip压缩包并解压后，即可直接在命令行中运行其中的nullclaw.exe。检查版本号：

x:\path\nullclaw.exe --version

方式二：官方容器镜像（Docker / Podman）

镜像与持久化目录约定

NullClaw 提供官方 OCI 镜像：ghcr.io/nullclaw/nullclaw。容器内持久化目录统一放在/nullclaw-data：

配置文件：/nullclaw-data/config.json
工作区：/nullclaw-data/workspace

镜像自带的初始配置已使用当前配置结构（agents.defaults.model.primary与models.providers），因此在你填入 provider 凭证之前，latest标签也应能正常启动。从 Dockerfile 可以看到镜像内置的初始config.json内容：

{ "agents": { "defaults": { "model": { "primary": "openrouter/anthropic/claude-sonnet-4" } } }, "models": { "providers": { "openrouter": {} } }, "gateway": { "port": 3000, "host": "::", "allow_public_bind": true } }

也就是说，镜像在首次启动时即可解析出默认模型路由，只差一个 provider 凭证。运行时默认以非 root 用户（uid/gid 65534）执行（Dockerfile），镜像声明EXPOSE 3000、ENTRYPOINT ["nullclaw"]，默认命令为gateway --port 3000 --host ::（Dockerfile）；容器内的NULLCLAW_HOME=/nullclaw-data、NULLCLAW_WORKSPACE=/nullclaw-data/workspace环境变量保证了配置与工作区始终落在持久化卷上。

单次命令（docker run）

查看状态：

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（将容器 3000 端口发布到宿主机回环地址）：

docker run --rm -it \ -p 127.0.0.1:3000:3000 \ -v nullclaw-data:/nullclaw-data \ ghcr.io/nullclaw/nullclaw:latest

注意：-it与--rm组合适合单次交互；长期运行场景建议用下面的 Compose 方式，以便获得服务化重启与健康检查。

Docker Compose

仓库根目录自带 docker-compose.yml，默认直接使用官方镜像（可通过NULLCLAW_IMAGE覆盖）。

交互式初始化：

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 gateway

Profile 含义：

agent：一次性的交互式 CLI 容器
gateway：长期运行的 HTTP gateway，默认发布到宿主机回环地址3000

从 docker-compose.yml 的源码可以看到几个对部署很有用的细节：

init-data服务会在 agent / gateway 启动前初始化/nullclaw-data/workspace目录并修正属主（docker-compose.yml），uid/gid 可通过NULLCLAW_UID/NULLCLAW_GID覆盖（默认 65534，即镜像内非 root 用户）。
gateway 服务默认监听0.0.0.0:3210，同时通过${NULLCLAW_BIND:-127.0.0.1}:${NULLCLAW_PORT:-3210}控制发布地址——即默认只发布到宿主机回环地址，端口可通过NULLCLAW_PORT覆盖（docker-compose.yml）。
gateway 服务带 healthcheck，通过wget http://127.0.0.1:${NULLCLAW_PORT:-3210}/health每 30 秒探测一次（docker-compose.yml）。
挂载卷包括命名卷nullclaw-data与宿主机./workspace目录，方便直接查看工作区产出（docker-compose.yml）。

如果你需要局域网或公网访问，请显式修改发布地址，并先阅读安全指南（官方默认绑定回环地址是有意为之的安全默认值）。

如果你要固定版本标签，或者以后切换到其他镜像仓库，可以覆盖NULLCLAW_IMAGE：

NULLCLAW_IMAGE=ghcr.io/nullclaw/nullclaw:v2026.3.11 docker compose --profile gateway up -d gateway

仓库 Makefile 还提供了一组与 Compose 对应的快捷目标：make build、make config（等价于onboard --interactive）、make up、make down、make run、make agent、make status、make shell、make logs。其中镜像构建目标默认使用releaseDocker target；若想以 root 身份运行（明确的自主模式 opt-in），可执行make build DOCKER_TARGET=release-root IMAGE=nullclaw:root，对应 Dockerfile 中的release-root阶段。

方式三：源码构建（通用）

git clone https://gitcode.com/gh_mirrors/nu/nullclaw cd nullclaw zig build -Doptimize=ReleaseSmall zig build test --summary all

构建产物：

zig-out/bin/nullclaw

zig build test --summary all会运行整套测试（compat 测试、库测试与可执行文件测试，见 build.zig），建议提交前或升级后跑一遍确认环境正常。

几个值得了解的源码级事实：

-Doptimize=ReleaseSmall是官方文档推荐的优化模式。非 Debug 优化下，构建脚本会自动开启strip、关闭 unwind tables 与 frame pointer，以进一步缩小二进制（build.zig）。
构建选项-Dchannels用于裁剪渠道：token 为all|none|cli|telegram|discord|slack|whatsapp|matrix|mattermost|irc|imessage|email|lark|dingtalk|wechat|weixin|wecom|line|onebot|qq|maixcam|signal|nostr|web|max，默认all（build.zig）。
构建选项-Dengines用于选择 memory 引擎：token 为base|minimal|all|none|markdown|memory|api|sqlite|lucid|redis|lancedb|postgres|clickhouse|kg，默认base,sqlite（build.zig）。选择sqlite/lucid/lancedb/kg会自动拉起 vendored SQLite 及其校验。
如需静态链接可加-Dstatic；-Dembedded_wasm3默认开启，可传-Dembedded_wasm3=false关闭内嵌 wasm3 运行时；-Dversion=<v>可把自定义版本串嵌入二进制（build.zig），版本字符串最终通过 src/version.zig 暴露给--version输出。

方式四：Android / Termux

在移动端有三种常见路径：

直接下载官方发布的 Android / Termux 预构建二进制
在手机上的 Termux 里原生构建
在另一台机器上交叉编译 Android 二进制

官方 release 提供aarch64、armv7、x86_64的 Android / Termux 预构建二进制。更完整的说明和排错见 Termux 指南。

Termux 原生构建

pkg update pkg install git zig git clone https://gitcode.com/gh_mirrors/nu/nullclaw 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），确认没问题后再考虑后台托管；前台验证可用./zig-out/bin/nullclaw agent与./zig-out/bin/nullclaw gateway --host 127.0.0.1 --port 3001。

低依赖构建路径：如果 SQLite 的拉取或构建在 Termux 里失败，先走轻量引擎集：

zig build -Doptimize=ReleaseSmall -Dengines=base

-Dengines=base包含markdown,memory,api,none，不依赖 SQLite（对应 build.zig 中的enableBase()）。对内存和依赖都更紧的 Android 设备，这通常是更稳妥的第一步；也可以显式指定-Dengines=markdown,memory。

常见错误：build.zig.zon提示expected string literal。这类报错最常见原因是 Zig 版本不对，而不是 NullClaw 源码本身有问题。排查顺序：运行zig version→ 确认输出是0.16.0→ 不是就先替换 Zig 再重新构建。不要为了兼容旧 Zig 去本地修改build.zig.zon——项目当前就固定在 Zig 0.16.0。

为 Android 交叉编译

如果你在另一台机器上给 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.24
arm-linux-androideabi.24，配合-Dcpu=baseline+v7a
x86_64-linux-android.24

选择与目标手机或模拟器架构匹配的 target。从 build.zig 可以确认，构建脚本对 Android ABI 有强制环境检查：除非设置了TERMUX_VERSION或通过--libc（或ZIG_LIBC）传入 libc/sysroot 文件，否则会在配置阶段直接报错退出。完整的--libc文件生成示例可参考 .github/workflows/release.yml。官方 release 也附带基于 Android API 24 构建的对应二进制。

将二进制加入 PATH

使用编译后的二进制文件

macOS / Linux（zsh / bash）

zig build -Doptimize=ReleaseSmall -p "$HOME/.local" echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # bash 用户改为 ~/.bashrc source ~/.zshrc

-p "$HOME/.local"会把zig-out/bin/nullclaw安装到~/.local/bin，与 Homebrew 的~/.local约定保持一致。

Windows（PowerShell）

zig 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）

从发布页下载 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能正常输出组件状态，说明安装与运行环境基本可用。更完整的首次启动验证流程（onboard --interactive→agent -m "你好，nullclaw"→gateway）见使用与运维；想要按子命令逐一核对，见命令参考。

升级与卸载

使用二进制文件

Homebrew（macOS / Linux 推荐）

brew update brew upgrade nullclaw brew uninstall nullclaw

Windows（CMD）

升级：nullclaw update（该命令还支持--check仅检查、--yes自动确认，见命令参考）
卸载：直接删除nullclaw二进制文件；检查系统变量 PATH，若存在就将 nullclaw 二进制文件的所在目录从中删除。

源码安装

升级：git pull后重新执行zig build -Doptimize=ReleaseSmall，再按需重跑zig build test --summary all做回归验证。
卸载：删除安装位置中的nullclaw二进制，并移除 PATH 配置行。

下一步

安装完成只是起点，建议按官方文档路径继续：

要开始初始化配置：继续看配置指南，先生成可运行的config.json。
要快速跑通一遍：继续看使用与运维，按首次启动流程验证安装结果。
要核对 CLI 命令：继续看命令参考，确认onboard、agent、gateway等入口。

相关页面：中文文档入口 · Termux 指南 · 配置指南 · 使用与运维 · 命令参考

人工智能
AI Agent
大模型
自主智能体
工具调用
RAG
Agent 记忆
MCP Clients

【免费下载链接】nullclaw

Fastest, smallest, and fully autonomous AI assistant infrastructure written in Zig

项目地址：https://gitcode.com/gh_mirrors/nu/nullclaw

点击查看免费下载

NullClaw 完整安装指南：macOS、Linux、Windows、Docker 与 Android/Termux 四路部署实战

【免费下载链接】nullclaw

前置要求：精确锁定 Zig 0.16.0 与 Git

方式一：使用预编译二进制

Homebrew（macOS / Linux 推荐）

Windows：从发布页下载 zip

方式二：官方容器镜像（Docker / Podman）

镜像与持久化目录约定

单次命令（docker run）

Docker Compose

方式三：源码构建（通用）

方式四：Android / Termux

Termux 原生构建

为 Android 交叉编译

将二进制加入 PATH

使用编译后的二进制文件

macOS / Linux（zsh / bash）

Windows（PowerShell）

直接使用下载的二进制文件（Windows）

安装验证

升级与卸载

使用二进制文件

Homebrew（macOS / Linux 推荐）

Windows（CMD）

源码安装

下一步

【免费下载链接】nullclaw

相关推荐

NullClaw 安装完全指南：macOS、Linux、Windows 与 Android/Termux 四路径实战

TDgpt 安装部署完全指南：Docker、云服务与 Linux/Windows 安装包实战

NNI 安装完全指南：Linux/macOS/Windows 与 Docker 多方式部署及验证

Bootstrap Icons 中的 Alarm 图标：从 SVG 源文件到图标字体与 Sprite 的完整使用指南

5G网络仿真中移动性管理建模指南：切换、波束与参数调优实战

GEOFlow托管渠道站点搭建完全指南：子域名分配与发布配额让一套后台管多站

Automation Workflow设计：让AI自己跑起来，TaoToken 统一 Key 接入实战

【多模态大模型】端侧语音大模型minicpm-o：手机上的 GPT-4o 级多模态大模型，配 TaoToken 统一 Key 打通 API 调用

财务数字化岗位秋招，哪些证书和技能值得准备？