OpenClaw 설치 완전 가이드:
베어 메탈 Mac에서 AI 에이전트를 제로에서 본격 운영까지

수 주 단위로 OpenClaw Gateway를 전용 Apple Silicon 베어 메탈에 올릴 계획이라면, 가장 자주 걸리는 지점은 npm install 입력 자체가 아닙니다. 절전 정책, 대화형 셸과 상주 프로세스의 PATH 차이, launchd reload 의미론, 로그 관측 경로입니다. 본문은 변경 티켓에 그대로 붙여 넣을 수 있는 운영 형태를 목표로, 공식 설치 가이드의 골격에 맞춰 버전 게이트, 삼자 비교 표, 순서가 있는 체크리스트 두 벌, 분류 표를 배치합니다. 하드웨어 구성과 표시 가격은 CALMVPS 요금 페이지를 참고하십시오.

읽고 나면 다음을 판단할 수 있습니다. 상류 문서가 요구하는 Node 하한을 내 환경이 충족하는지. 대화형으로 검증된 상태에서 예기치 않은 포트 충돌 없이 launchd로 옮기는 절차. 리스너가 침묵할 때 먼저 모을 증거. 이후는 복사·붙여넣기가 아니라 각 릴리스의 Setup 페이지를 반드시 1차 정보로 확인해야 합니다.

01 전제 조건: 가정과 드러나지 않는 비용을 정리합니다

베어 메탈은 일회용 클라우드 데스크톱과 다르게, 머신 전체 상태를 우리가 짊어지는 전제가 됩니다. NVMe를 이웃 테넌트와 다투는 소음은 사라지지만, 공격적인 전력 관리나 심야 OS 유지보수 창을 다른 주체가 대신 흡수해 주지는 않습니다. Gateway를 일시 스크립트 취급으로 굴리기 시작하는 팀은, 절전으로 TCP가 끊겨 조용히 죽는 사례나, 로그가 시스템 볼륨에 쌓여 빌드 산출물과 디스크를 다투는 사례를 나중에서야 마주합니다.

OpenClaw를 설치하기 전에 아래 항목을 이륙 전 수락 조건으로 취급하고, 사후 포스트모템 목록으로 미루지 마십시오.

  • 절전과 스케줄링: 상시 연결을 멈추지 않는 정책을 확정하십시오. Gateway는 안정적인 heartbeat를 전제합니다.
  • 디스크와 캐시: 전역 npm 또는 pnpm 캐시, Gateway 로그의 물리적 위치를 분리하여 빌드 작업과 같은 볼륨에서 경쟁하지 않게 하십시오.
  • 네트워크 이그레스: 상위 방화벽에서 HTTPS 출구와 리스너 포트를 확인하십시오. 다지역 구성에서는 DNS 왕복과 TLS 왕복이 CPU 그래프에 잘 드러나지 않는 지연 요인이 됩니다.
  • 비밀 처리: 모델 공급자 API 키, 채널 OAuth 자료, 키체인 정책을 분리하고, launchctl 디버그 출력에 평문이 새지 않게 하십시오.
  • 관측 가능성: log stream 조건자와 디스크 로그 경로를 미리 정하십시오. PID 존재만으로는 장애 대응이 부족합니다.

Gateway 용량 계획은 피크 CPU보다 정상 상태 메모리와 디스크 I/O의 꼬리 지연이 중심이 됩니다. Apple Silicon 단일 테넌트는 스케줄링 분산을 낮출 수 있지만, 모델 웜업 시 GC 스파이크와 채널 동시 팬아웃은 여전히 여유를 요구합니다. 하위 채팅 표면에 SLA를 약속하기 전에 최소 일주일 분량의 샘플을 채취하여 운영이 근거를 갖도록 하십시오.

보안 기준도 베어 메탈에서는 달라집니다. 벤더가 단단히 굳힌 어플라이언스 이미지 안에 있는 것이 아니라, 기본값 그대로의 macOS를 함께 끌고 갑니다. 패치 주기, 관리자 SSH 키, FileVault 방침은 Gateway 업그레이드 경로와 같은 런북에 두어, 장애 순간 즉흥 판단을 줄이십시오.

베어 메탈이 주는 이득은 분산의 감소입니다. 더 빠른 칩을 쫓기 전에 에이전트를 멈추는 행동부터 없애십시오.

02 의사결정: 노트북·베어 메탈·시간 공유형 Mac 클라우드

같은 OpenClaw 명령이라도 얹는 운용체에 따라 전제가 달라집니다. 노트북은 GUI 세션과 절전 리스크를 끼고 들어옵니다. 시간 공유형 Mac 클라우드는 사용자 정의 데몬을 제한할 수 있습니다. 베어 메탈은 격리를 주지만 데몬화는 직접 구성해야 합니다. 리뷰에서 “왜 남는 노트북으로 안 하느냐”는 질문이 나올 때 아래 표를 근거로 제시하십시오.

본격에 가까운 부하에서 OpenClaw Gateway를 둘 위치 비교
차원 개인용 Mac 노트북 CALMVPS 베어 메탈 노드 시간 공유 또는 가상화 Mac 클라우드
프로세스 경계 GUI 절전과 뚜껑 닫힘 리스크 단일 테넌트로 24시간 운용에 적합 하이퍼바이저와 과할당에 따름
데몬화 launchd 설정은 여전히 필요 launchd 필수, 이웃 테넌트 소음 없음 사용자 정의 LaunchDaemon을 막는 사업자도 있음
디스크와 I/O 데스크톱 작업과 용량을 공유 로그와 캐시 볼륨을 분리 가능 공유 스토리지에서 꼬리 지연이 커지기 쉬움
네트워크 안정성 가정용 uplink 요동 데이터센터 uplink가 에이전트 친화적 QoS와 이그레스 정책은 사업자마다 다름
컴플라이언스와 감사 자산 소유 관계가 흐려지기 쉬움 계약과 접근 경계가 분명 데이터 상주와 이미지 출처를 확인해야 함

목표가 iOS 또는 macOS CI 사이드카, 고객 대향 봇 Gateway, 상시 가동 에이전트 제어면이라면 지연·격리·감사를 한 번의 결정으로 맞추기에 베어 메탈이 가장 단순한 선택인 경우가 많습니다.

콜드 부팅 재현성, 네이티브 혼합 워크로드에 대한 예측 가능한 CPU 스케줄링, 패치의 단일 소유자가 필요하면 베어 메탈을 고르십시오. 대화형 기동 검증만 필요하면 노트북으로 충분합니다. 물리 보관이 제약이면서 변동을 허용할 수 있다면 시간 공유형 클라우드도 후보이나 I/O와 데몬 정책이라는 추가 변수를 반영하십시오.

03 Node.js와 OpenClaw 설치(공식 링크)

OpenClaw는 Node 생태계를 통해 배포됩니다. 상류는 최소 런타임을 때때로 올리므로, 명령을 붙여 넣기 전에 반드시 Setup을 다시 읽으십시오. 아래 순서는 골격이며 동결된 레시피가 아닙니다.

저장소나 문서 위치가 바뀌면 아래 페이지를 1차 정보로 우선하십시오.

https://docs.openclaw.ai/start/setup

https://www.npmjs.com/package/openclaw

  1. 아키텍처를 확인합니다: uname -m에서 arm64를 기대하십시오. x86_64이면 Rosetta 하에서의 잘못된 설치가 없는지 확인합니다.
  2. Node를 설치합니다: nvm, fnm, 공식 pkg 모두 가능합니다. 문서화된 최소 메이저에 맞추고 node와 npm은 같은 접두사에서 오게 하십시오.
  3. 전역 CLI: npm install -g openclaw@latest 후 which openclaw와 openclaw --version으로 검증합니다.
  4. 작업 공간 초기화: 전용 디렉터리에서 openclaw init 또는 문서화된 온보딩을 실행하고 다운로드 폴더 루트는 피하십시오.
  5. 비밀 주입: 공급자 키와 채널 토큰 배치는 문서를 따르고 평문을 git에 남기지 마십시오.
  6. 포그라운드 증명: openclaw gateway start 또는 동등 명령으로 트래픽이 흐를 때까지 대화형으로 실행한 뒤 launchd로 옮깁니다.
VERIFY_NODE.SH 
#!/bin/sh
node -v
npm -v
which openclaw
openclaw --version

셸이 openclaw를 찾지 못하면 비대화형 launchd 세션에서도 PATH에 전역 bin이 잡히는지, sudo 혼용으로 root와 사용자 접두사가 갈라졌는지를 의심하십시오.

설치 후 지원 티켓용으로 해석된 의존 트리 스냅샷을 남기십시오. npm ls -g --depth=0 출력과 OpenClaw 버전 문자열을 함께 보관하면 업그레이드 차이를 추적하기 쉽습니다.

04 Gateway 최초 기동과 launchd 기반 상주

대화형 SSH 세션에 본격 환경을 의존하지 마십시오. 세션이 끝나면 프로세스 트리도 함께 죽습니다. macOS에서는 launchd가 지속 감독자입니다. LaunchAgents는 로그인 맥락, LaunchDaemons는 root에서 더 엄격한 감사가 필요합니다. 아래는 사용자 에이전트 전제 절차입니다.

  1. 리스너 포트를 고릅니다: 설정에 박기 전에 lsof -nP -iTCP로 비었는지 확인하십시오.
  2. plist를 작성합니다: 고유한 Label. ProgramArguments는 which openclaw의 절대 경로. 기업 MITM이 있으면 PATH와 선택적 NODE_EXTRA_CA_CERTS를 EnvironmentVariables에 넣으십시오.
  3. 표준 출력과 표준 오류: StandardOutPath와 StandardErrorPath를 회전 가능한 파일로 지정하십시오.
  4. 로드합니다: launchctl load -w ~/Library/LaunchAgents/ai.openclaw.gateway.plist입니다.
  5. 안전하게 리로드합니다: 수정 후 unload 다음 load로 같은 포트에 옛 리스너가 남지 않게 하십시오.
  6. 헬스 체크합니다: 실제 트래픽을 붙이기 전에 curl 또는 문서의 프로브로 확인하십시오.
PLIST.SNIPPET.XML 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>ai.openclaw.gateway</string>
  <key>ProgramArguments</key><array>
    <string>/opt/homebrew/bin/openclaw</string>
    <string>gateway</string><string>start</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict></plist>

plist 안의 openclaw 경로는 대상 머신과 일치해야 합니다. Apple Silicon Homebrew와 nvm shim은 위치가 달라지며 launchd가 자동 보정하지 않습니다.

정상 시의 launchctl print 출력을 문서화하여, 당직이 인시던트 중 레이블·최종 종료 상태·스로틀 지표를 비교할 수 있게 하십시오.

05 로그·헬스 체크·분류 표

분류는 세 통에 나눕니다. 프로세스 없음, 프로세스는 있으나 리스너 없음, 리스너는 있으나 상류가 거부. 통마다 대응이 다릅니다.

흔한 Gateway 장애와 처음 모을 증거
증상 첫 증거 유력한 근본 원인
재부팅 후 자동 기동 없음 launchctl list | grep openclaw plist 미로드, 경로 오류, 권한
연결 거부 lsof -nP -iTCP:PORT -sTCP:LISTEN 루프백 전용 바인드 또는 포트 충돌
TLS 핸드셰이크 실패 Gateway stderr와 기업 CA 묶음 체인 불완전 또는 시각 편차
CPU 스파이크 sample 또는 Activity Monitor GC 또는 모델 웜업, 동시성 조정
  • Node 메이저 게이트: Setup 페이지를 따르십시오. 하한 미만에서는 친절한 오류 없이 종료될 수 있습니다.
  • 바인드 주소: 루프백 전용은 원격 프로브에는 다운되어 보입니다. 보안 그룹과 맞추십시오.
  • 로그 싱크: launchd 아래에서 표준 출력을 파일로 보내지 않으면 블랙박스로 돌아갑니다. 항상 경로를 설정하십시오.

장애가 반복되면 TCP 오픈뿐 아니라 실사용자와 같은 TLS 경로와 토큰 권한을 밟는 가벼운 합성 점검을 추가하십시오. 네트워크 팀에 대한 무죄 입증 시간을 줄일 수 있습니다.

06 본격 전환 여섯 단계 체크리스트와 정상 운영

  1. 버전을 고정해 기록합니다: 변경 기록에 node, openclaw, 채널 SDK를 남깁니다.
  2. 콜드 부트 훈련을 합니다: 깨끗한 세션에서 재부팅하고 launchd가 SLA 안에 리스너를 올리는지 확인합니다.
  3. 비밀 로테이션을 연습합니다: 모델 키와 채널 토큰을 plist 수작업 없이 교체할 수 있게 합니다.
  4. 백업과 롤백: 설정 트리와 인증서를 포함하고, 마지막으로 정상이던 plist를 보관합니다.
  5. 용량 샘플링: 이루 동안 CPU·메모리·디스크 쓰기 증폭을 보고 통합 메모리 층을 판단합니다.
  6. 문서 정렬: 유지보수 창마다 Setup과 릴리스 노트를 다시 읽습니다.

자작 노트북과 시간 공유 환경은 절전, 이웃 경합, 데몬 소유 모호성에서 자주 무너집니다. 안정적인 iOS 또는 macOS 빌드 사이드카, AI 에이전트 Gateway, 감사 가능한 접근 경로가 필요한 팀은 장수명 프로세스·디스크 배치·uplink 행동을 하나의 예측 가능한 봉투에 넣을 수 있는 CALMVPS Apple Silicon 베어 메탈 임대로 수렴하는 경우가 많으며, 월 단위 탄력은 요금 페이지에서 확인할 수 있습니다.