사이트의Ubuntu 24.04 + systemd + Tunnel과Docker Compose 프로덕션처럼 무거운 운영 형태를 이미 읽었더라도, Windows / macOS / 범용 Linux에서 OpenClaw CLI와 Gateway를 안정적으로 설치하고 데몬으로 등록한 뒤 헬스 체크까지 통과시켜야 합니다. 이 글은 그 층을 메워 공통 전제, OS별 대조표, 설치부터 데몬까지 여섯 단계, 초기 설치 단계에서 자주 나는 오류, 그리고 두 편의 프로덕션 글과의 경계를 정리해 노트북, WSL2, 소형 VPS에서도 같은 사고 모델을 재현할 수 있게 합니다.
OpenClaw Gateway는 오래 실행되는 서비스 프로세스에 CLI 도구 체인이 얹힌 형태입니다. 전제가 어긋나면 이후 systemd, Compose, Tunnel 설정이 맞아도 다른 모양으로 깨집니다. 아래는 멀티플랫폼 분류에서 자주 보이는 패턴으로, 채팅 기록이 아니라 내부 설치 Runbook에 적어 두는 편이 좋습니다.
Node 버전 표류: 개발 노트북은 오래된 LTS, CI는 다른 계열이라 Gateway 시작 스크립트가 호스트 A에서는 되고 B에서는 구문·의존성 오류가 납니다. 공식 바이너리나 nvm, fnm 등으로 고정하고 허용 마이너 범위를 문서화하세요.
상태 디렉터리를 동기 드라이브에:~/.openclaw나 동등 경로를 iCloud, OneDrive 등 동기 폴더에 두면 잠금, 권한, 충돌이 잦습니다. 로컬 디스크에 두고 백업은 별도 정책으로 설계합니다.
Windows 네이티브와 WSL2 PATH 혼합: PowerShell에 깐 CLI를 WSL에서 부르거나 그 반대가 되면 명령 없음·인증서 경로 오류가 납니다. 주 실행 면을 하나 정해 팀 전체가 통일합니다.
macOS TCC와 위치: GUI에 가까운 구성 요소를 다운로드 폴더에서 직접 실행하면 접근성·자동화 승인에 막혀 무인 시나리오가 깨집니다. /Applications 등 안정 경로를 쓰고 주요 OS 업그레이드 후 권한을 다시 확인합니다.
헬스 체크 부재: 프로세스 존재만 보고 루프백 curl·대시보드를 생략하면 프로덕션 네트워크 변경 뒤 502만 남는 경우가 많습니다.
기본으로 0.0.0.0에 바인딩: 관리면을 모든 인터페이스에 노출하면 감사·스캔 리스크가 급증합니다. 터널이나 리버스 프록시와 묶고 루프백 중심을 기본으로 합니다.
토큰을 셸 기록에: 대화형 셸에 export 해 공유하거나 스크린샷으로 흘리는 것은 열쇠 공유와 같습니다. 권한이 제한된 파일이나 비밀 관리로 옮깁니다.
체크리스트를 거친 뒤 대조표로 가면 같은 명령이 세 대에서 세 가지로 나오는 마찰을 줄입니다. iOS 빌드나 지속 GUI가 필요하면 Gateway는 Linux나 워크스테이션에 두고 무거운 Apple Silicon 작업은 전용 원격 Mac 실행 노드로 분리하는 토폴로지도 쉬워집니다.
또 하나의 숨은 비용은 문서 파편화입니다. README, 내부 위키, 몇 달 전 스크린샷이 섞이면 누구도 정답 Node 범위와 상태 경로를 갖지 못합니다. 개념 설명보다 단일 진실 원천에 Node 마이너, 상태 경로, 데몬 설치 서브커맨드를 적는 편이 낫습니다.
업그레이드에는 롤백 창을 남깁니다. CLI나 Gateway 패치 전 설정 트리와 토큰 파일을 백업하고, 데몬 등록이 실패하면 이전 바이너리나 이전 이미지 다이제스트로 돌아갈 수 있어야 합니다. 「부팅만 됐다」로 끝낸 팀은 설정 키 폐기를 야간에 맞닥뜨리기 쉬우며, 변경 로그와 스테이징에서의 onboard 리허설로 줄일 수 있습니다.
여러 에이전트 제품군이 있다면 「개발기 수작업 설치」와 「프로덕션 systemd/Compose」를 태그나 네임스페이스로 분리하고, 실험용 플러그인 디렉터리를 프로덕션 상태 경로에 동기화하지 않습니다. 개발은 독립 접두 경로, 프로덕션은 읽기 전용 설정 마운트와 쓰기 데이터 볼륨이 최소한의 분리입니다.
여유가 있으면 예비 VM에서 프로세스 kill·API 키 로테이션을 연습하고 status, 로그, 데몬 제거 명령이 Runbook에 있는지 확인합니다. 다이어그램보다 절차가 운영에서 더 큽니다.
세 환경 모두 같은 Gateway를 돌릴 수 있지만 프로세스 감독, 로그 위치, 업그레이드·롤백의 주체가 다릅니다. 표로 고정해 두면 설계 검토에서 Windows 서비스와 LaunchAgent를 섞어 말하기 어렵습니다.
| 플랫폼 | 흔한 설치 진입 | 상시 실행(데몬) 접근 | 전형적인 함정 |
|---|---|---|---|
| Windows | 공식 설치 프로그램, PowerShell 원클릭, 패키지 관리자 | Windows 서비스 또는 작업 스케줄러(로그 디렉터리 ACL 명시) | 네이티브와 WSL2 이중 환경, 백신 오탐, 공백 포함 경로 |
| macOS | Homebrew, curl 설치 스크립트, 업스트림 릴리스 | LaunchAgent / LaunchDaemon(로그인 세션 필요 여부로 선택) | TCC, Gatekeeper, 상태 디렉터리 소유권 |
| Linux(범용) | 배포판 패키지, 정적 바이너리, npm 글로벌(업스트림 권장 따름) | systemd 사용자/시스템 유닛(프로덕션 예는 베어메탈 장문) | SELinux/AppArmor, 최소 이미지 의존성 부족, 127.0.0.1 루프백이 iptables에 의해 깨지는 경우 |
크로스플랫폼에서 맞추는 것은 어떤 설치기를 눌렀는지가 아니라 버전 고정, 상태의 로컬화, 리스너면 축소, 스크립트 가능한 헬스 체크입니다.
Linux에서 프로덕션급 Tunnel과 유닛 파일까지 간다면 Ubuntu 24.04 + systemd + Tunnel 튜토리얼로 전환하고, 이미지 다이제스트와 이름 있는 볼륨이 주제면 Docker Compose 프로덕션 글을 따릅니다. 이 글은 「CLI/Gateway를 맞게 설치하고 데몬화한다」에 머물러 세 글이 서로의 범위를 빼앗지 않게 합니다.
아래는 업스트림 CLI가 onboard와 데몬 등록류 서브커맨드를 제공한다는 전제입니다. 이름이 다르면 로컬 --help를 따르되 순서는 유지하세요(설정이 먼저, 감독이 나중).
런타임 고정:node -v를 상류 요구와 맞추고, 부족하면 Gateway 전에 Node를 올립니다.
CLI 설치:OS별 권장 경로를 쓰고 sudo 글로벌과 사용자 글로벌을 같은 계정에서 섞지 않습니다.
설정·비밀:모델 공급자 키는 env 파일이나 비밀 저장소에, 권한 600(또는 OS 동등). 공용 저장소에 쓰지 않습니다.
onboard:Gateway 설정과 토큰을 생성·검증하고 출력 경로를 Runbook에 기록합니다.
데몬 설치:업스트림 install-daemon류 명령으로 크래시 재시작과 로그 디렉터리를 한 번에 구성합니다.
검수:status, health(있으면), 로컬 루프백 curl로 「가짜 running」을 제거합니다.
node -v openclaw --version openclaw onboard --install-daemon openclaw gateway status openclaw dashboard
안내:status는 정상인데 공인 URL이 실패하면 프로세스 문제와 라우팅 문제를 나눕니다. 먼저 호스트 루프백 curl, 다음 터널·리버스 프록시를 보고 Linux 장문과 같은 순서로 분류합니다.
Windows: 개발이 주로 WSL2라면 해당 배포판 안에서 CLI와 Gateway를 끝내 Linux 프로덕션과 경로 약속을 맞춥니다. DrvFs로 Windows 파일을 보면 IO·권한 차이에 유의합니다. 네이티브 서비스로 올릴 때는 서비스 계정에 상태·로그 경로 ACL을 명시합니다.
macOS: 바이너리는 안정 경로에 두고 다운로드 직실행을 피합니다. OS 업그레이드 후 자동화·접근성 승인을 다시 봅니다. 무인이면 업스트림이 UI를 요구하지 않는 한 LaunchDaemon 쪽이 안전합니다.
Linux: 이미 systemd 유닛을 쓴다면 이 글은 건너뛰고 베어메탈 글의 프로덕션 템플릿을 씁니다. Docker를 쓴다면 컨테이너와 호스트 중 누가 루프백·터널 사이드카를 가질지 Compose에 적어 이중 Gateway 포트 경쟁을 막습니다.
분류할 때는 증상→증거→가설 순으로, 로그를 잠시 읽을 수 있는 verbose로 올렸다가(상시는 디스크 위험) 같은 semver에서 재현합니다. 한 대만 실패하면 환경 변수·프록시·시계 skew를 비교하세요. 시계 오차는 토큰·TLS에서 애플리케이션 버그처럼 보입니다.
「대시보드가 연다」를 프로덕션 준비 완료와 동일시하지 마세요. 대시보드는 좁은 검증에 그칠 수 있습니다. 승격 전에 대표 작업을 업스트림에서 Gateway를 통해 끝까지 흘려 인증·라우팅·콜백·재시도·속도 제한을 확인합니다.
주의:2026년에도 공개 스캔 가능한 Gateway 관리면은 흔한 오설정입니다. 자동 스캔을 가정하고 허용 목록, 터널, mTLS, 사내망 도달을 선택이 아니라 기준선으로 둡니다.
아래는 내부 정렬용 초안이며 제3자 프로젝트에 대한 약속이 아닙니다. 실제 설치한 버전의 도움말과 릴리스 노트를 우선합니다.
노트북이나 작은 VM에서만 Gateway를 돌리는 것은 데모에는 충분하지만 수면 정책, 디스크 IO, Wi-Fi 지터가 에이전트 워크플로를 예측 불가로 만듭니다. 자체 랙 Mac은 감가와 현장 운영도 짊어집니다. 안정적인 Apple Silicon 실행층에서 빌드, 스크립트 서명, Gateway와 병행 자동화가 필요하면 무거운 일을 계약 기반 전용 원격 Mac 노드로 보내는 편이 프로덕션에 가깝습니다. 설치 복잡도와 장기 운영을 합치면 제어 면은 익숙한 Windows/Linux에 두고 실행 면을 NodeMini 클라우드 Mac mini 임대로 확장하는 구성이 현실적입니다.
조달 언어를 「노드」로 통일하면 재무와도 말이 통하고, 리전·디스크 등급·임대 기간으로 예산을 씁니다. OpenClaw 트래픽이 늘 때 개발기 이미지를 매번 갈아엎지 않고 실행층만 키울 수 있습니다.
토큰 로테이션 주체, 방화벽 예외 승인자, 권위 있는 대시보드 URL을 문서화해 두면 기능 플래그보다 거기서 장애가 줄어듭니다.
이 글은 교차 플랫폼 설치와 데몬 검수를 다룹니다.Ubuntu systemd 글과Docker 글은 프로덕션 토폴로지입니다. 더 많은 글은OpenClaw 카테고리 필터에서 보세요.
Node 버전, 상태 디렉터리가 동기 디스크에 없는지, 터미널이 Windows 네이티브인지 WSL2인지입니다. 병렬 용량이 필요하면임대 가격을 참고하세요.
SSH, VNC, 일반 네트워크는도움말 센터를 검색하세요. Gateway 라우팅과 터널은 위 두 프로덕션 글로 돌아가 대조합니다.