2026 헤드리스 SSH 다섯 가지 오해: Node, PATH, TTY, nvm, npm 전역 PREFIX
OpenClaw CLI와 Gateway는 쓰기 가능한 설정 루트와 안정된 Node 런타임과 해석 가능한 전역 명령을 전제로 합니다. 대화형 셸은 프로필로 조용히 채우지만 순수 SSH 비로그인 세션은 채우지 않습니다. 같은 호스트가 ssh -t에서는 녹색이어도 TTY를 할당하지 않는 자동화에서는 빨간색이 되며 command not found나 이유 없이 확인에서 멈추는 설치기가 나옵니다. 임대 베어메탈 Mac에서는 수락 명령과 티켓 필드를 한 대와 한 계정 이야기로 고정해 노트북 소문과 클라우드 소문을 동기화할 필요를 줄입니다.
가까운 지역 저지연 호스트와 먼 M4 Pro 상주의 차이는 주로 의존성 내려받기 벽시계 시간과 큰 통합 메모리 계층에서 무거운 doctor 루프를 돌릴지 여부입니다. 게이트웨이 프로토콜 자체는 변하지 않습니다. 런북 전반은 두 계층에서 동일하게 유지하고 조달 행만 리전과 SKU로 분기합니다. launchd와 포트 이분 탐색의 깊이는 계속 설치 체크리스트와 launchd 토큰 글에 맡깁니다.
헤드리스 운영에서는 화면 공유로 얼버무릴 수 없으므로 로그 한 줄 한 줄이 그대로 감사 흔적이 됩니다. 따라서 node 실체 경로와 npm prefix를 티켓에 붙이는 습관이 주말 장애 대응 시간을 가장 줄입니다. 여러 벤더 용어가 섞이면 같은 말의 클라우드 Mac도 구현이 다르며 여기서는 KVMNODE 전용 노드라는 전제로 진행합니다.
nvm을 넣은 개인 홈과 서비스 계정 홈을 혼동하지 마십시오. launchd가 읽는 plist EnvironmentVariables와 대화 로그인의 .zprofile은 별개입니다. 비대화형 doctor는 그 차이를 열거하므로 JSON을 손으로 자르기 전에 반드시 한 번은 통과합니다.
TTY 존재는 색 프롬프트 이야기가 아니라 설치기가 표준 입력을 읽으려 하는지에 직결합니다. CI용 플래그가 있는 공식 경로라면 curl도 좋습니다만 없으면 npm 전역과 명시 PREFIX 조합이 재현성에서 이깁니다. PREFIX를 바꾼 날에는 PATH 줄도 같은 티켓에 써서 다음 주 자신이 길을 잃지 않게 합니다.
node -v만이 아니라 which node와 which openclaw도 출력해 nvm과 시스템 Node 이중 선로를 드러냅니다.
launchd나 비로그인 SSH용 로그인 PATH: 게이트웨이를 돌릴 것과 같은 세션 유형으로 검증하고 bash -l 안에서만 녹색으로 만들지 마십시오.
TTY 없는 프롬프트 설치기: CI 플래그 존재를 확인하고 무한 curl 재시도 대신 PREFIX를 밝힌 npm 전역으로 전환합니다.
doctor를 건너뛰고 JSON만 수동 편집: 반쪽 상태를 부릅니다. 비대화형 doctor는 최소한 체크리스트를 뱉습니다.
게이트웨이를 바로 0.0.0.0에: 먼저 루프백 검증을 시작하고 터널과 Tailscale은 원격 액세스를 따릅니다.
공유 SSH 계정에서도 공유 노드 거버넌스와 같은 변경 템플릿에 이 검사를 복사해 npm prefix를 덮어쓰거나 두 openclaw 바이너리를 섞지 않습니다.
달력 프리즈 창도 적습니다. 벤더 유지보수와 Apple 업데이트와 OpenClaw 릴리스가 같은 주에 겹칠 수 있으며 마이너 npm 업데이트를 허용할지 고정할지 정하지 않으면 사후 분석이 실제 변경이 아니라 유령을 탓합니다.
한국에서 싱가포르 상주를 시험하는 경우와 미국 서부 M4 Pro를 고르는 경우 왕복 시간이 달라지지만 doctor 논리 순서는 같습니다. 차이는 큰 node_modules를 몇 번이나 깨고 고치는 작업에 몇 시간 기다리느냐 하는 체감 비용입니다.
보안 팀에는 헤드리스라도 감사 로그를 남기는 것과 터널 종단 노트북 쪽 로컬 포트가 누구의 프로세스 공간인지 미리 합의하면 나중의 몰랐다가 줄어듭니다.
행렬: curl 대 npm, 가까운 지역 상주 대 먼 M4 Pro
헤드리스 설치는 멋진 명령을 고르는 것이 아니라 지금 TTY와 세션 유형 아래에서 완료를 증명하는 것입니다. 표를 내부 위키 책임표 옆에 붙이고 CLI 정렬과 같은 노트에 둡니다. macOS 앱 셸이 없으면 어떤 바이너리가 게이트웨이를 돌리는지에 대한 진실은 CLI뿐입니다.
| 경로 | 맞는 경우 | 리스크 |
|---|---|---|
| 공식 curl 스크립트 | TTY가 있거나 CI 플래그가 먹힘 | TTY 없으면 확인에서 정지 |
| npm 전역 openclaw | PREFIX 고정 순수 자동화 | 전역 bin이 PATH에 없음 |
| 정리 없는 혼합 | 권장하지 않음 | 이중 바이너리 유령 |
| 호스트 프로필 | 전형적 사용 | M4 Pro로 옮길 때 |
|---|---|---|
| 가까운 M4 16GB 또는 24GB | 저지연 상주, 가벼운 프로브 | 병렬 채널이나 무거운 의존 컴파일 |
| 먼 M4 Pro 64GB | 긴 doctor 복구 루프 | 지연 SLA를 예산이 허용 |
| 원격 게이트웨이 모드 | 클라이언트는 로컬, 게이트웨이는 클라우드 | 원격 게이트웨이 참조 |
헤드리스 수락은 Node와 which 경로에서 시작하고 그다음 포트와 토큰입니다.
조달과 플랫폼은 포크를 분위기가 아니라 발주란 문장에 썼을 때만 수렵합니다.
운용 비용은 렌탈료만이 아니라 감사 불가능한 트리아지 시간입니다. 이 주 동안 curl 대 npm 종료 코드와 stderr 마지막 스무 줄과 doctor 요약을 모든 티켓에 첨부하면 스크립트 문제인지 네트워크 문제인지 데이터로 답합니다. 지역 렌탈 조건이 RTT를 변경 티켓에 고정하는 것처럼 여기서는 PREFIX와 리슨 포트가 앵커입니다.
에이전트 마케팅 이후 사건 건수가 튀면 npm 전역을 누가 소유하고 OpenClaw 설정이 어느 홈을 가리키는지를 표준화하고 위키 색인에 한 줄로 적는 것이 가장 빠른 승리입니다. 그 페이지가 sudo 경계를 신경 쓰는 보안과 재현성을 신경 쓰는 릴리스 공정의 악수가 됩니다.
표의 혼합 행은 실무에서 가장 흔한 패배 패턴입니다. 오래된 curl 잔해와 새 npm bin이 둘 다 PATH에 있고 launchd만 오래된 쪽을 집습니다. 주간 가벼운 스냅샷 잡으로 which 한 줄을 이력화하면 차분 검지가 쉬워집니다.
한국이나 홍콩에서 본 미동과 미서 차이는 지도 거리만이 아니라 피어링과 혼잡 시간대로 변합니다. 그래서 수락 테스트는 우리 사무실 체감이 아니라 클라우드 호스트 루프백과 그다음 터널로 두 단계로 나눕니다.
행렬을 붙인 뒤 책임자 이름과 롤백 절차 짧은 각주를 같은 블록에 두면 신입이 표만 복사해 동사를 떨어뜨리는 사고가 줄어듭니다.
openclaw doctor --non-interactive 읽기와 SSH 터널 경계
비대화형 doctor는 빈틈을 잡담이 아니라 정렬 가능한 작업 항목으로 바꿉니다. 연속 SSH 세션에서 환경 변수가 달라지지 않게 클라우드 호스트에 안정된 환경 파일을보낸 뒤 doctor를 실행합니다. 노트북이 게이트웨이에 닿아야 하면 클라우드 루프백에서 노트 로컬 포트로 SSH 로컬 포워드를 우선하고 실험 중 0.0.0.0에 노출하는 대신 원격 액세스에서 Tailscale 같은 장수 경로를 평가합니다.
node -v which node which openclaw openclaw doctor --non-interactive ssh -N -L 18789:127.0.0.1:18789 user@cloud-mac-host
팁: 포트와 라벨은 환경마다 다릅니다. 터널 줄은 예시이며 운영 문구는 설치 글과 원격 글에 맞춥니다.
doctor와 게이트웨이 상태가 어긋나면 상태를 지우기 전에 진단 사다리를 오릅니다.
첫 SSH에서 LANG을 C.UTF-8로 맞추고 LC_ALL을 고정하면 데스크톱에서는 드문 로케일 분기를 줄입니다. ulimit -n을 수락 필드에 기록해 작은 SKU에서 장수 소켓이 한도에 걸리는 것을 먼저 막습니다.
터널 줄의 사용자명과 호스트명은 실제 발주서 표기와 일치시킵니다. 공유 배스천이면 배스천과 타깃의 이단 SSH 중 어디서 전환할지 한 문장으로 고정하지 않으면 주번 담당이 매번 다른 해법을 시도합니다.
doctor 출력을 그대로 첨부 파일로 두면 나중에 diff를 뗄 수 있습니다. 채팅 복사는 줄바꿈이 깨지기 쉬워 증적으로 약합니다.
여섯 단계: 헤드리스 OpenClaw 가동을 수락 필드로 인코딩
Node 메이저 동결: 스무 이상으로 문서화하고 대상 세션 유형에서 node -v와 경로를 인쇄합니다.
npm 전역 prefix 고정: npm prefix -g와 PATH를 같은 티켓에 저장합니다.
curl 또는 npm: TTY와 플래그를 기록하고 실패하면 맹목 재시도 대신 경로를 바꿉니다.
doctor 비대화 실행과 출력 보관: 빌드 산출물로 업로드해 재생합니다.
루프백 검증 후 터널: 리전 표기는 주문 페이지에 맞춥니다.
cron 프로브 등록: cron 헬스 프로브와 스플릿 브레인 경계를 런북에 링크합니다.
여섯 단계에도 롤백 줄이 필요합니다. 전역 패키지 제거, 이전 plist 복원, 터널 종료를 위키 푸터에 명령 하나씩 써서 새벽 세 시에 전체 호스트 재구축만 강요하지 않습니다.
단계 순서를 바꾸면 포트가 열린 것처럼 보이나 실제로는 다른 프로세스가 잡는 고전 함정으로 돌아갑니다. 번호는 관습으로 존중하십시오.
수락 항목은 제품 릴리스 노트 언어와 맞추면 개발과 운용 대화가 짧아집니다. 여기서는 OpenClaw 쪽 용어에 맞추고 KVMNODE 쪽 리전 이름은 주문 화면 표기에 맞춥니다.
참조 정책: 세션 유형, 비대화 규율, 에스컬레이션 순서
세션 유형: 로그인 대화형, 비로그인, TTY 할당 세 가지에서 which와 doctor를 각각 한 번씩 실행합니다.
비대화: 무인 단계는 명시 종료 코드로 끝내고 stderr를 삼키지 않습니다.
에스컬레이션: doctor 통과 후에만 사다리와 launchd 토큰으로 분기하고 상태 확인을 건너뛰지 않습니다.
경고: 공유 배스천에서 관리 포트를 노출하면 보안 기준을 위반할 수 있습니다. 터널과 ACL 변경은 변경 관리에 넣습니다.
여러 에이전트 제품군에서는 주간 가벼운 스냅샷 잡을 돌립니다. 같은 스크립트가 로그인해 which를 인쇄하고 doctor를 실행하고 게이트웨이 상태를 한 줄로 가져옵니다. 임계를 넘는 차분만 사람이 깊게 파고칩니다. 이렇게 하면 페이저 노이즈가 줄고 진짜 스플릿 브레인이나 토큰 표면만 뜹니다.
정책 C는 온콜과의 계약입니다. doctor가 녹색이 되기 전에 에스컬레이션한 티켓은 체크리스트 링크로 되돌려 시니어 시간을 추측 편집으로 태우지 않습니다. 분기마다 이 규율은 주말 페이지를 줄이고 설정 저장소 blame도 깨끗해집니다.
마지막으로 하드웨어 세대를 소프트웨어 버전과 같은 표에 넣습니다. M4와 M4 Pro는 CLI 버전이 같아도 네이티브 애드온 컴파일과 링크가 통합 메모리 대역폭을 먹으므로 doctor 복구 병렬도 상한이 달라집니다.
재무가 헤드리스에 두 번째 SKU가 왜 필요한지 물으면 최근 세 건 평균 복구 시간으로 답합니다. PATH 표류가 주원인이면 싼 노트북은 그 수치를 내리지 못합니다.
임시로 노트북을 게이트웨이 호스트로 쓰면 Node 버전과 PATH와 리슨 인터페이스가 개인 습관에 숨고 밤에 연결이 뒤집힌 이유를 설명할 수 없게 됩니다. 리전과 SKU와 큐 의미가 밝힌 전용 Apple 실리콘 클라우드로 계약하면 상주가 공학이 됩니다. 싱가포르·일본·한국·홍콩·미동·미서를 가로지르는 팀이 가까운 지역 검증에서 먼 M4 Pro 상주로 갈 때 KVMNODE Mac mini 클라우드 렌탈이 운용상 강한 선택이 되기 쉽습니다. 베어메탈 분리와 설정 단계 검증과 탄력 렌탈 조건이 맞습니다. 안내는 고객 센터와 가격 페이지를 보십시오.