Gateway on macOS
기준일: 2026-07-26
공식 기준: Gateway on macOS
Gateway on macOS 문서는 OpenClaw 공식 문서(platforms/mac/bundled-gateway)를 한국어로 정리한 가이드입니다. Gateway runtime on macOS (external launchd service) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
Gateway runtime on macOS (external launchd service)
한국어 가이드 범위: platforms/mac/bundled-gateway 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- Automatic setup
- Manual recovery
- Launchd (Gateway as LaunchAgent)
- Version compatibility
- State directory on macOS
- Debug app connectivity
- Smoke check
- 관련 문서
상세 내용
본문
OpenClaw.app does not bundle Node or the Gateway runtime. The macOS app expects an external openclaw CLI install, does not spawn the Gateway as a child process, and manages a per-user launchd service to keep the Gateway running (or attaches to an already-running local Gateway).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Automatic setup
On a fresh Mac, choose This Mac during onboarding. The app runs its signed, bundled installer script before the Gateway wizard: it installs a user-space Node runtime and the matching openclaw CLI under ~/.openclaw, then installs and starts the per-user launchd service. This path needs no Terminal, Homebrew, or administrator access.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Manual recovery
Node 24.15+ is recommended for a manual install; Node 22.22.3+ also works. Install openclaw globally:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
npm install -g openclaw@<version>
Launchd (Gateway as LaunchAgent)
Label: ai.openclaw.gateway (default profile), or ai.openclaw. for a named profile.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- "OpenClaw Active" enables/disables the LaunchAgent.
- Quitting the app does not stop the Gateway (launchd keeps it alive).
- If a Gateway is already running on the configured port, the app attaches to
- launchd stdout:
~/Library/Logs/openclaw/gateway.log(profiles use - launchd stderr: suppressed
- If the host loops with repeated
EADDRINUSEor fast restarts, check for
Version compatibility
The macOS app checks the Gateway version against its own version. Onboarding automatically runs managed setup when an existing CLI is missing or incompatible. Use Retry setup to repeat installation, or Check again after repairing an external CLI.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
State directory on macOS
Keep OpenClaw state on a local, non-synced disk. Avoid iCloud Drive and other cloud-synced folders; sync latency and file locks can affect sessions, credentials, and Gateway state.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Debug app connectivity
Use the macOS debug CLI from a source checkout to exercise the same Gateway WebSocket handshake and discovery logic the app uses:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json
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
관련 문서
주요 항목:
- macOS app
- Gateway runbook
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/platforms/mac/bundled-gateway - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
npm install -g openclaw@<version>
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json
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
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.