웹훅 방송은 실패 주체를 알려 줄 뿐, 어떤 빌드·스킬 슬라이스가 프로덕션을 가져야 하는지는 알려 주지 않습니다. 비율 카나리, semver 스킬 디렉터리, Doctor·큐·다이제스트를 한 번에 보는 병합 프로브가 최소 재현 규율입니다.

이 HowTo는 멀티 AZ 게이트웨이: 프로브·웹훅·토큰과 겹치지 않습니다. 그쪽은 다이제스트·토큰이 제어 평면이고, 여기서는 트래픽 비율·스킬 슬라이스·승격 게이트입니다. clustervps Mac 세 대로 연습 가능합니다.

OpenClaw 다중 노드 배포 흐름(비율을 움직이기 전)

배포는 게이트웨이 간 계약입니다. 모든 Mac이 openclaw.lock, 테넌트 조각·Doctor·다이제스트 조각 집합, lockfile에 맞는 스킬 디렉터리, 아래 복합 ready 경로에 합의해야 합니다. 순서: 카나리 섀도 → Doctor+병합 프로브 녹색 → LB 가중치 → 피어 미러 → 감사. 섀도 생략은 healthy 속 스킬 분열로 이어집니다.

  • 권위 있는 소스: 승격마다 Git 태그; 작업 트리가 더러우면 launchd 리로드를 거부합니다.
  • 병렬 게이트웨이: writer Mac이 태그를 적용하고, 카나리 게이트웨이가 먼저 pull, 안정 게이트웨이는 비율 게이트 통과 후에만 pull합니다.
  • 워커·노티파이어: 게이트웨이보다 한 리비전 늦춰도 되지만 앞서면 안 됩니다. 그렇지 않으면 병합 프로브가 스킬 호환을 거짓으로 보고합니다.
#!/usr/bin/env bash
set -euo pipefail
cd /usr/local/share/openclaw-infra
/usr/bin/git fetch --tags origin
/usr/bin/git checkout "refs/tags/${PROMOTE_TAG}"
/usr/bin/shasum -a 256 openclaw.lock | /usr/bin/tee /tmp/lock.sha
/usr/local/bin/openclaw version --json | /usr/bin/tee /tmp/version.json
/usr/bin/diff -q openclaw.lock <(ssh canary-gw "cat /usr/local/share/openclaw-infra/openclaw.lock")

diff가 비어 있을 때만 로드밸런서 가중치를 만질 수 있습니다. 비어 있지 않으면 중단하세요. AZ 간 스플릿 브레인으로 들어가기 직전입니다.

트래픽 비율: clustervps 멀티 AZ 게이트웨이 카나리 게이트

카나리는 이산 비율입니다. next 섀도를 둔 게이트웨이로 신규 세션 약 5%부터 보내고, 복합 프로브 두 간격(대개 10분) 이상 유지하며 p95·큐·오류 예산을 웹훅과 분리해 봅니다. 병합 JSON에서 Doctor 녹색·다이제스트 허용일 때만 10~20%p씩 올립니다.

단계마다 한 행: 시각, 가중치, semver, 티켓. 롤백 나침반입니다.

벤더별 가중치 API·CLI를 셸 함수로 박제해 두면 장애 대응이 빨라집니다.

설정 조각 분할 테넌트(스킬 슬라이스 경계)

include 순서가 어긋나면 슬라이스는 깨집니다. next 전에 모든 게이트웨이에 /etc/openclaw/tenants/<tenant>/skills.d/를 맞추세요. 조각에는 도구 네임스페이스·모델·쿼터만, 시크릿은 /var/db/openclaw/secrets/<tenant> ACL로 분리합니다.

# git 태그 checkout 후 각 게이트웨이에서
sudo install -d -o root -g wheel /etc/openclaw/tenants/acme/skills.d
sudo /usr/local/bin/openclaw config lint --tenant acme
sudo /bin/ln -sfn "/var/db/openclaw/skills/1.4.2" /var/db/openclaw/skills/next
sudo launchctl kickstart -k system/com.openclaw.gateway

카나리 테넌트는 skills.d/10-canary.yaml로 next를 가리키게 할 수 있고, 프로덕션 테넌트는 감사 승인까지 current에 고정합니다. 클러스터 전체를 포크하지 않는 최소 per-tenant 슬라이스입니다.

헬스 프로브 병합: Doctor·큐·다이제스트·스킬 semver

한 URL이어도 응답은 디스크 semver = lock, 트래픽 테넌트의 Doctor, 큐 SLO를 함께 말해야 합니다. 다이제스트는 병합 JSON의 필드이지 승격 트리거가 아닙니다. 웹훅 중심 글과 각도가 갈립니다.

#!/usr/bin/env bash
set -euo pipefail
TENANT_CANARY="${TENANT_CANARY:-acme}"
SKILL_PATH="/var/db/openclaw/skills/current"
/usr/bin/readlink "${SKILL_PATH}" | /usr/bin/tee /tmp/skill_path.txt
/usr/local/bin/openclaw doctor --tenant "${TENANT_CANARY}" --json >/tmp/doctor.json
/usr/bin/curl -fsS --max-time 3 "http://127.0.0.1:9099/v1/webhook-digest" -o /tmp/digest.json
/usr/bin/python3 - <<'PY'
import hashlib, json, pathlib
blob = pathlib.Path("/tmp/doctor.json").read_bytes() + pathlib.Path("/tmp/digest.json").read_bytes()
print(json.dumps({"probe_sha256": hashlib.sha256(blob).hexdigest(),"skill_resolved": pathlib.Path("/tmp/skill_path.txt").read_text().strip()}))
PY

Doctor가 노란색이지만 semver와 다이제스트가 허용 가능하면 status: degraded를 내어 트래픽은 흐르게 하고 대시보드만 크게 울립니다. semver가 lockfile과 어긋나면 하드 실패입니다. 웹훅이 아무리 깨끗해도 그 빌드를 승격하면 안 됩니다.

롤백: 트래픽·심볼릭·launchd를 한 호흡에

롤백은 LB 스냅샷 복구와 current 심볼릭을 이전 semver로 되돌리기, 둘 다입니다. 하나만 하면 트래픽·스킬 조합이 꼬입니다. launchd kick 후 병합 프로브가 감사에 남긴 good 스냅샷과 일치하는지 확인합니다.

#!/usr/bin/env bash
set -euo pipefail
/usr/bin/scp stable-gw:/var/db/openclaw/audit/last_good_weights.json /tmp/weights.json
./lb_restore_weights.sh /tmp/weights.json
sudo /bin/ln -sfn "/var/db/openclaw/skills/${ROLLBACK_SEMVER}" /var/db/openclaw/skills/current
sudo launchctl kickstart -k system/com.openclaw.gateway
/usr/bin/curl -fsS http://127.0.0.1:8088/readyz | /usr/bin jq .

롤백 훈련은 크로스 리전 아티팩트·rsync 매트릭스 글의 아티팩트 위생과 짝을 이루세요. 로드밸런서가 잘못된 AZ를 가리키는 동안 rsync와 레이스하지 않도록 합니다.

감사: 보안팀이 grep 할 수 있는 append-only JSONL

비율마다 promotions.jsonl에 한 줄: actor, ticket, from/to semver, 가중치 맵, probe_sha256. 야간에 오브젝트 스토리지로 복제합니다.

/usr/bin/printf '%s\n' \
  "{"ts":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","actor":"${USER}","ticket":"${TICKET}","from":"1.4.1","to":"1.4.2","weights":"${WEIGHT_BLOB}","probe_sha256":"${PROBE_SHA}"}" \
  | /usr/bin/tee -a /var/db/openclaw/audit/promotions.jsonl

감사인이 무엇이 바뀌었냐고 물으면 Slack 스크롤이 아니라 jq 필터로 답합니다.

FAQ: 카나리 대 웹훅 우선 운영

다이제스트는? 병합 프로브에 넣되, 트래픽 확대의 유일한 근거로 쓰지 마세요. semver·Doctor가 먼저입니다.

한 테넌트만? 카나리 게이트웨이에 조각을 두고 LB 스티키로 그 코호트만 카나리 풀에 고정합니다.

최소 노드? 안정 AZ 두 대 + 비율 받는 카나리 한 대, clustervps 세 대가 최소 리허설입니다.

운영 가이드일 뿐입니다. OpenClaw 배포 세부는 릴리스마다 다릅니다. 설치된 빌드에 맞춰 플래그를 검증하세요. 로드밸런서 API는 벤더마다 다릅니다. 셸 조각은 패턴으로 보고 그대로 비밀에 넣지 마세요.
병렬 클러스터 전환

영웅 담당자가 아니라 AZ마다 게이트웨이를 맞추기

AZ마다 Mac이 있으면 섀도·병합 프로브 여유가 생깁니다. 요금제를 보고 리전에 병렬 노드를 더한 뒤 실기에 비율을 겁니다. 구매·도움말을 런북과 함께 두세요.

병렬 게이트웨이 Mac 추가 요금제 보기