오픈클로 설치 방법|맥미니·윈도우 공식 설치 절차와 비용·준비물 정리
오픈클로(OpenClaw) 설치 방법은 공식 설치 스크립트 1줄과 온보딩 마법사로 시작합니다. 맥미니는 터미널에서 설치 스크립트를 실행하고, 윈도우는 PowerShell 스크립트 또는 WSL2 경로 중 하나를 고릅니다. 설치 프로그램 자체는 오픈소스라 무료입니다. 실제 지출은 연결하는 모델 API 사용량에서 발생합니다.
원본 글(2026년 3월 25일 발행)이 안내하던 Node 22 기준과 openclaw gateway start 중심 절차는 현재 공식 문서와 다릅니다. 2026년 11월 4일 기준으로 공식 저장소 README는 Node 24.22.1 이상 또는 26.12.1 이상을 안내하고, Node 26을 권장합니다. Node 22·23·25는 v2026.9.3 이후 지원 대상이 아니라는 안내가 있습니다. 공식 저장소 설치 안내를 설치 직전 다시 확인하세요. 릴리스 번호는 날짜 기반으로 자주 바뀝니다.
공식 출처는 본문 근거 옆에 함께 적었습니다. 확인일자: 2026년 11월 4일 기준입니다.
오픈클로 설치 방법 핵심 요약: Node 26 권장·설치 스크립트 1줄·온보딩 3단계
오픈클로는 내 컴퓨터에서 돌아가는 개인 AI 어시스턴트입니다. 게이트웨이 하나가 메시지 채널과 모델, 도구 실행을 묶어 줍니다. 텔레그램·디스코드·왓츠앱 같은 채널에서 같은 에이전트와 대화하는 구조입니다.
설치 순서는 세 단계로 정리됩니다. ① 운영체제에 맞는 설치 스크립트를 실행합니다. ② 자동으로 열린 온보딩 마법사에서 모델 연결과 작업 폴더를 정합니다. ③ openclaw gateway status로 게이트웨이 상태를 확인한 뒤 대시보드에서 첫 메시지를 보냅니다.
설치 스크립트는 필요하면 지원되는 Node 런타임까지 준비해 줍니다. Node를 직접 관리하는 분은 npm 경로를 쓰면 됩니다. npm·pnpm·Bun으로 직접 설치한 경우에만 아래 명령으로 온보딩을 시작합니다. npm 12 또는 npm 11.16 이상 환경에서는 아래 명령 형태를 씁니다.
npm install -g openclaw@latest --allow-scripts=openclaw openclaw onboard --install-daemon openclaw gateway status
npm 11.15 이하에서는 --allow-scripts=openclaw 플래그를 빼고 실행한다는 안내가 있습니다. 공식 저장소에서 사용하는 npm 버전 조건을 대조하세요.
오픈클로 설치 방법 준비물: Node 24.22.1 이상·모델 API 키·작업 폴더 3가지
준비물은 세 가지입니다. 지원되는 Node 버전, 모델 제공자 API 키, 에이전트 작업 폴더입니다. 클라우드 모델을 쓰면 API 키가 필요합니다. 로컬 모델만 쓰면 키 없이 시작하는 구성이 가능하지만, 모델 파일 다운로드와 실행 자원이 따로 듭니다.
| 구분 | 게이트웨이 용도 | 로컬 모델 직접 실행 |
|---|---|---|
| 메모리 | 클라우드 모델 연결 시 로컬 부담이 작습니다 | 모델 크기에 따라 메모리·디스크 부담이 커집니다 |
| 모델 | 클라우드 API 키 1개 | Ollama·LM Studio 등 로컬 실행 도구와 모델 파일 |
| 디스크 | 설치 파일 + 작업 폴더 여유 공간 | 모델 파일 수 GB가 추가됩니다 |
Docker는 설치 필수 조건이 아닙니다. 도구는 파일 접근 권한이 넓어질 수 있습니다. 처음에는 전용 기기나 가상 머신, 격리 환경에서 시작하는 편이 안전합니다. 토큰과 API 키는 공개 채팅·캡처 화면에 노출하지 마세요. 관리 화면(Control UI)은 인터넷에 공개하지 않는 것이 공식 문서의 보안 안내 방향입니다.
함께 보면 좋은 글: PC·스마트폰 보안 점검 체크리스트에서 토큰·계정 보호 순서를 먼저 점검할 수 있습니다.

맥미니에 오픈클로 설치 방법: 설치 스크립트 1줄과 온보딩 3단계
맥미니는 24시간 켜 두기 좋은 상주 기기입니다. Apple Silicon 모델의 통합 메모리 구조는 로컬 모델 실행에서 유리합니다. 게이트웨이 용도라면 메모리 크기가 작아도 시작은 가능합니다.
1터미널을 열고 설치 스크립트를 실행하세요
아래 명령 1줄이 설치와 온보딩 시작까지 이어줍니다.
curl -fsSL https://openclaw.ai/install.sh | bash
2자동으로 열린 온보딩 마법사에서 모델·작업 폴더·채널을 정하세요
스크립트 설치에서는 마법사가 자동으로 실행되므로 onboard 명령을 따로 입력하지 않아도 됩니다. 데몬 설치 옵션을 함께 고르면 맥을 재시작해도 게이트웨이가 백그라운드에서 유지됩니다.
npm·pnpm·Bun으로 직접 설치한 경우에만 터미널에서 openclaw onboard --install-daemon을 실행해 온보딩을 시작합니다.
3게이트웨이 상태와 첫 메시지를 확인하세요
상태 확인 뒤 대시보드를 열어 첫 메시지를 보내 보세요. 채널 연결은 그다음 단계로 미뤄도 됩니다.
openclaw gateway status openclaw dashboard
macOS 전용 메뉴 막대 앱이 별도로 안내되기도 합니다. 필수는 아닙니다. 터미널 설치가 끝나면 앱 없이도 게이트웨이와 대시보드 사용이 가능합니다. 공식 저장소 설치 안내에서 macOS 앱 항목을 대조하세요.
에이전트 지시문은 짧게 남기는 편이 좋습니다. 지시문이 길어지면 에이전트 응답이 느려지고 토큰 사용이 늘어납니다. 자주 쓰는 지시만 짧게 남기고 나머지는 별도 문서로 빼는 편이 좋습니다.

윈도우에 오픈클로 설치 방법: PowerShell 1줄과 WSL2 권장 경로 2가지
윈도우는 두 갈래입니다. PowerShell 스크립트로 네이티브 경로를 타거나, WSL2 안의 우분투 환경에서 리눅스 경로를 탑니다. 공식 설치 안내도 WSL2 경로를 안내하며, 커뮤니티 설치 문서는 WSL2를 권장 경로로 적고 있습니다. 리눅스 방식 절차를 그대로 옮길 계획이면 WSL2 경로가 마찰이 적습니다.
1네이티브 경로: PowerShell을 관리자 권한으로 여세요
아래 명령 1줄로 윈도우용 설치 스크립트를 실행합니다.
iwr -useb https://openclaw.ai/install.ps1 | iex
2WSL2 경로: 우분투를 설치한 뒤 리눅스 스크립트를 쓰세요
PowerShell에서 wsl --install을 실행하고 재부팅합니다. 우분투 터미널 안에서 macOS와 같은 설치 스크립트를 실행합니다.
wsl --install curl -fsSL https://openclaw.ai/install.sh | bash
3두 경로 모두 자동으로 열린 온보딩 마법사와 상태 확인으로 마무리하세요
WSL2 안에서 게이트웨이가 돌아갈 때 윈도우 쪽 브라우저·메신저 접근이 막히면, 온보딩 출력 주소와 바인딩 설정을 먼저 확인하세요.
openclaw gateway status
npm·pnpm·Bun으로 직접 설치한 경우에만 openclaw onboard --install-daemon으로 온보딩을 시작합니다.
윈도우 허브 동반 앱이 별도로 안내되기도 합니다. 설정·트레이 상태·채팅을 돕는 선택 사항입니다. 설치 자체는 위 스크립트만으로 진행됩니다. 윈도우 시작 시 자동 실행 여부는 데몬·서비스 등록 결과로 갈립니다. 윈도우 시작프로그램 폴더 위치 찾는 방법도 함께 확인하면 시작 동작 점검에 도움이 됩니다.
오픈클로 설치 방법 비용: 프로그램 무료·모델 API 사용량 과금·로컬 실행 자원 3가지
오픈클로 설치 프로그램 자체는 MIT 라이선스 오픈소스입니다. 설치 비용은 0원입니다. 지출이 생기는 지점은 모델 호출입니다. 클라우드 모델 API는 호출량·모델 등급에 따라 과금이 달라집니다. 제공자별 요금표가 수시로 바뀌니 설치 당일 요금 페이지를 확인하세요.
로컬 모델만 쓰면 API 과금은 없습니다. 대신 모델 파일 저장 공간과 실행 시간의 전기·발열 부담이 남습니다. 맥미니를 24시간 켜 두면 전기료가 고정 지출로 붙습니다. 서버(VPS)에 올리면 서버 요금이 추가됩니다. 이 글에서는 특정 요금제를 단정하지 않습니다. 제공자 요금표가 없는 수치는 적지 않았습니다.
비용을 줄이는 실전 순서는 단순합니다. 가벼운 정리·요약은 작은 모델이나 로컬 모델에 맡기고, 추론이 무거운 작업만 큰 모델로 보냅니다. 에이전트가 백그라운드에서 계속 도는 설정은 토큰 사용을 키웁니다. 주기 실행 간격과 메모리 조회 범위를 먼저 좁히세요.
오픈클로 설치 방법 오류 해결: command not found·게이트웨이 미기동·채널 연결 실패 3가지
가장 잦은 오류는 command not found: openclaw입니다. 전역 설치 경로가 셸 PATH에 없어서 생깁니다. 새 터미널을 열고 openclaw --version 출력을 확인하세요. nvm·pnpm 환경에서는 셸 설정 파일(~/.zshrc 등)에 전역 경로를 추가한 뒤 설정을 다시 읽어야 합니다.
게이트웨이가 뜨지 않으면 openclaw gateway status와 openclaw doctor 출력을 먼저 보세요. 포트 충돌이나 설정 오류가 원인인 경우가 많습니다. 설치 스크립트를 덮어씌우기 전에 설정 파일 백업부터 만드세요. 설정 파일 위치는 ~/.openclaw/openclaw.json으로 안내됩니다.
채널 연결은 별도 단계입니다. 디스코드는 개발자 포털에서 봇 애플리케이션을 만들고 토큰을 발급받습니다. 메시지 내용 인텐트 설정이 빠져 있으면 메시지를 읽지 못합니다. Discord 개발자 포털에서 봇·인텐트·초대 권한을 대조하세요. 텔레그램 PC 설치 순서는 텔레그램 PC버전 다운로드 정리를 참고하세요.
⚠️ 주의: 오래된 글의 명령어를 그대로 복사하지 마세요. Node 22 전제와 구버전 게이트웨이 시작 명령이 섞인 절차는 현재 환경에서 실패할 수 있습니다. 설치 당일 공식 문서의 Node 조건과 온보딩 명령을 다시 확인하세요.
💡 팁: 저는 처음 설치하시는 분께 설치 스크립트 경로를 먼저 권합니다. Node 버전까지 스크립트가 챙겨 주기 때문입니다. npm 경로는 Node를 직접 관리하는 분께 어울립니다.
오픈클로 설치 방법 영상: freeCodeCamp 초보자 강좌 1편과 화면 속 버전 주의점
아래 영상은 freeCodeCamp 유튜브 채널의 초보자 강좌입니다. 설치부터 왓츠앱·디스코드 연결, 메모리 관리까지 한 강좌로 이어집니다. 본문 명령과 화면이 다르면 본문의 최신 공식 기준을 우선하세요. 강좌는 2026년 2월 공개본이라 화면 속 Node 버전 안내가 현재 공식 기준과 다를 수 있습니다.
출처: freeCodeCamp 유튜브 채널 강좌(영상 바로 보기), 강좌 안내 페이지 freeCodeCamp 강좌 소개.
오픈클로 설치 방법 자주 묻는 질문 6가지
Q 프로그래밍 지식이 없어도 오픈클로 설치가 가능한가요?
A 설치 스크립트 1줄과 온보딩 마법사로 시작은 가능합니다. 터미널 명령 입력과 오류 메시지 확인에는 익숙해질 필요가 있습니다.
Q 클라우드 API 없이 로컬 모델로만 오픈클로를 쓸 수 있나요?
A 가능합니다. Ollama·LM Studio 같은 로컬 실행 도구와 모델 파일을 연결하면 됩니다. 복잡한 도구 호출 안정성을 원하면 코딩 특화 모델을 고르는 편이 좋습니다.
Q 맥미니 8GB 모델로 오픈클로 설치가 되나요?
A 게이트웨이 용도라면 작은 메모리에서도 시작이 가능합니다. 로컬 모델을 직접 돌리면 모델 크기에 맞는 여유 메모리가 필요합니다.
Q command not found: openclaw 오류는 어떻게 해결하나요?
A 전역 설치 경로가 PATH에 없어서 생기는 경우가 많습니다. 새 터미널에서 버전을 확인하고, nvm·pnpm 환경이면 셸 설정 파일에 전역 경로를 추가한 뒤 다시 읽어 들이세요.
Q 오픈클로 설치 비용은 얼마인가요?
A 설치 프로그램 자체는 오픈소스라 무료입니다. 지출은 모델 API 사용량, 서버 요금, 24시간 상주 기기의 전기료에서 발생합니다. 요금표는 제공자 페이지에서 설치 당일 확인하세요.
Q 오픈클로 사용 시 개인 파일이 외부로 유출되나요?
A 로컬 모델만 쓰면 프롬프트가 외부 모델 서버로 가지 않습니다. 클라우드 모델을 연결하면 입력 내용이 해당 제공자 서버로 전송됩니다. 민감한 파일은 접근 범위를 먼저 좁히세요.
오픈클로 설치 방법 최종 체크리스트: 설치 전·설치 중·설치 후 8항목
✅ 한눈에 보는 최종 체크리스트
☐ Node 조건 확인: 24.22.1 이상 또는 26.12.1 이상, Node 26 권장
☐ 경로 선택: 맥미니 설치 스크립트 / 윈도우 PowerShell / 윈도우 WSL2
☐ 모델 결정: 클라우드 API 키 또는 로컬 모델 실행 도구
☐ 온보딩 진행: 스크립트 설치 시 자동 실행되는 마법사 진행 (npm 직접 설치 시 openclaw onboard –install-daemon)
☐ 상태 확인: openclaw gateway status 후 대시보드 첫 메시지
☐ 보안 점검: 토큰 비공개, 관리 화면 비공개, 접근 범위 축소
☐ 채널 연결: 디스코드·텔레그램은 설치 완료 후 별도 단계로 진행
☐ 비용 점검: API 사용량·서버 요금·상주 기기 전기료 확인
함께 보면 좋은 글: 무료 오픈소스 툴 7선 · 텔레그램 PC버전 다운로드 정리 · PC·스마트폰 보안 점검 체크리스트 · 윈도우 시작프로그램 폴더 위치 찾는 방법
📎 공식 출처: OpenClaw 공식 저장소 설치 안내 · freeCodeCamp 초보자 강좌 소개 · Discord 개발자 포털
※ 본문 명령어와 Node 조건은 2026년 11월 4일 기준으로 확인한 내용입니다. 오픈클로 릴리스 주기가 짧아 설치 직전 공식 문서 재확인이 필요합니다.




