오픈클로 설치 방법

작성자:

AI 에이전트 OpenClaw 로컬 실행 가이드

AI 에이전트에 관심이 있다면 OpenClaw라는 이름을 들어봤을 수 있습니다. 오픈클로(OpenClaw)는 사용자가 쓰는 채팅 앱이나 로컬 환경에서 AI 에이전트를 실행하고, 여러 작업 흐름을 연결할 수 있도록 설계된 오픈소스 기반 AI 에이전트 플랫폼입니다.

일반 챗봇이 질문에 답하는 데 초점이 있다면, AI 에이전트는 사용자의 목표를 이해하고 여러 단계를 거쳐 결과를 만드는 데 초점이 있습니다. OpenClaw는 이런 AI 에이전트 구조를 로컬 PC나 개인 서버에서 실행해볼 수 있는 도구로 소개되고 있습니다. OpenClaw 공식 사이트는 “The AI that actually does things”라는 설명과 함께 macOS, Windows, Linux에서 실행할 수 있고, 채팅 앱 기반 사용 흐름을 제공한다고 안내합니다.

이 글에서는 오픈클로 설치 방법, 설치 전 준비사항, 운영체제별 설치 명령어, 온보딩 설정, 설치 후 확인 방법, 자주 발생하는 문제를 초보자도 따라 할 수 있게 정리합니다.

1. 한 줄 요약

오픈클로(OpenClaw)는 로컬 PC나 서버에서 실행할 수 있는 AI 에이전트 플랫폼이며, macOS/Linux에서는 설치 스크립트 또는 npm으로, Windows에서는 PowerShell 또는 WSL2 환경에서 설치할 수 있습니다.

공식 문서 기준으로 빠른 설치는 다음 흐름입니다. macOS/Linux에서는 설치 스크립트를 실행하고, 이후 openclaw onboard --install-daemon 명령으로 초기 설정을 진행합니다. Windows에서는 PowerShell 설치 스크립트가 제공되며, 문서에서는 WSL2 사용도 권장합니다.

2. 쉽게 설명하면?

오픈클로는 내 컴퓨터에 설치하는 AI 에이전트 실행 도구라고 보면 됩니다.

예를 들어 ChatGPT 같은 서비스는 웹사이트에 접속해서 대화하는 방식입니다. 반면 OpenClaw는 로컬 환경 또는 개인 서버에 설치해서, 내가 선택한 AI 모델과 여러 채널을 연결해 사용할 수 있는 구조를 목표로 합니다.

쉽게 비유하면 다음과 같습니다.

구분비유
일반 챗봇질문하면 답하는 상담원
AI 에이전트목표를 보고 필요한 단계를 정리하는 업무 보조자
OpenClaw그 AI 에이전트를 내 환경에서 실행하게 해주는 운영 도구

OpenClaw 문서에서는 WhatsApp, Discord, Telegram, Slack, Microsoft Teams 등 다양한 채널과 연결 가능한 게이트웨이형 AI 에이전트 플랫폼으로 설명합니다.

3. 기술적으로는 무슨 뜻인가?

기술적으로 OpenClaw는 AI 모델, 채팅 채널, 플러그인, 로컬 실행 환경을 연결하는 에이전트 게이트웨이에 가깝습니다.

OpenClaw는 단순히 “AI 모델 하나를 실행하는 프로그램”이 아니라, 사용자가 쓰는 채널에서 메시지를 받고, 선택한 LLM에 요청을 보내고, 결과를 다시 사용자에게 전달하는 구조를 가질 수 있습니다.

구성 요소설명
OpenClaw CLI설치, 온보딩, 실행을 위한 명령어 도구
Gateway채팅 앱과 AI 모델 사이를 연결하는 실행 계층
LLM ProviderOpenAI, Anthropic, Google, 로컬 모델 등
ChannelTelegram, Discord, Slack 같은 연결 채널
Onboarding모델 제공자, API 키, Gateway 설정을 진행하는 초기 설정
Local Runtime사용자의 PC나 서버에서 OpenClaw를 실행하는 환경

OpenClaw Getting Started 문서는 설치 후 openclaw onboard --install-daemon을 실행하면 모델 제공자 선택, API 키 설정, Gateway 구성을 안내한다고 설명합니다.

4. 왜 필요한가?

OpenClaw 같은 AI 에이전트 도구가 필요한 이유는 단순 챗봇을 넘어 내가 사용하는 업무 흐름에 AI를 연결하고 싶기 때문입니다.

예를 들어 다음과 같은 상황에서 OpenClaw를 검토할 수 있습니다.

상황OpenClaw가 필요한 이유
로컬에서 AI 에이전트를 실험하고 싶음내 PC 또는 서버에서 실행 가능
다양한 채팅 앱과 연결하고 싶음여러 채널 연동을 목표로 함
특정 LLM 제공자를 선택하고 싶음여러 모델 제공자와 연결 가능
사내/개인 자동화 실험을 하고 싶음에이전트형 작업 흐름 실험 가능
로컬 모델을 써보고 싶음Ollama 같은 로컬 모델 연동 가능성이 안내됨

OpenClaw 소개 문서에서는 Claude, GPT, Gemini, Llama, Mistral 또는 Ollama 기반 로컬 모델 등 다양한 모델을 사용할 수 있다고 설명합니다.

5. 설치 전 준비사항

OpenClaw를 설치하기 전에 아래 항목을 확인하세요.

준비사항설명
운영체제macOS, Linux, Windows 지원
Node.jsNode 24 권장, Node 22.14 이상 지원
모델 제공자 API 키OpenAI, Anthropic, Google 등 모델 제공자 키 필요
터미널 사용macOS/Linux Terminal, Windows PowerShell 또는 WSL2
네트워크 연결설치 파일과 모델 관련 패키지 다운로드 필요
기본 개발 지식명령어 실행, 환경변수, API 키 개념 이해 권장

공식 Getting Started 문서는 Node.js 24를 권장하고 Node 22.14 이상도 지원한다고 안내하며, 온보딩 과정에서 모델 제공자 API 키를 입력하게 된다고 설명합니다.

용어 풀이

용어쉬운 설명
Node.jsJavaScript를 서버나 로컬 환경에서 실행할 수 있게 해주는 런타임
CLI명령어로 프로그램을 실행하는 도구
API 키외부 AI 모델 서비스를 사용할 때 필요한 인증 키
WSL2Windows에서 Linux 환경을 실행할 수 있게 해주는 기능
Daemon백그라운드에서 계속 실행되는 프로그램

6. macOS / Linux 설치 방법

macOS 또는 Linux에서는 공식 문서 기준으로 설치 스크립트를 사용할 수 있습니다.

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

설치 후 온보딩을 실행합니다.

openclaw onboard --install-daemon

공식 Getting Started 문서도 macOS/Linux 설치 후 openclaw onboard --install-daemon으로 온보딩을 진행한다고 설명합니다.

설치 흐름

단계명령 또는 작업
1터미널 실행
2설치 스크립트 실행
3설치 완료 확인
4openclaw onboard --install-daemon 실행
5모델 제공자 선택
6API 키 입력
7Gateway 설정 완료
8테스트 대화 실행

보안상 주의

curl ... | bash 방식은 편리하지만, 외부 스크립트를 바로 실행하는 방식입니다. 보안에 민감한 환경이라면 스크립트를 먼저 내려받아 내용을 확인한 뒤 실행하는 것이 좋습니다.

예시:

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

7. Windows 설치 방법

Windows에서는 PowerShell 설치 방식이 안내되어 있습니다.

iwr -useb https://openclaw.ai/install.ps1 | iex

또는 Windows에서 WSL2를 사용하는 방법도 권장됩니다. OpenClaw 설치 문서에서는 Windows 사용자의 경우 WSL2 환경이 더 안정적이라고 안내합니다.

Windows 설치 흐름

단계설명
1PowerShell을 관리자 권한으로 실행
2설치 명령어 실행
3설치 완료 후 터미널 재시작
4openclaw onboard 또는 온보딩 명령 실행
5모델 제공자와 API 키 설정
6정상 실행 확인

Windows에서 WSL2를 쓰는 경우

WSL2를 사용한다면 Ubuntu 같은 Linux 배포판을 설치한 뒤, macOS/Linux 설치 명령어와 비슷한 방식으로 진행할 수 있습니다.

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

WSL2는 Windows 안에서 Linux 환경을 쓰는 방식이므로, 개발 도구 설치나 서버형 도구 실행에 더 적합한 경우가 많습니다.

8. npm으로 설치하는 방법

Node.js가 이미 설치되어 있다면 npm 방식으로 설치할 수도 있습니다.

npm install -g openclaw@latest

설치 후 온보딩을 실행합니다.

openclaw onboard --install-daemon

OpenClaw 문서와 홈페이지는 npm 설치 방식도 함께 제시하고 있습니다.

npm 설치가 적합한 경우

상황설명
Node.js가 이미 설치되어 있음별도 설치 스크립트 없이 npm으로 설치 가능
개발자가 직접 버전 관리하고 싶음패키지 버전 확인이 쉬움
설치 과정을 명확히 통제하고 싶음자동 설치 스크립트보다 예측 가능

Node 버전을 먼저 확인하려면 아래 명령어를 사용합니다.

node --version
npm --version

Node.js 버전이 낮다면 먼저 Node.js를 업데이트해야 합니다.

9. 소스 코드로 설치하는 방법

소스 코드를 직접 확인하거나 수정하고 싶은 개발자는 GitHub 저장소를 클론해서 실행할 수 있습니다.

공식 홈페이지는 소스 체크아웃 방식으로 아래 흐름을 안내합니다.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install
pnpm openclaw onboard

소스 설치가 적합한 경우

상황설명
내부 구조를 분석하고 싶음코드 확인 가능
플러그인이나 기능을 수정하고 싶음직접 커스터마이징 가능
최신 개발 버전을 테스트하고 싶음릴리스 전 기능 확인 가능
기여를 고려하고 있음오픈소스 개발 흐름에 참여 가능

다만 일반 사용자는 설치 스크립트나 npm 방식을 먼저 사용하는 것이 더 쉽습니다.

10. 설치 후 온보딩 설정

OpenClaw 설치 후 가장 중요한 단계는 온보딩입니다.

openclaw onboard --install-daemon

온보딩에서는 보통 다음 설정을 진행합니다.

설정 항목설명
모델 제공자 선택사용할 LLM 제공자를 선택
API 키 입력선택한 모델 제공자의 인증 키 입력
Gateway 설정OpenClaw 실행 환경 구성
채널 연결사용할 채팅 채널 설정
테스트 대화정상 작동 여부 확인

Getting Started 문서도 온보딩 과정에서 모델 제공자 선택, API 키 설정, Gateway 구성을 진행한다고 설명합니다.

API 키 주의사항

API 키는 비밀번호와 비슷하게 취급해야 합니다.

  • 공개 저장소에 올리지 않기
  • 화면 공유 중 노출하지 않기
  • 팀원과 공유할 때 권한 범위 확인하기
  • 필요하면 사용량 제한 설정하기
  • 테스트 후 불필요한 키는 폐기하기

11. 설치 확인 방법

설치가 끝났다면 아래 명령어로 OpenClaw가 정상 설치되었는지 확인할 수 있습니다.

openclaw --version

또는 도움말을 확인합니다.

openclaw --help

온보딩을 다시 실행하려면 다음 명령어를 사용할 수 있습니다.

openclaw onboard

정상 설치 후에는 OpenClaw가 Gateway를 실행하고, 설정한 모델과 채널을 통해 대화가 가능한지 확인해야 합니다.

12. 자주 발생하는 오류와 해결 방법

OpenClaw 설치 중에는 아래 문제가 발생할 수 있습니다.

문제원인해결 방법
openclaw 명령어를 찾을 수 없음PATH 설정 문제터미널 재시작, npm global 경로 확인
Node 버전 오류Node.js 버전이 낮음Node.js 22.14 이상 또는 권장 버전 설치
온보딩 실패API 키 또는 모델 제공자 설정 문제API 키 재확인, 제공자 설정 확인
Windows에서 실행 오류네이티브 환경 호환 문제WSL2 환경에서 재시도
설치 스크립트 실패네트워크 또는 권한 문제관리자 권한, 네트워크 상태 확인
응답이 오지 않음Gateway 또는 모델 설정 문제Gateway 실행 상태와 로그 확인

Windows 사용자의 경우 WSL2가 더 안정적이라고 안내되는 문서가 있으므로, PowerShell 방식에서 문제가 반복되면 WSL2 설치를 검토하는 것이 좋습니다.

13. OpenClaw와 Ollama를 함께 사용할 수 있을까?

OpenClaw 소개 문서에서는 OpenAI, Anthropic, Google 같은 클라우드 모델뿐 아니라 Llama, Mistral, Ollama 기반 로컬 모델 사용도 언급합니다.

즉, 로컬 LLM을 선호한다면 Ollama와 함께 사용하는 구성을 검토할 수 있습니다.

구성설명
OpenClawAI 에이전트 실행과 채널 연결
Ollama로컬 LLM 실행
LLM실제 답변을 생성하는 모델
채팅 채널사용자가 대화하는 인터페이스

다만 실제 연동 방식은 OpenClaw 버전과 설정 파일 구조에 따라 달라질 수 있으므로, 사용 중인 버전의 공식 문서를 확인해야 합니다.

14. OpenClaw 설치 전 보안 체크리스트

AI 에이전트 도구는 여러 채널, 문서, 모델과 연결될 수 있기 때문에 보안 기준이 중요합니다.

체크 항목확인 내용
API 키 관리키가 외부에 노출되지 않도록 관리
사용량 제한과도한 API 사용 방지
채널 연결필요한 채널만 연결
권한 범위파일, 문서, 메시지 접근 범위 확인
로그 관리대화와 실행 기록 저장 여부 확인
로컬 실행개인 PC 또는 서버 보안 상태 점검
업데이트최신 보안 패치 적용

OpenClaw 문서에서는 self-hosted 구조와 sandbox, permissions, API key management 같은 보안 주제를 별도 섹션으로 다루고 있습니다.

15. 실제 설치 순서 요약

초보자라면 아래 순서대로 진행하면 됩니다.

macOS / Linux 권장 순서

node --version
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw --help

Windows 권장 순서

iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw onboard
openclaw --help

npm 설치 순서

node --version
npm install -g openclaw@latest
openclaw onboard --install-daemon

16. 오픈클로 설치 후 무엇을 해볼까?

설치 후에는 바로 큰 자동화를 만들기보다 작은 실습부터 해보는 것이 좋습니다.

실습목적
기본 대화 테스트모델 연결 확인
간단한 요약 요청답변 품질 확인
채널 하나 연결메시지 흐름 확인
로컬 모델 연결Ollama 사용 가능성 확인
짧은 업무 흐름 구성AI 에이전트 개념 이해

처음에는 “한 가지 채널 + 한 가지 모델 + 한 가지 작업”으로 시작하는 것이 좋습니다. 너무 많은 기능을 한 번에 연결하면 오류 원인을 찾기 어렵습니다.

17. 자주 묻는 질문

Q1. OpenClaw는 AI 모델인가요?

아닙니다. OpenClaw는 AI 모델 자체가 아니라, AI 모델과 채널, 작업 흐름을 연결하는 AI 에이전트 플랫폼에 가깝습니다.

Q2. OpenClaw 설치에 Node.js가 필요한가요?

공식 Getting Started 문서 기준으로 Node.js가 필요하며, Node 24 권장, Node 22.14 이상 지원으로 안내됩니다.

Q3. Windows에서도 설치할 수 있나요?

가능합니다. PowerShell 설치 명령이 제공되며, 문서에서는 WSL2 환경도 권장합니다.

Q4. API 키가 꼭 필요한가요?

클라우드 LLM 제공자를 사용할 경우 API 키가 필요합니다. 온보딩 과정에서 모델 제공자와 API 키 설정을 진행합니다.

Q5. Ollama와 함께 사용할 수 있나요?

OpenClaw 소개 문서에서는 로컬 모델과 Ollama 사용 가능성을 언급합니다. 다만 실제 설정 방법은 버전에 따라 달라질 수 있으므로 사용 중인 문서를 확인해야 합니다.

Q6. 설치 스크립트를 바로 실행해도 되나요?

편리하지만 보안상 스크립트 내용을 먼저 확인하는 것이 좋습니다. 특히 회사 PC나 서버에서는 보안 정책을 확인한 뒤 실행해야 합니다.

Q7. 초보자는 어떤 설치 방식을 선택하면 좋나요?

macOS/Linux 사용자는 공식 설치 스크립트, Windows 사용자는 WSL2 또는 PowerShell 방식을 먼저 검토하면 좋습니다. 개발자는 npm 설치도 편리합니다.

18. 정리

OpenClaw는 AI 에이전트를 로컬 PC나 개인 서버에서 실행하고, 다양한 채널과 LLM을 연결하기 위한 오픈소스 기반 도구로 소개되고 있습니다. 공식 문서 기준으로 macOS, Linux, Windows를 지원하며, Node.js와 모델 제공자 API 키가 필요합니다.

가장 쉬운 설치 흐름은 macOS/Linux에서 설치 스크립트를 실행한 뒤 openclaw onboard --install-daemon으로 초기 설정을 진행하는 방식입니다. Windows에서는 PowerShell 설치 방식이 제공되며, 안정적인 사용을 위해 WSL2 환경도 권장됩니다.

AI 에이전트 도구는 일반 챗봇보다 더 많은 권한과 연결 지점을 가질 수 있으므로, 설치 전 API 키 관리, 채널 연결 범위, 로그 관리, 데이터 접근 범위를 반드시 확인해야 합니다. 처음에는 작은 모델, 한 가지 채널, 단순한 작업부터 시작하는 것이 안전합니다.

댓글 남기기