OpenClaw 설치 가이드: 가장 빠른 시작 방법

새로운 개발 도구를 도입할 때 가장 귀찮은 건 역시 설치 과정이죠. 환경 변수를 맞추고 필요한 런타임을 일일이 찾는 과정에서 예상치 못한 오류가 나면, 본격적인 개발을 시작하기도 전에 진이 빠지곤 해요. OpenClaw는 이런 번거로움을 줄이기 위해 복잡한 과정 없이 바로 실행할 수 있는 공식 설치 스크립트를 제공하고 있어요.

필요한 것

설치를 시작하기 전에 본인의 운영체제가 아래 목록에 해당하는지 확인해 주세요.

macOS, Linux, 또는 WSL 환경
Windows (PowerShell 사용 환경)

빠른 시작

가장 권장하는 방식은 공식 스크립트를 사용하는 거예요. 5분 안에 설치를 마칠 수 있도록 플랫폼별 명령어를 정리해 두었으니, 본인의 환경에 맞는 코드를 복사해서 터미널에 붙여넣으세요.

macOS / Linux / WSL

기본적인 설치를 원한다면 install.sh를 사용하세요. Node.js가 없다면 함께 설치해주고, npm이나 git을 통해 OpenClaw를 내려받습니다. 온보딩 과정도 함께 진행할 수 있어요.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

도움말이 필요하다면 아래 명령어를 사용하세요.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

만약 루트(root) 권한 없이 로컬 경로(~/.openclaw)에 설치하고 싶다면 install-cli.sh가 좋은 선택이에요.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

Windows

Windows 사용자라면 PowerShell에서 아래 명령어를 실행하면 돼요. Node.js 설치부터 온보딩까지 한 번에 처리해 줍니다.

iwr -useb https://openclaw.ai/install.ps1 | iex

특정 버전을 테스트하거나 드라이런(DryRun)이 필요한 경우 아래와 같이 옵션을 추가할 수 있어요.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

문제 해결

설치 과정에서 문제가 생겼나요? 가장 자주 발생하는 상황을 확인해 보세요.

설치는 성공했는데 openclaw 명령어를 찾을 수 없나요? 새 터미널을 열었는데도 명령어가 실행되지 않는다면 Node.js 설정 문제일 확률이 높아요. 이럴 때는 Node.js troubleshooting 문서를 참고해서 환경 변수를 확인해 보세요.

설치 과정에서 막히는 부분이 있나요? AI Setup Assistant에게 질문하면 바로 답변을 얻을 수 있어요.

다음 단계

새로운 도구를 내 컴퓨터에 맞게 설정하는 과정은 생각보다 번거로울 때가 많아요. OS에 맞는 패키지 매니저를 확인하고, 필요한 런타임 버전을 일일이 맞추다 보면 정작 중요한 개발 시작이 늦어지곤 하죠.

OpenClaw는 이런 불편함을 줄이기 위해 `install.sh` 스크립트를 제공해요. 복잡한 의존성 설치부터 환경 구성까지 한 번에 해결할 수 있는 가장 추천하는 방식이에요.

## 필요한 것

설치를 시작하기 전에 다음 환경인지 확인해 주세요.

- macOS
- Linux (WSL 포함)

## 빠른 시작

가장 빠르게 OpenClaw를 설치하는 방법이에요. 터미널에서 아래 명령어를 실행하면 5분 안에 설정을 마칠 수 있어요.

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

이 스크립트는 실행 시 다음과 같은 단계를 자동으로 진행해요.

OS 감지: macOS와 Linux(WSL 포함)를 감지해요. macOS에서 Homebrew가 없다면 자동으로 설치를 도와줘요.
Node.js 22+ 확보: 현재 Node 버전을 확인하고, 필요하다면 Node 22를 설치해요. (macOS는 Homebrew, Linux는 NodeSource 스크립트 사용)
Git 설치: 시스템에 Git이 없다면 자동으로 설치해요.
OpenClaw 설치: 기본적으로 npm을 통해 글로벌 설치를 진행하거나, git을 통해 레포지토리를 클론하고 pnpm으로 빌드하여 ~/.local/bin/openclaw에 설치해요.
사후 작업: 설치가 끝나면 openclaw doctor를 실행해 상태를 점검하고, 필요한 경우 온보딩 과정을 시작해요.

설치 방식 선택하기

스크립트를 실행하는 위치에 package.json과 pnpm-workspace.yaml이 있다면 OpenClaw 소스 체크아웃 상태로 인식해요. 이때는 두 가지 선택지를 제공해요.

git 방식: 현재 체크아웃된 소스를 사용해요.
npm 방식: 글로벌 npm 패키지로 설치해요.

만약 TTY를 사용할 수 없는 환경에서 설치 방식을 명시하지 않으면, 경고 메시지와 함께 기본값인 npm 방식으로 진행돼요.

다양한 설치 예시

특정 상황에 맞춰 스크립트 옵션을 조정할 수 있어요.

온보딩 과정 건너뛰기

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

Git 방식으로 설치하기

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

설치 시뮬레이션 (Dry run)

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

Flags & Environment Variables

설치 과정을 더 세밀하게 제어하고 싶다면 아래 플래그와 환경 변수를 참고하세요.

Flags reference

Flag	Description
`--install-method npm\|git`	설치 방법을 선택해요 (기본값: `npm`). 별칭: `--method`
`--npm`	npm 설치 방식을 사용해요
`--git`	git 설치 방식을 사용해요. 별칭: `--github`
`--version <version\|dist-tag>`	설치할 npm 버전이나 태그를 지정해요 (기본값: `latest`)
`--beta`	beta 태그가 있으면 사용하고, 없으면 `latest`를 사용해요
`--git-dir <path>`	git 클론 위치를 지정해요 (기본값: `~/openclaw`). 별칭: `--dir`
`--no-git-update`	이미 소스가 있다면 `git pull`을 건너뛰어요
`--no-prompt`	사용자 입력을 묻지 않아요
`--no-onboard`	설치 후 온보딩 과정을 건너뛰어요
`--onboard`	온보딩 과정을 활성화해요
`--dry-run`	실제 변경을 적용하지 않고 실행될 내용만 출력해요
`--verbose`	디버그 출력을 활성화해요 (`set -x`, npm logs)
`--help`	도움말을 보여줘요 (`-h`)

Environment variables reference

Variable	Description
`OPENCLAW_INSTALL_METHOD=git\|npm`	설치 방법을 설정해요
`OPENCLAW_VERSION=latest\|next\|<semver>`	npm 버전이나 태그를 설정해요
`OPENCLAW_BETA=0\|1`	베타 버전 사용 여부를 결정해요
`OPENCLAW_GIT_DIR=<path>`	git 설치 경로를 설정해요
`OPENCLAW_GIT_UPDATE=0\|1`	git 업데이트 여부를 설정해요
`OPENCLAW_NO_PROMPT=1`	프롬프트를 비활성화해요
`OPENCLAW_NO_ONBOARD=1`	온보딩을 건너뛰어요
`OPENCLAW_DRY_RUN=1`	드라이 런 모드를 활성화해요
`OPENCLAW_VERBOSE=1`	디버그 모드를 활성화해요
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 레벨을 설정해요
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작을 제어해요 (기본값: `1`)

문제 해결

설치 중 문제가 발생하면 아래 내용을 확인해 보세요.

종료 코드 2: --install-method에 잘못된 값을 입력했거나, 유효하지 않은 설치 방식을 선택했을 때 발생해요. 입력한 플래그 값을 다시 확인해 주세요.
비대화형(Non-TTY) 환경: 터미널 입력이 불가능한 환경에서 설치 방식을 지정하지 않으면 npm으로 강제 설정되며 경고가 발생할 수 있어요. 자동화 스크립트에서 사용할 때는 --npm 또는 --git 플래그를 명시하는 것이 좋아요.

설치 과정에서 더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

설치를 마쳤다면 다음 단계로 넘어가 볼까요?

새로운 도구를 설치할 때마다 기존 시스템의 Node.js 버전과 충돌할까 봐 걱정해 본 적 있으신가요? 전역 패키지를 설치하다가 권한 오류를 마주하거나, 환경 변수가 꼬여서 고생하는 일은 개발자라면 누구나 겪는 골칫거리예요.

OpenClaw는 이런 번거로움을 해결하기 위해 시스템 환경을 건드리지 않고 지정된 로컬 경로에 모든 것을 격리해서 설치하는 방식을 제공해요. 덕분에 복잡한 설정 과정 없이 깔끔한 설치 환경을 유지할 수 있어요.

필요한 것

설치를 시작하기 전에 다음 사항을 확인해 주세요.

설치 경로에 대한 쓰기 권한 (기본값: ~/.openclaw)
인터넷 연결 및 curl 실행 권한

빠른 시작

OpenClaw를 설치하는 가장 빠른 방법이에요. 아래 명령어를 터미널에 복사해서 실행하면 5분 안에 모든 준비가 끝나요.

기본 설치

시스템의 Node.js 유무와 상관없이 로컬에 독립적인 환경을 구축해요.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

설치 옵션 커스터마이징

설치 경로를 바꾸거나 특정 버전을 선택하고 싶다면 파라미터를 추가할 수 있어요.

커스텀 경로 및 버전 지정

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

자동화를 위한 JSON 출력

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

설치 직후 온보딩 실행

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard

설치 프로세스 상세

스크립트는 다음 단계를 거쳐 설치를 진행해요.

로컬 Node runtime 설치: <prefix>/tools/node-v<version> 경로에 Node.js 타볼(기본값 22.22.0)을 다운로드하고 SHA-256 검증을 수행해요.
Git 확인 및 설치: 시스템에 Git이 없다면 Linux(apt/dnf/yum) 또는 macOS(Homebrew) 환경에 맞춰 설치를 시도해요.
OpenClaw 설치: npm의 --prefix 옵션을 사용해 지정된 경로에 설치한 후, <prefix>/bin/openclaw 위치에 실행을 돕는 wrapper 파일을 생성해요.

문제 해결

설치 중 발생할 수 있는 상황에 대한 대응 방법이에요.

권한 문제 발생 시: Linux 환경에서 현재 설정된 prefix에 쓰기 권한이 없다면 --set-npm-prefix 플래그를 사용해 보세요. npm prefix를 ~/.npm-global로 강제 설정하여 문제를 해결할 수 있어요.
의존성 오류: Git 설치에 실패할 경우 시스템 패키지 매니저가 정상적으로 작동하는지 확인이 필요해요.

Flags reference

Flag	Description
`--prefix <path>`	설치 경로 (기본값: `~/.openclaw`)
`--version <ver>`	OpenClaw 버전 또는 dist-tag (기본값: `latest`)
`--node-version <ver>`	Node.js 버전 (기본값: `22.22.0`)
`--json`	NDJSON 이벤트 출력
`--onboard`	설치 후 `openclaw onboard` 실행
`--no-onboard`	온보딩 건너뛰기 (기본 설정)
`--set-npm-prefix`	Linux에서 쓰기 권한 없을 시 npm prefix를 `~/.npm-global`로 강제 설정
`--help`	사용법 출력 (`-h`)

Environment variables reference

Variable	Description
`OPENCLAW_PREFIX=<path>`	설치 경로 설정
`OPENCLAW_VERSION=<ver>`	OpenClaw 버전 또는 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node.js 버전 설정
`OPENCLAW_NO_ONBOARD=1`	온보딩 프로세스 생략
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 로그 레벨 설정
`OPENCLAW_GIT_DIR=<path>`	이전 `Peekaboo` 서브모듈 정리 시 사용하는 경로
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	sharp/libvips 동작 제어 (기본값: `1`)

설치 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

새로운 도구를 설치할 때 환경 설정 때문에 고생한 적 많으시죠? 환경 변수를 수동으로 잡거나 의존성 도구들을 하나하나 찾아 설치하다 보면, 정작 중요한 개발은 시작도 하기 전에 지치곤 해요. Windows 사용자라면 이런 번거로움을 줄여주는 install.ps1 스크립트를 사용해 보세요.

필요한 것

설치를 시작하기 전에 다음 조건이 충족되었는지 확인해 주세요.

PowerShell 5 이상 버전이 필요해요.
Node.js 22 이상 버전이 필요해요. (만약 없다면 스크립트가 winget, Chocolatey, Scoop 순으로 설치를 시도할 거예요.)
Git 설치 방식을 선택한다면 Git이 미리 설치되어 있어야 해요.

빠른 시작

가장 빠르게 설치하는 방법은 기본 설정을 사용하는 거예요. 터미널을 열고 아래 명령어를 입력하면 5분 안에 설치가 끝납니다.

1. 기본 설치

npm을 통해 최신 버전을 글로벌로 설치합니다.

iwr -useb https://openclaw.ai/install.ps1 | iex

스크립트는 내부적으로 이런 순서로 작동해요:

환경 확인: PowerShell 5+ 및 Windows 환경인지 확인합니다.
Node.js 확인: Node.js 22+ 버전이 있는지 보고, 없으면 winget 등을 통해 설치를 시도합니다.
OpenClaw 설치: 선택한 방식(npm 또는 git)에 따라 설치를 진행합니다.
후속 작업: 필요한 경우 bin 디렉토리를 PATH에 추가하고, openclaw doctor --non-interactive를 실행해 상태를 점검합니다.

2. 다양한 설치 예시

상황에 따라 설치 방식을 바꿀 수 있어요.

Git으로 설치하기
저장소를 클론하고 pnpm으로 빌드하여 %USERPROFILE%\.local\bin\openclaw.cmd에 래퍼를 생성합니다.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

커스텀 디렉토리에 Git 설치
원하는 경로에 소스 코드를 내려받고 싶을 때 사용하세요.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

Dry run 실행
실제로 설치하지 않고 어떤 작업이 일어날지 미리 확인해 볼 수 있어요.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun

3. Flags & Environment Variables

설치 과정을 더 세밀하게 제어하고 싶다면 아래 Flag와 환경 변수를 활용해 보세요.

Flag	설명
`-InstallMethod npm\|git`	설치 방식 (기본값: `npm`)
`-Tag <tag>`	npm dist-tag 지정 (기본값: `latest`)
`-GitDir <path>`	Git 클론 경로 (기본값: `%USERPROFILE%\openclaw`)
`-NoOnboard`	온보딩 과정 건너뛰기
`-NoGitUpdate`	`git pull` 업데이트 건너뛰기
`-DryRun`	실행될 내용만 출력

환경 변수로도 동일한 설정을 할 수 있습니다:

OPENCLAW_INSTALL_METHOD=git|npm
OPENCLAW_GIT_DIR=<path>
OPENCLAW_NO_ONBOARD=1
OPENCLAW_GIT_UPDATE=0
OPENCLAW_DRY_RUN=1

문제 해결

설치 중에 문제가 발생했다면 다음 내용을 확인해 보세요.

Git 누락: -InstallMethod git을 사용했는데 시스템에 Git이 없다면 스크립트가 종료됩니다. 이 경우 스크립트가 출력하는 Git for Windows 링크를 통해 Git을 먼저 설치해 주세요.
Node.js 버전 문제: 스크립트가 Node.js 22 미만 버전을 감지하면 자동으로 업데이트를 시도하지만, 권한 문제로 실패할 수 있어요. 이럴 땐 터미널을 관리자 권한으로 실행해 보세요.

설치 과정에서 더 궁금한 점이 생기면 AI Setup Assistant에게 물어봐 주세요!

다음 단계

CI/CD 파이프라인을 구축하다 보면 대화형 프롬프트 때문에 빌드가 멈춰버리는 상황이 가장 곤혹스럽죠. 자동화 환경에서는 누군가 대신 버튼을 눌러줄 수 없기 때문에, 모든 과정이 멈춤 없이 매끄럽게 진행되어야 해요.

예측 가능한 실행을 위해 non-interactive 플래그와 환경 변수를 사용하는 방법을 정리해 드릴게요.

필요한 것

Git (git 설치 방식 사용 시 필수, npm 방식에서도 의존성 해결을 위해 권장해요)
npm (Node.js 환경에서 설치할 때 필요해요)

빠른 시작

CI나 자동화 스크립트에서는 아래와 같이 non-interactive 플래그를 사용해서 5분 안에 설정을 끝낼 수 있어요. 환경에 맞는 명령어를 선택해 보세요.

install.sh (non-interactive npm)

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt -- --no-onboard

install.sh (non-interactive git)

OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

install-cli.sh (JSON)

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

install.ps1 (skip onboarding)

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

문제 해결

설치 과정에서 문제가 생겼나요? 자주 발생하는 상황들과 해결 방법을 모아봤어요.

Git이 왜 필요한가요? git 설치 방식을 사용할 때 당연히 필요하지만, npm 설치 시에도 Git을 체크해요. 의존성 패키지 중 git URL을 사용하는 경우 spawn git ENOENT 오류가 발생하는 것을 방지하기 위해서예요.

Linux에서 npm EACCES 에러가 발생해요 일부 Linux 설정에서 npm global prefix가 root 소유 경로를 가리키고 있을 수 있어요. install.sh는 prefix를 ~/.npm-global로 바꾸고 shell rc 파일에 PATH를 자동으로 추가해 줄 수 있어요.

sharp/libvips 관련 이슈가 있어요 스크립트는 기본적으로 SHARP_IGNORE_GLOBAL_LIBVIPS=1로 설정되어 시스템 libvips와 충돌하는 것을 방지해요. 이를 무시하고 싶다면 아래 명령어를 사용하세요.

SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Windows: “npm error spawn git / ENOENT” 메시지가 떠요 Git for Windows를 설치한 다음, PowerShell을 다시 열고 설치 프로그램을 다시 실행해 보세요.

Windows: “openclaw is not recognized”라고 나와요 npm config get prefix 명령어를 실행해서 나온 경로 뒤에 \bin을 붙여주세요. 그 디렉토리를 사용자 PATH 환경 변수에 추가하고 PowerShell을 다시 열면 해결돼요.

설치 후 openclaw를 찾을 수 없어요 대부분 PATH 설정 문제예요. 더 자세한 내용은 Node.js troubleshooting 문서를 확인해 보세요.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요!

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.