macOS · Linux · WSL2 · Docker · launchd · systemd · 재현 가능한 검증
노트북, 서버, WSL2, 컨테이너 어디에서든 OpenClaw Gateway를 뚜껑을 닫아도 끊기지 않게 돌려야 하는 개발자는 모델 키 부족보다 대화형 셸과 데몬의 Node 실체 불일치, systemd 사용자 유닛에 같은 환경 블록이 실리지 않음, Docker가 잘못된 루프백에 바인딩됨에서 더 자주 막힙니다. 본문은 플랫폼별 합격/불합격 사전 판정, 공식 스크립트·패키지 매니저·소스·컨테이너 네 갈래 결정표, macOS launchd와 Linux systemd에서의 openclaw onboard와 --install-daemon 확인 명령, 버전·Gateway 상태·바인딩 면 게이트, 상시 온라인 Mac 노드로 옮기기 전 Runbook을 제시합니다. 깊은 오류 추적은 설치 및 Gateway 장애 대응 장문, 상시 운영과 프로세스 표현은 영구 클라우드 배포 플레이북, 노출면과 화이트리스트는 프로덕션 강화 체크리스트, 연산과 발주 경로는 대여 가격과 주문 페이지를 참고합니다.
2026년 OpenClaw 설치 경로는 스크립트화되어 있지만, 비용이 큰 부분은 데몬 컨텍스트를 이해하는 일입니다. 대화형 zsh에서는 node -v가 맞아도 launchd나 systemd가 띄운 프로세스는 짧은 PATH, 다른 홈, 빠진 API 키를 물려받을 수 있습니다. WSL2는 Windows Defender, 포트 포워딩, DNS가 Linux 가정 위에 겹칩니다. Docker는 볼륨 마운트, 숫자 UID, 공개 포트, 루프백 의미가 더해져 대시보드는 로컬에서 열리지만 수신 Webhook은 실패할 수 있습니다. 아래 다섯 가지는 커뮤니티에서도 반복되므로 설계 리뷰에 적는 편이 글로벌 npm을 두 번 재설치하는 것보다 시간을 아낍니다.
각 틈을 이진 게이트로 취급합니다. 실패하면 기능 개발을 멈추고 환경 계약을 먼저 고칩니다. 이 순서를 건너뛰면 금요일 밤에는 초록 스크립트를 축하하고 토요일 아침에는 말이 없는 데몬으로 깨어날 수 있습니다. 승리 선언 전에 재부팅이나 wsl --shutdown을 하지 않은 전형적인 사례입니다.
Node LTS와 바이너리 드리프트: 상위 스트림은 비교적 새 Node LTS를 가정합니다. nvm, fnm, asdf, 배포판 패키지를 섞으면 터미널은 황금색이어도 슈퍼바이저 아래는 낡은 바이너리가 됩니다. 합격 기준은 서비스와 동일한 UNIX 사용자에서 which node와 버전을 출력하고 openclaw doctor 또는 해당 헬스 명령과 맞추는 것입니다. 경로가 어긋나면 불합격입니다.
WSL2와 systemd 가정: 일부 배포판은 systemd를 명시적으로 켜거나 사용자 lingering이 있어야 대화 로그인 없이 사용자 유닛이 남습니다. 합격 기준은 수동 셸 없이 WSL을 완전히 재시작한 뒤에도 유닛이 active인 것입니다. 한 번 SSH나 터미널을 열어야 깨어나면 불합격입니다.
Docker 볼륨과 설정의 단일 진실: 설정을 컨테이너 쓰기 레이어에만 두면 다음 이미지 pull에서 비밀과 상태가 사라집니다. 합격 기준은 설정 디렉터리와 환경 파일을 바인드 마운트나 이름 붙은 볼륨에 올리고 업그레이드 전 백업과 복원 절차가 문서화된 것입니다.
리스너 기본값: 개발에서는 0.0.0.0이 편해 보이지만 프로덕션에서는 공개 대시보드가 됩니다. 합격 기준은 프로덕션 Runbook이 루프백 또는 리버스 프록시 TLS 종료를 요구하고 강화 글과 일치하는 것입니다.
로그와 로테이션: 표준 출력만으로 쌓으면 작은 클라우드 디스크가 가득 차고 사건 때 증거가 사라집니다. 합격 기준은 고객 트래픽을 얹기 전에 로그 목적지, 보존 일수, 중앙 로그와의 호환을 정의한 것입니다.
다섯 행을 합격/불합격으로 기록한 뒤 다음 절의 설치 경로를 고릅니다. 점수표는 일회용 노트북 실험인지 채널과 Webhook과 감사를 실을 토폴로지인지를 보여 줍니다.
iOS 빌드와 에이전트 자동화를 동시에 운영하는 팀은 Node의 진실, 설정의 진실, 로그 디렉터리를 같은 아키텍처 한 장에 올리는 편이 좋습니다. 작업 체인과 공유 빌드 풀 문서와 어휘를 맞추면 사건 복기마다 PATH 대 데몬 강의를 반복하지 않아도 됩니다.
각 경로는 다른 제약을 최적화합니다. 첫 성공까지의 시간, 감사 가능성, 패치 속도, 의존성 격리입니다. curl과 PowerShell 설치기는 수작업을 줄이지만 에어갭 미러와 충돌할 수 있습니다. 글로벌 npm은 JavaScript 플랫폼 팀에 맞지만 데몬 아래 PATH 분기를 키웁니다. 소스 빌드는 핫픽스와 사용자 정의 플래그를 가능하게 하고 CI 시간과 맞바꿉니다. 컨테이너는 라이브러리를 격리하지만 네트워크, UID 매핑, 볼륨 백업을 명시적으로 설계하게 합니다. 만능 답은 없으며 변경 관리, 컴플라이언스, 온콜 숙련도가 유지할 수 있는 답이 맞습니다.
여러 경로가 매력적이면 일회용 호스트에서 병렬로 시제품을 만들되 설정 권위는 하나로 유지합니다. 공유 비밀 전략 없는 병렬 실험은 어긋난 .env와 doctor 오탐을 보장합니다.
| 경로 | 주요 이점 | 주요 리스크 | 어울리는 경우 |
|---|---|---|---|
| 공식 curl / ps1 스크립트 | 수동 단계가 가장 적고 상위 기본값에 가깝다 | 사설 네트워크에는 미러가 필요하고 버전은 별도 기록 | 개인과 다섯 명 미만 팀이 가치를 빨리 증명할 때 |
| 글로벌 npm / pnpm / bun | JS 툴체인과 맞고 semver 고정이 쉽다 | 데몬 아래 PATH와 권한이 갈라지기 쉽다 | Node 공급망이 통일된 조직 |
| 소스 빌드 | 패치와 시작 인자 조정이 가능하다 | 빌드와 CI 유지 부담이 크다 | 포크나 긴급 수정을 내는 보안 팀 |
| Docker / Podman | 의존성을 격리하고 수평 시험이 빠르다 | 볼륨, UID, 루프백, 호스트 포트 설계가 무겁다 | 멀티테넌트 샌드박스나 단기 스파이크 |
설치 성공은 콜드 부팅 뒤에도 데몬이 같은 검증 명령을 통과하는 것이지, 대화형 터미널에서 한 번 돌아간 것만으로는 아닙니다.
macOS 노트북, Linux 클라우드, WSL2, 컨테이너는 마이그레이션 프로그램에서 공존할 수 있지만 설정 권위와 비밀 주입 방식은 통일해야 합니다. 체크리스트 없이 .env 조각을 환경 간에 복사하면 일주일 안에 드리프트가 납니다.
단계는 특정 CI 벤더에 묶이지 않습니다. 각 단계는 산출물을 남깁니다. 명령 출력, 유닛 상태 스크린샷, 설정 파일 체크섬을 변경 티켓에 붙입니다. 실패하면 긴 로그에 들어가기 전에 첫 절로 돌아갑니다. 환경 게이트가 초록이면 doctor 장애 대응 장문으로 미지를 좁힙니다.
각 명령 옆에 정확한 패키지 이름이나 컨테이너 태그를 적습니다. 미래의 나와 당번 엔지니어는 설치일에 승인된 semver를 추측하면 안 됩니다.
Node와 패키지 매니저 고정: 서비스 사용자 아래 LTS를 설치하고 PATH를 조용히 바꾸는 셸 훅을 끄며 Runbook 부록에 node -v와 npm -v 또는 pnpm과 bun 상응 정보를 기록합니다.
지원 설치기 실행: Unix 계열은 공식 스크립트나 릴리스용 문서화된 패키지 흐름을 따릅니다. Windows는 WSL2나 문서화된 PowerShell 경로를 우선하고 글로벌 모듈 소유를 다투는 두 런타임을 섞지 않습니다.
비밀과 모델로 onboard 완료: API 키, 워크스페이스 루트, 기본 모델 단계를 합의된 설정 파일에 씁니다. 셸 기록이나 누구나 읽는 임시 파일에 비밀을 두지 않습니다.
openclaw onboard --install-daemon 실행: 설치기가 출력하는 유닛 라벨을 적습니다. macOS에서는 launchctl을 확인하고 Linux에서는 systemctl --user나 시스템 경로를 설치한 버전의 상위 문서와 대조합니다.
콜드 스타트 증명: OS를 재부팅하거나 wsl --shutdown을 실행한 뒤 로그인 셸 없이 서비스가 active인지 확인합니다. SSH 후에만 뜨면 사용자 lingering이 미완입니다.
롤백 앵커 확보: 업그레이드 전 디스크 이미지 스냅샷, 컨테이너 태그, 이전 설정 트리 tarball을 남깁니다. 롤백은 알려진 좋은 유닛을 되돌리는 것이지 한밤중 plist나 unit 수동 편집이 아닙니다.
openclaw --version openclaw gateway status # macOS: 로드된 데몬 라벨(실제 유닛 이름으로 교체) launchctl list | grep -i openclaw || true # Linux: 사용자 범위 systemd 예시 systemctl --user status openclaw-gateway.service || true
팁: 하위 명령과 유닛 이름은 릴리스마다 바뀝니다. 조각을 계층 다이어그램으로 읽고 고정 문자열로 두지 말며 설치한 버전의 출력을 따릅니다.
데몬이 active여도 리스너, TLS 종료, 리버스 프록시 헤더가 옳다는 뜻은 아닙니다. 표를 공개 채널을 얹기 전 릴리스 게이트로 씁니다. 건너뛰면 채팅은 되지만 감사는 통과하지 못하는 회색 지대가 남습니다.
첫 설치뿐 아니라 Node 업데이트, 인증서 로테, 인프라 변경마다 게이트를 돌립니다. 회귀는 앱 배포보다 조용한 패키지 업데이트에서 자주 옵니다.
| 검사 | 기대 | 흔한 실패 신호 |
|---|---|---|
openclaw --version | Runbook에 고정한 semver와 일치 | PATH 분기로 두 빌드가 섞임 |
gateway status | 건강하거나 문서화된 오류 코드 | 설정 파싱 실패가 stdout 잡음에 묻힘 |
| 리스너 인터페이스 | 프로덕션은 루프백 또는 프록시 종료 | 대시보드가 공인망에서 직접 열림 |
| 외향 LLM 경로 | 데몬 환경에서 curl 또는 SDK 프로브 성공 | 기업 프록시 변수가 systemd에 없음 |
주의: 프로덕션 강화 체크리스트의 화이트리스트와 스킬 감사는 Gateway와 어댑터가 안정된 뒤에 적용합니다. 순서를 뒤집으면 제한이 꺼진 채 트래픽이 들어오는 창이 생깁니다.
아래 세 가지는 합성 벤치마크가 아니라 재무, 보안, 플랫폼 리드용 프로젝트 전 정렬 프롬프트입니다. SLA에 서명하기 전에 정성적 임계를 자체 텔레메트리와 티켓 수치로 바꿉니다.
노트북은 절전, 뚜껑 닫기, macOS 업데이트, 대화형 키체인에 흔들립니다. 개발에는 이상적이나 주 7일 에이전트의 유일한 호스트에는 맞지 않습니다. 자체 호스팅은 랙, 패치, 원격 핸드로 비용이 이동합니다. Gateway를 계약으로 묶을 수 있는 클라우드 Mac Mini에 두면 콜드 스타트, semver, 리스너 정책을 조달 검토에서 검증할 조항으로 바꿉니다.
흔한 함정: 내 머신에서 돌아간다를 팀 전체에 재현된다로 보고 유닛 이름, 환경 블록, 설정 권위를 공유하지 않으면 장애 대응이 채팅 스크린샷으로 퇴보합니다.
iOS와 macOS 빌드 용량이 OpenClaw와 야간 자동화를 나눠 써야 할 때 개인 기기와 빌려 쓴 머신은 감사 추적이나 가동 목표를 채우기 어렵습니다. 운용 마찰을 줄이고 리전을 고르고 임대 기간을 유연히 원하는 팀은 VpsMesh Mac Mini 클라우드 대여로 수렴하는 경우가 많습니다. 데몬과 채널 정책을 전용 호스트에 올리고 고객 센터와 주문 페이지로 온보딩을 맞추면 노트북 절전 정책과 끝없이 타협하지 않아도 됩니다.
Windows 데스크톱 툴체인과 한 기기에서 밀접히 협업하고 커널과 systemd를 확인하려면 WSL2입니다. 순수 서버 납품은 네이티브 Linux를 우선합니다. 원격 습관과 연결은 고객 센터와 관련 블로그를 함께 읽습니다.
먼저 설치 및 Gateway 장애 대응 장문에서 Node 경로, 권한, 설정 우선순위, 포트 점유를 확인한 뒤 본문으로 돌아와 유닛 콜드 스타트를 다시 봅니다.
공개 트래픽을 열기 전에 프로덕션 강화와 멀티채널 체크리스트를 마칩니다. 전용 노드가 필요하면 주문 페이지에서 리전과 기간을 고릅니다.