OpenClaw 한국어 문서

Appearance

Node.js ​

OpenClaw에는 Node 22.14 이상이 필요합니다. Node 24가 설치, CI 및 릴리즈 워크플로우의 기본 권장 런타임입니다. Node 22는 활성 LTS 라인을 통해 계속 지원됩니다. 설치 프로그램 스크립트는 Node를 자동으로 감지하고 설치합니다 — 이 페이지는 Node를 직접 설정하고 모든 것이 올바르게 연결되었는지 확인하려는 경우를 위한 것입니다(버전, PATH, 전역 설치).

버전 확인 ​

bash
node -v

v24.x.x 이상이 출력되면 권장 기본값을 사용 중입니다. v22.14.x 이상이 출력되면 지원되는 Node 22 LTS 경로를 사용 중이지만 편의에 따라 Node 24로 업그레이드하는 것을 여전히 권장합니다. Node가 설치되지 않았거나 버전이 너무 오래된 경우 아래의 설치 방법을 선택합니다.

Node 설치 ​

macOS

Homebrew (권장):

```bash
brew install node
```

또는 [nodejs.org](https://nodejs.org/)에서 macOS 설치 프로그램 다운로드.

Linux

Ubuntu / Debian:

```bash
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**Fedora / RHEL:**

```bash
sudo dnf install nodejs
```

또는 버전 관리자 사용 (아래 참조).

Windows

winget (권장):

```powershell
winget install OpenJS.NodeJS.LTS
```

**Chocolatey:**

```powershell
choco install nodejs-lts
```

또는 [nodejs.org](https://nodejs.org/)에서 Windows 설치 프로그램 다운로드.
버전 관리자 사용 (nvm, fnm, mise, asdf)

버전 관리자를 사용하면 Node 버전 간에 쉽게 전환할 수 있습니다. 인기 있는 옵션:

  • fnm — 빠르고 크로스 플랫폼
  • nvm — macOS/Linux에서 널리 사용됨
  • mise — 다국어 (Node, Python, Ruby 등)

fnm 예제:

bash
fnm install 24
fnm use 24

WARNING

버전 관리자가 셸 시작 파일(~/.zshrc 또는 ~/.bashrc)에서 초기화되어 있는지 확인합니다. 초기화되지 않으면 PATH에 Node의 bin 디렉터리가 포함되지 않아 새 터미널 세션에서 openclaw를 찾을 수 없을 수 있습니다.

:::

문제 해결 ​

openclaw: command not found ​

거의 항상 npm의 전역 bin 디렉터리가 PATH에 없다는 것을 의미합니다.

  1. 전역 npm 접두사 찾기

    bash
        npm prefix -g
    ```

  2. PATH에 있는지 확인

bash
    echo "$PATH"
    ```

    출력에서 `<npm-prefix>/bin` (macOS/Linux) 또는 `<npm-prefix>` (Windows)를 찾습니다.

3. **셸 시작 파일에 추가**

**macOS / Linux**

`~/.zshrc` 또는 `~/.bashrc`에 추가:

        ```bash
        export PATH="$(npm prefix -g)/bin:$PATH"
        ```

        그런 다음 새 터미널을 열거나 (zsh에서 `rehash` / bash에서 `hash -r`을 실행).


      **Windows**

설정 → 시스템 → 환경 변수를 통해 `npm prefix -g`의 출력을 시스템 PATH에 추가합니다.




### Linux에서 `npm install -g` 권한 오류

`EACCES` 오류가 발생하면 npm의 전역 접두사를 사용자가 쓸 수 있는 디렉터리로 전환합니다:

```bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

영구적으로 적용하려면 export PATH=... 줄을 ~/.bashrc 또는 ~/.zshrc에 추가합니다.

관련 항목 ​