127.0.0.1 밖으로 열어 CI·프록시·웹훅을 붙이려는 팀. HowTo: Node 22+, 설치기 또는 npm -g, OPENCLAW_GATEWAY_TOKEN SecretRef형 주입, doctor·validate·Bearer curl. 문서는 docs.openclaw.ai CLI·게이트웨이·보안 장과 대조. 연관 config validate CI 게이트, 게이트웨이 보안, 비대화형 onboard.
루프백만 쓸 때 숨는 운영 리스크
- PATH 분열: 셸
nvm과launchd최소PATH가 달라 데몬만 토큰 없이 보입니다. - 무방비 리슨: 비루프백에선 빈 베어러를 업스트림이 즉시 거절하는 경우가 많습니다.
- 프록시 동조: 같은 맥의 npm·PyPI 미러와 게이트웨이 장애가 겹치면 원인 분리가 어렵습니다.
리슨 범위와 인증 깊이 짧은 매트릭스
| 리슨 패턴 | 전형적 용도 | 토큰·네트워크 메모 |
|---|---|---|
127.0.0.1 |
doctor·역프록시 업스트림 | 문서 요구 시 OPENCLAW_GATEWAY_TOKEN 유지. |
| VPN NIC | 폐쇄망 CI 호출 | 방화벽·토큰 회전을 멤버십과 함께 기록. |
| LAN IP | 웹훅 | 레이트리밋·감사·공식 보안 절 반영. |
최소 재현 단계
1단계 Node 22.14 또는 24 고정, 잡마다 node -v 로그 선두.
2단계 공식 설치 스크립트 또는 npm install -g "openclaw@^…", command -v openclaw·openclaw --version. Brew 상호작용은 비대화형 onboard.
node -v npm install -g "openclaw@^2026.3.0" command -v openclaw openclaw --version
3단계 잡별 OPENCLAW_HOME·OPENCLAW_CONFIG_HOME, 디렉터리 700.
4단계 GitHub env:·Azure·SecretRef 패턴으로 OPENCLAW_GATEWAY_TOKEN만 주입, echo 금지.
5단계 공식 리슨·TLS 장에 따라 비루프백; 선호는 역프록시→루프백. 토큰 변경 후 plist unload·load 또는 잡 재시작.
6단계 openclaw doctor 후 openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json". 로그 병합은 config validate CI 게이트와 동일.
export OPENCLAW_GATEWAY_TOKEN="$(cat "$RUNNER_TEMP/gw.token")"
openclaw doctor
openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json"
curl -fsS -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
"http://127.0.0.1:18789/v1/health"
무인증 기동 거절 로그 흔한 대조
비루프백+빈 토큰은 가드레일에 자주 걸립니다. 문자열은 릴리스 노트와 docs.openclaw.ai 보안 절과 대조하세요.
| 증상·로그 단서 | 가능 원인 | 문서 정렬 첫 조치 |
|---|---|---|
| 비루프백 직후 즉시 종료 | 토큰 env 비어 있음 | 시크릿 주입·plist·잡 재로드. |
| 헬스 HTTP 401 | Authorization 누락·오타·개행 | 문서 Bearer 스킴 정합·토큰 재발급. |
| 셸 doctor OK·launchd만 실패 | plist에 변수 없음 | EnvironmentVariables diff 후 unload·load. |
하드닝 패턴은 게이트웨이 보안 강화 글을 함께 보세요.
프리플라이트 체크리스트
- Node 22.14+ 또는 24 로그
openclaw절대 경로가 launchd=CI- 토큰 env 존재·비노출
- 방화벽 서브넷 문서화
- doctor+validate 한 파일 녹색
- Bearer 시에만 헬스 200
같은 원격 Mac에서 CI·프록시 풀과 묶는 가치
한 대의 Apple Silicon에 게이트웨이와 npm·PyPI·레지스트리 프리풀을 두면 RTT가 줄고 웹훅이 워밍 캐시를 탑니다. Bearer 헬스로 설정 오류를 의존성 플릿 전에 막습니다.
토큰 없는 헬스 요청을 머지 게이트에서 의도적으로 실패로 두면 회귀 비용이 줄어듭니다. 마이너를 올릴 때마다 릴리스 노트의 보안 문구를 docs.openclaw.ai 보안 장과 diff 하세요.