초보자를 위한 오픈클로 설치하기
처음은 누구나 어렵고 지루합니다. 이 지루한 30분만 지나면 AI 비서가 일하기 시작합니다. 오늘 30분이 아까워서 미루면 내일도 모레도 그 잡다한 반복 작업을 직접 하게 됩니다. 자, 터미널 하나 열어놓고 커피 한 잔 내리면서 따라오세요. 생각보다 금방 끝납니다. 만약 설치를 하다가 문제가 생겼다면, 챕터 마지막에 있는 문제가 생겼을 때 페이지를 확인하세요.
Node.js 설치하기
컴퓨터 사양은 크게 신경 안 써도 됩니다. 오픈클로 자체가 무거운 프로그램이 아닙니다. AI 모델은 클라우드에서 돌아가고, 오픈클로는 그 AI에게 일을 전달하고 결과를 받아오는 역할입니다. 최근 5년 안에 산 컴퓨터라면 거의 다 됩니다. 딱 하나, Node.js 22 버전 이상이 필요합니다. 당장 Node.js가 뭔지 자세히 알 필요는 없습니다. Node.js는 자바스크립트를 컴퓨터에서 실행하는 도구이며, 오픈클로가 자바스크립트로 만들어져서 필요하다는 정도만 알아두세요.
Node.js 설치되어 있는지 확인하기
Node.js가 이미 설치되어 있을 수도 있으니까 먼저 확인해봅시다. 터미널을 열고 이렇게 입력해보세요.
v22.x.x 이상의 숫자가 나오면 OK입니다. 만약 command not found라고 나오거나 버전이 22보다 낮으면 다음에서 Node.js부터 설치하면 됩니다. 이미 Node.js 22 이상이 설치되어 있다면 이 섹션은 건너뛰세요.
Homebrew로 Node.js 설치하기
macOS는 Homebrew로 설치하는 방법이 가장 간편합니다. Homebrew가 없는 독자 여러분을 위해 Homebrew 설치부터 차근차근 진행하겠습니다.
01 다음 사이트에 접속해 설치 명령어를 복사하고 터미널에 붙여넣어 실행하세요. 설치 명령어는 다음과 같습니다. 사이트 화면을 캡처한 이미지는 크게 중요하지 않으므로 생략했습니다.
Homebrew : brew.sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
02 Homebrew를 설치했다면 이어서 Node.js 설치 명령을 실행하면 됩니다.
```
> brew install node
```
설치 프로그램으로 Node.js 설치하기
만약 Homebrew가 없거나 Homebrew를 통해 설치하고 싶지 않고, 어쩔 수 없이 윈도우를 쓰는 환경이라면 Node.js 공식 사이트에서 다운로드할 수 있습니다.
01 nodejs.org/ko/download에 접속해서 버전과 환경을 선택합니다. 버전은 LTS라고 써져있는 버전을 선택하세요. 환경은 macOS, 리눅스, 윈도우 등 사용자 컴퓨터에 맞는 것을 고르면 됩니다.
02 설치 프로그램 다운로드를 선택하고 설치 프로그램을 실행합니다. 설치 프로그램에서는 [Continue]만 누르면 됩니다.
설치가 끝났다면 다시 터미널을 열어 node -v 명령을 실행해 설치가 잘 되었는지 확인하는 게 좋습니다. Node.js는 오픈클로를 실행하기 위해 꼭 필요하므로 오픈클로를 설치한 이후에도 삭제하면 안 됩니다.
오픈클로 설치하기
Node.js를 준비했다면 오픈클로를 바로 설치합니다. 두 가지 방법이 있습니다. 하나는 설치 스크립트를 사용하는 것이고, 하나는 Node.js의 패키지 관리자인 npm을 사용하는 겁니다.
설치 스크립트 사용하기
저는 설치 스크립트 방법을 추천합니다. 가장 간편하고 실수할 일이 적습니다.
01 오픈클로 홈페이지에서 다음 설치 명령어를 복사한 후 터미널에 붙여넣고 [Enter]를 누르세요. 이 스크립트가 알아서 오픈클로를 설치하고, 기본 설정 파일을 만들고, 온보딩 마법사까지 자동으로 시작합니다.
이렇게 정상적으로 설치가 끝나고 온보딩 화면이 나오면 됩니다.
온보딩 마법사 따라가기
온보딩 마법사는 오픈클로의 초기 설정을 간편하게 수행할 수 있는 프로그램입니다. 온보딩 마법사를 시작하는 방법은 터미널에서 다음 명령어를 입력하는 겁니다. 설치 스크립트로 오픈클로를 설치했다면 명령어를 입력하지 않아도 자동으로 실행될 겁니다.
```
openclaw onboard --install-daemon
```
자세한 설명보다는 설치부터 하고 싶은 분, 이미 오픈클로를 한 번 설치해본 분은 다음 목록을 보고 그대로 따라하세요. 가장 빠르게 온보딩을 끝낼 수 있는 방법을 정리한 목록입니다. 초보 독자 여러분은 읽지 않고 넘어가도 좋습니다.
I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
Yes
Onboarding mode
QuickStart
Model/auth provider
OpenAI
OpenAI auth method
OpenAI Codex (ChatGPT OAuth)
챗GPT 계정 로그인
Default model
openai-codex/gpt-5.3-codex
Select channel (QuickStart)
Telegram (Bot API)
How do you want to provide this Telegram bot token?
Enter Telegram bot token
텔레그램 봇 생성 및 토큰 입력
Search provider
Skip for now
Configure skills now? (recommended)
No
Enable hooks?
Skip for now ([Space ➝ Enter])
How do you want to hatch your bot?
Do this later
이제 온보딩을 본격적으로 시작해보겠습니다. 어려워도 하나씩 천천히 따라하면 누구나 설치할 수 있습니다.
01 처음에 보안 안내가 나옵니다. 오픈클로는 여러분의 컴퓨터를 제어할 수 있는 AI라서, 몇 가지 주의 사항을 미리 알려주는 겁니다.
핵심만 정리하면 이렇습니다. 읽어보고 동의하면 다음 단계로 넘어갑니다.
신뢰할 수 있는 AI 모델만 사용하세요. Anthropic(클로드), OpenAI(GPT) 같은 검증된 서비스를 쓰라는 뜻입니다. 책에서는 OpenAI의 GPT를 사용합니다.
API 키를 안전하게 보관하세요. API 키가 유출되면 다른 사람이 여러분 돈으로 AI를 사용할 수 있습니다.
채널 접근을 제한하세요. 아무나 오픈클로에 명령을 보낼 수 없게 관리해야 합니다.
02 지금부터는 오픈클로가 던지는 질문에 차례대로 대답하며 오픈클로 설정을 진행할 겁니다. 처음은 온보딩 모드를 설정합니다. 빠른 시작을 위해 [QuickStart]로 진행하겠습니다.
03 게이트웨이 위치를 선택합니다. 이 질문은 버전과 사용환경에 따라서 나오지 않을 수 있습니다. 다음 세 가지 옵션 중 하나를 선택합니다.
Local (이 컴퓨터)
Remote (SSH/Tailnet)
Configure later (나중에 설정)
여러분은 [Local]을 선택하세요. 지금 쓰고 있는 컴퓨터에서 오픈클로를 운영한다는 뜻입니다. 대부분의 사용자에게는 이게 최선의 선택입니다. 나중에 서버에 올리고 싶어지면 그때 변경하면 됩니다. [Remote]는 별도의 서버(VPS, 홈 서버 등)에서 돌릴 때 쓰는 옵션입니다. 지금 단계에서는 신경 쓰지 않아도 됩니다.
04 AI 프로바이더Provider를 선택합니다. 여기가 가장 중요한 단계입니다. 오픈클로의 모델, 즉 두뇌를 결정하는 겁니다. 여기서 OpenAI를 선택하세요.
이 책에서는 OpenAI를 기준으로 설명합니다. OpenAI는 GPT-5.1-mini 같은 가성비 좋은 모델부터 GPT-4.1까지 다양한 선택지를 제공합니다. 도구 사용 능력도 뛰어나서 오픈클로와 궁합이 좋습니다.
05 OpenAI를 선택하면 인증 방식을 선택할 수 있습니다. 이 책에서는 인증 방식은 [OpenAI Codex]를 사용합니다.
각 방식마다 장단점이 있으니 본인에게 맞는 걸 선택하세요. OAuth 방식은 챗GPT를 구독할 때 사용할 수 있습니다. API Key 방식은 사용하는 만큼 비용을 지불해야 합니다.
챗GPT 계정으로 연동하기
ChatGPT Plus나 Pro를 구독하고 있다면 이 방법이 가장 편합니다. API 키 없이 기존 ChatGPT 계정으로 바로 연결합니다. 챗GPT Plus 또는 Pro 구독이 필요합니다.
01 앞에서 본 온보딩 마법사에서 [OpenAI Codex (ChatGPT OAuth)]를 선택합니다. 그러면 로그인을 위한 브라우저가 자동으로 열립니다.
02 챗GPT 계정으로 로그인합니다. 이미 로그인되어 있다면 건너뜁니다. [계속] 버튼을 눌러 오픈클로가 계정에 접근할 수 있도록 승인합니다.
03 연결 완료 메시지가 나타나면 터미널로 돌아가세요.
04 사용할 모델을 선택합니다. 모델은 최신 모델을 선택하세요.
챗GPT 계정 연동은 장점이 있습니다. API 키를 따로 발급받을 필요가 없습니다. 키가 유출될 걱정도 없죠. 그리고 이미 구독 중인 챗GPT 요금제를 그대로 사용하니 저렴합니다.
나중에 모델을 다시 연결하고 싶다면 openclaw configure 명령어를 실행하고 model 설정에서 재연결할 수 있습니다.
API 키로 인증하기
챗GPT를 구독하지 않거나 사용량 기반 과금을 원한다면 API 키를 발급받아 사용합니다. 이미 챗GPT 계정 연동을 끝냈다면 이 부분은 생략해도 됩니다.
01 OpenAI 플랫폼에 접속해서 로그인합니다.
platform.openai.com
02 좌측 메뉴에서 [API Keys ➝ Create new secret key] 버튼을 누릅니다. 키 이름을 정하고 [Create secret key]를 클릭합니다.
이때 주의할 점이 있습니다. 생성한 키는 딱 한 번만 보인다는 겁니다. 그러므로 반드시 복사해서 안전한 곳에 저장하세요. sk-proj-로 시작하는 긴 문자열이 키입니다. 또한, API 키는 유출하면 안 됩니다. 여러분의 비밀번호와 같습니다. 절대 깃허브에 커밋(업로드)하거나 공개하지 마세요. 키가 유출되었다면 즉시 OpenAI 플랫폼에서 삭제하고 새로 발급받으세요.
03 복사한 키를 온보딩 마법사에 붙여넣습니다.
API 키 방식은 사용량만큼 과금합니다. 가벼운 일상 사용 기준이라면 월 5~20달러 정도 예상하면 됩니다. 만약 사용량 한도를 정하고 싶다면 [Settings → Billing → Usage limits]에서 월 최대 지출 한도를 설정해두세요. 설정한 금액 이상은 과금하지 않습니다.
메신저 채널 연결하기
채널은 오픈클로와 소통하는 메신저를 말합니다. 오픈클로는 정말 다양한 채널을 지원하며, 다음 채널이 대표적입니다.
텔레그램Telegram
왓츠앱WhatsApp
디스코드Discord
이 책에서는 텔레그램을 기준으로 진행합니다. 텔레그램은 오픈클로 설정이 가장 간단하고, 봇 API가 안정적이며, 무료이고, PC와 모바일 모두에서 쓸 수 있다는 장점이 많은 메신저입니다. 다만 텔레그램을 연동하려면 봇 토큰이 필요합니다. 텔레그램에서 봇을 만들고 토큰을 받는 방법부터 알아보겠습니다.
01 스마트폰에 텔레그램 앱을 설치하고 실행하세요. 검색창에 ‘@BotFather’를 검색합니다.
02 BotFather에게 /newbot이라고 메시지를 보냅니다. 봇 이름과 봇 사용자명을 정해줍니다. 저는 봇 이름을 goldenrabbitbot으로 하겠습니다. 봇 사용자명은 반드시 ‘bot’으로 끝나야 하며, 전 세계에서 유일한 이름을 정해야 합니다. 겹치지 않는 이름을 찾아보세요.
이름을 정하면 BotFather가 봇 토큰을 알려줍니다. 이 토큰을 복사하세요. 봇 토큰도 API 키처럼 다른 사람에게 공유하면 안 됩니다. 토큰이 유출되면 BotFather에서 /revoke 명령으로 폐기하고 새로 발급받으세요.
03 온보딩 마법사로 돌아갑니다. 복사한 토큰을 붙여넣으면 됩니다.
검색 제공자 선택하기
토큰을 입력하고 나면 검색 제공자를 묻습니다. 원하는 검색 엔진을 선택하세요. 잘 모르겠다면 [Skip for now]를 선택해 넘어가도 괜찮습니다.
나만 명령할 수 있도록 설정하기
allowFrom을 묻습니다. 이건 ‘누가 이 봇을 쓸 수 있게 할 건가요?’라는 질문입니다. 이걸 설정해야 아무나 봇에게 명령을 내릴 수 없습니다.
01 allowFrom에는 본인의 텔레그램 user ID를 입력하면 됩니다. 텔레그램에서 @userinfobot 검색해서 대화를 시작합니다. /start를 보내면 본인의 user ID를 알려줍니다.
02 온보딩 마법사로 돌아가 user ID를 붙여넣습니다. 이제 여러분의 오픈클로는 여러분 본인만 사용할 수 있는 겁니다.
추가 기능 설정하기
이제 오픈클로 설정이 거의 끝났습니다. 이어서 설명하는 추가 기능 설정은 생략해도 됩니다. 나중에 필요할 때 언제든지 설정할 수 있습니다. 첫 번째는 오픈클로에게 유용한 스킬을 달아주는 과정입니다. 스킬은 오픈클로에게 특정 작업에 대한 설명과 수행 방법을 적어둔 설명서 같은 겁니다.
01 당장 스킬을 설정하고 싶지 않다면 [no]를 선택해서 지나갑니다. 하지만 몇몇 자주 사용하는 스킬은 미리 설정해두는 것을 추천합니다. [yes ➝ npm]을 선택하면 사용할 수 있는 스킬 목록이 나타납니다.
02 저는 구글 워크스페이스 작업을 위한 스킬을 추가해보겠습니다. gog, himalaya를 선택하세요. 나중에 필요한 스킬을 얼마든지 설치하고 활용할 수 있습니다.
03 스킬 설치가 끝났다면 API 키와 훅 사용 여부를 물어봅니다. 위치 정보 조회나 음성 생성 등을 위한 기능이지만 나중에도 설정할 수 있기 때문에 전부 [No]를 입력하여 넘어가겠습니다. ‘Enable Hooks?’는 훅 기능을 사용할 것인지 선택하는 옵션입니다. 이것도 [Skip for now]를 선택하고 나중에 필요할 때 활성화하겠습니다.
환경 변수 설정하기
온보딩에서 입력한 API 키는 ~/.openclaw/openclaw.json 파일에 저장합니다. 그대로 사용할 수도 있지만, 이 방식은 파일을 열어보면 키가 그대로 보여서 보안이 취약할 수 있습니다. 더 안전한 방법이 있습니다. 환경 변수에 키를 저장해두는 겁니다. 환경 변수는 컴퓨터가 기억하는 메모 같은 겁니다. API 키처럼 민감한 정보를 저장해두기 좋습니다. macOS는 ~/.zshrc 파일에서 환경 변수를 관리할 수 있습니다.
01 먼저 터미널을 열고, 다음 명령어를 입력하세요.
```
echo 'export OPENAI_API_KEY="sk-proj-여러분의키"' >> ~/.zshrc
```
echo 명령어는 따옴표 안의 내용을 그대로 출력하는 명령어입니다. export는 환경 변수를 추가하는 명령어입니다. 환경 변수는 다음과 같은 형태로 입력합니다. 우리는 GPT의 API 키를 사용하니 환경 변수 이름은 OPENAI_API_KEY이고, 큰따옴표 사이에는 이전에 복사한 키가 들어갑니다.
환경 변수 이름="값"
>>는 출력한 내용을 특정 파일에 추가하라는 뜻입니다. 그래서 따옴표 안에 있는 ‘export...’ 명령어를 ~/.zshrc 파일 맨 끝에 추가합니다.
02 환경 변수를 변경해도 터미널에 바로 적용되는 것은 아닙니다. 새로운 터미널을 시작해야 적용됩니다. 설정을 바로 적용하려면 이 명령어를 실행하세요.
```
source ~/.zshrc
```
이렇게 하면 ~/.zshrc 파일에 export OPENAI_API_KEY="..." 한 줄이 추가됩니다. 터미널이 실행될 때마다 이 파일을 읽어서 환경 변수를 설정합니다. 오픈클로는 실행될 때 OPENAI_API_KEY라는 이름을 찾아서 자동으로 사용합니다.
오픈클로는 API 키가 필요할 때 환경 변수를 먼저 찾아보고, 없다면 설정 파일인 openclaw.json에서 찾아 사용합니다.
게이트웨이 시작하고 메시지 보내기
온보딩 마법사가 어떤 환경에서 오픈클로 봇을 실행할지 물어봅니다. 오픈클로를 실행할 모든 준비가 끝난 겁니다.
01 오픈클로는 기본적으로 두 가지 실행 환경을 제공합니다. 터미널에서 대화하려면 [Hatch in TUI]를 선택합니다. 터미널이 어렵다면 [Open the web UI]를 선택해 웹브라우저에서 오픈클로와 대화할 수 있습니다.
02 종종 온보딩 과정 중에 작업이 꼬이는 경우 게이트웨이가 안 켜지는 경우가 있습니다. 이럴 때는 다음 명령어를 이용해서 게이트웨이를 수동으로 실행합니다.
```
openclaw gateway run --port 18789
```
화면에 이런 식으로 나오면 성공입니다.
```
[OpenClaw Gateway] Starting...
[Agent] Ready
[Gateway] Listening on port 18789
```
03 터미널로 오픈클로를 실행했다고 브라우저에서 사용하지 못하는 건 아닙니다. 언제든지 브라우저 대시보드를 열어볼 수 있습니다. 다음 명령어를 실행하세요.
```
openclaw dashboard
```
또는 브라우저에서 직접 http://127.0.0.1:18789로 접속해도 됩니다. 다른 포트번호로 실행했다면 18789 대신 실행한 포트 번호를 입력하면 됩니다. 이렇게 터미널이나 웹브라우저에서 오픈클로와 대화해도 좋습니다. 하지만 AI 비서를 어디에서나 활용하려면 스마트폰으로 대화하는 게 좋겠죠. 터미널이나 웹브라우저는 채널 연결이 원활하지 않을 때만 사용하겠습니다.
04 이제 텔레그램 앱을 열고 대화를 시작해보겠습니다. BotFather가 텔레그램 봇 토큰과 함께 채팅방 링크를 주었을 겁니다. 링크에 접속하면 새로운 대화가 열립니다. 여기서 우리가 방금 만든 봇과 대화할 수 있습니다. 먼저 나를 무엇으로 부를지 알려주고, AI 비서에게 이름과 역할을 만들어주세요.
05 답장이 왔다면 설정은 잘 끝난 겁니다. 우리의 AI 비서가 무사히 첫 출근을 했네요. 간단하게 첫 업무를 시킬 겸, 다음에 또 설치할 일이 생길 수 있으니 오픈클로 설정 과정을 정리해달라고 말해보겠습니다.
[나]
다음에 또 설치할 일이 있을 수 있으니까, 오픈클로 설정 과정을 처음부터 끝까지 정리해줘.
[/나]
이 정도면 기본은 된 겁니다. 시시하다고 생각하나요? 아직 워밍업입니다. 오픈클로의 진짜 능력은 파일을 읽고 쓰고, 웹을 검색하고, 스케줄에 맞춰 자동으로 일하는 데 있습니다. 여러분은 24시간 365일 컴퓨터에 상주하는 AI 비서를 얻었습니다. 다음 챕터부터 차근차근 배워볼 겁니다.
---
이렇게 오픈클로 설정이 끝났습니다. 나중에 새로운 컴퓨터에 다시 설치하거나 새로운 봇을 만든다면 비슷한 과정을 반복할 겁니다. 지금은 어려워도 나중에는 순식간에 새로운 봇을 만들어낼 수 있습니다. 혹시 설치가 잘 안 됐다면 도서의 문제가 생겼을 때를 참고해주세요.