스니펫용 한 줄: 이 글은 컨테이너보다 앞선 macOS 네이티브 사실만 다룹니다. 공식 앱 또는 openclaw CLI로 설치한 뒤 OPENCLAW_STATE_DIR을 바탕화면·문서 iCloud 동기 트리 밖에 두고, TCC(손쉬운 사용, 자동화·Apple 이벤트, 화면 기록, 필요 시 마이크)를 릴리스 게이트로 관리합니다. launchd LaunchAgent와 터미널의 openclaw gateway start가 겹치면 이중 리스너가 생기므로 운영 모드는 하나만 남기고 openclaw doctor·openclaw gateway status로 증빙합니다. 세 OS 설치 전체는 설치·배포 가이드, 설치 후 검증은 doctor·WSL2 분기, 컨테이너 운영은 Docker 프로덕션 Runbook을 따릅니다. 물리 리전·임대는 6개국 Mac mini 임대 가이드와 함께 읽습니다.
OPENCLAW_STATE_DIR이 그 아래에 놓일 때 컨테이너에서는 보이지 않는 레이스가 생깁니다. 증상은 「가끔 페어링 성공, 재부팅 후 토큰 불일치」처럼 보입니다.openclaw와 공식 앱 번들의 헬퍼는 시스템에 다른 주체로 보입니다. 경로가 바뀐 업그레이드 뒤에는 이전 승인이 자동 이월되지 않아 스킬이 조용히 멈추고 HTTP 403처럼 명확히 떨어지지도 않습니다.패키지·채널·크로스 플랫폼 배포는 Windows·macOS·Linux 설치·배포 가이드를 단일 진실원으로 두고, 설치 후 검증·WSL2 인접 문제는 설치 후 doctor·Gateway·WSL2 분기를 따릅니다. 표준 형태가 이미지·오케스트레이션이면 Docker Gateway 프로덕션 Runbook을 주 문서로 삼고, 본 문서는 「여전히 메탈 macOS에 남는 틈」을 메우는 패치입니다. 리전·임대 조합은 6개국 Mac mini 임대 비용 가이드와 함께 검토해 소프트웨어만 고치고 물리 위치는 그대로 두는 실수를 피합니다.
리뷰에서는 설정 문제와 플랫폼 한계를 구분합니다. 전자는 본문 증상표로 15분 안에 한 줄 근으로 수렴해야 하고, 후자만 기능 요청·버전 업으로 승격합니다. 「재현 불가」를 적기 전에 다음을 확인합니다. 상태 경로가 로컬 APFS인가? TCC 스크린샷이 빌드와 함께 갱신되었는가? LaunchAgent 레이블이 유일한가? 이 세 가지가 의사결정을 정리합니다.
OPENCLAW_STATE_DIR: 자산 번호처럼 적고, 그냥 홈 한구석에 두지 않습니다환경 변수는 조직이 승인한 셸 프로파일이나 LaunchAgent의 EnvironmentVariables에 넣고 CMDB에 「경로·업무 시스템·담당자」 세 열을 남깁니다. 예시로 /usr/local/var/openclaw, /opt/openclaw/state, 동기화되지 않는 /Users/Shared/… 등을 쓸 수 있으며, 핵심은 df -h가 가리키는 마운트가 클라우드 동기 에이전트에 가로막히지 않는다는 점입니다.
사용자 홈 아래에 둘 경우에도 Mobile Documents, 클라우드 플레이스홀더, MDM이 재지정한 「문서」 경로는 피합니다. 「동료 A는 되고 B는 안 된다」면 재설치 전에 두 사람의 OPENCLAW_STATE_DIR 디바이스 노드와 inode 사용 상태를 비교합니다.
한 평가기에 여러 계정이 붙을 때 두 사람이 같은 state 폴더를 공유하기로 구두 합의하면 SQLite 잠금·.sock 생명주기·토큰 로테이션이 충돌합니다. 계정별 디렉터리와 서비스 정체를 분리하거나, 진짜 클러스터 토폴로지로 설계하고 아키텍처 리뷰에 명시합니다.
각 행에는 단 하나의 책임 역할(클라이언트·macOS 플랫폼·게이트웨이·외부 네트워크)만 붙입니다. 동일 plist 앞에 다섯 명이 동시에 SSH로 모이는 조직적 교착을 막습니다.
| 증상 | 유력 원인 | 안정화(단일 선택) |
|---|---|---|
| 페어링이 들쭉날쭉하고 재부팅 후에야 회복 | 상태 경로가 iCloud·동기 볼륨이거나 두 부모가 동일 디렉터리에 기록 | 로컬 APFS로 이전하고 launchd vs 수동 시작 중 하나만 채택 |
| AppleScript·창 자동화가 멈춤 | 실제 바이너리에 자동화·손쉬운 사용 승인이 없음 | 시스템 설정 → 개인 정보 보호 및 보안에서 재승인·업그레이드 후 재실행 |
| 캡처·녹화 파이프라인 무출력 | 「화면 기록」 항목 누락 | 해당 바이너리 허용 후 게이트웨이 부모 프로세스 재시작으로 TCC 부착 일치 |
| 포트 충돌·WebSocket 간헐 실패 | 이중 게이트웨이 또는 좀비 프로세스 | 테스트 plist launchctl bootout 또는 대화형 세션 종료 후 단일 오케스트레이션만 유지 |
| 주간에는 정상, 새벽 배치만 실패 | 노트북 수면·저전력 네트워크(OpenClaw 회귀 아님) | 권위 게이트웨이를 상시 전원 원격 Mac으로 이전하고 로컬은 CLI 클라이언트만 |
스케줄러 중첩은 인적 사고가 많습니다. 프로덕션에서 이미 LaunchAgent를 쓴다면 「임시로 게이트웨이 손 실행」은 레드라인으로 두고 대응하는 bootout·kickstart -k 복구 순서까지 같은 문서에 적습니다. 그렇지 않으면 압박 상황에서 두 번째 리스너가 뜨고 패킷 캡처 없이는 보이지 않습니다.
손쉬운 사용은 다른 앱을 제어하는 경계, 자동화(Apple 이벤트)는 스크립트가 대상 앱에 이벤트를 보낼 수 있는지, 화면 기록은 픽셀 채널입니다. 셋 중 하나라도 빠지면 스킬은 오류 대신 「무한 대기」로 보입니다. 음성 스킬을 쓰면 마이크도 명시적으로 켭니다. Linux 컨테이너에서의 기본 가정을 그대로 가져오면 안 됩니다.
macOS·OpenClaw 메이저 업그레이드마다 10분짜리 「프라이버시 점검」을 일정에 넣고, 담당자가 시스템 설정을 캡처해 변경 티켓에 첨부합니다. 스크린샷 없는 「확실히 켰어요」는 교대 근무에서 증거가 되지 않습니다.
규제 산업에서는 위 캡처가 최소 권한 감사의 증거가 됩니다. 어떤 바이너리가 언제 허용되었고 어떤 티켓과 연결되는지 구성 관리 DB로 거슬러 올라갈 수 있어야 합니다.
openclaw gateway start: 「정사」는 하나만LaunchAgent의 가치는 무인입니다. 재부팅·데몬 크래시·짧은 네트워크 플랩 뒤에도 정책으로 돌아옵니다. 임대해 전원이 안정적인 원격 Mac에서 CI 러너나 모델 사이드카와 같이 두기 좋습니다. 수동 시작은 엔지니어가 터미널을 보며 디버깅한다는 전제의 개발대용입니다.
디버깅 시 먼저 launchctl print gui/$(id -u)로 레이블과 마지막 종료 코드를 봅니다. 반드시 수동으로 띄워야 한다면 LaunchAgent를 깨끗이 내리거나 비활성화해 지금 PID의 로그만 보게 합니다.
문서에는 「개발 모드」와 「데이터센터 모드」 명령 블록을 병렬로 두고 PR 템플릿에 「이번 변경은 어느 모드에서 검증했는가?」를 넣습니다. 이 줄이 없으면 로컬 녹색·프로덕션 적색 같은 허위 안전이 생깁니다.
로컬은 사람이 쓰는 머신에 제어 평면을 묶습니다. 반복이 빠르고 프롬프트 경로가 짧지만 수면·VPN·핫스팟 전환·회의 앱의 오디오 점유를 그대로 물려받습니다. 원격은 권위 세션과 장시간 연결을 고정 호스트·고정 출구에 둡니다. 조직 단위 입구나 7×24 스킬 실행면에 맞습니다.
CLI UX는 같을 수 있습니다. 달라지는 것은 어느 디스크가 주 상태를 갖는지, 어느 NIC가 기본 라우트인지, 어느 리전이 ASC·모델 클러스터 RTT에 유리한지입니다. 서비스 카탈로그에 적어 두면 보안 리뷰에서 「실험용 노트북 게이트웨이」와 「싱가포르 랙 권위 게이트웨이」를 섞어 말하지 않습니다.
두 모드가 공존하면 모니터링에서 호스트명 접두사를 달리해 Grafana 한 패널에 섞여 오탐이 나지 않게 합니다.
OPENCLAW_STATE_DIR·로그·선택 캐시를 만들고 실행 사용자 소유인지 확인합니다(root 혼용 금지).openclaw doctor·openclaw gateway status 출력을 변경 티켓에 붙입니다.교차 플랫폼 증상을 맞춰 보려면 doctor 분기 문서의 필드 명명을 참고하고, 이미지 레이어·토큰 단일 출처 이슈는 Docker 프로덕션 Runbook을 우선합니다. cgroup 문제를 TCC로 기록하지 않도록 합니다.
#!/usr/bin/env bash
set -euo pipefail
# 읽기 위주 점검 — 경로는 조직 표준에 맞게 바꿉니다
export OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/Library/Application Support/OpenClawState-local}"
umask 077
mkdir -p "$OPENCLAW_STATE_DIR"
echo "OPENCLAW_STATE_DIR=$OPENCLAW_STATE_DIR"
command -v openclaw >/dev/null && openclaw doctor || echo "doctor: CLI가 PATH에 없음"
openclaw gateway status 2>/dev/null || echo "gateway: 응답 없음(의도적으로 꺼져 있으면 정상)"
launchctl print "gui/$(id -u)" 2>/dev/null | grep -i openclaw || echo "launchd: openclaw 레이블 없음(수동 전용이면 무시)"
gateway status까지 걸린 초: 악화 시 plist 의존 순서와 TCC 프롬프트 가로채기를 먼저 의심하고 런타임 언어를 의심하지 않습니다.OPENCLAW_STATE_DIR가 로컬 APFS 블록인지: df와 마운트 테이블로 증명합니다. FUSE·동기 스텁이 보이면 미달입니다.원본 명령 출력 없는 결론은 RCA에 넣지 않습니다. 다음 on-call이 같은 이야기를 다시 듣지 않기 위함입니다.
노트북은 이동에 최적화되어 덮개를 닫으면 잠들고, 배터리 정책으로 피크 시 클럭이 줄며, 기업 VPN은 실시간 트래픽을 우회시킵니다. 권위 게이트웨이를 이런 장애 도메인에 묶는 것은 자동화 SLA를 개인 일정·회의실 네트워크에 묶는 것과 같습니다.
반대로 MACCOME 클라우드 Mac mini(M4 / M4 Pro)는 여섯 리전에서 전용 Apple Silicon·안정 전원·예측 가능한 디스크 구성을 제공합니다. LaunchAgent·장기 토큰·모니터링 프로브를 한 대에 묶고 개발자 노트북은 가벼운 CLI·디버그 채널만 갖게 할 수 있습니다. 리전·청구 타당성은 노드 임대·지연 가이드의 RTT·임대 조합표에 맡기면 「게이트웨이가 사람을 따라다니는」 숨은 중단을 줄입니다.
TCC·동기 디스크·launchd는 네이티브 runbook에, cgroup·이미지 digest·bridge 네트워크는 Compose 문서에 둡니다. 한 사건이 양쪽을 동시에 밟으면 타임라인을 두 갈래 RCA로 나눕니다. 그렇지 않으면 상호 비난만 남습니다.
변경 창을 닫기 전에 openclaw doctor를 다시 돌려 출력과 버전을 지식 베이스에 고정합니다. 권위 게이트웨이가 원격에 있어야 한다면 요약에 「노트북 권위 모드에서는 이번 검증을 통과하지 않았다」를 명시해 이후 담당자가 설정을 오용하지 않게 합니다.
FAQ
프로덕션 Gateway는 모두 Docker인데 왜 LaunchAgent를 알아야 하나요?
GUI·운영 노트북에서 메탈 먼저 페어링을 시작하는 경우가 많고 Compose가 고정되기 전 단계가 있습니다. launchd와 Compose 경계를 알면 장애 대응 중 추가 프로세스로 이중 리스너가 생기는 일을 줄입니다.
7×24 OpenClaw Gateway를 둘 호스트와 임대는 어디서 보나요?
먼저 Mac mini 대여 가격에서 리전·플랜을 비교하고, 과금·접속 세부는 같은 공개 페이지 안내를 따르거나 지원 경로로 후속 확인합니다.