2026년에 OpenClaw를 설치 또는 Docker/Compose로 운용하는 팀은 종종 잘못된 모델 라우트, 429와 타임아웃 혼선, 페일오버 순서 불일치, npm 글로벌과 컨테이너 사이의 환경 변수 분열에서 막힙니다. 「설치가 안 된다」가 아닙니다. 본문은 《크로스플랫폼 설치》《Docker 프로덕션》《업그레이드·마이그레이션》과 범위를 나누고 런타임 멀티 모델 라우팅, 실행 가능한 페일오버, 이중 경로 표, 증상 기반 Gateway/CLI 로그 분류에 초점을 둡니다. 설치 후 증상은 《설치 후 분류》로 이어집니다.
기본·폴백 모델과 서로 다른 프로바이더 속도 제한이 Gateway 뒤에 있으면 장애가 무작위로 보입니다. HTTP 상태만 보지 말고 다음 여섯 클래스를 알림 필드에 매핑합니다.
export만 있고 컨테이너 주입이 없거나, compose 오버라이드가 의도와 반대입니다.이 통증들은 업그레이드 백업·이미지 태그와 직교합니다. 런타임 라우팅 vs 변경 통제입니다. 릴리스와 당번을 분리하려면 둘 다 읽습니다.
멀티 모델은 보통 여러 과금 계정과 컴플라이언스 경계를 뜻합니다. 세션이 모델에 명시적으로 스코프되지 않으면 과소비나 정책 위반 위험이 있습니다. 라우트 표를 Secrets 거버넌스와 함께 검토하는 비용·권한 계약으로 다룹니다.
「엔드포인트 도달」은 「체인 건강」이 아닙니다. 프록시·방화벽·DNS가 세션마다 성공을 갈라 놓을 수 있습니다. 구조화된 로그와 샘플링이 단일 전역 오류율보다 낫습니다.
설정 로드 순서, 환경 우선순위, 재시작 경계를 두 경로 모두에 문서화하지 않으면 「호스트는 바꿨는데 컨테이너는 아니다」가 납니다.
| 차원 | npm 글로벌/로컬 프로세스 | Docker/Compose |
|---|---|---|
| 설정·시크릿 | 사용자 설정 파일과 셸 환경이 우세합니다 | env_file, 마운트, 런타임 -e를 명시해야 합니다 |
| 업그레이드·롤백 | 글로벌 CLI로 npm 패키지 고정 | 이미지 태그, 볼륨, 업그레이드 가이드 순서의 docker compose pull |
| 헬스 체크 | systemd/launchd 프로브에 맞춥니다 | 컨테이너 내 curl/CLI; 네트워크 스택은 호스트와 다릅니다(루프백 정책 포함) |
| 흔한 실수 | 여러 Node 버전이 잘못된 글로벌을 고릅니다 | 핫 리로드 기대의 읽기 전용 마운트, 재빌드 후 환경 소실 |
조직 전체에서 모델을 바꿀지, 키를 바꿀지, egress를 고칠지 규칙을 정하고 같은 SLO 문서에 씁니다. 숫자가 작을수록 먼저 시도합니다.
| 증상(로그/메트릭) | 가능 원인 | 예시 순서 |
|---|---|---|
| HTTP 429 또는 명시적 속도 제한 | 쿼터 또는 동시성 | 백오프→예비 키→동시성 하향→임시 폴백 모델 |
| 타임아웃, 리셋, 느린 TLS | 네트워크 경로 또는 리전 egress | 타임아웃 상향(상한)→프록시/DNS→가까운 egress |
| 모델 없음/자격 없음 | ID 또는 계정 권한 | 프로바이더 콘솔 확인→라우트 표 수정→무관한 폴백을 조용히 쓰지 않기 |
| 부분 세션 성공 | 키 불균형 또는 스티키 라우팅 오류 | 키별 카운터·서킷 브레이커→세션 고정→Gateway 샤딩 |
# 요청당 최소 로그 필드(예): # requestId / sessionId / provider / modelId / status / latencyMs # 하나라도 빠지면 라우트를 맹목적으로 바꾸기 전에 관측성을 추가합니다
경고: 더 작거나 저렴한 모델로 다운그레이드할 때는 다운스트림 자동화나 검토 단계의 역량 격차를 라벨링합니다. 조용히 「덜 똑똑한」 출력이 나오면 업무 사고로 이어집니다.
2026년에도 프로바이더 카탈로그는 바뀝니다. 설정을 문서로 두는 편이 구전보다 낫습니다. 라우트 표와 알림 임계값을 같은 저장소에 두어 인수인계 간극을 줄입니다.
Gateway가 APAC과 북미에 있으면 리전×프로바이더 히트맵을 그립니다. 지역 저하는 종종 글로벌 적신호의 전조이며 피크 대여 신호가 됩니다.
사용자 여정을 분해합니다. 인증→라우팅→모델 호출→도구 부작용→세션 기록. 각 단계는 requestId를 공유해야 합니다. 없으면 모델을 만지기 전에 트레이싱을 추가합니다.
하이브리드(노트북, 베어 서버, 컨테이너)에서는 주간 최소 패리티 테스트를 돌립니다. 동일 프롬프트·라우트 버전을 세 경로에서 비교하고, 지연/오차 편차가 임계를 넘으면 릴리스를 멈춥니다.
개인 기기는 절전, 불안정한 WAN, 감사되지 않은 환경 변수를 더해 라우팅 버그를 간헐적 유령으로 만듭니다. CI, 페이징, 고객 SLA가 걸리면 전용 연산, 안정적인 egress, 계약 가능한 대여 조건이 필요하며 hosts 무한 편집이 아닙니다.
24/7 Gateway, 배치 자동화, 빌드/서명 호스트 옆의 낮은 지연이 필요하면 실행을 전문 멀티 리전 Mac 클라우드에 두는 편이 관측·감사에 유리합니다. MACCOME은 Mac Mini M4/M4 Pro 베어메탈을 여러 리전에서 유연한 조건으로 제공합니다. 《멀티 리전·대여 기간 가이드》와 대여 요금을 함께 보세요.
파일럿에서는 한 리전에서 라우트와 로그 필드가 안정될 때까지 기다린 뒤, Gateway를 워크로드와 같이 두어 크로스 리전 추론과 스로틀링을 피할지 결정합니다.
고급 채널을 고급 Runbook에서 쓰면 모델 라우팅 변경과 채널 설정 변경을 별 릴리스로 나누어 폭발 반경을 줄입니다. 변경 티켓에 라우트 표 버전을 붙여 로그 샘플링과 감사에 씁니다.
자주 묻는 질문
업그레이드·마이그레이션 가이드와 어떻게 다른가요?
업그레이드 편은 백업과 롤백을 다룹니다. 본문은 런타임 라우팅과 이중 경로 로그입니다. 분류는 《설치 후 분류》를 보세요. 상업 조항은 《대여 요금》과 《고객 센터》에서 확인합니다.
Docker에 새 모델 이름이 보이는데 트래픽은 옛날입니다—무엇을 먼저 보나요?
Compose 볼륨과 환경 오버라이드를 확인하고, 컨테이너에 로드된 설정과 Gateway 로그를 봅니다. 《Docker 프로덕션》 헬스 체크와 함께 보세요.