openclaw doctor·대시보드 토큰·루프백 바인딩을 먼저 고정합니다. 채팅 알림이 필요하면 Discord·CI 요약 글, 터널·하드닝은 게이트웨이 보안 가이드, 상시 헬스는 LaunchAgent 헬스와 함께 보세요.
- 관리면 노출: 게이트웨이를 0.0.0.0에 두지 말고 127.0.0.1과 터널로만 받습니다.
- 토큰 과다: 조직 전체가 아니라 해당 저장소·Checks 쓰기·콘텐츠 읽기 등 최소 집합만 씁니다.
- 작업 디렉터리 혼선: 병렬 웹훅이 같은 클론을 건드리면 lockfile diff가 틀어집니다. 이벤트마다 격리 디렉터리를 씁니다.
설치·openclaw doctor·문서 정렬
팀이 고른 Node LTS로 맞춘 뒤 openclaw onboard로 설정 디렉터리를 만듭니다. 비로그인 셸·self-hosted 러너·launchd가 같은 바이너리를 보게 PATH를 통일하고 openclaw doctor로 인증서·프록시·업스트림 연결을 확인합니다. 공식 문서 docs.openclaw.ai의 게이트웨이 항목과 버전을 주기적으로 맞추면 재현이 깨지지 않습니다.
| 점검 항목 | 권장 | 피할 것 |
|---|---|---|
| 바인드 주소 | 127.0.0.1 + 승인된 터널 | 불필요한 공개 포트 |
| 비밀 저장 | chmod 600·시크릿 스토어 |
저장소 로그에 토큰 노출 |
| 이벤트 | check_suite 또는 PR paths 필터 |
모든 push에 무차별 실행 |
게이트웨이·대시보드 토큰·루프백만 바인딩
게이트웨이 프로세스는 로컬 루프백에만 붙이고 대시보드에서 발급한 토큰을 환경 변수나 plist로 주입합니다. GitHub가 밖에서 치게 하려면 ssh -L 또는 조직이 승인한 리버스 프록시 한 경로로만 연결합니다. 관리 API와 웹훅 수신 경로를 분리하면 토큰 유출 시 영향 범위를 줄일 수 있습니다.
- 수신 핸들러 앞단에서 Bearer 또는 게이트웨이 자체 검증 규칙을 통과시킵니다.
- 헬스 프로브는 내부 루프백만 두고 외부 모니터링은 터널 안쪽에서 수행합니다.
Webhook 등록·이벤트 필터·서명 검증
저장소 설정에서 Webhook을 만들고 콘텐츠 타입은 JSON으로 둡니다. 이벤트는 check_suite 또는 pull_request 중 필요한 것만 켜고 핸들러 안에서 action·head_sha·변경 파일 목록으로 lockfile 경로가 있을 때만 이어갑니다. 페이로드는 X-Hub-Signature-256으로 검증해 위조를 막습니다.
| 트리거 | 필터 요지 |
|---|---|
| check_suite | 완료 상태·중복 head_sha 제거 |
| pull_request | paths에 lock 파일 패턴만 |
최소 권한 토큰·작업 디렉터리 격리
fine-grained PAT 또는 GitHub App으로 저장소 단위 권한을 주고 메타데이터 읽기·콘텐츠 읽기·Checks 쓰기처럼 필요한 최소 집합만 남깁니다. 클론은 이벤트마다 새 디렉터리나 git worktree로 받아 이전 빌드의 node_modules 등이 섞이지 않게 합니다. 토큰 파일은 러너 계정만 읽게 두고 감사 로그에 본문이 남지 않게 마스킹합니다.
lockfile 스캔·Checks API로 요약 회신
package-lock.json·yarn.lock·pnpm-lock.yaml·Cargo.lock 등 팀이 정한 목록을 git diff나 검증 스크립트로 돌린 뒤 결과를 Check Run 본문·요약 필드에 넣습니다. 실패가 애매하면 중립 상태로 두고 로그 경로를 남깁니다. 재시도는 지수 백오프로 제한해 API 한도를 넘기지 않습니다.
흔한 오류 FAQ
전달 401·404: 프록시가 경로를 잘랐는지·시크릿이 GitHub 설정과 같은지·루프백 포트가 터널 끝과 연결됐는지 확인합니다.
Checks 403: 토큰에 Checks 쓰기가 없거나 앱이 저장소에 설치되지 않았을 수 있습니다. 조직 정책도 점검합니다.
이벤트 폭주: head_sha 단위 중복 제거와 paths 필터로 줄입니다.
doctor TLS: 기업 루트를 NODE_EXTRA_CA_CERTS에 넣고 curl -v https://api.github.com로 확인합니다.
diff와 빌드 불일치: 잘못된 SHA를 체크아웃했거나 격리 디렉터리가 오염됐을 때가 많습니다.