쓸모 쓸모연구소 · 실전 노트
제 825 호이번 주 새 글 49 편2026 · 11 · 14
AI 에이전트⁠·비서
OpenClaw · 라즈베리파이 · Node.js

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

라즈베리파이 OpenClaw 설치 방법, 64비트 확인부터 텔레그램까지

라즈베리파이 OpenClaw 설치를 조립부터 텔레그램 봇 대화까지 35단계로 정리했습니다. 64비트 OS 확인, Node.js 22 설치, npm 전역 설치 권한 정리처럼 라즈베리파이에서만 막히는 지점을 명령어와 함께 담았습니다.

라즈베리파이 OpenClaw 설치 방법, 64비트 확인부터 텔레그램까지 삽화
삽화 · 쓸모연구소

라즈베리파이로 OpenClaw를 돌린다는 것

OpenClaw(오픈클로, 내 기기에서 돌아가며 메신저로 대화하고 일을 처리하는 AI 에이전트 프로그램)를 돌리려고 다들 Mac mini를 사거나 옛 노트북을 꺼냅니다. 그런데 라즈베리파이(Raspberry Pi, 손바닥만 한 보드형 소형 컴퓨터)로도 충분히 돌아갑니다. OpenClaw를 돌리는 방법 중 가장 저평가되고 저렴한 쪽에 속합니다.

보드 모델명⁠·메모리⁠·가격은 정해진 답이 없습니다. 비용은 보드값에 모델 사용료가 더해지는 구조이고, 큰돈이 들지는 않습니다.

먼저 알아 둘 조건, 64비트와 보안

가장 중요한 조건은 이것입니다. Raspberry Pi OS가 64비트여야 합니다. uname -m(기기의 CPU 구조를 보여 주는 명령) 결과가 64로 끝나야 하고, ARMv7이 나오면 32비트라서 OpenClaw가 작동하지 않습니다. Node.js(자바스크립트 프로그램을 돌리는 실행 환경)도 꼭 있어야 합니다.

설치 과정에서 보안과 관련해 마주치는 장면은 온보딩(처음 실행할 때 설정을 묻는 대화형 과정)의 첫 질문입니다. "OpenClaw가 얼마나 강력하고 위험한지 이해하느냐"고 묻고, Yes를 골라야 다음으로 넘어갑니다.

OpenClaw는 설치된 기기의 파일과 연결한 계정에 접근하는 에이전트 도구입니다. 라즈베리파이를 전용 기기로 쓰면 메인 컴퓨터의 파일과 분리된다는 장점이 생깁니다. 그 장점을 살리려면 라즈베리파이 브라우저에 은행⁠·업무 계정을 로그인해 두지 않는 편이 좋습니다. 연결할 채널과 계정 범위도 처음부터 직접 정해 둡니다.

따라 하기 전에 알아 둘 것

아래 35단계는 실제 설치 순서 그대로입니다. 순서를 바꾸면 안 되는 곳은 두 군데입니다. 5번 구획(64비트 확인)은 Node.js 설치보다 먼저, 7번 구획(npm 권한)은 OpenClaw 설치보다 먼저 합니다.

몇 군데는 방법을 따로 채워 두었습니다.

  • 16단계 Node.js 설치는 NodeSource(Node.js 배포판을 리눅스용으로 제공하는 저장소) 방식의 일반적인 명령을 씁니다.
  • 19~22단계의 npm-global 폴더 경로, 프로필에 넣는 PATH export 줄, 프로필 파일 이름은 npm 공식 문서에서 권하는 형태입니다.
  • 12단계 full-upgrade와 14단계 apt-get install은 가장 흔히 쓰는 형태로 적었습니다. 설치 중 질문이 나오면 Y를 누르면 됩니다.
  • microSD에 OS를 굽는 방법, 32비트일 때 64비트로 바꾸는 방법, API 키 입력, Telegram 설정 세부, 삭제 방법은 각 단계와 뒤쪽 구획에 넣었습니다.

준비물

  • Raspberry Pi 본체, 팬, 케이스(body kit), 나사
  • microSD 카드: Raspberry Pi OS 64비트가 들어 있어야 합니다
  • 전원, 모니터, 키보드(마우스가 있으면 초기 설정이 편합니다)
  • 인터넷 연결: 초기 설정 화면에서 와이파이를 고르거나 랜선을 꽂습니다
  • 모델 계정이나 API 키: 이 글은 OpenAI 기준입니다
  • (권장) Telegram 또는 Discord
  • 비용: 큰돈은 들지 않습니다. 보드와 모델 요금은 판매처와 각 서비스의 공식 안내를 확인해야 합니다

1. 라즈베리파이 조립

  1. 팬을 끼웁니다.

    확인: 팬이 보드에 딸깍 고정된다.

  2. 케이스(body kit)를 밀어 끼웁니다.

    확인: 케이스가 씌워진다.

  3. 나사를 조입니다.

    확인: "제대로 된 작은 기계처럼" 보인다.

2. microSD 카드 준비와 첫 부팅

  1. Raspberry Pi OS 64비트가 들어 있는 microSD 카드를 준비합니다.

    주의: 반드시 64비트 버전이어야 합니다. OS가 미리 들어 있는 키트 카드를 쓰면 이 단계는 끝입니다.

    빈 카드라면: 다른 컴퓨터에 라즈베리파이 재단의 공식 굽기 프로그램 Raspberry Pi Imager를 설치합니다. 프로그램에서 기기 모델, OS, 저장 장치(microSD) 순서로 고르는데, OS는 이름에 64-bit가 붙은 Raspberry Pi OS를 고릅니다. 굽기가 끝나면 카드를 보드 아래쪽 microSD 슬롯에 꽂습니다.

    확인: 카드에 Raspberry Pi OS 64비트가 들어 있다.

  2. 전원을 연결합니다.

    확인: 전원 케이블이 꽂혀 있다.

  3. 모니터를 연결합니다.

    확인: 모니터 케이블이 꽂혀 있다.

  4. 키보드를 연결합니다.

    확인: 키보드가 꽂혀 있다.

  5. 부팅합니다.

    확인: 모니터에 Raspberry Pi 설정 안내가 뜬다.

  6. 화면 안내(prompts)를 따라 초기 설정을 마칩니다.

    위치: 보통 국가⁠·언어⁠·시간대, 사용자 이름과 암호, 와이파이, 소프트웨어 업데이트 순으로 묻습니다. 여기서 정한 암호는 뒤에서 sudo(관리자 권한으로 실행) 명령을 칠 때 다시 묻습니다.

    확인: Raspberry Pi 바탕화면이 뜬다.

3. 시스템 업데이트

  1. 바탕화면에서 터미널을 엽니다.

    위치: 화면 위쪽 작업 표시줄의 검은 창 모양 아이콘을 누르거나, 키보드에서 Ctrl+Alt+T를 누릅니다.

    확인: 터미널 창이 열린다.

  2. 아래 명령을 입력해 실행합니다. 패키지(설치 가능한 프로그램) 목록을 새로 받아 오는 명령입니다.

명령어
sudo apt update

확인: 패키지 목록 갱신이 끝나고 입력 프롬프트로 돌아온다.

  1. 아래 명령을 입력해 실행합니다. 설치된 프로그램을 모두 최신으로 올리는 명령이고, -y는 중간 확인 질문에 자동으로 yes라고 답하라는 뜻입니다.
명령어
sudo apt full-upgrade -y

확인: 업그레이드가 끝난다. 처음이라면 몇 분 걸릴 수 있다.

  1. 아래 명령으로 재부팅합니다.
명령어
sudo reboot

확인: 라즈베리파이가 재시작해 다시 바탕화면이 뜬다.

4. 기본 패키지 설치

  1. 아래 명령을 입력해 실행합니다. curl(인터넷에서 파일을 받는 도구), ca-certificates(보안 접속용 인증서), build-essential(프로그램을 컴파일하는 기본 도구 묶음)을 한 번에 까는 명령입니다.
명령어
sudo apt-get install curl ca-certificates build-essential

주의: 재부팅 뒤에는 터미널이 닫혀 있습니다. 10단계처럼 다시 엽니다.

위치: 설치하겠느냐고 물으면 Y를 누르고 Enter를 칩니다.

확인: 약 1분 뒤 설치가 끝난다.

5. 라즈베리파이 64비트 확인 (순서 고정)

더 가기 전에 이것부터 확인합니다. 이 단계는 순서를 바꾸지 않습니다.

  1. 아래 명령을 입력해 실행합니다.
프롬프트
uname -m

주의: 결과가 ARMv7이면 32비트입니다. 64비트 OS 이미지로 바꿔야 하고, 그대로 두면 OpenClaw가 작동하지 않습니다.

바꾸는 법: 4단계의 Raspberry Pi Imager로 64-bit OS를 골라 카드를 다시 굽고 1~14단계를 반복합니다. 카드 안의 파일은 지워지니 필요한 것은 먼저 옮겨 둡니다. 아주 오래된 모델(초기형 Pi 1·2, 첫 Pi Zero)은 64비트 OS를 지원하지 않으니 이 경우엔 기기를 바꿔야 합니다.

확인: 결과가 64로 끝난다(보통 aarch64).

6. Node.js 22 설치와 버전 확인

  1. Node.js를 설치합니다. OpenClaw에 꼭 필요한데 라즈베리파이에는 기본으로 깔려 있지 않습니다.

    방법: Raspberry Pi OS 기본 저장소의 Node.js는 버전이 낮은 경우가 많습니다. NodeSource 저장소를 추가해 22 버전을 까는 것이 일반적인 방법입니다. 아래 두 줄을 차례로 실행합니다.

명령어
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

확인: 설치가 끝나고 프롬프트로 돌아온다.

  1. 아래 명령으로 Node.js 버전을 확인합니다.
명령어
node -v

확인: 버전 22.x가 보인다.

  1. 아래 명령으로 npm(Node.js용 프로그램 설치 도구) 버전을 확인합니다.
명령어
npm -v

확인: 버전 번호가 나온다. npm은 Node.js와 번호 체계가 달라서 22가 아닌 다른 숫자가 나와도 정상입니다. 17단계에서 22대가 보였다면 넘어가면 됩니다.

7. npm 전역 설치 권한 고치기

목적은 모든 명령에 sudo를 붙이지 않아도 되게 하는 것입니다. npm install -g(전역 설치, 어느 폴더에서든 쓸 수 있게 까는 방식)는 기본적으로 시스템 폴더에 쓰려고 해서 권한 오류가 납니다. 내 홈 폴더 안에 전역 설치 폴더를 따로 두면 이 문제가 사라집니다. 라즈베리파이에서 OpenClaw를 돌릴 때 권장되는 방식입니다.

순서 고정: 폴더 → prefix → PATH → source → 확인.

  1. npm-global이라는 폴더를 만듭니다.

    위치: npm 공식 문서가 예로 드는 형태는 홈 폴더 안의 숨김 폴더입니다.

명령어
mkdir ~/.npm-global

확인: 폴더가 생긴다.

  1. npm의 전역 설치 위치(prefix)를 그 폴더로 지정합니다. {폴더 경로}에 19단계에서 만든 폴더 경로를 넣습니다.
명령어
npm config set prefix {폴더 경로}

예시: 19단계 명령을 그대로 썼다면 아래와 같습니다.

명령어
npm config set prefix ~/.npm-global

확인: 명령이 오류 없이 끝난다.

  1. PATH(터미널이 명령어를 찾아보는 폴더 목록)를 export하는 줄을 프로필 파일에 echo로 추가합니다.

    위치: 라즈베리파이 바탕화면에서 여는 터미널은 ~/.bashrc를 읽으므로 이 파일에 넣는 것이 확실합니다.

프롬프트
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

확인: 프로필 파일 끝에 export 줄이 들어간다.

  1. 프로필을 source로 다시 불러옵니다. 터미널을 껐다 켜지 않아도 21단계 설정이 바로 적용됩니다.
명령어
source ~/.bashrc

확인: 명령이 오류 없이 끝난다.

  1. 아래 명령으로 경로를 확인합니다.
프롬프트
which npm

확인: 경로가 나온다. npm 자체는 여전히 /usr/bin/npm으로 나올 수 있습니다. prefix가 제대로 바뀌었는지는 npm config get prefix를 쳐서 홈 폴더 안의 .npm-global 경로가 나오는지로 보는 편이 확실합니다.

8. 라즈베리파이에 OpenClaw 설치

  1. 아래 명령을 입력해 실행합니다. sudo를 붙이지 않습니다.
명령어
npm install -g openclaw

주의: 권한 오류(EACCES)가 나면 7번 구획 설정이 적용되지 않은 것입니다. 20~22단계를 다시 확인합니다.

확인: 설치가 오류 없이 진행된다. 끝난 뒤 which openclaw를 치면 .npm-global/bin 안의 경로가 나온다.

  1. 아래 명령으로 온보딩을 시작합니다.
명령어
openclaw onboard

확인: 온보딩 화면에 들어간다.

9. 온보딩에서 모델과 채널 고르기

온보딩 화면은 방향키로 항목을 옮기고 Enter로 고르는 방식입니다. 여러 개를 고르는 목록에서는 스페이스바로 체크합니다.

  1. "OpenClaw가 얼마나 강력하고 위험한지 이해하느냐"는 질문에 Yes를 고릅니다.

    주의: 설치 과정에서 나오는 유일한 위험 경고 문구입니다. 읽고 넘어갑니다.

    확인: 다음 선택 화면으로 넘어간다.

  2. "quick start"를 고릅니다.

    확인: 모델 선택 화면이 뜬다.

  3. 모델을 고릅니다.

    대안: 이 글은 OpenAI 기준이고, 목록의 다른 모델도 쓸 수 있습니다.

    인증 방법: OpenAI를 API 키로 쓴다면 OpenAI 개발자 플랫폼에 로그인해 API keys 메뉴에서 새 키를 만들고, 온보딩 입력 칸에 붙여 넣습니다. 계정 로그인 방식이 목록에 보이면 그쪽을 골라 브라우저에서 로그인해도 됩니다. 키는 한 번만 보여 주므로 메모장에 따로 적어 둡니다.

    확인: 채널 선택 화면이 뜬다.

  4. 채널을 고릅니다.

    대안: 휴대폰으로 쓰기 편한 Telegram이 무난합니다.

    확인: 채널 설정 안내가 뜬다.

  5. 화면 안내를 따라 채널 설정을 마칩니다.

    Telegram이라면: 휴대폰 Telegram에서 BotFather를 검색해 대화를 열고 /newbot을 보냅니다. 봇 이름과 사용자명(끝이 bot으로 끝나야 함)을 차례로 보내면 토큰(봇 비밀번호 같은 긴 문자열)을 줍니다. 이 토큰을 온보딩 입력 칸에 붙여 넣습니다.

    확인: 다음 설정 항목으로 넘어간다.

  6. 나중에 설치하고 싶은 항목은 건너뜁니다(skip).

    확인: 온보딩이 완료된다.

10. 작동 확인과 봇 이름 정하기

  1. 봇에게 메시지를 보내 작동을 확인합니다.

    위치: Telegram을 연결했다면 내 봇 대화창에서 Start를 누릅니다. 봇이 "access not configured"와 코드를 돌려주면 라즈베리파이 터미널에 아래 명령을 치고 {코드}에 받은 코드를 넣은 뒤, Telegram에서 다시 말을 겁니다.

명령어
openclaw pairing approve telegram {코드}

확인: 응답이 돌아오면 작동 중이다.

  1. 봇에게 자기소개를 합니다.

    확인: 봇이 대화를 이어 간다.

  2. 봇의 이름을 정해 줍니다.

    확인: 봇이 새 이름을 쓴다. 예를 들면 "Jimmybot Pi" 같은 이름입니다.

  3. (권장) Discord 또는 Telegram에서 봇에게 메시지를 보냅니다.

    대안: 라즈베리파이 앞에 없어도 메시지를 보낼 수 있게 Discord나 Telegram 채널을 설정해 두는 것이 좋습니다.

    확인: Telegram(또는 Discord)에서 봇이 답한다.

첫 대화는 이렇게 보내 보면 됩니다.

프롬프트
안녕, 나는 {이름}이야. 너는 지금 라즈베리파이에서 돌아가고 있어.
앞으로 네 이름은 {봇 이름}이야. 오늘 날짜와 네가 할 수 있는 일 다섯 가지를 짧게 알려 줘.

라즈베리파이 OpenClaw 설치 최종 체크리스트

  • uname -m 결과가 64로 끝난다(ARMv7 아님)
  • node -v에 22.x가 나온다
  • which npm으로 경로 설정을 확인했다(npm config get prefix도 함께)
  • npm install -g openclaw가 sudo 없이 끝났다
  • openclaw onboard를 끝까지 마쳤다
  • 봇이 응답한다
  • (권장) Telegram 또는 Discord에서 봇과 대화가 된다

막힐 때 확인할 곳

  • OpenClaw가 작동하지 않거나 uname -m이 ARMv7로 나온다: 32비트 OS입니다. 64비트 OS 이미지로 바꿔야 합니다. Raspberry Pi Imager로 64-bit OS를 다시 굽습니다(15단계).
  • npm 명령마다 sudo가 필요하다: npm 전역 설치 권한 문제입니다. 7번 구획의 폴더, prefix, PATH 설정을 합니다.
  • 설치는 됐는데 openclaw를 치면 "command not found"가 나온다: PATH가 적용되지 않은 것입니다. source ~/.bashrc를 다시 치거나 터미널을 새로 엽니다.
  • node -v에 22대가 안 나온다: Node.js가 없거나 기본 저장소의 낮은 버전이 깔린 것입니다. 16단계의 NodeSource 방식으로 다시 설치합니다.
  • Telegram에서 봇이 답하지 않는다: 페어링 승인 전일 수 있습니다. 32단계의 openclaw pairing approve telegram {코드}를 실행합니다.

OpenClaw 삭제하고 되돌리는 법

npm으로 설치했으니 아래 명령으로 프로그램을 지울 수 있습니다.

명령어
npm uninstall -g openclaw

설정과 대화 기록은 홈 폴더의 숨김 폴더(보통 .openclaw)에 남습니다. 깨끗하게 처음부터 다시 하려면 이 폴더까지 정리하거나, 가장 확실하게는 microSD 카드를 새로 굽습니다. 봇 토큰이 노출됐다면 BotFather에서 토큰을 새로 발급받고, 모델 API 키도 해당 서비스에서 삭제한 뒤 새로 만듭니다.

라즈베리파이가 OpenClaw 전용기로 맞는 사람

라즈베리파이로도 OpenClaw는 돌아갑니다. 큰돈 들이지 않는 괜찮은 로컬 구성이고, 지갑에 들어갈 만한 보드 하나로 끝납니다.

다만 라즈베리파이가 모델을 직접 돌리는 게 아니라는 점은 알아 두면 좋습니다. 이 구성은 OpenAI 같은 클라우드 모델을 부르고, 라즈베리파이는 OpenClaw 프로그램과 메신저 연결만 맡습니다. 그래서 작은 보드로도 돌아가지만, 모델 사용료는 따로 나갑니다. 화면이 없어도 되는 상시 가동 기기, 메인 컴퓨터와 분리된 실험용 기기가 필요하다면 잘 맞습니다.

처음 하는 사람이 가장 많이 막히는 곳은 Node.js 설치와 PATH 설정 두 군데입니다. 16단계와 19~22단계를 천천히 따라가면 됩니다.

자주 묻는 질문

라즈베리파이에서 OpenClaw가 정말 돌아가나요?

돌아갑니다. 설치 후 Telegram에서 봇이 답하는 데까지 문제없이 진행됩니다. 조건은 64비트 Raspberry Pi OS와 Node.js 22입니다. 모델은 클라우드(예: OpenAI)를 쓰므로 라즈베리파이는 프로그램과 메신저 연결만 맡습니다.

32비트 라즈베리파이 OS에서도 설치할 수 있나요?

안 됩니다. uname -m에 ARMv7이 나오면 32비트이고, 64비트 OS 이미지로 바꿔야 합니다. Raspberry Pi Imager로 64-bit OS를 골라 카드를 다시 구우면 됩니다.

라즈베리파이 OpenClaw 설치에 sudo를 써야 하나요?

시스템 업데이트와 기본 패키지 설치에는 sudo가 필요하지만, npm install -g openclaw에는 붙이지 않는 것이 권장 방식입니다. npm 전역 설치 폴더를 홈 폴더로 옮겨 두면(7번 구획) sudo 없이 설치됩니다.

모니터 없이 라즈베리파이에 OpenClaw를 설치할 수 있나요?

할 수 있습니다. Raspberry Pi Imager의 설정에서 SSH(다른 컴퓨터에서 터미널로 원격 접속하는 방식)를 켜고 구운 뒤, 내 컴퓨터 터미널에서 ssh 사용자명@라즈베리파이주소로 접속해 같은 명령을 치면 됩니다. 온보딩까지 전부 터미널에서 진행됩니다.

라즈베리파이 OpenClaw 비용은 얼마나 드나요?

보드값과 모델 사용료 두 가지가 듭니다. 큰돈이 드는 구성은 아니지만 정확한 금액은 상황마다 다릅니다. 보드 가격은 판매처, 모델 요금은 OpenAI 등 각 서비스의 공식 안내를 확인해야 합니다.

이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.

원본 영상 보러가기 ↗