메인 콘텐츠로 건너뛰기

​
macOS에서의 Gateway 수명 주기

macOS 앱은 기본적으로 launchd를 통해 Gateway를 관리하며, Gateway를 자식 프로세스로 생성하지 않습니다. 먼저 구성된 포트에서 이미 실행 중인 Gateway에 연결을 시도하고, 도달 가능한 것이 없으면 외부 openclaw CLI를 통해 launchd 서비스를 활성화합니다(임베디드 런타임 없음). 이를 통해 로그인 시 자동 시작과 충돌 시 재시작을 안정적으로 제공합니다. 자식 프로세스 모드(앱이 Gateway를 직접 생성)는 현재 사용되지 않습니다. UI와 더 강하게 결합해야 한다면 터미널에서 Gateway를 수동으로 실행하세요.

​
기본 동작 (launchd)

  • 앱은 사용자별 LaunchAgent ai.openclaw.gateway를 설치합니다 (--profile/OPENCLAW_PROFILE 사용 시 ai.openclaw.<profile>; 레거시 com.openclaw.*도 지원).
  • 로컬 모드가 활성화되면 앱은 LaunchAgent가 로드되어 있는지 확인하고 필요하면 Gateway를 시작합니다.
  • 로그는 launchd gateway 로그 경로에 기록됩니다(Debug Settings에서 확인 가능).
일반적인 명령: 
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway
이름 있는 profile을 실행 중이라면 라벨을 ai.openclaw.<profile>로 바꾸세요.

​
서명되지 않은 개발 빌드

scripts/restart-mac.sh --no-sign은 서명 키가 없을 때 빠른 로컬 빌드를 위한 것입니다. launchd가 서명되지 않은 relay 바이너리를 가리키지 않도록 하기 위해, 이 스크립트는:
  • ~/.openclaw/disable-launchagent를 작성합니다.
서명된 scripts/restart-mac.sh 실행은 이 마커가 있으면 해당 재정의를 제거합니다. 수동으로 재설정하려면: 
rm ~/.openclaw/disable-launchagent

​
attach-only 모드

macOS 앱이 launchd를 절대 설치하거나 관리하지 않게 하려면 --attach-only(또는 --no-launchd)로 실행하세요. 그러면 ~/.openclaw/disable-launchagent가 설정되어, 앱은 이미 실행 중인 Gateway에만 연결합니다. 같은 동작을 Debug Settings에서도 전환할 수 있습니다.

​
원격 모드

원격 모드에서는 로컬 Gateway를 절대 시작하지 않습니다. 앱은 원격 호스트로 SSH 터널을 만들고 그 터널을 통해 연결합니다.

​
launchd를 선호하는 이유

  • 로그인 시 자동 시작
  • 내장된 재시작/KeepAlive 동작
  • 예측 가능한 로그와 감독
진정한 자식 프로세스 모드가 다시 필요해진다면, 별도의 명시적인 개발 전용 모드로 문서화되어야 합니다.