15. gateway token mismatch로 remote unauthorized 뜰 때 해결

openclaw browser ...나 openclaw gateway ...를 쳤는데 unauthorized: gateway token mismatch가 뜨면, 보통은 브라우저 문제가 아니라 지금 붙으려는 클라이언트의 토큰과 실제 gateway가 요구하는 토큰이 서로 다르다는 뜻이다. 여기서 많이 헷갈리는 지점은, “gateway는 살아 있는데 왜 안 붙지?”라는 부분이다. 실제로는 프로세스가 죽은 게 아니라 연결은 시도됐지만 인증 단계에서 막힌 상태인 경우가 많다.

OpenClaw 공식 문서도 문제를 볼 때 먼저 openclaw status와 openclaw gateway status 같은 진단 계단부터 확인하라고 안내한다. 또한 remote access 문서에서는 하나의 gateway가 세션과 상태의 source of truth라고 설명한다. 그래서 다른 머신에서 접속할 때는 단순히 포트가 열려 있는지만 볼 게 아니라, 어느 gateway에 어떤 인증 정보로 붙는지를 같이 봐야 한다.

30초 핵심 요약

gateway token mismatch는 대개 장애보다 인증 불일치다.
gateway가 살아 있어도, client 쪽 gateway.remote.token과 gateway 쪽 gateway.auth.token이 다르면 unauthorized가 난다.
먼저 gateway가 진짜 죽었는지 확인하지 말고, 같은 host / 같은 port / 같은 token을 보고 있는지부터 맞추는 편이 빠르다.
원격 장비가 여러 대면 “지금 내가 37을 보는지 39를 보는지” 같은 대상 host 구분이 가장 먼저다.

칠판 치트시트

openclaw status로 기본 상태 확인

openclaw gateway status로 runtime/probe 확인

지금 접속 대상 host와 port가 맞는지 확인

gateway 쪽 auth token과 client 쪽 remote token이 같은지 확인

브라우저 문제로 오해하지 말고 인증 경로부터 자른다

flowchart LR
A[gateway 명령 실행] --> B{unauthorized: token mismatch?}
B -- 아니오 --> G[다른 원인 탐색]
B -- 예 --> C[대상 host/port 재확인]
C --> D[gateway runtime 정상 여부 확인]
D --> E[client remote token vs gateway auth token 비교]
E --> F{같은 값인가?}
F -- 아니오 --> H[토큰 정렬 후 재시도]
F -- 예 --> I[다른 auth mode/경로 점검]
H --> J[openclaw gateway status 재검증]
I --> J

이 에러를 먼저 이렇게 해석하면 덜 꼬인다

빠른 troubleshooting 문서는 openclaw status → openclaw status --all → openclaw gateway probe → openclaw gateway status → openclaw doctor 순서로 보라고 안내한다. 여기서 중요한 건 gateway token mismatch가 떴을 때도 바로 재설치/재시작으로 가지 않는 것이다.

왜냐하면 이 에러는 “gateway가 없음”이 아니라, gateway는 있는데 지금 인증된 연결로 받아주지 않음을 뜻하는 경우가 많기 때문이다. Gateway troubleshooting 문서도 dashboard/control UI 연결 문제를 볼 때 URL·auth mode·token mismatch를 먼저 의심하라고 설명한다.

왜 자주 생기나

이 문제는 보통 아래 셋 중 하나로 생긴다.

1) 다른 머신의 gateway를 보고 있다

Remote access 문서는 gateway host가 세션과 상태를 소유한다고 설명한다. 그래서 노트북, 데스크톱, VPS를 섞어 쓰면 “내가 지금 어디 gateway에 붙고 있는지”부터 분리해야 한다.

예를 들어 37번 맥북의 gateway를 보고 있다고 생각했는데 실제로는 39번 호스트 기준 설정을 쓰고 있으면, 포트는 살아 있어도 토큰이 맞지 않아 인증이 틀어진다.

2) token은 바뀌었는데 client 설정은 예전 값을 계속 쓴다

Gateway CLI 문서를 보면 gateway query 명령들은 URL, token, password 같은 공용 연결 옵션을 사용한다. 즉, 예전 토큰이 남아 있으면 연결 자체는 시도하지만 인증에서 떨어질 수 있다.

이럴 때 흔한 패턴은 아래와 같다.

gateway 재설정 또는 온보딩 이후 토큰이 바뀜
클라이언트/별도 머신 설정은 예전 값을 유지함
결과적으로 unauthorized만 반복됨

3) 포트/터널은 맞는데 auth mode가 다르다

CLI gateway 문서는 gateway가 token/password 등 auth 모드를 가진다고 설명한다. 그래서 포트가 열려 있고 터널도 살아 있는데, 한쪽은 token 기준이고 다른 쪽은 다른 인증 기대값으로 붙으면 똑같이 인증 실패처럼 보일 수 있다.

5분 복구 순서

운영자 기준으로는 아래 순서가 가장 빠르다.

1) gateway가 정말 죽은 건지 먼저 분리

openclaw status
openclaw gateway status

이 단계의 목적은 “무응답”과 “인증 불일치”를 분리하는 것이다.

runtime 자체가 비정상이면 먼저 gateway 상태부터 복구해야 한다.
runtime은 정상인데 RPC probe나 연결 단계에서 auth 관련 경고가 뜨면 token mismatch 쪽이 더 유력하다.

2) 지금 어느 host를 보고 있는지 적어놓고 본다

원격 장비가 여러 대일수록 이 단계가 중요하다. 특히 한 대는 항상 켜진 gateway host이고, 다른 한 대는 그냥 원격 제어 클라이언트라면 더 헷갈리기 쉽다.

여기서 체크할 건 단순하다.

지금 명령을 실행하는 머신은 어디인가
붙으려는 gateway host는 어디인가
터널/relay/remote 설정이 어느 장비를 향하는가

한 줄로 못 설명하면, 이미 대상 분리가 안 된 상태다.

3) 토큰이 진짜 같은 값을 보는지 확인

실무에서는 여기서 해결되는 경우가 많다. 에러 문구가

unauthorized: gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

처럼 나온다면, 해석은 거의 직설적이다. client가 들고 있는 remote token을 gateway의 auth token과 맞춰라는 뜻이다.

Configuration reference는 ~/.openclaw/openclaw.json의 설정 기준이 gateway 동작을 정한다는 점을 전제로 한다. 따라서 token mismatch가 난다면, 설정 파일과 실제 daemon/runtime이 어떤 값을 사용 중인지 함께 맞춰 봐야 한다.

4) 브라우저/툴 문제로 오해하지 말고 짧은 probe로 다시 본다

이 에러가 openclaw browser ...에서 먼저 보였더라도, 원인이 브라우저 자체라는 뜻은 아니다. 브라우저 툴도 결국 gateway 쪽 인증 경로를 타기 때문이다.

그래서 긴 명령 여러 개를 던지기보다, 짧게 상태를 재확인하는 편이 낫다.

openclaw gateway status
openclaw doctor

Help troubleshooting 문서도 doctor를 빠른 진단 계단에 넣고 있다. 즉, 인증/경로/서비스 상태를 짧게 다시 확인하는 용도로 적합하다.

현장 미니 사례 2개

사례 A) 맥북에서만 browser 명령이 계속 unauthorized

상황: 같은 OpenClaw인데 데스크톱에서는 되는데 맥북에서만 gateway token mismatch
원인: 맥북이 보고 있는 remote 설정의 token이 실제 gateway host의 token과 달랐음
해결: 대상 host와 token 기준을 다시 맞춘 뒤 openclaw gateway status로 짧게 재확인
포인트: 브라우저 장애가 아니라 remote 인증 경로 불일치였다

사례 B) 터널은 살아 있는데 아무 명령도 안 붙는 느낌

상황: SSH tunnel이나 relay는 살아 있는 것처럼 보이는데 계속 unauthorized
원인: 네트워크 연결 자체는 살아 있지만, auth 단계에서 막히는 상태
해결: 연결 생존 여부와 인증 성공 여부를 분리해서 보고, token mismatch를 먼저 해결
포인트: “터널 살아있음 = 붙을 수 있음”이 아니다

이렇게 보면 재발이 줄어든다

1. 무조건 재시작부터 하지 않는다

인증 불일치인데 재시작만 반복하면 원인 분리가 더 늦어진다. 먼저 status/probe 계단으로 분리하는 편이 훨씬 빠르다.

2. host, port, token을 항상 한 세트로 본다

이 셋 중 하나만 어긋나도 같은 증상이 나온다. 특히 원격 장비가 2대 이상이면 host 구분을 먼저 메모해 두는 습관이 좋다.

3. gateway 하나가 source of truth라는 점을 잊지 않는다

Remote access 문서는 하나의 gateway가 세션과 상태를 소유한다고 설명한다. 여러 장비를 오갈수록, “어느 gateway가 진짜 기준인지”를 먼저 정해야 진단이 덜 꼬인다.

복구 확인 체크리스트

아래 4개가 맞으면 대부분 복구된 상태다.

openclaw gateway status에서 runtime/probe가 정상으로 보인다.
같은 머신에서 짧은 gateway 명령이 2회 연속 정상 응답한다.
어느 host에 붙는지 한 줄로 설명할 수 있다.
브라우저/채널 문제로 번지기 전에 token mismatch 원인을 먼저 분리했다.

한 줄 결론

gateway token mismatch는 대개 gateway가 죽은 문제가 아니라, 원격 접속 경로의 host·port·token 중 하나가 어긋난 상태다.
status → gateway status → 대상 host 확인 → token 정렬 순서로 보면, 쓸데없는 재시작 없이 훨씬 빨리 복구된다.

같이 보면 좋은 문서

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

일하는 ai

탐색기