OpenClaw 테스트 가이드: 유닛 테스트부터 라이브 환경까지

개발을 하다 보면 로컬에서는 분명 잘 작동하던 코드가 실제 API와 연결했을 때나 복잡한 네트워크 환경에서 갑자기 에러를 뿜어내 당황스러운 적이 있죠. 특히 여러 프로바이더를 다루는 프로젝트라면 어디서 문제가 생겼는지 파악하기가 더 힘들어집니다.

OpenClaw는 이런 문제를 방지하기 위해 세 가지 단계의 테스트 스위트를 제공해요. 가벼운 유닛 테스트부터 실제 비용이 발생하는 라이브 테스트까지, 상황에 맞는 테스트 방법을 정리해 드릴게요.

필요한 것

테스트를 시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요.

• pnpm: 패키지 매니저
• API Keys: Live 테스트 실행 시 필요
• Credentials: ~/.openclaw/ 경로에 저장된 프로필 또는 설정 파일
• Docker: Linux 환경 검증이 필요한 경우

빠른 시작

가장 빠르게 테스트를 실행하는 방법이에요. 보통 코드 푸시 전에는 Full gate 명령어를 사용합니다.

# Full gate (푸시 전 권장)
pnpm lint && pnpm build && pnpm test

# 커버리지 확인
pnpm test:coverage

# E2E 스위트 (Gateway 네트워킹 확인)
pnpm test:e2e

# Live 스위트 (실제 프로바이더 호출, 비용 발생)
pnpm test:live

Test Suites

OpenClaw의 테스트는 크게 네 가지 영역으로 나뉩니다.

1. Unit / Integration (기본): src/**/*.test.ts 파일들을 테스트해요. 외부 키가 필요 없고 속도가 매우 빠릅니다. CI에서 항상 실행돼요.
2. E2E (Gateway Smoke): src/**/*.e2e.test.ts 파일을 다룹니다. 멀티 인스턴스 Gateway, WebSocket, HTTP 환경을 테스트해요.
3. Live (Real Providers): src/**/*.live.test.ts 파일을 사용하며, 실제 API 호출을 수행합니다. 비용과 Rate Limit이 발생하므로 주의가 필요해요.
4. Docker Runners: Linux 환경에서의 동작을 검증하기 위해 Docker 컨테이너 내부에서 테스트를 실행합니다.

상황	추천 스위트
로직이나 테스트 코드를 수정할 때	pnpm test
Gateway 네트워킹 설정을 변경했을 때	pnpm test:e2e 추가 실행
”봇이 작동하지 않음” 또는 프로바이더 이슈 발생 시	범위를 좁힌 pnpm test:live

Live Testing

라이브 테스트는 두 가지 레이어로 나뉩니다.

Layer 1: Direct Model Completion

Gateway를 거치지 않고 프로바이더에 직접 요청을 보냅니다. API 자체가 문제인지, 아니면 내부 파이프라인 문제인지 구분할 때 유용해요.

OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

Layer 2: Gateway + Agent Smoke

Gateway부터 Agent, 모델, 도구(Tools)까지 이어지는 전체 파이프라인을 테스트합니다.

OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

이 테스트에는 파일 읽기/쓰기, 이미지 OCR 등 다양한 프로브(Probe)가 포함되어 있어요.

Docker Runners

Linux 환경에서의 유효성을 검증하고 싶다면 Docker를 활용해 보세요.

pnpm test:docker:live-models       # 직접 모델 테스트
pnpm test:docker:live-gateway      # Gateway + Agent 테스트
pnpm test:docker:onboard           # 온보딩 위저드 테스트
pnpm test:docker:gateway-network   # 두 개의 컨테이너 네트워킹 테스트
pnpm test:docker:plugins           # 플러그인 로딩 테스트

문제 해결

라이브 테스트를 실행할 때 모든 테스트가 돌아가면 속도가 느려지고 비용이 많이 들 수 있어요. 이때는 allowlist를 사용해 범위를 좁히는 것이 좋습니다.

# 특정 모델 하나만 직접 테스트할 때
OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

# 여러 프로바이더를 지정할 때
OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5" pnpm test:live

또한, 자격 증명(Credentials) 문제가 발생한다면 ~/.openclaw/ 폴더에 프로필이나 설정 파일이 제대로 있는지 확인해 보세요. 환경 변수로도 설정할 수 있습니다.

여전히 문제가 해결되지 않나요? AI Setup Assistant가 테스트 관련 이슈를 도와드릴 수 있어요.

다음 단계

• Logging → — 로그 파일 및 콘솔 출력 확인법
• Debugging → — Watch 모드와 로우 스트림 디버깅
• Contributing → — 개발 가이드라인 및 기여 방법