🇨🇳 简体中文 🇹🇼 繁體中文 🇯🇵 日本語 🇰🇷 한국어 🇮🇳 हिन्दी 🇧🇩 বাংলা 🇮🇩 Bahasa Indonesia 🇪🇸 Español 🇧🇷 Português 🇫🇷 Français 🇩🇪 Deutsch
홈 / 문제 해결

문제 해결

문제가 생겼나요? 당황하지 마세요! 아래 방법을 단계별로 따라 하면, 대부분의 문제를 직접 해결할 수 있어요.

🔍 진단 단계 (순서대로 따라 해 주세요)

OpenClaw에 문제가 발생하면, 다음 순서대로 단계적으로 점검하세요:

1

실행 상태 확인

openclaw status

OpenClaw가 아직 실행 중인지 확인하세요. "stopped"가 표시되거나 오류가 나면, 먼저 재시작을 시도해 보세요.

2

게이트웨이 상태 확인

openclaw gateway status

게이트웨이는 OpenClaw가 채팅 플랫폼에 연결하는 다리 역할을 해요. 게이트웨이 상태가 비정상이면, 채팅 메시지를 주고받을 수 없어요.

3

로그 확인

openclaw logs

로그에는 OpenClaw 실행의 모든 세부 사항이 기록되어 있어요. 오류가 있으면, 보통 빨간색 오류 메시지로 어디에 문제가 있는지 알려줘요.

4

상태 점검 실행

openclaw doctor

전체적인 상태 점검으로, 어떤 구성 요소가 정상이고 어떤 것에 문제가 있는지 알려줘요.

5

채널 연결 확인

openclaw channels status

각 채팅 채널의 연결 상태를 확인해서, 어떤 채널이 연결이 끊어졌는지 살펴보세요.

🐛 자주 발생하는 오류와 해결 방법

오류: "openclaw: command not found"

원인: 시스템이 openclaw 명령어를 찾지 못하는 것으로, 보통 PATH 환경 변수 문제예요.

해결:

# openclaw 설치 위치 확인
npm list -g openclaw

# npm 전역 디렉토리를 PATH에 추가
export PATH="$(npm config get prefix)/bin:$PATH"

# 위 명령어를 shell 설정 파일에 추가해서 영구적으로 적용
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

오류: 포트 충돌 (EADDRINUSE: address already in use :::18789)

원인: 포트 18789가 이미 다른 프로그램에 의해 사용 중이에요.

해결:

# 포트를 사용 중인 프로세스 찾기
lsof -i :18789

# 이전 OpenClaw 프로세스 중지
openclaw stop

# OpenClaw 프로세스가 아닌 경우, 설정에서 포트를 변경할 수 있어요
# ~/.openclaw/openclaw.json을 편집해서 port 값을 수정하세요

오류: 429 Too Many Requests (속도 제한)

원인: 요청을 너무 자주 보내서, AI 모델 제공업체의 API 호출 빈도 제한에 걸린 거예요.

해결:

  • 몇 분 기다린 후 다시 시도하세요
  • 메시지 전송 빈도를 줄이세요
  • API 유료 플랜을 업그레이드해서 더 높은 속도 제한을 받으세요
  • 제한이 더 느슨한 모델 제공업체로 전환을 고려해 보세요

오류: 게이트웨이를 시작할 수 없음

원인: Bot Token이 유효하지 않거나, 네트워크 연결 문제, 또는 채팅 플랫폼 API 변경일 수 있어요.

해결:

# 게이트웨이 로그 확인
openclaw gateway logs

# Bot Token이 유효한지 검증
openclaw channels verify

# 게이트웨이 재시작
openclaw gateway restart

오류: 메시지를 보낼 수 없음

원인: 채널 설정 오류, 네트워크 문제, 또는 Bot 권한 부족일 수 있어요.

해결:

  • 채널 상태 확인: openclaw channels status
  • 해당 플랫폼에서 Bot이 메시지 전송 권한을 가지고 있는지 확인
  • 네트워크 연결이 정상인지 확인
  • 로그에서 구체적인 오류 메시지가 있는지 확인

오류: 대시보드가 열리지 않음

원인: OpenClaw 서비스가 실행되지 않고 있거나, 포트 설정이 잘못되었을 수 있어요.

해결:

# OpenClaw가 실행 중인지 확인
openclaw status

# 실행 중이 아니면, 시작하기
openclaw start

# 그런 다음 대시보드 열기 시도
openclaw dashboard

# 또는 브라우저에서 직접 접속
# http://127.0.0.1:18789/

🆘 그래도 해결이 안 되나요?

위의 방법으로도 문제가 해결되지 않으면, 다음을 할 수 있어요:

  • GitHub Issues에서 검색하거나 문제를 제출하세요
  • OpenClaw의 Discord 커뮤니티에 참여해서 도움을 구하세요
  • 질문할 때 openclaw doctor와 openclaw logs의 출력 결과를 첨부해 주세요