OpenClaw 연동 장애 해결기: OAuth/TLS/텔레그램/게이트웨이 한 번에 잡기

이번 장애는 단일 원인이 아닌, TLS 인증서 신뢰 문제 + Gateway 실행 방식 + 포트 충돌 + npm 권한 문제가 동시에 겹친 복합 이슈였습니다.

배경 설명: 왜 브라우저는 되는데 Node만 실패했나?

macOS에서는 브라우저/일부 도구(curl)가 시스템 Keychain의 루트 인증서를 잘 활용하지만, Node 런타임은 환경에 따라 동일하게 동작하지 않을 수 있습니다. 이때 외부 API 호출(fetch)에서 인증서 체인 검증이 실패하면 OAuth, 모델 호출, Telegram API 호출이 한꺼번에 깨질 수 있습니다.

증상 요약

OpenAI OAuth 실패 (fetch failed, UNABLE_TO_GET_ISSUER_CERT_LOCALLY)
웹챗 연결은 되는데 답변 없음
Gateway 포트 충돌/반복 실패
npm EACCES 권한 오류
Telegram 연동 오류 (deleteMyCommands failed)

1) OAuth 실패 (fetch failed)

증상

OpenAI OAuth failed
TypeError: fetch failed
UNABLE_TO_GET_ISSUER_CERT_LOCALLY

원인

Node TLS 인증서 체인 검증 실패.

해결

security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain > ~/macos-system-roots.pem
NODE_EXTRA_CA_CERTS=~/macos-system-roots.pem

2) 채팅 무응답 (연결은 되는데 답 없음)

원인

CLI에서는 NODE_EXTRA_CA_CERTS가 적용됐지만, LaunchAgent로 띄운 Gateway 프로세스에는 환경변수가 자동으로 전달되지 않음.

해결

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

3) Gateway 반복 실패 / 포트 충돌

해결

openclaw gateway stop
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

운영 원칙: 이후 Gateway는 서비스 방식 단일 운영.

4) npm EACCES 오류

해결

sudo chown -R 501:20 ~/.npm

운영 원칙: sudo npm / sudo openclaw 사용 금지.

5) Telegram 연동 실패

동일한 TLS 이슈 (Gateway 환경에 CA 미적용). Gateway에 NODE_EXTRA_CA_CERTS 적용 후 정상화.

최종 안정 상태

Node 22 유지
macOS 루트 CA PEM 생성 완료
LaunchAgent에 NODE_EXTRA_CA_CERTS 영구 반영
npm 캐시 권한 복구
Gateway 서비스 단일 운영
Telegram 연동 정상
재부팅 후 자동 실행 정상 확인

재발 방지 체크리스트

sudo로 node/npm/openclaw 실행하지 않기
수동 Gateway와 서비스 Gateway 동시에 띄우지 않기
launchd에 NODE_EXTRA_CA_CERTS 항상 포함
포트 충돌 시 openclaw gateway stop 먼저 수행

마무리

이번 케이스는 TLS, Node 런타임, launchd 환경, 포트 충돌, 권한 문제가 얽힌 전형적인 복합 장애였습니다. 핵심은 문제를 한 번에 해결하려 하지 말고, 레이어별로 분리해서 원인을 제거하는 것입니다.