openclaw doctor란?
openclaw doctor는 OpenClaw에 내장된 진단 도구로, 실행 환경, 설정 파일, 각종 서비스 연결 상태를 자동으로 점검하여 설치 및 배포 과정에서 발생하는 문제를 빠르게 찾아 해결할 수 있도록 도와줍니다. 설치를 막 완료했거나 운영 중 장애가 발생한 경우, openclaw doctor가 가장 먼저 사용해야 할 진단 수단입니다.
기본 사용법
터미널에서 다음 명령을 실행합니다:
openclaw doctor
명령은 여러 항목을 순차적으로 점검하고, 각 항목의 결과를 통과, 경고, 실패 상태로 명확하게 출력합니다.
점검 항목 상세
openclaw doctor는 다음과 같은 핵심 항목을 점검합니다. 각 항목의 의미와 자주 발생하는 문제를 살펴보겠습니다.
Node.js 버전 점검
OpenClaw은 Node.js 22 이상이 필요합니다. doctor는 현재 Node.js 버전이 요구 사항을 충족하는지 확인합니다.
자주 발생하는 문제: 시스템에 여러 Node.js 버전이 설치되어 있고, 실제 실행 중인 버전이 22 미만인 경우.
해결 방법:
node --version
버전이 22 미만이면 업그레이드가 필요합니다. nvm을 사용한 Node.js 버전 관리를 권장합니다:
nvm install 22
nvm use 22
nvm alias default 22
특히 주의할 점: Bun을 Node.js 대체품으로 사용하지 마세요. Bun이 일부 시나리오에서 더 빠르지만, WhatsApp 및 Telegram의 WebSocket 연결 처리 시 알려진 호환성 문제가 있어 OpenClaw 공식적으로 사용을 권장하지 않습니다.
설정 파일 점검
doctor는 ~/.openclaw/openclaw.json 설정 파일이 존재하며 형식이 올바른지 검증합니다.
자주 발생하는 문제:
- 설정 파일이 존재하지 않음: 일반적으로 초기화 가이드를 실행하지 않아서 발생
- JSON 형식 오류: 수동 편집 시 구문 오류 발생
해결 방법:
설정 파일이 없는 경우 가이드 프로그램을 실행합니다:
openclaw onboard --install-daemon
JSON 형식 오류가 있는 경우 다음 명령으로 검증할 수 있습니다:
python3 -m json.tool ~/.openclaw/openclaw.json
JSON 오류는 보통 쉼표 누락, 불필요한 쉼표, 따옴표 불일치 등으로 인해 발생합니다.
네트워크 연결 점검
doctor는 OpenClaw 핵심 서비스 및 각 AI 모델 API와의 네트워크 연결을 테스트합니다.
자주 발생하는 문제:
- 방화벽이 아웃바운드 연결을 차단
- 프록시 설정 오류
- DNS 해석 실패
해결 방법:
기본 네트워크 연결을 확인합니다:
curl -I https://api.openai.com
curl -I https://api.anthropic.com
프록시가 필요한 네트워크 환경이라면 올바른 프록시 환경 변수를 설정해야 합니다:
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port
AI 모델 API 점검
doctor는 설정된 AI 모델 API 키가 유효한지 검증하고 API 연결을 테스트합니다.
자주 발생하는 문제:
- API 키 만료 또는 무효
- API 쿼터 소진
- 선택한 모델 사용 불가
해결 방법:
설정 파일을 열어 API 키를 확인합니다:
cat ~/.openclaw/openclaw.json
키 형식이 올바르고 만료되지 않았는지 확인합니다. 각 AI 제공업체의 콘솔에서 키 상태와 잔여 쿼터를 확인할 수 있습니다. 키를 업데이트해야 하는 경우 설정 파일을 직접 편집하거나 가이드 프로그램을 다시 실행합니다.
채팅 플랫폼 연결 점검
doctor는 설정된 채팅 플랫폼의 연결 상태를 하나씩 점검합니다. WhatsApp, Telegram, Discord 등이 포함됩니다.
자주 발생하는 문제:
- WhatsApp 세션 만료로 QR 코드 재스캔 필요
- Telegram Bot Token 무효
- Discord Bot이 대상 서버에 초대되지 않음
- Webhook URL 접근 불가
해결 방법:
WhatsApp 연결 문제의 경우:
openclaw onboard
가이드 프로그램에 다시 진입하여 WhatsApp 재연결을 선택하고 안내에 따라 QR 코드를 스캔합니다.
Telegram 문제의 경우, Bot Token이 유효한지 확인합니다:
curl https://api.telegram.org/bot당신의TOKEN/getMe
Webhook URL 문제의 경우, 서버가 외부에서 접근 가능하고 포트 3000(또는 설정한 포트)이 방화벽에서 허용되어 있는지 확인합니다.
포트 점유 점검
doctor는 OpenClaw이 사용하는 포트(기본 3000)가 다른 프로그램에 의해 점유되어 있는지 확인합니다.
자주 발생하는 문제:
- 다른 OpenClaw 인스턴스가 이미 실행 중
- 다른 웹 애플리케이션이 동일한 포트를 사용 중
해결 방법:
포트 점유 상태를 확인합니다:
# Linux
ss -tlnp | grep 3000
# macOS
lsof -i :3000
포트가 점유된 경우 해당 프로세스를 중지하거나 OpenClaw 설정에서 다른 포트를 사용하도록 변경할 수 있습니다.
디스크 공간 점검
doctor는 ~/.openclaw/이 위치한 파티션에 충분한 디스크 공간이 있는지 확인합니다.
자주 발생하는 문제:
- 로그 파일 과도한 누적
- 디스크 공간 부족으로 서비스 이상 발생
해결 방법:
df -h ~
du -sh ~/.openclaw/*
공간이 부족한 경우 불필요한 로그 파일을 정리합니다:
rm -rf ~/.openclaw/logs/*.log.old
데몬 프로세스 상태 점검
doctor는 OpenClaw의 데몬 프로세스가 올바르게 설정되고 실행 중인지 확인합니다.
자주 발생하는 문제:
- systemd 서비스 미활성화 (Linux)
- LaunchAgent 미로드 (macOS)
- 서비스 중지 또는 실패 상태
해결 방법:
Linux의 경우:
systemctl status openclaw
sudo systemctl restart openclaw
macOS의 경우:
launchctl list | grep openclaw
launchctl start com.openclaw.agent
일반적인 진단 시나리오
시나리오 1: 설치 직후
설치 후 가장 먼저 openclaw doctor를 실행하여 환경이 모든 요구 사항을 충족하는지 확인합니다:
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor
시나리오 2: 서비스가 갑자기 중단된 경우
OpenClaw이 갑자기 메시지에 응답하지 않을 때:
openclaw doctor
점검 결과를 바탕으로 문제를 파악합니다. 일반적으로 네트워크 변경, API 키 만료 또는 채팅 플랫폼 세션 타임아웃이 원인입니다.
시나리오 3: 업그레이드 후 문제 발생
OpenClaw 버전 업그레이드 후 doctor를 실행하여 호환성을 확인합니다:
npm install -g openclaw@latest
openclaw doctor
시나리오 4: 마이그레이션 후 검증
OpenClaw을 한 서버에서 다른 서버로 마이그레이션한 후:
openclaw doctor
설정 파일이 올바르게 복원되었고 모든 연결이 새 환경에서 정상 작동하는지 확인합니다.
출력 해석
doctor의 출력은 색상과 기호로 각 항목의 상태를 표시합니다:
- 통과: 해당 항목이 완전히 정상이며, 조치 불필요
- 경고: 잠재적 문제가 있지만 기본 동작에는 영향 없음, 주의 필요
- 실패: 해당 항목이 통과하지 못했으며, 즉시 수정 필요
실패한 항목에 대해 doctor는 보통 구체적인 오류 정보와 수정 제안을 제공합니다. 제안에 따라 하나씩 수정한 후 openclaw doctor를 다시 실행하여 모든 항목이 통과할 때까지 반복합니다.
더 상세한 진단 정보 확인
표준 진단이 충분하지 않은 경우 OpenClaw 실행 로그에서 더 많은 정보를 확인할 수 있습니다:
# Linux systemd
journalctl -u openclaw -n 100
# macOS LaunchAgent
cat /tmp/openclaw.stderr.log
# 또는 OpenClaw 자체 로그 확인
ls ~/.openclaw/logs/
커뮤니티 도움 요청
자체적으로 해결할 수 없는 경우, openclaw doctor의 전체 출력을 OpenClaw의 GitHub Issues 또는 커뮤니티 포럼에 공유하여 도움을 요청할 수 있습니다. 진단 출력에 충분한 환경 정보가 포함되어 있어 커뮤니티 구성원이 빠르게 문제를 파악할 수 있습니다.
문제 제출 시 포함하면 좋은 정보:
openclaw doctor전체 출력openclaw --version버전 정보node --version버전 정보- 운영 체제 종류 및 버전
- 문제에 대한 상세 설명 및 재현 단계
정리
openclaw doctor는 OpenClaw 생태계에서 가장 실용적인 진단 도구 중 하나입니다. 설치 후, 업그레이드 후, 문제 발생 시 가장 먼저 doctor를 실행하는 습관을 기르면 대부분의 설치 및 배포 문제를 빠르게 식별하고 해결할 수 있습니다. 실행 환경부터 서비스 연결까지 체계적으로 점검하여 OpenClaw의 안정적인 운영을 보장하는 중요한 수단입니다.