2026-07-13 기준 · OpenClaw 2026.7.1 안정 버전 기준 · 시리즈 2/3
결론부터: 이 에러의 가장 흔한 원인은 "게이트웨이가 이미 떠 있는데 또 띄운 것"입니다. 새로 시작하기 전에 openclaw gateway status 로 기존 프로세스를 먼저 확인하세요. 온보딩 때 자동 등록된 게이트웨이가 백그라운드에서 이미 포트를 잡고 있는 경우가 대부분이라, 이때는 고칠 것 없이 그냥 그 게이트웨이를 쓰면 됩니다.
증상
게이트웨이를 시작할 때 다음과 같은 메시지가 나옵니다:
Error: listen EADDRINUSE: address already in use 127.0.0.1:18789
또는:
another gateway instance is already listening
18789 는 오픈클로 게이트웨이의 기본 포트입니다. 2026년 4월 릴리스(2026.4.5)에서도 동일 증상이 이슈로 보고된 바 있는(GitHub #62276), 신규 사용자가 가장 자주 만나는 에러 중 하나입니다.
원인 (한 문장)
기본 포트 18789 를 이미 다른 프로세스 — 대부분은 온보딩 때 서비스로 등록된 기존 게이트웨이, 드물게는 업데이트 후 남은 옛 프로세스나 전혀 다른 프로그램 — 가 점유하고 있어서, 두 번째 게이트웨이가 같은 포트에 바인딩하지 못하는 것입니다.
해결 단계
1) 이미 떠 있는지부터 확인 (가장 흔한 케이스)
openclaw gateway status
이미 실행 중(running)이라면 끝 — 터미널에서 openclaw gateway 를 또 칠 필요가 없습니다. 대시보드는 openclaw dashboard 로 열면 됩니다.
2) 포트를 누가 잡고 있는지 확인 (macOS/Linux)
lsof -i :18789
macOS 에서 더 정확히 보려면:
lsof -nP -iTCP:18789 -sTCP:LISTEN
3) 남은 옛 프로세스·깨진 서비스 등록 정리
업데이트/재설치 후 옛 프로세스나 launchd(macOS)·systemd(Linux) 서비스 등록이 남아 충돌하는 경우:
openclaw doctor --fix
openclaw gateway restart
4) 포트 점유자가 다른 프로그램이라 양보가 필요하면 — 포트 변경
openclaw config set gateway.port 18790
openclaw gateway restart
5) 마무리 확인
openclaw gateway status
관련 보안 주의
포트를 바꾸더라도 바인딩은 반드시 루프백(127.0.0.1)을 유지하세요. "충돌 피하려고" 0.0.0.0 으로 열면 같은 네트워크의 누구든 내 게이트웨이에 노크할 수 있습니다. 지금 내 포트가 외부로 노출돼 있는지 확인하는 법과 토큰 인증·샌드박스 격리까지 포함한 7가지 점검은 오픈클로 보안 체크리스트 글에 정리돼 있습니다. 자가 점검은 openclaw security audit --deep 한 줄로도 가능합니다.
에러를 고쳤다면, 이제 일을 시킬 차례
포트 충돌까지 잡았다면 세팅의 고비는 넘겼습니다. 그다음 "에이전트에게 뭘 시켜야 돈과 시간이 절약되는가"는 AI 에이전트 강의에서 비개발자 기준으로 다룹니다. 1차시 무료 공개.
FAQ
Q. lsof 가 없다고 나옵니다 (Windows).
A. Windows 는 PowerShell 에서 netstat -ano | findstr 18789 로 점유 프로세스 PID 를 확인할 수 있습니다.
Q. 죽여도 죽여도 다시 살아나요.
A. 서비스(launchd/systemd)로 등록된 게이트웨이가 자동 재시작되는 정상 동작일 가능성이 큽니다. 프로세스를 직접 죽이지 말고 openclaw gateway status → 이미 있는 게이트웨이를 그대로 쓰거나, openclaw doctor --fix 로 등록 상태를 정리하세요.
Q. 게이트웨이 시작이 "blocked" 라는 메시지로 막혀요.
A. 그건 포트가 아니라 모드 설정 문제입니다 — 시리즈 1편(Gateway start blocked 해결법) 참고.
이 글은 2026-07-13 기준 OpenClaw 공식 트러블슈팅 문서(docs.openclaw.ai/gateway/troubleshooting)와 GitHub 이슈 #62276 을 교차 확인해 작성했습니다. 버전 업데이트로 명령·기본 포트가 바뀔 수 있으니 공식 문서를 함께 확인하세요.