Gateway 실행 및 운영 가이드

새로운 백그라운드 서비스를 설정하다 보면 예상치 못한 포트 충돌이나 설정 오류로 시간을 허비할 때가 많아요. 특히 서비스가 제대로 돌고 있는지, 왜 연결이 안 되는지 파악하기 어려우면 개발 흐름이 끊기기 마련이죠.

이 가이드는 Gateway 서비스를 처음 실행하는 ‘Day-1’ 단계부터 안정적으로 운영하는 ‘Day-2’ 단계까지 필요한 핵심 정보를 담고 있습니다. 복잡한 절차 없이 바로 따라 할 수 있도록 정리했어요.

필요한 것

시작하기 전에 다음 사항을 확인해 주세요.

• OpenClaw CLI 설치 완료
• 터미널 환경 (macOS 또는 Linux)

Quick Start: 5분 안에 로컬에서 시작하기

가장 빠른 경로로 Gateway를 띄우고 상태를 확인해 보겠습니다.

Step 1: Gateway 시작

기본 포트 또는 특정 옵션을 사용해 서비스를 실행합니다.

# 기본 포트(18789)로 실행
openclaw gateway --port 18789

# 디버그/트레이스 로그를 터미널에 함께 출력
openclaw gateway --port 18789 --verbose

# 선택한 포트의 리스너를 강제 종료 후 시작
openclaw gateway --force

Step 2: 서비스 상태 확인

서비스가 정상적으로 올라왔는지 체크합니다.

openclaw gateway status
openclaw status
openclaw logs --follow

정상적인 상태라면 Runtime: running과 RPC probe: ok 메시지가 표시됩니다.

Step 3: 채널 준비 확인

채널이 활성화되었는지 최종적으로 검증합니다.

openclaw channels status --probe

참고: Gateway 설정 리로드는 활성 설정 파일 경로를 감시합니다. 기본 모드는 gateway.reload.mode="hybrid"입니다.

Runtime model

Gateway는 라우팅, Control Plane, 채널 연결을 위해 항상 켜져 있는 단일 프로세스입니다. 하나의 멀티플렉싱된 포트를 통해 다음 기능을 모두 처리해요.

• WebSocket 제어 및 RPC
• HTTP API (OpenAI 호환, Responses, tools invoke)
• 제어 UI 및 Hook

기본 Bind mode는 loopback이며, 보안을 위해 gateway.auth.token 또는 gateway.auth.password를 통한 인증이 기본적으로 필요합니다.

포트 및 바인딩 우선순위

설정값이 겹칠 때는 아래 순서대로 적용됩니다.

• Gateway port: --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
• Bind mode: CLI/override → gateway.bind → loopback

Hot reload 모드

gateway.reload.mode 설정에 따라 동작이 달라집니다.

• off: 설정을 다시 불러오지 않음
• hot: 안전한 변경 사항만 즉시 적용
• restart: 재시작이 필요한 변경 시 프로세스 재시작
• hybrid (기본값): 안전하면 Hot-apply, 필요하면 재시작

운영 명령어 모음

운영 중에 자주 사용하는 명령어들입니다.

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw logs --follow
openclaw doctor

Remote access

원격 접속 시에는 Tailscale이나 VPN을 사용하는 것이 가장 좋습니다. 여의치 않다면 SSH tunnel을 활용하세요.

ssh -N -L 18789:127.0.0.1:18789 user@host

그다음 로컬에서 ws://127.0.0.1:18789로 접속하면 됩니다.

주의: SSH tunnel을 사용하더라도 Gateway 인증이 설정되어 있다면 클라이언트는 반드시 token이나 password를 보내야 합니다.

서비스 수명 주기 관리 (Supervision)

프로덕션 환경과 같은 안정성을 위해 OS별 서비스 관리 도구를 사용하세요.

macOS (launchd)

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw doctor를 실행하면 서비스 설정의 오차를 점검하고 복구할 수 있습니다.

Linux (systemd user)

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

로그아웃 후에도 프로세스를 유지하려면 sudo loginctl enable-linger <user> 명령어를 실행해 주세요.

한 호스트에서 여러 Gateway 실행하기

대부분의 경우 하나의 Gateway만 실행하는 것이 권장되지만, 격리가 필요한 경우 여러 인스턴스를 띄울 수 있습니다. 이때 각 인스턴스는 다음 항목들이 고유해야 합니다.

• gateway.port
• OPENCLAW_CONFIG_PATH
• OPENCLAW_STATE_DIR
• agents.defaults.workspace

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

Troubleshooting: 자주 발생하는 문제

문제가 생겼을 때 로그에 나타나는 주요 사인과 해결 방법입니다.

로그 메시지 (Signature)	예상 원인
refusing to bind gateway ... without auth	인증 토큰 없이 외부 바인딩 시도
another gateway instance is already listening	포트 충돌 (이미 사용 중)
Gateway start blocked: set gateway.mode=local	설정이 remote 모드로 되어 있음
unauthorized (접속 시)	클라이언트와 Gateway 간 인증 정보 불일치

더 자세한 진단이 필요하다면 Gateway Troubleshooting 문서를 확인해 보세요.

---

도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

What’s Next:

• Troubleshooting
• Configuration
• Health
• Authentication