콘텐츠로 이동
이 페이지는 더 이상 업데이트되지 않습니다. 최신 내용은 OpenClaw 공식 문서에서 확인하세요 →

OpenClaw 게이트웨이 원격 설정 및 포트 구성 가이드

서버를 원격으로 관리하다 보면 포트가 꼬이거나 접속이 안 돼서 답답할 때가 많죠. 특히 Gateway 설정이 제대로 안 되면 로컬에서는 잘 되던 게 외부에서는 먹통이 되기도 합니다.

오늘은 Gateway 포트 관리와 Remote 모드 설정에 대해 꼭 필요한 내용만 정리해 드릴게요. 설정을 제대로 이해하면 원격 환경에서도 훨씬 안정적으로 서비스를 운영할 수 있어요.

PortUse
18789HTTP/WS (main port)
18790gRPC (internal RPC)

Remote 모드에서는 Control UI와 Gateway WebSocket 모두 18789 포트(또는 사용자가 직접 변경한 포트)를 사용해요.

Gateway가 이미 실행 중이라고 뜨는 이유는 무엇인가요?

섹션 제목: “Gateway가 이미 실행 중이라고 뜨는 이유는 무엇인가요?”

다른 프로세스나 이전에 제대로 종료되지 않은 프로세스가 18789 또는 18790 포트를 이미 점유하고 있기 때문이에요.

Terminal window
# Check if the daemon is alive
openclaw gateway status
# Stop the service
openclaw gateway stop
# If you forcibly need the port
lsof -i :18789
kill -9 <pid>

Remote 모드에서 CLI를 어떻게 사용하나요?

섹션 제목: “Remote 모드에서 CLI를 어떻게 사용하나요?”

CLI 명령어에 --remote <gateway-url>을 추가하거나, OPENCLAW_GATEWAY_URL 환경 변수 또는 설정 옵션을 지정하면 돼요.

예시:

Terminal window
openclaw status --remote http://my-vps-tailnet:18789

만약 Gateway가 토큰 인증을 사용하고 있다면, OPENCLAW_GATEWAY_TOKEN을 설정하거나 --token 플래그를 함께 사용해 주세요.

Gateway를 Tailnet 주소에 바인딩할 수 있나요?

섹션 제목: “Gateway를 Tailnet 주소에 바인딩할 수 있나요?”

네, 가능해요. gateway.bind: "tailnet"으로 설정하면 OpenClaw가 Tailscale의 100.x.x.x 주소를 자동으로 찾아 바인딩해 줍니다. 이 기능을 쓸 때는 gateway.auth 설정도 반드시 함께 해주어야 해요.

만약 Tailscale이 실행 중이지 않거나 할당된 IP가 없다면 Gateway가 시작되지 않아요. 보통 다음과 같은 에러 메시지가 출력됩니다.

Failed to bind to tailnet: no Tailscale IP found

해결 방법:

  • 해당 호스트에서 Tailscale을 실행해서 100.x 주소를 할당받으세요.
  • 또는 gateway.bind 설정을 "loopback"이나 "lan"으로 변경하세요.

같은 호스트에서 여러 개의 Gateway를 실행할 수 있나요?

섹션 제목: “같은 호스트에서 여러 개의 Gateway를 실행할 수 있나요?”

일반적으로는 권장하지 않아요. 하나의 Gateway만으로도 여러 개의 메시징 채널과 에이전트를 충분히 관리할 수 있거든요. 복구용 봇을 운영하거나 물리적인 격리가 반드시 필요한 경우에만 여러 Gateway를 사용하세요.

꼭 여러 개를 실행해야 한다면 다음 항목들을 각각 다르게 설정해서 격리해야 합니다.

  • 각 Gateway별 서로 다른 포트
  • 서로 다른 상태 디렉토리 (OPENCLAW_STATE_DIR)
  • 서로 다른 서비스 이름 (커스텀 unit 파일 사용)
  • 설정 충돌을 피하기 위한 서로 다른 자격 증명(credential) 경로

원격 관리(non-loopback)를 어떻게 활성화하나요?

섹션 제목: “원격 관리(non-loopback)를 어떻게 활성화하나요?”

Loopback이 아닌 주소에 바인딩할 때는 보안을 위해 인증 설정이 필수예요. gateway.bind와 gateway.auth를 다음과 같이 설정해 보세요.

{
gateway: {
bind: "lan", // or "tailnet" for Tailscale-only
port: 18789,
auth: {
mode: "token",
token: "replace-me-with-a-strong-token"
}
}
}

다른 방법으로는 Tailscale Serve를 활용할 수도 있어요.

Terminal window
openclaw gateway --tailscale serve

Gateway는 리스닝 중인데 Control UI가 로드되지 않는 이유는 무엇인가요?

섹션 제목: “Gateway는 리스닝 중인데 Control UI가 로드되지 않는 이유는 무엇인가요?”

다음 사항들을 다시 한번 체크해 보세요.

  • http:// 프로토콜을 사용 중인지, 호스트네임과 포트가 정확한지 확인하세요.
  • 브라우저에서 해당 주소에 실제로 접근 가능한지 확인하세요. (방화벽, Tailscale, VPN 연결 상태 등)
  • Gateway 인증이 설정되어 있다면 정확한 토큰을 입력했는지 확인하세요.

먼저 Gateway 호스트에서 openclaw gateway status를 실행해 서비스가 살아있는지 확인해 보세요. 서비스가 실행 중이라면 health 엔드포인트에 직접 curl을 날려보는 것이 가장 확실해요.

Terminal window
curl http://localhost:18789/health

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요!

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.