2부·8장 자주 막히는 7가지 문제 해결

OpenClaw 설치가 어려운 이유는 당신이 초보라서가 아니다. 이 도구가 CLI, Gateway, 모델 제공자, 메신저 채널, 운영체제 서비스까지 한 줄로 엮여 돌아가기 때문이다. 한 군데만 어긋나도 겉보기 증상은 비슷하다. 명령어가 안 먹거나, 대시보드가 안 열리거나, 텔레그램 봇이 조용히 입을 다문다.

다행히도 패턴은 꽤 정직하다. 이 장에서는 초보자가 가장 자주 부딪히는 7가지 장애를, 당황하지 않고 하나씩 분해하는 법을 알려준다. 목표는 단순하다. 재설치를 열 번 반복하는 대신, 어디가 막혔는지 5분 안에 감을 잡는 것이다.

재설치 전에 먼저 하는 3단계

문제가 생기면 제일 먼저 기억할 것은 이것이다. OpenClaw의 CLI는 리모컨이고, 실제로 일을 하는 쪽은 Gateway다. 그래서 겉으로는 설치가 끝난 것처럼 보여도 Gateway가 죽어 있으면 아무 일도 일어나지 않는다. WSL2 환경에서는 특히 systemd가 켜져 있어야 데몬 설치가 제대로 작동한다.¹

처음 막혔을 때는 아래 순서만 지켜도 절반은 풀린다.

1. 현재 상태를 본다.

openclaw status --all
openclaw gateway status

2. 실시간 로그를 본다.

openclaw logs --follow

3. 자동 진단을 돌린다.

openclaw doctor

이 세 명령은 각각 다른 질문에 답한다. status는 살아 있느냐를, logs는 왜 실패했느냐를, doctor는 구조적으로 뭐가 틀어졌느냐를 보여준다. 이 순서를 몸에 익혀 두면, 설치 문제를 감정이 아니라 증거로 다루게 된다.

1. openclaw 명령어를 찾을 수 없을 때

가장 흔한 첫 번째 벽은 아주 단순하다. 분명 설치를 했는데 openclaw를 치면 command not found가 뜬다. 이때 많은 사람이 설치 자체가 실패했다고 생각하지만, 실제 원인은 대개 PATH다. OpenClaw가 설치된 npm 글로벌 실행 경로를 셸이 모르고 있는 것이다.²

먼저 설치 위치부터 확인하자.

npm prefix -g
which openclaw
echo $PATH

PowerShell이라면 이렇게 본다.

npm prefix -g
$env:Path

npm prefix -g로 나온 경로가 PATH 안에 없으면, 셸은 OpenClaw를 못 찾는다. Linux나 WSL2에서는 ~/.bashrc 또는 ~/.zshrc에 npm 글로벌 bin 경로를 추가하고 터미널을 다시 열면 된다.²

export PATH=$(npm prefix -g)/bin:$PATH

여기서 많이 헷갈리는 함정이 하나 있다. WSL2 안에서 설치한 OpenClaw는 WSL2 터미널에서만 바로 쓸 수 있다. Windows PowerShell의 PATH와 WSL2의 PATH는 따로 논다. 바닷가재가 사는 수조가 둘인데, 한쪽 수조에만 먹이를 넣은 셈이다.

2. Node 버전, nvm, sudo 때문에 설치가 꼬였을 때

두 번째 벽은 조금 더 교묘하다. 명령어는 보이는데 실행하면 이상한 오류가 나거나, 어떤 터미널에서는 되고 어떤 터미널에서는 안 된다. 이때는 Node.js 버전과 설치 방식부터 의심하는 게 빠르다. OpenClaw는 Node 22 이상이 사실상 기준선이다.²

먼저 버전을 확인한다.

node --version
npm --version

버전이 22 미만이면, 다른 문제를 보기 전에 먼저 올려야 한다. 특히 nvm을 쓰는 사람은 더 조심해야 한다. nvm은 Node 버전마다 글로벌 패키지 경로를 따로 갖기 때문에, 예전에 v18에서 설치한 OpenClaw가 v22로 넘어오면 갑자기 사라진 것처럼 보일 수 있다.²

이럴 때는 현재 활성화한 Node 22에서 다시 설치하면 된다.

nvm use 22
npm install -g openclaw@latest

또 하나의 흔한 함정은 sudo npm install -g다. 이 명령은 루트 계정 쪽 경로에 설치해 버려서, 일반 사용자 PATH와 엇갈리기 쉽다.² 처음엔 되는 것 같다가 나중에 업데이트나 권한 문제로 발목을 잡는다. 이미 그렇게 설치했다면 루트 쪽 버전을 지우고, 일반 사용자로 다시 설치하는 편이 덜 아프다.

한마디로 정리하면 이렇다. OpenClaw 설치가 이상하게 들쭉날쭉하면, 코드를 의심하기 전에 Node 버전과 설치 사용자를 의심하라.

3. 대시보드가 안 열리고 127.0.0.1:18789 연결 거부가 뜰 때

이 오류는 초보자가 가장 자주 포기하는 지점이다. 브라우저에 주소를 열었는데 연결 거부가 뜬다. 마치 모든 것이 망가진 느낌이지만, 실제로는 Gateway가 실행 중이 아니거나, 데몬으로 설치되지 않아 터미널을 닫으면서 같이 종료된 경우가 많다.

OpenClaw 공식 문서도 WSL2에서는 openclaw onboard --install-daemon 또는 openclaw gateway install로 Gateway 서비스를 설치하는 흐름을 권장한다.¹

우선 상태를 확인한다.

openclaw gateway status
openclaw status --all

실행 중이 아니라면 다음 순서로 복구한다.

openclaw onboard --install-daemon
openclaw gateway start
openclaw doctor

WSL2 사용자라면 여기서 한 번 더 확인할 것이 있다. systemd가 꺼져 있으면 데몬 설치가 제대로 굴러가지 않는다. 공식 가이드도 WSL 설정에서 systemd 활성화를 필수 단계로 다룬다.¹

systemctl --user status

이 명령이 제대로 반응하지 않는다면, 설치가 잘못된 게 아니라 운영체제 서비스 계층이 아직 준비되지 않은 것이다. 다시 말해 바닷가재는 멀쩡한데 수조 필터가 안 돌아가는 상황이다.

4. 포트 18789가 이미 사용 중일 때

Gateway가 시작되지 않으면서 address already in use나 EADDRINUSE가 보이면, 누군가 이미 18789 포트를 잡고 있다는 뜻이다. 가장 흔한 범인은 예전 OpenClaw 프로세스, 비정상 종료 후 남은 좀비 프로세스, 혹은 업데이트 중 꼬인 서비스다.

누가 포트를 잡고 있는지 먼저 찾는다.

lsof -nP -iTCP:18789 -sTCP:LISTEN

Linux에서는 아래도 자주 쓴다.

ss -tulpn | grep 18789

Windows에서는 이렇게 확인한다.

netstat -ano | findstr 18789

가능하면 먼저 점잖게 종료해 본다.

openclaw gateway stop
openclaw gateway restart

그래도 포트가 계속 붙잡혀 있으면 해당 PID를 종료해야 한다. 다만 무조건 강제 종료부터 하지 말고, 지금 떠 있는 프로세스가 진짜 OpenClaw인지부터 확인하는 습관이 좋다.

업데이트 직후라면 조금 더 특별한 상황일 수도 있다. 2026.3.13 무렵에는 gateway token mismatch, 포트 점유, 서비스 entrypoint 불일치가 함께 나타나는 회귀 사례가 보고되었다.⁴ 이런 경우는 프로세스 하나만 죽여서는 안 풀리고, 진단 후 서비스 재설치가 필요할 수 있다.

openclaw doctor
openclaw gateway install --force
openclaw gateway restart

중요한 것은 증상만 보고 포트를 바꾸는 습관을 들이지 않는 것이다. 포트 변경은 임시 우회로는 좋지만, 원인을 숨기기도 한다. 특히 첫 설치 단계에서는 왜 18789가 막혔는지를 확인하는 편이 다음 문제를 훨씬 덜 만든다.

5. WSL이나 원격 환경에서 대시보드 주소가 헷갈릴 때

127.0.0.1은 마법의 주소가 아니다. 언제나 지금 브라우저가 실행 중인 그 기계를 뜻한다. 이 단순한 사실 때문에 WSL, 원격 서버, 별도 노트북 접속에서 많은 사람이 미로에 빠진다.

예를 들어 OpenClaw는 WSL2 안에서 돌고 있는데, 다른 기기 브라우저에서 http://127.0.0.1:18789를 열었다면 그 요청은 WSL로 가지 않는다. 그 브라우저가 있는 기계 자신에게 간다. 공식 Windows 문서도 WSL은 자체 가상 네트워크를 쓰기 때문에, 다른 기기에서 접근하려면 도달 가능한 URL을 확인하고 필요하면 포트 포워딩을 구성하라고 설명한다.¹

이럴 때 가장 먼저 할 일은 감으로 주소를 찍지 않는 것이다.

openclaw status --all

여기서 Gateway가 실제로 어느 주소에 바인딩되어 있는지 본다. 다른 기기에서 접근해야 한다면, WSL의 현재 IP가 바뀌었는지도 확인해야 한다. WSL은 재시작 때 IP가 바뀔 수 있어서, 어제 되던 주소가 오늘 안 되는 일이 드물지 않다.¹

하지만 여기서 보안 감각도 같이 가져가야 한다. 초보 단계에서는 가능하면 loopback, 즉 로컬 바인딩을 유지하는 편이 안전하다. 외부에서 붙어야 한다면 일단 SSH 터널이나 Tailscale 같은 더 좁은 길을 쓰고, 포트를 인터넷에 그대로 드러내는 습관은 뒤로 미뤄도 된다.

6. API 인증 오류가 날 때

Gateway가 살아 있고 채널도 붙었는데 모델만 응답하지 않으면, 거의 언제나 인증이나 과금, 권한 문제다. 이 단계에서 제일 유용한 명령은 openclaw models status다. 공식 문서도 항상 켜 둘 Gateway 호스트에서는 OAuth보다 API 키 구성이 더 예측 가능하다고 권장한다.³

먼저 상태를 본다.

openclaw models status
openclaw status --all

그리고 API 키를 어디에 넣었는지도 확인한다. 대화형 온보딩에서 저장했을 수도 있고, 직접 ~/.openclaw/.env에 넣었을 수도 있다. 데몬으로 돌리는 환경에서는 이 .env 방식이 특히 안정적이다.³

cat ~/.openclaw/.env

오류는 보통 세 갈래로 나뉜다.

401은 키 자체가 틀렸거나, 다른 제공자의 키를 잘못 넣었거나, 복사 과정에서 공백이 섞인 경우다. 가장 단순하지만 가장 자주 나온다.

403은 계정 권한, 지역 제한, 또는 선택한 모델 접근 권한 문제인 경우가 많다. 키는 맞는데 그 모델을 쓸 자격이 없는 상황이다.

429는 실패가 아니라 과속 딱지다. 요청이 너무 많거나, 크레딧이 떨어졌거나, 플랜 한도를 넘은 것이다. 이때는 키를 다시 넣어도 해결되지 않는다. 잠깐 기다리거나, 결제 상태를 확인하거나, 더 가벼운 모델로 내려와야 한다.

키를 바꿨다면 꼭 Gateway를 다시 읽혀야 한다.

openclaw gateway restart
openclaw doctor

Anthropic을 예로 들면, 장기 운영에서는 API 키가 가장 예측 가능하고, 같은 호스트에서 Claude CLI 로그인을 재사용하는 방식도 지원된다.³ 중요한 것은 멋진 인증 방식이 아니라, 재부팅 뒤에도 안 흔들리는 인증 방식이다.

7. 텔레그램은 연결됐는데 답이 없거나, 로컬 모델만 유독 멍할 때

이 마지막 구간은 묘하게 사람을 지치게 한다. 설치도 됐고 봇도 보이는데, 말을 걸어도 반응이 없거나, 반응은 하는데 금붕어처럼 방금 한 말을 잊는다. 이때는 채널 문제와 모델 문제를 분리해서 봐야 한다.

먼저 텔레그램이 조용하다면 페어링부터 확인한다. OpenClaw는 기본적으로 낯선 DM을 막아 두는 경우가 많다. 그래서 봇 등록은 성공했는데 실제 대화는 승인 대기 상태일 수 있다.

openclaw pairing list all
openclaw pairing approve telegram 코드

이 단계가 빠지면 사용자는 봇이 고장 났다고 느끼고, 실제 원인은 보안 정책이다. 아주 흔한 오해다.

그다음은 로컬 모델이다. Ollama나 LM Studio를 붙였을 때 초반 성공률이 내려가는 가장 큰 이유는 성능이 아니라 기대치 mismatch다. 작은 로컬 모델은 긴 시스템 프롬프트, 긴 메모리, 여러 도구 호출이 한꺼번에 들어오면 쉽게 흐트러진다. 쉽게 말해 등산 가방이 작은데 짐을 너무 많이 넣은 셈이다.

증상은 대체로 비슷하다. 오래 걸린다. 앞 문맥을 잊는다. 한국어 요약이 갑자기 뭉개진다. 도구를 써야 할 상황인데 엉뚱하게 말로만 때운다. LM Studio에서는 컨텍스트 윈도우 설정이 너무 작으면 더 빨리 이런 현상이 나타난다.

이럴 때는 세 가지를 먼저 줄여 보자.

• 한 번에 시키는 일을 줄인다.

• 긴 대화 기록을 새 세션으로 끊는다.

• 첫 설치 검증 단계에서는 프런티어 API 모델로 먼저 성공 경로를 만든다.

처음부터 로컬 모델로 모든 걸 해내겠다는 마음은 멋지지만, 초반 진단에는 오히려 독이 된다. 설치 검증의 목적은 철학이 아니라 성공 경험이다. 먼저 되는 구성을 만들고, 그다음에 로컬화해도 늦지 않다.

60초 점검 체크리스트

마지막으로, 재설치 버튼을 누르기 전에 이 일곱 가지를 훑어보자.

• openclaw status --all에서 Gateway가 살아 있는가

• node --version이 22 이상인가

• openclaw가 현재 셸의 PATH에서 보이는가

• 18789 포트를 다른 프로세스가 잡고 있지 않은가

• WSL이나 원격 환경에서 127.0.0.1을 잘못 보고 있지 않은가

• openclaw models status에서 인증 오류나 429가 보이지 않는가

• 텔레그램 페어링 또는 로컬 모델 컨텍스트 한계를 놓치고 있지 않은가

OpenClaw 설치에서 가장 위험한 순간은 오류가 많은 순간이 아니라, 원인을 구분하지 못한 채 모든 걸 한 번에 갈아엎는 순간이다. 반대로 말하면, 문제를 층층이 나눠 보는 습관만 들어도 성공률은 눈에 띄게 올라간다. 그리고 그 순간부터 OpenClaw는 무서운 도구가 아니라, 다루는 맛이 있는 도구가 된다.

참고

¹Windows - OpenClaw

²OpenClaw 安装后 command not found：5 种场景逐一修复

³Authentication - OpenClaw

⁴Bug: Gateway Token Mismatch and Port Conflict in OpenClaw 2026.3.13