2026 캐나다 cloud Mac M4 무헤드 OpenClaw CI: install-cli.sh, --no-onboard, Mac mini hosting launchd 프로브

플랫폼 팀이 OpenClaw를 캐나다 원격 Mac M4로 옮길 때 흔한 실수는 데스크톱 플레이북을 그대로 복사하는 것입니다. Screen Sharing을 열고 전체 openclaw onboard를 실행한 뒤 SSH가 끊긴 후에도 Gateway가 살아 있기를 바랍니다. CI와 배치 워크로드에는 다른 계약이 필요합니다—공식 install-cli.sh와 --no-onboard를 쓰는 헤드리스(headless) 설치 경로, 사전 주입된 설정, 마법사 대신 launchd 헬스 프로브. 이 글은 질문 하나만 다룹니다: 클라우드 Mac / Mac mini 클라우드 빌드 시트에서 재현 가능한 헤드리스 OpenClaw CI를 어떻게 착지시키는가. SSH 터널 vs 직접 Gateway 논쟁은 반복하지 않습니다(OpenClaw 캐나다 M4: SSH Gateway, 18789 token 및 launchd). 대화형 onboard 로그 플레이북도 다루지 않습니다(원격 Mac 설치·onboard와 Gateway 24/7). 같은 Mac mini 호스팅 시트에서 GitHub Actions runner도 돌린다면 클라우드 Mac 자체 호스팅 macOS runner에 따라 Unix 사용자와 launchd 레이블을 분리해 Node 버전과 포트 18789 충돌을 막으세요.

1. 대화형 onboard 대신 헤드리스 --no-onboard가 필수일 때

대화형 openclaw onboard는 실 GUI 세션이 있는 Mac에서 운영자가 TCC(손쉬운 사용, 자동화, 화면 기록)를 승인하는 첫 실행 경험에 적합합니다. 대상이 SSH나 자체 호스트 runner로만 접근하는 클라우드 Mac CI 레인이고 설정이 내부 템플릿으로 이미 생성되었다면, 마법사를 계속 호출하면 파이프라인을 막고 Git에서 재구축 불가능한 스노우플레이크 호스트를 만듭니다.

헤드리스 계약은 다음과 같습니다:

• install-cli.sh로 Node LTS와 전역 openclaw CLI semver 고정.
• --no-onboard 전달, 설정 디렉터리(상류 문서 기준, 보통 ~/.openclaw)를 Secrets 관리에서 동기화.
• 에이전트가 브라우저 자동화로 TCC가 여전히 필요할 때만 일회성 Screen Sharing 창 예약. 이후 launchd만으로 운영.

「원격 Mac 안정화」 노트와의 차이: 이 글은 버전 관리된 CI Runbook과 프로브 스크립트를 제공하며 데스크톱 운영자 매뉴얼이 아닙니다. 새 시트마다 onboard에 손으로 답하는 팀은 아직 헤드리스 성숙도에 도달하지 못했습니다.

2. 헤드리스 install-cli.sh vs 전체 onboard: 선택 방법

공급자에서 새 Mac mini 클라우드 시트를 프로비저닝할 때 먼저 헤드리스 smoke 파이프라인을 실행하세요. 「한 번 수동 onboard」한 팀은 몇 주 뒤 1시간 안에 Gateway를 DR할 수 없다는 사실을 자주 발견합니다.

비교 표의 「전형적 실패」 열은 Runbook 업데이트 트리거로 쓰세요. PATH 드리프트가 주간으로 재발하면 plist EnvironmentVariables와 CI Node pin을 같은 변경으로 묶어야 합니다. 클라우드 Mac 빌드 시트에서는 config semver와 CLI semver를 다른 티켓으로 올리지 않는 운영이 sharp·401 연쇄 장애를 줄입니다.

3. 헤드리스 프로비저닝 Runbook: install-cli.sh와 설정 주입

아래 예는 VNC 관리자와 분리된 전용 시스템 사용자 openclaw-ci를 가정합니다. 캐나다 M4 클라우드 Mac에서 Node는 LTS(2026년 기준 22.x가 합리적)에 pin하고 runner 사용자 nvm shim과 분리—launchd job은 대화형 shell 프로필을 로드하지 않습니다.

# 클라우드 Mac에서 openclaw-ci로 SSH
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
curl -fsSL https://example.openclaw.dev/install-cli.sh | bash -s -- --no-onboard

# CI secrets에서 config 복원 — token을 Git에 커밋하지 말 것
install -d -m 700 "$OPENCLAW_CONFIG_DIR"
echo "$OPENCLAW_CONFIG_JSON" > "$OPENCLAW_CONFIG_DIR/config.json"

# 지원 시 Gateway launchd 서비스 설치
openclaw gateway install-daemon
openclaw doctor --non-interactive

취미 설치와 프로덕션 클라우드 Mac 레인을 가르는 운영 메모:

1. 멱등성: workflow는 재실행을 견뎌야 함. 좋은 스크립트는 이미 설치 시 no-op 또는 버전 수렴.
2. Semver 잠금: Runbook에 openclaw --version과 config schema 버전 기록. 업그레이드는 변경 창과 롤백 단계.
3. 디스크 레이아웃: npm/pnpm 캐시를 독립 wipe 가능 경로에. 같은 호스트에서 iOS도 빌드하면 Derived Data와 분리.
4. Checksum: 프로덕션에서 install 스크립트 digest pin. 검증 없는 curl | bash는 공급망 사고 대기.

4. launchd 헬스 체크: 프로세스, 포트, 로그 삼각

헤드리스에서 「Gateway가 떠 있다」는 것은 종종 PATH가 완전한 SSH 세션에서 curl을 한 번 돌린 것을 의미합니다. 프로덕션 프로브는 launchd 상태, listen 주소, 로그 키워드를 함께 검증. 5분마다 cron 또는 예약 GHA workflow로 실행:

#!/bin/bash
set -euo pipefail
LABEL="ai.openclaw.gateway"
launchctl print "gui/$(id -u)/$LABEL" | grep -q 'state = running'
lsof -nP -iTCP:18789 -sTCP:LISTEN | grep -q openclaw
curl -sf -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/health | grep -q '"ok":true'
tail -n 50 ~/Library/Logs/openclaw/gateway.log | grep -Ei 'sharp|EADDRINUSE|401' && exit 1 || true

plist는 절대 경로로 openclaw를 호출하고 EnvironmentVariables에 PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin을 명시. launchd는 대화형 ~/.zprofile을 읽지 않습니다. 이 불일치가 임대 클라우드 Mac에서 「SSH로는 되는데 daemon은 즉시 종료」의 최대 원인입니다.

프로브에 duration 메트릭 추가: /health p95 지연 추적, 콜드 스타트가 workflow 타임아웃 예산을 넘으면 알림. 대화형 4초, launchd 30초 Gateway는 타이트한 재시도 CI job을 실패시킬 수 있습니다.

헤드리스 운영에서는 프로브 결과를 시계열 DB에 기록하고 주간 리포트로 EADDRINUSE·401 트렌드를 보는 것을 권장합니다. 일회성 수동 curl 성공은 SLA 증거가 아닙니다. Mac mini 클라우드 시트에서는 재부팅 후 90초 안에 녹색으로 복귀하는 것을 SLO로 Runbook에 명시하고, 초과 시 자동 launchctl kickstart를 시도하세요.

5. 프로브 결과 매트릭스: 녹색, 노랑, 빨강 대응

노랑이 24시간 넘게 지속되면 릴리스 블로커로 취급. 헤드리스 CI는 예측 가능한 Gateway를 가정; 간헐적 인증·지연 실패는 agent 쪽에서 값비싼 일괄 타임아웃으로 증폭됩니다.

운영자는 노란 상태에서 agent 동시 실행 수를 줄이고 Token 동기화와 openclaw doctor를 먼저 실행하세요. 빨강으로 넘어가기 전에 Mac mini 호스팅 시트의 디스크 I/O·메모리 압력이 Gateway 재시작을 지연하지 않는지도 확인합니다.

6. Apple Silicon 클라우드 Mac에서 sharp 네이티브 모듈

OpenClaw 의존성에 sharp(libvips 바인딩)가 포함됩니다. M4 arm64 호스트에서 Node 메이저 불일치나 설치 사용자 혼용 시 Cannot find module '../build/Release/sharp.node' 또는 런타임 아키텍처 불일치가 납니다. 헤드리스 CI는 첫 실패 job에서야 알면 안 됩니다—golden image 또는 post-install hook에 sharp 검증을 구워 넣으세요.

6.1 흔한 실패와 수정

• 사용자 불일치: root가 전역 CLI 설치, openclaw-ci가 daemon 실행—서비스 사용자로 sharp 또는 CLI 재설치.
• Node 업그레이드 후 미 rebuild: Node bump 후 npm rebuild sharp 또는 openclaw CLI 패키지 재설치.
• Rosetta 혼용: plist와 CLI 모두 arm64; file $(which node)는 arm64 보고.
• 오프라인 캐시: 대역폭 제한 Mac mini 클라우드 호스트에서 sharp 바이너리 prefetch, CI 매 job GitHub releases 방지.
• 복수 Node 관리자: daemon에 Homebrew Node, 대화 shell에 nvm 혼용 금지—하나의 스토리를 plist에 인코딩.

node -p "process.arch + ' ' + process.version"
npm ls sharp --global 2>/dev/null || true
npm rebuild sharp --foreground-scripts
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor.log
grep -i sharp /tmp/openclaw-doctor.log && exit 1 || echo "sharp OK"

doctor가 여전히 sharp를 보고하면 동일 install-cli.sh 아티팩트에서 Node와 CLI 채널을 맞춘 뒤 앱 계층을 추적. Homebrew Node + npm 전역 CLI에 plist PATH 미수정은 Mac mini 호스팅 티켓에서 가장 흔한 sharp 엣지입니다.

골든 이미지를 쓰는 팀은 이미지 갱신마다 npm rebuild sharp와 openclaw doctor --non-interactive를 post-install hook에 넣으세요. 대역폭 제한 Mac mini 클라우드에서는 sharp prebuilt를 로컬 mirror에 두면 CI job마다 GitHub 의존이 줄고 헤드리스 lane 가용성이 올라갑니다.

7. CI에서 Gateway 18789 경계와 token 로테이션

헤드리스 pipeline은 bearer token으로 로컬 Gateway 127.0.0.1:18789 호출—포트를 공인 인터페이스에 노출하지 말 것. token은 CI secrets(예 OPENCLAW_GATEWAY_TOKEN)에 저장. 로테이션: 새 token을 config에 기록, daemon reload, 프로브 녹색, 구 secret 폐기. 루프백은 runner와 Gateway가 한 클라우드 Mac을 공유할 때 지연 최소. 크로스 호스트는 위 SSH Gateway 글 참조.

workflow는 명시 타임아웃과 제한 재시도. 재부팅 후 콜드 스타트 10–30초 가능. 프로브 실패 시 파괴적 reinstall 전 launchctl kickstart 한 번. macOS 패치 후 boot storm에서 동작 config를 지우지 않도록 on-call에 문서화.

token 로테이션은 CI 파이프라인과 Gateway를 같은 변경 티켓에 묶어 한쪽만 갱신되는 split-brain을 막으세요. 프로덕션 클라우드 Mac에서는 staging 시트에서 새 token을 검증한 뒤 production config를 전환하는 2단계 배포가 안전합니다. 롤백 절차에는 구 token 만료 시점과 gateway.log의 401 스파이크 해석을 포함하세요.

8. 호스팅 Mac 시트에서 헤드리스 OpenClaw 보안 기선

• 전용 사용자: openclaw-ci admin/VNC 로그인 없음.
• Secrets: config와 token은 vault만. 볼륨 FileVault 활성.
• 네트워크: 인바운드 SSH 또는 Tailscale만. 18789 LAN 브로드캐스트 금지.
• 공급망: install 스크립트 checksum 검증. 프로덕션 미감사 pipe-to-bash 차단.
• 감사: gateway.log 14일 보존. 401과 sharp 키워드를 로그 스택으로.
• 폭발 반경: agent tools profile 최소 권한. 불신 fork PR은 프로덕션 Gateway 호스트 접근 금지.

헤드리스 자동화는 속도를 높이고 의심스러운 install URL에 사람이 멈추는 순간도 제거합니다. install 스크립트 URL과 checksum을 프로덕션 TLS 인증서와 동일한 엄격함으로 다루세요.

정기 DR 훈련에서는 Runbook대로 30분 안에 새 클라우드 Mac 시트를 재구축할 수 있는지 측정하세요. 헤드리스 CI의 가치는 대화형 onboard 없이 fleet을 재생성할 수 있다는 점에 있습니다. Mac mini 호스팅 계약에서는 스냅샷과 FileVault 복구 키 보관 위치도 Runbook에 포함하세요.

감사 로그는 SIEM으로 보내고 401·sharp 키워드 알림 규칙을 설정하세요. fork PR이 프로덕션 Gateway 호스트에 닿는 workflow 경로는 branch protection과 environment 승인으로 차단합니다.

9. 헤드리스 OpenClaw를 GHA 또는 내부 CI에 연결

Gateway 프로브가 녹색이 된 뒤 가드된 단계로 pipeline에 OpenClaw 노출:

1. GitHub Environments에서 OPENCLAW_GATEWAY_TOKEN export. 프로덕션은 리뷰어 필수.
2. agent job은 runs-on: [self-hosted, macos-m4-canada, openclaw] 레이블. 서명/archive job과 분리.
3. 비용 큰 LLM·브라우저 단계 전 cron과 동일 shell 프로브로 fast fail.
4. 실패 시 openclaw doctor 출력을 workflow artifact로 저장해 비동기 리뷰.

메모리 계획: 24GB Mac mini 클라우드 시트에서 같은 밤 xcodebuild archive도 돌리면 통합 메모리 압력 80% 초과 시 OpenClaw agent 배치 일시 중지. 큐 깊이 알림으로 「GitHub가 느림」 오인을 막고 호스트 과부하를 드러냅니다.

GHA workflow에서는 OpenClaw 단계 전에 memory_pressure 또는 vm_stat 기반 preflight를 넣으면 야간 archive와 agent 충돌을 줄입니다. 라벨 openclaw를 archive 전용 runner와 섞지 않는 것도 Mac mini 호스팅 운영의 기본입니다. 실패 artifact에는 doctor 출력과 최근 gateway.log 200줄을 함께 두면 VNC 없이도 트리아지가 현실적입니다.

10. 캐나다 M4 전용 시트 첫 주 체크리스트

1. Mac mini 호스팅 플랜 선택(CI + Gateway는 24GB RAM, 512GB SSD 이상).
2. openclaw-ci 생성. install-cli.sh --no-onboard smoke 통과.
3. config·token 주입. openclaw doctor --non-interactive 클린.
4. launchd 설치. 녹/노/적 프로브와 페이징.
5. sharp 사전 검증. Node·CLI 버전 Runbook 잠금.
6. GHA runner 공유 시 사용자 분리·포트 충돌 없음 확인.
7. 재구축 문서: 새 클라우드 Mac 시트는 30분 내 동일 Gateway 동작.

11. FAQ

--no-onboard 후에도 VNC가 필요한가?

에이전트가 브라우저 자동화나 TCC를 요하면 일회 그래픽 세션. 순수 CLI·API Gateway는 launchd 안정 후 VNC 없이 장기 운영 가능.

install-cli.sh vs 전체 install.sh?

CI가 CLI + Gateway만 필요하면 install-cli.sh. 메뉴 막대 앱 포함 전체 설치자는 반복 헤드리스 runner 배포에 부적합.

프로세스는 떠 있는데 프로브 401?

대개 token 로테이션 드리프트나 workflow가 구 secret 전송. 디스크 config와 Authorization 헤더 정렬, stale token 주입 프록시 확인.

SSH에서는 sharp OK, launchd에서는 실패?

거의 항상 PATH 또는 사용자 환경 차이. launchctl print environment와 대화 env를 나란히 비교.

macOS에서 Docker로 OpenClaw Gateway?

Mac Docker는 네이티브 TCC·GUI 자동화를 대체 못 함. Gateway는 네이티브 launchd. 컨테이너는 주변 도구만.

한 호스트에서 OpenClaw와 GitHub Actions 스케줄?

agent 배치는 archive 피크 회피. 메모리 80% 초과 시 agent 일시 중지. 레이블·동시성은 자체 호스트 runner 글 참조.

Hashvps 캐나다 노드가 헤드리스 OpenClaw에 적합한가?

전용 IPv4, 베어메탈 M4, 상시 SSH가 필요하면 적합. npm 캐시와 로테이션 gateway 로그에 디스크 tier 충분한지 계약 전 확인.

표준 CLI 업그레이드 절차?

유지보수 창: launchctl bootout, install-cli로 버전 수렴, npm rebuild sharp, doctor, 프로브 녹색, 트래픽 복구.