OpenClaw 설치하기 - Ollama 기반 로컬 AI 에이전트 환경 구축

최근 로컬 LLM과 AI 에이전트 도구들이 빠르게 등장하고 있는데, 그중 OpenClaw는 로컬 환경에서 실행할 수 있는 AI 에이전트 런타임입니다. 이 글에서는 Ollama와 OpenClaw를 이용해 Mac 환경에서 로컬 AI 에이전트를 설치하고 실행하는 방법을 정리합니다.

 

0. 어떤 이를 위한 글인가

리눅스(유닉스 포함)의 기본 명령에 익숙하고 ChatGPT를 잘 부릴 줄 알며 자동화에 관심이 많은 엔지니어나 개발자인데 OpenClaw를 처음 접하는 분들을 위한 글입니다. 맥북프로 M시리즈에 설치된 macOS 26.3을 기준으로 로컬 LLM을 활용한 AI 에이전트의 핵심 기능을 빠르게 체험해 보도록 하겠습니다.

---

1. OpenClaw 개념

1) OpenClaw란 무엇인가

OpenClaw는 LLM을 기반으로 동작하는 AI 에이전트 실행 플랫폼입니다. 사용자가 메시지로 요청을 보내면 시스템이 이를 해석하고 필요한 도구를 실행한 뒤 결과를 정리해 다시 사용자에게 보고합니다. 이 과정은 단순한 대화가 아니라 다음과 같은 작업 실행 루프로 이루어집니다.

요청 이해 → 작업 계획 → 도구 실행 → 결과 정리 → 사용자 보고

이러한 과정을 자동화하고 예약 실행할 수도 있습니다. 즉 OpenClaw는 단순한 챗봇이 아니라 컴퓨터 환경에서 작업을 수행하는 AI 에이전트 런타임이라고 볼 수 있습니다.

2) AI 에이전트

AI 에이전트는 사용자를 대신해 작업을 수행하는 소프트웨어 대리자입니다. 에이전트는 다음과 같은 일을 수행할 수 있습니다.

• 파일 탐색 및 처리
• 쉘 명령 실행
• 외부 서비스 호출
• 데이터 가공 및 분석
• 결과 요약 및 보고

이러한 작업은 LLM을 통해 사용자 요청을 - 맥락에 따라 - 이해하고 실행됩니다.

3) OpenClaw 구성 요소

OpenClaw는 Gateway 중심구조로 동작합니다.

User
 ↓
Channels
 ↓
Gateway
 ├ Agents
 ├ Skills
 └ Hooks
 ↓
LLM Provider
 ↓
Ollama

각 구성 요소의 역할은 다음과 같습니다.

gateway

OpenClaw의 중심 컴포넌트입니다.

• 사용자 메시지 라우팅
• 세션 관리
• 도구 실행
• 에이전트 실행 관리

모든 요청은 Gateway를 통해 처리됩니다

---

LLM provider

LLM 모델과 통신하는 인터페이스입니다.

• 로컬 LLM (Ollama 등)
• 클라우드 LLM (OpenAI 등)

모델은 사용자 요청을 이해하고 실행 결과를 자연어로 정리하는 역할을 합니다.

---

channels

사용자와 에이전트를 연결하는 인터페이스입니다.
예를 들면

• Web UI
• Terminal
• Slack
• Discord
• Telegram

등 다양한 메신저를 연결할 수 있습니다.

---

skills

확장 가능한 기능 모듈입니다.
예를 들면

• 파일 시스템 접근
• 웹 검색
• API 호출
• 데이터 처리

커뮤니티에서 다양한 스킬이 공개되고 있습니다.

---

hooks

이벤트 기반 자동화 스크립트입니다.
예를 들어

• 에이전트 시작 시 실행
• 명령 실행 로그 기록
• 세션 메모리 관리

등의 작업을 자동화할 수 있습니다.

---

agents

에이전트의 성격과 행동 규칙을 정의합니다.
예를 들어

• 어떤 모델을 사용할지
• 어떤 스킬을 사용할 수 있는지
• 어떤 작업을 수행할 수 있는지

등이 정의됩니다.

4) 거버넌스

AI 에이전트는 운영체제 쉘에서 명령을 실행하고 다양한 애플리케이션과 데이터를 접근할 수 있습니다.
따라서 다음과 같은 거버넌스가 중요합니다.

• 개인정보 보호
• 데이터 접근 통제
• 실행 권한 관리
• 로그 및 감사

AI 에이전트를 안전하게 운영하기 위해서는 정책과 통제 구조가 반드시 필요합니다.

---

2. OpenClaw 설치

1) OpenClaw CLI 설치

OpenClaw CLI는 Node.js 기반 도구이기 때문에 npm을 통해 설치합니다.

node 설치

mkdir -p ~/DevTools
cd ~/DevTools
tar zxvf node-v24.14.0-darwin-arm64.tar.gz
mv node-v24.14.0-darwin-arm64 node-v24.14.0
ln -s node-v24.14.0 node

💡M 시리즈 Mac 사용자는 반드시 darwin-arm64 아키텍처 바이너리를 사용해야 합니다.

환경 변수 설정

export NODE_HOME=/Users/본인계정홈/DevTools/node
export PATH=$NODE_HOME/bin:$PATH

설치 확인

node -v

OpenClaw 설치

npm install -g openclaw@latest

설치 확인

openclaw -V

💡opneclaw 쉘을 삭제해야 할 경우 npm rm -g openclaw
💡openclaw의 설정, 데이터를 삭제하려면 rm -rf ~/.openclaw

2) LLM 프레임워크와 모델 설치

로컬 LLM 실행을 위해 Ollama 프레임워크를 사용합니다.

ollama 설치

curl -fsSL <https://ollama.com/install.sh> | sh

설치 확인

ollama -v

모델 설치

ollama pull freehuntx/qwen3-coder:8b

💡ollama 앱의 삭제는 rm -rf /Application/Ollama.app
💡ollama의 설정,  모델 및 데이터를 삭제하려면 rm -rf ~/.ollama

필요 시 Ollama 실행

open /Applications/Ollama.app

💡Ollama 설정에서 "Cloud", "Auto-download updates"를 비활성화하는 것을 권장합니다.

3) 게이트웨이 구성

게이트웨이 구성 및 데몬 설치

openclaw onboard --install-daemon

설정 과정에서 다음 옵션을 선택합니다.

Onboarding mode: QuickStart
Model/Auth Provider: Skip for now
Filter models by provider: ollama
Default model: ollama/freehuntx/qwen3-coder:8b
Channel: Skip for now
Search provider: Skip for now
Configure skills: No
Enable hooks:
 - boot-md
 - bootstrap-extra-files
 - command-logger
 - session-memory

💡게이트웨이가 설치되면 Node.js Foundation이 백그라운드에서 실행됨

Gateway 재시작

openclaw gateway restart

상태 확인

openclaw status

웹 대시보드 실행

openclaw dashboard

4) 오류 해결

다음 오류가 발생할 수 있습니다.

Agent failed before reply: No API key found for provider "ollama"

이 경우 모델 provider를 직접 설정해야 합니다.

# ollama provider 추가
cat ~/.openclaw/openclaw.json | jq '
   .models.providers.ollama = {
      "baseUrl": "<http://127.0.0.1:11434>",
      "api": "ollama",
      "apiKey": "ollama-local",
      "models": [
        {
          "id": "freehuntx/qwen3-coder:8b",
          "name": "freehuntx/qwen3-coder:8b",
          "reasoning": false,
          "input": [
            "text"
          ],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 131072,
          "maxTokens": 8192
        }
      ]
    }
' > /tmp/openclaw_new.json && \
mv /tmp/openclaw_new.json ~/.openclaw/openclaw.json

# 기본 모델 지정
openclaw models set ollama/freehuntx/qwen3-coder:8b

# 모델 설정 확인
openclaw models status

# 게이트웨이 재시작
openclaw gateway restart

💡OpenClaw 에이전트는 긴 시스템 프롬프트와 도구 정의를 사용하기 때문에 64K 이상의 컨텍스트 윈도우 모델을 사용하는 것이 권장됩니다. 위 스크립트에선 128K로 지정했습니다.

---

3. OpenClaw 사용

1) Web UI vs Terminal UI

OpenClaw는 에이전트와 상호작용하기 위한 여러 인터페이스를 제공합니다. 대표적으로 다음 두 가지 방법을 사용할 수 있습니다. 물론 메신저를 이용하는 방법도 있지만 이 글에선 생략합니다.

웹 UI

openclaw dashboard

웹 브라우저에서 에이전트와 대화할 수 있는 인터페이스가 열립니다. 설정 확인이나 로그 확인에도 편리합니다.

터미널 UI

터미널에서 직접 에이전트와 대화할 수도 있습니다.

openclaw chat

개발자 입장에서는 터미널 환경이 더 빠르고 편리한 경우가 많습니다.

2) 간단한 일 시켜보기

예를 들어 에이전트에게 다음과 같은 요청을 할 수 있습니다.

디스크를 얼마나 쓰고 있는지 주요 파티션별로 정리해서 보여줘 

또는

내 사진 폴더의 디스크 사용량을 하위 1단계 폴더 수준에서 정리해서 보여줘 

에이전트는 요청을 해석한 뒤 필요한 쉘 명령을 실행하고 결과를 요약해 사용자에게 전달합니다. 이처럼 OpenClaw는 단순한 대화형 AI가 아니라 로컬 환경에서 작업을 수행하는 자동화 에이전트로 활용할 수 있습니다.

로컬 LLM과 연계한 OpenClaw에게 요청한 디스크 사용량 분석

---

4. 마무리 그리고 다음 작업

OpenClaw는 LLM을 기반으로 동작하는 AI 에이전트 실행 환경입니다.

로컬 LLM과 결합하면 개인 컴퓨터에서도 다음과 같은 자동화를 구현할 수 있습니다.

• 파일 처리 자동화
• 로그 분석
• 시스템 관리 작업
• 개인 생산성 도구

이번 글에서는 OpenClaw 설치와 기본 실행 환경 구성까지 살펴보았습니다.
다음 글에서는 OpenClaw가 내부적으로 어떻게 동작하는지 아키텍처 관점에서 살펴보겠습니다.