🦞 23. node run plaintext ws 보안에러 해결

openclaw node run --host 192.168.x.x --port 18789 실행 시 Cannot connect ... over plaintext ws:// 에러가 뜰 때, 가장 빠른 복구 방법을 정리한다.

빠른 탐색이 필요하면 지식정원 홈에서 오늘의 문제해결 링크를 먼저 확인해도 좋다.

문제 요약

증상 예시:

node host gateway connect failed:
SECURITY ERROR: Cannot connect to "192.168.0.39" over plaintext ws://
Use wss:// for the gateway URL, or connect via SSH tunnel to localhost.

핵심 원인:

• ws://는 평문 전송이라 OpenClaw가 보안상 기본 차단
• Gateway 자격정보/채팅 데이터가 네트워크에서 노출될 수 있음

원인 구조 한눈에 보기

flowchart LR
A[node run --host 192.168.0.39] --> B[기본 연결: ws://192.168.0.39:18789]
B --> C{평문인가?}
C -- 예 --> D[OpenClaw 보안차단]
D --> E[SECURITY ERROR]
C -- 아니오(wss/터널) --> F[정상 연결]

해결 방법 1 (권장): SSH 터널

가장 빠르고 안전한 실전 복구 경로다.

1) 37에서 터널 오픈 (터미널 A)

ssh -N -L 18789:127.0.0.1:18789 tw2@192.168.0.39

• -N: 명령 실행 없이 터널만 유지
• 이 창은 닫지 말고 유지

2) 37에서 node 연결 (터미널 B)

openclaw node run --host 127.0.0.1 --port 18789 --display-name mcclaw-37

3) 39에서 페어링 승인

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes status --connected

해결 방법 2: TLS(wss) 직접 연결

운영 환경에서 TLS를 준비했다면 wss로 직접 연결 가능.

• Gateway를 TLS/wss로 노출
• node run에 TLS 옵션 적용

openclaw node run --host <gateway-host> --port <tls-port> --tls --display-name mcclaw-37

초기 구성 난이도는 SSH 터널보다 높음.

복구 체크리스트 (3분)

• 39에서 openclaw gateway status가 정상인가?
• 37↔39 네트워크 경로가 살아있는가? (IP/포트)
• 평문 ws://로 직접 붙고 있지 않은가?
• SSH 터널을 연 뒤 127.0.0.1:18789로 붙는가?
• nodes pending에 요청이 보이고 approve 되었는가?

재현 절차 (문제 확인용)

문제가 맞는지 1분 안에 확인하려면 아래 순서로 재현한다.

1. 37에서 평문 연결 시도

openclaw node run --host 192.168.0.39 --port 18789 --display-name mcclaw-37

2. 아래 에러 문구가 나오면 본 문서의 대상 이슈가 맞다.

SECURITY ERROR: Cannot connect to "192.168.0.39" over plaintext ws://

3. 즉시 Ctrl + C로 종료 후 SSH 터널 방식으로 전환한다.

실패사례 (현장에서 자주 막히는 지점)

사례 1) SSH 터널은 열었는데 여전히 실패

• 원인: node run에서 --host 127.0.0.1 대신 원래 IP를 그대로 사용
• 해결: 터널을 열었으면 반드시 localhost로 연결

사례 2) Permission denied (publickey,password)

• 원인: 39 로그인 계정명 오입력 또는 SSH 키 미등록
• 해결: ssh <계정>@192.168.0.39 'whoami'로 계정 확인 후 키 재등록

사례 3) 페어링이 안 보임

• 원인: 39에서 nodes pending 확인 전에 node 프로세스가 종료됨
• 해결: 37에서 openclaw node run ... 프로세스를 유지한 상태로 승인 진행

FAQ

Q1. 왜 그냥 ws://192.168...로 붙으면 안 되나요?

A. 인증정보/대화 데이터가 평문으로 노출될 수 있어 보안상 기본 차단됩니다.

Q2. SSH 터널과 TLS(wss) 중 뭐가 더 좋나요?

A. 단기 복구는 SSH 터널이 가장 빠르고, 상시 운영은 TLS(wss)가 더 구조적으로 깔끔합니다.

Q3. 연결은 됐는데 --connected에 안 보일 때는?

A. 승인 누락이 가장 흔합니다. 39에서 openclaw nodes pending → approve 순서로 확인하세요.

발행 전 체크 (품질 게이트)

• 재현 명령 1개 + 복구 명령 1개를 실제로 복붙 검증했는가?
• 계정명/호스트/IP 예시가 현재 운영 환경과 일치하는가?
• 성공 판정(nodes status --connected)이 본문에 명시되었는가?
• 관련 문서(허브/인덱스) 링크가 살아있는가?

자주 하는 실수

1. --host 192.168.0.39로 바로 접속 시도 (평문 차단)
2. 터널 창을 닫아놓고 node run 실행
3. 페어링 승인(nodes approve) 생략

다음 읽기

• 지식정원 홈으로 돌아가기
• OpenClaw 인덱스에서 연관 복구 가이드 보기

한 줄 결론

node run plaintext ws 에러는 장애가 아니라 의도된 보안 차단이다.
실무에서는 SSH 터널 + localhost 연결이 가장 빠른 표준 복구 경로다.

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.