어떤 일이 있었나
최근 프로젝트의 대대적인 리브랜딩과 네이밍 마이그레이션을 진행했습니다. moltbot으로 시작해 clawdbot을 거쳐, 최종적으로 openclaw라는 이름으로 정착했죠. 수백 개의 파일 이름을 바꾸고 수천 개의 문자열을 교체하는 거대한 작업이었습니다.
마이그레이션 직후, 자동화된 테스트에서는 모든 것이 정상으로 보였습니다. 하지만 새로운 사용자들이 게이트웨이 인증에 실패한다는 보고를 하기 시작했습니다. 에러 메시지는 좌절스러울 정도로 모호했습니다: Authentication failed: Missing required credentials.
인증 로직을 몇 시간 동안 뒤졌지만, 코드는 완벽했습니다. 문제는 훨씬 더 단순하고 당혹스러운 곳에 있었습니다.
근본 원인
근본 원인은 환경 변수 템플릿 파일의 이름 불일치였습니다. clawdbot에서 openclaw로 넘어가는 과정에서 핵심 설정 로직은 업데이트했지만, 예시 환경 변수 파일을 놓친 것이었습니다.
docker/.env.example: 여전히CLAWDBOT_GATEWAY_TOKEN=your-token사용config/openclaw.json:OPENCLAW_GATEWAY_TOKEN을 기대하도록 업데이트됨
사용자들은 당연히 .env.example을 .env로 복사하고 자신의 토큰을 입력한 뒤 서비스를 시작했습니다. 하지만 애플리케이션은 OPENCLAW_로 시작하는 변수를 찾고 있었고, 환경에는 CLAWDBOT_로 시작하는 변수만 있었기 때문에 토큰은 결코 로드되지 않았습니다.
전형적인 “라스트 마일(last mile)” 실패였습니다. 엔진은 리팩토링했지만, 연료를 넣는 방법(설명서)을 업데이트하는 것을 잊은 셈입니다.
해결 방법
해결 방법은 아주 간단했습니다.
# docker/.env.example
# 수정 전
CLAWDBOT_GATEWAY_TOKEN=your-secure-token-here
# 수정 후
OPENCLAW_GATEWAY_TOKEN=your-secure-token-here
하지만 진짜 해결책은 단순히 문자열을 바꾸는 것이 아니라, 이러한 마이그레이션을 처리하는 방식을 개선하는 것이었습니다.
배운 점
- 네이밍 마이그레이션은 철저해야 합니다. 소스 코드만 검색하고 바꾸는 것으로는 부족합니다. 문서, 예시 파일, CI/CD 파이프라인, 심지어 철저함을 기하고 싶다면 커밋 메시지까지 확인해야 합니다.
- 예시 파일은 일급 시민입니다. 우리는 흔히
.env.example이나config.sample.json을 부차적인 결과물로 취급하지만, 사용자에게는 이것이 가장 먼저 접하는 진입점입니다. 이것이 잘못되면 사용자의 첫 경험은 실패로 시작됩니다. - 빠르고 명확하게 실패하세요. 애플리케이션은 시작 시 필수 환경 변수의 존재 여부를 확인하고, 명확한 메시지와 함께 종료되었어야 합니다:
Error: OPENCLAW_GATEWAY_TOKEN이 설정되지 않았습니다. .env 파일을 업데이트하셨나요? - 체크리스트를 자동화하세요. 전체 저장소에서 이전 프로젝트 이름을 검색하는 간단한 스크립트만 있었어도 몇 초 만에 발견했을 문제입니다.
예방 조치
동일한 실수를 반복하지 않기 위해 몇 가지 새로운 안전장치를 도입했습니다.
- 시작 시 유효성 검사: 이제 애플리케이션은 시작할 때 스키마 검증을 수행합니다. 필수 환경 변수가 누락된 경우, 도움이 되는 에러 메시지와 함께 즉시 종료됩니다.
- Pre-commit Hook: 코드베이스에
CLAWDBOT이나MOLTBOT이 남아 있는지 확인하는 커스텀 훅을 추가했습니다. - 통합 테스트: CI 단계에
.env.example에 제공된 값들만 사용하여 애플리케이션을 시작해보는 테스트를 추가했습니다.
이름을 짓는 것도 어렵지만, 마이그레이션 과정에서 그 이름을 일관되게 유지하는 것은 더 어렵습니다. 템플릿 파일의 단순한 불일치가 사용자가 떠나가는 이유가 되지 않도록 주의해야 합니다.