Skip to main content
使用 nix-openclaw 声明式安装 OpenClaw，这是官方提供、开箱即用的 Home Manager 模块。
nix-openclaw 仓库是 Nix 安装的唯一事实来源。本页仅作快速概览。

​
你将获得什么

  • Gateway + macOS 应用 + 工具（whisper、spotify、cameras），全部固定版本
  • 可在重启后持续运行的 launchd 服务
  • 具备声明式配置的插件系统
  • 即时回滚：home-manager switch --rollback

​
快速开始

1

安装 Determinate Nix

如果尚未安装 Nix，请按照 Determinate Nix installer 的说明进行操作。
2

创建本地 flake

使用 nix-openclaw 仓库中的 agent-first 模板：
3

配置密钥

配置你的消息机器人令牌和模型提供商 API 密钥。放在 ~/.secrets/ 下的普通文件也可以正常使用。
4

填入模板占位符并切换

5

验证

确认 launchd 服务正在运行，并且你的机器人可以响应消息。
有关完整的模块选项和示例，请参阅 nix-openclaw README。

​
Nix 模式运行时行为

当设置了 OPENCLAW_NIX_MODE=1（在使用 nix-openclaw 时会自动设置）时，OpenClaw 会进入适用于 Nix 管理安装的确定性模式。其他 Nix 包也可以设置相同模式；nix-openclaw 是首选参考实现。 你也可以手动设置：
在 macOS 上，GUI 应用不会继承 shell 环境变量。请改用 defaults 启用 Nix 模式：

​
Nix 模式下会有什么变化

  • 自动安装和自我修改流程将被禁用。
  • openclaw.json 会被视为不可变。启动时派生的默认值仅保留在运行时，而配置写入器（setup、onboarding、会修改配置的 openclaw update、插件 install/update/uninstall/enable、doctor --fix、doctor --generate-gateway-token、openclaw config set）会拒绝编辑该文件。
  • 请直接修改 Nix 源。对于 nix-openclaw，请使用以 agent 为先的 Quick Start，并将配置放在 programs.openclaw.config 或 instances.<name>.config 下。
  • 缺失依赖会显示 Nix 特定的修复提示。
  • UI 会显示只读的 Nix 模式横幅。

​
配置和状态路径

OpenClaw 会从 OPENCLAW_CONFIG_PATH 读取 JSON5 配置，并将可变数据存储在 OPENCLAW_STATE_DIR 中。在 Nix 下，请显式将它们设置为由 Nix 管理的位置，以便运行时状态和配置都不进入不可变 store。

​
服务 PATH 发现

launchd/systemd gateway 服务会自动发现 Nix profile 二进制文件，因此会 shell out 到 nix 安装的可执行文件的插件和工具无需手动设置 PATH：
  • 当设置了 NIX_PROFILES 时，每个条目都会按从右到左的优先级添加到服务 PATH 中（与 Nix shell 的优先级一致：最右侧优先）。
  • 当未设置 NIX_PROFILES 时，会回退添加 ~/.nix-profile/bin。
这同时适用于 macOS 的 launchd 和 Linux 的 systemd 服务环境。

​
相关内容

nix-openclaw

事实来源的 Home Manager 模块和完整设置指南。

设置向导

非 Nix CLI 设置流程。

Docker

容器化安装，作为非 Nix 替代方案。

更新

将 Home Manager 管理的安装与包一起更新。