OpenClaw 게이트웨이에서 포트 18789는 무엇에 쓰이나요?

많은 2026 템플릿에서 18789는 게이트웨이 프로세스와 동일 머신의 관리·진단·확장 핸드셰이크·doctor/reload류 프로브용 로컬 HTTP 면입니다. openclaw.json과 launchd plist에서 바인드 주소·포트를 반드시 확인하고, 포트를 바꾸면 VS Code 확장의 베이스 URL도 함께 맞추세요.

원격 Mac에서 curl http://127.0.0.1:18789는 되는데 노트북 VS Code 확장은 타임아웃인 이유는?

127.0.0.1은 머신별 루프백입니다. 확장이 SSH -L 로컬 포워드나 올바른 DNS로 종료되는 TLS 역프록시를 거치지 않으면, 노트북에서의 요청은 원격 게이트웨가 아니라 노트북 자신의 루프백으로 갑니다. 포워딩된 로컬 포트에 nc -vz를 쓰고, TLS면 nginx 앞에서 openssl s_client로 검증하세요.

어떤 TCC(개인정보 보호·보안) 실패가 네트워크 장애처럼 보이나요?

launchd가 키체인 항목을 읽거나 워크스페이스 상태를 쓰거나 자동화로 터미널을 제어해야 하는데 전체 디스크 접근·손쉬운 사용이 없으면 로그에는 EACCES나 spawn 오류가 찍히는데 lsof에는 18789 LISTEN이 남을 수 있습니다. 실제 바이너리 경로를 시스템 설정에 추가하고 작업을 다시 로드하세요.

한 Mac에서 OpenClaw 인스턴스가 여러 개일 때 18789가 겹치면?

인스턴스마다 127.0.0.1:18789와 127.0.0.1:18790처럼 구분된 바인드를 주고, VS Code 워크스페이스마다 올바른 베이스 URL을 매핑하며, lsof -nP -iTCP -sTCP:LISTEN으로 launchd가 동일 레이블을 이중 기동하지 않게 하세요.

OpenClaw VS Code Node × 원격 물리 Mac 게이트웨이 18789 (2026 런북)

서론: 이 글이 답하는 세 가지

누구—전용 또는 풀링된 원격 Mac에 OpenClaw를 배선하는 플랫폼 엔지니어. 무엇을—마켓플레이스 확장부터 포트 18789의 안정적인 HTTP 제어 면까지, 루프백 성공을 종단 간 성공으로 착각하지 않는 단일 재현 경로. 구조—난점, 의사결정 표, 7단계, 수치, 트리아지, FAQ, 그리고 무인 게이트웨이에 적합한 Apple Silicon Mac mini 관점.

동일 주제의 English · 简体中文 · 日本語 버전과 hreflang으로 연결됩니다.

기업 메신저·이그레스와 게이트웨이를 맞출 때는 OpenClaw 페이슈·Lark·Microsoft Teams 연동 Runbook을 참고하고, 테스트용 단독 대여 Mac의 운영 리스크는 macOS Sequoia 이후 테스트 Mac 대여 가이드와 교차 검토하세요.

1. 세 가지 고질적 난점

루프백은 전이되지 않습니다. 서버에서 curl http://127.0.0.1:18789/health가 된다는 것은 그 호스트의 게이트웨이와 방화벽만 증명합니다. 다른 머신의 VS Code 창에는 명시적 터널·분할 DNS·역프록시 경로가 없으면 확장이 자기 루프백에만 말하고 타임아웃합니다.
권한 거부가 "포트가 나쁨"처럼 보입니다. TCC가 키체인 읽기, 터미널 자동화, 보호 디렉터리 쓰기를 막으면 lsof에는 여전히 18789 LISTEN이 보일 수 있습니다. 로그의 EPERM을 놓치고 nginx만 몇 시간 쫓는 패턴입니다.
JSON·plist·UI 사이의 조용한 드리프트. 누군가 openclaw.json의 바인드를 바꿨는데 LaunchAgent ProgramArguments는 그대로이거나, VS Code 워크스페이스는 http://127.0.0.1:18789인데 프로덕션은 localhost:8443 TLS로 옮겼다면, 설정 동기 블롭이 다른 팀원마다 달라 간헐적으로만 재현됩니다.

2. VS Code 확장이 게이트웨이에 닿는 방식(의사결정 표)

환경마다 주 전송 하나를 고르세요. 문서 없이 SSH -L과 공유 nginx 업스트림을 섞으면 온콜이 주말을 잃습니다.

패턴	적합한 경우	주의
Mac 직접 루프백	자동화, cron, 로컬 doctor 스크립트	원격 노트북에는 보이지 않음—실수로 WAN에 노출하지 않으려면 `127.0.0.1` 바인드
SSH `-L` 로컬 포워드	재택·출장 Wi-Fi에서 VS Code를 붙이는 개발자	기업 정책에 맞는 keepalive·점프 호스트—로컬 포트(예: 원격 18789 → 노트북 18789)를 런북에 적습니다
nginx/Caddy 루프백 + TLS	mTLS, SSO 헤더, 경로 기반으로 여러 데몬에 라우팅	인증서 갱신·`proxy_pass` 오타—확장 베이스 URL은 공개 호스트명에 맞추고 raw 18789만 쓰지 않기

3. 7단계 재현 런북

리스너 베이스라인: 원격 Mac에서 lsof -nP -iTCP:18789 -sTCP:LISTEN와 curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/(설치에 경로 접두가 있으면 조정).
VS Code에 OpenClaw Node 설치: extensions.json 권장 목록에 확장 버전을 고정해 팀 전체가 동일 RPC 스키마를 로드하게 합니다.
베이스 URL 계약 공표: 개발자가 ssh -L 18789:127.0.0.1:18789 user@gateway 뒤 http://127.0.0.1:18789를 쓸지, https://openclaw.internal 가상 호스트를 쓸지 위키에 한 줄로 못 박습니다.
launchd 강화: RunAtLoad, ThrottleInterval, 명시적 WorkingDirectory; 환경은 월드 Writable 도트파일이 아니라 root만 읽는 plist 조각에서 주입합니다.
TCC를 의도적으로: 게이트웨이가 AppleScript로 셸을 띄우거나 개발자 인증서를 읽으면, 개인정보 보호 설정에 실제 바이너리 경로를 미리 허용하고 내부 보안 검토용 스크린샷을 남깁니다.
클라이언트 수락: 터널이 올라온 뒤 개발자 노트북에서 nc -vz 127.0.0.1 18789; TLS 프런트면 openssl s_client -connect openclaw.internal:443 -servername openclaw.internal.
베이스라인 동결: JSON+plist 스니펫을 플랫폼 저장소에 커밋하고, 게이트웨이 시맨틱 버전과 확장 시맨틱 버전을 함께 검증한 태그를 찍습니다.

4. 인용 가능한 파라미터

18789—많은 2026 템플릿에서 로컬 OpenClaw HTTP 제어 관례; 마법 숫자가 아니라 설정 가능한 기본값으로 취급.
127.0.0.1 대 0.0.0.0—루프백 바인드는 실수로 WAN에 노출되는 것을 줄임; 전 인터페이스 바인드는 방화벽·VPC 규칙이 필요해 VS Code 연동에는 드뭅니다.
약 30~60초—재부팅 후 LaunchAgent 콜드 스타트 예산(온콜 페이지 전); ThrottleInterval과 짝지어 재시작 폭풍을 피합니다.

5. 트리아지 치트시트

증상	유력 원인	첫 명령·조치
노트북에서만 ECONNREFUSED	SSH 포워드 없음·로컬 포트 불일치	SSH `-v` 재실행; `~/.ssh/config`의 `LocalForward` 확인
nginx HTTP 502	업스트림 다운·소켓 불일치	Mac에서 직접 `curl -v http://127.0.0.1:18789`; error 로그 꼬리
프로세스 코드 1로 종료, 포트 비어 있음	TCC·시크릿 누락	Console.app에서 서브시스템 필터; 바이너리에 FDA 추가 후 plist 리로드

6. FAQ

<head>의 JSON-LD FAQ와 같은 답을 풀어 썼습니다.

18789 역할: 관리·진단·확장 트래픽용 로컬 HTTP 면인 경우가 많음—항상 자신의 openclaw.json과 LaunchAgent로 확인.
원격 curl OK, VS Code NG: 루프백 정의가 다름—터널을 쓰거나 검증한 경로로 확장 베이스 URL을 바꿈.
18789를 공인 인터넷에? TLS·인증·속도 제한 없이는 비권장—VPN·Tailscale·SSH 포워드를 우선하고, 브라우저가 닿아야 하면 127.0.0.1 뒤 nginx를 둠.
한 Mac에 여러 인스턴스: 포트·plist 레이블을 겹치지 않게 할당하고 배포 전 LISTEN을 grep.

7. 이 게이트웨이 스택을 Apple Silicon Mac mini에서

OpenClaw와 VS Code 기반 자동화는 조용히 켜 두는 머신에서 빛납니다. Apple Silicon Mac mini는 유휴 전력이 대략 4W 전후인 경우가 많으면서도 네이티브 Unix 도구·launchd·Keychain 통합을 하이퍼바이저 세금 없이 제공합니다. Gatekeeper·SIP·FileVault는 장기 API 키를 올려 두는 점프 박스보다 신뢰 경계가 단순합니다.

통합 메모리 대역폭은 Node 게이트웨이, nginx, 가벼운 CI 에이전트가 동시에 스파이크할 때도 한 샤시 안에서 응답성을 유지하는 데 유리합니다—doctor 프로브, 확장 RPC, 로그 전송이 겹칠 때 특히 그렇습니다.

분산 팀을 위해 OpenClaw 게이트웨이를 표준화한다면 Mac mini M4는 24/7 macOS 자동화를 위한 비용 대비 앵커로 강력합니다. 위 절차와 같은 plist 의미론을 갖춘 전용 노드를 빠르게 확보하려면 ZoneMac 홈에서 렌탈 옵션을 확인해 보세요.

2026년 OpenClaw Node for VS Code 원격 물리 Mac 게이트웨이 재현 런북: 확장 설치, 18789 연결, 로컬 루프백·SSH -L·TCC 권한 마찰(트리아지 + FAQ)