2026 OpenClaw Gateway 페어링과 토큰 충돌 실무: onboarding 정체, 1006/1008, 환경 변수가 설정을 덮어쓸 때의 단계별 체크리스트

약 15분 읽기 · MACCOME

대상: Docker 또는 로컬에 OpenClaw를 설치했는데 openclaw CLI가 최초 페어링·onboarding·컨테이너 실행에서 WebSocket 1006/1008을 반복하거나, 설정 파일을 바꿔도 token mismatch가 남는 경우입니다.핵심: 환경 변수 덮어쓰기, CLI가 실제로 붙는 ws URL, 페어링 상태 머신을 한 장의 대조표에 맞춘 뒤 openclaw doctor와 Docker 네트워크 글을 이어 붙입니다.구성: 여섯 가지 오판, 증상 매트릭스, 지문 명령, 여섯 단계 Runbook, 세 KPI, 호스팅 정리입니다.

gateway.auth.token을 바꿨는데도 mismatch가 남는 이유: 여섯 가지 흔한 오판

2025–2026 커뮤니티 장애 분류에서 OpenClaw Gateway 페어링·인증 문제는 종종 «네트워크가 끊겼다»로 섞입니다. 로그에 종료 코드와 모델 오류가 같이 보이면 상류 LLM 장애로 착각하기 쉽습니다. 아래 여섯 줄은 당직에서 엔지니어를 다른 길로 빼는 패턴이니, 설치 후 doctor와 Gateway 헬스와 함께 위키 첫 화면에 붙여 두세요.

  1. OPENCLAW_GATEWAY_TOKEN이 설정 파일을 조용히 덮어씁니다: 컨테이너나 launchd 유닛이 주입한 환경 변수가 우선합니다. 디스크의 gateway.auth.token은 바꿨는데 프로세스는 예전 값을 읽어 «재시작해도 mismatch»처럼 보입니다.
  2. 컨테이너 안 CLI가 기본으로 127.0.0.1을 향합니다: Compose에서 CLI의 Gateway URL을 openclaw-gateway 서비스 이름으로 돌리지 않으면 핸드셰이크 초기에 실패하고, 애플리케이션 계층 오류 없이 1006/1008만 남아 Docker 네트워크 분기 체크리스트와 겹칩니다.
  3. 페어링이 끝나기 전에 무거운 작업을 돌립니다: 명시 확인이나 상태 기록이 필요한 onboarding 단계를 스크립트 파이프라인이 건너뛰면 Gateway는 듣고 있어도 세션 계층이 준비되지 않아 CLI에서는 «가끔 붙었다가 바로 끊김»처럼 보입니다.
  4. 설정 경로가 두 갈래입니다: 사용자 홈과 프로젝트에 각각 .openclaw가 있고, CLI가 읽는 경로와 편집기에서 연 파일이 다릅니다.
  5. CI 시크릿에 오래된 token이 남습니다: Gateway token을 교체한 뒤 GitHub Actions나 GitLab CI 변수가 갱신되지 않아 야간 잡이 잘못된 token으로 로그를 채우고, 고쳐야 할 Runner 라벨 이슈를 가립니다.
  6. 1006을 모두 «잠깐 네트워크 흔들림»으로만 봅니다: «프로토콜상 정상 종료»와 «인증·서브프로토콜 실패»를 나누지 않으면 네트워크 글과 이 글 사이를 왕복하며 수렴하지 못합니다.

공식 설치 스크립트와 npm 전역 경로와의 관계: 설치 글은 «바이너리와 Node 버전이 PATH에 있다»를 보장하고, 이 글은 «CLI와 Gateway가 같은 token과 같은 WebSocket 엔드포인트로 말한다»를 보장합니다. 같은 첫날 Runbook에 순서대로 넣습니다.

표 1: 증상 → 우선 의심 스택 → 다음 단계 (페어링 먼저, 그다음 네트워크, 마지막 모델)

이 매트릭스는 첫 분기용입니다. 행에 해당하면 해당 점검을 «재현 가능한 명령 출력»까지 만든 뒤 다음으로 넘어가고, token·Compose·리버스 프록시를 동시에 바꾸지 마세요.

겉으로 보이는 증상먼저 의심할 스택즉시 할 점검다음 문서
로그: token mismatch이고 파일 수정이 소용없음환경 변수 덮어쓰기 / 다중 설정프로세스 환경의 OPENCLAW_GATEWAY_* 출력; 실제 로드 경로와 대조이 글 §3 지문 스크립트; 설치 후 doctor 글
컨테이너에서만 실패하고 호스트는 성공루프백 / 서비스 이름 / DNS컨테이너 안에서 Gateway 포트를 curl 또는 nc로 확인; ws URL 호스트 검증Docker 네트워크 분기 체크리스트
1008과 401/403 의미 또는 명시적 인증 실패인증 설정 / 리버스 프록시 헤더 제거loopback 직접 연결로 재현; 프록시 전후 응답 헤더 비교Nginx/Caddy 리버스 프록시와 WebSocket 글
1006이 잦고 인증 오류가 분명하지 않음유휴 종료, 프로브에 의한 세션 종료, 버전 불일치CLI와 Gateway 버전 정렬; 게이트웨이 로그에서 세션 회수 여부 확인Gateway 무응답과 doctor 글
onboarding UI/CLI가 멈춘 것처럼 보임상태 머신 미완 / 포트 충돌리슨 포트 충돌 확인; 재페어링 전 임시 상태 정리(공식 안내)공식 Troubleshooting; 이 글 Runbook
재설치 후 «한 번은 붙었다가» 곧 끊김예전 token 주입 경로가 남음systemd drop-in, 셸 프로파일, CI 변수 확인설치 글의 pin과 프록시 폴백 절

실행 스니펫: «누가 token을 덮어쓰는지»와 «CLI가 실제로 어디로 가는지»

출력은 티켓에 붙이고, 루트 경로는 환경에 맞게 바꿉니다. Docker 볼륨과 권한과 함께 검토할 때는 마운트가 새 볼륨을 오래된 설정 디렉터리로 가리지 않는지 확인하세요.

bash
# A) 현재 셸에서 보이는 환경 변수(대소문자와 접두사 주의)
env | sort | grep -i OPENCLAW || true

# B) 예시: systemd로 gateway를 관리할 때 drop-in이 token을 주입하는지
# systemctl show openclaw-gateway --property=Environment 2>/dev/null || true

# C) CLI 버전과 doctor(먼저 얕게—프로덕션에서 무분별 --fix는 피함)
openclaw --version || true
openclaw doctor 2>/dev/null | sed -n '1,40p' || true

# D) CLI 쪽 gateway URL 출력(서브커맨드는 설치된 빌드에 맞출 것)
# openclaw config get gateway.remoteUrl  # 예시 이름, 자리 표시자

# E) Docker: CLI를 돌리는 컨테이너에서 ws 목적지가 잘못된 127.0.0.1:18789가 아닌지
# docker compose exec cli sh -lc 'env | grep -i OPENCLAW; getent hosts openclaw-gateway || true'
info

안내: 커뮤니티 이슈에서 환경 변수의 token과 파일 불일치로 onboarding이 오래 멈추는 사례가 흔합니다. Compose 변경을 논하기 전에 A/B 출력을 먼저 채우세요.

여섯 단계 Runbook: «연결 안 됨»에서 «재현 가능한 페어링 결론»까지

  1. 버전 지문을 고정합니다: CLI, Gateway 이미지 태그, pin된 npm 전역을 기록하고 설치 글의 pin 정책과 맞춰, 장애 분석 중 자동 업그레이드가 끼어들지 않게 합니다.
  2. 층별로 재현합니다: loopback 직결 → 같은 호스트의 다른 네트워크 네임스페이스(컨테이너) → 리버스 프록시 순으로, 각 층에서 실패가 시작하는 로그 조각을 남깁니다.
  3. 덮어쓰기 원을 비웁니다: OPENCLAW_GATEWAY_TOKEN 등 주입을 하나씩 제거하고 프로세스 재시작 후 환경이 깨끗한지 확인한 뒤, 설정 파일에 단일 진실을 되돌립니다.
  4. ws URL을 바로잡습니다: 컨테이너에서는 서비스 이름과 올바른 포트를 명시합니다. Docker 네트워크 글의 «127.0.0.1 기본 오지정 금지」 조항과 대조합니다.
  5. 페어링을 다시 돌리고 상태를 캡처합니다: 공식 onboarding 순서를 따릅니다. 빌드에 doctor --deep가 있으면 변경 창 안에서 실행하고 출력을 보관합니다.
  6. 회귀 테스트를 추가합니다: 최소 재현을 CI smoke(health만, 무거운 모델 없음)로 옮겨 다음 Compose 병합이 token 이중 트랙을 다시 넣지 못하게 합니다.

대시보드와 변경 티켓에 넣을 만한 단단한 세 가지 지표

  1. Token 진실 개수: 환경 변수, 설정 파일, 시크릿 관리 주입 경로를 셉니다(해시 앞부분만으로도 됨). 하나보다 많으면 위반입니다. 먼저 수렴시킵니다.
  2. 페어링 재시도율: onboarding 재시도 대비 성공을 기록합니다. 단기 급등은 보통 이중 token이나 잘못된 ws 호스트이며 «모델이 느려서»가 아닙니다.
  3. 1006/1008 비율: 주간으로 종료 코드와 인접 로그 키워드를 묶습니다. 1008이 인증 키워드와 같이 오르면 CPU를 늘리기 전에 리버스 프록시와 헤더를 봅니다.

엔지니어링 정렬 메모(실험실 벤치가 아니라 커뮤니티·운영 경험): 공개 이슈에서 token 이중 트랙과 컨테이너 루프백 오지정은 «첫 배포 실패» 유형 상위에 계속 남습니다. 변경 템플릿에 환경 변수 감사를 넣으면 평균 분기 라운드가 줄어드는 경우가 많습니다. 더 중요한 점은 이런 실패가 GHz와 약한 상관이라는 것입니다. 메모리만 늘려서 핸드셰이크 실패가 사라지지는 않습니다.

Gateway를 7×24로 돌리고 개인 노트북의 절전·전원과 싸우지 않으려면 «안정적인 전용 실행면»과 «페어링·업그레이드 창»을 같은 SRE 문서에 둡니다. 기업이 에이전트용 Gateway를 원격 Mac에 상주시키는 관행과도 맞습니다.

왜 «노트북에 Gateway를 올려 둔 채로」는 프로덕션 페어링 리듬을 버티기 어렵나

개인 기기에서는 절전, VPN 전환, 기업 인증서 갱신의 영향을 받기 쉬워 페어링 상태 머신을 감사하고 재생하기 어렵습니다. token 로테가 여러 사람의 CI에 걸칠 때 노트북 환경은 고정 호스트명과 안정적인 루프백 경계도 부족해 로그가 잘게 쪼개집니다.

예측 가능하게 재시작할 수 있고 디스크·로그 동작이 읽기 쉬우며 팀 Runner와 같은 네트워크에 둘 수 있는 전용 원격 Mac에 Gateway를 두면, 여러 대의 개인 기기를 옮겨 다니는 것보다 onboarding 이슈가 빨리 수렴합니다. Apple Silicon을 상시 가동하고 CI 비밀 모델과 맞춰 납품하려는 팀은 MACCOME Mac mini M4 / M4 Pro 멀티 리전과 유연한 렌탈 기간으로 «페어링 분기»와 «안정 실행면»을 같은 청구와 변경 리듬에 올릴 수 있습니다. 먼저 공개 가격 안내를 읽고, 운영은 원격 Mac 상주 운영 체크리스트에 맞춥니다.

파일럿 제안: 주 CI와 같은 리전의 원격 한 대만 고르고 Gateway와 최소 smoke 잡만 올린 뒤, 격주 리뷰에서 이 글의 여섯 단계 Runbook을 돌리고, 그다음 대화형 개발까지 같은 토폴로지로 옮길지 결정합니다.

자주 묻는 질문

먼저 doctor를 돌릴까요, token을 바꿀까요?

먼저 이 글의 표 1로 «페어링·token」을 갈라냅니다. 네트워크 층까지 확정됐다면 doctor의 네트워크 항목을 병행해도 됩니다. 공개 가격과 리전은 Mac mini 대여 가격 안내를 보세요.

1006은 항상 1008보다 덜 심각한가요?

반드시 그렇지는 않습니다. 인접 로그 줄과 재현성을 함께 봅니다. 종료 코드는 라벨이지 결론이 아니므로 인증 분기를 건너뛰지 마세요.

프로덕션 컨테이너에 token을 오래 export해 두어도 되나요?

권장하지 않습니다. 오케스트레이터가 단기 자격 증명을 주입하거나 시크릿 사이드카를 쓰고 «진실»을 한곳으로 모으는 편이 안전합니다. 그렇지 않으면 로테 때마다 이중 트랙이 생기기 쉽습니다.