OpenClaw Gateway를 VPS나 집 서버에 올려 두었지만 18789 포트를 공인에 노출하고 싶지 않고, 노트북·다른 Linux·모바일 노드가 내부 서비스처럼 CLI·WebSocket에 접속하기를 바라는 경우가 많습니다. 본문은 Tailscale 사설 터널과 기본 루프백 바인딩을 기준으로 토폴로지 경계, 토큰·환경 변수, 원격 CLI 점검 항목을 정리하고, 터널은 붙는데 RPC·세션이 기대대로 이어지지 않을 때의 분기 진단에 초점을 맞춥니다. 끝까지 읽으면 사이트 내 Cloudflare Tunnel + systemd 글과의 역할 분담을 파악할 수 있고, 중부하 시나리오에서 전용 원격 Mac으로 자연스럽게 이어지는 흐름도 이해할 수 있습니다.
OpenClaw Gateway는 기본으로 제어 면을 127.0.0.1에 바인딩합니다. 이는 공격면을 OS가 약속한 경계 안에 머물게 둔다는 뜻으로, WebSocket·HTTP 제어 면에 직접 닿을 수 있는 것은 해당 기기의 프로세스뿐입니다. 첫 배포에서 원격에서도 openclaw를 쓰려다 감이 오지 않을 때, 섣불리 리슨을 0.0.0.0으로 바꾸고 수동으로 방화벽을 덧댄다면, 데모로는 굴러가도 프로덕션에서는 무인 스캔, 토큰 유출, CORS 오설정이 한꺼번에 커질 수 있습니다.
스캔면이 가파르게 커집니다: 포트가 공인에서 닿는 순간, 자동화 스캐닝이 수 시간 안에 훑습니다. 토큰을 잠시 셔터를 내려도 로그는 소음으로 가득해 SOC에서 경보를 잡기 어렵습니다.
「최소 노출」 보안 가이드와 충돌합니다: 사이트 내 Gateway 보안 강화 문서는 루프백·토큰 순환·실행 승인을 강조합니다. bind를 열어 두는 것은 그 첫 관문을 스스로 무너뜨리는 셈입니다.
장애 신호가 오염됩니다: 공인 경로에는 CDN, 이통사 NAT, 사내 프록시가 겹칩니다. half-close나 MTU 이슈를 OpenClaw로만 돌릴 뿐, 실제 원인은 전송 경로에 있을 수 있습니다.
감사·컴플라이언스가 어려워집니다: "어느 공인 IP가 에이전트 제어 면에 들어왔는가"를 자연인과 쉽게 맞추기 어렵고, tailnet 쪽 신원(기기·사용자 + ACL)이 제도에 쓰기 훨씬 수월합니다.
다중 Gateway 토폴로지를 수렴시키기 어렵습니다: 같은 호스트에 두 번째 인스턴스를 실험할 때 포트 충돌·토큰 혼용 확률이 뛰어오릅니다.
원격 Mac 시나리오와도 맞지 않습니다: 장기적으로 큰 힘을 요구하는 것은 Xcode, 시뮬레이터, 대용량 캐시입니다. Gateway는 가볍게 두고 무거운 일을 전용 노드에 스케줄하는 편이 맞습니다.
취해야 할 기본 관점은 Gateway는 loopback에 두고, 도달성은 Tailscale 같은 통제된 네트워크 층으로 다룬다는 것입니다. DB를 127.0.0.1에만 열고 SSH 터널로 접는 습관과 같은 계열의 설계입니다. Cloudflare Tunnel에 익숙하다면, Linux VPS + systemd + Cloudflare Tunnel 글에서 "에지 입구"와 본문의 "순 tailnet" 차이를 먼저 읽어 두는 것이 좋습니다.
| 차원 | Loopback + Tailscale | 공인 bind | Cloudflare Tunnel |
|---|---|---|---|
| 신뢰 모델 | tailnet 신원 + ACL, 기본은 사설 | 방화벽+토큰, 노출이 큼 | 에지·터널 자격, 공인 쪽 입구 |
| 운영 복잡도 | 중: ACL·호스트명 유지 | 시작은 쉬우나 장기 위험 | 중·고: DNS·인증·백엔드 정책 |
| OpenClaw 기본 구성과의 궁합 | 높음: bind 변경이 거의 불필요 | 낮음: bind를 열도록 유도 | 중: 터널이 루프백 포트로 되돌림 |
| 전형적 사용자 | 개인·소규모 팀의 사내 오케스트레이션 | 프로덕션 권장 대상이 아님 | 공인에서 제어된 입구가 필요한 경우 |
「터널이 해 주는 것은 경로이지, 인증이 아닙니다. 토큰과 실행 승인은 끄지 않는 것이 좋습니다.」
Tailscale의 가치는 여러 기기를 동일한 신뢰 도메인에 넣어 100.x 대역이나 안정적인 호스트명으로 서비스에 닿게 하는 점에 있습니다. Gateway 쪽 토큰을 자동으로 대체해 주지는 않습니다. ACL이 지나치게 넓다면(예: *:*) tailnet 안에 축소된 공용망에 가까운 구역이 하나 더 생깁니다.
2026년에 자주 쓰는 토폴로지로는 서브넷 라우터와 exit node가 붙습니다. 전자는 Tailscale이 없는 LAN 대역에도 tailnet에서 접속할 수 있게 하고, 후자는 특정 기기의 이그레스를 다른 기기로 보냅니다. Gateway와 DB가 같은 VPC에 있고, 노트북만 tailnet에 붙어 있다면 "어떤 src가 DB 포트까지 들어올 수 있는가"를 그려 보지 않으면, 서버에선 curl이 잘 돼도 원격 CLI만 간헐 500이 나는 것처럼 보이는, ACL·경로 비대칭 이슈를 OpenClaw 탓으로 오해하기 쉽습니다.
또 자주 잡는 세부는 MagicDNS와 검색 도메인입니다. 일부 엔터프라이즈는 *.ts.net을 사내 DNS로 흡수합니다. 장애 시 노트북에서 공용 리졸버와 tailnet 기본 해석을 나란히 dig로 보면, DNS를 섞는 문제를 OpenClaw 세션 이상으로 오독하는 일을 줄일 수 있습니다. 운영 런북에 정리해 두면 신입 온보딩도 훨씬 수월해집니다.
Gateway 호스트에 Tailscale을 설치·로그인한 뒤, 같은 tailnet의 노트북에서 ping과 tailscale ping의 RTT를 먼저 확인합니다. Admin 콘솔에서 해당 노드에 tag가 맞는지, MagicDNS가 켜져 있는지, ACL에 운용 서브넷에서 Gateway 역할로 TCP 18789(또는 사용자 정의 포트)로의 허가가 있는지 봅니다.
// ACL fragment: only machines with tag:ops reach gateway :18789
{
"groups": { "group:ops": ["alice@github", "bob@github"] },
"tagOwners": { "tag:gateway": ["group:ops"] },
"acls": [
{
"action": "accept",
"src": ["tag:ops"],
"dst": ["tag:gateway:18789"]
}
]
}
주의: 위는 형태를 보여주는 예시입니다. 실제 ACL은 exit node·서브넷 라우트·모바일 노드에 대한 최소 권한을 함께 담고, 변경 후에는 테스트 기기에서 tailnet을 재연결한 뒤 다시 확인합니다.
검수 항목은 변경 티켓에 같이 박는 편이 좋습니다. ① Gateway 프로세스는 여전히 127.0.0.1:18789에 리슨하는가. ② 운용 머신에서, SSH 포워딩이 아닌 tailnet IP로도 동일한 헬스 엔드포인트(배포 버전이 정의한 경로)에 닿는가. ③ 공인 보안 그룹에서 18789 인바운드는 모두 막혀 있는가. 채널은 연결돼도 메시지가 안 온다는 이슈와 겹쳐 볼 때는 channels 탐지와 dmPolicy 문서를 함께 대조합니다.
Gateway가 해당 호스트에서 openclaw doctor까지 녹색이라는 전제를 둡니다. 아직 기동을 마치지 않았다면, 먼저 전 플랫폼 설치·초기 트러블슈팅을 읽고 본문으로 돌아오는 것이 좋습니다.
리슨 주소를 확인합니다: 서버에서 lsof -nP -iTCP:18789 -sTCP:LISTEN로 127.0.0.1에 묶여 있는지 봅니다. *:18789이면 먼저 구성을 되돌리고 터널 이야기를 이어갑니다.
토큰 출처를 고정합니다: OPENCLAW_GATEWAY_TOKEN을 환경 변수로 주입하는 방식을 우선해, 동기화되는 설정 저장소에 장기 키를 쓰지 않도록 합니다.
노트북에 remote를 씁니다: 클라이언트 ~/.openclaw/openclaw.json에 tailnet 호스트명·포트를 가리키는 remote 블록을 둡니다(필드명은 사용 중인 CLI의 도움말을 기준). WebSocket URL은 ws://·wss://를 사내망 정책에 맞게 선택합니다.
포트 환경 변수를 맞춥니다: 기본이 아닌 포트를 쓰면, 서비스·클라이언트 세션 모두에서 OPENCLAW_GATEWAY_PORT를 동일하게 맞춥니다. "doctor는 통과하는데 원격 CLI만 다른 포트로 붙는" 상황을 막습니다.
TLS가 어디서 끝나는지 봅니다: tailnet 안에 로컬 리버스 프록시를 둔 경우, WebSocket 업그레이드 헤더를 중간에서 떨어뜨리지 않는지 확인합니다.
한 번 통과한 세션의 로그 흐름을 박제합니다: gateway status, doctor, 실패한 한 세션을 동일 티켓에 남기면, 이후 Gateway 버전 업 시에도 대조하기 좋습니다.
// client ~/.openclaw/openclaw.json (example; see official CLI)
{
"gateway": {
"remote": {
"url": "ws://openclaw-gateway.tailnet-1234.ts.net:18789",
"token": "use-env-or-osx-keychain-instead-of-plaintext"
}
}
}
참고: Gateway와 대용량 빌드·아티팩트를 메모리가 작은 VPS 한 대에 겹쳐 두지 않는 것이 좋습니다. xcodebuild나 큰 캐시에 에이전트를 묶을 계획이면, 실행면은 전용 원격 Mac에 두고 Gateway는 세션·툴 오케스트레이션에 집중하는 구성이 안정적입니다. 디스크·지역에 맞는지는 Mac Mini 임대 요금 안내로 티어를 먼저 맞춰 봅니다.
| 현상 | 우선 의심 | 권장 조치 |
|---|---|---|
| tailscale ping은 되는데 CLI만 타임아웃 | 포트가 ACL에 없음, 혹은 호스트 방화벽이 루프백 뒤 전달을 막음 | 서버에서 먼저 loopback을 검증한 뒤 단계를 바깥으로 넓힘 |
| HTTP 401 / 인증 실패 | 토큰 불일치, systemd 유닛에 환경 변수가 안 실림 | unit의 Environment=와 사용 중 셸의 값을 맞춤 |
| WebSocket이 즉시 끊김 / gateway closed(1000) | 버전 올린 뒤 scope·세션이 맞지 않음 | 사이트 내 gateway closed(1000) 자료로 토큰·scope를 수렴 |
| 채널은 켜졌는데 메시지가 안 들어옴 | 채널 미페어·dmPolicy 차단 | channels 하위 탐지 명령과 정책 표를 맞춤 |
Gateway 소버전을 올린 뒤에만, 같은 ACL·같은 토큰인데 원격 CLI에서만 터지는 사례가 나오면, 릴리스 노트의 호환성 변경과 기본 포트 표를 먼저 읽고, 이전에 안정이던 빌드로 되돌려 이분합니다. 아직 리슨·포트 매트릭스를 확정하기 전에 ACL을 반복해서 바꾸면, 티켓에는 거짓 양성이 쌓입니다.
18789을 다중 제어 면으로 씁니다(정확한 값은 릴리스를 따릅니다). 포트를 옮기면 systemd·Docker Compose·클라이언트 remote가 한 줄이라도 엇갈릴 수 있고, "절반만 예전 포트" 같은 상태로 진단이 끼입니다.tag:gateway 같이 꼬리표를 박으면, ACL을 팀이 커질수록 키울 수 있습니다. 운영 런북에는 "퇴사 시 기기를 tailnet에서 삭제·폐기"를 고정 루틴으로 써 두는 것이 좋습니다.공인에 민감도가 높은 bind나 지나치게 느슨한 tailnet ACL만 믿으면, 2026년에도 에이전트 제어 면이 감사하기 어렵고, Gateway가 얹힌 작은 VPS 한 대에만 무게를 실으면 메모리·디스크가 동시에 답답해질 수 있습니다. 전자는 네트워크·신원 측 방어를 잃는 것이고, 후자는 클라우드 머신처럼 수평 확장하기 힘든 실행면을 쓰는 셈입니다.
안정된 조합은 Gateway는 가볍게 상주시키고, tailnet으로 접속면을 줄이며, 무거운 일은 독점 macOS 노드에 넘기는 것입니다. 안정된 Xcode·장기 세션·계약에 묶을 수 있는 디스크가 필요하다면, NodeMini Mac Mini 클라우드 임대가 자주 더 나은 수단이 됩니다.
패킷이 tailnet을 타고 대상 호스트에 들어온 뒤, 그 호스트의 스택이 127.0.0.1:18789로 흐름을 이어 줍니다. Gateway를 "전부 인터페이스"로 바꿀 필요는 없고, ACL·호스트 방화벽·토큰을 맞추는 쪽이 핵심입니다. Mac 쪽 용량·요금 티어는 Mac Mini 임대 요금 안내로 함께 보는 것이 좋습니다.
Tunnel 글은 공인망에서 사설로 안전히 들어오는 "에지 라우팅"에 초점을 둡니다. 본문은 tailnet 안에서 루프백을 유지하는 "사설 모델"을 다룹니다. 상황에 따라 하나를 고르거나, 계층을 겹쳐도 됩니다. 인증 사슬을 이해하지 못한 채 여러 층을 쌓지 않는 것이 좋습니다.
블로그 OpenClaw 분류에서 주제를 걸어 보고, 연결·계정·원격 쪽은 클라우드 Mac 도움말 센터의 SSH·원격 쿼터에 해당하는 절을 함께 봅니다.