openclaw onboard --install-daemon, openclaw doctor, 게이트웨이 기본 WebSocket 18789·루프백·토큰을 먼저 고정하세요. 연관 글: 헬스·LaunchAgent, Jenkins Webhook 최소 재현, Bundler 프리체크 플레이북.
왜 여기서 막히나: VPC·웹훅 방향·요약 전송
- 소스 웹훅은 Git→AWS이고, Mac으로 오는 건 별도 아웃바운드(buildspec·EventBridge)입니다. 둘을 섞으면 “웹훅이 안 온다”로 오해합니다.
- VPC CodeBuild는 NAT·엔드포인트 없으면 퍼블릭 OpenClaw URL로
curl이 막힙니다. - CodeBuild와 게이트웨이가 서로 다른 Node·미러·토큰을 보면 프리체크만 실패하고 훅은 200인 경우가 많습니다.
비교: buildspec curl vs EventBridge API 대상
| 방식 | 장점 | 주의 |
|---|---|---|
| buildspec post_build curl | IAM·리소스 최소, 재현 쉬움 | YAML·따옴표 실수 시 빌드 실패 |
| EventBridge + API Destination | 빌드스펙 변경 없이 중앙 라우팅 | 규칙·DLQ·api destinations:Invoke 관리 |
| Bearer 공유 시크릿 | 구현 단순·검증 빠름 | 시크릿 회전·SSM 주입 필수 |
| 요약 POST | Slack·대시보드와 직결 | 2·4·8초 백오프·멱등 키 |
설치·게이트웨이·토큰·헬스
Node.js 22 이상(운영 편의상 22.16+ 또는 24 LTS)을 launchd와 대화형 셸에서 동일하게 맞춘 뒤 openclaw doctor로 경고를 없앱니다. 공식 문서에 따라 로컬 게이트웨이는 openclaw onboard --install-daemon으로 사용자 서비스에 올리면, 온보딩이 먼저 관리형 게이트웨이 설치 경로를 밟고 헬스 대기까지 포함합니다(자동화만 필요하면 --skip-health 참고). 게이트웨이 WebSocket 기본 포트는 문서상 18789이며, 외부 Git 웹훅과 혼동하지 말고 HTTP 훅은 리버스 프록시 뒤 별도 경로로 노출합니다. curl -fsS http://127.0.0.1:<HTTP 바인딩>/health를 LaunchAgent로 주기 호출해 프로세스 생존과 TLS 업스트림을 분리 진단하세요. OPENCLAW_GATEWAY_TOKEN 등은 chmod 600 파일·SecretRef만 사용합니다.
- IAM: buildspec만 쓸 때는 훅 시크릿용 SSM GetParameters(또는 Secrets Manager) 정도로 축소. EventBridge 경로는 api destinations:InvokeConnection·대상 DLQ 확인.
- 로그 필드:
CODEBUILD_BUILD_ID·CODEBUILD_PROJECT_NAME·CODEBUILD_RESOLVED_SOURCE_VERSION·CODEBUILD_BUILD_SUCCEEDING·상관 ID를 한 줄 JSON으로 남김. - 재시도: 아웃바운드
curl은 2·4·8초 슬립·최대 3회,connect-timeout·max-time고정. - 쉘과 launchd의
which node동일, 프록시 본문 재작성 끔, WORK_ROOT 디스크·동시 클론 한도.
수신 즉시 2xx를 돌리고 클론·프리체크는 워커로 넘기면 CodeBuild 쪽 타임아웃과 분리됩니다. 장애 알림은 빌드 실패와 훅 전달 실패 채널을 나누면 노이즈가 줄어듭니다.
CodeBuild: 소스 웹훅과 Mac 훅 전달·검증
콘솔에서 소스 제공자 웹훅을 켜 브랜치·경로 필터를 설정합니다(이 단계는 Git→AWS). Mac의 OpenClaw로 상태를 넘기려면 아래처럼 post_build에서 최소 JSON을 보냅니다. 시크릿은 Parameter Store 환경 변수로 주입하고 CloudWatch 로그에 값이 찍히지 않게 마스킹합니다.
OpenClaw 측에서는 Authorization 또는 커스텀 헤더를 상수 시간 비교하고, 본문은 CodeBuild가 생성한 JSON 그대로 파싱합니다. 조직 표준으로는 동일 페이로드를 EventBridge aws.codebuild 규칙과 API 대상으로 전달해도 됩니다.
OpenClaw 수신 후 composer·npm 프리체크 명령 템플릿
빌드 ID별 WORK_ROOT에서 CODEBUILD_RESOLVED_SOURCE_VERSION으로 얕은 클론 후 실행합니다. 종료 코드·stderr 꼬리를 요약 JSON에 포함하세요.
모노레포는 하위 경로에서 반복. PHP·Node 버전 파일로 고정.
빌드 요약 회송 HTTP·Webhook과 실패 재시도
JSON에 buildId·project·commit·preflight_ok·log_tail 등을 넣어 Slack·사내 대시보드로 POST합니다. 502·504·연결 거부면 이·사·팔 초 슬립 후 최대 세 번. buildId를 멱등 키로 삼아 중복 알림을 걸러내세요. 수신측 Retry-After가 있으면 우선 적용합니다.
흔한 오류 FAQ
Mac에 이벤트가 한 건도 안 옵니다
VPC CodeBuild면 NAT/엔드포인트, 퍼블릭 서브넷·라우팅, curl DNS·프록시, 보안 그룹 아웃바운드부터 확인하세요. EventBridge를 쓰면 규칙 적중·대상 실패·DLQ를 봅니다.
401·403만 반복됩니다
SSM 주입 값과 OpenClaw 기대 토큰 불일치, API Gateway 리소스 정책, WAF IP 제한을 점검합니다.
빌드는 성공인데 프리체크만 실패
Mac과 CodeBuild의 Node·lockfile·레지스트리 미러가 다릅니다. 동일 SHA 클론과 토큰·캐시 경로를 맞춥니다.
composer·npm만 느림
COMPOSER_PROCESS_TIMEOUT·npm_config_fetch_timeout·미러·NO_PROXY·캐시 디스크.