OpenClaw 오류 해결: 15가지 일반적인 문제 및 해결 방법

요약

OpenClaw 문제 해결은 연결 끊김, 인증 실패, 라우팅 오류, 성능 문제를 다룹니다. 대부분의 문제는 네트워크 불안정, 잘못된 API 키 또는 채널 구성 오류에서 비롯됩니다. 이 가이드는 가장 일반적인 15가지 OpenClaw 오류에 대한 단계별 해결 방법을 제공합니다.

설치 및 설정 문제

Node.js 버전 불일치

문제: openclaw 명령어를 찾을 수 없거나 "지원되지 않는 Node 버전" 오류가 발생합니다.

원인: OpenClaw는 Node.js 22 이상 버전을 필요로 합니다. 이전 버전에는 필요한 기능이 없습니다.

해결 방법:

Node 버전 확인:

node --version

버전이 22 미만이면 Node를 업데이트하세요:

# nvm 사용 (권장)
nvm install 22
nvm use 22

# 또는 nodejs.org에서 다운로드

OpenClaw 재설치:

npm install -g openclaw@latest

설치 확인:

openclaw --version

설치 중 권한 거부

문제: npm install -g openclaw 명령어가 EACCES 또는 권한 오류와 함께 실패합니다.

원인: npm이 적절한 권한 없이 시스템 디렉토리에 쓰려고 합니다.

해결 방법:

sudo를 사용하지 마세요. 대신 npm이 사용자 디렉토리를 사용하도록 구성하세요:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

셸 프로필(~/.zshrc 또는 ~/.bashrc)에 추가:

export PATH=~/.npm-global/bin:$PATH

셸 다시 로드:

source ~/.zshrc

OpenClaw 설치:

npm install -g openclaw@latest

구성 파일을 찾을 수 없음

문제: 설치 후 OpenClaw가 ~/.openclaw/config.json 파일을 찾을 수 없습니다.

원인: 온보딩 마법사가 실행되지 않았거나 조용히 실패했습니다.

해결 방법:

온보딩을 수동으로 실행하세요:

openclaw onboard

실패하면 구성 디렉토리를 만드세요:

mkdir -p ~/.openclaw

최소 구성 파일을 만드세요:

cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF

온보딩을 다시 실행하세요:

openclaw onboard

채널 연결 문제

WhatsApp QR 코드 스캔 불가

문제: QR 코드가 나타나지만 WhatsApp 앱에서 "잘못된 QR 코드"라고 표시되거나 응답이 없습니다.

원인: QR 코드가 만료되었거나 휴대폰과 OpenClaw 간의 네트워크 문제입니다.

해결 방법:

1. 휴대폰과 컴퓨터가 동일한 네트워크에 있는지 확인하세요.
2. QR 코드 재생성:

openclaw channels logout whatsapp
openclaw channels login whatsapp

1. 30초 이내에 스캔하세요 (QR 코드는 빨리 만료됩니다).
2. 여전히 실패하면 방화벽 설정을 확인하세요:

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node

# Linux (ufw)
sudo ufw allow 18789/tcp

WhatsApp이 몇 시간 후 연결 해제됨

문제: WhatsApp이 처음에는 작동하지만 2-4시간 후에 연결이 끊깁니다.

원인: WhatsApp 프로토콜은 주기적인 하트비트를 필요로 합니다. 네트워크 변경 또는 절전 모드는 연결을 방해합니다.

해결 방법:

자동 재연결 활성화:

openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300

이것은 5분마다 연결을 확인하고 필요한 경우 재연결합니다.

노트북을 사용하는 경우, OpenClaw가 실행되는 동안 절전 모드를 방지하세요:

# macOS
caffeinate -i openclaw gateway

# Linux
systemd-inhibit --what=sleep openclaw gateway

프로덕션 환경에서는 노트북 대신 서버에서 OpenClaw를 실행하세요.

Telegram 봇이 메시지를 받지 못함

문제: 봇이 온라인이지만 메시지에 응답하지 않습니다.

원인: 봇에 필요한 권한이 없거나 토큰이 유효하지 않습니다.

해결 방법:

봇 토큰 테스트:

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

오류가 반환되면 토큰을 재생성하세요:

1. Telegram을 열고 @BotFather에게 메시지를 보내세요.
2. `/mybots`를 보내세요.
3. 봇을 선택하세요.
4. "API 토큰" → "토큰 재생성"을 선택하세요.
5. OpenClaw 업데이트:

openclaw channels update telegram --token NEW_TOKEN

그룹 채팅의 경우 봇을 "메시지 읽기" 권한을 가진 관리자로 추가하세요.

Discord 봇이 오프라인으로 표시됨

문제: Discord 서버 목록에 봇이 오프라인으로 표시됩니다.

원인: "메시지 내용 인텐트"가 없거나 토큰이 유효하지 않습니다.

해결 방법:

1. Discord 개발자 포털로 이동하세요.
2. 애플리케이션을 선택하세요.
3. "봇" 탭으로 이동하세요.
4. Privileged Gateway Intents 아래에서 "메시지 내용 인텐트"를 활성화하세요.
5. 변경 사항을 저장하세요.
6. OpenClaw 재시작:

openclaw gateway restart

봇이 여전히 오프라인이면 토큰을 확인하세요:

openclaw channels test discord

실패하면 개발자 포털에서 토큰을 재생성하고 OpenClaw를 업데이트하세요.

iMessage 브리지 작동 안 함 (macOS)

문제: iMessage 채널이 "연결 끊김"으로 표시되거나 메시지를 받지 못합니다.

원인: 접근성 권한이 없거나 메시지 앱이 실행 중이지 않습니다.

해결 방법:

1. 시스템 설정 → 개인 정보 보호 및 보안 → 손쉬운 사용을 여세요.
2. 터미널(또는 터미널 앱)을 허용 목록에 추가하세요.
3. OpenClaw 재시작:

openclaw gateway restart

1. 메시지 앱이 실행 중이고 로그인되어 있는지 확인하세요.
2. 자신에게 메시지를 보내서 테스트하세요.

여전히 작동하지 않으면 브리지 프로세스를 확인하세요:

ps aux | grep openclaw-imessage-bridge

실행 중이지 않으면 수동으로 시작하세요:

openclaw channels restart imessage

인증 및 API 오류

유효하지 않은 API 키

문제: 로그에 "인증 실패" 또는 "유효하지 않은 API 키" 오류가 표시됩니다.

원인: 잘못된 API 키, 만료된 키 또는 적절한 권한이 없는 키입니다.

해결 방법:

API 키를 확인하세요:

# Anthropic용
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# OpenAI용
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'

curl 명령이 실패하면 키가 유효하지 않은 것입니다. 공급자 대시보드에서 새 키를 받으세요.

OpenClaw 업데이트:

openclaw config set --provider anthropic --api-key NEW_KEY

게이트웨이 재시작:

openclaw gateway restart

속도 제한 초과

문제: "속도 제한 초과" 또는 "너무 많은 요청" 오류가 발생합니다.

원인: AI 공급자에게 너무 많은 요청을 보내고 있습니다.

해결 방법:

사용량 확인:

openclaw stats --period 1h

속도 제한 활성화:

openclaw limits set --max-requests 50 --window 3600

이것은 시간당 50개의 요청으로 제한합니다. 공급자의 제한에 따라 조정하세요.

버스트 트래픽의 경우 큐잉 활성화:

openclaw config set --enable-queue true --queue-max-size 100

속도 제한에 도달하면 메시지가 큐에 대기하고 용량이 확보되면 처리됩니다.

모델을 찾을 수 없음

문제: "모델을 찾을 수 없음" 또는 "유효하지 않은 모델" 오류가 발생합니다.

원인: 존재하지 않거나 계정에서 사용할 수 없는 모델을 지정했습니다.

해결 방법:

사용 가능한 모델 나열:

# Anthropic
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: YOUR_KEY"

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

에이전트 구성 업데이트:

openclaw agents update default --model claude-sonnet-4-6

게이트웨이 재시작:

openclaw gateway restart

크레딧 부족

문제: "크레딧 부족" 또는 "결제 필요" 오류가 발생합니다.

원인: AI 공급자 계정의 크레딧이 소진되었거나 청구 한도에 도달했습니다.

해결 방법:

공급자 대시보드에서 계정 잔액을 확인하세요:

• Anthropic: https://console.anthropic.com/settings/billing
• OpenAI: https://platform.openai.com/account/billing

크레딧을 추가하거나 결제 방법을 업데이트하세요.

기다리는 동안 무료 또는 로컬 모델로 라우팅하세요:

openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback

메시지 라우팅 실패

메시지가 잘못된 에이전트로 이동함

문제: 라우팅 규칙에도 불구하고 메시지가 잘못된 AI 에이전트로 라우팅됩니다.

원인: 라우팅 규칙이 충돌하거나 우선순위가 올바르지 않습니다.

해결 방법:

모든 라우팅 규칙 나열:

openclaw routing list

충돌을 확인하세요. 우선순위가 높은 규칙이 먼저 일치합니다. 다음과 같은 경우:

Priority 5: channel=whatsapp → agent=default
Priority 10: sender=+1234567890 → agent=vip

WhatsApp의 +1234567890으로부터의 메시지는 vip로 이동합니다 (우선순위 10이 승리).

충돌하는 규칙 제거:

openclaw routing remove <rule-id>

올바른 우선순위로 규칙 추가:

openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10

라우팅 테스트:

openclaw routing test --channel whatsapp --sender +1234567890 --message "test"

이것은 메시지를 보내지 않고 어떤 에이전트가 메시지를 처리할지 보여줍니다.

키워드 라우팅이 작동하지 않음

문제: 특정 키워드가 포함된 메시지가 구성된 에이전트로 라우팅되지 않습니다.

원인: 키워드가 대소문자를 구분하거나 메시지에 정확한 키워드가 포함되어 있지 않습니다.

해결 방법:

키워드를 대소문자 구분 없이 만드세요:

openclaw routing add --keyword "debug" --agent debugging --case-insensitive

유연한 일치를 위해 정규식을 사용하세요:

openclaw routing add --pattern "debug|error|bug" --agent debugging

이것은 메시지 내의 "debug", "error" 또는 "bug"를 일치시킵니다.

키워드 일치 테스트:

openclaw routing test --message "I found a debug issue"

사용자 정의 라우팅 함수 오류

문제: 사용자 정의 라우팅 함수가 오류를 발생시키거나 실행되지 않습니다.

원인: 구문 오류, 누락된 종속성 또는 잘못된 반환 값입니다.

해결 방법:

라우팅 함수를 테스트하세요:

openclaw routing test-custom ~/.openclaw/routing.js --message "test"

이것은 함수를 실행하고 결과 또는 오류를 보여줍니다.

일반적인 문제:

1. 구문 오류: JavaScript 구문을 확인하세요.
2. 반환 누락: 항상 에이전트 이름을 반환해야 합니다.
3. 비동기 함수: 라우팅 함수에서는 async/await를 사용하지 마세요 (동기적이어야 합니다).

올바른 함수 예시:

module.exports = function route(message) {
  // 항상 문자열(에이전트 이름)을 반환합니다.
  if (message.channel === 'whatsapp') {
    return 'whatsapp-agent';
  }
  return 'default';
};

잘못된 함수 예시:

// 이렇게 하지 마세요
module.exports = async function route(message) {
  const result = await someAsyncOperation();
  return result; // 비동기 함수는 지원되지 않습니다
};

대체 에이전트가 트리거되지 않음

문제: 기본 에이전트가 실패할 때 메시지가 대체 에이전트로 라우팅되지 않습니다.

원인: 대체 에이전트가 구성되지 않았거나 기본 에이전트가 실패를 올바르게 보고하지 않습니다.

해결 방법:

대체 에이전트 구성:

openclaw routing set-fallback backup-agent

대체 에이전트 테스트:

# 기본 에이전트를 일시적으로 비활성화합니다.
openclaw agents disable default

# 테스트 메시지를 보냅니다.
openclaw routing test --message "test"

# 대체 에이전트를 표시해야 합니다.

기본 에이전트 다시 활성화:

openclaw agents enable default

성능 및 메모리 문제

높은 메모리 사용량

문제: OpenClaw가 2GB 이상의 RAM을 사용하고 계속 증가합니다.

원인: 세션 데이터가 정리 없이 시간이 지남에 따라 축적됩니다.

해결 방법:

메모리 사용량 확인:

openclaw stats --memory

오래된 세션 지우기:

openclaw sessions clear --older-than 7d

세션 타임아웃 줄이기:

openclaw config set --session-timeout 1800

이제 세션은 기본 1시간 대신 30분 동안 활동이 없으면 만료됩니다.

자동 정리 활성화:

openclaw config set --auto-cleanup true --cleanup-interval 3600

이것은 매시간 정리를 실행합니다.

느린 응답 시간

문제: AI 응답이 30초 이상 걸리거나 시간 초과됩니다.

원인: 네트워크 지연, 느린 AI 공급자 또는 큐 백로그입니다.

해결 방법:

큐 상태 확인:

openclaw queue status

큐에 50개 이상의 메시지가 있으면 동시성 증가:

openclaw config set --max-concurrent-requests 10

이것은 기본 3개 대신 10개의 메시지를 동시에 처리합니다.

AI 공급자에 대한 네트워크 지연 확인:

# Anthropic
ping api.anthropic.com

# OpenAI
ping api.openai.com

지연 시간이 길면 (>200ms) 다른 공급자 또는 로컬 모델을 사용하는 것을 고려하세요.

요청 타임아웃 활성화:

openclaw config set --request-timeout 30000

30초 이상 걸리는 요청은 실패하고 재시도됩니다.

게이트웨이가 응답하지 않음

문제: 게이트웨이가 메시지 또는 API 호출에 응답하지 않습니다.

원인: 교착 상태, 무한 루프 또는 리소스 고갈입니다.

해결 방법:

게이트웨이 상태 확인:

openclaw gateway status

멈춰 있으면 스레드 덤프를 얻으세요:

kill -SIGUSR1 $(pgrep -f "openclaw gateway")

이것은 ~/.openclaw/gateway.log에 스레드 덤프를 작성합니다. 멈춘 작업을 찾으세요.

게이트웨이 재시작:

openclaw gateway restart

상태 확인 활성화:

openclaw config set --health-check-interval 60

이제 게이트웨이는 60초마다 자체 상태를 확인하고 응답하지 않으면 다시 시작합니다.

CPU 사용량 급증

문제: OpenClaw가 지속적으로 CPU를 100% 사용합니다.

원인: 무한 루프, 과도한 로깅 또는 메시지 플러딩입니다.

해결 방법:

CPU를 소비하는 항목 확인:

top -p $(pgrep -f "openclaw gateway")

로그 레벨 감소:

openclaw config set --log-level warn

이것은 디버그 및 정보 로그를 비활성화하여 I/O를 줄입니다.

메시지 플러딩 확인:

openclaw stats --messages --period 1h

시간당 1000개 이상의 메시지를 수신하는 경우 채널당 속도 제한 활성화:

openclaw channels config whatsapp --rate-limit 100 --rate-window 3600

게이트웨이 충돌 및 재시작

시작 시 게이트웨이 충돌

문제: openclaw gateway가 오류 메시지 없이 즉시 충돌합니다.

원인: 손상된 구성 파일 또는 누락된 종속성입니다.

해결 방법:

디버그 모드로 실행:

openclaw gateway --debug

이것은 자세한 오류 메시지를 보여줍니다.

일반적인 원인:

1. 손상된 구성: 구성을 백업하고 재설정하세요.

cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard

1. 누락된 종속성: OpenClaw 재설치.

npm uninstall -g openclaw
npm install -g openclaw@latest

1. 포트가 이미 사용 중: 포트를 변경하세요.

openclaw gateway --port 18790

작동 중 게이트웨이 충돌

문제: 게이트웨이가 잠시 실행되다가 예기치 않게 충돌합니다.

원인: 처리되지 않은 예외, 메모리 누수 또는 외부 프로세스에 의한 종료입니다.

해결 방법:

충돌 로그 확인:

tail -100 ~/.openclaw/gateway.log

충돌 전에 스택 추적 또는 오류 메시지를 찾으세요.

충돌 덤프 활성화:

openclaw config set --enable-crash-dumps true

다음 충돌 시 ~/.openclaw/crashes/에 덤프를 작성합니다. 디버깅을 위해 OpenClaw 팀과 공유하세요.

자동 재시작으로 게이트웨이 실행:

openclaw gateway --auto-restart

게이트웨이는 충돌 후 자동으로 다시 시작합니다.

프로덕션 환경에서는 프로세스 관리자를 사용하세요:

# pm2 사용
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup

재시작 후 세션 데이터 손실

문제: 게이트웨이 재시작 후 대화가 재설정됩니다.

원인: 세션이 디스크에 유지되지 않거나 세션 파일이 손상되었습니다.

해결 방법:

세션 유지 활성화:

openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db

이제 세션은 30초마다 디스크에 저장됩니다.

세션 파일 확인:

ls -lh ~/.openclaw/sessions.db

파일이 0바이트이거나 없으면 세션이 저장되지 않습니다. 디스크 공간을 확인하세요:

df -h ~

디스크가 가득 차면 공간을 확보하고 게이트웨이를 재시작하세요.

백업에서 복원:

cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart

플랫폼별 문제

macOS: "openclaw"를 열 수 없습니다

문제: macOS가 "확인되지 않은 개발자" 경고로 OpenClaw를 차단합니다.

원인: macOS Gatekeeper 보안 기능입니다.

해결 방법:

OpenClaw 허용:

xattr -d com.apple.quarantine $(which openclaw)

또는 시스템 설정 → 개인 정보 보호 및 보안으로 이동하여 OpenClaw 경고 옆의 "어쨌든 허용"을 클릭하세요.

Linux: inotify에 대한 권한 거부

문제: "ENOSPC: 파일 감시자 수에 대한 시스템 제한에 도달했습니다."

원인: Linux는 프로세스가 감시할 수 있는 파일 수를 제한합니다.

해결 방법:

제한 증가:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

OpenClaw 재시작:

openclaw gateway restart

Windows: 명령을 찾을 수 없음

문제: Windows에서 openclaw 명령어를 인식하지 못합니다.

원인: npm 전역 bin 디렉토리가 PATH에 없습니다.

해결 방법:

npm 전역 디렉토리 찾기:

npm config get prefix

PATH에 추가:

1. 시스템 속성 → 환경 변수를 여세요.
2. 사용자 변수 아래의 "Path"를 편집하세요.
3. C:\Users\YourName\AppData\Roaming\npm (또는 위에서 찾은 경로)를 추가하세요.
4. 확인을 클릭하고 터미널을 다시 시작하세요.

확인:

openclaw --version

Docker: 네트워크 문제

문제: Docker의 OpenClaw가 메시징 플랫폼에 연결할 수 없습니다.

원인: Docker 네트워크 격리입니다.

해결 방법:

호스트 네트워크로 실행:

docker run --network host openclaw/openclaw gateway

또는 게이트웨이 포트 노출:

docker run -p 18789:18789 openclaw/openclaw gateway

WhatsApp의 경우 QR 코드 스캔을 위해 추가 포트를 노출해야 합니다:

docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway

디버깅 도구 및 로그

디버그 로깅 활성화

자세한 로그 얻기:

openclaw config set --log-level debug
openclaw gateway restart

로그는 기본적으로 ~/.openclaw/gateway.log로 이동합니다.

실시간으로 로그 보기:

tail -f ~/.openclaw/gateway.log

개별 구성 요소 테스트

채널 테스트:

openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord

에이전트 테스트:

openclaw agents test default --message "Hello"

라우팅 테스트:

openclaw routing test --channel whatsapp --sender +1234567890 --message "debug issue"

게이트웨이 상태 검사

현재 상태 얻기:

openclaw gateway inspect

이것은 다음을 보여줍니다:

• 활성 채널 및 상태
• 구성된 에이전트 및 상태
• 라우팅 규칙 및 우선순위
• 큐 크기 및 보류 중인 메시지
• 메모리 사용량 및 가동 시간

진단 내보내기

진단 보고서 생성:

openclaw diagnostics export > openclaw-diagnostics.json

이것은 다음을 포함합니다:

• 구성 (API 키는 마스킹됨)
• 최근 로그
• 오류 횟수
• 성능 지표
• 시스템 정보

문제를 보고할 때 이것을 지원팀과 공유하세요.

네트워크 디버깅

AI 공급자에 대한 연결 테스트:

openclaw network test anthropic
openclaw network test openai

이것은 다음을 확인합니다:

• DNS 해결
• TLS 핸드셰이크
• API 엔드포인트 도달 가능성
• 지연 시간

어떤 검사라도 실패하면 네트워크 문제가 있습니다.

자주 묻는 질문

OpenClaw는 왜 이렇게 많은 메모리를 사용하나요?

OpenClaw는 빠른 액세스를 위해 세션 기록을 메모리에 유지합니다. 각 세션은 전체 대화 컨텍스트를 저장합니다. 각각 50개의 메시지를 가진 100개의 활성 세션이 있다면, 메모리에는 5000개의 메시지가 있습니다.

메모리 사용량 줄이기:

1. 세션 타임아웃을 낮추세요.
2. 자동 정리를 활성화하세요.
3. 세션당 컨텍스트 길이를 제한하세요.

openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50

인터넷 없이 OpenClaw를 실행할 수 있나요?

예, 로컬 AI 모델을 사용하는 경우 가능합니다. Ollama를 설치하고 OpenClaw가 이를 사용하도록 구성하세요:

# Ollama 설치
curl https://ollama.ai/install.sh | sh

# 모델 가져오기
ollama pull llama2

# OpenClaw 구성
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434

메시징 플랫폼은 여전히 인터넷이 필요하지만, AI 추론은 로컬에서 실행됩니다.

새 머신으로 어떻게 마이그레이션하나요?

구성을 내보내세요:

openclaw config export > openclaw-backup.json

openclaw-backup.json을 새 머신으로 복사하세요.

OpenClaw 설치:

npm install -g openclaw@latest

구성 가져오기:

openclaw config import openclaw-backup.json

채널을 다시 연결하세요 (QR 코드와 토큰은 전송되지 않습니다):

openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN

메시지가 순서 없이 도착하는 이유는 무엇인가요?

OpenClaw는 메시지를 동시에 처리합니다. 3개의 메시지를 빠르게 보내면 네트워크 타이밍에 따라 AI 공급자에게 다른 순서로 도달할 수 있습니다.

순차 처리 활성화:

openclaw config set --max-concurrent-requests 1

이것은 한 번에 하나의 메시지를 처리하여 순서를 보존합니다. 더 느리지만 순서를 보장합니다.

프로덕션 환경에서 OpenClaw를 사용할 수 있나요?

예, 하지만 다음 지침을 따르세요:

1. 노트북이 아닌 서버에서 실행하세요.
2. 프로세스 관리자(pm2, systemd)를 사용하세요.
3. 세션 유지 기능을 활성화하세요.
4. 모니터링 및 경고를 설정하세요.
5. 속도 제한을 구성하세요.
6. 제어 UI를 위해 리버스 프록시(nginx)를 사용하세요.
7. HTTPS를 활성화하세요.
8. 구성을 정기적으로 백업하세요.

systemd 서비스 예시:

[Unit]
Description=OpenClaw 게이트웨이
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

버그를 어떻게 보고하나요?

1. 진단 생성:

openclaw diagnostics export > diagnostics.json

1. GitHub에서 이슈를 여세요.
2. 다음을 포함하세요:

• OpenClaw 버전 (openclaw --version)
• Node.js 버전 (node --version)
• 운영 체제
• 재현 단계
• 진단 보고서 (민감한 데이터는 마스킹)

결론

대부분의 OpenClaw 문제는 네트워크 문제, 잘못된 구성 또는 플랫폼별 특이성에서 비롯됩니다. 이 가이드는 가장 일반적인 15가지 오류와 해결 방법을 다룹니다.

주요 문제 해결 단계:

1. 먼저 로그를 확인하세요 (~/.openclaw/gateway.log).
2. 구성 요소를 개별적으로 테스트하세요 (채널, 에이전트, 라우팅).
3. 자세한 오류를 위해 디버그 모드를 활성화하세요.
4. 상태를 내보내기 위해 진단 도구를 사용하세요.
5. 도움을 받으려면 커뮤니티에 참여하세요.

OpenClaw와 함께 API 워크플로우를 구축 중이라면, API 디자인, 테스트 및 문서화를 위해 Apidog를 확인해 보세요. Apidog는 OpenClaw의 대화형 인터페이스를 구조화된 API 관리로 보완합니다.

다음 단계:

• 빠른 참조를 위해 이 가이드를 북마크하세요.
• 문제를 조기에 발견하기 위해 모니터링을 설정하세요.
• 실시간 도움을 받으려면 OpenClaw Discord에 참여하세요.
• GitHub에서 프로젝트에 수정 사항을 기여하세요.