이번 장애는 단일 원인이 아닌, 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 failedTypeError: fetch failedUNABLE_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 환경, 포트 충돌, 권한 문제가 얽힌 전형적인 복합 장애였습니다. 핵심은 문제를 한 번에 해결하려 하지 말고, 레이어별로 분리해서 원인을 제거하는 것입니다.
