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

개발을 하다 보면 운영 중인 메인 봇이 멈췄을 때를 대비해 백업용 봇이 필요하거나, 서로 다른 작업을 완전히 분리해서 실행해야 할 때가 있습니다. 하지만 같은 환경에서 여러 인스턴스를 띄우다 보면 포트가 충돌하거나 설정 파일이 서로 덮어써지는 문제가 자주 발생하죠. 인스턴스끼리 자원을 공유하다가 설정값이 꼬여버리면 원인을 찾기도 쉽지 않습니다.

보통은 하나의 Gateway만으로도 여러 메시징 연결과 에이전트를 충분히 처리할 수 있습니다. 하지만 더 강력한 격리 환경이나 리던던시(예: 복구용 rescue bot)가 필요하다면, 프로필과 포트를 분리해 별도의 Gateway를 실행하는 것이 좋습니다.

필요한 것

• OpenClaw CLI
• 각 인스턴스에 할당할 고유한 포트 번호
• 격리된 설정 파일 및 상태 디렉토리

빠른 시작

가장 권장하는 방법은 --profile 옵션을 사용하는 거예요. 이 옵션을 쓰면 OPENCLAW_STATE_DIR와 OPENCLAW_CONFIG_PATH의 범위가 자동으로 지정되고 서비스 이름 뒤에 접미사가 붙어 관리가 편해집니다.

# 메인 인스턴스 설정
openclaw --profile main setup
openclaw --profile main gateway --port 18789

# 복구용(rescue) 인스턴스 설정
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001

각 프로필별로 서비스를 설치하려면 다음 명령어를 사용하세요.

openclaw --profile main gateway install
openclaw --profile rescue gateway install

Rescue-bot 설정 가이드

메인 봇이 다운되었을 때 디버깅을 하거나 설정을 변경하려면, 동일한 호스트에서 별도의 자원을 사용하는 두 번째 Gateway를 실행해야 합니다. 이때 다음 항목들이 반드시 격리되어야 합니다.

• 프로필 및 설정 파일
• 상태 디렉토리(state dir)
• 워크스페이스(workspace)
• 베이스 포트 및 파생 포트

포트를 설정할 때는 베이스 포트 사이에 최소 20개 이상의 여유를 두세요. 그래야 브라우저, Canvas, CDP 등 파생 포트들이 서로 충돌하지 않습니다.

복구용 봇 설치 방법

# 메인 봇 (기존 설치 또는 신규 설치)
# 18789 포트와 관련 포트들을 사용합니다.
openclaw onboard
openclaw gateway install

# 복구용 봇 (격리된 프로필과 포트 사용)
openclaw --profile rescue onboard
# 참고:
# - 워크스페이스 이름 뒤에 기본적으로 -rescue가 붙습니다.
# - 포트는 메인 포트(18789)보다 최소 20개 이상 높게 설정하세요.
# - 19789처럼 완전히 다른 베이스 포트를 선택하는 것이 더 좋습니다.

# 서비스 설치 (onboarding 과정에서 자동 설치되지 않은 경우)
openclaw --profile rescue gateway install

Port mapping 상세

베이스 포트는 gateway.port 또는 --port 옵션으로 결정됩니다. 이를 기준으로 다른 서비스 포트들이 자동으로 할당됩니다.

• browser control service port: 베이스 포트 + 2 (루프백 전용)
• canvasHost.port: 베이스 포트 + 4
• CDP ports: browser.controlPort + 9부터 + 108까지 자동 할당

설정 파일이나 환경 변수에서 이 값들을 직접 수정한다면, 인스턴스마다 값이 겹치지 않도록 주의해야 합니다.

문제 해결

설정 충돌 및 포트 오류

여러 인스턴스를 실행할 때 다음 항목이 공유되고 있지는 않은지 확인해 보세요. 하나라도 겹치면 설정 경합(race)이나 포트 충돌이 발생합니다.

• OPENCLAW_CONFIG_PATH: 인스턴스별 설정 파일
• OPENCLAW_STATE_DIR: 세션, 인증 정보, 캐시 저장소
• agents.defaults.workspace: 워크스페이스 루트
• gateway.port: 고유한 베이스 포트

브라우저 및 CDP 관련 문제

• 여러 인스턴스에서 browser.cdpUrl을 동일한 값으로 고정하지 마세요.
• 각 인스턴스는 베이스 포트에서 파생된 고유한 브라우저 컨트롤 포트와 CDP 범위를 가져야 합니다.
• 특정 CDP 포트가 꼭 필요하다면 인스턴스별로 browser.profiles.<name>.cdpPort를 설정하세요.
• 원격 크롬을 사용한다면 인스턴스 및 프로필별로 browser.profiles.<name>.cdpUrl을 지정해야 합니다.

상태 확인하기

설치가 완료되었다면 다음 명령어로 각 인스턴스의 상태를 확인할 수 있습니다.

openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status

더 자세한 설정 방법이나 도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Gateway Configuration Deep Dive
• Managing Multiple Agent Profiles