macOS에서 LaunchAgent로 OpenClaw 데몬 프로세스 관리하기

macOS의 서비스 관리 방식

macOS 시스템에서 백그라운드 서비스를 관리하는 표준 방법은 launchd와 LaunchAgent를 사용하는 것입니다. Linux의 systemd와 유사하게, launchd는 macOS의 시스템 서비스 관리자이며, LaunchAgent는 현재 사용자 수준의 백그라운드 프로세스를 관리하는 전용 도구입니다. OpenClaw은 AI Agent 게이트웨이로서 WhatsApp, Telegram, Discord 등 채팅 플랫폼의 메시지를 지속적으로 수신해야 하므로, LaunchAgent 데몬 프로세스로 설정하는 것이 macOS에서의 모범 사례입니다.

자동 설치 방법

OpenClaw은 데몬 프로세스를 원클릭으로 설치하는 명령어를 제공합니다. macOS에서는 자동으로 LaunchAgent 설정을 생성합니다:

openclaw onboard --install-daemon

실행 후, OpenClaw이 자동으로 ~/Library/LaunchAgents/ 디렉터리에 plist 설정 파일을 생성합니다. 다음 명령어로 설치가 성공했는지 확인할 수 있습니다:

launchctl list | grep openclaw

출력에 openclaw 관련 항목이 포함되어 있으면 데몬 프로세스가 설정된 것입니다. 자동 설치가 작동하지 않거나 설정을 커스터마이징하고 싶다면, 수동 설정 부분을 계속 읽어주세요.

사전 요구사항

수동 설정을 시작하기 전에 다음 조건이 충족되어야 합니다:

macOS 시스템(Ventura 13 이상 지원)
Node.js 22+ 설치 완료(Bun은 사용하지 마세요. WhatsApp과 Telegram 연결 처리 시 알려진 버그가 있습니다)
npm install -g openclaw@latest로 OpenClaw 설치 완료
openclaw onboard로 초기화 설정 완료

OpenClaw이 정상적으로 실행되는지 확인합니다:

openclaw --version
openclaw doctor

LaunchAgent 설정 파일 생성

LaunchAgent의 설정 파일은 XML 형식의 plist 파일로, ~/Library/LaunchAgents/ 디렉터리에 저장됩니다.

먼저 OpenClaw의 설치 경로를 확인합니다:

which openclaw

일반적인 경로는 /usr/local/bin/openclaw 또는 /opt/homebrew/bin/openclaw입니다. 이 경로를 기록합니다.

plist 파일을 생성합니다:

nano ~/Library/LaunchAgents/com.openclaw.agent.plist

다음 내용을 입력합니다:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.agent</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>start</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
        <key>NetworkState</key>
        <true/>
    </dict>

    <key>ThrottleInterval</key>
    <integer>5</integer>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
        <key>NODE_ENV</key>
        <string>production</string>
    </dict>

    <key>StandardOutPath</key>
    <string>/tmp/openclaw.stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/openclaw.stderr.log</string>

    <key>ProcessType</key>
    <string>Background</string>
</dict>
</plist>

/usr/local/bin/openclaw을 실제 OpenClaw 경로로 교체하세요. Homebrew로 설치한 Node.js를 사용하는 경우 경로가 /opt/homebrew/bin/openclaw일 수 있습니다.

설정 설명

Label: 서비스의 고유 식별자, 역방향 도메인 형식 사용
RunAtLoad: true로 설정하면 사용자 로그인 시 자동 시작
KeepAlive: 자동 재시작 정책 설정. SuccessfulExit가 false이면 비정상 종료 시 자동 재시작, NetworkState가 true이면 네트워크 사용 가능 시에만 실행
ThrottleInterval: 크래시 후 재시작까지의 최소 간격(초), 빈번한 재시작 방지
EnvironmentVariables: PATH에 Node.js와 OpenClaw 경로가 포함되어야 합니다
ProcessType: 백그라운드 프로세스로 표시, macOS가 이에 따라 리소스 스케줄링 최적화

서비스 로드 및 관리

서비스 로드

launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

서비스 시작

launchctl start com.openclaw.agent

서비스 상태 확인

launchctl list | grep openclaw

출력의 첫 번째 열 숫자는 PID(프로세스 ID)로, 0이 아니면 서비스가 실행 중입니다. 두 번째 열은 종료 상태 코드로, 0은 정상을 의미합니다.

서비스 중지

launchctl stop com.openclaw.agent

서비스 언로드

launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist

로그 확인

OpenClaw의 표준 출력과 에러 로그는 설정한 경로에 각각 저장됩니다:

tail -f /tmp/openclaw.stdout.log
tail -f /tmp/openclaw.stderr.log

로그를 더 영구적인 위치에 저장하고 싶다면 plist의 StandardOutPath와 StandardErrorPath를 다음과 같이 수정합니다:

<key>StandardOutPath</key>
<string>/Users/사용자이름/.openclaw/logs/stdout.log</string>
<key>StandardErrorPath</key>
<string>/Users/사용자이름/.openclaw/logs/stderr.log</string>

먼저 로그 디렉터리를 생성해야 합니다:

mkdir -p ~/.openclaw/logs

설정 수정 후 다시 로드

plist 파일이나 OpenClaw 설정 파일 ~/.openclaw/openclaw.json을 수정한 후에는 서비스를 다시 로드해야 합니다:

launchctl unload ~/Library/LaunchAgents/com.openclaw.agent.plist
launchctl load ~/Library/LaunchAgents/com.openclaw.agent.plist

관리 패널 접속

서비스가 실행된 후 브라우저로 OpenClaw 관리 패널에 접속할 수 있습니다:

openclaw dashboard

또는 브라우저에서 직접 http://localhost:3000을 엽니다.

문제 해결

서비스가 시작되지 않는 경우, 다음 단계로 문제를 해결합니다:

plist 문법 확인: plutil -lint ~/Library/LaunchAgents/com.openclaw.agent.plist
시스템 로그 확인: log show --predicate 'senderImagePath CONTAINS "openclaw"' --last 5m
에러 로그 확인: cat /tmp/openclaw.stderr.log
수동 실행 테스트: openclaw start, 오류 여부 관찰
경로 정확성 확인: plist의 ProgramArguments 경로가 실제 openclaw 실행 파일을 가리키는지 확인
진단 실행: openclaw doctor

일반적인 문제로는 PATH 환경 변수에 Node.js 경로가 포함되지 않은 경우, 파일 권한이 올바르지 않은 경우, 포트 3000이 다른 앱에 의해 점유된 경우 등이 있습니다.

정리

LaunchAgent로 OpenClaw 데몬 프로세스를 관리하면, macOS에서 Linux systemd와 동일한 서비스 관리 경험을 구현할 수 있습니다: 부팅 시 자동 시작, 크래시 시 자동 복구, 중앙화된 로그 관리. 이를 통해 OpenClaw AI Agent 게이트웨이가 24시간 안정적으로 운영되어, 채팅 플랫폼의 어떤 메시지도 놓치지 않습니다.