macOS dev setup
기준일: 2026-07-26
공식 기준: macOS dev setup
macOS dev setup 문서는 OpenClaw 공식 문서(platforms/mac/dev-setup)를 한국어로 정리한 가이드입니다. Setup guide for developers working on the OpenClaw macOS app 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
Setup guide for developers working on the OpenClaw macOS app
한국어 가이드 범위: platforms/mac/dev-setup 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- macOS developer setup
- 사전 요구사항
- 1. Install dependencies
- 2. Build and package the app
- 3. Install the CLI and Gateway
- 트러블슈팅
- Build fails: toolchain or SDK mismatch
- App crashes on permission grant
- Gateway "Starting..." indefinitely
- If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
- 관련 문서
상세 내용
macOS developer setup
Build and run the OpenClaw macOS application from source.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
사전 요구사항
주요 항목:
- Xcode 26.2+ (Swift 6.2 toolchain), on the latest macOS available in
- Node.js 24.15+ & pnpm for the gateway, CLI, and packaging scripts. Node
1. Install dependencies
pnpm install
2. Build and package the app
Outputs dist/OpenClaw.app. Without an Apple Developer ID certificate, the script falls back to ad-hoc signing.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
./scripts/package-mac-app.sh
3. Install the CLI and Gateway
The packaged app embeds the canonical scripts/install-cli.sh installer. On a fresh profile, choose This Mac during onboarding; the app installs the matching user-space CLI and runtime before starting the Gateway wizard.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
npm install -g openclaw@<version>
트러블슈팅
이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.
Build fails: toolchain or SDK mismatch
The macOS app build expects the latest macOS SDK and the Swift 6.2 toolchain (Xcode 26.2+).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
xcodebuild -version
xcrun swift --version
App crashes on permission grant
If the app crashes when you try to allow Speech Recognition or
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
tccutil reset All ai.openclaw.mac.debug
Gateway "Starting..." indefinitely
Check whether a zombie process holds the port:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
If a manual run holds the port, stop it (Ctrl+C), or kill the PID found above as a last resort.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
관련 문서
주요 항목:
- macOS app
- Install overview
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/platforms/mac/dev-setup - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
pnpm install
./scripts/package-mac-app.sh
npm install -g openclaw@<version>
xcodebuild -version
xcrun swift --version
tccutil reset All ai.openclaw.mac.debug
openclaw gateway status
openclaw gateway stop
# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.