원격 Mac CI에서 OpenClaw 스킬 체인과 MCP 도구를 매 잡마다 동일하게 쓰려면 Node 버전·설치 경로·게이트웨이 바인딩·토큰·데몬까지 한 번에 고정해야 합니다. 공식 문서(
docs.openclaw.ai/install/node) 기준 Node 22.16 이상이 필요하고 Node 24가 기본 권장 런타임입니다. 본문은 비교표·단계·오류 대조표·최소 워크스페이스·cron 예시로 재현 절차만 압축합니다. 스킬 허브 연동 맥락은 ClawHub·CI 사전 풀 글과 함께 보세요. 사이트 안내는 기술 블로그 목록·홈·구매에서 이어갈 수 있습니다.
원격 Mac CI에서 자주 깨지는 지점(세 가지)
1
런타임 드리프트. 에이전트·MCP가 서로 다른 Node에 올라가면 글로벌 패키지 경로와 네이티브 모듈 ABI가 어긋납니다.
node -v를 러너 시작 스크립트에 넣고 실패 시 즉시 중단하세요.
2
게이트웨이 공개 바인딩.
0.0.0.0에 토큰 없이 열면 내부 도구가 인터넷에 그대로 노출됩니다. 반드시 127.0.0.1 또는 사내 인터페이스 + 방화벽 + 무작위 긴 토큰 조합으로 잠급니다.
3
세션 vs 데몬. SSH로만 띄운 프로세스는 세션이 끊기면 MCP가 사라집니다.
launchd LaunchAgent로 사용자 단위 상시 기동을 걸고 로그 경로를 고정하세요.설치 경로 의사결정: 공식 설치 스크립트 vs npm 글로벌
팀 표준을 하나만 고르고 문서에 고정하세요. 여기서는 공식 설치 스크립트(문서의 Alternative install methods)를 기본으로 두고, npm 글로벌은 대안으로만 적습니다.
| 방식 | 적합한 경우 | 장점 | 주의 |
|---|---|---|---|
| 공식 설치 스크립트 | 처음부터 재현성·온보딩 문서를 맞출 때 | Node 감지·설치까지 한 흐름, 문서와 동작 일치 | 조직 정책상 curl 파이프 설치 금지면 내부 미러·승인 필요 |
| npm install -g | 이미 Node 24를 fnm·brew로 고정한 러너 | 버전 핀과 CI 캐시에 넣기 쉬움 | npm prefix -g가 PATH에 없으면 openclaw: command not found |
| Homebrew node | macOS 전용 상주 에이전트 | 업그레이드 경로 단순 | 메이저 업 시 파이프라인 재검증 필요 |
인용·체크(2026 공식 Node 가이드 요지)
- 최소: Node 22.16+ 지원, Node 24 권장.
- PATH: 글로벌 설치 시
export PATH="$(npm prefix -g)/bin:$PATH"를~/.zshrc에 영구 반영. - 리눅스 권한:
EACCES면 사용자 쓰기 가능한~/.npm-global프리픽스로 전환.
재현 절차(여섯 단계 체크리스트)
원격 Mac SSH 세션과 CI 러너에 동일한 순서를 복사해 두면 스킬 체인이 흔들리지 않습니다.
1
Node 고정.
node -v가 22.16 미만이면 중단. macOS는 brew install node 또는 공식 pkg, 팀 표준이면 fnm으로 24를 지정합니다.
2
OpenClaw 설치. 문서의 공식 설치 스크립트 한 가지로 올리고, 대안으로만
npm install -g openclaw(또는 조직이 승인한 패키지명)을 사용합니다. 설치 직후 which openclaw로 PATH를 확인합니다.
3
MCP 등록. 워크스페이스 루트의
openclaw.json(또는 팀 표준 파일)에 MCP 서버 커맨드·env·워킹 디렉터리를 절대경로로 박습니다. 스킬 번들 경로도 동일 파일에만 둡니다.
4
게이트웨이·토큰. 리슨을
127.0.0.1로 제한하고 OPENCLAW_GATEWAY_TOKEN 같은 환경변수에 32바이트 이상 무작위 값을 넣습니다. 0.0.0.0 공개 바인딩 + 무방비 토큰 조합은 운영 금지로 문서화하세요.
5
launchd 상시 기동.
~/Library/LaunchAgents/com.team.openclaw.mcp.plist에 ProgramArguments·WorkingDirectory·EnvironmentVariables·표준출력 로그 경로를 넣고 launchctl bootstrap gui/$UID …로 등록합니다. 재부팅 후에도 동일하게 올라오는지 확인합니다.
6
프리플라이트 게이트. CI 입구에서 MCP 헬스체크·스킬 로드 검증 스크립트를 실행하고 실패 시 잡을 즉시 중단합니다. 아래 cron 예시를 참고하세요.
흔한 오류 대조표
| 증상 | 우선 조치 |
|---|---|
openclaw: command not found |
npm prefix -g의 bin을 PATH에 추가, 새 셸에서 재시도 |
| MCP 프로세스 즉시 종료(코드 1) | Node 버전이 22.16 미만인지 확인, 네이티브 모듈 재빌드 |
| 게이트웨이 연결 거부 | 바인딩이 루프백인지, 방화벽·프록시 예외·토큰 헤더 일치 여부 확인 |
| 세션 끊김 후 MCP 사라짐 | SSH 포그라운드 대신 launchd LaunchAgent로 데몬화 |
EACCES on npm i -g |
사용자 프리픽스 ~/.npm-global로 전환 후 PATH 영구화 |
최소 재현 워크스페이스 디렉터리
저장소에 아래 골격을 그대로 두면 신규 러너가 디렉터리만 클론해도 동일하게 시작할 수 있습니다.
ci-mac-openclaw/
├── openclaw.json # MCP 서버·스킬 경로·env 참조
├── skills/ # 팀 스킬 번들(버전 핀)
├── scripts/
│ ├── preflight.sh # node -v, openclaw doctor, MCP ping
│ └── pull-and-preflight.sh
└── logs/ # launchd 표준출력·에이전트 로그
예시: 정기 pull과 프리플라이트 결합
상주 에이전트가 최신 스킬을 받아야 할 때, cron으로 짧은 주기만 허용하고 실패 시 알람을 붙이세요.
*/15 * * * * cd $HOME/ci-mac-openclaw && git pull --ff-only && ./scripts/preflight.sh || logger "openclaw preflight failed"
pull-and-preflight.sh 안에서는 set -euo pipefail로 중간 실패를 즉시 전파하고, MCP 엔드포인트에 로컬 루프백 헬스 요청을 한 번 보내는 방식이 안전합니다.
요약: 스킬 체인을 한 줄로 고정하기
Node 22.16+·단일 설치 경로·루프백 게이트웨이·강한 토큰·launchd·프리플라이트 다섯 요소가 맞으면 원격 Mac CI에서 MCP 도구 호출이 문서와 동일하게 반복됩니다.