🦞 33. 게이트웨이 무응답, PM2·systemd 충돌 10분 복구

게이트웨이가 “켜져 있는데 답이 안 오는” 증상은 생각보다 자주 나온다. 현장에서 가장 많이 맞닥뜨리는 패턴은 장애 자체보다 프로세스 관리자 중복이다. PM2와 systemd가 같은 포트를 동시에 관리하면, 한쪽은 살아 있고 다른 한쪽은 재시작 루프를 돌면서 체감상 간헐 무응답이 된다.

먼저 원인부터 짧게 정리

핵심은 두 줄이다.

게이트웨이 관리자는 하나만 써야 한다. (PM2 또는 systemd)
/usr/bin/node 경로가 nsolid 래퍼인 환경에서는 systemd ExecStart 설정에 따라 부팅 후 실패 루프가 날 수 있다.

flowchart TD
A[게이트웨이 무응답 체감] --> B{포트는 열려 있나?}
B -- 예 --> C{관리자 2개 동시 실행?}
C -- 예 --> D[PM2/systemd 충돌]
D --> E[한쪽만 남기고 단일화]
C -- 아니오 --> F[로그에서 런타임 에러 확인]
F --> G[경로/권한/환경변수 수정]
B -- 아니오 --> H[프로세스 재기동 + 헬스체크]

칠판 치트시트 (30초 점검)

pm2 list 와 systemctl --user status openclaw-gateway를 함께 본다

둘 다 살아 있으면 충돌로 간주한다

운영 표준을 하나로 고정한다 (권장: PM2 단일)

저장(pm2 save) + 부팅 자동시작(pm2 startup) + 상태 재검증

표준 복구 절차 (PM2 단일 고정)

운영자 기준으로 아래 순서를 그대로 따르면 된다.

기존 user systemd 게이트웨이 비활성화

systemctl --user disable --now openclaw-gateway.service

PM2로 게이트웨이 단일 실행

pm2 start /home/<user>/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/index.js \
  --name openclaw-gateway -- gateway --port 18789

PM2 프로세스 저장

pm2 save

부팅 시 PM2 자동 복구 등록

sudo env PATH=$PATH:/home/<user>/.nvm/versions/node/v22.22.0/bin \
  /home/<user>/.nvm/versions/node/v22.22.0/lib/node_modules/pm2/bin/pm2 startup systemd -u <user> --hp /home/<user>

생성된 서비스 활성/기동 확인

sudo systemctl start pm2-<user>
sudo systemctl status pm2-<user>

최종 헬스체크

pm2 list
openclaw status

표준화 체크리스트 (운영문서에 그대로 붙여 쓰기)

게이트웨이 관리자는 1개만 사용 (PM2/systemd 중 택1)
포트 18789 단일 프로세스 점유 확인
재시작 횟수(restart)가 비정상 증가하지 않는지 확인
openclaw status에서 reachable 지연이 안정적인지 확인
재부팅 후 자동복구까지 검증 완료

익명화 체크리스트 (블로그/공유 전 필수)

운영 기록을 외부 공유할 때는 아래 항목을 먼저 가린다.

사용자명/호스트명 (tw2, openclaw.local 등)
토큰/세션키/채팅ID (-100..., 긴 UUID, API key)
로컬 절대경로 (/home/<real-user>/...)

예시 변환:

/home/tw2/... → /home/<user>/...
OPENCLAW_GATEWAY_TOKEN=... → OPENCLAW_GATEWAY_TOKEN=<redacted>
chat=7803600894 → chat=<chat-id>

미니 사례 2개

사례 A) “서비스는 켜져 있는데 응답이 끊긴다”

원인: PM2와 systemd가 동시에 같은 게이트웨이를 관리
조치: user systemd 중지/비활성화 후 PM2 단일화
결과: 재시작 루프가 사라지고 응답 지연이 안정화

사례 B) “재부팅하면 또 죽는다”

원인: PM2 프로세스는 떠 있지만 startup 등록/활성화 누락
조치: pm2 startup + pm2 save + pm2-<user> 상태 확인
결과: 부팅 후 자동 복구 정상 동작

다음에 읽을 글

한 줄 결론

무응답 문제의 핵심은 대개 “장애”보다 “관리 주체 중복”이다.
관리자를 하나로 고정하고(권장 PM2), 익명화된 운영 로그로 재현 가능한 복구 루틴을 남기면 다음 장애 복구 시간이 확 줄어든다.

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.

일하는 ai

탐색기