OpenClaw macOS Web UI 토큰 오류 해결법 (unauthorized / token mismatch)
OpenClaw 업데이트나 설정 변경 후 Web UI가 계속 끊기는 문제가 있었다. macOS launchd 서비스와 Control UI의 Gateway Token이 어긋나면 발생하는 증상이다. 이 글에서는 토큰을 찾아 두 곳에 동일하게 맞추는 방법을 순서대로 정리한다.
증상#
설치/업데이트 후 Dashboard URL은 뜨지만 Web UI가 안 열리거나, 열려도 계속 끊긴다.
disconnected (1008): unauthorized: device token mismatch (rotate/reissue device token)
disconnected (1008): unauthorized: gateway token missing (open the dashboard URL and paste the token in Control UI settings)
Cron failed: gateway closed (1008): unauthorized: device token mismatch
openclaw gateway restart가 성공 메시지를 띄워도 Web UI 에러가 사라지지 않는다면 토큰 불일치가 원인이다.
왜 이런 문제가 생기나#
OpenClaw가 업데이트·설정 변경·doctor fix 실행 등의 특정 상황에서 Gateway Token을 새로 생성/회전(rotate) 시킨다.
이때 launchd 서비스 파일(LaunchAgent plist) 또는 Control UI 설정이 변경을 따라가지 못하면 인증이 깨진다.
- 게이트웨이는 정상 실행 중 (포트 LISTEN)
- UI는 "토큰이 없거나 틀리다"고 판단해서 연결을 끊음
단계별 해결 방법#
1단계 — 게이트웨이가 실제로 떠있는지 확인#
lsof -nP -iTCP:18789 -sTCP:LISTEN
아래처럼 IPv4/IPv6 두 줄이 보이면 게이트웨이 프로세스는 살아있는 것이다.
node ... TCP 127.0.0.1:18789 (LISTEN)
node ... TCP [::1]:18789 (LISTEN)
2단계 — launchd 서비스 방식으로 통일#
openclaw gateway start/stop을 쳤을 때 "service not loaded"가 나오면서도 포트가 열려 있다면,
launchd 서비스와 수동 실행이 혼재하는 상태다.
서비스 방식(LaunchAgent) 하나로 통일하는 것이 가장 깔끔하다.
# 이미 떠있는 프로세스가 있다면 PID로 종료
kill <PID>
# 안 꺼지면
kill -9 <PID>
# launchd 방식으로 재로드
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
3단계 — openclaw.json에서 Gateway Token 찾기#
올바른 Gateway Token은 ~/.openclaw/openclaw.json에 저장돼 있다.
키 이름이 대소문자·camelCase로 다를 수 있으니 아래처럼 넓게 검색한다.
head -n 30 ~/.openclaw/openclaw.json
grep -ni "token" ~/.openclaw/openclaw.json
grep -ni "gateway" ~/.openclaw/openclaw.json
팁:
~/.openclaw폴더가 Finder에 보이지 않는다면 ⌘ + Shift + . 를 눌러 숨김 파일을 표시하거나, Finder → 이동 → 폴더로 이동(~/.openclaw)을 사용한다.
4단계 — launchd plist에 토큰 반영#
LaunchAgent plist를 열고 OPENCLAW_GATEWAY_TOKEN 값을 3단계에서 찾은 토큰으로 수정한다.
nano ~/Library/LaunchAgents/ai.openclaw.gateway.plist
- 저장:
Ctrl + O→ Enter - 종료:
Ctrl + X
수정 후 서비스를 재로드한다.
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
5단계 — Control UI에 Gateway Token 붙여넣기#
Dashboard의 Control UI → Settings 화면에서 아래 값을 입력하고 Connect를 누른다.
| 항목 | 값 |
|---|---|
| WebSocket URL | ws://127.0.0.1:18789 |
| Gateway Token | (3단계에서 찾은 값) |
주의: 여기에는 "디바이스 토큰"이 아니라 Gateway Token(OPENCLAW_GATEWAY_TOKEN) 을 넣어야 한다.
6단계 — 정상 동작 확인#
openclaw gateway status
RPC probe가 ok로 나오고 Web UI가 정상 동작하면 완료다.
트러블슈팅 / FAQ#
Q. kill <PID> 후에도 포트가 계속 열려있어요.
A. kill -9 <PID>로 강제 종료한 뒤 launchctl bootstrap으로 새로 띄운다.
Q. openclaw.json에서 gateway 관련 키를 못 찾겠어요.
A. cat ~/.openclaw/openclaw.json | python3 -m json.tool로 전체 구조를 보기 좋게 출력한다. gateway 블록 안의 token 필드를 찾는다.
Q. plist를 수정했는데 launchctl load가 실패해요.
A. XML 문법 오류일 수 있다. plutil -lint ~/Library/LaunchAgents/ai.openclaw.gateway.plist로 검증 후 수정한다.
Q. 업데이트마다 반복해야 하나요?
A. OpenClaw가 토큰을 자동 회전시키는 버전이라면 반복될 수 있다. 업데이트 후 Web UI가 끊기면 3~5단계만 다시 진행한다.
다음 단계#
OpenClaw 최초 설치부터 Dashboard/텔레그램 연동까지의 전체 과정은 OpenClaw macOS 설치 방법 (텔레그램 연동 + Dashboard)에서 확인할 수 있다.
공식 문서 및 이슈 트래커: OpenClaw GitHub