전제 조건 (Node 24 / 게이트웨이)
OpenClaw·TLS·러너를 같은 UNIX 사용자로 통일하면 launchd·CI가 PATH·시크릿을 공유합니다.
- Node 24 LTS 고정, 비로그인 쉘에서
node -v확인. - 모든 업스트림 HTTPS 출구·동일
HTTPS_PROXY. chmod 600env·로그 경로 단일화. 원격 Mac 전용 노드면 풀·게이트웨이를 한 평면에서 운영하기 쉽습니다.
설치 및 핵심 요점
채널 하나로 설치하고 openclaw onboard로 디렉터리·포트를 선확보하세요.
- 업스트림 등록 전 doctor로 PATH·권한 정리.
- 프록시는
Host·X-Forwarded-Proto전달, 문서된 방식으로 리로드. - CI 옆에 바인드·공개 URL·로그 경로를 적은 게이트웨이 프로필을 둡니다.
다중 호환 엔드포인트·라우팅 설정 단계표
인증·모델 ID가 업스트림마다 다릅니다. 표를 런북에 복사해 env 키와 매핑하세요.
| 단계 | 작업 | 기록·완료 기준 |
|---|---|---|
| 1 | 업스트림 베이스 URL·담당·한도 표준화. | curl로 8초 내 핸드셰이크 확인. |
| 2 | 논리 별칭(fast 등)→실제 모델 ID, Git에 커밋(비밀 제외). |
동일 별칭 블라인드 해석 일치. |
| 3 | Bearer·커스텀 헤더·mTLS 등 인증 등록. | 리로드 후 업스트림별 테스트 호출 로그. |
| 4 | 접두·태그·잡 라벨 순서 라우팅·폴백. | 오라우팅 시 한 홉 내 폴백. |
| 5 | 429·5xx 서킷 브레이커·쿨다운. | 503 시 보조 업스트림 자동 전환. |
| 6 | 신규 벤더 승인·티켓 템플릿. | 커밋에 티켓 ID. |
거대 한 줄 JSON보다 순서 규칙이 유지보수에 유리합니다.
/health 점검
얕은 /health로 과금 호출 없이 상태만 보고, 깊은 검사는 긴 주기로 분리합니다.
launchd 주기 프로브·연속 실패 알림은 헬스 가이드를 따르세요.
CI Webhook·로그 요약 연동 예시
설정·모델 핀 변경 잡 끝에 요약을 남겨 레인 가시성을 확보합니다.
A) GitHub GITHUB_STEP_SUMMARY에 프로필·헬스 일부·로그 tail을 마크다운으로 추가(비밀·키 제외, 별칭만).
B) Webhook: CI 완료 JSON을 게이트웨이로 POST해 Slack 등에 전달—채널 FAQ처럼 서명 검증 필수.
원격 Mac: 풀·캐시·게이트웨이를 한 노드에 두면 회선·디스크가 안정되어 R&D 풀과 AI 트래픽이 함께 굴러갑니다.
흔한 오류 FAQ
401 Postman만 통과: 헤더 이중 접두·launchd env·사용자 불일치 → 최소 스크립트로 env 비교.
라우팅 미반영: lsof -i :PORT로 고아 리스너 제거 후 리로드·doctor.
헬스 OK·채팅 타임아웃: 얕은 헬스 의심, 소형 완료 호출·TLS·HTTP/2 점검.
요약 깨짐: 비UTF-8 tail 금지, JSON 필드만·키 붙여넣기 금지.
Node 24·doctor·버전 라우팅·헬스·CI 요약이 맞물리면 게이트웨이가 안정되고 R&D 풀이 빨라집니다. 블로그 목록에서 연관 글을 이어 보세요.