OpenClaw API 연결 오류 해결 완벽 가이드

서문

OpenClaw는 다양한 AI 모델 제공업체의 API와 통신해야 합니다. 사용 과정에서 여러 종류의 연결 오류를 만날 수 있습니다. 본 글에서는 각 오류의 원인과 해결 방안을 체계적으로 소개하여 문제를 신속하게 파악하고 수정할 수 있도록 도와드리겠습니다.

1. 빠른 진단 도구

문제를 해결하기 전에 먼저 OpenClaw 내장 진단 도구를 사용합니다:

# 종합 진단 실행
openclaw doctor

# 실시간 로그에서 오류 확인
openclaw logs | grep -i "error\|fail\|timeout"

# API 연결 테스트
curl -v 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-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

2. HTTP 오류 코드 상세 설명

2.1 401 Unauthorized — 인증 실패

증상:

Error: API request failed with status 401: Invalid API key

원인 및 해결 방안:

# 설정 파일의 API Key 확인
cat ~/.config/openclaw/openclaw.json5 | grep -i "key\|token"

# Key 형식이 올바른지 확인 (Anthropic의 경우 sk-ant-로 시작해야 함)
# 업데이트 후 재시작
openclaw restart

2.2 403 Forbidden — 권한 부족

증상:

Error: API request failed with status 403: Permission denied

일반적인 원인:

• API Key에 해당 모델의 접근 권한이 없음
• 계정에서 특정 모델 사용 자격을 개통하지 않음 (예: Claude Opus)
• IP 주소가 API 제공업체에 의해 차단됨
• 해당 지역이 서비스 범위에 포함되지 않음

# IP 제한 문제인지 확인
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -w "\n%{http_code}" 2>&1

# 프록시를 사용하는 경우 프록시 설정이 올바른지 확인
echo $HTTP_PROXY
echo $HTTPS_PROXY

2.3 429 Too Many Requests — 속도 제한

증상:

Error: Rate limit exceeded. Please retry after 30 seconds.

각 제공업체의 속도 제한 참고:

해결 방안:

// ~/.config/openclaw/openclaw.json5
{
  "rateLimiting": {
    // 전역 요청 간격 (밀리초)
    "minInterval": 1000,
    // 속도 제한 시 재시도 전략
    "retry": {
      "enabled": true,
      "maxRetries": 3,
      "backoffMultiplier": 2,
      "initialDelay": 5000
    }
  }
}

2.4 500 Internal Server Error — 서버 내부 오류

처리 방법:

# 보통 제공업체 측의 문제입니다. 서비스 상태 페이지를 확인하세요
# Anthropic: https://status.anthropic.com
# OpenAI: https://status.openai.com

# 대체 모델 자동 전환 설정

// ~/.config/openclaw/openclaw.json5
{
  "models": {
    "primary": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "fallback": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}

2.5 502/503 Bad Gateway / Service Unavailable

증상:

Error: 502 Bad Gateway
Error: 503 Service Unavailable - The server is temporarily overloaded

해결 단계:

# 1. 제공업체 서비스 장애인지 확인
curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com/v1/messages

# 2. 로컬 네트워크가 정상인지 확인
ping api.anthropic.com
traceroute api.anthropic.com

# 3. 리버스 프록시를 사용하는 경우 프록시가 정상인지 확인
nginx -t
systemctl status nginx

3. 타임아웃 문제 해결

3.1 연결 타임아웃

Error: connect ETIMEDOUT 104.18.0.1:443

# API 엔드포인트와의 연결 테스트
curl -v --connect-timeout 10 https://api.anthropic.com/v1/messages

# 연결 타임아웃이 발생하면 프록시 설정이 필요할 수 있습니다

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890",
    // 또는 SOCKS5 프록시 사용
    // "url": "socks5://127.0.0.1:1080"
  },
  "timeout": {
    "connect": 30000,    // 연결 타임아웃 30초
    "request": 120000    // 요청 타임아웃 120초
  }
}

3.2 요청 타임아웃

모델이 긴 텍스트를 생성할 때 기본 타임아웃 시간을 초과할 수 있습니다:

// 타임아웃 시간 증가
{
  "timeout": {
    "request": 300000  // 5분
  }
}

4. DNS 해석 실패

증상:

Error: getaddrinfo ENOTFOUND api.anthropic.com
Error: querySrv ESERVFAIL _http._tcp.api.openai.com

해결 방안:

# 1. DNS 해석 확인
nslookup api.anthropic.com
dig api.anthropic.com

# 2. 공용 DNS 사용 시도
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf

# 3. hosts 레코드 수동 추가 (임시 방안)
echo "104.18.0.1 api.anthropic.com" | sudo tee -a /etc/hosts

# 4. 수정 후 해석 테스트
nslookup api.anthropic.com

5. SSL 인증서 오류

증상:

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
Error: CERT_HAS_EXPIRED

해결 방법:

# 1. 인증서 정보 확인
openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com </dev/null 2>/dev/null | openssl x509 -noout -dates

# 2. 시스템 CA 인증서 업데이트
# Ubuntu/Debian
sudo apt update && sudo apt install -y ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust

# 3. 프록시의 중간자 인증서 문제인 경우
# 프록시의 CA 인증서를 Node.js 신뢰 목록에 추가
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt

경고: 프로덕션 환경에서 절대로 NODE_TLS_REJECT_UNAUTHORIZED=0을 설정하지 마세요. 이는 SSL 검증을 완전히 비활성화하여 심각한 보안 위험이 있습니다.

6. 프록시 설정 문제

6.1 HTTP 프록시

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890"
  }
}

6.2 환경 변수 방식

# 시스템 환경에 설정
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

# OpenClaw 재시작
openclaw restart

6.3 프록시 연결성 테스트

# 프록시를 통한 API 접근 테스트
curl -x http://127.0.0.1:7890 -v https://api.anthropic.com/v1/messages

# SOCKS5 프록시 테스트
curl -x socks5://127.0.0.1:1080 -v https://api.anthropic.com/v1/messages

7. 각 제공업체별 전문 해결

7.1 Anthropic (Claude)

# API Key 유효성 검증
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":5,"messages":[{"role":"user","content":"test"}]}'

자주 발생하는 문제: API Key 형식은 sk-ant-api03-...이며, OpenAI의 Key와 혼동하지 않도록 주의하세요.

7.2 OpenAI (GPT)

# API Key 검증
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}],"max_tokens":5}'

자주 발생하는 문제: 무료 할당량을 다 사용하면 429 오류가 반환되므로 결제 수단을 등록해야 합니다.

7.3 Ollama (로컬 모델)

# Ollama 서비스 실행 여부 확인
curl http://localhost:11434/api/tags

# 모델 다운로드 확인
ollama list

# 모델 호출 테스트
curl http://localhost:11434/api/generate \
  -d '{"model":"llama3","prompt":"test","stream":false}'

자주 발생하는 문제: Ollama는 기본적으로 localhost만 수신합니다. OpenClaw가 다른 머신에 있다면 OLLAMA_HOST=0.0.0.0을 설정해야 합니다.

7.4 OpenRouter

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"test"}]}'

8. 오류 해결 체크리스트

API 연결 오류가 발생하면 다음 순서로 확인하세요:

1. ✅ openclaw doctor를 실행하여 진단 결과 확인
2. ✅ API Key가 올바르고 만료되지 않았는지 확인
3. ✅ 네트워크 연결 확인 (ping, curl)
4. ✅ 프록시 설정이 올바른지 확인 (프록시 사용 시)
5. ✅ DNS 해석이 정상인지 확인
6. ✅ SSL 인증서가 유효한지 확인
7. ✅ 제공업체 서비스 상태 페이지 확인
8. ✅ 속도 제한이 발동되었는지 확인
9. ✅ openclaw logs에서 상세한 오류 정보 확인
10. ✅ curl로 직접 API를 호출하여 OpenClaw 자체 문제 배제

이러한 해결 기법을 숙지하면 대부분의 API 연결 문제를 신속하게 파악하고 해결하여 OpenClaw 서비스의 안정적인 운영을 유지할 수 있습니다.