방구석 IT

Mac mini OpenClaw 구축기 (OpenAI Auth + Gemma 4) 본문

Tech 학습 및 정리/AI

Mac mini OpenClaw 구축기 (OpenAI Auth + Gemma 4)

펭잉 2026. 6. 15. 14:45

📌 실제 구축 기록을 기준으로 챕터 흐름, 명령어, 검증 기준, 문제 해결 절차를 정리한 정리본입니다. 이 글은 2026년 4월 26일 무렵 설치한 기록을 기준으로 하며, 설치 버전이나 실행 시점에 따라 설치 및 온보딩 과정은 일부 상이할 수 있습니다.

OpenClaw 소개 이미지

Mac mini OpenClaw 구축 가이드

대상 구성: Mac mini에서 OpenClaw Gateway를 상시 실행하고, Telegram Bot으로 대화하며, 기본 모델은 Codex 또는 Gemma 4/Ollama 조합으로 운용하는 구성입니다.

0. 전체 구성 요약

  • Mac mini: OpenClaw Gateway와 Ollama가 실행되는 상시 구동 장비
  • Telegram Bot: 외부에서 OpenClaw와 대화하는 기본 채널
  • OpenAI Codex: 초기 구축 및 고난도 코딩/추론용 모델
  • Ollama + Gemma 4 e4b: 로컬 기본 응답 모델 후보
  • Gateway Port: 기본 18789, 로컬 바인딩 127.0.0.1 권장

✅ 처음 구축할 때는 Codex + Telegram + Local Gateway를 먼저 안정화하고, 이후 Ollama/Gemma 4를 추가하는 순서가 가장 안전합니다.

1. 사전 준비

1.1 준비 항목

  • Mac mini: macOS, zsh 환경
  • Telegram 계정 및 BotFather 접근 권한
  • OpenAI/Codex 로그인 준비
  • Homebrew 설치 상태 확인
  • 관리자 권한: brew 설치, LaunchAgent 등록, macOS 권한 승인에 필요

1.2 계정 구성: 관리 사용자 + OpenClaw 표준 사용자

이 구축은 Mac mini에 별도의 표준 사용자 계정을 만들고, OpenClaw는 그 표준 사용자 계정에서 상시 실행하는 구성을 기준으로 합니다. 운영 계정과 관리자 계정을 분리하면 평소 자동화/대화 환경의 권한 범위를 줄일 수 있습니다.

  • 관리 사용자 계정: Homebrew 패키지 설치, cask 설치, 시스템 설정 변경, 권한 승인, 문제 해결 작업을 수행합니다.
  • OpenClaw 표준 사용자 계정: OpenClaw Gateway, workspace, Telegram Pairing, 일반 대화/자동화 실행을 담당합니다.
  • brew install, brew tap, brew install --cask 같은 설치 작업은 기본적으로 관리 사용자 계정에서 진행합니다.
  • 설치 후 OpenClaw 표준 사용자 계정에서 실제 명령이 보이는지 확인합니다. PATH가 다르면 /opt/homebrew/bin 경로를 zsh 설정에 반영해야 합니다.
  • Apple Notes, Reminders, Messages, 화면 제어 같은 macOS 권한은 실제로 OpenClaw를 실행하는 표준 사용자 계정에서 허용되어야 합니다.

🔐 정리하면: “설치/관리 작업은 관리자 계정”, “상시 실행과 Telegram 대화는 OpenClaw 표준 사용자 계정”으로 나누는 방식입니다.

# 관리 사용자 계정에서 설치
brew tap steipete/tap
brew tap antoniorodr/memo
brew install jq

# OpenClaw 표준 사용자 계정에서 확인
which brew
brew --version
openclaw gateway status

1.3 Telegram Bot Token 준비

Telegram에서 @BotFather를 열고 새 Bot을 만들거나 기존 Bot의 토큰을 확인합니다.

@BotFather
→ /newbot
→ Bot 이름 입력
→ Bot username 입력
→ API Token 복사

기존 Bot을 사용할 경우:

@BotFather
→ /mybots
→ 대상 Bot 선택
→ API Token 확인

🔐 Bot Token은 비밀번호와 같습니다. 문서에 그대로 노출하지 말고, OpenClaw 설정 단계에서만 입력하세요.

2. Mac mini 이름 정리

Bonjour/mDNS, 로컬 네트워크 탐색, 로그 확인을 쉽게 하려면 Mac 이름은 영문 소문자와 하이픈 중심으로 단순하게 맞춥니다.

sudo scutil --set ComputerName "openclaw-macmini"
sudo scutil --set LocalHostName "openclaw-macmini"
sudo scutil --set HostName "openclaw-macmini"

확인:

scutil --get ComputerName
scutil --get LocalHostName
scutil --get HostName

예상 결과:

openclaw-macmini
openclaw-macmini
openclaw-macmini

ℹ️ Telegram 중심으로만 사용할 경우 Bonjour는 필수는 아닙니다. 다만 Mac 이름을 깔끔하게 맞춰두면 추후 로컬 노드/장치 연결 문제를 줄일 수 있습니다.

3. OpenClaw 설치 및 온보딩

3.1 공식 설치 스크립트 실행

curl -fsSL https://openclaw.ai/install.sh | bash
공식 설치 스크립트 실행 화면
공식 설치 스크립트 실행 화면

3.2 온보딩 기본 선택값

초기 구축은 QuickStart로 진행하고, 세부 설정은 나중에 openclaw configure로 조정하는 흐름이 단순합니다.

Continue? → Yes
Setup mode → QuickStart
OpenAI Codex auth method → OpenAI Codex Browser Login
Channel → Telegram
Telegram Bot Token → BotFather에서 발급받은 토큰 입력
Web Search → 필요 시 설정, 아니면 Skip
Skills/Hooks → 기본값 또는 Skip 후 나중에 추가
Daemon → LaunchAgent 설치
QuickStart 및 초기 설치 선택 화면
QuickStart 및 초기 설치 선택 화면
Codex 브라우저 로그인 단계
Codex 브라우저 로그인 단계
모델 선택 단계
모델 선택 단계
채널 선택 - Telegram 권장
채널 선택 - Telegram 권장
Telegram Bot Token 입력 안내
Telegram Bot Token 입력 안내
Telegram Bot Token 준비/입력 화면 1
Telegram Bot Token 준비/입력 화면 1
Telegram Bot Token 준비/입력 화면 2
Telegram Bot Token 준비/입력 화면 2
토큰 입력 후 진행 화면
토큰 입력 후 진행 화면
Web Search 설정 단계
Web Search 설정 단계
기본 Skill 선택 단계
기본 Skill 선택 단계
추천 Skill 목록 참고
추천 Skill 목록 참고
API Key 입력 단계
API Key 입력 단계
Hook 설정 단계
Hook 설정 단계
추천 Hook 목록 참고
추천 Hook 목록 참고
Gateway 실행 단계
Gateway 실행 단계
TUI 테스트 및 온보딩 종료 화면
TUI 테스트 및 온보딩 종료 화면

3.3 추천 Skill 설치

개인 비서 용도라면 아래 Skill을 우선 고려합니다. 단, brew tap/install/cask 설치는 관리 사용자 계정에서 진행하고, 설치 후 OpenClaw 표준 사용자 계정에서 명령이 실행되는지 확인합니다. 메시지 발송이나 개인정보 접근이 있는 Skill은 권한과 확인 절차를 신중하게 둡니다.

⚠️ 아래 brew 명령들은 “관리 사용자 계정”에서 실행하는 것을 전제로 합니다. 이후 표준 사용자 계정에서 which memo/remindctl/imsg/peekaboo/goplaces/gogcli 등으로 접근 가능 여부를 확인하세요.

  • apple-notes: Apple Notes 생성/조회/편집/검색/내보내기
  • apple-reminders: Apple Reminders 기반 할 일 관리
  • imsg: iMessage/SMS 조회 및 발송. 발송 전 확인 필수
  • peekaboo: macOS 화면 캡처 및 UI 자동화
  • clawhub: Skill 검색/설치/업데이트
  • gog/goplaces/weather 등: Google Workspace, 장소 검색, 날씨 확인
brew tap steipete/tap
brew tap antoniorodr/memo

brew install antoniorodr/memo/memo
brew install steipete/tap/remindctl
brew install steipete/tap/imsg
brew install steipete/tap/peekaboo
brew install steipete/tap/goplaces
brew install steipete/tap/gogcli
brew install jq

brew install --cask steipete/tap/codexbar

3.4 추천 Hook

  • session-memory: /new 또는 /reset 시 세션 내용을 memory 폴더에 저장
  • command-logger: 명령 이벤트를 로그로 남김
  • boot-md: Gateway 시작 시 BOOT.md 실행
  • bootstrap-extra-files: 추가 bootstrap 파일을 에이전트 컨텍스트에 주입

🧭 초기에는 Hook을 최소화하고 Gateway가 안정적으로 동작하는지 먼저 확인한 뒤 하나씩 추가하는 편이 문제 원인 추적에 좋습니다.

4. Gateway 상태 확인

온보딩이 끝나면 Gateway가 정상적으로 실행 중인지 확인합니다.

openclaw gateway status

정상 판단 기준:

Runtime: running
Connectivity probe: ok
Listening: 127.0.0.1:18789
Gateway 상태 확인 화면
Gateway 상태 확인 화면

추가 진단 명령어:

lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw status
openclaw gateway status
tail -n 120 ~/.openclaw/logs/gateway.err.log
tail -n 120 ~/.openclaw/logs/gateway.log

5. Bonjour 문제 대응

Telegram 중심 운용에서는 Bonjour가 없어도 대화가 가능합니다. Bonjour 관련 로그가 반복되거나 Gateway 상태가 불안정하면 비활성화 후 재시작합니다.

openclaw plugins disable bonjour
openclaw gateway restart
openclaw gateway status

반복될 수 있는 로그 예시:

CIAO ANNOUNCEMENT CANCELLED
bonjour: restarting advertiser
Bonjour 관련 오류/진단 화면
Bonjour 관련 오류/진단 화면
Bonjour 비활성화 명령 실행 화면
Bonjour 비활성화 명령 실행 화면
Gateway 재시작 후 상태 확인 화면
Gateway 재시작 후 상태 확인 화면

6. Telegram Pairing 승인

Telegram Bot에게 먼저 메시지를 보내면 OpenClaw가 Pairing code를 생성합니다. Mac mini 터미널에서 해당 코드를 승인합니다.

openclaw pairing approve telegram <PAIRING_CODE>

예시:

openclaw pairing approve telegram <PAIRING_CODE>

정상 결과:

Approved telegram sender <TELEGRAM_USER_ID>.
Telegram Pairing 정보 확인 화면
Telegram Pairing 정보 확인 화면

7. 최종 확인

  • Gateway 상태: Runtime running, Connectivity probe ok
  • Dashboard: http://127.0.0.1:18789/ 접속 가능
  • Telegram Bot에게 테스트 메시지 전송 후 OpenClaw 응답 확인
  • 설치 버전 확인: openclaw --version
openclaw --version
openclaw gateway status
Dashboard에서 Gateway 상태를 확인한 화면
Dashboard에서 Gateway 상태를 확인한 화면

8. 운영 명령어 요약

openclaw gateway status
openclaw gateway restart
openclaw gateway start
openclaw gateway stop
openclaw status
openclaw logs --follow
openclaw security audit
lsof -nP -iTCP:18789 -sTCP:LISTEN
launchctl print "gui/$(id -u)/ai.openclaw.gateway"

처음부터 다시 볼 때 필요한 핵심 명령어

sudo scutil --set ComputerName "openclaw-macmini"
sudo scutil --set LocalHostName "openclaw-macmini"
sudo scutil --set HostName "openclaw-macmini"

curl -fsSL https://openclaw.ai/install.sh | bash
exec zsh
openclaw --version
openclaw gateway status

openclaw plugins disable bonjour
openclaw gateway restart
openclaw pairing approve telegram <PAIRING_CODE>

✅ 여기까지 완료되면 “Telegram으로 OpenClaw와 대화 가능한 Mac mini 상시 구동 환경”이 완성됩니다.

Gemma 4 e4b + Ollama 연결

🧪 이 챕터는 보류/추가 구축 영역입니다. 먼저 Codex + Telegram Gateway를 안정화한 뒤, 로컬 비용 절감과 상시 응답을 위해 Ollama/Gemma 4를 붙이는 순서가 좋습니다.

9. 로컬 모델 구성 개요

Telegram / iMessage / Slack 등
        ↓
OpenClaw Gateway
        ↓
기본 응답: Ollama + Gemma 4 로컬
        ↓
고난도/코딩/정확도 필요 시: Codex 또는 GPT 계열로 전환
  • OpenClaw는 Ollama provider를 지원합니다.
  • Ollama는 OpenAI 호환 /v1 URL이 아니라 네이티브 API 주소인 http://127.0.0.1:11434 를 쓰는 구성이 안전합니다.
  • M4 Mac mini 24GB 기준 기본 후보는 gemma4:e4b입니다.

10. 모델 선택 기준

  • gemma4:e4b: 기본 개인 비서, 일정/메모/생활 자동화용으로 가장 현실적
  • gemma4:e2b: 더 가볍고 빠르지만 품질은 낮음
  • gemma4:26b: 로컬 추론 품질은 높일 수 있으나 메모리 압박 큼
  • gemma4:31b: 24GB Mac mini 상시 운용에는 비추천

11. Ollama 설치

brew install --cask ollama
open -a Ollama

정상 동작 확인:

ollama --version
curl http://localhost:11434/api/tags
Ollama 설치 및 실행 확인 화면
Ollama 설치 및 실행 확인 화면

12. Gemma 4 모델 설치 및 테스트

먼저 E4B 모델을 받고, 필요하면 더 가벼운 E2B도 함께 받아둡니다.

ollama pull gemma4:e4b
ollama pull gemma4:e2b
gemma4:e4b 다운로드 진행 화면
gemma4:e4b 다운로드 진행 화면
모델 다운로드 완료/목록 확인 화면
모델 다운로드 완료/목록 확인 화면

간단 테스트:

ollama run gemma4:e4b "너는 내 맥미니에서 실행되는 개인 AI 비서야. 한 문장으로 자기소개해줘."
Gemma 4 간단 응답 테스트 화면
Gemma 4 간단 응답 테스트 화면

로드 상태와 GPU 사용 여부 확인:

ollama ps

🖥️ PROCESSOR 항목에서 GPU 비율이 높게 잡히는지 확인합니다. CPU로만 동작하면 속도와 발열/부하가 달라질 수 있습니다.

ollama ps로 로드 상태 확인
ollama ps로 로드 상태 확인
컨텍스트/GPU 오프로딩 확인 화면
컨텍스트/GPU 오프로딩 확인 화면
추가 성능 확인 화면
추가 성능 확인 화면

13. Ollama 컨텍스트와 Keep Alive 조정

모델을 오래 살려두고 컨텍스트 길이를 늘리면 응답 준비 시간이 줄고 긴 문맥 처리에 유리합니다. 다만 메모리 압박이 생기면 값을 낮춥니다.

Ollama 앱을 종료한 뒤 환경값을 설정하는 방식:

ollama stop gemma4:e4b
osascript -e 'quit app "Ollama"'
pkill -x Ollama 2>/dev/null

launchctl setenv OLLAMA_KEEP_ALIVE "24h"
launchctl setenv OLLAMA_CONTEXT_LENGTH "16384"

open -a Ollama

되돌리기:

launchctl unsetenv OLLAMA_KEEP_ALIVE
launchctl unsetenv OLLAMA_CONTEXT_LENGTH

모델을 24시간 유지하도록 한 번 호출:

curl http://127.0.0.1:11434/api/chat -d '{
  "model": "gemma4:e4b",
  "messages": [],
  "keep_alive": "24h"
}'
Ollama 종료 및 환경값 설정 화면
Ollama 종료 및 환경값 설정 화면
Ollama 설정 화면에서 context 조정
Ollama 설정 화면에서 context 조정
메모리 여유 확인 화면
메모리 여유 확인 화면

메모리와 속도 확인:

ollama ps
memory_pressure
time ollama run gemma4:e4b --think=false "내일 해야 할 일을 5개 항목으로 정리해줘."
Gemma 4 속도 테스트 화면
Gemma 4 속도 테스트 화면

14. OpenClaw에 Ollama 연결

openclaw configure --section model

선택값:

Provider: Ollama
Base URL: http://127.0.0.1:11434
Mode: Local
Model: gemma4:e4b
OpenClaw 모델 설정 - provider 선택
OpenClaw 모델 설정 - provider 선택
Ollama Base URL 입력
Ollama Base URL 입력
gemma4:e4b 모델 선택/확인
gemma4:e4b 모델 선택/확인

검증:

openclaw config validate
openclaw models list

15. 기본 모델 전환

openclaw models list
openclaw models set ollama/gemma4:e4b
openclaw models list

Telegram/OpenClaw 채널에서도 확인할 수 있습니다.

/model status
/model list

16. 수동 설정이 필요한 경우

온보딩이 꼬이거나 Ollama provider가 제대로 잡히지 않으면 더미 API Key를 넣고 다시 모델 목록을 확인합니다.

openclaw config set models.providers.ollama.apiKey "ollama-local"
ollama list
openclaw models list
openclaw models set ollama/gemma4:e4b

⚠️ 주의: Base URL에 /v1을 붙이지 않습니다. OpenClaw의 Ollama 연동은 http://127.0.0.1:11434 형태의 네이티브 Ollama API 주소를 기준으로 둡니다.

17. 권장 컨텍스트 길이

  • gemma4:e2b: 32768 ~ 64000
  • gemma4:e4b: 32768 우선, 안정적이면 64000
  • gemma4:26b: 8192 ~ 32768
  • gemma4:31b: 8192 ~ 16384

💡 24GB Mac mini에서는 gemma4:e4b + 32768부터 시작하고, memory_pressure가 안정적일 때 64000으로 올리는 방식을 권장합니다.

18. 상시 실행 설정

Ollama와 OpenClaw Gateway가 동시에 살아 있어야 Telegram 등 외부 채널에서 계속 호출할 수 있습니다.

  • 시스템 설정 → 일반 → 로그인 항목 → Ollama 추가
  • Ollama 앱 메뉴에서 Launch at Login 활성화
  • OpenClaw Gateway는 LaunchAgent로 설치되어 있는지 확인
openclaw gateway status
ollama ps

마무리 체크리스트

  • Mac 이름이 영문 단순 이름으로 정리되어 있다.
  • OpenClaw Gateway가 Runtime running 상태다.
  • Telegram Pairing 승인이 완료되어 Bot 대화가 된다.
  • Bonjour 문제가 있으면 비활성화 후 Gateway를 재시작했다.
  • Ollama/Gemma 4는 Gateway 안정화 이후 추가했다.
  • 기본 모델 전환 후 /model status 또는 openclaw models list로 확인했다.