일반적인 OpenClaw 설치 오류 및 해결 방법

OpenClaw 설치 문제 해결 가이드

r/openclaw의 최근 게시물은 OpenClaw 도구의 반복적인 설치 및 런타임 오류를 다루며, 구체적인 명령어와 수정 방법을 제공합니다.

주요 문제 및 해결 방법

"설치되었지만 openclaw를 찾을 수 없음"

이는 npm의 글로벌 bin 디렉토리가 PATH에 포함되지 않았을 때 발생합니다. 바이너리는 존재하지만 찾을 수 없습니다.

• npm prefix -g를 실행하여 글로벌 접두사를 확인하세요.
• .bashrc 또는 .zshrc에서 $PATH에 <prefix>/bin을 추가하세요.
• 셸을 다시 로드한 후 openclaw --version이 작동해야 합니다.

설치 시 "EACCES: 권한 거부됨"

이는 루트가 소유한 npm의 기본 글로벌 디렉토리와 관련된 권한 문제입니다.

• sudo를 사용하지 마세요.
• 대신 사용자 소유의 접두사를 구성하세요:

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

• 셸 구성 파일에 export를 추가하고 sudo 없이 설치를 다시 실행하세요.

구형 Node.js의 자동 실패

OpenClaw는 Node.js 22+가 필요합니다. 이전 버전은 오류 없이 설치될 수 있지만 런타임에서 중단되는 바이너리를 생성할 수 있습니다.

• 항상 먼저 node --version을 확인하세요.

"장치에 부적절한 ioctl"

이는 실제 터미널이 없는 Docker 컨테이너나 CI 환경에서 흔히 발생하는 TTY 문제입니다.

• openclaw onboard --non-interactive --accept-risk를 실행하여 대화형 마법사를 건너뛰세요.

Telegram 플러그인이 "사용 불가" 상태로 고착됨

이전에 손상된 설치가 Telegram 플러그인을 부분적으로 구성된 상태로 남겼다면, 고착될 수 있습니다.

• 상태를 지우려면 openclaw doctor --fix를 실행하세요.

"게이트웨이 연결 페어링 필요"에 대한 참고

이 메시지는 설치 오류가 아닙니다. 이는 DM 정책과 관련되어 있으며, OpenClaw는 기본적으로 DM에 응답하기 전에 수동 페어링을 요구합니다. 채널 구성에 대한 OpenClaw 문서를 참조하세요.