macOS에 OpenClaw 설치하기 완전 가이드

들어가며

macOS는 OpenClaw를 실행하기에 이상적인 플랫폼 중 하나로, 안정적인 Unix 환경과 뛰어난 터미널 경험을 제공합니다. 본 문서에서는 Homebrew와 npm 두 가지 설치 방법을 소개하고, macOS의 launchd를 활용하여 시스템 시작 시 자동 실행을 구현하는 방법을 상세히 설명합니다.

환경 요구 사항

1단계: 사전 의존성 설치

Xcode 명령줄 도구 설치

OpenClaw의 일부 의존성은 설치 시 네이티브 모듈을 컴파일해야 하므로 Xcode 명령줄 도구가 필요합니다.

xcode-select --install

팝업 대화 상자에서 "설치"를 클릭하고 다운로드 및 설치가 완료될 때까지 기다립니다.

설치 확인:

xcode-select -p
# 출력: /Library/Developer/CommandLineTools

Homebrew 설치

아직 Homebrew를 설치하지 않았다면 다음 명령어를 실행합니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Silicon 사용자는 설치 완료 후 Homebrew를 PATH에 추가해야 합니다.

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2단계: Node.js 설치

방법 1: Homebrew를 통한 설치 (권장)

brew install node@22

# node@22를 PATH에 링크
brew link --overwrite node@22

# 버전 확인
node --version
npm --version

방법 2: nvm을 통한 설치

# nvm 설치
brew install nvm

# nvm 환경 설정
mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# Node.js 22 설치
nvm install 22
nvm use 22
nvm alias default 22

3단계: OpenClaw 설치

Homebrew 또는 npm 두 가지 방법으로 설치할 수 있습니다.

방법 1: Homebrew 설치 (권장)

brew install openclaw

Homebrew 방식은 의존성을 자동으로 처리하며 업데이트도 더 편리합니다.

방법 2: npm 전역 설치

npm install -g openclaw@latest

설치 확인

openclaw --version

4단계: 초기 구성

초기화 마법사를 실행합니다.

openclaw onboard

안내에 따라 다음 설정을 완료합니다.

1. AI 모델 제공업체 선택 (Claude / OpenAI / Ollama / Gemini / OpenRouter)
2. 해당 API 키 입력
3. 연동할 메신저 채널 선택
4. 게이트웨이 포트 확인 (기본값 18789)

구성 파일은 다음 위치에 저장됩니다.

~/.config/openclaw/openclaw.json5

VS Code 또는 다른 편집기로 열어 수동 조정할 수 있습니다.

code ~/.config/openclaw/openclaw.json5

5단계: OpenClaw 시작

openclaw up

성공적으로 시작되면 다음과 같이 표시됩니다.

[OpenClaw] Gateway started on port 18789
[OpenClaw] Model provider: Claude (claude-sonnet-4-20250514)
[OpenClaw] Channels: ready
[OpenClaw] Dashboard: http://localhost:18789/dashboard

자주 사용하는 관리 명령어

# 실행 상태 및 환경 점검
openclaw doctor

# 관리 패널 열기
openclaw dashboard

# 실시간 로그 확인
openclaw logs

# 서비스 재시작
openclaw restart

# 설치된 스킬 목록 확인
openclaw skill list

6단계: launchd 자동 시작 설정

macOS는 launchd를 사용하여 백그라운드 서비스를 관리하며, Linux의 systemd에 해당합니다. 아래 단계를 통해 OpenClaw를 launchd 사용자 수준 서비스로 등록합니다.

plist 파일 생성

mkdir -p ~/Library/LaunchAgents

~/Library/LaunchAgents/com.openclaw.agent.plist 파일을 생성하고 내용을 다음과 같이 작성합니다.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/openclaw</string>
        <string>up</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME</string>

    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.openclaw/logs/stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.openclaw/logs/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

YOUR_USERNAME을 실제 사용자 이름으로 교체하십시오. npm으로 설치한 경우 /opt/homebrew/bin/openclaw를 which openclaw의 출력 경로로 교체해야 합니다.

로그 디렉토리 생성 및 서비스 로드

# 로그 디렉토리 생성
mkdir -p ~/.openclaw/logs

# 서비스 로드
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

# 서비스 시작 확인
launchctl list | grep openclaw

launchd 서비스 관리

# 서비스 중지
launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist

# 서비스 시작
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

# 서비스 상태 확인 (macOS 13+)
launchctl print gui/$(id -u)/com.openclaw.agent

macOS 전용 최적화 팁

백그라운드 네트워크 연결 허용

OpenClaw를 처음 시작할 때 macOS에서 방화벽 알림이 표시될 수 있습니다. "허용"을 클릭하면 됩니다.

알림을 놓쳤다면 수동으로 추가할 수 있습니다.

1. "시스템 설정" > "네트워크" > "방화벽"을 엽니다
2. "옵션"을 클릭합니다
3. Node.js 또는 OpenClaw를 찾아 "들어오는 연결 허용"으로 설정합니다

macOS 절전 모드로 인한 서비스 중단 방지

Mac에서 장시간 OpenClaw를 실행하는 경우 시스템 절전을 비활성화하는 것이 좋습니다.

# 시스템 절전 방지 (터미널에서 실행)
caffeinate -s &

# 또는 시스템 설정에서 조정
# 시스템 설정 > 잠금 화면 > 디스플레이 끈 후 잠기지 않음

Apple Silicon 성능 최적화

Apple Silicon Mac에서 로컬 모델(예: Ollama)을 실행하는 경우 Metal 가속을 활용할 수 있습니다.

# Ollama 설치
brew install ollama

# Ollama 시작 (자동으로 Metal GPU 가속 사용)
ollama serve

# openclaw.json5에서 Ollama를 모델 제공업체로 설정

iTerm2를 사용한 모니터링

iTerm2의 분할 화면 기능을 사용하여 OpenClaw 로그와 시스템 리소스를 동시에 모니터링하는 것을 권장합니다.

# 왼쪽 패널: OpenClaw 로그 확인
openclaw logs

# 오른쪽 패널: 시스템 리소스 모니터링
top -pid $(pgrep -f openclaw)

Homebrew 업데이트

Homebrew로 설치한 사용자의 업데이트는 매우 간단합니다.

# Homebrew 인덱스 업데이트
brew update

# OpenClaw 업그레이드
brew upgrade openclaw

# 서비스 재시작
openclaw restart

제거

OpenClaw를 제거해야 하는 경우:

# Homebrew로 설치한 경우
brew uninstall openclaw

# npm으로 설치한 경우
npm uninstall -g openclaw

# 구성 파일 정리 (선택 사항)
rm -rf ~/.config/openclaw
rm -rf ~/.openclaw

# launchd 서비스 제거
launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist
rm ~/Library/LaunchAgents/com.openclaw.agent.plist

마무리

macOS는 안정적인 Unix 기반과 뛰어난 하드웨어 성능을 갖추고 있어 OpenClaw를 실행하기에 탁월한 선택입니다. Homebrew를 통해 설치하면 가장 원활한 경험을 얻을 수 있으며, launchd 자동 시작을 함께 설정하면 AI 어시스턴트가 항상 온라인 상태를 유지합니다. 이어서 채널 연동 및 스킬 플러그인 관련 튜토리얼을 참고하여 OpenClaw의 잠재력을 더욱 발휘해 보십시오.