대상: 원격 Mac CI에서 LaunchDarkly 변경과 의존성 게이트를 같이 돌리려는 플랫폼 엔지니어.
요약: OpenClaw v2026.5.x·Node 24로
npm i -g openclaw·openclaw onboard --install-daemon 후 openclaw gateway status·openclaw doctor 출력을 한 블록으로 묶어 PR 코멘트에 실습니다.
더보기: status 게이트,
onboard 병합,
토큰.
플래그만 바뀌었는데 의존 그래프가 조용히 깨질 때
- 로그 분리: 웹훅과 게이트웨이 헬스 포트가 달라 요약이 갈립니다.
- 토큰 과잉: 쓰기 권한까지 넣으면 감사가 어렵습니다.
- 지연: 업스트림이 길면 코멘트 게시가 사공팔로 끊깁니다.
게이트웨이 노출 방식 짧은 매트릭스
| 방식 | 장점 | 주의 |
|---|---|---|
| 루프백 이칠팔칠팔구 | 설정 단순·Bearer 검증 반복이 쉬움 | 동일 사용자 환경과 launchd 경로 고정 필요 |
| SSH 로컬 포워드 | 에이전트 없이 외부 오케스트레이터만 노출 | 재연결 시 지터·세션 타임아웃 모니터링 |
| 역방향 프록시 단일 호스트명 | 감사 로그 한 채널 | TLS 종료 지점과 헤더 보존 일치 |
환경 준비 및 버전 고정
OPENCLAW_HOME 을 잡별로 나누고 npm install -g openclaw@^2026.5.0 후 openclaw onboard --install-daemon 을 비대화형으로 실행합니다. 곧바로 openclaw doctor 로 경고를 비우고 로그 파일을 남깁니다.
전역 경로 정렬
which openclaw 와 launchd plist 안의 절대 경로가 동일한지 비교합니다.
데몬 상태 확인
openclaw gateway status JSON 에 포트와 업타임 필드를 jq 로 추출합니다.
게이트웨이 루프백과 SSH 터널 노출 중 하나 선택
내부면 루프백·Bearer 만으로 충분합니다. 외부 수신기가 필요하면 ssh -L 18789:127.0.0.1:18789 단일 점프만 열고 프로브 URL 과 동일 호스트명을 맞춥니다.
export OPENCLAW_GATEWAY_TOKEN="$(vault kv get -field=gw token/openclaw)"
curl -sS -H "Authorization: Bearer ${OPENCLAW_GATEWAY_TOKEN}" \
http://127.0.0.1:18789/health | jq .
웹훅 라우팅과 변경 서명 검증
시크릿으로 페이로드 원문 HMAC 을 헤더와 비교합니다. REST 토큰은 읽기·감사 최소 스코프로 일주일 안 회전합니다. 검증 실패 시 의존 스텝은 건너뜁니다.
- 시크릿은 저장소가 아니라 런타임 금고와 연동합니다.
- 플래그 키 화이트리스트 밖 이벤트는 무시합니다.
헬스 프로브 출력을 단일 풀 리퀘스트 요약으로 병합
openclaw gateway status 와 openclaw doctor 앞부분을 한 블록으로 묶고 프리플라이트는 성공 시에만 돌립니다.
STATUS_JSON="$(openclaw gateway status --json)"
DOCTOR_TOP="$(openclaw doctor 2>&1 | head -n 40)"
printf '%s\n' "${STATUS_JSON}" "${DOCTOR_TOP}" > openclaw-merge.txt
백오프는 이초·사초·팔초 간격 최대 세 번과 로그를 함께 둡니다.
자주 묻는 질문 이사공과 사공팔
| 증상 | 가능 원인 | 조치 |
|---|---|---|
| 프로브 이사공 | Bearer 불일치 또는 비루프백 거부 | 토큰 회전과 바인딩 주소를 게이트웨이 설정과 동일하게 |
| 게시 단계 사공팔 | 업스트림 지연·페이로드 과대 | 백오프 세 번 후 축약 요약만 전송 |
| 서명 불일치 | 원문과 검증 문자열 불일치 | 바디 파싱 전 원시 버퍼로 HMAC |
인용 가능 숫자와 정책
- 노드 이십사와 오픈클로 이점오점오점x 를 이미지 태그에 고정합니다.
- 백오프 세 번은 코멘트 API 한도와 맞물릴 때 안전합니다.
- 플래그당 읽기 토큰 한 세트로 감사가 단순합니다.