비행 전 · 의사 · 오류 매트릭스 · 재현 가능한 배포
첫 번째 채널을 연결하는 빌더일반적으로 약한 모델이 아닌 "게이트웨이가 시작되지 않습니다"에서 멈춥니다. 노드 버전, 디렉터리 권한,.envYAML 드리프트, 사용량이 많은 포트, 프록시 및 DNS는 각각 빨간색 로그로 폭발할 수 있습니다. 이 가이드는비행 전 체크리스트,최소 대 다중 채널비교,여섯 가지 진단 단계(포함openclaw doctor),오류 증상 매트릭스, 그리고클라우드 마이그레이션 자체 점검. pm2 및 상시 가동 기준선에 대해서는 다음을 읽어보세요.영구 클라우드 배포 플레이북; 가격 책정 컨텍스트를 보려면 공개하세요.임대 가격.
설치 스크립트는 짧아 보입니다. 비용이 많이 드는 부분은 런타임 가정을 작성하는 것입니다. 즉, 어떤 사용자가 게이트웨이를 시작하는지, 구성이 확인되는 위치, 기본 로그 경로, 어떤 포트가 비어 있어야 하는지, 프록시/DNS를 소유하는 사람이 누구인지 등입니다. 많은 "게이트웨이가 시작되지 않음" 사고는 OpenClaw 로직이 아닌 Node와 macOS 권한 상호 작용에서 발생합니다. 아래의 5가지 공백은 커뮤니티 스레드에 지속적으로 표시됩니다. PATH 드리프트를 발견하기 전에 세 번 다시 설치하지 않도록 Runbook에서 캡처하세요.
다음에 Slack이나 Telegram을 계획하고 있다면 다음을 결정하세요.토큰 순환그리고최소 권한 디렉터리일찍; 오래된 환경 변수로 첫 번째 채널이 성공하면 두 번째 회전이 고통스럽습니다.
노드 및 패키지 관리자 드리프트:OpenClaw는 최신 Node LTS를 기대합니다. nvm, fnm 및 시스템 노드를 혼합하면 종종 올바른 결과가 나옵니다.node -v터미널에는 있지만 프로세스 감독자 아래에는 오래된 바이너리가 있습니다. 하나의 골든 호출을 고정하고 의사 출력에서 실제 바이너리를 확인하세요.
작업 디렉터리 및 권한 경계:데스크탑 또는 iCloud 지원 폴더에 복제하면 잠금 또는 권한 문제가 발생합니다. 서비스 사용자 홈 및 문서 쓰기 가능한 AgentSkill 경로의 전용 하위 트리 아래에 프로덕션 트리를 유지합니다.
포트 및 방화벽 기본값:다른 데몬과 충돌하는 대시보드 및 게이트웨이 리스너는 즉시 종료됩니다. 회사 프록시 또는 호스트 방화벽이 아웃바운드 LLM 통화를 차단할 수 있습니다. 프리플라이트에 포트 스캔과 한 줄 아웃바운드 컬 스모크 테스트를 추가합니다.
다중 구성 소스: .env, 쉘 프로필, launchd/pm2 env 블록 및 YAML 오버레이는 함께 "잘못된 파일을 편집했습니다" 버그를 생성합니다. 단일 진실 소스와 문서 우선순위를 선택하세요.
로깅 및 관찰 가능성의 격차:stdout 대상 및 회전이 없으면 첫 번째 장기 실행에서 디스크를 채우거나 실제 오류를 스크롤하여 버립니다. 설치 시 경로 및 유지를 수정합니다. 모니터를 새로 장착하는 것보다 훨씬 저렴합니다.
목록을 확인한 후 다음 섹션(최소 게이트웨이 전용 또는 다중 채널 프로덕션 토폴로지)에서 설치 경로를 선택하세요.
첫날 Slack, 메일, 웹후크를 켜면 실패 매트릭스가 폭발적으로 늘어납니다. 더 안전한:정상적인 로그가 있는 가장 작은 프로필에서 게이트웨이를 부팅합니다.그런 다음 변경 창당 하나의 채널 어댑터를 추가하여 롤백이 명확하게 유지되도록 합니다. 이 표는 첫 번째 검토에 대한 기대치를 조정합니다.
| 차원 | 최소(게이트웨이 + 단일 채널 또는 CLI) | 다중 채널 증분 |
|---|---|---|
| 목표 | 프로세스 검증, 구성 구문 분석, LLM 송신, 기본 기술 | 라우팅, 토큰 순환, 동시 세션 격리 검증 |
| 구성 표면 | 소수의 환경 변수, 얕은 YAML | 많은 웹훅/토큰 오류 표면이 빠르게 증가함 |
| 분류 순서 | 게이트웨이 로그와 의사를 먼저 사용한 다음 모델 API를 사용합니다. | 에이전트 오류와 채널 오류를 분리하세요. |
| 롤백 비용 | 낮음 - 하나의 어댑터와 차이점에 대해 설명합니다. | 높음 - 채널별 스냅샷 유지 |
| 다음에 가장 적합 | 처음으로 빌더와 소규모 팀 | Runbook을 사용하여 프로덕션으로 향하는 팀 |
어댑터 이전에 유휴 게이트웨이를 안정화합니다. 순서를 바꾸면 하나의 로그 스트림에 세 가지 오류 클래스가 쌓입니다.
이 단계는 격리됩니다.프로세스 수준 실패(부팅 시 종료, 잘못된 구성, 사용 중인 포트). 프로세스가 정상이지만 메시지가 도착하지 않는 경우 게이트웨이가 녹색으로 표시된 후에만 어댑터를 디버그하세요. 커뮤니티 CLI가 자주 제공됩니다.openclaw doctor(또는 수정 변형) — 릴리스 노트의 정확한 하위 명령을 대체합니다.
재현 명령을 고정합니다.티켓에 npm 스크립트, 글로벌 CLI, pm2, cwd를 기록합니다.
환경 자체 검사를 실행합니다.실행하다openclaw doctor, 전체 출력을 보관하고 노드 경로, 권한 거부, 누락된 Deps 및 스키마 오류를 원으로 표시합니다.
레이어의 구성을 확인합니다.YAML/JSON을 구문 분석한 다음 환경 변수가 셸 프로필에 의해 재정의되지 않았는지 확인합니다.
청취자를 확인하십시오.대시보드 및 게이트웨이 포트가 사용 가능한지 확인하십시오. 루프백에 대한 VPN 문제를 참고하세요.
처음 200개의 로그 줄을 캡처합니다.첫 번째 ERROR에서 위쪽으로 이동합니다. 근본 원인은 경고보다 먼저 나타나는 경우가 많습니다.
최소 롤백 테스트:선택적 어댑터 및 타사 기술을 비활성화하고 하나의 공식 샘플을 유지한 다음 복원을 양분합니다.
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
팁: doctor --fix로컬 구성을 변경합니다. 즉, 프로덕션 노드에서 사용하기 전에 파일을 스냅샷하거나 변경 제어를 실행합니다.
이를 통화 중 치트 카드로 사용하십시오. 증상을 일치시키고 첫 번째 조치를 실행한 다음 검색 범위를 넓히십시오. 세 번의 통과가 실패하면 섹션 3으로 돌아가 전체 로그를 기록하고 이등분합니다.
| 징후 | 가능한 원인 | 첫 번째 조치 |
|---|---|---|
| 즉시 종료, 스택 없음 | PATH의 노드 불일치 또는 잘못된 바이너리 | nvm/pm2 노드 정렬; 재실행 의사 |
| YAML/JSON 구문 분석 오류 | 들여쓰기, 인코딩, 정크 병합 | 구문 유효성을 검사합니다. 최소 구성 복원 |
| 이미 사용 중인 포트 | 좀비 프로세스 또는 충돌하는 데몬 | lsof, 포트를 해제하거나 변경하세요. |
| LLM 시간 초과/TLS 오류 | 프록시, DNS, 기업 MITM | 컬 출구 테스트; 신뢰 체인 / HTTPS_PROXY |
| 프로세스가 진행되는 동안 채널 인증이 실패합니다. | 만료된 토큰 또는 웹훅 URL 드리프트 | 비밀을 회전합니다. 콜백 호스트 확인 |
| AgentSkill EACCES | 파일 시스템 권한 또는 샌드박스 | 소유권을 수정하세요. 감사 기술 스크립트 |
경고:반복을 피하세요sudo npm install -g프로세스 모델을 이해하지 못한 채 — 런타임이 여전히 잘못된 모듈 트리를 해결하는 동안 전역은 "설치됨"을 보고할 수 있습니다.
설치 소방 및 장기 신뢰성은 인접한 분야입니다. 첫 번째는 재현 가능한 콜드 스타트를 최적화하고 두 번째는 충돌 복구 및 감사 가능성을 최적화합니다. 이러한 측정 가능한 프롬프트는 업스트림 문서를 교체하지 않고도 검토하는 데 도움이 됩니다.
노트북이 만날 수 없을 때무인그리고제로 대화상자요구 사항, 클라우드 자체 검사를 통해 Guardian 재시작 정책 추가, 대시보드 노출 및 로그 순환 — 프로덕션 앵커를영구 클라우드 플레이북.
보안 알림:전체를 붙여넣지 마세요..env파일을 채팅에 넣습니다. 만료되는 비밀 채널과 문서 철회를 사용하세요.
절전 모드, 업데이트 및 공유 세션을 저글링하는 노트북은 작업 설치로 해결할 수 없는 무작위성을 주입합니다. 전용 지역 배치 클라우드 Mac 노드를 사용하면 "뚜껑이 열려 있을 때 부팅"보다 "매일 부팅"이 더 쉬워집니다. OpenClaw를 제공 표준에 맞추는 팀의 경우,일반적으로 VpsMesh Mac Mini 클라우드 대여가 더 적합합니다.: 기본 Apple Silicon, 연중무휴 금속, 유연한 임대 창구 - 시스템 상태 대신 게이트웨이 로직에 사이클을 소비합니다.