macOS에서 OpenClaw 게이트웨이 설정 및 실행 가이드

로컬 개발 환경을 설정하다 보면 백그라운드 프로세스가 갑자기 종료되거나, 런타임 버전이 꼬여서 고생하는 경우가 종종 있죠. OpenClaw는 이런 번거로움을 줄이기 위해 macOS의 시스템 서비스 관리자인 launchd를 활용해 Gateway를 더 안정적으로 운영할 수 있도록 구조를 변경했어요.

이제 OpenClaw.app은 Node.js나 Bun, Gateway 런타임을 내장하지 않아요. 대신 시스템에 설치된 외부 openclaw CLI를 사용하며, Gateway를 자식 프로세스로 실행하는 대신 launchd 서비스를 통해 관리해요. 이미 실행 중인 로컬 Gateway가 있다면 그곳에 바로 연결되기도 하고요.

CLI 설치 (로컬 모드 필수)

macOS에서는 Node 24가 기본 런타임이에요. 호환성을 위해 Node 22 LTS(현재 22.14+) 버전도 계속 사용할 수 있어요. 아래 명령어를 사용해 openclaw를 전역으로 설치해 주세요.

npm install -g openclaw@<version>

macOS 앱 내에 있는 Install CLI 버튼을 눌러도 npm이나 pnpm을 통해 동일한 설치 과정을 진행해요. (Gateway 런타임으로 bun을 사용하는 것은 권장하지 않아요.)

Launchd (LaunchAgent로서의 Gateway)

Label:

• ai.openclaw.gateway (또는 ai.openclaw.<profile>, 이전 버전의 com.openclaw.* 형식이 남아있을 수 있어요.)

Plist 위치 (사용자별):

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist (또는 ~/Library/LaunchAgents/ai.openclaw.<profile>.plist)

관리 방식:

• 로컬 모드에서 macOS 앱이 LaunchAgent의 설치와 업데이트를 직접 관리해요.
• CLI에서도 openclaw gateway install 명령어로 설치할 수 있어요.

동작 방식:

• “OpenClaw Active” 설정으로 LaunchAgent를 켜고 끌 수 있어요.
• 앱을 종료해도 Gateway는 멈추지 않아요. launchd가 프로세스를 계속 살려두거든요.
• 설정된 포트에서 이미 Gateway가 실행 중이라면, 앱은 새 프로세스를 시작하는 대신 기존 Gateway에 연결해요.

로그 확인:

• launchd 표준 출력 및 에러 로그: /tmp/openclaw/openclaw-gateway.log

버전 호환성

macOS 앱은 실행 시 Gateway 버전과 앱 버전을 대조해요. 만약 두 버전이 서로 호환되지 않는다면, 앱 버전에 맞춰서 전역 CLI를 업데이트해야 정상적으로 작동해요.

정상 작동 확인 (Smoke check)

설치가 잘 되었는지 확인하려면 아래 명령어들을 실행해 보세요.

openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback

그 다음, 아래 명령어로 헬스 체크를 진행할 수 있어요.

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 언제든 물어보세요.

다음 단계

• CLI 명령어 가이드
• 문제 해결 방법