지난 1편 [openclaw 설치하기 1] 에서 깃(Git)과 도커(Docker)라는 튼튼한 대지를 다졌으니, 이제 진짜 건물을 올리고 내 첫 번째 AI 에이전트를 입주 시켜 볼 차례다.
사실 1편에서 귀여운 고양이 UI(Star Office UI)를 당장이라도 보여줄 것처럼 호들갑을 떨었지만... 고백하자면 아직 거기까지 스터디를 못 했다. (퇴근하고 헬스장 다녀와서 언제 그걸 다 연결하고 있겠는가 ㅠㅠ) 언젠간 내 화면에 고양이들을 풀어놓고 말겠다는 원대한 꿈을 안고, 오늘은 일단 텍스트로만 소통하는 '기본형 에이전트'부터 무사히 출근 시켜 보겠다.
혹시라도 내 야매(?) 삽질기가 불안하거나 더 깊고 정확한 내용이 궁금하다면,
언제든 오픈클로 공식문서를 펼쳐보길 권한다.
참고로, 공식 문서에서는 '샌드박스(Sandbox)'라는 모드를 소개하고 있다.
깃의 브랜치(Branch)처럼 버전을 격리해서 안전하게 테스트할 수 있는 훌륭한 기능이다. 하지만 나는 윈도우 환경이 꼬이는 게 세상에서 제일 무서운 사람이기 때문에, 공식 문서에서 강력하게 권장하는 방법이 아님에도 불구하고 가장 환경 변수 통제가 확실하고 삭제가 편리한 도커(Docker) 설치 방식을 선택했다.
1. 셋업 시작하기: 마법의 주문 입력
지난번 포스팅 마지막 단계에서 우리는 터미널(CMD 혹은 PowerShell)을 열고 openclaw폴더 안까지 들어와 있는 상태였다. (경로가 C:\...\openclaw> 로 끝나면 맞다.)
이제 에이전트를 생성하는 마법의 주문을 입력해 준다.
(이때 터미널이 관리자 권한으로 실행되어 있어야 했던 것 같은데, 정확히 기억이 안 난다. 혹시 에러가 난다면 관리자 권한으로 터미널을 다시 열어보자.)
./docker-setup.sh
엔터를 치면 화면에 무언가 촤르륵 올라가면서 도커가 알아서 설치와 세팅을 시작한다.
이게 제대로 설치된 건지 불안하다면 Docker Desktop 프로그램을 열어보자.
 |
| 사실 오른쪽 아래 Terminal을 눌러 docker설치 파일을 실행할 수도 있다. |
딱 두 가지를 확인 하면 된다.
1. Images 탭에 openclaw 관련 이미지가 잘 구워졌는지 확인
2. Containers 탭에 openclaw 컨테이너가 초록 불을 켜고 잘 들어와 있는지 확인!
참고로 위에 있는 ollama는 LLM모델을 로컬에서 작동 시키는 방식인데, 다루는 방법은 추후에 다루도록 하겠다.
아마 자동으로 온보딩 창이 떴을 것이다.
[주의] 깃(Git) 버전 오류 삽질기
명령어를 치면 터미널 안에서 키보드 방향 키로 움직일 수 있는 예쁜 온보딩 UI가 떠야 한다. 그런데 여기서 체크박스가 제대로 표시되지 않거나 스페이스바를 눌러도 선택이 안 되는 난감한 현상이 발생할 수 있다.
원인은 구버전 Git 때문이었다. 당황하지 말고 지난번에 설명했던 아래 명령어로 깃 버전을 확인하고 업데이트를 해주자.
git --version (현재 버전 확인)git update-git-for-windows (깃 최신 버전으로 업데이트)
업데이트가 무사히 끝났다면 다시 ./docker-setup.sh를 입력해서 설치를 재개하면 된다.
2. 오픈클로 온보딩: 뇌와 입을 달아주자
셋업 스크립트가 무사히 돌아가면, 터미널 창에 꽤나 힙한 OpenClaw 로고가 뜨면서 우리를 반겨준다.
이제 에이전트의 초기 설정을 잡아주는 과정이다. 방향 키와 스페이스바, 엔터 키를 이용해 다음 단계들을 하나씩 격파해 보자.
(현재 2026-04-03 최신 버전의 openclaw를 사용 중이다. 버전이 변경되면 온보딩 항목이 달라질 수 있다)
1) 약관 동의
당연히 동의(Yes)를 눌러준다.
2) 모드 선택
우리는 초보이기 때문에 QuickStart를 눌러준다.
3) 모델 적용 (에이전트의 뇌 연결하기)
에이전트가 생각을 하려면 LLM(Large Language Model) API 키가 필요하다. 지난번에 언급했 듯 우리는 무료를 사랑하니까, Google AI Studio에 들어가서 무료 버전(Gemini) API 키를 하나 발급 받아보자.
1. 구글 AI Studio에 접속한 뒤, 왼쪽 하단의
Get API Key를 눌러준다.
2. 우측 상단의
API 키 만들기를 선택한다.
3. 팝업창에서 키 이름 지정에 아무 이름이나(나는 openclaw-test로 지정했다.) 넣어주고, 가져올 프로젝트 선택에는 만들어둔 프로젝트가 없으니 프로젝트 만들기를 선택한다. (프로젝트명도 openclaw-test로 지정했다.)
이제 API키가 만들어졌다. 결제 설정을 하지 않으면 무료 계정으로 사용할 수 있다. API rate 초과했다는 메시지를 자주 보게 되겠지만, 처음 세팅할때부터 과금하는건 절대 추천하지 않는다. (돈이 매우 많다면...한번 해보시라...)
첫 번째 줄에 있는
API 키를 잘 복사해두자.
...
다시 온보딩으로 돌아오자!
Model을 설정하라고 하는데, Model/Auth Provider가 어마어마하게 많다.
claude, copilot, OpenAI, Deepseek 등 한번쯤 들어봤을 법한 이름들도 보인다.
그중 우리는
Google을 선택 할 것이다.(쭉 내려서 엔터!)
그럼 권한을 설정하는 탭이 뜨는데, Gemini CLI OAuth와 Google Gemini API key 중 하나를 선택할 수 있다. Google Gemini API key를 선택하여, 아까 복사해둔 API 키를 입력해준다.
참고 Gemini CLI OAuth는 우리가 흔히 쓰는 Gemini (챗봇 서버?라고 이해하면 좀 비슷하려나) Gemini 권한을 가져와서 openclaw에 연결한다는 말이다. 이 경우 약관 위반으로 구글 계정이 정지당한 사례도 있다고 한다...
4) 대시보드(Dashboard) 불러오기
이 부분에서도 생각보다 친절하지 않은 가이드 탓에 삽질을 조금 많이 했다.
openclaw가 잘 구동되는지 확인하기 위해 지정된 주소로 들어가 대시보드를 확인하라고 한다.
대시보드 진입 주소는 도커 컨테이너 내부의 터미널에서 명령어를 입력하면 확인할 수 있다.
도커 데스크탑 프로그램 내에서 진입가능하지만 오늘은 명령어도 알아볼 겸 일반 터미널에서,
docker ps -a(도커 컨테이너 리스트 확인)
docker exec [컨테이너ID] /bin/bash (컨테이너 내부로 진입)
이 두가지 명령어로 컨테이너 내부 터미널에 진입하자.
openclaw gateway run
을 입력하면 openclaw의 대시보드가 실행되는 주소가 나오는데,
localhost:18789를 기본으로 사용할 것이다.
여기서!
로그인 화면에서 진입이 안된다! 무슨 토큰키를 받으라는데?
그렇다면 잘 오셨다.
오픈클로는 기본적으로 토큰값을 가진 사용자만 대시보드에 진입할 수 있게 보안이 설정되어있다.
그럼 이번엔 다른 명령어를 입력해보자.
openclaw dashboard --no-open
이 명령어를 입력하면 토큰값이 포함된 url주소가 나온다.
이걸 입력해서 들어가자.
여기서!
권한이 없다고 뜬다면 이번엔 기기 등록을 해줘야한다.
컴퓨터를 변경하거나 새로 설치하여 오픈클로를 첫 실행할 경우 기기를 페어링해주어야한다.
openclaw devices list (권한 요청한 기기 확인)
openclaw devices approve --latest (최신 버전으로 권한 승인)
이 두개의 명령어를 입력해준다. approved가 뜬다면 이제 오픈클로는 실행된것이다.
이제 토큰값을 포함한 대시보드 URL을 클릭하면 바로 접속이 된다!!
5) 채널 연결 (에이전트의 입과 귀 달아주기)
머리가 생겼으니 이제 소통할 공간이 필요하다. 오픈클로에서는 텔레그램, 왓츠앱 등 다른 메신저 프로그램으로도 소통하지만, 한국인에게 그래도 가장 친숙한 채팅 프로그램은 디스코드인것같다. 디스코드로 설치하자.
1. 디스코드에 나만의 서버를 하나 파둔다. (다른 사람이 들어있는 서버는 사람들의 대화에 전부 대답을 하는 문제가 생길 수 있어 추천하지 않는다)
2. 디스코드 개발자 포털(Developer Portal)에 들어가서 신규 애플리케이션을 하나 만든다. 에이전트의 이름도 붙여주자.
이후
봇 탭에 들어가서
토큰 초기화를 눌러준다.
오픈클로에 토큰값을 넣어줘야하니 잘 기억하자!!토큰 값은 텍스트나 엑셀 파일에 잘 보관해두자. 이건 열쇠와 같으니 유출되거나 없어지면 재발급 받아야한다.
하단에 있는 Presence Intent , Server Members Intent, Message Content Intent를 모두 켜주자.
3. OAuth2 탭에 들어가자.
스코프에서
bot, applications.commands를 체크해주고, 하단의
봇 권한에서
채널보기, 메시지 보내기, 링크 임베드, 파일첨부, 메시지 기록보기, 반응추가를 켜준다.
그리고 하단의 URL을 복사하여 주소창에 붙여넣으면 내 채널에 우리가 만든 AI봇이 들어온다.
프사도 넣어주고... 이름도 예쁘게 지어주자.
4. 디스코드 설정 > 고급 > 개발자모드를 켜준다. 이제 서버와 채널 아이디를 확인할 수 있다.
다시 온보딩으로 돌아오자!
Select channel 에서, discord를 선택한 후, Enter Discord bot token이 떴을때, 아까 복사해둔 봇 토큰을 넣어준다.
discord channels access에서는 Allowlist를 선택해준다. Open의 경우, 얘가 모든 채널의 말을 듣고 대답하며 토큰 먹는 귀신이 될 수 있다고 한다...
이제 Discord channels allowlist를 적어줘야 하는데, 서버명을 우클릭하면 아까 개발자 모드를 켰기 때문에 서버ID복사하기가 활성화되어있다. 또한, AI가 작업할 채팅 채널을 우클릭하면 채널 ID 복사하기도 가능하다.
이제 Discord channels allowlist에 서버ID/채널ID의 형태로 넣어준다.
5) Search Engine 설정
웹 검색을 할 수 있게 해주는 기능들을 켜는 곳이다. 일단 다 꺼준다.
"어? 검색 못하면 바보 되는 거 아니야?"라고 걱정할 필요 없다. 추후에 설정 파일에서 얼마든지 다시 켤 수 있으니, 지금은 초기 에러를 잡기 위해 짐을 가볍게 챙기는 것이 좋다.
6) Configuer skills now?
skill도 나중에 설정할 수 있다. 일단 skip하고 넘어가자.
(사실 npm 오류 때문에 clawhub 설치가 안됐었다. 이 부분은 스킬 설명할 때 다루겠다)
나머지 api 연결 하라는 것도 전부 no를 외치며 넘어가준다.
5) Hooks
Hook은 ai가 문제가 생겼을 때 어떻게 행동할 지에 대한 내용들이다. 나중에 사용하다 보면 이 녀석이 파일 전체를 읽느라 토큰(API 사용량)을 과도하게 잡아먹는다며 끄라는 조언들이 많다. 하지만 초기 세팅을 마치고 이 에이전트가 내 문서들을 어떻게 읽고 파악하는지 '감'을 잡으려면 초반에는 전부 켜두는 것을 추천한다. 특히 bootstrap은 꼭 켜두자...
3. 첫 출근을 축하합니다
온보딩의 모든 과정을 마치고 엔터를 누르면 약간의 시간이 지나고 설정이 저장된다.
그리고 아까 만들어둔 디스코드 서버를 슬쩍 확인해 보자. 오프라인으로 죽어있던 내 봇의 프로필에 초록불이 들어오며 '온라인'으로 로그인되어 있다면?
축하한다!
길고 길었던 삽질 끝에 드디어 첫 번째 에이전트가 내 디스코드 사무소로 출근을 완료했다. 아직 눈에 보이는 귀여운 아바타는 없지만, 디스코드 창에서 내 말에 대답하는 녀석을 보면 꽤나 뿌듯해질 것이다.
다음 편에서는 이렇게 만든 에이전트 여러 마리(?)가 함께 일하는 환경에 대한 개념과, 그 복작복작한 멀티 에이전트 워크스페이스를 어떻게 구성할 수 있는지에 대해 적어보겠다. 건축 사무소로 치면 막내 신입 한 명 뽑았으니, 이제 팀장님을 모셔 올 차례다.
댓글
댓글 쓰기