openclaw onboard, 게이트웨이·대시보드, 검증·트러블슈팅까지 한 흐름으로 정리했습니다. 다중 엔드포인트·CI 요약, 헬스 LaunchAgent, 채널 FAQ와 함께 보세요.
- 권한 과다: 봇·관리자 토큰 대신 채널 Webhook만 씁니다.
- 환경 불일치: launchd·러너·쉘의
PATH·Node가 다르면 후킹만 실패합니다. - 무차별 POST: 매 스텝마다 내면 429가 납니다. 잡 종료 한 번이 안전합니다.
환경 전제와 최소 권한 원칙
2026년 흔한 경로는 curl install.sh 또는 npm i -g 후 openclaw onboard로 디렉터리·바인드·로그를 잡는 방식입니다. 문서가 요구하는 Node LTS(예: 22.16+, 팀 정책에선 24 고정)를 node -v로 비로그인 쉘·self-hosted 러너에서 맞춥니다. 게이트웨이·스크립트·LaunchAgent는 동일 계정, 비밀은 chmod 600·저장소 시크릿만 씁니다. Webhook URL은 로그에 전체가 남지 않게 마스킹하고 폐기 시 Discord에서 삭제합니다.
| 설치 | 장점 | 주의 |
|---|---|---|
| curl 스크립트 | 온보딩이 빠름 | 업데이트 채널·PATH를 doctor로 고정 |
| npm 전역 | 기존 Node 핀과 맞추기 쉬움 | prefix 불일치 시 절대 경로를 런북에 |
Discord Webhook 생성과 게이트웨이 측 바인딩
서버 설정에서 채널 Webhook을 만들고 URL을 DISCORD_WEBHOOK_URL로 보관합니다. 대시보드·플러그인에 필드가 있으면 거기에 넣고, 없으면 게이트웨이 호스트에서 curl로 JSON POST합니다. 바인딩 전 openclaw doctor, 아웃바운드는 discord.com 위주로 열어도 됩니다.
- 프로브 페이로드로 HTTP 204와 채널 표시를 동시에 확인합니다.
- 204가 아니면 FAQ로, 메시지가 없으면 URL·포크 PR 시크릿을 의심합니다.
CI 빌드 요약 payload 템플릿과 필드 매핑
content 또는 embeds로 잡당 한 번만 보냅니다. 길이 한도를 넘기면 잘리므로 로그는 링크·아티팩트로 빼고 요약만 넣습니다.
| CI 변수 | Discord |
|---|---|
GITHUB_REPOSITORY |
embed.title |
GITHUB_REF_NAME·짧은 SHA |
fields 브랜치·커밋 |
| run URL·결과·요약 텍스트 | embed.url·상태 필드 |
서명·레이트리밋·실패 재시도 파라미터
게이트웨이가 CI 콜백을 받으면 HMAC·타임스탬프 윈도로 위조를 막습니다. Discord 출구는 URL 보호가 핵심입니다. curl --connect-timeout 8 --max-time 35, retry-after 초만큼 대기 후 최대 3회 백오프합니다. 러너가 많으면 채널을 나눕니다.
흔한 오류 FAQ (403·429·타임아웃·수신 불가)
403: Webhook 삭제·권한 변경 → 재발급·시크릿 갱신.
429: 스텝마다 POST 금지, Retry-After 준수.
타임아웃: DNS·프록시·IPv6를 curl -v로 분리, 로컬 헬스는 LaunchAgent 가이드와 비교.
204인데 안 보임: 다른 Webhook URL·클라이언트 음소거·채널 필터를 확인합니다.