macOS에서 Gateway 라이프사이클 관리하기

개발을 하다 보면 백그라운드 프로세스가 예기치 않게 종료되어 흐름이 끊기는 경우가 많아요. 매번 수동으로 서비스를 다시 올리거나, 시스템을 재시작할 때마다 프로세스 상태를 일일이 확인하는 일은 꽤나 번거롭죠.

macOS에서 Gateway가 어떻게 구동되는지 이해하면 이런 반복적인 작업에서 벗어나 더 안정적인 개발 환경을 유지할 수 있어요.

필요한 것

• macOS 앱
• openclaw CLI (외부 바이너리)

빠른 시작

macOS 앱은 기본적으로 launchd를 통해 Gateway를 관리해요. 앱이 Gateway를 자식 프로세스(child process)로 직접 실행하지 않고 시스템 서비스로 등록하여 관리하는 방식이에요. 이 방식은 로그인 시 자동 시작과 크래시 발생 시 자동 재시작을 보장해 줍니다.

1. 연결 시도: 앱이 실행되면 먼저 설정된 포트에서 이미 작동 중인 Gateway가 있는지 확인해요.
2. 서비스 활성화: 연결 가능한 Gateway가 없으면 openclaw CLI를 사용해 launchd 서비스를 활성화해요.
3. 레이블 관리: 서비스는 bot.molt.gateway라는 레이블로 등록돼요. (프로필 사용 시 bot.molt.<profile> 형태가 됩니다.)
4. 로그 확인: Gateway 로그는 Debug Settings에 지정된 경로에 기록되어 언제든 확인할 수 있어요.

자주 사용하는 관리 명령어는 다음과 같아요.

# 서비스 강제 재시작
launchctl kickstart -k gui/$UID/bot.molt.gateway

# 서비스 종료
launchctl bootout gui/$UID/bot.molt.gateway

문제 해결

서명되지 않은 개발 빌드 문제 서명 키 없이 로컬 빌드를 위해 scripts/restart-mac.sh --no-sign을 실행하면, launchd가 서명되지 않은 바이너리를 실행하지 않도록 ~/.openclaw/disable-launchagent 파일이 생성돼요. 이 파일이 남아 있으면 서비스가 정상적으로 실행되지 않을 수 있어요.

해결 방법: 수동으로 설정을 초기화하려면 아래 명령어를 입력하세요.

rm ~/.openclaw/disable-launchagent

Attach-only 모드 앱이 launchd를 관리하지 않고 이미 실행 중인 Gateway에 연결만 하도록 설정하고 싶다면, --attach-only 또는 --no-launchd 플래그로 앱을 실행하세요. 이 옵션은 Debug Settings에서도 켜고 끌 수 있어요.

구체적인 설정이나 설치 과정에서 도움이 필요하다면 AI Setup Assistant를 확인해 보세요.

다음 단계

• Remote mode 설정 가이드
• Debug Settings 활용법