Gateway를 VPS 또는 클라우드 Mac에서 안정적으로 돌리고 있지만 노트북에서 openclaw를 실행하면 도구가 켜지지 않거나 RPC 프로브 실패가 나오고 서버 로그는 유독 조용한 상황을 다룹니다. OpenClaw를 프로덕션 게이트웨이로 쓰는 팀을 위한 글입니다. 먼저 일곱 가지 체크로 gateway.mode=remote와 Tailscale 노출, SSH 포트 포워딩을 분리합니다. 이어 네 줄 표로 프로세스 위치, 클라이언트 기본 대상, TLS, 토큰 검증을 정렬합니다. 그다음 6단계 인수인계 Runbook(원격 URL, wss, 양쪽 gateway status, gateway install --force, doctor, 헬스 프로브)을 제시하고 사이트 내 Tailscale 비공개 노출, 크로스플랫폼 설치 분기, gateway closed(1000) 글과 역할을 나눕니다.
공식 FAQ의 local / remote 설명은 짧지만, 운영에서는 프로브 URL과 실제 리스너가 어긋나는 경우와 systemd 사용자 유닛과 대화형 셸 설정이 갈라지는 경우에 시간이 탑니다. 아래 7가지로 논의를 ping은 된다에서 서명 가능한 인수 기준표로 모읍니다.
원격 모드를 SSH 포트 포워딩의 별칭으로 보는 경우: SSH -L은 브라우저에서 UI로 가는 경로만 정리하고, 원격 모드는 CLI의 기본 프로브 대상을 바꿉니다. 겹쳐 쓸 수 있지만 의미는 다릅니다.
Tailscale Serve를 remote mode와 동일시:Tailscale은 로컬 Gateway를 tailnet에서 도달 가능하게 합니다. remote mode는 노트북 CLI가 다른 호스트의 Gateway에 붙습니다. 경계 표는 Tailscale 글을 보세요.
gateway.remote.url만 바꾸고 gateway.mode를 잊는 경우: mode가 local이면 CLI는 빈 로컬 포트를 계속 프로브해 이유 없는 타임아웃이 납니다.
http와 wss 혼용:리버스 프록시가 TLS를 종료하는데 클라이언트 URL과 trusted-proxy 설명이 어긋나면 401이나 재연결 폭풍이 납니다. 하드닝 체크리스트와 함께 검토하세요.
Config (cli) / Config (service) 두 줄 무시:업그레이드 후 root로 파일을 고쳤는데 서비스는 --profile dev의 다른 state 디렉터리에서 도는 전형적 패턴입니다.
토큰을 한쪽에만 기록:Gateway에서 gateway.auth.token을 돌렸는데 노트 Control UI가 옛값을 캐시합니다. 토큰 표는 gateway closed(1000)과 함께 읽으세요.
최소 원격 수락 시나리오 없음:채팅만 테스트하고 도구 체인을 안 보면 모델 업그레이드 뒤에야 RPC 스코프 드리프트가 드러납니다. 읽기 전용 명령을 카나리아로 고정하세요.
공통 원인은 OpenClaw를 단일 웹앱이 아니라 로컬 감독 프로세스와 원격 세션 라우팅을 가진 이단 시스템으로 보지 않는 것입니다. 플랫폼 엔지니어링은 kubeconfig 맥락과 같이 개발 머신마다 프로필, state 디렉터리, 원격 URL, 로테이션 시각을 감사 가능하게 남겨야 합니다.
크로스플랫폼 설치 분기와 함께: 첫 설치에서 openclaw doctor가 통과하지 않았는데 remote로 급히 가면 티켓마다 깨진 설치와 잘못된 인스턴스가 섞입니다.
2026년에 Gateway는 클라우드, IDE는 로컬을 표준화한다면 오프라인 시 성능 저하(디그레이데이션)를 문서화하세요. CLI를 읽기 전용으로 떨어뜨릴지, 암묵적 mode 전환을 금지해 프로덕션 오연결을 막을지 정합니다.
전용 원격 Mac 토폴로지에서는 Gateway를 Linux VPS에 두고 도구 실행을 임대 macOS에 두는 패턴이 흔합니다. remote URL은 여전히 VPS를 가리킵니다. Mac으로 SSH하는 주소를 Gateway URL로 붙여 넣지 마세요. 그 Mac에서 두 번째 Gateway를 실제로 띄우는 경우가 아니라면요.
기업 프록시가 장수명 WebSocket을 유휴 끊으면 간헐 끊김이 증폭됩니다. Runbook에 하트비트·재연결·클라이언트 캐시 정리를 적고 모델이 둔해졌다는 오해를 줄이세요.
리뷰에서는 프로세스가 어디서 돌고 클라이언트 기본 연결이 어디로 가는지로 나누면 보안과 운영 책임이 빨리 맞춰집니다.
| 모드 | Gateway 위치 | 전형적 클라이언트 | 주요 리스크 |
|---|---|---|---|
| local(기본) | 이 머신 | 로컬 CLI / UI | 로컬 포트, 토큰, 개인 세션 뒤엉킴 |
| remote | 원격 호스트 | 로컬 CLI / UI가 wss://…를 향함 | URL 드리프트, 이중 설정, 프록시 끊김 |
| Tailscale / 터널 노출 | 여전히 대상 호스트 루프백 또는 바인딩 | tailnet 또는 터널 경로 뒤의 브라우저 / CLI | ACL, MagicDNS, 토큰과 bind 조합 |
| SSH 로컬 포워드 | 대상 호스트 | 원격 포트를 노트북 127.0.0.1에 매핑 | 세션 수명, 점프 호스트 권한, remote URL 연결 오류 |
원격 모드가 고치는 것은 컨트롤 플레인이 가리키는 곳입니다. 같은 CLI가 노트북에서 다른 머신의 감독자와 도구 레지스트리에 안정적으로 말합니다. TLS나 토큰 모델을 대체하지는 않습니다.
데이터센터나 VPS에서 Gateway를 상시 가동하고 엔지니어에게는 가벼운 CLI만 들게 하려면 remote가 합리적 기본값입니다. UI에 제로트러스트로 닿아야 하면 원격 호스트에 Tailscale Serve를 얹고 두 관심사를 한 스위치로 합치지 마세요.
RPC / 1000 분기 글과 함께: 원격 모드에서는 스코프와 도구 허용 목록을 논하기 전에 현재 CLI 세션이 실제로 어느 Gateway 인스턴스에 붙었는지 확인하세요. 잘못된 호스트만 계속 고치는 일을 줄입니다.
순서는 원격을 먼저 검증하고, 클라이언트 mode를 바꾼 뒤, 카나리아 명령을 실행합니다. 상류 트러블슈팅 권장 순서와 같습니다.
원격에서 서비스 사용자로:openclaw gateway status를 실행해 Runtime: running과 RPC 프로브가 정상인지 확인합니다.
원격 WebSocket URL과 TLS 종료 지점 기록:리버스 프록시가 있으면 경로 접두사와 헬스 URL을 문서화해 손으로 path를 한 단계 더 쓰지 않게 합니다.
노트북에서 현재 프로필 스냅샷:openclaw.json 또는 동등한 state 경로를 백업해 local로 한 번에 되돌릴 수 있게 합니다.
gateway.mode=remote와 gateway.remote.url 설정:공식 openclaw config set 경로나 통제된 템플릿을 쓰고 여기저기 손수정을 금지합니다.
openclaw status / openclaw health 실행:프로브 대상과 지연을 확인하고 이중 설정이 갈라지면 다음 단계로 갑니다.
서비스와 같은 컨텍스트에서 openclaw gateway install --force 후 openclaw gateway restart:실제로 로컬 서비스를 유지할 때만. 순수 원격 클라이언트는 install을 생략하고 doctor로 드리프트를 없앱니다.
openclaw config set gateway.mode remote openclaw config set gateway.remote.url "wss://gateway.example.internal/v1/ws" openclaw config get gateway.mode openclaw config get gateway.remote.url openclaw status openclaw doctor
팁:원격에서 Tailscale Serve도 켜져 있으면 Tailscale 비공개 노출의 ACL·토큰 절에서 wss 종단과 내부 DNS가 맞는지 확인하세요.
롤백은 변경 티켓에 적습니다. 옛 local 설정 스냅샷과 전환 시간대를 남기고, 대형 업그레이드 날에는 원격 URL을 동결한 뒤 원격 카나리아가 통과할 때까지 클라이언트 설정 일괄 푸시를 미룹니다.
staging/prod 등 여러 프로필이면 셸 시작 스크립트에 현재 OPENCLAW_PROFILE을 출력해 staging인 줄 알고 prod에 붙는 실수를 줄입니다.
증상을 클라이언트·게이트웨이·프록시 층에 매핑하면 쓸데없는 재시작이 줄어듭니다.
401 / unauthorized:Control UI와 CLI 토큰을 같은 출처로 맞춥니다. 원격 모드에서는 노트북이 오래된 디바이스 토큰을 캐시하는 경우가 많으니 공식 디바이스 목록 로테이션 또는 재인가 흐름을 따르세요.
Runtime running이지만 RPC probe failed:먼저 gateway closed(1000)로 잘못된 인스턴스와 맞는 인스턴스지만 스코프 부족을 가르고, 같은 시간 창에 원격 호스트에서 openclaw logs --follow를 잡습니다.
주의:원격 리스너를 모르는 채 노트북에서 gateway restart를 연타하지 마세요. 로컬 유휴 프로세스만 돌고 분기 로그만 오염됩니다.
어제까지 됐는데(업그레이드 후):릴리스 노트에서 기본 인증 강화나 WebSocket path 변경이 없는지 보고, 티켓에 원격·클라이언트 버전과 digest를 함께 남겨 한쪽만 올리는 일을 피합니다.
채널형 무음과 비교하면 원격 모드 이슈는 연결·세션 층에 가깝습니다. 메시지 흐름을 의심하면 channels 프로브 글을 읽고 remote URL을 추측으로 두드리지 마세요.
상시 운영 팀은 프로브 실패율과 재연결 간격을 기존 관측 스택으로 보냅니다. OpenClaw가 건강해도 기업망 지터는 보여야 합니다.
아래는 내부 합의용 기준입니다. 임계값은 사용자 규모와 리전에 맞게 조정하세요.
wss 종단까지 핸드셰이크 실패는 60초 이내에 DNS·TCP·TLS·WSS 층별 점검으로 어디서 끊겼는지 특정할 수 있어야 한다.Config (cli)와 Config (service)가 어긋나면 기본 경로는 동일 사용자 install --force → restart → doctor이며 state 디렉터리를 기록한다.노트북만으로 Gateway를 돌리면 수면·회의 앱과 포트를 다툽니다. 원격 CLI만 있고 안정적으로 닿는 컨트롤 플레인이 없으면 VPN 지터에 함께 쓰러집니다. Gateway를 전용·상시 온라인·SSH로 유지보수 가능한 클라우드 Mac 또는 VPS에 두고 엔지니어 노트북을 원격 클라이언트로 표준화하는 것이 2026년에도 가장 흔한 타협입니다. 불안정한 컨테이너나 불투명 가상화에 감독 프로세스를 억지로 넣는 것보다 NodeMini Mac Mini 클라우드 대여가 SSH 기준선과 예측 가능한 티어, 재현 가능한 노드 이미지 측면에서 OpenClaw를 프로덕션 인프라로 다루기 쉽습니다. 사양과 가격은 Mac Mini 대여 가격, 온보딩은 헬프 센터를 보세요. 관련 글은 OpenClaw 카테고리에서 필터링할 수 있습니다.
출시 시 본 Runbook을 내부 환경 단계(dev/staging/prod)에 묶고 각각 다른 remote URL과 토큰 주기를 두며, 프로덕션 URL을 개인 프로필에 손으로 복사하지 않는 규칙을 지키세요.
원격 모드는 CLI가 다른 머신의 Gateway에 붙습니다. Tailscale은 이미 노트북에서 리슨하는 Gateway를 tailnet에 안전히 노출하는 쪽에 가깝습니다. 병행 가능합니다. OpenClaw 관련 글은 블로그 OpenClaw 필터를 보세요.
서비스와 동일 사용자·동일 state 디렉터리에서 openclaw gateway install --force와 restart를 실행한 뒤 openclaw doctor로 검증하세요. 노드·청구는 헬프 센터도 참고하세요.
환경 변수 덮어쓰기, 셸 프로필 잔여, gateway.mode가 아직 local인지 확인하세요. Gateway를 클라우드에 상시 두려면 Mac Mini 대여 가격으로 티어를 비교하세요.