折腾 OpenClaw 的时候我一开始也图省事直接用系统自带的依赖跑官方脚本结果半个月后升级一次就把环境给搞坏了。后来狠下心用 Nix 重新装了一遍才发现 OpenClaw 这种要跟本机各种工具打交道的应用本来就该用 Nix 这类声明式包管理来伺候。这篇就完整记录我怎么用 Nix 把 OpenClaw 从零装好、跑起来中间踩过的坑也一并写清楚给同样准备入坑的人一份能直接抄的作业。如果你已经在用 Docker 或者源码方式跑过 OpenClaw但被版本混乱、依赖冲突、升级翻车这些问题烦过那这篇文章很适合你如果你刚听说 OpenClaw不知道它是什么我会先用一小节讲明白。读完你应该能回答这几个问题为什么 OpenClaw 值得用 Nix 装、Nix 本身怎么装、OpenClaw 的 Nix 安装流程怎么走、安装过程中哪些环节容易出幺蛾子。1. 先说清楚OpenClaw 为什么值得用 Nix 来装1.1 OpenClaw 是什么它对环境有多挑剔OpenClaw 可以理解成一个面向真实任务的智能体运行时。大模型负责理解你的话OpenClaw 负责把理解结果转化成真实的系统操作查文件、跑命令、控制 Chrome 浏览器、调用本地 Ollama 模型、接上微信收发消息这些事情都能通过它的 skill 机制扩展出去。它的定位决定了它不是一个装完就丢在后台的服务而是一个必须跟宿主机上各种软件深度协作的胶水层。这种到处都要伸手的形态让 OpenClaw 对环境特别敏感。它依赖一堆命令行工具、动态链接库、Python 或 Node 运行时还要能发现浏览器、模型服务、甚至是某些即时通讯软件的本地登录态。如果你用传统方式把所有依赖直接灌进系统全局目录刚开始可能没什么感觉但过一段时间只要系统里任何一个相关软件升级了OpenClaw 就很容易变成第一个被波及的对象。我在笔记本上就是活生生的例子一次系统更新把我本来的 Python 版本顶掉了OpenClaw 的几个 skill 直接全部罢工。1.2 Nix 相比 Docker 和源码安装的取舍很多人会问直接用 Docker 不是更省心实际用下来Docker 和 Nix 解决的是不同层面的问题。安装方式隔离性本机资源访问升级与回滚适合场景Docker很强需要额外的挂载、端口和网络配置镜像层可回滚但容器内状态管理麻烦只想快速跑通不打算让 OpenClaw 操作宿主机工具源码安装弱直接无隔离基本靠手动依赖容易污染系统想改源码做二次开发能接受环境被折腾Nix较强且能访问本机资源直接访问本机设备和命令事务式升级一条命令回滚既要干净环境又要 OpenClaw 能调用本机功能我最后选 Nix核心原因是它把环境当成代码来管理。同样一套配置拿到另一台机器上装出来的依赖版本、目录结构、启动命令完全一致不会再出现我这边能跑、你那边跑不了的尴尬。另一个让我很受用的点是Nix 的升级不是覆盖式的而是先把新版本装好确认没问题之后再切换一旦发现不对一条命令就能回到旧版本。对 OpenClaw 这种经常要跟模型版本、浏览器驱动、skill 配置打交道的应用来说这个能力太关键了。2. 装 Nix 之前必须确认的几件事2.1 系统发行版与 Nix 安装模式的对应关系在动手之前先搞清楚你所在的系统环境因为 Nix 在不同系统上的安装方式差别还挺大。LinuxDebian/Ubuntu/Fedora 等官方推荐多用户安装方式。执行安装脚本后Nix 会以 daemon 的形式运行普通用户都能使用日常操作不需要 root。macOS同样支持多用户安装App 和命令行工具都能通过 Nix 管理。NixOS系统本身已经内置 Nix不需要额外装包管理器直接在系统配置里声明 OpenClaw 即可。WindowsNix 不能原生跑在 Windows 上最接近官方推荐的路子是在 WSL2 里装一个 Ubuntu然后在 Ubuntu 里走 Linux 的安装流程。很多人在 Windows 上折腾 OpenClaw其实最终都是通过 WSL2 进来的。以最常见的 Linux 多用户安装为例命令很简单sh (curl -L https://nixos.org/nix/install) --daemon安装脚本会帮你完成大部分工作装完重新打开终端或者执行下面的命令让 Nix 环境立即生效. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh装完后检查一下 Nix 版本确认安装成功nix --version这里要提醒一句如果系统里已经有旧版本 Nix不要直接覆盖安装先看一下 /nix/store 里是否残留重要数据。我在一台备用机上没注意这个旧 profile 里的包在新版本下路径全变了最后只能一个个重建。2.2 OpenClaw 的运行时依赖与版本敏感点OpenClaw 的核心进程需要依赖 Python 运行时外围工具可能还会用到 Node、git、curl 这些基础命令。传统安装方式会要求你手动保证这些依赖存在但用 Nix 之后OpenClaw 对运行时的大部分需求会被 Nix 自动搞定你只需要关心几个最容易忽略的地方。第一个是数据目录。OpenClaw 的配置、skill、会话记录通常存放在~/.openclaw或者~/.config/openclaw升级和回滚都只会改二进制文件不会动数据目录。所以在升级之前最重要的不是备份系统而是备份这个目录。第二个是模型后端地址。如果你用本地 OllamaOpenClaw 需要能访问localhost:11434如果你用远程 API需要在配置里写清楚 endpoint。Nix 不会替你管理这些业务配置它只负责把程序本身和环境依赖装好。还有一点值得注意OpenClaw 的一些 skill 需要操作 Chrome 浏览器。Nix 安装的浏览器路径往往不在系统默认的 PATH 里需要单独把CHROME_BIN环境变量指过去。这一条很多人都会踩后面第 4 章我会给出具体的配置方式。3. 最小可用的 Nix 安装流程从 flake 开始3.1 拉取 OpenClaw 项目仓库并生成 flake现在 Nix 社区基本都在用 flake 这套新机制OpenClaw 如果提供 Nix 支持一般也是以 flake 的形式给出。在开始之前先确保你的 Nix 开启了 flake 功能。mkdir -p ~/.config/nix cat ~/.config/nix/nix.conf EOF experimental-features nix-command flakes EOF配置好后不需要下载任何东西nix命令本身就支持直接运行远程 flake。OpenClaw 的仓库如果托管在 GitHub最简单的尝鲜方式是这样nix run github:openclaw/openclaw -- --version如果仓库里的 flake 配置正确这条命令会自动拉取源码、构建依赖并运行程序。第一次执行会很慢因为 Nix 需要把完整依赖树都构建或下载下来后面再跑就是秒开了。我习惯先把仓库克隆到本地再做二次开发和配置git clone https://github.com/openclaw/openclaw.git cd openclaw如果仓库里已经有写好的flake.nix你在本地目录里直接执行nix develop就能进入一个所有依赖都齐备的开发环境。仓库没有提供 flake 的话也可以自己写一个简单的入口。下面是一个最小可用的flake.nix示意{ inputs { nixpkgs.url github:NixOS/nixpkgs/nixos-unstable; openclaw.url github:openclaw/openclaw; }; outputs { self, nixpkgs, openclaw, ... }: let system x86_64-linux; pkgs import nixpkgs { inherit system; }; openclawPkg openclaw.packages.${system}.default; in { devShells.${system}.default pkgs.mkShell { packages [ openclawPkg ]; shellHook echo OpenClaw development environment ready. ; }; }; }如果你用的是 Apple Silicon记得把x86_64-linux换成aarch64-darwin或aarch64-linux。这不是什么高级技巧但对刚接触 flake 的人来说最容易错的就是 system 参数。3.2 进入开发环境并完成首次启动在项目目录里执行nix develop进入开发环境后你的PATH里已经被注入了 OpenClaw 所需的全部命令。第一次使用时先初始化配置openclaw initinit会在数据目录里生成一份默认配置文件里面包含模型后端、日志级别、监听端口这些基础项。打开配置文件把model.provider改成你实际在用的后端。如果你本机已经装好了 Ollama可以继续保持默认的localhost地址OpenClaw 会自动识别。完成配置后启动服务试试openclaw serve看到类似OpenClaw is running on http://127.0.0.1:8899的日志说明主程序已经起来了。第一次启动不需要急着配一堆 skill先把这一个最小闭环跑通后面验证功能才有基础。这里补充一个细节很多人在nix develop里启动 OpenClaw 时会发现某些系统级命令找不到比如 Chrome 或者本机安装的 Python 模块。这是因为 Nix 的 devShell 默认带的是 Nix 自己管理的依赖集不会自动读取宿主机的/usr/bin。如果你确定要让某个系统命令穿透进来可以依赖pkgs.buildEnv或写一个 wrapper但这属于进阶用法。新手阶段先保证 OpenClaw 主进程能跑起来就够了。3.3 把 OpenClaw 装进用户 profilenix develop的方式适合开发调试但每次都要先进入目录、再敲命令日常使用不太方便。更推荐的做法是用 profile 把 OpenClaw 变成全局可用的命令。nix profile install github:openclaw/openclaw执行之后Nix 会在/nix/var/nix/profiles/per-user/你的用户名/下创建一个指向当前 OpenClaw 版本的 profile并把这个路径加入你的 PATH。之后再打开任意终端都能直接执行openclaw命令不需要再进 devShell。用 profile 管理和直接用系统包管理器安装最大的区别在于可回滚。每次nix profile install、nix profile upgrade之后Nix 都会记录当前 profile 的状态一旦新版本出问题你可以用nix profile history查看历史记录然后nix profile rollback回到上一个状态。这是传统安装方式给不了的体验。卸载也简单nix profile remove openclaw不过要记住nix profile remove只是把程序从 PATH 中摘掉数据目录~/.openclaw里的配置和 skill 不会被动。真正要清干净的话还需要手动删除数据目录这个我在最后一章会细说。4. 在 NixOS 上把 OpenClaw 做成系统级服务4.1 用 NixOS module 管理 OpenClaw 配置如果你用的是 NixOS没必要再用nix profile手动装了直接在系统配置里声明更干净。绝大多数 NixOS 用户会把 OpenClaw 写进/etc/nixos/configuration.nix{ config, pkgs, ... }: { environment.systemPackages with pkgs; [ openclaw ]; }然后执行sudo nixos-rebuild switch这条命令会把 OpenClaw 装进系统环境所有用户都能使用。不过这里有个关键点放在 systemPackages 里的应用它的数据目录还是属于具体用户。也就是说你用哪个用户执行openclaw init配置就落在哪个用户的 home 目录下和系统级安装并不冲突。如果你希望 OpenClaw 以系统服务的形式常驻后台比如开机自启官方或者社区可能提供了 NixOS module类似services.openclaw { enable true; user myuser; group users; port 8899; };启用服务后用systemctl status openclaw查看运行状态。这里我想特别提醒如果你之前已经用nix profile install装过一版又在 NixOS 系统配置里加了一个 OpenClaw那么两个版本的openclaw命令可能会同时出现在 PATH 里具体执行哪个取决于 PATH 的搜索顺序。这种情况下建议二选一不要混着用不然 skill 装的目录和数据目录会被两个版本抢来抢去非常容易出问题。4.2 关联 Ollama、Chrome 等外部工具时的 Nix 配置OpenClaw 不是孤岛它要发挥作用就得连通本机的 Ollama 和 Chrome 这类工具。NixOS 上这些工具的路径和普通发行版不太一样需要显式配置。先看 Ollama。如果 Ollama 已经在你本机跑着默认监听 11434 端口OpenClaw 访问http://127.0.0.1:11434即可不需要额外设置。但如果 NixOS 启用了防火墙就需要放行这个端口networking.firewall.allowedTCPPorts [ 11434 ];再看 Chrome。NixOS 上 Chrome 或者 Chromium 一般是通过pkgs.chromium安装的可执行文件路径在/nix/store/...-chromium/bin/chromium。问题是这个 store 路径包含一串哈希不固定你不应该硬编码。解决办法是通过环境变量把路径交给 OpenClawenvironment.variables { CHROME_BIN ${pkgs.chromium}/bin/chromium; };这样写的好处是无论 Nix 升级后 chromium 的 store 路径怎么变CHROME_BIN始终指向当前版本。有些 skill 还会依赖系统里的unzip、ffmpeg、imagemagick这类小工具。在 NixOS 上这些也需要加到environment.systemPackages里。我的经验是先跑一次 OpenClaw 的某个 skill看它报哪个命令找不到再回过来补包。不要一开始把所有能想到的包装一遍那样只会让系统环境越来越臃肿。5. 安装现场最容易翻车的三个细节5.1 二进制缓存签名与构建超时问题Nix 装包时会优先从二进制缓存拉取预编译好的结果拉不到才会走本地源码编译。OpenClaw 这类更新比较快的项目很容易出现缓存还没有生成或者 hash 不一致的情况。最常见的报错之一是hash mismatch in fixed-output derivation。出现这个错通常是因为你在本地改了 flake 的版本但没有同步更新nix-prefetch-url计算出的 hash。解决办法很简单把 flake 里的hash字段注释掉跑一次构建让 Nix 告诉你真实的 hash再把值填回去。另一种情况是构建超时。OpenClaw 的依赖树里有不少包需要从源码编译机器性能一般的话一个包编十几分钟很正常。如果构建任务卡在某个环节迟迟不动先别急着认为死机了可以检查 Nix 的构建进程ps aux | grep nix如果确认是在编译耐心等即可。想缩短构建时间可以配置max-jobs让 Nix 并行度更高比如nix run github:openclaw/openclaw --max-jobs 4要注意--max-jobs只影响构建任务的并行数量不能提高单任务的构建速度。5.2 沙箱导致 Python 依赖打包失败Nix 在 Linux 上默认启用构建沙箱构建过程不能访问网络。这本来是为了保证可复现性但 OpenClaw 这种大量依赖 Python 生态的应用某些依赖在构建阶段需要从 PyPI 下载资源如果构建脚本里没有显式声明 fixed-output derivation就会在沙箱里卡住。我在第一次构建 OpenClaw 时卡在一个叫pydantic-core的依赖上报错信息是网络访问被拒绝。后来搜了一圈发现这不是我一个人的问题而是构建沙箱下 Python wheel 下载的经典问题。解决办法有两个层面如果项目本身已经通过buildPythonPackage或poetry2nix管理依赖不要自己去改动它直接用项目提供的 flake 构建这些工具已经把每一个外部资源声明成了 fixed-output derivation沙箱网络限制不影响它。如果是自己写 derivation依赖了某个未声明的fetchurl那构建脚本必须显式使用fetchurl并给出 hash不能在 build phase 里临时用pip install。有些教程会让新手直接关闭沙箱nix build --option sandbox false这确实能绕过去但它会破坏可复现性我只建议在本地调试时临时用一下不要写进任何依赖配置里。5.3 升级 OpenClaw 版本时的状态目录迁移Nix 的升级思路是换掉整个应用包但 OpenClaw 的数据目录往往还保留着旧版本的痕迹。升级前不处理数据目录升级后轻则 skill 列表异常重则直接起不来。我现在的固定流程是这三步先跑openclaw doctor看看当前配置和 skill 有没有明显问题。备份数据目录cp -r ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)。升级后立刻openclaw doctor检查一次再做一次冒烟测试。版本升级的具体命令取决于安装方式。用 profile 装的nix profile upgrade openclaw用 flake 直接跑的nix run github:openclaw/openclaw -- --version如果发现升级后 skill 的路径失效通常是因为 skill manifest 里记录的 Python 解释器路径还指向旧 store 路径。不要手工去改 store 里的文件重新装一遍对应 skill 是最快的恢复方式。我在升级 OpenClaw 后习惯顺手把所有第三方 skill 重装一次避免路径残留的坑。6. 装完之后怎么验证、怎么回滚、怎么卸载6.1 冒烟测试用一个真实任务跑通安装结束不代表可以放心使用我建议用一次真实任务做冒烟测试。启动 OpenClaw 后在终端里给它发一条简单指令比如openclaw run 在 /tmp 下创建一个名为 hello.txt 的文件内容写上 OpenClaw installed by Nix正常情况下OpenClaw 会调用本地的 shell 工具完成操作并返回执行结果。你随后检查一下/tmp/hello.txt是否存在且内容正确就能确认核心链路是通的。如果中途报错不要慌先看日志。OpenClaw 的日志文件默认在数据目录的logs/下面执行tail -n 100 ~/.openclaw/logs/openclaw.log常见的冒烟测试失败原因有三种模型后端没连通、当前用户没有文件写入权限、配置里的工作目录不存在。这三种都能在日志里直接看到线索。6.2 skill 与外部通道的快速连通实验冒烟测试通过后可以测一下 skill 机制。OpenClaw 的 skill 可以从社区或官方仓库安装类似clawhub这个名称的出现频率很高通常可以这样装openclaw skill install clawhub:skill-name装完后用openclaw skill list确认 skill 已经加载。如果你想测试外部通道我建议先测 Ollama因为它的链路最短。在本地跑一个模型然后让 OpenClaw 调用它回答一个问题。如果 OpenClaw 与 Ollama 能对话说明模型集成没问题。Chrome 控制的测试也不要跳过。装一个和浏览器相关的 skill再让 OpenClaw 打开一个指定网页。这个测试能同时验证CHROME_BIN环境变量是否正确、浏览器驱动能不能正常工作。因为环境变量在 Nix 环境里很容易配错这个测试值得做。6.3 回滚和卸载的三种姿势如果升级后发现问题回滚比修复更省时间。profile 安装版先nix profile history看历史再nix profile rollback回到上一个可用的 profile。NixOS 系统版直接sudo nixos-rebuild switch --rollback整个系统回到上一次构建状态。源码本地版因为 flake 本身是可复现的切回旧版本只需要改 flake.lock 或重新 checkout 旧 commit再走一遍构建流程。卸载时要看你是哪种安装方式# profile 安装版 nix profile remove openclaw # NixOS 系统版删除 configuration.nix 里的 openclaw 后 sudo nixos-rebuild switch卸载程序后~/.openclaw数据目录一般不会被自动清理。想彻底卸载的话rm -rf ~/.openclaw最后可以跑一次nix store gc把没有 profile 引用的旧版本包清掉释放 /nix/store 空间。这个动作不会影响其他应用因为它只清理不再被任何 profile、用户环境引用的 store 路径。从个人经验来说用 Nix 安装 OpenClaw 之后最大的感受是终于可以大胆折腾了。以前每次升级都担心依赖搞坏系统现在升级前该备份备份该测试测试翻车了大不了 rollback心理负担小很多。如果你也是那种喜欢把环境固化成代码的人建议把 OpenClaw 的配置文件、flake.nix、还有安装笔记放进自己的 dotfiles 仓库一起管理这样换电脑时恢复成本几乎为零。到这一步OpenClaw 在 Nix 环境下的安装链路就算完全打通了接下来你可以放心去折腾 skill 和各种外部工具集成。
用Nix优雅管理OpenClaw：从环境安装到依赖隔离的完整实践
折腾 OpenClaw 的时候我一开始也图省事直接用系统自带的依赖跑官方脚本结果半个月后升级一次就把环境给搞坏了。后来狠下心用 Nix 重新装了一遍才发现 OpenClaw 这种要跟本机各种工具打交道的应用本来就该用 Nix 这类声明式包管理来伺候。这篇就完整记录我怎么用 Nix 把 OpenClaw 从零装好、跑起来中间踩过的坑也一并写清楚给同样准备入坑的人一份能直接抄的作业。如果你已经在用 Docker 或者源码方式跑过 OpenClaw但被版本混乱、依赖冲突、升级翻车这些问题烦过那这篇文章很适合你如果你刚听说 OpenClaw不知道它是什么我会先用一小节讲明白。读完你应该能回答这几个问题为什么 OpenClaw 值得用 Nix 装、Nix 本身怎么装、OpenClaw 的 Nix 安装流程怎么走、安装过程中哪些环节容易出幺蛾子。1. 先说清楚OpenClaw 为什么值得用 Nix 来装1.1 OpenClaw 是什么它对环境有多挑剔OpenClaw 可以理解成一个面向真实任务的智能体运行时。大模型负责理解你的话OpenClaw 负责把理解结果转化成真实的系统操作查文件、跑命令、控制 Chrome 浏览器、调用本地 Ollama 模型、接上微信收发消息这些事情都能通过它的 skill 机制扩展出去。它的定位决定了它不是一个装完就丢在后台的服务而是一个必须跟宿主机上各种软件深度协作的胶水层。这种到处都要伸手的形态让 OpenClaw 对环境特别敏感。它依赖一堆命令行工具、动态链接库、Python 或 Node 运行时还要能发现浏览器、模型服务、甚至是某些即时通讯软件的本地登录态。如果你用传统方式把所有依赖直接灌进系统全局目录刚开始可能没什么感觉但过一段时间只要系统里任何一个相关软件升级了OpenClaw 就很容易变成第一个被波及的对象。我在笔记本上就是活生生的例子一次系统更新把我本来的 Python 版本顶掉了OpenClaw 的几个 skill 直接全部罢工。1.2 Nix 相比 Docker 和源码安装的取舍很多人会问直接用 Docker 不是更省心实际用下来Docker 和 Nix 解决的是不同层面的问题。安装方式隔离性本机资源访问升级与回滚适合场景Docker很强需要额外的挂载、端口和网络配置镜像层可回滚但容器内状态管理麻烦只想快速跑通不打算让 OpenClaw 操作宿主机工具源码安装弱直接无隔离基本靠手动依赖容易污染系统想改源码做二次开发能接受环境被折腾Nix较强且能访问本机资源直接访问本机设备和命令事务式升级一条命令回滚既要干净环境又要 OpenClaw 能调用本机功能我最后选 Nix核心原因是它把环境当成代码来管理。同样一套配置拿到另一台机器上装出来的依赖版本、目录结构、启动命令完全一致不会再出现我这边能跑、你那边跑不了的尴尬。另一个让我很受用的点是Nix 的升级不是覆盖式的而是先把新版本装好确认没问题之后再切换一旦发现不对一条命令就能回到旧版本。对 OpenClaw 这种经常要跟模型版本、浏览器驱动、skill 配置打交道的应用来说这个能力太关键了。2. 装 Nix 之前必须确认的几件事2.1 系统发行版与 Nix 安装模式的对应关系在动手之前先搞清楚你所在的系统环境因为 Nix 在不同系统上的安装方式差别还挺大。LinuxDebian/Ubuntu/Fedora 等官方推荐多用户安装方式。执行安装脚本后Nix 会以 daemon 的形式运行普通用户都能使用日常操作不需要 root。macOS同样支持多用户安装App 和命令行工具都能通过 Nix 管理。NixOS系统本身已经内置 Nix不需要额外装包管理器直接在系统配置里声明 OpenClaw 即可。WindowsNix 不能原生跑在 Windows 上最接近官方推荐的路子是在 WSL2 里装一个 Ubuntu然后在 Ubuntu 里走 Linux 的安装流程。很多人在 Windows 上折腾 OpenClaw其实最终都是通过 WSL2 进来的。以最常见的 Linux 多用户安装为例命令很简单sh (curl -L https://nixos.org/nix/install) --daemon安装脚本会帮你完成大部分工作装完重新打开终端或者执行下面的命令让 Nix 环境立即生效. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh装完后检查一下 Nix 版本确认安装成功nix --version这里要提醒一句如果系统里已经有旧版本 Nix不要直接覆盖安装先看一下 /nix/store 里是否残留重要数据。我在一台备用机上没注意这个旧 profile 里的包在新版本下路径全变了最后只能一个个重建。2.2 OpenClaw 的运行时依赖与版本敏感点OpenClaw 的核心进程需要依赖 Python 运行时外围工具可能还会用到 Node、git、curl 这些基础命令。传统安装方式会要求你手动保证这些依赖存在但用 Nix 之后OpenClaw 对运行时的大部分需求会被 Nix 自动搞定你只需要关心几个最容易忽略的地方。第一个是数据目录。OpenClaw 的配置、skill、会话记录通常存放在~/.openclaw或者~/.config/openclaw升级和回滚都只会改二进制文件不会动数据目录。所以在升级之前最重要的不是备份系统而是备份这个目录。第二个是模型后端地址。如果你用本地 OllamaOpenClaw 需要能访问localhost:11434如果你用远程 API需要在配置里写清楚 endpoint。Nix 不会替你管理这些业务配置它只负责把程序本身和环境依赖装好。还有一点值得注意OpenClaw 的一些 skill 需要操作 Chrome 浏览器。Nix 安装的浏览器路径往往不在系统默认的 PATH 里需要单独把CHROME_BIN环境变量指过去。这一条很多人都会踩后面第 4 章我会给出具体的配置方式。3. 最小可用的 Nix 安装流程从 flake 开始3.1 拉取 OpenClaw 项目仓库并生成 flake现在 Nix 社区基本都在用 flake 这套新机制OpenClaw 如果提供 Nix 支持一般也是以 flake 的形式给出。在开始之前先确保你的 Nix 开启了 flake 功能。mkdir -p ~/.config/nix cat ~/.config/nix/nix.conf EOF experimental-features nix-command flakes EOF配置好后不需要下载任何东西nix命令本身就支持直接运行远程 flake。OpenClaw 的仓库如果托管在 GitHub最简单的尝鲜方式是这样nix run github:openclaw/openclaw -- --version如果仓库里的 flake 配置正确这条命令会自动拉取源码、构建依赖并运行程序。第一次执行会很慢因为 Nix 需要把完整依赖树都构建或下载下来后面再跑就是秒开了。我习惯先把仓库克隆到本地再做二次开发和配置git clone https://github.com/openclaw/openclaw.git cd openclaw如果仓库里已经有写好的flake.nix你在本地目录里直接执行nix develop就能进入一个所有依赖都齐备的开发环境。仓库没有提供 flake 的话也可以自己写一个简单的入口。下面是一个最小可用的flake.nix示意{ inputs { nixpkgs.url github:NixOS/nixpkgs/nixos-unstable; openclaw.url github:openclaw/openclaw; }; outputs { self, nixpkgs, openclaw, ... }: let system x86_64-linux; pkgs import nixpkgs { inherit system; }; openclawPkg openclaw.packages.${system}.default; in { devShells.${system}.default pkgs.mkShell { packages [ openclawPkg ]; shellHook echo OpenClaw development environment ready. ; }; }; }如果你用的是 Apple Silicon记得把x86_64-linux换成aarch64-darwin或aarch64-linux。这不是什么高级技巧但对刚接触 flake 的人来说最容易错的就是 system 参数。3.2 进入开发环境并完成首次启动在项目目录里执行nix develop进入开发环境后你的PATH里已经被注入了 OpenClaw 所需的全部命令。第一次使用时先初始化配置openclaw initinit会在数据目录里生成一份默认配置文件里面包含模型后端、日志级别、监听端口这些基础项。打开配置文件把model.provider改成你实际在用的后端。如果你本机已经装好了 Ollama可以继续保持默认的localhost地址OpenClaw 会自动识别。完成配置后启动服务试试openclaw serve看到类似OpenClaw is running on http://127.0.0.1:8899的日志说明主程序已经起来了。第一次启动不需要急着配一堆 skill先把这一个最小闭环跑通后面验证功能才有基础。这里补充一个细节很多人在nix develop里启动 OpenClaw 时会发现某些系统级命令找不到比如 Chrome 或者本机安装的 Python 模块。这是因为 Nix 的 devShell 默认带的是 Nix 自己管理的依赖集不会自动读取宿主机的/usr/bin。如果你确定要让某个系统命令穿透进来可以依赖pkgs.buildEnv或写一个 wrapper但这属于进阶用法。新手阶段先保证 OpenClaw 主进程能跑起来就够了。3.3 把 OpenClaw 装进用户 profilenix develop的方式适合开发调试但每次都要先进入目录、再敲命令日常使用不太方便。更推荐的做法是用 profile 把 OpenClaw 变成全局可用的命令。nix profile install github:openclaw/openclaw执行之后Nix 会在/nix/var/nix/profiles/per-user/你的用户名/下创建一个指向当前 OpenClaw 版本的 profile并把这个路径加入你的 PATH。之后再打开任意终端都能直接执行openclaw命令不需要再进 devShell。用 profile 管理和直接用系统包管理器安装最大的区别在于可回滚。每次nix profile install、nix profile upgrade之后Nix 都会记录当前 profile 的状态一旦新版本出问题你可以用nix profile history查看历史记录然后nix profile rollback回到上一个状态。这是传统安装方式给不了的体验。卸载也简单nix profile remove openclaw不过要记住nix profile remove只是把程序从 PATH 中摘掉数据目录~/.openclaw里的配置和 skill 不会被动。真正要清干净的话还需要手动删除数据目录这个我在最后一章会细说。4. 在 NixOS 上把 OpenClaw 做成系统级服务4.1 用 NixOS module 管理 OpenClaw 配置如果你用的是 NixOS没必要再用nix profile手动装了直接在系统配置里声明更干净。绝大多数 NixOS 用户会把 OpenClaw 写进/etc/nixos/configuration.nix{ config, pkgs, ... }: { environment.systemPackages with pkgs; [ openclaw ]; }然后执行sudo nixos-rebuild switch这条命令会把 OpenClaw 装进系统环境所有用户都能使用。不过这里有个关键点放在 systemPackages 里的应用它的数据目录还是属于具体用户。也就是说你用哪个用户执行openclaw init配置就落在哪个用户的 home 目录下和系统级安装并不冲突。如果你希望 OpenClaw 以系统服务的形式常驻后台比如开机自启官方或者社区可能提供了 NixOS module类似services.openclaw { enable true; user myuser; group users; port 8899; };启用服务后用systemctl status openclaw查看运行状态。这里我想特别提醒如果你之前已经用nix profile install装过一版又在 NixOS 系统配置里加了一个 OpenClaw那么两个版本的openclaw命令可能会同时出现在 PATH 里具体执行哪个取决于 PATH 的搜索顺序。这种情况下建议二选一不要混着用不然 skill 装的目录和数据目录会被两个版本抢来抢去非常容易出问题。4.2 关联 Ollama、Chrome 等外部工具时的 Nix 配置OpenClaw 不是孤岛它要发挥作用就得连通本机的 Ollama 和 Chrome 这类工具。NixOS 上这些工具的路径和普通发行版不太一样需要显式配置。先看 Ollama。如果 Ollama 已经在你本机跑着默认监听 11434 端口OpenClaw 访问http://127.0.0.1:11434即可不需要额外设置。但如果 NixOS 启用了防火墙就需要放行这个端口networking.firewall.allowedTCPPorts [ 11434 ];再看 Chrome。NixOS 上 Chrome 或者 Chromium 一般是通过pkgs.chromium安装的可执行文件路径在/nix/store/...-chromium/bin/chromium。问题是这个 store 路径包含一串哈希不固定你不应该硬编码。解决办法是通过环境变量把路径交给 OpenClawenvironment.variables { CHROME_BIN ${pkgs.chromium}/bin/chromium; };这样写的好处是无论 Nix 升级后 chromium 的 store 路径怎么变CHROME_BIN始终指向当前版本。有些 skill 还会依赖系统里的unzip、ffmpeg、imagemagick这类小工具。在 NixOS 上这些也需要加到environment.systemPackages里。我的经验是先跑一次 OpenClaw 的某个 skill看它报哪个命令找不到再回过来补包。不要一开始把所有能想到的包装一遍那样只会让系统环境越来越臃肿。5. 安装现场最容易翻车的三个细节5.1 二进制缓存签名与构建超时问题Nix 装包时会优先从二进制缓存拉取预编译好的结果拉不到才会走本地源码编译。OpenClaw 这类更新比较快的项目很容易出现缓存还没有生成或者 hash 不一致的情况。最常见的报错之一是hash mismatch in fixed-output derivation。出现这个错通常是因为你在本地改了 flake 的版本但没有同步更新nix-prefetch-url计算出的 hash。解决办法很简单把 flake 里的hash字段注释掉跑一次构建让 Nix 告诉你真实的 hash再把值填回去。另一种情况是构建超时。OpenClaw 的依赖树里有不少包需要从源码编译机器性能一般的话一个包编十几分钟很正常。如果构建任务卡在某个环节迟迟不动先别急着认为死机了可以检查 Nix 的构建进程ps aux | grep nix如果确认是在编译耐心等即可。想缩短构建时间可以配置max-jobs让 Nix 并行度更高比如nix run github:openclaw/openclaw --max-jobs 4要注意--max-jobs只影响构建任务的并行数量不能提高单任务的构建速度。5.2 沙箱导致 Python 依赖打包失败Nix 在 Linux 上默认启用构建沙箱构建过程不能访问网络。这本来是为了保证可复现性但 OpenClaw 这种大量依赖 Python 生态的应用某些依赖在构建阶段需要从 PyPI 下载资源如果构建脚本里没有显式声明 fixed-output derivation就会在沙箱里卡住。我在第一次构建 OpenClaw 时卡在一个叫pydantic-core的依赖上报错信息是网络访问被拒绝。后来搜了一圈发现这不是我一个人的问题而是构建沙箱下 Python wheel 下载的经典问题。解决办法有两个层面如果项目本身已经通过buildPythonPackage或poetry2nix管理依赖不要自己去改动它直接用项目提供的 flake 构建这些工具已经把每一个外部资源声明成了 fixed-output derivation沙箱网络限制不影响它。如果是自己写 derivation依赖了某个未声明的fetchurl那构建脚本必须显式使用fetchurl并给出 hash不能在 build phase 里临时用pip install。有些教程会让新手直接关闭沙箱nix build --option sandbox false这确实能绕过去但它会破坏可复现性我只建议在本地调试时临时用一下不要写进任何依赖配置里。5.3 升级 OpenClaw 版本时的状态目录迁移Nix 的升级思路是换掉整个应用包但 OpenClaw 的数据目录往往还保留着旧版本的痕迹。升级前不处理数据目录升级后轻则 skill 列表异常重则直接起不来。我现在的固定流程是这三步先跑openclaw doctor看看当前配置和 skill 有没有明显问题。备份数据目录cp -r ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)。升级后立刻openclaw doctor检查一次再做一次冒烟测试。版本升级的具体命令取决于安装方式。用 profile 装的nix profile upgrade openclaw用 flake 直接跑的nix run github:openclaw/openclaw -- --version如果发现升级后 skill 的路径失效通常是因为 skill manifest 里记录的 Python 解释器路径还指向旧 store 路径。不要手工去改 store 里的文件重新装一遍对应 skill 是最快的恢复方式。我在升级 OpenClaw 后习惯顺手把所有第三方 skill 重装一次避免路径残留的坑。6. 装完之后怎么验证、怎么回滚、怎么卸载6.1 冒烟测试用一个真实任务跑通安装结束不代表可以放心使用我建议用一次真实任务做冒烟测试。启动 OpenClaw 后在终端里给它发一条简单指令比如openclaw run 在 /tmp 下创建一个名为 hello.txt 的文件内容写上 OpenClaw installed by Nix正常情况下OpenClaw 会调用本地的 shell 工具完成操作并返回执行结果。你随后检查一下/tmp/hello.txt是否存在且内容正确就能确认核心链路是通的。如果中途报错不要慌先看日志。OpenClaw 的日志文件默认在数据目录的logs/下面执行tail -n 100 ~/.openclaw/logs/openclaw.log常见的冒烟测试失败原因有三种模型后端没连通、当前用户没有文件写入权限、配置里的工作目录不存在。这三种都能在日志里直接看到线索。6.2 skill 与外部通道的快速连通实验冒烟测试通过后可以测一下 skill 机制。OpenClaw 的 skill 可以从社区或官方仓库安装类似clawhub这个名称的出现频率很高通常可以这样装openclaw skill install clawhub:skill-name装完后用openclaw skill list确认 skill 已经加载。如果你想测试外部通道我建议先测 Ollama因为它的链路最短。在本地跑一个模型然后让 OpenClaw 调用它回答一个问题。如果 OpenClaw 与 Ollama 能对话说明模型集成没问题。Chrome 控制的测试也不要跳过。装一个和浏览器相关的 skill再让 OpenClaw 打开一个指定网页。这个测试能同时验证CHROME_BIN环境变量是否正确、浏览器驱动能不能正常工作。因为环境变量在 Nix 环境里很容易配错这个测试值得做。6.3 回滚和卸载的三种姿势如果升级后发现问题回滚比修复更省时间。profile 安装版先nix profile history看历史再nix profile rollback回到上一个可用的 profile。NixOS 系统版直接sudo nixos-rebuild switch --rollback整个系统回到上一次构建状态。源码本地版因为 flake 本身是可复现的切回旧版本只需要改 flake.lock 或重新 checkout 旧 commit再走一遍构建流程。卸载时要看你是哪种安装方式# profile 安装版 nix profile remove openclaw # NixOS 系统版删除 configuration.nix 里的 openclaw 后 sudo nixos-rebuild switch卸载程序后~/.openclaw数据目录一般不会被自动清理。想彻底卸载的话rm -rf ~/.openclaw最后可以跑一次nix store gc把没有 profile 引用的旧版本包清掉释放 /nix/store 空间。这个动作不会影响其他应用因为它只清理不再被任何 profile、用户环境引用的 store 路径。从个人经验来说用 Nix 安装 OpenClaw 之后最大的感受是终于可以大胆折腾了。以前每次升级都担心依赖搞坏系统现在升级前该备份备份该测试测试翻车了大不了 rollback心理负担小很多。如果你也是那种喜欢把环境固化成代码的人建议把 OpenClaw 的配置文件、flake.nix、还有安装笔记放进自己的 dotfiles 仓库一起管理这样换电脑时恢复成本几乎为零。到这一步OpenClaw 在 Nix 环境下的安装链路就算完全打通了接下来你可以放心去折腾 skill 和各种外部工具集成。
