【해결 기록】OpenClaw 업그레이드 후 HTTP 500:404 NOT_FOUND 오류? 문제 해결 경험 공유

OpenClaw 업그레이드 후 HTTP 500:404 NOT_FOUND 오류가 발생했나요? 제 해결 경험을 공유합니다.

안녕하세요, 로컬 AI 도구를 자주 실험하는 개발자입니다. 최근 OpenClaw를 구버전에서 최신 버전으로 업그레이드했습니다. 사실 그렇게 오래된 버전이 아니었습니다. 2026.3.2에서 2026.3.8로 업그레이드했을 뿐인데, 재시작 후 대화를 시작하자마자 Web UI에 빨간색 오류 메시지가 떴습니다:

HTTP 500:404 NOT_FOUND

정말 머리가 아프더군요. 업그레이드 전에는 모든 게 정상이었고, 업그레이드 로그에도 오류가 없었는데, 갑자기 Gateway에 연결할 수 없고, agent에서 메시지를 보내면 멈춰버렸습니다.

가장 먼저 공식적으로 추천하는 만능 해결책을 시도했습니다: openclaw doctor.

openclaw doctor --fix

두 번 실행해도 출력은 계속 “Everything looks good!”이었고, 경고조차 없었습니다. “이제 완전히 망했구나”라고 생각했는데, GitHub issue, Discord 그룹, 문서를 모두 찾아보니 비슷한 404 버그는 몇 개 있었지만, 대부분 모델 fallback이나 OpenAI Responses API 문제였고, 제 경우처럼 “업그레이드 후 전체 시스템이 멈춘” 문제와는 달랐습니다.

거의 한 시간 동안 삽질하다가, 그냥 삭제 후 재설치할까 하다가(이미 설정해둔 channels와 skills가 아까워서 포기), 마지막으로 가장 강력한 방법을 시도해 보기로 했습니다 - 바로 openclaw onboard로 설정을 재설정 (기존 설정 파일과 skills 폴더는 꼭 백업하세요. 수동으로 잘하시는 분들은 비교하며 수동 교체할 수도 있습니다)

구체적인 절차는 두 단계입니다:

1. 먼저 현재 Gateway를 중지합니다 (안전하게):

   openclaw gateway stop
   # 또는 systemctl stop openclaw-gateway (어떤 데몬으로 설치했는지에 따라)

2. 재설정 위저드를 실행합니다:

   openclaw onboard --reset

   (참고: --reset을 추가하면 기존 config+credentials+sessions가 모두 삭제됩니다. 문서에 따르면 기본 동작이 이렇습니다. 저는 전체 재설정 --reset-scope full을 사용했는데, 어차피 기존 데이터는 모두 백업해뒀습니다.)

위저드에서 “Quick Start”를 계속 선택하며 API 토큰, channels 등을 다시 설정합니다… 설정 항목이 늘어났고, 최신 ChatGPT 5.4 모델도 호환됩니다. 전체 과정이 3분도 안 걸렸습니다. (10번 이상 설치한 경험으로 뽐내자면)

마지막으로 Web UI를 선택하면 페이지가 자동으로 열리고, hello라고 인사하면 정상적으로 대화할 수 있습니다! 그 지독한 500:404가 완전히 사라졌습니다.

왜 doctor는 문제를 해결 못 했는데, onboard는 바로 해결했을까요?

이것은 전형적인 “업그레이드 후 남은 설정 문제”입니다. OpenClaw의 업데이트 속도가 빠릅니다 (이전 이름은 Clawdbot/Moltbot). 3월 초에만 4번 버전이 업데이트되었고, 버전이 바뀔 때마다 config 스키마가 변경될 수 있습니다. 그런데 문서에서 “업그레이드 후 반드시 onboard 재설정을 실행하라”고 강조하지 않아서, 제가 이 문제에 빠졌습니다. 나중에 분들에게 작은 팁이 되길 바랍니다.

이번 삽질 때문에 시간이 좀 낭비됐지만, OpenClaw의 설정 메커니즘을 더 깊이 이해하게 되었습니다. 로컬 AI 도구가 아무리 좋아도, 업그레이드는 조심해야 한다는 교훈을 얻었습니다.

이 글이 500:404로 고생 중인 분들께 도움이 되기를 바랍니다! 다음에 뵙겠습니다~ 🦞