Nix

**nix-openclaw**을 사용해 OpenClaw를 선언적으로 설치하세요. nix-openclaw는 필요한 기능을 모두 갖춘 공식 Home Manager 모듈입니다.

제공되는 기능

• 모두 버전이 고정된 Gateway, macOS 앱 및 도구(whisper, spotify, 카메라)
• 재부팅 후에도 유지되는 launchd 서비스
• 선언적 구성을 지원하는 Plugin 시스템
• 즉시 롤백: home-manager switch --rollback

빠른 시작

mkdir -p ~/code/openclaw-local# nix-openclaw 저장소에서 templates/agent-first/flake.nix 복사

home-manager switch

전체 모듈 옵션과 예시는 nix-openclaw README를 참조하세요.

Nix 모드 런타임 동작

OPENCLAW_NIX_MODE=1이 설정되면(nix-openclaw에서는 자동 설정) OpenClaw가 Nix 관리형 설치를 위한 결정적 모드로 전환됩니다. 다른 Nix 패키지도 동일한 모드를 설정할 수 있으며, nix-openclaw가 공식 참조 구현입니다.

직접 설정할 수도 있습니다.

export OPENCLAW_NIX_MODE=1

macOS에서는 GUI 앱이 셸 환경 변수를 상속하지 않습니다. 대신 defaults를 통해 Nix 모드를 활성화하세요.

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

Nix 모드에서 변경되는 사항

• 자동 설치 및 자체 변경 흐름이 비활성화됩니다.
• openclaw.json은 변경할 수 없는 파일로 취급됩니다. 시작 시 파생되는 기본값은 런타임에만 유지되며, 구성 작성 기능(설정, 온보딩, 구성을 변경하는 openclaw update, Plugin 설치/업데이트/제거/활성화, doctor --fix, doctor --generate-gateway-token, `openclaw config set)은 이 파일의 편집을 거부합니다.
• 대신 Nix 소스를 편집하세요. nix-openclaw에서는 에이전트 우선 빠른 시작을 따르고 programs.openclaw.config 또는 instances.<name>.config 아래에서 구성을 설정하세요.
• 종속성이 누락되면 Nix 전용 해결 안내 메시지가 표시됩니다.
• UI에 읽기 전용 Nix 모드 배너가 표시됩니다.

구성 및 상태 경로

OpenClaw는 OPENCLAW_CONFIG_PATH에서 JSON5 구성을 읽고 변경 가능한 데이터를 OPENCLAW_STATE_DIR에 저장합니다. Nix에서는 런타임 상태와 구성이 변경 불가능한 저장소에 들어가지 않도록 Nix 관리형 위치를 명시적으로 설정하세요.

서비스 PATH 검색

launchd/systemd Gateway 서비스는 Nix 프로필 바이너리를 자동으로 검색하므로 Plugin과 도구에서 nix로 설치된 실행 파일을 호출할 때 PATH를 직접 설정할 필요가 없습니다.

• NIX_PROFILES가 설정되어 있으면 모든 항목이 오른쪽에서 왼쪽으로 우선순위를 적용해 서비스 PATH에 추가됩니다(Nix 셸 우선순위와 동일하게 가장 오른쪽 항목이 우선합니다).
• NIX_PROFILES가 설정되어 있지 않으면 대체 경로로 ~/.nix-profile/bin이 추가됩니다.

이는 macOS launchd와 Linux systemd 서비스 환경 모두에 적용됩니다.

관련 항목