# Nix
> 使用 Nix 以声明式方式安装 OpenClaw
- 网址：https://funcoding.ai/agents/openclaw/install/nix/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/install/nix
---
使用第一方、功能完备的 Home Manager 模块 **[nix-openclaw](https://github.com/openclaw/nix-openclaw)**，以声明式方式安装 OpenClaw。
[nix-openclaw](https://github.com/openclaw/nix-openclaw) 仓库是 Nix 安装方式的权威来源。本页提供快速概览。
## 你将获得
- Gateway 网关 + macOS 应用 + 工具（whisper、spotify、摄像头），全部锁定版本
- 重启后仍可持续运行的 launchd 服务
- 支持声明式配置的插件系统
- 即时回滚：`home-manager switch --rollback`
## 快速开始
**安装 Determinate Nix**
如果尚未安装 Nix，请按照 [Determinate Nix 安装程序](https://github.com/DeterminateSystems/nix-installer)的说明操作。
**创建本地 flake**
使用 nix-openclaw 仓库中以智能体为先的模板：
```bash
mkdir -p ~/code/openclaw-local
# 从 nix-openclaw 仓库复制 templates/agent-first/flake.nix
```
**配置机密信息**
设置消息 Bot 令牌和模型提供商 API 密钥。使用 `~/.secrets/` 中的纯文本文件即可。
**填写模板占位符并切换**
```bash
home-manager switch
```
**验证**
确认 launchd 服务正在运行，并且 Bot 能够响应消息。
有关完整的模块选项和示例，请参阅 [nix-openclaw README](https://github.com/openclaw/nix-openclaw)。
## Nix 模式下的运行时行为
设置 `OPENCLAW_NIX_MODE=1` 后（使用 nix-openclaw 时会自动设置），OpenClaw 会针对由 Nix 管理的安装进入确定性模式。其他 Nix 软件包也可设置相同模式；nix-openclaw 是第一方参考实现。
也可以手动设置：
```bash
export OPENCLAW_NIX_MODE=1
```
在 macOS 上，GUI 应用不会继承 shell 环境变量。请改用 `defaults` 启用 Nix 模式：
```bash
defaults write ai.openclaw.mac openclaw.nixMode -bool true
```
### Nix 模式下的变化
- 自动安装和自修改流程会被禁用。
- `openclaw.json` 会被视为不可变。启动时派生的默认值仅保留在运行时中，并且配置写入程序（设置、新手引导、会修改配置的 `openclaw update`、插件安装/更新/卸载/启用、`doctor --fix`、`doctor --generate-gateway-token`、`openclaw config set`）会拒绝编辑该文件。
- 请改为编辑 Nix 源。对于 nix-openclaw，请使用以智能体为先的[快速开始](https://github.com/openclaw/nix-openclaw#quick-start)，并在 `programs.openclaw.config` 或 `instances..config` 下设置配置。
- 缺少依赖项时会显示 Nix 专用的修复提示。
- UI 会显示只读的 Nix 模式横幅。
### 配置和状态路径
OpenClaw 从 `OPENCLAW_CONFIG_PATH` 读取 JSON5 配置，并将可变数据存储在 `OPENCLAW_STATE_DIR` 中。在 Nix 环境下，请将这些路径显式设置为由 Nix 管理的位置，使运行时状态和配置避开不可变存储区。
| 变量 | 默认值 |
| ---------------------- | --------------------------------------- |
| `OPENCLAW_HOME` | `HOME` / `USERPROFILE` / `os.homedir()` |
| `OPENCLAW_STATE_DIR` | `~/.openclaw` |
| `OPENCLAW_CONFIG_PATH` | `$OPENCLAW_STATE_DIR/openclaw.json` |
### 服务 PATH 发现
launchd/systemd Gateway 网关服务会自动发现 Nix 配置文件中的二进制文件，因此，通过 shell 调用由 `nix` 安装的可执行文件的插件和工具无需手动设置 PATH 即可正常工作：
- 设置 `NIX_PROFILES` 后，其中每个条目都会按从右到左的优先级添加到服务 PATH 中（与 Nix shell 的优先级一致：最右侧优先）。
- 未设置 `NIX_PROFILES` 时，会添加 `~/.nix-profile/bin` 作为回退项。
这同时适用于 macOS launchd 和 Linux systemd 服务环境。
## 相关内容
- [nix-openclaw](https://github.com/openclaw/nix-openclaw)：作为权威来源的 Home Manager 模块和完整设置指南。
- [设置向导](https://funcoding.ai/agents/openclaw/start/wizard/)：非 Nix 环境下的 CLI 设置操作指南。
- [Docker](https://funcoding.ai/agents/openclaw/install/docker/)：可替代 Nix 的容器化设置方式。
- [更新](https://funcoding.ai/agents/openclaw/install/updating/)：将 Home Manager 管理的安装与软件包同步更新。