설치가 잘 끝난 줄 알았는데 어느 순간 게이트웨이가 켜지지 않거나 알 수 없는 에러가 뜨면 당황스럽습니다. 특히 환경마다 경로, 권한, 포트 상황이 달라서 같은 명령도 다르게 실패하곤 합니다.
이번 4편에서는 핵심 키워드인 openclaw 오류 해결에 집중합니다. `openclaw doctor`를 중심으로 설치·실행 문제를 진단하고 자동 복구하는 방법, 자주 만나는 오류별 실전 해결법과 예방 팁을 정리합니다.
지난 편(이전: openclaw onboard — 온보딩 실행과 첫 AI 대화 연결하기)에서는 온보딩 마법사로 AI 모델 연결과 최초 대화 설정을 다뤘습니다.
openclaw doctor란 무엇인가요? — 설치·실행 진단 도구
간단히 말해 `openclaw doctor`는 OpenClaw 시스템의 상태를 자동으로 점검해주는 진단 유틸리티입니다. 설정 파일 검증, 필수 의존성 검사, 포트 사용 여부, 프로세스 상태 등 게이트웨이 운영에 필요한 기본 항목을 스캔합니다.
문제가 발생했을 때 가장 먼저 실행해 볼 만한 명령어이며, `--fix` 옵션을 사용하면 흔한 설정 오류를 자동으로 정리해 줍니다.
기본 실행 예시
간단한 진단은 아래 명령으로 시작합니다. 출력된 WARN/FAIL 메시지를 바탕으로 다음 조치를 선택하면 됩니다.
# 내 OpenClaw 시스템 상태 기본 진단하기
openclaw doctor
대표적인 설치/실행 오류와 해결 방법
초보자가 자주 마주치는 오류와 실전에서 바로 쓸 수 있는 명령어들을 정리합니다. 아래 3가지는 가장 빈번한 사례입니다.
① "openclaw: command not found" — PATH 문제
설치 스크립트가 완료됐더라도 쉘의 `PATH`에 글로벌 npm bin 경로가 포함되지 않으면 명령을 찾지 못합니다. 임시로 경로를 추가하여 동작을 확인한 뒤, 셸 설정 파일에 영구 등록하세요.
# 임시로 글로벌 npm bin 경로 추가(테스트용)
export PATH="$(npm prefix -g)/bin:$PATH"
# 영구 적용 예시 (zsh 사용 시)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
② EADDRINUSE :::18789 — 포트 충돌
게이트웨이가 사용하는 포트가 이미 점유되어 있으면 바인드에 실패합니다. 우회 포트를 사용하거나 이미 실행 중인 프로세스를 종료하세요.
# 다른 포트로 우회 실행
openclaw gateway run --port 19000
# 또는 기존 OpenClaw 프로세스 종료 후 재시작
pkill -f openclaw
openclaw gateway
장기적으로는 시스템 서비스로 등록하거나 프로세스 감시 도구(systemd, pm2 등)를 사용해 충돌 발생 시 자동 재시작하도록 구성하세요.
③ 설정 파일 오류(Unknown Config Key 등)
OpenClaw는 설정 검증이 엄격합니다. 과거 버전의 키가 남아 있거나 오타가 있으면 게이트웨이 시작을 거부합니다. `--fix` 옵션으로 자동 정리하거나, 필요 시 수동으로 백업 후 재생성하세요.
# 잘못된 설정 키를 자동으로 정리
openclaw doctor --fix
# 설정 초기화(필요 시)
rm ~/.openclaw/openclaw.json
openclaw init
단계별 진단 가이드 — 5분 내로 문제 원인 파악하기
아래 순서대로 따라 하시면 대부분의 문제를 빠르게 좁힐 수 있습니다.
- 1) 기본 진단 실행터미널에서 `openclaw doctor`를 실행하고 출력 내용을 확인합니다. WARN/FAIL 레벨을 우선 분류하세요.
- 2) 자동 복구 시도간단한 설정 정리는 `--fix`로 해결 가능한 경우가 많습니다. 자동 복구가 실패하면 로그를 캡처합니다.
- 3) 상세 로그 모드로 재현`openclaw gateway --verbose`로 실행해 스킬 로드, 모델 인증, 네트워크 연결 단계의 상세 로그를 확인합니다.
- 4) 환경 점검포트 사용 여부, 프로세스 상태, 권한 문제, 외부 모델 서버(예: Ollama) 연결 상태를 점검하세요.
- 5) 커뮤니티에 문의직접 해결이 어려우면 `openclaw doctor` 출력과 함께 GitHub Issues/Discord에 로그를 붙여 문의하세요.
추가 검토 사항 — 권한·환경·버전 호환성
특정 오류는 권한 문제(파일 접근 권한), Node/npm 버전 불일치, 또는 OS별 특성(Wsl2, macOS SIP 등) 때문에 발생합니다. 문제 재현 시 환경(OS, Node 버전, OpenClaw 버전)을 명확히 하는 것이 중요합니다.
예시: 설정 파일의 문제를 유발하는 잘못된 키
아래 예시는 과거 버전에서 사용하던 키가 남아 있을 때 발생할 수 있는 문제 형태입니다.
# 설정 파일 예시 (문제가 될 수 있는 키 예시)
# 주의: 실제 구성은 openclaw init/onboard로 생성된 파일을 기준으로 합니다.
{
"gateway": {
"port": 18789,
"token": "YOUR_TOKEN"
},
"deprecatedKey": "value" # <-- Unknown Config Key 오류를 유발할 수 있음
}
실전 팁과 주의사항
- 설치 직후에는 `openclaw doctor`를 먼저 실행해 기본 상태를 점검하세요.
- 글로벌 npm 경로는 셸 설정 파일에 영구 등록해 CLI 인식 문제를 방지하세요.
- 포트 충돌이 잦다면 고정 포트 대신 환경변수나 설정 파일로 포트 관리를 표준화하세요.
- 중요 설정은 버전별 변경 내역을 확인하고, 업그레이드 전 백업을 생활화하세요.
자주 묻는 질문 (FAQ)
- openclaw doctor를 실행했더니 노란색 경고 메시지가 너무 많이 나와요. 어떻게 하죠?
- 노란색 경고는 선택적 컴포넌트 미설치 알림일 가능성이 큽니다. 붉은 FAIL이 없으면 우선 운영을 이어가고 필요한 툴만 설치하세요.
- `openclaw doctor --fix`를 쳤는데도 설정 파일이 이상해서 아예 초기화하고 싶어요.
- 설정 파일을 백업한 뒤 삭제(`rm ~/.openclaw/openclaw.json`)하고 `openclaw init` 또는 `openclaw onboard`를 실행하면 초기화됩니다.
- 로컬 모델(Ollama) 연동 시 발생하는 에러도 doctor가 잡아주나요?
- OpenClaw 설정 문제는 잡을 수 있지만 외부 모델 프로세스까지 복구하진 않습니다. `--verbose`로 로그를 확인해 네트워크·인증 문제를 먼저 파악하세요.
- 그래도 문제가 해결되지 않으면 어디에 물어봐야 하나요?
- 공식 GitHub Issues나 Discord에 `openclaw doctor` 출력과 로그를 함께 올리면 커뮤니티에서 도움을 받을 수 있습니다.
이 글이 도움이 됐다면 댓글로 여러분의 에러 로그나 해결 경험을 알려주세요! 🙌
이번 편에서 막히는 부분이 있으면 댓글에 남겨주세요 — 직접 답변드립니다.
핵심 키워드: openclaw 오류 해결 · openclaw doctor · 자동 복구
'OpenClaw' 카테고리의 다른 글
| [openclaw 완전 가이드] 3편 openclaw onboard — 온보딩 실행과 첫 AI 대화 연결하기 (0) | 2026.03.27 |
|---|---|
| [OpenClaw 완전 가이드 2편] 설치 방법 — macOS·Windows·WSL2 환경별 완벽 정리 (0) | 2026.03.26 |
| [openclaw 완전 가이드 1편] openclaw란 무엇인가? 셀프호스팅 AI 에이전트 만들기 입문 (0) | 2026.03.26 |
댓글