문제 설명
OpenClaw 게이트웨이를 시작할 때 포트가 점유되었다는 오류가 발생합니다:
[openclaw:server] Error: listen EADDRINUSE: address already in use :::3000
at Server.setupListenHandle [as _listen2] (node:net:1817:16)
at listenInCluster (node:net:1865:12)
at Server.listen (node:net:1964:7)
또는 시작 후 관리 패널에 접속할 수 없습니다:
[openclaw:server] Server started on port 3000
$ curl http://localhost:3000/health
curl: (7) Failed to connect to localhost port 3000: Connection refused
OpenClaw은 기본적으로 포트 3000에서 HTTP 게이트웨이 서비스를 시작하며, Webhook 콜백 수신, 관리 패널 제공, REST API를 위해 사용합니다. 해당 포트가 이미 다른 프로그램에 의해 점유되어 있으면 OpenClaw을 시작할 수 없습니다.
진단 단계
포트 점유 상태 확인
Linux / macOS:
lsof -i :3000
출력 예시:
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 12345 user 22u IPv6 123456 0t0 TCP *:3000 (LISTEN)
또는 ss 명령 사용:
ss -tlnp | grep 3000
Windows:
netstat -ano | findstr :3000
출력 예시:
TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 12345
PID로 포트를 점유하고 있는 프로세스를 찾습니다:
tasklist /FI "PID eq 12345"
잔류 OpenClaw 인스턴스 확인
ps aux | grep openclaw
이전에 제대로 종료되지 않은 오래된 OpenClaw 프로세스가 실행 중인 경우가 있습니다.
OpenClaw 설정 포트 확인
cat ~/.openclaw/openclaw.json | grep port
설정 파일에 설정된 포트 번호를 확인합니다.
해결 방법
방법 1: 포트를 점유하는 프로세스 중지
포트가 이전 OpenClaw 인스턴스에 의해 점유된 경우:
openclaw stop
stop 명령이 작동하지 않으면 프로세스를 강제 종료합니다:
Linux / macOS:
# 3000 포트를 점유하는 프로세스 찾아서 종료
kill $(lsof -t -i :3000)
# 일반 kill이 작동하지 않으면
kill -9 $(lsof -t -i :3000)
Windows:
# PID 찾기
netstat -ano | findstr :3000
# 프로세스 종료 (PID 교체)
taskkill /PID 12345 /F
프로세스 종료 후 OpenClaw을 다시 시작합니다:
openclaw start
방법 2: OpenClaw 포트 변경
3000 포트가 다른 중요한 서비스(예: React 개발 서버)에 의해 점유된 경우, OpenClaw의 포트 설정을 변경합니다:
커맨드 라인 매개변수로 포트 지정:
openclaw start --port 3001
또는 설정 파일 ~/.openclaw/openclaw.json 수정:
{
"server": {
"port": 3001,
"host": "0.0.0.0"
}
}
환경 변수로도 설정 가능:
OPENCLAW_PORT=3001 openclaw start
주의: Webhook 방식으로 메시지를 수신하는 경우(예: Telegram Webhook), 포트 변경 후 Webhook URL의 포트 번호도 함께 업데이트해야 합니다.
방법 3: 방화벽 차단 해결
포트가 다른 프로그램에 의해 점유되지 않았지만 여전히 연결할 수 없다면 방화벽이 연결을 차단하고 있을 수 있습니다.
Linux (ufw):
sudo ufw allow 3000/tcp
sudo ufw status
Linux (firewalld):
sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload
Windows:
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -Port 3000 -Protocol TCP -Action Allow
방법 4: 리버스 프록시 설정
프로덕션 환경에서는 Nginx 또는 Caddy를 리버스 프록시로 사용하여 OpenClaw은 로컬 포트에서 리스닝하고, 리버스 프록시를 통해 표준 80/443 포트를 외부에 노출하는 것이 좋습니다:
Nginx 설정 예시:
server {
listen 80;
server_name bot.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 지원
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
Caddy 설정 예시 (자동 HTTPS):
bot.example.com {
reverse_proxy localhost:3000
}
리버스 프록시 사용 후 OpenClaw은 127.0.0.1:3000(로컬에서만 접속)에서 리스닝할 수 있어 보안성이 높아집니다:
{
"server": {
"port": 3000,
"host": "127.0.0.1"
}
}
방법 5: Unix Socket 사용 (Linux/macOS)
포트 충돌이 반복적으로 발생하는 경우 OpenClaw이 TCP 포트 대신 Unix Socket을 사용하도록 할 수 있습니다:
{
"server": {
"socket": "/tmp/openclaw.sock"
}
}
Nginx 설정에서 해당 부분을 수정합니다:
location / {
proxy_pass http://unix:/tmp/openclaw.sock;
}
이렇게 하면 포트 충돌 가능성을 완전히 방지할 수 있습니다.
수정 확인
시작 후 서비스가 정상적으로 실행 중인지 확인합니다:
openclaw start
# 서비스 상태 확인
curl http://localhost:3000/health
# 예상 출력
# {"status":"ok","version":"x.x.x","uptime":5}
포트를 변경한 경우 명령의 3000을 새 포트 번호로 교체합니다. 관리 패널에 정상적으로 접속할 수 있는지 확인합니다: 브라우저에서 http://localhost:3000(또는 설정한 포트)을 엽니다.