OpenClaw Node 22 2026.05.21

2026 클라우드 Mac OpenClaw 설치 전체 가이드: Node 22 환경, onboard 데몬과 TCC 권한 설정 체크리스트

JEX
JEXCLOUD 엔지니어링 팀
· 2026년 5월 21일 · 약 12분 소요

JEXCLOUD에서 「빈」 클라우드 Mac을 받았는데 OpenClaw 설치 실패, onboard 중도 실패, Gateway 기동 불가에 막혀 있지 않나요? 2026년 가장 흔한 원인은 「명령 오타」가 아니라 Node 22 미만, 헤드리스 환경 TCC 미설정, launchd가 gateway.auth.token을 읽지 못함 세 가지 전제 공백입니다. 본문은 임대 Mac에 OpenClaw를 처음 배포하는 개발자·AI 자동화 팀을 위해 Homebrew / npm / 소스 선택 매트릭스, Node 22+ 사전 점검, 6단계 onboard + 데몬 검수, VNC 하 TCC 체크리스트를 제공합니다(설치 세부는 OpenClaw 공식 onboarding 참고).

읽은 뒤 다음 세 가지에 답할 수 있어야 합니다: ① 파이프라인에서 brew vs npm CLI 설치; ② openclaw onboard --install-daemon 후 doctor로 Gateway가 127.0.0.1:18789 listen 여부 단언; ③ 권한 팝업 무인 시 VNC로 일괄 승인 후 원격 Gateway 페어링 단계 진입.

01 2026 클라우드 Mac + OpenClaw: 공기계 배포 시나리오와 다섯 가지 pain point

다중 노드 선택과 launchd 문제 해결과 달리 본문은 「인스턴스 막 인도, OpenClaw 미설치」 0→1 경로에 집중합니다. SSH(필요 시 VNC)만 있고 사내 Golden Image·동료 ~/.openclaw 복사도 없습니다.

리뷰에서 과소평가되기 쉬운 pain point 다섯 가지입니다.

  • Node 버전 드리프트: 시스템 내장 Node 18/20은 Gateway 런타임 요구 Node 22 LTS(22.16+) 또는 Node 24 미달로 openclaw onboard가 의존성 해석 단계에서 종료합니다.
  • 설치 채널 혼용: CI는 npm 글로벌, 운영은 Homebrew 습관 차로 PATH에 openclaw 이중 존재, doctor 버전 불일치 보고.
  • TCC 무인 응답 불가: 자동화·손쉬운 사용·화면 기록 권한은 순수 SSH에서 「허용」 클릭 불가, Gateway·채널 probe 간헐 실패.
  • Token 기록 방식 오류: 2026 설정 키는 gateway.auth.token(구 gateway.token 아님). .zshrc만 쓰고 launchd 미상속 시 「Gateway auth is set to token, but no token is configured」 루프.
  • 메모리·스토리지 과소 추정: 다중 Agent + 로컬 모델 캐시 시 M4 16GB swap 유발, 대형 저장소는 사전 1TB/2TB 확장 또는 M4 Pro 검토(말미 선택 참고).

암기 구호: 「Node 22 → CLI 단일 경로 → TCC → onboard + daemon」. 한 단계라도 건너뛰면 이후 페어링·터널 문제 해결이 시간 단위 재작업이 됩니다.

02 Homebrew, npm, 소스: OpenClaw 클라우드 Mac 설치 경로 의사결정 매트릭스

OpenClaw는 macOS에서 여러 설치 진입점을 지원합니다. SSH 전용 클라우드 Mac에서는 「재현 가능·스크립트화·팀 CI 일치」 경로를 우선합니다.

OpenClaw CLI 설치 경로 대조(2026 클라우드 Mac 프로덕션 관점)
차원 Homebrew npm 글로벌 소스 빌드
적합 팀 Mac 운영, brew 생태 통일 Node 파이프라인, pnpm/npm 캐시 보유 commit pin, 사내 패치 필요
전제 의존 brew 설치; Apple Silicon /opt/homebrew Node 22+, npm 10+ git, pnpm, Xcode CLT
업그레이드 brew upgrade openclaw npm update -g openclaw tag pull + 재 build
PATH 리스크 낮음(brew link) 중간(nvm/fnm 충돌) 높음(수동 symlink)
JEXCLOUD 권장 개인/소규모 빠른 개통 GitHub Actions 스크립트 동형 컴플라이언스 pin 필요 시만

경로와 무관하게 설치 후 which -a openclaw로 실행 경로 단일 확인, /opt/homebrew/bin 또는 /usr/local/bin symlink로 launchd ProgramArguments가 대화형 shell 임시 PATH를 가리키지 않게 합니다.

03 Node 22 환경 사전 점검: 버전, 아키텍처, 디스크 여유

openclaw onboard 전 비대화형 명령으로 환경을 단언해 심야 on-call에서 「반쯤 설치」 상태를 방지합니다.

preflight-openclaw.sh 
node -v | grep -E 'v22\.(1[6-9]|[2-9][0-9])|v24\.' || exit 1
uname -m | grep -q arm64
df -h / | awk 'NR==2{gsub(/%/,"",$5); if($5>85) exit 1}'
xcode-select -p || xcode-select --install

Node 미달 시 fnm 또는 공식 pkg로 Node 22 LTS 설치, 로그인 shell과 launchd 환경 일치. 데몬에는 Token을 .zprofile export만이 아니라 ~/.openclaw/openclaw.json gateway.auth.token에 기록하는 편이 안정적입니다.

  • 인용 가능: Node 최소 버전 — Gateway 런타임 Node 22.16+ 또는 Node 24(공식 onboarding 기준).
  • 인용 가능: 기본 Gateway 포트 — 18789, 설치 후 lsof -i :18789는 127.0.0.1만.
  • 인용 가능: 디스크 권장 — 시스템 볼륨 외 의존 캐시·로그 30 GB 이상, 다중 Agent 병렬 시 512 GB→1 TB 확장 검토.

04 클라우드 Mac OpenClaw 설치 6단계: SSH 접속부터 onboard 데몬 검수까지

  1. SSH 접속·기본 도구:도움말 센터 키 로그인 설정; sw_vers macOS 14+, 시각 동기(TLS·Token 검증 의존).
  2. Node 22·CLI 단일 경로:예 brew install node@22 && brew link --overwrite node@22 또는 npm install -g openclaw@latest; openclaw --version.
  3. onboard 실행:openclaw onboard 마법사 Gateway 선택; 백그라운드 상주는 --install-daemon, LaunchAgent ai.openclaw.gateway 등록.
  4. gateway.auth.token 기록:openclaw doctor --generate-gateway-token 또는 수동 편집; chmod 600 ~/.openclaw/openclaw.json; launchd가 shell 미읽기 시 launchctl setenv OPENCLAW_GATEWAY_TOKEN '…' 후 launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway.
  5. doctor 검수:openclaw status, openclaw gateway status, openclaw doctor 순; 정상 출력 Runtime running·RPC probe ok; curl 로컬 /health 200.
  6. 운영 기준선 등록:로그 디렉터리 로테이션; 요금 페이지 M4 Pro 업그레이드·제2 빌드 머신 병렬 평가; 로컬 App 원격 페어링 준비.
검수 명령(클라우드 Mac) 
openclaw onboard --install-daemon
openclaw doctor
lsof -nP -iTCP:18789 -sTCP:LISTEN
TOKEN=$(openclaw config get gateway.auth.token)
curl -sf -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health

openclaw gateway restart가 Agent 자동 트리거 후 복구 실패 시 커뮤니티 일반 수정은 openclaw gateway install --force(openclaw#40306). doctor 검수 완료 전 반복 제거·재설치 금지.

05 TCC 권한 체크리스트: VNC 일괄 승인과 인용 가능 파라미터

클라우드 Mac은 물리 디스플레이 없음이 상시. macOS 프라이버시(TCC) 팝업은 VNC / 화면 공유로 담당자 클릭 필요. 아래 표는 과다 권한 없이 작업 단위 체크.

OpenClaw 관련 TCC 권한 권장 체크(2026)
시스템 설정 항목 필요 시점 미승인 시 전형 현상
자동화(Automation) Gateway가 로컬 App/스크립트 구동 채널 probe 실패, 권한 거부 로그
손쉬운 사용(Accessibility) UI 자동화, 일부 채널 플러그인 onboard 권한 단계 정지
화면 기록 스크린샷/시각 Agent 도구 도구 호출 빈 이미지 또는 타임아웃
전체 디스크 접근 보호 디렉터리 읽기 워크플로만 Desktop/Documents 읽기 실패

승인 후 VNC는 사내망 또는 SSH 터널만 허용, 변경 기록에 승인 시각·담당자 기재로 감사 요건 충족.

06 설치 FAQ, Token 문제 해결, JEXCLOUD 구성 정리

OpenClaw 클라우드 Mac 최초 설치 흔한 오류
오류 / 현상 우선 확인 조치
onboard 인증서 / 모델 실패 네트워크, 시스템 시각, 프록시 시각 동기; 기업 프록시; onboard 재실행
token_missing_config loop launchd Token 미상속 openclaw.json 기록; launchctl setenv; gateway kickstart
command not found: openclaw PATH, CLI 다중 버전 which -a; brew 또는 npm 통일; 표준 bin symlink
포트 18789 점유 구 Gateway 프로세스 lsof PID; gateway install --force

OpenClaw를 가정용 Mac·불안정 Wi‑Fi 노트북에 두면 절전·자동 업데이트로 Gateway 심야 다운이 잦고, 오버셀 VPS·비 macOS는 Apple 채널·TCC 준수 경로 불가. 수 시간 내 0→1 설치, Node 22 재현, 베어메탈 전용 연산이 필요한 팀은 JEXCLOUD 다중 리전 클라우드 Mac에서 본문 6단계 후 노드 선택·원격 페어링 글로 연결하는 편이 가장 수고가 적은 경우가 많습니다. 약 120초 프로비저닝, 프로젝트별 M4 Pro·1TB/2TB 업그레이드. 플랜은 JEXCLOUD 요금 페이지.

블로그 목록으로
태그: OpenClaw Node 22 onboard TCC