OpenClaw 시작 가이드 설치부터 첫 프로젝트까지 빠르게 배우기

이 가이드는 오픈소스 AI 에이전트 프레임워크 OpenClaw의 설치부터 첫 프로젝트 생성까지의 전 과정을 상세히 안내합니다. 리눅스, macOS, Windows(WSL2) 환경에서의 Node.js 설치, 원클릭 스크립트 또는 npm을 이용한 간편한 설치 방법, API 키 설정, 그리고 ‘Hello, Agent!’ 프로젝트를 직접 실행하는 단계별 지침을 포함하여 누구나 쉽게 AI 에이전트 개발을 시작할 수 있도록 돕습니다.

sudo apt update
sudo apt install ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt update
sudo apt install nodejs -y

설치가 끝났으면 node --version 명령어를 입력하여 Node.js 버전이 22 이상으로 올바르게 설치되었는지 확인하세요.

macOS 및 Linux 사용자 (Node.js)

macOS와 리눅스 사용자 대부분은 Homebrew나 각 운영체제의 패키지 관리자를 통해 Node.js가 이미 설치되어 있을 수 있습니다. 터미널을 열고 node --version 명령어를 입력하여 Node.js가 설치되어 있는지 확인합니다. 또한, npm --version 명령어로 npm(Node Package Manager)의 버전도 함께 확인하는 것이 좋습니다. 만약 Node.js가 설치되어 있지 않다면, Node.js 공식 웹사이트(nodejs.org)에 방문하여 운영체제에 맞는 설치 파일을 다운로드하여 설치할 수 있습니다.

OpenClaw 설치 방법 상세 가이드 (단계별)

이제 준비가 끝났으니 본격적으로 OpenClaw를 설치할 차례입니다. 가장 안정적이고 빠른 OpenClaw 설치 방법 상세 가이드를 따라가 봅시다.

2.1. 가장 쉬운 방법: 원클릭 설치 스크립트 (모든 운영체제 공통)

이 방법은 OpenClaw 설치에 필요한 여러 가지 의존성(다른 프로그램들) 문제를 자동으로 해결해주기 때문에 가장 권장되는 방식입니다. Windows 사용자라면 위에서 설치한 WSL2 터미널을 열고 다음 명령어를 그대로 복사해서 붙여넣으세요.

curl -fsSL https://openclaw.ai/install.sh | bash

이 명령어를 실행하면 OpenClaw가 여러분의 시스템에 전역으로 설치되어, 어디서든 OpenClaw 명령어를 사용할 수 있게 됩니다. 이 스크립트가 알아서 모든 설정을 처리해주므로, 여러분은 기다리기만 하면 됩니다.

2.2. 대안: npm을 통한 전역 설치

만약 Node.js 환경에 익숙한 사용자라면 npm(Node Package Manager)을 통해 OpenClaw를 설치할 수도 있습니다.

Windows 사용자 주의사항: Windows PowerShell에서 npm 스크립트를 실행하려면 보안 정책을 변경해야 할 수도 있습니다. PowerShell을 열고 다음 명령어를 먼저 실행한 후, 프롬프트에서 ‘Y’를 입력하여 변경 사항을 승인하세요.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

설치 명령어: 이제 다음 명령어를 입력하여 OpenClaw를 전역으로 설치합니다.

npm install -g openclaw@latest

2.3. 설치 확인

설치가 성공적으로 완료되었는지 확인하는 것은 매우 중요합니다. 터미널에 openclaw --version을 입력했을 때, OpenClaw의 버전 번호가 출력된다면 정상적으로 설치된 것입니다. 만약 오류 메시지가 나타난다면, 이전 단계를 다시 확인해보거나 다음 섹션의 문제 해결 가이드를 참고하세요.

기본 설정 및 첫 AI 에이전트 프로젝트 생성: OpenClaw 기본 설정 및 초기 프로젝트 생성

OpenClaw 설치를 마쳤으니, 이제 기본적인 설정을 하고 여러분의 첫 AI 에이전트 프로젝트를 만들어볼 차례입니다. OpenClaw 기본 설정 및 초기 프로젝트 생성 과정을 통해 직접 AI 에이전트와 대화하는 경험을 해보세요.

3.1. 온보딩 가이드 실행 및 API 키 설정

OpenClaw는 처음 시작하는 사용자를 위해 대화형 설정 가이드(온보딩)를 제공합니다. 터미널에서 openclaw 또는 openclaw --guide 명령어를 실행하여 이 가이드를 시작합니다.

API 키 발급 상세 안내:
OpenClaw는 여러 AI 모델과 연결될 수 있지만, 이 가이드에서는 접근성이 좋고 사용하기 쉬운 Google AI Studio의 API 키를 사용하는 방법을 기준으로 설명하겠습니다.

먼저, 웹 브라우저를 열고 Google AI Studio (https://aistudio.google.com)에 접속합니다.
구글 계정으로 로그인합니다.
메뉴에서 ‘Get API key’를 선택한 후, ‘Create API key in new project’ 버튼을 클릭하여 새로운 API 키를 만듭니다.
생성된 API 키를 복사합니다. 이 키는 여러분의 AI 에이전트가 구글의 AI 모델과 통신할 수 있도록 해주는 중요한 열쇠입니다.
이제 OpenClaw 온보딩 가이드가 실행 중인 터미널로 돌아가서, API 키를 입력하라는 프롬프트가 나타나면 복사한 키를 붙여넣으세요. OpenClaw가 이 키를 환경 변수로 자동 저장하여 앞으로 쉽게 사용할 수 있게 합니다.

3.2. 첫 “Hello, Agent!” 프로젝트 생성

이제 첫 AI 에이전트 프로젝트를 만들어 봅시다.

프로젝트 디렉토리 생성: 먼저, 작업할 폴더를 만듭니다. 터미널에 다음 명령어를 입력하세요.
```
mkdir my-first-agent
cd my-first-agent
```
이 명령은 ‘my-first-agent’라는 새 폴더를 만들고, 그 폴더 안으로 이동하는 역할을 합니다.
OpenClaw 프로젝트 초기화: 현재 폴더를 OpenClaw 프로젝트로 만들기 위해 다음 명령어를 실행합니다.
```
openclaw init
```
이 명령어를 실행하면 OpenClaw 프로젝트의 기본적인 파일과 폴더 구조가 자동으로 생성됩니다.
프로젝트 구조 설명: openclaw init 명령을 실행하면 다음과 같은 폴더와 파일이 만들어지는 것을 볼 수 있습니다.
- agents/ 폴더: 이 폴더 안에 여러분이 만들 AI 에이전트의 생각(로직)과 질문(프롬프트)을 정의하는 파일들이 저장됩니다.
- openclaw.toml: 이 파일은 프로젝트의 전체적인 설정을 관리하는 중요한 파일입니다.
에이전트 실행: 이제 터미널에서 openclaw 명령어를 다시 실행해보세요.
```
openclaw
```
이 명령어를 입력하면, 프로젝트 폴더 안에서 대화형 터미널 사용자 인터페이스(TUI)가 실행됩니다. 이제 여러분은 직접 AI 에이전트와 대화를 시작하고 명령을 내릴 수 있습니다! ‘Hello, Agent!’라고 인사하며 첫 대화를 시도해 보세요.

OpenClaw 공식 문서 200% 활용법: OpenClaw 공식 문서 활용법

OpenClaw를 더 깊이 이해하고 능숙하게 사용하려면 공식 자료를 적극적으로 활용하는 것이 중요합니다. OpenClaw 공식 문서 활용법을 익혀 스스로 문제를 해결하고 새로운 아이디어를 얻는 능력을 길러봅시다.

4.1. 공식 문서: 모든 정보의 시작점

OpenClaw의 모든 기능, 개념, 그리고 사용 방법에 대한 가장 정확하고 최신 정보는 공식 문서에 있습니다.

공식 문서 URL: https://docs.openclaw.ai/
활용 팁: 문서 웹사이트의 왼쪽 사이드바에 있는 목차를 잘 활용해보세요. ‘Concepts’에서는 OpenClaw의 기본 개념을, ‘Guides’에서는 특정 작업을 수행하는 방법을 단계별로 배울 수 있습니다. ‘API Reference’는 더 전문적인 정보를 얻는 데 유용합니다. 체계적으로 문서를 읽는 습관을 들이면 OpenClaw 전문가가 될 수 있습니다.

4.2. GitHub 저장소: 실제 코드와 최신 동향 확인

OpenClaw는 오픈소스 프로젝트이므로, GitHub 저장소는 단순한 문서 그 이상입니다. 최신 업데이트 내역, 다른 사람들이 겪는 문제와 그 해결책, 그리고 다양한 예제 코드를 확인할 수 있는 아주 중요한 채널입니다.

GitHub 저장소 URL: https://github.com/openclaw/openclaw
활용 팁: ‘Issues’ 탭에서는 다른 사용자들이 보고한 버그나 개선 요청을 볼 수 있습니다. 여러분이 겪는 문제가 이미 해결되었을 수도 있으니 검색해보세요. ‘Discussions’ 탭에서는 다른 개발자들과 아이디어를 나누거나 질문을 할 수 있습니다. 실제 코드를 직접 살펴보는 것도 OpenClaw의 동작 방식을 이해하는 데 큰 도움이 됩니다.

4.3. 터미널 내장 도움말 활용

가장 빠르고 간단하게 명령어 옵션을 확인하는 방법은 바로 터미널 내장 도움말을 사용하는 것입니다.

터미널에 openclaw --help 명령어를 입력해보세요. OpenClaw가 제공하는 모든 명령어와 각 명령어에 사용할 수 있는 다양한 옵션들이 보기 쉽게 정리되어 출력됩니다. 특정 명령어에 대한 도움말이 필요하다면, openclaw [명령어] --help와 같이 입력하여 상세 정보를 얻을 수 있습니다. 예를 들어, openclaw init --help는 init 명령어에 대한 자세한 도움말을 보여줄 것입니다.

자주 묻는 질문 및 문제 해결 (FAQ & Troubleshooting)

초보자들이 OpenClaw를 설치하고 사용하는 과정에서 흔히 겪는 문제와 그 해결책을 미리 알아두면 시간을 절약하고 더욱 즐겁게 학습할 수 있습니다.

Q1. Windows에서 WSL2 설치 중 오류가 발생합니다.

A. PowerShell을 ‘관리자 권한’으로 실행했는지 다시 확인해 주세요. 관리자 권한이 없으면 일부 중요한 작업이 제대로 진행되지 않을 수 있습니다. 또한, wsl --update 명령어를 실행하여 WSL 자체를 최신 버전으로 업데이트한 후 다시 시도해보는 것이 좋습니다. WSL 관련 오류는 대부분 이러한 기본적인 조치로 해결됩니다.

Q2. `npm install` 시 권한 오류(Permission Denied)가 발생합니다.

A. macOS나 Linux에서는 시스템 전체에 프로그램을 설치할 때 특별한 권한이 필요할 수 있습니다. 이럴 때는 명령어 앞에 sudo를 붙여 sudo npm install -g openclaw@latest와 같이 실행해보세요. sudo는 관리자 권한으로 명령을 실행하게 해주는 명령어입니다.

Q3. npm 설치가 계속 실패합니다.

A. 때때로 npm 캐시에 문제가 생겨 설치가 잘 안 될 수 있습니다. 이럴 때는 npm cache clean --force 명령어로 npm 캐시를 깨끗하게 정리한 후, 다시 설치를 시도해보세요. 캐시를 정리하면 이전에 저장된 불필요하거나 손상된 데이터가 제거되어 새로운 설치가 원활하게 진행될 수 있습니다.

결론: 오픈소스 AI 에이전트 프로젝트 시작하기, OpenClaw와 함께!

이 가이드를 통해 OpenClaw 설치, 개발 환경 구축, 그리고 첫 AI 에이전트 프로젝트 생성까지의 모든 과정을 성공적으로 마쳤습니다. 축하합니다! 이제 여러분은 자신만의 아이디어를 현실로 만들 수 있는 강력한 AI 에이전트 개발 도구를 손에 넣었습니다. 지금부터가 진짜 오픈소스 AI 에이전트 프로젝트 시작하기의 첫걸음입니다.

OpenClaw는 끊임없이 발전하고 있는 오픈소스 프로젝트입니다. 공식 문서와 GitHub 커뮤니티에 적극적으로 참여하여 더 많은 정보를 얻고, 다른 개발자들과 교류하며 여러분만의 혁신적인 AI 에이전트를 만들어보세요. 상상하는 모든 것을 현실로 만들 수 있는 OpenClaw의 세계가 여러분을 기다리고 있습니다!

이 글이 마음에 드세요?

RSS 피드를 구독하세요!

목차

Linux 사용자 (Node.js)