OpenClaw 데몬과 launchd

2026 OpenClaw 데몬·백그라운드:
launchd, 로그, 복구

상시 OpenClaw를 위해 launchd, 5단계 복구, 설치·오류·일일 대여 링크를 정리했습니다.

01. 세 가지 문제

OpenClaw를 오래 띄워 두면 노트북 절전, SSH 끊김, 로그 소실이라는 세 벽에 부딪히기 쉽습니다. 이 글은 기본 설치를 마친 뒤 launchd 수준의 재현성—예측 가능한 재시작, 통합 로그, 절차화된 복구—을 원하는 운영자를 위한 것입니다.

1) 세션 종속: 터미널이나 SSH 포그라운드 실행은 행업 시 종료됩니다. 절전이나 셸 종료와 함께 서비스가 멈추므로 launchd 없이는 상시 구동이 어렵습니다.

2) 오래된 plist 경로: Node나 CLI 위치가 바뀐 뒤에도 LaunchAgents가 옛 바이너리를 가리키면, 작업은 올라와 있는 듯하지만 불투명한 종료 코드로 즉시 종료합니다.

3) 로그 분산: 표준 출력만 보면 TCC 거부나 커널 메시지가 빠지고, log show에 잡히는 정보가 없으면 원인 추적이 추측에 의존합니다.

전역 CLI만 올리고 에이전트를 다시 읽지 않으면 “새 CLI·옛 데몬” 불일치가 납니다. OS 업데이트나 수동 brew upgrade node 이후에도 plist를 차이 저장소에 남기세요.

02. openclaw onboard --install-daemon

온보딩은 마법이 아니라 발판입니다. 어떤 파일을 건드리는지 알아 두면 OS 업데이트나 수동 업그레이드 뒤의 드리프트 진단이 빨라집니다.

보통 사용자 LaunchAgents plist를 쓰고, 환경과 작업 경로를 맞춘 뒤 로그인 후 자동 시작을 등록합니다. 에이전트를 올릴 macOS 사용자와 설치 사용자를 같게 하세요. sudo와 GUI 로그인 사용자를 섞으면 흔한 실패 패턴입니다. 기초는 설치 가이드에서 다룹니다.

일일 대여 Mac은 반납 시 데이터 유실을 전제로 워크스페이스 키와 plist 사본을 백업하세요. 세부는 함정 정리를 참고합니다. SSH 셸과 GUI 로그인의 PATH가 다르면 EnvironmentVariables를 넣거나 ProgramArguments를 절대 경로로 고정하세요.

개발과 운영에서 Label이나 포트가 겹치면 플래핑이 납니다. 환경마다 라벨과 소켓을 이름 공간으로 나누세요. 접근성·연락처 등 프라이버시 확인은 한 번 그래픽 세션이 필요할 수 있어, 대여 맥에서는 짧은 VNC로 허용한 뒤 SSH 유지보수로 돌아오는 편이 현실적입니다.

03. 포그라운드와 launchd

축 포그라운드 사용자 LaunchAgent
용도디버깅·첫 실행장시간·무인
수명터미널·SSH에 종속launchd 관리, KeepAlive 선택
분석터미널 출력launchctl·콘솔·log show·plist

종료 코드는 명령 오류 FAQ와 대조하세요. KeepAlive를 과하게 켜면 재시작 폭풍이 납니다. 먼저 포그라운드에서 설정을 고친 뒤 데몬으로 돌아가는 것이 안전합니다.

04. 5단계 복구

장애 때는 단계를 건너뛰지 말고 순서대로 진행하세요. 곧바로 재설치하면 같은 오타 plist를 다시 만들어 근본 원인이 가려집니다.

  1. launchctl list | grep -i openclaw로 PID와 LastExitStatus를 기록합니다. 작업 자체가 없으면 올바른 GUI 사용자(gui/$(id -u))에 로드했는지, 실수로 root 시스템 도메인만 보고 있지 않은지 확인합니다.
  2. log show로 node·openclaw에 대한 술어로 최근 1시간을 뽑아 티켓에 첨부합니다. 필터가 너무 좁으면 놓치므로 필요하면 com.apple.xpc.launchd가 라벨을 언급하는 줄까지 넓힙니다.
  3. ~/Library/LaunchAgents/*.plist에서 ProgramArguments·WorkingDirectory·쓰기 가능 경로를 검증합니다. 셸이 펼치는 ~와 launchd의 처리가 어긋날 수 있으므로 명시 설정을 확인합니다.
  4. launchctl bootout으로 내린 뒤 plist를 고치고, macOS 버전에 맞게 bootstrap 또는 예전 방식의 load로 되돌립니다. 구형에서는 unload/load였습니다. 운영 문서에 버전별 명령을 박아 두면 심야 실수가 줄어듭니다.
  5. OpenClaw를 롤백하거나 openclaw onboard --install-daemon을 다시 실행하고 중복 plist를 제거합니다. 롤백 후에는 설치 직후와 동일한 스모크(채널·웹훅 응답)를 반드시 반복합니다.
ls ~/Library/LaunchAgents/ | grep -i openclaw
launchctl list | grep -i openclaw

원인 분리는 앱보다 시스템·인프라를 먼저: 디스크 여유·시간 동기·DNS/TLS입니다. 이를 건너뛰면 앱 설정만 헛돕니다. 공유 빌드 Mac에서는 plist 변경을 버전 관리하면 재현성이 좋아집니다.

05. 지표와 저사양 Mac

  • 1: 실패 후 15분 이내에 통합 로그를 저장(회전 전).
  • 2: RAM이 계속 80%를 넘기면 Node 계열 데몬의 OOM 위험이 커집니다(8GB 구성 주의).
  • 3: 짧은 주기로 규칙적으로 죽으면 설정 문제, 간격이 불규칙하면 자원·디스크 가득·네트워크 끊김을 의심합니다.

Xcode나 시뮬레이터가 CPU를 빼앗으면 이벤트 루프가 굶습니다. 부하를 나누거나 머신을 분리하세요. 메모리와 안정 호스트는 요금과 원격 접속 가이드를 참고합니다. 컨테이너 운영 패턴은 프로덕션 배포에 있으나, 네이티브 macOS의 중심은 여전히 launchd입니다.

06. tmux와 전용 Mac

주간 헬스 점검으로 launchctl list 상태·남은 디스크·API 지연을 표로 남기면 추이가 보입니다. tmux/screen/nohup은 절전과 전원 관리 통합이 약하고 plist 기반 건강 검사와도 잘 맞지 않습니다. launchd는 재부팅 이후 복귀와 전원 이벤트 처리에 강합니다.

설치 검증을 마친 뒤 이 체크리스트를 적용하고, 이상 시 명령 오류 FAQ와 대조하세요. 저비용 시험은 일일 대여와 로컬 비용 비교를 보고, 플랜은 요금에서 확인합니다.

07. OpenClaw 데몬에 중요한 plist 키

Label과 ProgramArguments 말고도 신뢰성을 바꾸는 키가 있습니다. WorkingDirectory는 launchd가 기동하기 전에 실제로 존재해야 하며, 온보딩 때 만든 심볼릭 링크가 나중에 깨지면 즉시 종료합니다. RunAtLoad는 plist 로드 직후 시작 여부를 정하는데, 노트북에서 “수동 시작” 가정과 충돌할 수 있습니다.

ThrottleInterval은 충돌 루프의 CPU 포화를 줄이지만, 근본 수정 없이 오류를 가리지 않도록 포그라운드에서 설정을 먼저 고치세요. EnvironmentVariables에는 대화형 셸이 쓰던 PATH, NODE_OPTIONS, API 엔드포인트 덮어쓰기를 그대로 넣습니다. 이후 업그레이드에서 변수가 사라지지 않도록 키 단위로 내부 위키에 남기세요.

여러 환경에서는 Label을 적극적으로 이름 공간화합니다. 중복 라벨은 두 번째 plist를 조용히 실패시키거나 먼저 올라온 작업과 싸웁니다. com.example.openclaw.prod와 .staging처럼 나누고, 최신 macOS에서는 launchctl print gui/$(id -u)로 실효 구성을 확인하는 편이 확실합니다.

08. 로깅: 통합 로그·파일·회전

데몬화 뒤에는 터미널 출력만으로는 부족합니다. 사건 중에는 log stream이나 log show 술어를 중심으로 두고, 필요하면 plist에 StandardOutPath와 StandardErrorPath를 추가해 텍스트 로그를 남깁니다. 디스크 팽창을 감시하고, 외부 공유 전 권한과 마스킹을 확인하세요. 토큰이 stderr에 새어 나올 수 있습니다.

launchd 타임스탬프와 애플리케이션 로그를 맞추고, PID 재사용으로 타임라인이 어지러우면 log show --style syslog 헤더의 부트 세션 UUID를 적어 둡니다. 일일 대여 인스턴스는 해제 전에 로그를 내려받으세요. 일회성 디스크는 다음 임차인에게 남지 않을 수 있습니다.

09. 절전·전원·헤드리스 클라우드 Mac

노트북은 잠들고, 많은 클라우드 Mac은 워크스테이션 설정 그대로입니다. Power Nap이나 수면에 들어가면 백그라운드 네트워킹이 예측하기 어렵게 멈춥니다. 상시 에이전트는 정책이 허용하면 AC 전원에서 pmset으로 절전을 줄이거나, 설정을 고칠 때까지 caffeinate를 제한적으로 씁니다. 누가 전력 프로파일을 되돌릴 수 있는지 문서화하지 않으면 선의의 기본값 복원이 야간 작업만 조용히 죽입니다.

데이터센터 Mac mini에서는 Node CPU를 오래 쓸 때 열과 팬 동작을 확인하세요. 스로틀링은 프로세스가 죽지 않아도 아웃바운드 웹훅 지연으로 보일 수 있습니다.

10. 권한·TCC·GUI 전용 프롬프트

화면 기록·접근성·캘린더 등에 닿는 기능은 투명성·동의·통제(TCC) 승인이 필요할 수 있고, 순수 SSH 데몬은 입력 대기로 멈출 수 있습니다. 최초 동의는 한 번 VNC 같은 그래픽 세션에서 끝내고, 부여된 권한 체크리스트와 보안팀 허가가 있다면 정책 스냅샷을 남깁니다. 사용자를 다시 만들거나 plist를 옮긴 뒤에는 선택적 프롬프트를 다시 봐야 할 수 있습니다.

Apple Silicon에서 Rosetta를 가로지르는 구성이라면 plist가 의도한 아키텍처 바이너리를 가리키는지 확인하세요. 로그인 셸은 nvm 훅을 읽고 데몬은 읽지 않아 “셸에서는 되는데 launchd만 실패”가 자주 납니다.

11. 업그레이드와 롤백 주기

OpenClaw 업데이트는 다른 운영 의존성과 같이 버전 고정·릴리스 노트 검토·비운영 Mac 스테이징을 지킵니다. 올린 뒤 launchctl bootout과 재로드로 새 바이너리 경로를 반드시 읽히게 합니다. 직전 node_modules 트리나 잠금 파일 tarball을 보관해 빠른 롤백 통로를 만드세요.

절차를 리허설할 격리 하드웨어가 필요하면 단기 일일 대여 Mac으로 plist 편집·권한 프롬프트·launchd 리로드 주기를 저렴하게 연습할 수 있습니다. 합성 부하를 일주일 무사히 돌린 뒤 같은 plist 템플릿을 공유 인프라로 승격하세요. 단계를 밟을수록 호출기 소음이 줄고 업무 흐름 응답이 유지됩니다.

12. 모니터링 훅과 합성 점검

운영 데몬에는 API와 비슷한 가시성을 붙입니다. 매분 호출 가능한 가벼운 헬스 명령(예: openclaw status나 HTTP 프로브)을 두고, 연속 세 번 실패에서만 경보를 내어 플래핑을 줄입니다. 종료 코드로 잡히지 않는 시그니처는 통합 로그 기반 경보를 병행합니다.

밤에 실제 채널(채팅·메일·파일)을 두드리는 합성 대화나 도구 호출을 예약하고 소요 시간과 성공을 기록합니다. 메모리 누수나 디스크립터 한계 직전에는 지연 악화가 하드 장애에 앞섭니다. 대시보드는 빌드 팜 모니터링과 같은 입구에 두어 담당자가 이중 로그인하지 않게 합니다.

심각도를 문서화합니다. 노랑은 에이전트 재시작, 빨강은 대기 Mac 페일오버나 릴리스 롤백 등 구체 명령(launchctl kickstart, plist 재로드, 패키지 다운그레이드)까지 연결합니다. 분기마다 스테이징에서 plist를 의도적으로 깨뜨리는 게임 데이로 절차 구멍을 드러내세요. 자산 목록에 OpenClaw를 올린 시리얼·대여 ID·plist 버전·OS 업그레이드 승인자를 기록해 설정 드리프트를 일찍 잡습니다.

13. 상시 에이전트 보안 자세

항상 켜진 데몬은 로드한 계정의 권한을 그대로 물려받습니다. 그 계정을 서비스 신원처럼 다루고 디스크에서는 최소 권한, 불필요한 관리자 권한은 피하며, 비밀은 plist 평문이나 Git이 아니라 키체인이나 금고에 둡니다. API 키는 CI 토큰과 같은 주기로 돌리고, 전체 재부팅 없이 돌릴 담당을 정합니다.

아웃바운드는 명시적으로 화이트리스트하고 정책이 허용하면 호스트 방화벽이나 프록시로 제한합니다. 연결 실패를 애플리케이션 오류와 구분해 로그에 남기면 권한 문제와 일시 DNS 실패를 가르기 쉽습니다. 원격 Mac 무리에서는 VPN이나 제로 트러스트를 자동화가 건드리는 리전과 맞춰 지리 차단의 뜻밖의 타격을 피합니다.

버전을 바꿀 때마다 plist와 환경 스냅샷을 백업합니다. ~/Library/LaunchAgents, 관련 셸 프로필, 마스킹한 launchctl print 출력을 tarball로 묶으면 감사와 미래의 재현성이 좋아집니다. 변경 이력에 날짜·담당·사유·롤백 명령을 짧게 남겨 깊은 밤 긴급 디버깅을 줄입니다.

도구 실행이 가능한 어시스턴트는 파일 시스템 범위를 좁히고 전 세계 쓰기 가능 경로를 피하며, 사용자가 갱신할 수 있는 바이너리에는 무결성 점검을 검토합니다. 대여 Mac을 실험에 공유하면 테넌트마다 사용자를 나눠 다른 팀 토큰이 LaunchAgents에 남지 않게 합니다. 침해가 의심될 때의 킬 스위치(언로드·자격 증명 폐기·이해관계자 통지)를 스테이징에서 연습해 본전에서 처음 명령을 짜지 않도록 하세요.

큰 macOS 업그레이드마다 권한 대화·하드닝된 런타임·게이트키퍼 변화를 다시 확인하고, plist 문자열이 같아도 동작이 바뀔 수 있음을 릴리스 체크에 넣습니다. 보안과 신뢰성은 같은 기반, 즉 정상과 이상 모두에서 예측 가능한 launchd 동작에 서 있습니다.