완벽하게 통제되는 나만의 로컬 LLM 게이트웨이(Openclaw) 구축

Ⅰ. OpenClaw 기술이란?

ⅰ. 로컬 LLM 관리 및 게이트웨이 솔루션

1. OpenClaw는 개발자가 로컬 환경에서 대규모 언어 모델(LLM)을 쉽게 관리하고 연동할 수 있도록 돕는 게이트웨이 및 TUI(터미널 사용자 인터페이스) 기반의 도구입니다.
2. 특히, Ollama와 같은 로컬 LLM 구동기와의 연동에 최적화되어 있어 API 비용이나 데이터 유출 걱정 없이 안전하게 AI 모델을 활용할 수 있는 환경을 제공합니다.

Ⅱ. OpenClaw 기술 특징

ⅰ. 비용 및 보안 이점 (Local Only)

1. 클라우드 API를 거치지 않고 내 PC의 자원(WSL2 내 Ollama)만 활용하므로, 민감한 데이터가 외부로 유출되지 않습니다.
2. API 사용에 따른 과금 요소가 전혀 없습니다.

ⅱ. 안정적인 백그라운드 구동 (Daemon)

1. Linux의 서비스 관리자인 systemd를 활용하여 OpenClaw Gateway를 유저 서비스(user service) 형태로 안정적으로 구동합니다.
2. 시스템 재부팅 시에도 유연하게 대처하고 서비스 상태를 쉽게 모니터링할 수 있습니다.

ⅲ. 직관적인 TUI (터미널 UI) 제공

1. 복잡한 설정 파일 수정 없이 터미널 내에서 방향키와 엔터만으로 셋업이 가능한 온보딩 화면을 제공합니다.

Ⅲ. OpenClaw 기술 동작방식

ⅰ. 모델과 게이트웨이의 분리

1. Ollama (Model Provider): 실제 AI 모델(예: qwen2.5:7b, llama3.1:8b)을 메모리에 적재하고 추론(Inference)을 담당합니다. (기본 포트: 11434)
2. OpenClaw (Gateway): 사용자의 요청을 받아 Ollama로 전달하고, 응답을 관리하며, 시스템 환경을 통제하는 중계자 역할을 수행합니다.

ⅱ. 통신 흐름

1. 사용자가 OpenClaw CLI나 애플리케이션을 통해 프롬프트를 전송합니다.
2. OpenClaw Gateway가 이 요청을 [http://127.0.0.1:11434](http://127.0.0.1:11434)에 위치한 Ollama 서버로 라우팅합니다.
3. Ollama가 모델을 통해 생성한 결과를 다시 Gateway를 거쳐 사용자에게 반환합니다.

Ⅳ. OpenClaw 기술 구성 및 흐름도

 ⅰ. 전체 아키텍처

+-------------------------------------------------------------------------+
|                          Windows 11 (Host OS)                           |
|                                                                         |
|  +-------------------------------------------------------------------+  |
|  |                        WSL2 (Ubuntu 24.04)                        |  |
|  |                                                                   |  |
|  |   [ Local LLM Layer ]             [ OpenClaw Management Layer ]   |  |
|  |                                                                   |  |
|  |   +-------------------+           +---------------------------+   |  |
|  |   |      Ollama       | <-------  |     OpenClaw Gateway      |   |  |
|  |   | (Port: 11434)     |  (REST)   |  (systemd user service)   |   |  |
|  |   +-------------------+           +---------------------------+   |  |
|  |             |                                   ^                 |  |
|  |             v                                   |                 |  |
|  |   +-------------------+           +---------------------------+   |  |
|  |   |   AI Models       |           |     OpenClaw CLI (TUI)    |   |  |
|  |   | - qwen2.5:7b      |           | - Configuration / Setup   |   |  |
|  |   | - llama3.1:8b     |           | - Status Monitoring       |   |  |
|  |   +-------------------+           +---------------------------+   |  |
|  +-------------------------------------------------------------------+  |
+-------------------------------------------------------------------------+

Ⅴ. OpenClaw 기술 설치 방법

설치 전, 자신이 열어둔 터미널이 PowerShell인지 WSL(Ubuntu)인지 프롬프트를 보고 반드시 구분하시길 바랍니다.

 

ⅰ. 설치 전 준비물 확인

1. 운영체제: Windows 10/11, macOS 12 이상, Ubuntu 20.04 이상
2. Node.js: 버전 18 이상 (22.x 또는 24.x LTS 권장)
3. 시스템 RAM: 8GB 이상 필수 (원활한 모델 구동을 위해 16GB 이상 권장)
4. 선택 사항: 외부 클라우드 병행 시 사용할 AI API 키

ⅱ. 1단계: WSL 및 Systemd 준비

1. PowerShell을 관리자 권한으로 실행 후 Ubuntu를 설치합니다.

   wsl --install -d Ubuntu-26.04

    

2. WSL 내부에서 systemd를 활성화합니다.

   sudo tee /etc/wsl.conf >/dev/null <<'EOF'
   [boot]
   systemd=true
   EOF
   

3. PowerShell에서 WSL을 재시작하고 systemd 동작을 확인합니다.

   wsl --shutdown
   wsl
   ps -p 1 -o comm=  # 결과가 'systemd'로 나와야 함
   

ⅲ. 2단계: 기본 패키지 및 Ollama 설치

1. WSL 내부에서 필수 패키지를 설치합니다.

   sudo apt update
   sudo apt install -y curl git build-essential ca-certificates zstd lsof
   

 

패키지	용도
curl	설치 스크립트 다운로드
git	소스 설치 또는 GitHub 접근
build-essential	일부 Node 패키지 빌드
ca-certificates	HTTPS 인증서 검증
zstd	Ollama 설치 파일 압축 해제
lsof	포트 점유 프로세스 확인

   2. Ollama를 설치하고 모델을 다운로드합니다.

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:7b  # 테스트용 권장 모델

 

ⅳ. 3단계: Node.js 및 OpenClaw 설치

1. Node.js 24 버전을 설치합니다.

   curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
   sudo apt install -y nodejs
   

2. npm을 활용해 OpenClaw를 전역(Global)으로 설치합니다.

   sudo npm install -g openclaw@latest
   

Ⅵ. OpenClaw 기술 사용 방법

ⅰ. 온보딩(초기 설정) 진행

1. 터미널(WSL)에서 아래 명령어를 입력하여 TUI 온보딩 화면을 엽니다.

   openclaw onboard --install-daemon
   

2. 다음과 같이 권장값을 선택하며 진행합니다.
   • Model/auth provider: Ollama 선택
   • Ollama mode: Local only 선택
   • Ollama base URL: http://127.0.0.1:11434 입력
   • Install gateway as daemon?: Yes 선택
   • Gateway access: Localhost only 선택

ⅱ. 서비스 상태 확인 및 점검

1. 설치가 완료되면 게이트웨이가 정상 구동 중인지 진단합니다.

   openclaw doctor
   openclaw gateway status
   

2. 백그라운드 데몬 로그를 확인하고 싶다면 아래 명령어를 사용합니다.

   journalctl --user -u openclaw-gateway -f
   

Ⅶ. OpenClaw 기술 자주 쓰는 명령어

ⅰ. 상태 확인 및 관리

1. openclaw --version : 현재 설치된 OpenClaw 버전 확인
2. openclaw doctor : OpenClaw 시스템 진단 및 오류 체크
3. openclaw gateway status : 게이트웨이 실행 상태 확인
4. openclaw onboard --install-daemon : 설정 초기화 및 데몬 재설치

ⅱ. Ollama 관련 명령어

1. curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags) : Ollama 서버 구동 및 응답 확인
2. ollama list : 현재 다운로드된 로컬 모델 목록 확인
3. ollama pull [모델명] : 새로운 모델 다운로드 (예: llama3.1:8b)

Ⅷ. OpenClaw 기술 활용방안

ⅰ. 안전한 코딩 어시스턴트 구축

1. 사내 보안 규정상 클라우드 기반 AI(ChatGPT, Claude 등)에 소스코드를 복사하기 어려운 환경에서 유용합니다.
2. qwen2.5-coder:7b 와 같은 코딩 특화 모델을 로컬에 받아 OpenClaw와 연동하면 완벽하게 폐쇄된 오프라인 코딩 보조 환경을 구축할 수 있습니다.

ⅱ. 저사양 PC에서의 모델 최적화 운영

1. VRAM이나 RAM이 부족한 PC 환경(예: 32GB RAM, 8G VRAM)에서도 무거운 70B 모델 대신 7B~8B 수준의 경량 모델을 OpenClaw로 관리하여 응답 속도와 리소스를 최적화할 수 있습니다.

Ⅸ. OpenClaw 기술 트러블 슈팅

ⅰ. Ollama Address already in use 오류

1. 증상: Error: listen tcp 127.0.0.1:11434: bind: address already in use
2. 원인: 백그라운드에서 이미 Ollama가 11434 포트를 점유하고 실행 중인 상태(정상 상태)입니다.
3. 해결: 오류가 아니므로 무시하고 curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags) 로 정상 응답이 오는지 확인한 뒤, 바로 모델 다운로드를 진행하면 됩니다.

ⅱ. PowerShell 명령어 인식 오류

1. 증상: Get-Process : 매개 변수 이름 'p'이(가) 모호하므로... 혹은 systemd : 'systemd' 용어가 cmdlet...
2. 원인: Linux 전용 명령어(ps -p 1 -o comm=)를 Windows PowerShell에서 실행했기 때문입니다.
3. 해결: 터미널에 wsl을 입력하여 Ubuntu 내부 환경으로 진입한 뒤 명령어를 다시 실행하십시오.

ⅲ. Ollama 설치 중 zstd 오류

1. 증상: ERROR: This version requires zstd for extraction.
2. 해결: 압축 해제용 라이브러리가 누락된 것입니다. WSL 안에서 sudo apt install -y zstd 를 실행한 후 설치 스크립트를 재실행하세요.