솔직히 말씀드리면, Windows에서 OpenClaw를 설치하는 것은 macOS나 Linux보다 조금 더 복잡합니다. Windows 환경에는 환경 변수, 사용자 권한 모델, 도구 체인 호환성 측면에서 Unix 기반 시스템에는 없는 고유한 과제가 존재합니다. 적절한 가이드 없이는 특정 단계에서 막혀 불명확한 오류 메시지와 함께 어떻게 진행해야 할지 모르는 상황이 생기기 쉽습니다.
이 가이드는 실제 설치 경험을 바탕으로 작성되었으며, 가장 흔한 실패 지점과 그 해결책을 모두 포함합니다. 모든 단계는 Windows 10과 Windows 11 클린 설치 환경에서 검증되었습니다. 순조로운 설치 과정뿐만 아니라 각 단계별 상세한 문제 해결 가이드도 함께 제공합니다.
이 가이드를 끝까지 따라 하면 브라우저에서 완전히 작동하는 OpenClaw 인스턴스를 갖게 되고, 원하는 AI 제공업체에 연결되며, 재시작 후 다시 실행하는 방법도 정확히 알게 됩니다.
⚙️ 시스템 요구사항
시작하기 전에 사용 중인 컴퓨터가 아래 최소 사양을 충족하는지 확인하세요. 최소 사양 이하의 하드웨어에서 OpenClaw를 실행하면 느린 성능, 빌드 실패 또는 예기치 않은 충돌이 발생할 수 있습니다.
- 운영체제: Windows 10(64비트) 또는 Windows 11. 32비트 Windows나 Windows 10보다 오래된 버전은 지원되지 않습니다.
- RAM: 최소 2 GB, 권장 4 GB 이상. 8 GB는 특히 빌드 단계에서 훨씬 부드러운 경험을 제공합니다.
- CPU: 최소 2코어. 2015년 이후 제조된 대부분의 컴퓨터는 이 요구사항을 충족합니다.
- 여유 디스크 공간: 최소 1 GB, 권장 4 GB. Node.js 런타임, Git, OpenClaw 소스 트리, 설치 중 생성되는 node_modules 디렉터리에 필요한 공간입니다.
- 인터넷 연결: 설치 중 Node.js, Git, npm/pnpm 패키지를 다운로드하는 데 필요합니다. 안정적인 연결이 가장 흔한 설치 실패를 방지합니다.
⚠️ 보안 참고사항: 메인 컴퓨터에서 OpenClaw를 실행하는 것에 우려가 있다면 VPS나 가상 머신에 배포하는 것을 고려하세요. 기능 손실 없이 메인 환경을 안전하게 유지할 수 있습니다.
📦 1단계: Node.js 설치
OpenClaw는 Node.js 애플리케이션입니다. Node.js가 올바르게 설치되어 있지 않으면 설치 프로세스의 어떤 부분도 작동하지 않습니다. 이것이 첫 번째 필수 의존성입니다.
1.1 왜 Node.js v22 이상이 필요한가
OpenClaw의 코드베이스는 Node.js v22에서 도입된 현대적인 JavaScript API와 Node.js 고유 기능을 활용합니다. 여기에는 V8 엔진의 향상된 성능 특성과 업데이트된 내장 모듈이 포함됩니다. 이전 버전을 설치하면 빌드 실패나 런타임 오류가 발생합니다. 설치 전에 프로젝트의 README에서 버전 요구사항을 반드시 확인하세요.
1.2 Node.js 다운로드
브라우저를 열고 Node.js 공식 사이트(nodejs.org)에 접속하세요. 홈페이지에서 「Get Node.js」라고 적힌 버튼을 클릭합니다. 다운로드 섹션으로 이동합니다.
LTS(Long-Term Support)와 Current 두 가지 릴리스 라인이 표시됩니다. 안정적인 설치를 위해 항상 LTS를 선택하세요. LTS 릴리스는 출시 후 최소 30개월간 보안 패치와 버그 수정을 제공받으며, 새 기능보다 안정성을 우선시하는 Current 브랜치보다 훨씬 신뢰할 수 있습니다. LTS 버전 선택 후 「Windows Installer (.msi)」를 클릭하여 설치 프로그램을 다운로드합니다. 파일 이름은 node-v24.x.x-x64.msi 형태입니다.
1.3 Node.js 설치 절차
다운로드한 MSI 파일을 더블클릭하여 설치 프로그램을 실행합니다. Windows가 앱의 변경을 허용할지 묻는 사용자 계정 컨트롤(UAC) 프롬프트를 표시하면 「예」를 클릭합니다. Node.js 설치 마법사가 열리면 다음 단계를 따르세요.
- 환영 화면에서 「Next」를 클릭합니다.
- 최종 사용자 라이선스 계약서를 읽고 「I accept the terms in the License Agreement」에 체크 후 「Next」를 클릭합니다.
- 대상 폴더 화면에서 기본 경로(C:\Program Files\nodejs\)를 유지합니다. 변경하면 PATH 문제가 발생할 수 있습니다. 「Next」를 클릭합니다.
- 사용자 지정 설치 화면에서 npm 패키지 관리자를 포함한 모든 구성 요소를 기본값으로 유지하고 「Next」를 클릭합니다.
- 네이티브 모듈용 도구 화면에서 네이티브 Node.js 애드온을 컴파일할 필요가 없다면 체크를 입력할 필요가 없습니다. 「Next」를 클릭합니다.
- 「Install」을 클릭하여 실제 설치를 시작합니다. 진행 표시줄이 나타납니다.
- 설치 완료를 기다립니다(보통 1~3분 소요).
- 「Finish」를 클릭하여 마법사를 닫습니다.
✅ 팁: 진행 표시줄이 잠시 멈춘 것처럼 보여도 설치 과정을 중단하지 마세요. 설치 프로그램은 여러 작업을 수행하며 작업 사이에 잠깐 일시 중지될 수 있습니다.
1.4 Node.js 설치 확인
설치 프로그램이 닫힌 후, Node.js가 올바르게 설치되고 명령줄에서 접근 가능한지 확인해야 합니다.
관리자 권한으로 명령 프롬프트를 엽니다. 작업 표시줄의 검색 아이콘🔍을 클릭하고 「cmd」를 입력합니다. 검색 결과의 「명령 프롬프트」를 우클릭하여 「관리자 권한으로 실행」을 선택하고 UAC 프롬프트에서 「예」를 클릭합니다.
명령 프롬프트에서 다음을 입력하고 Enter를 누릅니다.
node -v
예상 출력:
v24.14.0
v22.x.x 이상의 버전 번호면 설치 성공입니다. 다음으로 Node.js와 함께 설치된 npm 패키지 관리자를 확인합니다.
npm -v
버전 번호(예: 10.9.0)가 출력되면 npm도 정상적으로 작동하고 있습니다.
⚠️ ‘node’를 내부 또는 외부 명령으로 인식할 수 없다는 오류가 나타나는 경우: Node.js가 시스템 PATH에 추가되지 않았거나 현재 터미널 세션이 설치 이전 것입니다. 해결책: 명령 프롬프트 창을 닫고 관리자로 다시 엽니다. 새 세션이 업데이트된 PATH 환경 변수를 불러옵니다.
1.5 pnpm 설치
pnpm(Performant npm)은 OpenClaw가 기본 npm 대신 사용하는 Node.js 패키지 관리자입니다. pnpm이 권장되는 이유를 기술적으로 이해하면 이 추가 단계의 필요성을 이해하는 데 도움이 됩니다.
기술적 수준에서 pnpm은 콘텐츠 주소 지정 가능한 스토리지 모델과 하드 링크 및 심볼릭 링크를 사용하여 패키지를 관리합니다. npm이 각 프로젝트의 node_modules 디렉터리에 패키지 파일을 복사하는 것과 달리, pnpm은 단일 글로벌 스토어를 유지하고 그것을 가리키는 링크를 생성합니다. 이 접근 방식은 세 가지 구체적인 이점을 제공합니다.
- 더 빠른 설치 속도: 반복 설치나 여러 프로젝트 간에는 패키지를 한 번만 다운로드하고 이후에는 링크만 사용하므로 pnpm이 npm보다 2~3배 빠릅니다.
- 디스크 사용량 감소: 여러 Node.js 프로젝트를 유지 관리하는 경우 pnpm의 공유 패키지 스토리지로 몇 기가바이트의 디스크 공간을 절약할 수 있습니다.
- 엄격한 의존성 격리: pnpm은 비평탄 node_modules 구조를 생성하여 선언되지 않은 의존성에 대한 패키지 접근을 방지합니다. npm의 평탄한 구조가 암묵적으로 허용하는 버그 클래스를 방지합니다.
관리자 명령 프롬프트에서 다음 명령어로 pnpm을 전역 설치합니다.
npm install -g pnpm
-g 플래그는 특정 프로젝트가 아닌 시스템 전체에 pnpm을 설치합니다. 출력 결과:
added 1 package in 3s
설치 확인:
pnpm -v
10.32.1과 같은 버전 번호가 표시되면 pnpm을 사용할 준비가 된 것입니다.
⚠️ 설치 직후 pnpm이 인식되지 않는 경우: 명령 프롬프트를 닫고 관리자로 다시 엽니다. PATH 업데이트가 적용되려면 새 터미널 세션이 필요합니다.
🔧 2단계: Git 설치
Git은 업계 표준 버전 관리 시스템입니다. 이 가이드에서는 저장소를 클론하지 않고 ZIP 아카이브로 OpenClaw를 다운로드하지만, Git은 여전히 필요합니다. 이유는 Git for Windows에 번들된 Git Bash라는 Unix 계열 터미널 에뮬레이터가 OpenClaw의 빌드 및 실행 명령을 위한 가장 신뢰할 수 있는 실행 환경을 제공하기 때문입니다.
명령 프롬프트(cmd)와 PowerShell도 많은 작업을 처리할 수 있지만, OpenClaw의 pnpm 스크립트에서 사용되는 특정 셸 스크립팅 패턴은 Unix 호환 환경을 가정합니다. Git Bash는 WSL(Windows Subsystem for Linux)이 필요 없이 Windows에서 그것을 제공합니다.
2.1 Git 다운로드
브라우저에서 Git 공식 사이트(git-scm.com)로 이동합니다. 사이트가 자동으로 OS를 감지하여 적절한 다운로드 버튼을 제공합니다. 「Download for Windows」를 클릭합니다. 다음 페이지에서 「Git for Windows / x64 setup」을 찾아 클릭하여 다운로드를 시작합니다. 설치 프로그램 크기는 약 50~60 MB입니다.
2.2 Git 설치 절차
다운로드한 설치 프로그램(Git-2.xx.x-64-bit.exe)을 더블클릭하여 실행하고 UAC 프롬프트에 동의합니다. Git 설치 프로그램에는 많은 구성 화면이 있습니다. 기본값이 잘 선택되어 있으므로 다음 주요 결정 사항을 제외하고 모두 기본값으로 Next를 클릭하며 진행하면 됩니다.
- 구성 요소 선택: 기본값을 유지합니다. 「Git Bash Here」와 「Git GUI Here」에 체크되어 있는지 확인하세요. 이것들은 파일 탐색기 우클릭 컨텍스트 메뉴에 매우 유용한 옵션을 추가합니다.
- PATH 환경 조정: 「Git from the command line and also from 3rd-party software」(기본값)를 선택합니다. 이렇게 하면 git이 시스템 PATH에 추가되어 명령 프롬프트와 PowerShell 모두에서 접근할 수 있습니다.
- 터미널 에뮬레이터 구성: 「Use MinTTY (the default terminal of MSYS2)」를 선택합니다. MinTTY는 Windows 기본 콘솔보다 기능이 풍부하고 유니코드와 ANSI 색상을 올바르게 처리합니다.
나머지 화면도 기본값으로 Next를 클릭하고 Install 버튼이 활성화되면 클릭합니다. 설치 완료를 기다립니다. 마지막 화면에서 「Launch Git Bash」를 체크하고 「View Release Notes」의 체크를 해제한 후 「Finish」를 클릭합니다. Git Bash가 자동으로 열립니다.
2.3 Git 설치 확인
열린 Git Bash 터미널에서 다음을 입력합니다.
git –version
예상 출력:
git version 2.53.0.windows.1
버전 번호가 표시되면 성공입니다. 설치 중 git이 시스템 PATH에 추가되었으므로 명령 프롬프트에서도 동일한 명령으로 확인할 수 있습니다.
✅ 앞으로의 사용: 이 가이드에서 「Git Bash를 열기」라고 할 때, 시작 메뉴에서 「Git Bash」를 검색하여 「관리자 권한으로 실행」을 선택하거나, 파일 탐색기에서 폴더 안의 빈 공간을 우클릭하여 「Git Bash here」를 선택하면 해당 디렉터리에서 바로 열 수 있습니다.
🦞 3단계: OpenClaw 설치
Node.js, pnpm, Git이 설치되고 확인되었으니 이제 OpenClaw 자체를 설치할 준비가 되었습니다. 이 단계에서는 소스 코드 다운로드, 의존성 설치, 프로젝트 빌드, 초기 설정을 수행합니다.
3.1 OpenClaw 소스 코드 다운로드
브라우저를 열고 OpenClaw의 공식 GitHub 저장소로 이동합니다. 저장소 메인 페이지에서 파일 목록 상단 우측의 초록색 「Code」 버튼을 클릭합니다. 드롭다운 메뉴가 나타나면 「Download ZIP」을 선택합니다.
브라우저가 openclaw-main.zip을 다운로드합니다. 다운로드가 완료되면 컴퓨터에 체계적인 디렉터리 구조를 만들어야 합니다. 파일 탐색기에서 D 드라이브(또는 원하는 위치)로 이동하여 「ai」라는 새 폴더를 만들고, 그 안에 「openclaw」 폴더를 만듭니다. 다운로드한 openclaw-main.zip을 D:\ai\openclaw로 이동하고 우클릭하여 「압축 풀기」를 선택합니다. 압축 해제 후 openclaw-main이라는 폴더가 생성됩니다.
최종 디렉터리 구조는 D:\ai\openclaw\openclaw-main\이 됩니다. openclaw-main 안에는 package.json, tsconfig.json 등의 파일과 각종 소스 디렉터리가 있습니다.
⚠️ 경로 정확성이 중요합니다: 이 전체 경로 D:\ai\openclaw\openclaw-main을 기억해 두세요. 다른 위치를 선택한 경우 이후 모든 명령에서 해당 경로로 대체하세요.
3.2 프로젝트 의존성 설치
OpenClaw는 작동하기 위해 수십 개의 서드파티 Node.js 패키지에 의존합니다. 이것들은 ZIP 다운로드에 포함되어 있지 않으며 npm 레지스트리에서 가져와야 합니다. pnpm이 package.json 매니페스트를 읽어 자동으로 모든 것을 처리합니다.
관리자로 명령 프롬프트를 열고 단계별로 프로젝트 디렉터리로 이동합니다.
d:
활성 드라이브가 D:로 전환됩니다. 계속합니다:
cd ai
cd openclaw
cd openclaw-main
마지막 명령 후 프롬프트는 D:\ai\openclaw\openclaw-main>로 표시되어야 합니다. 이제 의존성을 설치합니다.
pnpm install
pnpm은 package.json과 패키지 잠금 파일을 파싱하고 전체 의존성 트리를 계산한 후 npm 레지스트리에서 패키지 다운로드를 시작합니다. 터미널에 진행 표시기가 표시됩니다. 인터넷 연결 속도에 따라 1~5분 정도 걸릴 수 있습니다.
완료되면 pnpm이 추가된 패키지 수와 소요 시간을 보여주는 요약을 출력합니다. 오류 메시지(빨간색 ERR!로 시작하는 줄)가 없으면 모든 의존성이 올바르게 설치된 것입니다.
⚠️ pnpm install 중 네트워크 오류: 이것이 전체 설치 프로세스에서 가장 흔한 실패입니다. pnpm이 ECONNREFUSED, ETIMEDOUT 또는 유사한 오류를 보고하면 연결 불안정으로 인해 하나 이상의 패키지 다운로드가 실패한 것입니다. 해결책: 동일한 명령을 다시 실행하면 됩니다. pnpm은 이미 다운로드된 패키지를 건너뛰고 재개하도록 설계되어 있어 1~2번의 재시도로 거의 항상 해결됩니다.
3.3 프로젝트 빌드
빌드 단계는 OpenClaw의 TypeScript/JavaScript 소스 코드를 Node.js가 직접 실행할 수 있는 최적화된 JavaScript로 컴파일하는 과정입니다. 이것은 한 번만 수행하면 됩니다. 빌드가 성공하면 소스 코드를 업데이트하거나 메이저 버전 변경 후 재설치하지 않는 한 다시 빌드할 필요가 없습니다.
빌드 단계와 이후 모든 실행 명령에는 일반 명령 프롬프트 대신 Git Bash를 사용하세요. OpenClaw의 빌드 중 pnpm이 호출하는 Unix 스타일 셸 스크립트와의 호환성이 더 높기 때문입니다.
- 권장 방법 — 프로젝트 폴더에서 우클릭: 파일 탐색기에서 D:\ai\openclaw\openclaw-main으로 이동하고, 폴더 안의 빈 공간을 우클릭하여 「Git Bash here」를 선택합니다. Git Bash가 프로젝트 루트에 작업 디렉터리가 설정된 상태로 열립니다.
- 대안 — 시작 메뉴에서: 「Git Bash」를 검색하여 관리자 권한으로 실행한 후 수동으로 이동합니다:
cd /d/ai/openclaw/openclaw-main
Git Bash의 경로 구문은 백슬래시가 아닌 슬래시를 사용하고 D 드라이브는 D:\ 대신 /d/로 참조하는 Unix 스타일임에 주의하세요.
프로젝트 디렉터리에서 Git Bash가 열리면 빌드 명령을 실행합니다.
pnpm build
빌드 프로세스에는 TypeScript 타입 체크, 모듈 번들링, 출력 파일 생성이 포함됩니다. 성공적인 빌드는 30초에서 2분 내에 완료되며 오류 메시지 없이 종료됩니다. 생성된 출력 파일 목록이 표시되면 빌드 아티팩트가 준비된 것입니다.
⚠️ pnpm build가 실패하는 경우: 먼저 작업 디렉터리를 확인하세요. Git Bash에서 pwd를 입력하여 출력이 /openclaw-main으로 끝나는지 확인합니다. 그 다음 node -v로 Node.js 버전이 v22 이상인지 확인합니다. 두 가지가 모두 맞는데도 빌드가 실패한다면 이전 단계에서 pnpm install이 오류 없이 완료되었는지 확인하세요.
3.4 OpenClaw 첫 번째 실행
빌드가 완료되었으니 이제 OpenClaw를 시작할 수 있습니다. Git Bash에서 다음을 실행합니다.
pnpm start
이 명령은 OpenClaw 핵심 서비스를 시작합니다. OpenClaw가 모듈을 로드하고 내부 상태를 구성하는 초기화 로그가 표시됩니다. 로그 출력이 안정될 때까지 기다립니다. 이것은 OpenClaw가 Gateway 연결을 수락할 준비가 되었음을 나타냅니다.
다음으로 Gateway 서비스를 시작합니다. Gateway는 브라우저가 OpenClaw와 통신하는 로컬 HTTP 프록시 역할을 합니다. 두 번째 Git Bash 창을 열고(첫 번째는 pnpm start를 실행한 상태로 유지) 다음을 실행합니다:
pnpm openclaw gateway
몇 초 후 Gateway가 수신 주소를 출력합니다.
http://127.0.0.1:18789
이 URL을 복사하여 브라우저 주소창에 붙여넣고 Enter를 누릅니다. OpenClaw 웹 인터페이스가 브라우저에 로드됩니다.
🎉 축하합니다! OpenClaw가 Windows에서 정상적으로 실행되고 있습니다. 다음 단계는 API 키 설정을 통해 AI 제공업체에 연결하는 것입니다.
3.5 AI 제공업체로 OpenClaw 설정
OpenClaw가 응답을 생성하려면 AI 제공업체의 API key가 필요합니다. 설정 마법사가 연결 과정을 안내합니다. 먼저 Gateway의 Git Bash 창에서 Ctrl + C를 눌러 Gateway를 중지합니다. 그런 다음 설정 마법사를 실행합니다.
pnpm openclaw configure
대화형 설정 마법사가 실행됩니다. 각 프롬프트를 정확히 따라 주세요.
첫 번째 프롬프트 — 「Where will the Gateway run?」: 화살표 키를 사용하여 「Local (this machine)」을 강조 표시하고 Enter를 누릅니다. 이렇게 하면 OpenClaw가 로컬 컴퓨터에서 완전히 실행되도록 구성됩니다.
두 번째 프롬프트 — 「Model」: 이 옵션을 선택하고 Enter를 눌러 AI 제공업체 선택 화면으로 진행합니다.
제공업체 선택: OpenAI, Anthropic, Google, xAI, Minimax 등 지원되는 AI 제공업체 목록이 표시됩니다. 화살표 키로 원하는 제공업체를 강조 표시하고 Enter를 누릅니다. 이미 계정이 있는 제공업체를 선택하는 것을 권장합니다.
리전 선택: 아시아에 위치한 경우 낮은 지연 시간을 위해 「CN」으로 표시된 옵션을 선택합니다. Enter로 확인합니다.
API key 프롬프트: 제공업체 대시보드에서 API key를 붙여넣습니다. API key는 일반적으로 제공업체 콘솔의 API 설정 섹션에서 찾을 수 있습니다. key를 붙여넣고 Enter를 누릅니다.
설정 요약: 마법사가 구성한 모든 설정의 요약을 표시합니다. 정확성을 검토하고 Enter를 눌러 확인하고 저장합니다. 화살표 키로 나머지 옵션을 탐색하고 마지막으로 Enter를 눌러 완료합니다.
⚠️ API key 관련 주의사항: API key는 AI 모델에 대한 프로그래밍 방식의 접근을 허용하며 사용량에 따라 요금이 부과될 수 있습니다. API key는 기밀로 유지하고 공개적으로 공유하지 마세요.
3.6 전체 설정 확인
설정 후 Gateway를 재시작하여 모든 것이 엔드-투-엔드로 작동하는지 확인합니다.
pnpm openclaw gateway
출력에 127.0.0.1:18789가 나타나면 브라우저에서 해당 URL을 엽니다. 이번에는 OpenClaw가 구성한 AI 제공업체에 연결됩니다. 간단한 테스트 메시지를 보내 API key가 유효하고 연결이 작동하는지 확인하세요.
✅ 설정은 영구적입니다. 모든 설정은 디스크의 설정 파일에 저장됩니다. 이후 세션에서는 단 두 개의 명령만으로 OpenClaw를 다시 실행할 수 있습니다.
🔴 자주 발생하는 오류 및 해결 방법
다음은 실제 경험에서 도출된 가장 자주 발생하는 오류들입니다. 각 항목에는 증상, 근본 원인, 정확한 해결 단계가 포함되어 있습니다.
오류 1: 네트워크 오류로 인한 pnpm install 실패
증상: ECONNREFUSED, ETIMEDOUT, fetch failed 등의 네트워크 관련 오류 메시지가 빨간색으로 표시됩니다. 근본 원인: 네트워크 불안정 또는 일시적인 레지스트리 중단으로 인해 하나 이상의 패키지 다운로드가 실패했습니다.
해결책: 동일한 명령을 다시 실행하면 됩니다.
pnpm install
거의 모든 경우 1~2번의 재시도로 충분합니다.
오류 2: ‘pnpm’을 내부 또는 외부 명령으로 인식할 수 없음
증상: npm install -g pnpm으로 pnpm을 설치한 후 pnpm을 입력하면 인식 불가 오류가 반환됩니다. 근본 원인: pnpm 설치로 인한 PATH 환경 변수 업데이트가 현재 터미널 세션에 로드되지 않았습니다.
해결책: 열려 있는 모든 명령 프롬프트 창을 닫습니다. 관리자로 새 명령 프롬프트를 엽니다. pnpm -v로 확인합니다.
오류 3: 액세스 거부 또는 권한 거부
증상: 액세스 거부, 권한 거부 또는 EPERM을 언급하는 오류로 명령이 실패합니다. 근본 원인: 터미널에 시스템 디렉터리에 패키지를 설치할 충분한 권한이 없습니다.
해결책: 명령 프롬프트와 Git Bash를 항상 「관리자 권한으로 실행」으로 엽니다.
오류 4: pnpm build TypeScript 또는 모듈 오류
증상: 빌드가 TypeScript 컴파일 실패, 모듈 누락 또는 구문 오류를 언급하는 빨간색 오류 텍스트를 출력합니다. 근본 원인: 작업 디렉터리가 잘못되었거나 Node.js 버전이 너무 낮거나 pnpm install이 정상적으로 완료되지 않았습니다.
해결책: Git Bash에서 pwd로 디렉터리를 확인하고(/openclaw-main으로 끝나야 함), node -v로 Node.js 버전을 확인합니다(v22 이상이어야 함).
오류 5: Gateway가 시작되지 않거나 포트가 이미 사용 중
증상: pnpm openclaw gateway가 포트가 이미 사용 중이거나 주소가 이미 바인딩되어 있다는 오류를 출력합니다. 근본 원인: 다른 애플리케이션이 이미 포트 18789에서 수신 중이거나 이전 Gateway 인스턴스가 정상적으로 종료되지 않았습니다.
해결책: 작업 관리자(Ctrl+Shift+Esc)에서 기존 Node.js 프로세스를 확인하고 종료한 후(node.exe 찾기) 게이트웨이 명령을 다시 시도합니다.
💡 마치며: 재시작 후 OpenClaw 사용 방법
설치 완료 후 자주 받는 질문이 있습니다: 「컴퓨터를 재시작하면 처음부터 모든 것을 다시 설치해야 하나요?」 답은 단호하게 아니오입니다. 설치된 모든 구성 요소 — Node.js, pnpm, Git, OpenClaw 소스 코드, 의존성, API key 설정 — 은 재시작 후에도 디스크에 유지됩니다.
시스템 재시작 후 OpenClaw를 다시 사용하려면 다음 두 단계만 수행하면 됩니다.
1단계 — 관리자로 Git Bash를 열고 프로젝트 디렉터리로 이동합니다.
cd /d/ai/openclaw/openclaw-main
2단계 — Gateway를 시작합니다.
pnpm openclaw gateway
출력에 127.0.0.1:18789 주소가 나타날 때까지 기다리고, 그것을 복사하여 브라우저에 붙여넣으면 즉시 OpenClaw를 사용할 수 있습니다. Git Bash를 여는 것부터 작동하는 OpenClaw 인터페이스까지의 전체 과정은 30초 이내에 완료됩니다.
✅ 재시작 후 필요한 것은 단 두 개의 명령뿐입니다. 재설치 없음. 재구성 없음. pnpm install이나 pnpm build도 없음. 이 두 명령 시작 시퀀스가 전부입니다.
이 가이드에서 다루지 않은 설치 문제가 발생하면 정확히 어떤 단계에 있었는지와 받은 전체 오류 메시지를 댓글에 남겨 주세요. 정확한 오류 세부 정보가 정확한 지원을 위해 필수적입니다.
◉ 0 Thảo luận Khoa học