gateway.bind=lan을 유효한 gateway.auth.token과 세트로 요구합니다. refusing to bind without auth, Dashboard unauthorized, SSH에서는 녹색인데 launchd만 빨간 증상은 bind 변경과 token 배선 순서 역전, 또는 LaunchAgent가 옛 loopback 설정을 쥔드리프트에서 자주 납니다. 본문은 loopback·lan 결정 트리, ~/.openclaw/.env의 OPENCLAW_GATEWAY_TOKEN과 openclaw.json 단일 정보원, 6단계 프로덕션 전환, gateway.reload.mode=hybrid 핫 리로드 경계, gateway.controlUi.allowedOrigins, /healthz 검수, LaunchAgent 드리프트 탐지를 정리합니다. launchd token, 업그레이드 bind·터널, 원격 Gateway 토폴로지, 진단 사다리, install-daemon과 함께 읽으시기 바랍니다.
loopback과 lan: 개인 SSH 터널에서 Control UI 프로덕션 bind까지
OpenClaw Gateway 기본값은 127.0.0.1:18789 loopback 리슨입니다. KVMNODE 클라우드 Mac에 SSH한 뒤 ssh -L 18789:127.0.0.1:18789로 브라우저를 여는 운영은 단일 엔지니어 개발기에 가장 안전하며 token 없이도 doctor가 통과하기 쉽습니다. 반면 사내 두 번째 노트북에서 Control UI에 직접 붙거나, LAN 내부 헬스 프로브가 RFC1918 주소로 도달해야 하거나, Tailscale 서브넷 라우터 너머 고정 IP로 두드려야 할 때 gateway.bind=lan 검토가 시작됩니다.
2026 빌드는 비루프백 bind에명시적 인증을 요구합니다. gateway.bind만 lan으로 바꾸고 token을 plist·.env에 빠뜨리면 로그에 refusing to bind without auth류 조기 종료가 나오고 launchd가 재시작 루프에 들어갑니다. 이는 모델 API 장애가 아니라 설정 가드가 의도대로 동작하는 신호입니다. 터널·ACL 없이 공网 인터페이스에 18789를 노출하는 선택은 권장되지 않습니다. 클라우드 보안 그룹에서 포트를 열기 전에 애플리케이션 계층 token과 allowedOrigins를 맞추세요.
loopback 유지: 한 사람이 SSH 터널로 Dashboard만 본다. 변경 티켓에 터널 명령 고정.
lan + token: 동일 VPC·Tailnet 내 다중 클라이언트, 무인 프로브, Control UI 상시 URL.
터널 우선 절충: bind는 loopback, Tailscale serve·SSH -L로 에지만 두고 Gateway 본체는 최소 노출.
피할 것: token 없는 lan, 수동 gateway start와 plist 공존, 변경 후 listen 주소 미확인.
원격 클라이언트만 늘리고 Gateway 권위는 한 대에 두는 설계는 gateway.mode remote 글이 다룹니다. 본문은서버 측 Gateway 자체의 bind 면에 초점을 둡니다. 첫 onboard가 끝나지 않았다면 설치 체크리스트로 loopback healthy를 잡은 뒤 lan으로 진행하세요.
.env와 openclaw.json: OPENCLAW_GATEWAY_TOKEN 단일 정보원과 금지 패턴
token을 대화 shell export에만 두면 launchd 상주로 바꾸는 순간 감독 프로세스는 빈 환경으로 기동합니다. launchd token 글이 설명하는 split brain과 같아, CLI는 openclaw config get gateway.auth.token으로 값을 주는데 데몬은 다른 경로·미주입 상태로 unauthorized를 반환합니다.
프로덕션 권장은 ~/.openclaw/.env에 OPENCLAW_GATEWAY_TOKEN=을 쓰고 openclaw.json에서 gateway.auth.mode를 명시하는 것입니다. Gateway install 또는 openclaw gateway install --force가 plist가 state 디렉터리와 .env를 읽는 경로를 재생성합니다. plist EnvironmentVariables에 평문 token을중복 저장하면 로테이션 때 한쪽만 갱신되어 금지입니다. PATH, OPENCLAW_STATE_DIR, 필요 시 node 절대 경로만 plist에 남깁니다.
| 보관 위치 | 용도 | launchd 가시성 | 피해야 할 이유 |
|---|---|---|---|
| ~/.openclaw/.env | 프로덕션 token 단일 원 | install 후 가능 | chmod 600, Git 금지 |
| openclaw.json gateway.auth | mode·메타 또는 json 단독 | 가능 | repo에 평문 commit 금지 |
| ~/.zshrc export | 대화 디버그만 | 불가 | 상주 Gateway에 미전달 |
| plist 평문 token | 단기 트리아지 | 가능 | 로테 드리프트·이중 관리 |
| 채팅·티켓 붙여넣기 | 없음 | — | 유출·재발급 비용 |
bind를 lan으로 넓히기 전에 감독 프로세스가 token을 읽는지 doctor와 launchctl print로 증명하세요. 인증 없는 listen 확대는 설계상 실패합니다.
레거시 키 gateway.token만 남으면 새 스키마가 무시해 Dashboard가 401을 반복합니다. 업그레이드 런북 token 절을 참고해 lan bind와 같은 변경 티켓에서 gateway.auth.token 또는 .env로 통일하세요.
6단계 따라하기: 구 프로세스 중지부터 healthz·token 클라이언트 검수까지
아래는 KVMNODE 전용 클라우드 Mac에서 loopback을 lan 프로덕션 bind로 옮기는 표준 순서입니다. 각 단계 stdout을 변경 티켓에 붙이고 롤백은 json·.env·plist 세트로 합니다.
구 프로세스·이중 listen 정리: lsof -nP -iTCP:18789 -sTCP:LISTEN으로 수동 gateway와 plist 경합 해소. 여분 PID는 기록 후 중지.
.env에 token 기록: openssl rand -hex 32 등으로 생성해 ~/.openclaw/.env에 OPENCLAW_GATEWAY_TOKEN= 추가. 권한 600.
openclaw.json bind·auth: gateway.bind=lan, gateway.auth.mode 명시. allowedOrigins는 후단 가능.
gateway install·LaunchAgent 검수: openclaw gateway install --force 후 launchctl print gui/$(id -u)/com.openclaw.gateway로 ProgramArguments·WorkingDirectory 확인.
healthz: 호스트에서 curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:18789/healthz와 LAN IP 도달 기록.
클라이언트 token 검수: Control UI·CLI에서 Authorization 헤더 연결. 무 token 401 확인으로 오노출 탐지.
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" lsof -nP -iTCP:18789 -sTCP:LISTEN openclaw config set gateway.bind lan openclaw config set gateway.auth.mode token openclaw gateway install --force openclaw gateway restart openclaw gateway status --deep curl -sS http://127.0.0.1:18789/healthz curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" http://127.0.0.1:18789/
원격 실행 시 위 명령은Gateway가 도는 클라우드 Mac SSH 세션에서 돌려야 합니다. 로컬 노트북 터미널에서 config set하면 대상 호스트 openclaw.json이 갱신되지 않는 오바인딩이 납니다. openclaw gateway status --deep이 duplicate unit을 보이면 여분 LaunchAgent를 bootout한 뒤 install을 재실행하세요.
gateway.reload.mode=hybrid: 핫 리로드와 수동 재시작 경계, allowedOrigins
gateway.reload.mode=hybrid는 채널 설정·일부 UI 메타 변경을 프로세스 재시작 없이 반영하는 모드입니다. 운용 함정은 bind·auth·listen 포트·LaunchAgent 본체 변경을 hybrid로 끝내려는 것입니다. 이들은 소켓 재바인드·plist 재로드가 필요해 openclaw gateway restart 또는 kickstart가 정답입니다.
| 변경 항목 | hybrid로 충분? | 권장 조작 | 검수 |
|---|---|---|---|
| gateway.controlUi.allowedOrigins | 대개 가능 | config set 후 UI CORS 오류 소멸 | 브라우저 DevTools |
| 채널 webhook URL | 경우 있음 | channels probe | openclaw channels probe |
| gateway.bind | 불가 | restart + lsof | LISTEN이 0.0.0.0 또는 LAN IP |
| OPENCLAW_GATEWAY_TOKEN | 불가 | .env 갱신 → restart | 구 token 401 |
| ProgramArguments / Node 경로 | 불가 | gateway install --force | launchctl print |
Control UI를 다른 오리진 브라우저에서 열려면 gateway.controlUi.allowedOrigins에 HTTPS 오리진을 열거합니다. 터널로 http://127.0.0.1:19000을 쓰는 개발기와 프로덕션 HTTPS 도메인은 변경 티켓에서 항목을 나누세요. allowedOrigins만 고쳐도 bind가 loopback이면 LAN 클라이언트는 여전히 못 붙습니다. 순서는 bind → token → restart → origins → hybrid 가능 영역 확인입니다.
힌트: hybrid 반영 후에도 openclaw gateway status RPC 프로브가 실패하면 핫 리로드가 아니라 LaunchAgent 드리프트를 의심하고 진단 사다리 L2 deep status로 가세요.
고빈도 오류 분기, LaunchAgent 드리프트 검수, 육 지역·M4 Pro 선정
refusing to bind without auth: lan 설정 대비 token이 .env·json에 없음. 생성·install 선행.EADDRINUSE: 18789 소유가 수동 프로세스. kill 전 lsof로 PID·명령행 저장.unauthorized: 클라이언트 token과 서버 .env 불일치 또는 allowedOrigins 미등록.프로브만 실패: listen 주소와 probe URL 불일치. loopback 프로브를 lan bind에 두지 마세요.
| LaunchAgent 드리프트 신호 | 의미 | 시정 |
|---|---|---|
| which openclaw ≠ plist 선두 | CLI·데몬 다른 빌드 | PATH 고정 → install --force |
| listen이 127.0.0.1 유지 | json 갱신 미반영 | restart, 안 되면 plist 재생성 |
| 로그에 token 행 없음 | .env 경로 감독 환경과 어긋남 | OPENCLAW_STATE_DIR 일치 |
| 이중 Label | 구 onboard 잔존 | bootout 여분 → 단일 unit |
장애 순서: gateway status --deep → doctor → lsof 18789 → .env·json → install --force → 클라이언트 token 재시도.
육 지역: LAN bind는 노드 NIC에 의존. 리전 이전 시 allowedOrigins·방화벽 재검수.
M4·M4 Pro: bind 변경 자체는 CPU 비의존. 동일 호스트 iOS CI·Gateway 공존으로 메모리 압이 큰 주는 M4 Pro 또는 풀 분리.
주의: hybrid·restart 연타 전에 로그와 doctor를 읽으세요. 단순 포트 경합을 재시작 루프로 바꾸면 채널 전체 outage 창이 넓어집니다.
노트북 덮개를 Gateway 호스트로 두면 lan bind 성공 후에도 수면으로 listen이 사라져 클라이언트는 unauthorized·타임아웃으로 보입니다.7×24 lan 프로덕션 bind에는 KVMNODE 전용 클라우드 Mac과 launchd 상주가 실무 기본입니다. bind 모드·token 로테 일·plist Label·healthz 결과를 한 변경 티켓에 실을 전용 호스트는 원격 팀 감사 비용을 줄입니다. SKU는 가격 페이지, 절차는 고객 센터, 주문은 주문入口를 참고하세요. 24시간 안정 운영 heartbeat 절과 함께 야간 프로브에도 token URL을 쓰면 드리프트 탐지가 빨라집니다.