Nix

使用 nix-openclaw 以声明式方式安装 OpenClaw，这是官方提供的、开箱即用的 Home Manager 模块。

你将获得¶

• 网关 + macOS 应用 + 工具（whisper、spotify、摄像头），全部固定版本
• 重启后依然存在的 launchd 服务
• 支持声明式配置的插件系统
• 即时回滚：home-manager switch --rollback

快速开始¶

1. 安装 Determinate Nix

如果尚未安装 Nix，请按照 Determinate Nix 安装器 的说明操作。

2. 创建一个本地 flake

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

mkdir -p ~/code/openclaw-local
git clone https://github.com/openclaw/nix-openclaw.git /tmp/nix-openclaw
cp /tmp/nix-openclaw/templates/agent-first/flake.nix ~/code/openclaw-local/flake.nix

3. 配置机密信息

配置你的消息机器人令牌和模型提供方 API 密钥。使用 ~/.secrets/ 下的纯文本文件即可。

4. 填写模板占位符并切换

home-manager switch

5. 验证

确认 launchd 服务正在运行，并且你的机器人能够响应消息。

完整的模块选项和示例请参阅 nix-openclaw README。

Nix 模式运行时行为¶

当设置 OPENCLAW_NIX_MODE=1 时（使用 nix-openclaw 会自动设置），OpenClaw 会为 Nix 管理的安装进入确定性模式。其他 Nix 包也可以设置相同的模式；nix-openclaw 是第一方参考实现。

对于不使用 Nix 的外部管理配置，请使用 OPENCLAW_CONFIG_READONLY=1。它会以通用信息应用相同的不可变配置强制规则， 而不会启用 Nix 特定行为。已有的 OPENCLAW_NIX_MODE=1 安装无需更改。

你也可以手动设置：

export OPENCLAW_NIX_MODE=1

在 macOS 上，GUI 应用不会继承 shell 环境变量。请改用 defaults 启用 Nix 模式：

defaults write ai.openclaw.mac openclaw.nixMode -bool true

Nix 模式下的变化¶

• 自动安装和自我修改流程已被禁用。
• openclaw.json 被视为不可变文件。启动时派生的默认值仅保留在运行时中，配置写入器（setup、onboarding、会修改配置的 openclaw update、插件安装/更新/卸载/启用、doctor --fix、doctor --generate-gateway-token、openclaw config set）将拒绝编辑该文件。
• 请改为编辑 Nix 源文件。对于 nix-openclaw，请使用 agent-first 快速开始，并在 programs.openclaw.config 或 instances.<name>.config 下设置配置。
• 缺失的依赖项会显示 Nix 特定的修复消息。
• UI 会显示一个只读的 Nix 模式横幅。

配置与状态路径¶

OpenClaw 从 OPENCLAW_CONFIG_PATH 读取 JSON5 配置，并将可变数据存储在 OPENCLAW_STATE_DIR 中。在 Nix 下，请将这些变量显式设置为 Nix 管理的位置，以便运行时状态和配置保留在不可变存储之外。

服务 PATH 发现¶

launchd/systemd 网关服务会自动发现 Nix-profile 中的二进制文件，因此那些调用 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 管理的安装。