노드 연결은(는) 무엇을 하나요?
목표: 하나의 정확한 클라이언트를 하나의 정확한 게이트웨이에 대해 수정하고, 해당 클라이언트의 새로운 연결을 증명합니다.
1. 대상 고정
대상 환경/프로필, OpenClaw 바이너리, 설정/상태 루트, 게이트웨이 URL/포트 및 서비스를 변경 전에 기록합니다.
- 모든 설정, 로그, 서비스, 장치 및 노드 명령에 대해 명명된 배포 래퍼/프로필을 사용합니다.
- 기본
openclaw, 증명 환경 또는 유사한 이름의 배포로 절대 변경하지 마십시오. - 글로벌 실행 파일이 오래된 경우 소유자를 통해 대상을 호출합니다.
- 상태, 설정, 로그 및 프로세스 ID가 동일한 게이트웨이를 설명하는지 확인합니다.
페어링 또는 인증을 변경하기 전에 대상 게이트웨이를 식별합니다.
2. 클라이언트 분류
명령을 선택하기 전에 요청 및 게이트웨이 로그에서 분류합니다.
- Control UI 브라우저: 사용자가 브라우저, 대시보드, Control UI 또는 웹챗을 언급합니다. 로그에
client=openclaw-control-ui또는mode=webchat가 표시됩니다. - 네이티브 모바일/노드: 공식 앱에서 연결, QR 스캔 또는 설정 코드를 표시합니다. 로그/요청 메타데이터에 네이티브 클라이언트 또는
role=node가 표시됩니다.
휴대폰은 두 클라이언트 모두 될 수 있습니다. 휴대폰 브라우저에는 openclaw qr 또는 openclaw nodes status를 사용하지 마십시오. 이는 네이티브 모바일/노드 페어링에 속합니다.
3. 실패 시도 관찰
고정된 대상을 통해 다음 명령을 실행합니다.
openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode
로그가 실시간으로 표시되는 동안 클라이언트가 한 번 재시도하도록 합니다. 해당 클라이언트 ID, 모드, 플랫폼, 주소, 인증 결과, 장치 ID, 사용자 및 종료 코드를 상호 연관시킵니다. 다른 페어링된 장치는 무시합니다.
첫 번째 실패 전환을 해석합니다.
- 일치하는 게이트웨이 시도 없음: 경로, DNS, TLS, origin 또는 프록시 문제.
token_missing,password_missing, 불일치 또는 Tailscale ID 실패: 페어링 전에 인증 실패. 따라서 빈 보류 목록이 예상됩니다.pairing required: 경로와 인증 성공. 정확한 보류 요청을 승인합니다.client connected:conn,client,mode및role을 정확한 클라이언트와 일치시킵니다. 입장은 hello 응답보다 먼저 발생합니다. 그 뒤에1006이 오면 인증/페어링을 유지하고 hello 전달, 수명 주기, 전송, 프록시 또는 재연결을 검사합니다. 이전 빌드는 임시 클라이언트를 생략하는 중복된authenticated user connected/webchat connected레코드를 사용합니다.- 일치하는 애플리케이션 수준 입장 레코드 없이
1006이 발생하면 인증/페어링을 증명하지 않습니다. 이전 핸드셰이크 전환을 검사합니다.
4. 경로 증명
동일 머신, LAN, tailnet 또는 공용 리버스 프록시 중 하나의 토폴로지를 선택합니다. 혼합하지 마십시오.
- 브라우저 Control UI는 브라우저 장치 ID를 위해 HTTPS 또는 localhost가 필요합니다. 원격 일반 HTTP tailnet/LAN URL은 유효한 대체물이 아닙니다.
gateway.tailscale.mode=off는 OpenClaw가 Serve/Funnel을 관리하지 않음을 의미합니다. Tailscale 또는 외부에서 관리되는 Serve 경로가 없음을 증명하지 않습니다.- Tailscale이 관련된 경우 OpenClaw 설정에서 추론하지 말고 실시간 상태를 검사합니다.
tailscale status --json
tailscale serve status --json
클라이언트의 URL을 고정된 게이트웨이에 도달하는 리스너/프록시 경로와 일치시킵니다.
5A. Control UI 브라우저 경로
페어링 요청을 찾기 전에 브라우저 인증을 복원합니다.
- 토큰/비밀번호 인증의 경우 Control UI 설정에 자격 증명을 입력합니다. 영구 비밀을 채팅, 로그 또는 URL에 절대 넣지 마십시오.
- 게이트웨이 호스트에서 일회성 서명된 핸드오프를 위해
openclaw dashboard를 선호합니다. 운영자가 해당 호스트의 클립보드를 검색할 수 있는 경우에만--no-open을 사용하고, 호스트 브라우저/클립보드를 에이전트 도구 외부에 유지합니다.dashboard --json을 절대 캡처하지 마십시오. 핸드오프 및 공유 자격 증명을 노출할 수 있습니다. 루프백 핸드오프 URL을 원격 전화로 중계, 재작성 또는 보내지 마십시오. - Tailscale Serve의 경우 실시간 경로와 전달된 ID를 확인합니다. 의도한 신뢰 경계에 대해서만
gateway.auth.allowTailscale을 활성화합니다. 브라우저 장치 ID로 확인된 Tailscale Control UI 인증은 페어링을 건너뛸 수 있습니다.
인증이 성공한 후:
- 재시도합니다. 인증 전 시도에서 페어링을 추론하지 마십시오. 토큰/비밀번호 인증은
pairing required를 드러낼 수 있습니다. 확인된 Tailscale ID는 건너뛸 수 있습니다. - 로그에
pairing required가 표시되면 장치를 다시 나열하고 정확한 요청 ID를 승인합니다. - 성공적인 확인된 Tailscale 연결은 보류 또는 페어링된 장치 행을 올바르게 생성하지 않을 수 있습니다.
- 반복된
1006이후에는 인증/페어링을 유지하고 재연결 증거를 검사합니다.
5B. 네이티브 모바일/노드 경로
설정 자격 증명을 노출하지 않고 고정된 대상을 통해 네이티브 경로를 검사합니다.
openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'
원격 게이트웨이를 제어하는 CLI의 경우 --json 앞에 --remote를 추가합니다. 이는 gateway.remote.url 및 원격 자격 증명을 선택합니다. 편집 필터를 사용할 수 없는 경우 에이전트가 볼 수 있는 출력에서 원시 QR JSON을 실행하지 마십시오.
gatewayUrl 및 urlSource를 확인합니다. 설정 코드는 비밀번호와 동등합니다. 운영자가 Control UI → 장치 → 장치 페어링에서 복사하거나, 에이전트 도구 외부의 터미널에서 openclaw qr --setup-code-only를 실행하여 공식 앱에 직접 붙여넣도록 합니다. 에이전트/채팅/도구 출력을 통해 절대 중계하지 마십시오. URL/인증 수정 또는 만료 후 새 코드를 생성합니다.
앱이 pairing required를 보고하는 경우:
openclaw devices list
openclaw devices approve --latest # 미리보기 전용; 승인 없이 종료
openclaw devices approve <requestId>
openclaw nodes status
--latest는 현재 요청만 미리 봅니다. 절대 승인으로 처리하지 마십시오. 재시도가 요청을 대체할 수 있으므로 정확한 ID 명령 바로 전에 다시 나열합니다. 위치, 기간 또는 유사성으로 승인하지 마십시오.
6. 상호 연관 및 종료
승인 전에 사용 가능한 요청, 장치/공개 키, 클라이언트, 모드/역할, 플랫폼, 주소, 사용자 및 재시도 시간 사실을 일치시킵니다.
최종 변경 후 이루어진 새로운 시도가 모든 적용 가능한 검사를 입증한 경우에만 성공을 선언합니다.
- 정확한 클라이언트가 고정된 게이트웨이에 도달합니다.
- 의도된 인증이 성공합니다.
- 브라우저가 초기 요청을 완료하거나 네이티브 노드가
openclaw nodes status에 나타납니다. - 승인에 정확한 요청 ID가 사용되었습니다.
- 즉시 인증, 페어링 또는 재연결 실패가 발생하지 않습니다.
QR/설정 코드, 실행된 브라우저, 빈 보류 목록, 승인, 페어링된 장치 수 또는 Tailscale ping은 하나의 전환만 증명합니다.
진단, 선택된 경로/인증 경로, 정확한 클라이언트 증거 및 남아 있는 실패 전환을 보고합니다.