44. OpenClaw gateway probe가 실패할 때 읽는 순서

openclaw gateway probe를 돌렸는데 ok가 안 보이거나, 로컬은 되는데 remote만 실패하거나, 어떤 날은 되고 어떤 날은 안 되면 순간적으로 전체가 망가졌다고 느끼기 쉽다. 그런데 OpenClaw 공식 문서와 실제 CLI help를 같이 보면 이 명령은 단순 ping이 아니라 local loopback, configured remote gateway, discovery, health, status를 한 번에 좁혀 보는 진단용 명령에 가깝다. 그래서 실패가 떠도 바로 재설치로 갈 일은 의외로 많지 않다.

공식 gateway troubleshooting은 기본 사다리를 openclaw status → openclaw gateway status → openclaw logs --follow → openclaw doctor → openclaw channels status --probe 순서로 제시한다. 실제 openclaw gateway probe --help도 이 명령을 Show gateway reachability + discovery + health + status summary (local + remote)라고 설명한다. 핵심은 간단하다. probe 실패는 “gateway가 죽었다”보다 “어느 경로를 통해 어느 gateway를 보려 했는지”가 먼저 어긋난 경우가 많다.

안내: 본문은 생성형 AI로 초안을 정리하고, OpenClaw 공식 문서와 실제 CLI help 출력을 기준으로 보정했습니다.

flowchart TD
A[`openclaw gateway probe` 실패] --> B{local도 실패하나?}
B -->|예| C[`openclaw gateway status`로 runtime 확인]
B -->|아니오| D{remote만 실패하나?}
D -->|예| E[`--url`, `--token`, `--ssh` 경로 확인]
D -->|아니오| F{어떤 gateway가 winner인지 헷갈리나?}
F -->|예| G[discovery / probe 결과로 active target 분리]
F -->|아니오| H[`openclaw logs --follow` + `doctor`]
C --> I[서비스 축 복구]
E --> J[인증/원격 경로 정렬]
G --> J
H --> K[구조 문제 정리]
I --> L[다시 probe]
J --> L
K --> L

칠판 치트시트

1. gateway probe는 단순 연결 테스트가 아니다
2. local 실패와 remote 실패는 같은 문제로 보면 안 된다
3. --url을 쓰면 config나 env 자격증명에 자동 fallback하지 않는다
4. 여러 gateway가 보이면 먼저 어느 target이 진짜 기준인지 정해야 한다
5. probe 실패만 보고 브라우저, 채널, 세션 문제를 한 덩어리로 묶지 않는 편이 빠르다

이런 증상이면 이 문서가 바로 맞다

• openclaw gateway probe에서 로컬은 되는데 remote만 실패한다.
• openclaw gateway status는 얼핏 정상인데 probe가 흔들린다.
• 어떤 날은 붙고 어떤 날은 안 붙어서 active target drift가 의심된다.
• --url을 붙였더니 갑자기 unauthorized나 timeout처럼 보인다.
• 채널이나 browser 문제처럼 보이는데 실제로는 gateway reachability부터 잘라야 한다.

먼저 알아둘 것, probe는 여러 후보를 함께 본다

공식 gateway CLI 문서는 probe를 local + remote reachability, discovery, health, status summary를 함께 보여 주는 명령으로 설명한다. 즉 이 명령이 실패했다고 해서 곧바로 gateway 프로세스가 죽었다고 단정하면 안 된다.

실무에서는 아래 셋이 자주 섞인다.

• local loopback은 정상
• configured remote만 실패
• discovery는 보이는데 auth가 맞지 않음

이 셋은 체감상 모두 “probe 실패”처럼 보이지만, 복구 방향은 전혀 다르다.

왜 자주 헷갈리는가

1) gateway status와 gateway probe는 보는 층이 조금 다르다

공식 gateway troubleshooting은 먼저 openclaw gateway status를 보고 healthy signal로 Runtime: running, Connectivity probe: ok, Capability: ...를 기대한다고 설명한다. 즉 status는 서비스 상태와 probe 결과를 요약해서 보여 주는 축이다.

반면 gateway probe는 실제 help 설명 그대로 local, remote, discovery, health, status summary를 더 적극적으로 스캔한다. 그래서 status는 정상처럼 보여도 probe에서 remote 경로나 active target 충돌이 드러날 수 있다.

2) --url을 쓰는 순간 자격증명 fallback 기대가 깨질 수 있다

공식 gateway CLI 문서는 중요한 주의사항을 하나 명시한다. --url을 직접 주면 CLI는 config나 environment 자격증명으로 fallback하지 않는다. 이때는 --token 또는 --password를 명시해야 한다.

이 규칙을 놓치면 자주 이렇게 보인다.

• 평소에는 잘 되던 probe가 --url을 넣는 순간 실패
• 사람은 네트워크 문제라고 느끼지만
• 실제 원인은 자격증명을 명시하지 않은 호출 방식 변화

즉 URL을 강제로 지정했다면, 인증도 같이 강제로 맞춰 준다고 생각하는 편이 덜 헷갈린다.

3) 여러 gateway가 동시에 reachable하면 “무엇이 진짜 기준인지”부터 꼬인다

공식 gateway CLI 문서는 probe가 local loopback과 설정된 remote gateway를 함께 본다고 설명한다. remote 운영에서는 discovery나 터널 상태까지 얽히기 쉽기 때문에, 체감상 같은 OpenClaw인데도 어느 날은 로컬, 어느 날은 다른 remote가 winner처럼 보일 수 있다.

이때 브라우저나 채널만 만지면 같은 현상이 반복된다. 실제로는 어느 gateway가 source of truth인지부터 분리해야 하기 때문이다.

가장 빠른 5분 점검 순서

1) 먼저 local이 죽은 건지, remote만 죽은 건지 자른다

가장 먼저 할 일은 “안 된다”를 하나로 보지 않는 것이다.

openclaw gateway status
openclaw gateway probe

이때 해석은 이렇게 한다.

• local도 실패 → 서비스 축 또는 로컬 bind/auth 축 우선
• local은 정상, remote만 실패 → 원격 URL/토큰/SSH 축 우선
• 둘 다 보이는데 결과가 들쭉날쭉 → active target drift 가능성 우선

이 분기만 해도 불필요한 재시작이 많이 줄어든다.

2) --url을 썼다면 --token 또는 --password를 같이 봐야 한다

공식 문서의 shared options 설명과 note 기준으로, --url을 줄 때는 자격증명을 자동으로 기대하면 안 된다.

openclaw gateway probe --url ws://127.0.0.1:18789 --token <token>

이 점이 중요한 이유는 간단하다. 평소 기본 설정으로는 잘 되던 명령도, 명시 URL 호출로 바꾸는 순간 인증 경로가 달라질 수 있기 때문이다.

3) remote면 --ssh 축과 target 구분을 같이 본다

실제 openclaw gateway probe --help에는 --ssh, --ssh-auto, --ssh-identity 옵션이 있다. 즉 원격 경로가 얽힌 환경에서는 단순 HTTP/WebSocket reachability만 보는 게 아니라, 어떤 SSH target을 통해 어떤 gateway를 보려는지도 함께 맞춰야 한다.

openclaw gateway probe --ssh user@host

이 단계에서 자주 풀리는 문제는 아래다.

• 잘못된 host를 보고 있음
• discovery는 되지만 실제 터널 대상이 다름
• identity file 또는 SSH 대상이 바뀌었음

4) 그래도 흔들리면 logs와 doctor로 구조 문제를 분리한다

공식 gateway troubleshooting은 command ladder에 openclaw logs --follow와 openclaw doctor를 같이 둔다. probe만 오래 보는 것보다, 실제 실패 서명과 구조 경고를 함께 읽는 편이 빠르기 때문이다.

openclaw logs --follow
openclaw doctor

여기서 얻는 힌트는 보통 두 갈래다.

• runtime/service 쪽이 실제로 흔들리는가
• auth/config/path drift가 누적된 상태인가

5) browser나 channels 증상으로 번졌다면 원인과 증상을 분리한다

gateway probe 실패는 나중에 browser, dashboard, channels 문제처럼 체감될 수 있다. 하지만 복구 순서는 반대다. 먼저 gateway reachability를 자르고, 그 다음 도구별 증상으로 내려가야 한다.

예를 들어 아래처럼 읽으면 편하다.

• probe 실패 + browser 실패 → browser보다 gateway 축이 먼저
• probe 실패 + channels 흔들림 → channel token보다 전역 gateway 축이 먼저
• probe 정상 + browser/channels 실패 → 이제 각 도구 문서로 내려가도 됨

운영자가 바로 판단하는 기준

상황	먼저 볼 것	이유
local도 remote도 둘 다 실패	openclaw gateway status	gateway runtime 자체 문제인지 먼저 갈라야 한다
local은 정상, remote만 실패	--url, --token, --ssh	원격 경로나 인증이 더 유력하다
--url 넣은 뒤부터 실패	explicit credentials	문서상 자동 fallback이 꺼진다
어떤 날은 되고 어떤 날은 안 됨	active target drift	같은 gateway를 보고 있지 않을 수 있다
probe 실패 뒤 browser/channels도 흔들림	gateway 축 우선	증상보다 공통 원인을 먼저 자르는 편이 빠르다

현장 미니 사례 2개

사례 A) 로컬은 되는데 remote만 계속 timeout처럼 보인 경우

• 상황: gateway status는 대체로 정상, remote probe만 흔들림
• 실제 원인: gateway 전체 장애가 아니라 원격 경로 또는 SSH target drift
• 복구: --ssh 대상과 실제 remote URL을 다시 맞춘 뒤 재확인
• 포인트: local 정상 여부를 먼저 분리했더니 범위가 바로 줄어들었다

사례 B) --url을 붙인 뒤부터 unauthorized처럼 보인 경우

• 상황: 기본 호출은 되던 명령이 explicit URL 사용 후 실패
• 실제 원인: 공식 문서 note대로 explicit URL 호출 시 credentials fallback을 기대하면 안 됐음
• 복구: --token 또는 --password를 함께 명시
• 포인트: 네트워크 문제처럼 보였지만 실제로는 호출 방식 변경에 따른 인증 누락이었다

검색형 FAQ

Q1. openclaw gateway probe가 실패하면 gateway가 꺼진 건가요?

꼭 그렇지는 않다. 공식 문서와 help 기준으로 probe는 local, remote, discovery, health, status summary를 함께 본다. 어느 경로가 실패했는지 먼저 나눠야 한다.

Q2. gateway status는 정상인데 probe는 왜 실패하나요?

status는 서비스 상태와 연결 요약을 보여 주고, probe는 remote/discovery/health까지 더 적극적으로 스캔한다. 그래서 remote target drift나 인증 누락이 probe에서 먼저 드러날 수 있다.

Q3. --url만 넣었는데 왜 갑자기 안 되나요?

공식 gateway CLI note 기준으로 --url을 명시하면 config나 env credentials로 fallback하지 않는다. --token 또는 --password를 같이 넣어야 한다.

Q4. remote probe가 흔들릴 때 무엇부터 봐야 하나요?

--ssh, --ssh-auto, --ssh-identity, 그리고 실제 remote URL과 target host가 맞는지부터 보는 편이 빠르다.

Q5. 가장 짧은 복구 순서는 무엇인가요?

openclaw gateway status → openclaw gateway probe → explicit URL/credentials 확인 → SSH target 확인 → logs/doctor 순서가 가장 덜 헷갈린다.

다음 읽기

• 15. gateway token mismatch로 remote unauthorized 뜰 때 해결
• 27. OpenClaw 대시보드가 안 열릴 때 해결
• 30. OpenClaw 채널은 연결됐는데 답이 없을 때 해결
• 33. OpenClaw gateway status는 정상인데 browser가 안 될 때 해결
• 41. OpenClaw doctor에서 경고가 여러 개 뜰 때 우선순위 정리
• 42. OpenClaw status —all에서 경고가 떠도 먼저 볼 것
• 43. OpenClaw channels status —probe가 실패할 때 해결 순서
• 🚀 OpenClaw 허브
• Troubleshooting 허브

한 줄 결론

openclaw gateway probe가 실패해도 바로 전체 장애로 보면 복구가 느려진다. local과 remote를 먼저 나누고, explicit URL 호출이면 credentials fallback이 없다는 점까지 함께 확인하는 것이 가장 빠르다.

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