OpenClaw 테스트 가이드: 단위부터 라이브 테스트까지

빠른 시작

대부분의 경우 다음과 같은 명령어를 사용합니다.

푸시 전 필수 확인 사항: pnpm build && pnpm check && pnpm check:test-types && pnpm test
사양이 좋은 머신에서 더 빠르게 전체 스위트를 실행할 때: pnpm test:max
Vitest watch 루프를 직접 실행할 때: pnpm test:watch
특정 파일이나 경로를 타겟팅할 때: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
단일 실패 사례를 반복적으로 수정할 때는 타겟팅 실행을 우선하세요.
Docker 기반 QA 사이트 실행: pnpm qa:lab:up
Linux VM 기반 QA 실행: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

테스트를 수정하거나 추가적인 확신이 필요할 때:

커버리지 확인: pnpm test:coverage
E2E 스위트 실행: pnpm test:e2e

실제 제공자나 모델을 디버깅할 때(실제 자격 증명 필요):

라이브 스위트(모델 + Gateway 도구/이미지 프로브): pnpm test:live
특정 라이브 테스트 파일만 조용히 실행: pnpm test:live -- src/agents/models.profiles.live.test.ts

팁: 실패한 사례 하나만 확인하면 될 때는 아래 설명된 허용 목록 환경 변수를 사용하여 라이브 테스트 범위를 좁히는 것이 좋습니다.

QA 전용 러너

이 명령어들은 QA 랩의 실제 환경과 유사한 테스트가 필요할 때 메인 테스트 스위트와 함께 사용합니다.

pnpm openclaw qa suite
- 호스트에서 리포지토리 기반 QA 시나리오를 직접 실행합니다.
- 격리된 Gateway 워커를 사용하여 기본적으로 여러 시나리오를 병렬로 실행합니다. qa-channel은 기본적으로 4개의 동시성을 가집니다. --concurrency <count>를 사용하여 워커 수를 조정하거나, 이전 방식인 직렬 실행을 위해 --concurrency 1을 사용하세요.
- 시나리오 실패 시 0이 아닌 값으로 종료됩니다. 아티팩트를 유지하면서 실패 종료 코드를 피하려면 --allow-failures를 사용하세요.
- 제공자 모드로 live-frontier, mock-openai, aimock을 지원합니다. aimock은 실험적인 픽스처 및 프로토콜 모의 테스트를 위해 로컬 AIMock 기반 제공자 서버를 시작합니다.
pnpm openclaw qa suite --runner multipass
- 일회용 Multipass Linux VM 내부에서 동일한 QA 스위트를 실행합니다.
- 호스트의 qa suite와 동일한 시나리오 선택 동작을 유지합니다.
- qa suite와 동일한 제공자/모델 선택 플래그를 재사용합니다.
- 라이브 실행 시 게스트 환경에서 실용적인 QA 인증 입력을 전달합니다(환경 기반 제공자 키, QA 라이브 제공자 설정 경로, CODEX_HOME 등).
- 출력 디렉토리는 마운트된 워크스페이스를 통해 게스트가 다시 쓸 수 있도록 리포지토리 루트 아래에 있어야 합니다.
- 일반 QA 리포트와 요약, 그리고 Multipass 로그를 .artifacts/qa-e2e/... 아래에 작성합니다.
pnpm qa:lab:up
- 운영자 스타일의 QA 작업을 위해 Docker 기반 QA 사이트를 시작합니다.
pnpm openclaw qa aimock
- 직접적인 프로토콜 스모크 테스트를 위해 로컬 AIMock 제공자 서버만 시작합니다.
pnpm openclaw qa matrix
- 일회용 Docker 기반 Tuwunel 홈 서버에 대해 Matrix 라이브 QA 레인을 실행합니다.
- 이 QA 호스트는 현재 리포지토리/개발자 전용입니다. 패키지화된 OpenClaw 설치에는 qa-lab이 포함되어 있지 않으므로 openclaw qa를 노출하지 않습니다.
- 리포지토리 체크아웃은 번들된 러너를 직접 로드하므로 별도의 플러그인 설치 단계가 필요 없습니다.
- 3개의 임시 Matrix 사용자(driver, sut, observer)와 1개의 비공개 방을 프로비저닝한 후, 실제 Matrix 플러그인을 SUT 전송으로 사용하는 QA Gateway 자식을 시작합니다.
- 기본적으로 고정된 안정적인 Tuwunel 이미지 ghcr.io/matrix-construct/tuwunel:v1.5.1을 사용합니다. 다른 이미지를 테스트해야 할 경우 OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE로 재정의하세요.
- Matrix는 로컬에서 일회용 사용자를 프로비저닝하므로 공유 자격 증명 소스 플래그를 노출하지 않습니다.
- Matrix QA 리포트, 요약, 관찰된 이벤트 아티팩트, 결합된 stdout/stderr 출력 로그를 .artifacts/qa-e2e/... 아래에 작성합니다.
pnpm openclaw qa telegram
- 환경 변수의 드라이버 및 SUT 봇 토큰을 사용하여 실제 비공개 그룹에 대해 Telegram 라이브 QA 레인을 실행합니다.
- OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN, OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN이 필요합니다. 그룹 ID는 숫자 형태의 Telegram 채팅 ID여야 합니다.
- 공유 풀링 자격 증명을 위해 --credential-source convex를 지원합니다. 기본적으로 환경 모드를 사용하거나, OPENCLAW_QA_CREDENTIAL_SOURCE=convex를 설정하여 풀링된 리스(lease)를 선택하세요.
- 시나리오 실패 시 0이 아닌 값으로 종료됩니다. 아티팩트를 유지하면서 실패 종료 코드를 피하려면 --allow-failures를 사용하세요.
- 동일한 비공개 그룹 내에 두 개의 서로 다른 봇이 필요하며, SUT 봇은 Telegram 사용자 이름을 노출해야 합니다.
- 안정적인 봇 간 관찰을 위해 @BotFather에서 두 봇 모두에 대해 Bot-to-Bot 통신 모드를 활성화하고, 드라이버 봇이 그룹 봇 트래픽을 관찰할 수 있는지 확인하세요.
- Telegram QA 리포트, 요약, 관찰된 메시지 아티팩트를 .artifacts/qa-e2e/... 아래에 작성합니다.

라이브 전송 레인은 새로운 전송이 분기되지 않도록 하나의 표준 계약을 공유합니다.

테스트 스위트 (실행 위치)

테스트 스위트는 “현실성 증가”(및 불안정성/비용 증가) 순서로 생각하면 됩니다.

단위 / 통합 (기본값)

명령어: pnpm test
설정: 기존 스코프된 Vitest 프로젝트에 걸쳐 10개의 순차적 샤드 실행(vitest.full-*.config.ts)
파일: src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts 아래의 코어/단위 인벤토리 및 vitest.unit.config.ts가 다루는 화이트리스트된 ui Node.js 테스트
범위:
- 순수 단위 테스트
- 프로세스 내 통합 테스트(Gateway 인증, 라우팅, 도구, 파싱, 설정)
- 알려진 버그에 대한 결정론적 회귀 테스트
기대 사항:
- CI에서 실행
- 실제 키 필요 없음
- 빠르고 안정적이어야 함

E2E (Gateway 스모크)

명령어: pnpm test:e2e
설정: vitest.e2e.config.ts
파일: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
런타임 기본값:
- 리포지토리의 나머지 부분과 일치하도록 isolate: false와 함께 Vitest threads를 사용합니다.
- 적응형 워커를 사용합니다(CI: 최대 2개, 로컬: 기본 1개).
- 콘솔 I/O 오버헤드를 줄이기 위해 기본적으로 조용한 모드에서 실행됩니다.
범위:
- 다중 인스턴스 Gateway 엔드투엔드 동작
- WebSocket/HTTP 표면, 노드 페어링 및 더 무거운 네트워킹

E2E: OpenShell 백엔드 스모크

명령어: pnpm test:e2e:openshell
파일: test/openshell-sandbox.e2e.test.ts
범위:
- Docker를 통해 호스트에서 격리된 OpenShell Gateway 시작
- 임시 로컬 Dockerfile에서 샌드박스 생성
- 실제 sandbox ssh-config + SSH exec를 통해 OpenClaw의 OpenShell 백엔드 실행
- 샌드박스 fs 브리지를 통해 원격 정규 파일 시스템 동작 검증

라이브 (실제 제공자 + 실제 모델)

명령어: pnpm test:live
설정: vitest.live.config.ts
파일: src/**/*.live.test.ts
기본값: pnpm test:live에 의해 활성화됨(OPENCLAW_LIVE_TEST=1 설정)
범위:
- “이 제공자/모델이 실제 자격 증명으로 오늘 실제로 작동하는가?”
- 제공자 형식 변경, 도구 호출 특이 사항, 인증 문제 및 속도 제한 동작 포착
기대 사항:
- 설계상 CI 안정적이지 않음(실제 네트워크, 제공자 정책, 할당량, 중단)
- 비용 발생 / 속도 제한 사용
- “전체” 실행보다는 범위를 좁혀 실행하는 것을 권장

어떤 스위트를 실행해야 하나요?

다음 결정 표를 사용하세요:

로직/테스트 편집: pnpm test 실행 (많이 변경했다면 pnpm test:coverage)
Gateway 네트워킹 / WS 프로토콜 / 페어링 수정: pnpm test:e2e 추가
“봇이 다운됨” 디버깅 / 제공자별 실패 / 도구 호출: 범위를 좁힌 pnpm test:live 실행

AI Setup Assistant

실시간: Android 노드 기능 스윕

이 테스트는 연결된 Android 노드가 광고하는 모든 명령어를 호출하여 명령어 계약이 올바르게 작동하는지 확인합니다. OpenClaw Android 노드 기능을 검증하는 데 사용하세요.

테스트: src/gateway/android-node.capabilities.live.test.ts
스크립트: pnpm android:test:integration
목표: 연결된 Android 노드가 광고하는 모든 명령어를 호출하고 명령어 계약 동작을 확인합니다.
범위:
- 사전 조건/수동 설정(이 테스트 스위트는 앱을 설치/실행/페어링하지 않습니다).
- 선택된 Android 노드에 대한 명령어별 Gateway node.invoke 검증.
필수 사전 설정:
- Android 앱이 이미 Gateway에 연결 및 페어링되어 있어야 합니다.
- 앱이 포그라운드 상태여야 합니다.
- 통과를 기대하는 기능에 대한 권한/캡처 동의가 부여되어야 합니다.
선택적 대상 재정의:
- OPENCLAW_ANDROID_NODE_ID 또는 OPENCLAW_ANDROID_NODE_NAME.
- OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
전체 Android 설정 세부 정보: Android App

실시간: 모델 스모크 테스트 (프로필 키)

실시간 테스트는 실패 지점을 격리하기 위해 두 개의 계층으로 나뉩니다. OpenClaw 모델 프로필 및 API 키 유효성을 검증하는 데 최적화되어 있습니다.

“Direct model”은 제공자/모델이 주어진 키로 응답할 수 있는지 확인합니다.
“Gateway smoke”는 해당 모델에 대한 전체 Gateway+에이전트 파이프라인(세션, 기록, 도구, 샌드박스 정책 등)이 작동하는지 확인합니다.

계층 1: 직접 모델 완료 (Gateway 없음)

테스트: src/agents/models.profiles.live.test.ts
목표:
- 발견된 모델 열거
- getApiKeyForModel을 사용하여 자격 증명이 있는 모델 선택
- 모델별로 작은 완료 테스트 실행(필요한 경우 대상 회귀 테스트 포함)
활성화 방법:
- pnpm test:live (또는 Vitest를 직접 호출하는 경우 OPENCLAW_LIVE_TEST=1)
OPENCLAW_LIVE_MODELS=modern(또는 modern의 별칭인 all)을 설정하여 이 스위트를 실행합니다. 그렇지 않으면 pnpm test:live가 Gateway 스모크 테스트에 집중하도록 건너뜁니다.
모델 선택 방법:
- OPENCLAW_LIVE_MODELS=modern을 사용하여 최신 허용 목록(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)을 실행합니다.
- OPENCLAW_LIVE_MODELS=all은 최신 허용 목록의 별칭입니다.
- 또는 OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (쉼표로 구분된 허용 목록)
- 최신/전체 스윕은 기본적으로 선별된 고신호 캡을 사용합니다. 철저한 최신 스윕을 원하면 OPENCLAW_LIVE_MAX_MODELS=0으로 설정하거나, 더 작은 캡을 원하면 양수를 설정하세요.
제공자 선택 방법:
- OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (쉼표로 구분된 허용 목록)
키 출처:
- 기본값: 프로필 저장소 및 환경 변수 폴백
- 프로필 저장소만 강제하려면 OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1을 설정하세요.
존재 이유:
- “제공자 API가 깨짐 / 키가 유효하지 않음”과 “Gateway 에이전트 파이프라인이 깨짐”을 분리합니다.
- 작고 격리된 회귀 테스트를 포함합니다(예: OpenAI 응답/Codex 응답 추론 재생 + 도구 호출 흐름).

계층 2: Gateway + 개발 에이전트 스모크 (실제 “@openclaw” 동작)

테스트: src/gateway/gateway-models.profiles.live.test.ts
목표:
- 프로세스 내 Gateway 가동
- agent:dev:* 세션 생성/패치 (실행당 모델 재정의)
- 키가 있는 모델을 반복하며 다음을 확인:
  - “의미 있는” 응답(도구 없음)
  - 실제 도구 호출 작동(read 프로브)
  - 선택적 추가 도구 프로브(exec+read 프로브)
  - OpenAI 회귀 경로(도구 호출 전용 → 후속 조치)가 계속 작동하는지 확인
프로브 세부 정보(실패를 빠르게 설명하기 위함):
- read 프로브: 테스트가 작업 공간에 nonce 파일을 작성하고 에이전트에게 read를 요청하여 nonce를 다시 에코하도록 합니다.
- exec+read 프로브: 테스트가 에이전트에게 exec를 통해 임시 파일에 nonce를 작성하게 한 다음 read로 다시 읽도록 합니다.
- 이미지 프로브: 테스트가 생성된 PNG(고양이 + 무작위 코드)를 첨부하고 모델이 cat <CODE>를 반환할 것으로 기대합니다.
- 구현 참조: src/gateway/gateway-models.profiles.live.test.ts 및 src/gateway/live-image-probe.ts.
활성화 방법:
- pnpm test:live (또는 Vitest를 직접 호출하는 경우 OPENCLAW_LIVE_TEST=1)
모델 선택 방법:
- 기본값: 최신 허용 목록(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
- OPENCLAW_LIVE_GATEWAY_MODELS=all은 최신 허용 목록의 별칭입니다.
- 또는 OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (또는 쉼표 목록)을 설정하여 좁힙니다.
- 최신/전체 Gateway 스윕은 기본적으로 선별된 고신호 캡을 사용합니다. 철저한 최신 스윕을 원하면 OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0으로 설정하거나, 더 작은 캡을 원하면 양수를 설정하세요.
제공자 선택 방법 (“OpenRouter everything” 방지):
- OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (쉼표로 구분된 허용 목록)
도구 + 이미지 프로브는 이 실시간 테스트에서 항상 켜져 있습니다:
- read 프로브 + exec+read 프로브 (도구 스트레스)
- 모델이 이미지 입력 지원을 광고할 때 이미지 프로브 실행
- 흐름 (상위 수준):
  - 테스트가 “CAT” + 무작위 코드가 포함된 작은 PNG를 생성합니다(src/gateway/live-image-probe.ts).
  - agent attachments: [{ mimeType: "image/png", content: "<base64>" }]를 통해 전송합니다.
  - Gateway가 첨부 파일을 images[]로 파싱합니다(src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts).
  - 임베디드 에이전트가 멀티모달 사용자 메시지를 모델로 전달합니다.
  - 단언: 응답에 cat + 코드가 포함되어야 합니다(OCR 허용 오차: 사소한 실수 허용).

팁: 머신에서 테스트할 수 있는 항목(및 정확한 provider/model ID)을 확인하려면 다음을 실행하세요:

openclaw models list
openclaw models list --json

실시간: CLI 백엔드 스모크 (Claude, Codex, Gemini 또는 기타 로컬 CLI)

이 테스트는 기본 설정을 건드리지 않고 로컬 CLI 백엔드를 사용하여 Gateway + 에이전트 파이프라인을 검증합니다. OpenClaw의 CLI 통합 기능을 테스트하는 데 유용합니다.

테스트: src/gateway/gateway-cli-backend.live.test.ts
목표: 기본 설정을 건드리지 않고 로컬 CLI 백엔드를 사용하여 Gateway + 에이전트 파이프라인을 검증합니다.
백엔드별 스모크 기본값은 소유 확장 프로그램의 cli-backend.ts 정의와 함께 유지됩니다.
활성화:
- pnpm test:live (또는 Vitest를 직접 호출하는 경우 OPENCLAW_LIVE_TEST=1)
- OPENCLAW_LIVE_CLI_BACKEND=1
기본값:
- 기본 제공자/모델: claude-cli/claude-sonnet-4-6
- 명령어/인수/이미지 동작은 소유 CLI 백엔드 플러그인 메타데이터에서 가져옵니다.
재정의 (선택 사항):
- OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
- OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"
- OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 (실제 이미지 첨부 전송, 경로는 프롬프트에 주입됨)
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" (이미지 파일 경로를 프롬프트 주입 대신 CLI 인수로 전달)
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (또는 "list", IMAGE_ARG 설정 시 이미지 인수 전달 방식 제어)
- OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 (두 번째 턴을 보내고 재개 흐름 검증)
- OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0 (기본 Claude Sonnet → Opus 동일 세션 연속성 프로브 비활성화, 선택한 모델이 전환 대상을 지원할 때 강제로 켜려면 1로 설정)

예시:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Docker 레시피:

pnpm test:docker:live-cli-backend

단일 제공자 Docker 레시피:

pnpm test:docker:live-cli-backend:claude
pnpm test:docker:live-cli-backend:claude-subscription
pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini

참고:

Docker 러너는 scripts/test-live-cli-backend-docker.sh에 있습니다.
리포지토리 Docker 이미지 내에서 루트가 아닌 node 사용자로 실시간 CLI 백엔드 스모크를 실행합니다.
소유 확장 프로그램에서 CLI 스모크 메타데이터를 확인한 다음, 일치하는 Linux CLI 패키지(@anthropic-ai/claude-code, @openai/codex 또는 @google/gemini-cli)를 OPENCLAW_DOCKER_CLI_TOOLS_DIR(기본값: ~/.cache/openclaw/docker-cli-tools)의 캐시된 쓰기 가능 접두사에 설치합니다.
pnpm test:docker:live-cli-backend:claude-subscription은 ~/.claude/.credentials.json의 claudeAiOauth.subscriptionType 또는 claude setup-token에서 얻은 CLAUDE_CODE_OAUTH_TOKEN을 통해 휴대용 Claude Code 구독 OAuth가 필요합니다. 먼저 Docker에서 직접 claude -p를 증명한 다음, Anthropic API 키 환경 변수를 보존하지 않고 두 번의 Gateway CLI 백엔드 턴을 실행합니다. 이 구독 차선은 Claude가 현재 타사 앱 사용을 일반 구독 플랜 제한 대신 추가 사용량 청구를 통해 라우팅하기 때문에 기본적으로 Claude MCP/도구 및 이미지 프로브를 비활성화합니다.
실시간 CLI 백엔드 스모크는 이제 Claude, Codex, Gemini에 대해 동일한 엔드투엔드 흐름(텍스트 턴, 이미지 분류 턴, Gateway CLI를 통해 검증된 MCP cron 도구 호출)을 수행합니다.
Claude의 기본 스모크는 또한 세션을 Sonnet에서 Opus로 패치하고 재개된 세션이 이전 메모를 기억하는지 확인합니다.

실시간: ACP 바인드 스모크 (`/acp spawn ... --bind here`)

이 테스트는 실시간 ACP 에이전트와 함께 실제 ACP 대화 바인드 흐름을 검증합니다. OpenClaw의 ACP 통합 기능을 테스트하는 데 사용하세요.

테스트: src/gateway/gateway-acp-bind.live.test.ts
목표: 실시간 ACP 에이전트와 함께 실제 ACP 대화 바인드 흐름을 검증합니다:
- /acp spawn <agent> --bind here 전송
- 제자리에서 합성 메시지 채널 대화 바인딩
- 동일한 대화에서 일반 후속 조치 전송
- 후속 조치가 바인딩된 ACP 세션 기록에 도달하는지 확인
활성화:
- pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
- OPENCLAW_LIVE_ACP_BIND=1
기본값:
- Docker의 ACP 에이전트: claude,codex,gemini
- 직접 pnpm test:live ...를 위한 ACP 에이전트: claude
- 합성 채널: Slack DM 스타일 대화 컨텍스트
- ACP 백엔드: acpx
재정의:
- OPENCLAW_LIVE_ACP_BIND_AGENT=claude
- OPENCLAW_LIVE_ACP_BIND_AGENT=codex
- OPENCLAW_LIVE_ACP_BIND_AGENT=gemini
- OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini
- OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'
참고:
- 이 차선은 Gateway chat.send 표면을 관리자 전용 합성 발신 경로 필드와 함께 사용하여 테스트가 외부 전달을 가장하지 않고 메시지 채널 컨텍스트를 첨부할 수 있도록 합니다.
- OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND가 설정되지 않은 경우, 테스트는 선택된 ACP 하네스 에이전트에 대해 임베디드 acpx 플러그인의 내장 에이전트 레지스트리를 사용합니다.

예시:

OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts

Docker 레시피:

pnpm test:docker:live-acp-bind

단일 에이전트 Docker 레시피:

pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini

Docker 참고:

Docker 러너는 scripts/test-live-acp-bind-docker.sh에 있습니다.
기본적으로 지원되는 모든 실시간 CLI 에이전트(claude, codex, gemini)에 대해 순차적으로 ACP 바인드 스모크를 실행합니다.
매트릭스를 좁히려면 OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex 또는 OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini를 사용하세요.
~/.profile을 소싱하고, 일치하는 CLI 인증 자료를 컨테이너에 스테이징하고, acpx를 쓰기 가능한 npm 접두사에 설치한 다음, 누락된 경우 요청된 실시간 CLI(@anthropic-ai/claude-code, @openai/codex 또는 @google/gemini-cli)를 설치합니다.
Docker 내부에서 러너는 OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx를 설정하여 acpx가 소싱된 프로필의 제공자 환경 변수를 자식 하네스 CLI에서 사용할 수 있도록 합니다.

AI Setup Assistant

Live: Codex app-server harness smoke

이 테스트는 일반적인 Gateway를 통해 플러그인 소유의 Codex 하네스를 검증하는 것을 목표로 합니다.

agent 메서드:
- 번들로 제공되는 codex 플러그인을 로드합니다.
- OPENCLAW_AGENT_RUNTIME=codex를 선택합니다.
- 첫 번째 Gateway 에이전트 턴을 codex/gpt-5.4로 보냅니다.
- 동일한 OpenClaw 세션으로 두 번째 턴을 보내 app-server 스레드가 재개되는지 확인합니다.
- 동일한 Gateway 명령 경로를 통해 /codex status 및 /codex models를 실행합니다.
테스트: src/gateway/gateway-codex-harness.live.test.ts
활성화: OPENCLAW_LIVE_CODEX_HARNESS=1
기본 모델: codex/gpt-5.4
선택적 이미지 프로브: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
선택적 MCP/도구 프로브: OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
이 스모크 테스트는 OPENCLAW_AGENT_HARNESS_FALLBACK=none을 설정하여, 손상된 Codex 하네스가 PI로 조용히 대체되는 것을 방지합니다.
인증: 쉘/프로필의 OPENAI_API_KEY와 선택적으로 복사된 ~/.codex/auth.json 및 ~/.codex/config.toml을 사용합니다.

로컬 레시피:

source ~/.profile
OPENCLAW_LIVE_CODEX_HARNESS=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts

Docker 레시피:

source ~/.profile
pnpm test:docker:live-codex-harness

Docker 참고 사항:

Docker 러너는 scripts/test-live-codex-harness-docker.sh에 위치합니다.
마운트된 ~/.profile을 소싱하고, OPENAI_API_KEY를 전달하며, 존재할 경우 Codex CLI 인증 파일을 복사하고, 쓰기 가능한 마운트된 npm 프리픽스에 @openai/codex를 설치한 뒤, 소스 트리를 스테이징하고 Codex 하네스 라이브 테스트만 실행합니다.
Docker는 기본적으로 이미지 및 MCP/도구 프로브를 활성화합니다. 더 좁은 범위의 디버그 실행이 필요할 때는 OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 또는 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0을 설정하세요.
Docker는 또한 OPENCLAW_AGENT_HARNESS_FALLBACK=none을 내보내어, 라이브 테스트 설정과 일치시켜 openai-codex/* 또는 PI 폴백이 Codex 하네스 회귀를 숨기지 못하도록 합니다.

Live: 모델 매트릭스 (커버리지 범위)

고정된 “CI 모델 목록”은 없지만(라이브 테스트는 옵트인 방식), 키가 있는 개발 머신에서 정기적으로 다루는 권장 모델들은 다음과 같습니다.

기준: 도구 호출 (읽기 + 선택적 실행)

공급자 제품군당 최소 하나를 선택하세요:

OpenAI: openai/gpt-5.4 (또는 openai/gpt-5.4-mini)
Anthropic: anthropic/claude-opus-4-6 (또는 anthropic/claude-sonnet-4-6)
Google: google/gemini-3-flash-preview (또는 google/gemini-3.1-pro-preview)
Z.AI (GLM): zai/glm-4.7
MiniMax: minimax/MiniMax-M2.7

추가 커버리지 (선택 사항):

xAI: xai/grok-4 (또는 최신 버전)
Mistral: mistral/… (활성화된 도구 사용 가능 모델 중 하나 선택)
Cerebras: cerebras/… (액세스 권한이 있는 경우)
LM Studio: lmstudio/… (로컬; 도구 호출은 API 모드에 따라 다름)

비전: 이미지 전송 (첨부 파일 → 멀티모달 메시지)

이미지 프로브를 테스트하려면 OPENCLAW_LIVE_GATEWAY_MODELS에 이미지 사용이 가능한 모델(Claude/Gemini/OpenAI 비전 지원 변형 등)을 최소 하나 포함하세요.

애그리게이터 / 대체 Gateway

키가 활성화되어 있다면 다음을 통한 테스트도 지원합니다:

OpenRouter: openrouter/... (수백 개의 모델; openclaw models scan을 사용하여 도구+이미지 사용 가능 후보를 찾으세요)
OpenCode: Zen용 opencode/... 및 Go용 opencode-go/... (OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY를 통한 인증)

라이브 매트릭스에 포함할 수 있는 추가 공급자(자격 증명/설정이 있는 경우):

내장: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
models.providers 경유 (사용자 지정 엔드포인트): minimax (클라우드/API), 그리고 모든 OpenAI/Anthropic 호환 프록시 (LM Studio, vLLM, LiteLLM 등)

팁: 문서에 “모든 모델”을 하드코딩하지 마세요. 공식 목록은 머신에서 discoverModels(...)가 반환하는 값과 사용 가능한 키에 따라 결정됩니다.

자격 증명 (절대 커밋하지 마세요)

라이브 테스트는 CLI와 동일한 방식으로 자격 증명을 검색합니다. 실질적인 의미는 다음과 같습니다:

CLI가 작동하면 라이브 테스트도 동일한 키를 찾을 수 있어야 합니다.
라이브 테스트에서 “no creds”라고 나오면 openclaw models list / 모델 선택을 디버그하는 것과 동일한 방식으로 디버그하세요.
에이전트별 인증 프로필: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (라이브 테스트에서 “profile keys”가 의미하는 바입니다)
구성: ~/.openclaw/openclaw.json (또는 OPENCLAW_CONFIG_PATH)
레거시 상태 디렉토리: ~/.openclaw/credentials/ (존재할 경우 스테이징된 라이브 홈으로 복사되지만, 기본 프로필 키 저장소는 아님)
로컬 라이브 실행은 기본적으로 활성 구성, 에이전트별 auth-profiles.json 파일, 레거시 credentials/ 및 지원되는 외부 CLI 인증 디렉토리를 임시 테스트 홈으로 복사합니다. 스테이징된 라이브 홈은 workspace/ 및 sandboxes/를 건너뛰며, agents.*.workspace / agentDir 경로 재정의는 제거되어 프로브가 실제 호스트 작업 공간에 영향을 주지 않도록 합니다.

환경 변수 키(예: ~/.profile에 내보낸 키)에 의존하려면 source ~/.profile 후에 로컬 테스트를 실행하거나 아래의 Docker 러너를 사용하세요(컨테이너에 ~/.profile을 마운트할 수 있습니다).

Deepgram 라이브 (오디오 전사)

테스트: src/media-understanding/providers/deepgram/audio.live.test.ts
활성화: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

AI Setup Assistant

BytePlus coding plan live

개발 중인 기능이 실제 환경에서 어떻게 동작하는지 확인하고 싶을 때가 있죠. OpenClaw BytePlus coding plan live 테스트를 통해 실제 API 연동 상태를 점검할 수 있습니다.

테스트 실행: src/agents/byteplus.live.test.ts
활성화: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
모델 오버라이드(선택 사항): BYTEPLUS_CODING_MODEL=ark-code-latest

BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts

ComfyUI workflow media live

OpenClaw ComfyUI workflow media live 기능을 사용하면 복잡한 미디어 처리 파이프라인을 검증할 수 있습니다. 워크플로우 제출이나 폴링, 다운로드 로직을 변경한 후 이 테스트를 활용해 보세요.

테스트 실행: extensions/comfy/comfy.live.test.ts
활성화: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
범위:
- 번들된 comfy 이미지, 비디오 및 music_generate 경로를 실행합니다.
- models.providers.comfy.<capability>가 설정되지 않은 기능은 건너뜁니다.
- comfy 워크플로우 제출, 폴링, 다운로드 또는 플러그인 등록을 변경한 후 유용합니다.

OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

Image generation live

OpenClaw image generation live 테스트는 등록된 모든 이미지 생성 공급자 플러그인을 체계적으로 검사합니다. 환경 변수와 API 키를 올바르게 로드하여 실제 환경에서의 동작을 보장합니다.

테스트 실행: src/image-generation/runtime.live.test.ts
명령어: pnpm test:live src/image-generation/runtime.live.test.ts
하네스: pnpm test:live:media image
범위:
- 등록된 모든 이미지 생성 공급자 플러그인을 열거합니다.
- 프로빙 전에 로그인 셸(~/.profile)에서 누락된 공급자 환경 변수를 로드합니다.
- 기본적으로 저장된 인증 프로필보다 라이브/환경 API 키를 우선 사용하여 auth-profiles.json의 오래된 키가 실제 셸 자격 증명을 가리지 않도록 합니다.
- 사용 가능한 인증/프로필/모델이 없는 공급자는 건너뜁니다.
- 공유 런타임 기능을 통해 표준 이미지 생성 변형을 실행합니다:
  - google:flash-generate
  - google:pro-generate
  - google:pro-edit
  - openai:default-generate
현재 포함된 공급자:
- openai
- google
옵션 좁히기:
- OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"
- OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"
- OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"
인증 동작 옵션:
- OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1을 설정하여 프로필 저장소 인증을 강제하고 환경 변수 오버라이드를 무시합니다.

pnpm test:live src/image-generation/runtime.live.test.ts

Music generation live

OpenClaw music generation live 테스트는 공유 음악 생성 공급자 경로를 검증합니다. Google과 MiniMax와 같은 다양한 공급자를 지원하며, 런타임 모드에 따라 유연하게 테스트를 수행합니다.

테스트 실행: extensions/music-generation-providers.live.test.ts
활성화: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
하네스: pnpm test:live:media music
범위:
- 공유 번들 음악 생성 공급자 경로를 실행합니다.
- 현재 Google 및 MiniMax를 지원합니다.
- 프로빙 전에 로그인 셸(~/.profile)에서 공급자 환경 변수를 로드합니다.
- 저장된 인증 프로필보다 라이브/환경 API 키를 우선 사용합니다.
- 사용 가능한 인증/프로필/모델이 없는 공급자는 건너뜁니다.
- 사용 가능한 경우 두 가지 런타임 모드를 모두 실행합니다:
  - 프롬프트 전용 입력을 사용하는 generate
  - 공급자가 capabilities.edit.enabled를 선언한 경우의 edit
- 현재 공유 범위:
  - google: generate, edit
  - minimax: generate
  - comfy: 별도의 Comfy 라이브 파일 사용
옵션 좁히기:
- OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
- OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
인증 동작 옵션:
- OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1을 설정하여 프로필 저장소 인증을 강제합니다.

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

Video generation live

OpenClaw video generation live 테스트는 실제 환경에서 비디오 생성 기능을 검증하기 위한 도구입니다. 이 테스트는 공유된 비디오 생성 provider 경로를 활용하여 안정적인 동작을 보장합니다.

테스트 실행: extensions/video-generation-providers.live.test.ts
활성화: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
하네스 실행: pnpm test:live:media video
범위:
- 공유된 번들 비디오 생성 provider 경로를 실행합니다.
- 기본적으로 릴리스 안전 스모크 경로를 사용합니다: 비 FAL provider, provider당 하나의 텍스트-투-비디오 요청, 1초짜리 lobster 프롬프트, 그리고 OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS(180000 기본값)에 따른 provider별 작업 제한을 적용합니다.
- provider 측 큐 지연 시간이 릴리스 시간에 영향을 줄 수 있으므로 기본적으로 FAL은 건너뜁니다. 명시적으로 실행하려면 --video-providers fal 또는 OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"을 전달하세요.
- 프로빙 전에 로그인 셸(~/.profile)에서 provider 환경 변수를 로드합니다.
- 기본적으로 저장된 인증 프로필보다 라이브/환경 API 키를 우선 사용하므로 auth-profiles.json의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않습니다.
- 사용 가능한 인증/프로필/모델이 없는 provider는 건너뜁니다.
- 기본적으로 generate만 실행합니다.
- OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1을 설정하면 사용 가능한 경우 선언된 변환 모드도 실행합니다:
  - provider가 capabilities.imageToVideo.enabled를 선언하고 선택된 provider/모델이 공유 스윕에서 버퍼 기반 로컬 이미지 입력을 허용할 때 imageToVideo를 실행합니다.
  - provider가 capabilities.videoToVideo.enabled를 선언하고 선택된 provider/모델이 공유 스윕에서 버퍼 기반 로컬 비디오 입력을 허용할 때 videoToVideo를 실행합니다.
- 공유 스윕에서 현재 선언되었으나 건너뛰는 imageToVideo provider:
  - vydra: 번들된 veo3는 텍스트 전용이며 번들된 kling은 원격 이미지 URL이 필요하기 때문입니다.
- provider별 Vydra 커버리지:
  - OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
  - 해당 파일은 veo3 텍스트-투-비디오와 기본적으로 원격 이미지 URL 픽스처를 사용하는 kling 레인을 실행합니다.
- 현재 videoToVideo 라이브 커버리지:
  - runway: 선택된 모델이 runway/gen4_aleph인 경우에만 실행됩니다.
- 공유 스윕에서 현재 선언되었으나 건너뛰는 videoToVideo provider:
  - alibaba, qwen, xai: 현재 원격 http(s) / MP4 참조 URL이 필요하기 때문입니다.
  - google: 현재 공유 Gemini/Veo 레인이 버퍼 기반 로컬 입력을 사용하며 해당 경로가 공유 스윕에서 허용되지 않기 때문입니다.
  - openai: 현재 공유 레인에 조직별 비디오 인페인트/리믹스 액세스 보장이 부족하기 때문입니다.
선택적 범위 축소:
- OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"
- OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"
- OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""를 설정하면 FAL을 포함한 모든 provider를 기본 스윕에 포함합니다.
- OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000을 설정하여 공격적인 스모크 실행을 위해 각 provider 작업 제한을 줄입니다.
선택적 인증 동작:
- OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1을 설정하여 프로필 저장소 인증을 강제하고 환경 변수 전용 재정의를 무시합니다.

Media live harness

Media live harness는 이미지, 음악, 비디오 라이브 테스트 스위트를 통합하여 관리할 수 있는 단일 진입점입니다. 이 도구를 사용하면 OpenClaw 환경에서 미디어 관련 기능을 효율적으로 테스트할 수 있습니다.

명령어: pnpm test:live:media
목적:
- 공유 이미지, 음악, 비디오 라이브 스위트를 하나의 리포지토리 네이티브 진입점을 통해 실행합니다.
- ~/.profile에서 누락된 provider 환경 변수를 자동으로 로드합니다.
- 기본적으로 현재 사용 가능한 인증이 있는 provider로 각 스위트를 자동으로 좁힙니다.
- scripts/test-live.mjs를 재사용하므로 하트비트 및 조용한 모드 동작이 일관되게 유지됩니다.
예시:
- pnpm test:live:media
- pnpm test:live:media image video --providers openai,google,minimax
- pnpm test:live:media video --video-providers openai,runway --all-providers
- pnpm test:live:media music --quiet

Docker 러너 (Linux 환경 확인용 선택 사항)

이 Docker 러너들은 크게 두 가지 범주로 나뉩니다.

라이브 모델 러너: test:docker:live-models와 test:docker:live-gateway는 리포지토리 Docker 이미지 내에서 해당 프로필 키와 일치하는 라이브 파일(src/agents/models.profiles.live.test.ts 및 src/gateway/gateway-models.profiles.live.test.ts)만 실행하며, 로컬 설정 디렉터리와 워크스페이스를 마운트합니다(마운트 시 ~/.profile도 소싱합니다). 대응하는 로컬 진입점은 test:docker:live-models 및 test:live:gateway-profiles입니다.
Docker 라이브 러너는 전체 Docker 스윕이 실용적으로 유지되도록 기본적으로 더 작은 스모크 캡을 사용합니다. test:docker:live-models는 기본적으로 OPENCLAW_LIVE_MAX_MODELS=12를 사용하며, test:docker:live-gateway는 기본적으로 OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000, OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000을 사용합니다. 더 큰 규모의 철저한 스캔이 필요할 때는 이 환경 변수들을 직접 재정의하세요.
test:docker:all은 test:docker:live-build를 통해 라이브 Docker 이미지를 한 번 빌드한 다음, 두 개의 라이브 Docker 레인에서 재사용합니다.
컨테이너 스모크 러너: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels, test:docker:plugins는 하나 이상의 실제 컨테이너를 부팅하여 상위 수준의 통합 경로를 검증합니다.

라이브 모델 Docker 러너는 필요한 CLI 인증 홈만 바인드 마운트하거나(범위가 좁혀지지 않은 경우 지원되는 모든 홈 마운트), 실행 전에 컨테이너 홈으로 복사하여 외부 CLI OAuth가 호스트 인증 저장소를 변경하지 않고도 토큰을 갱신할 수 있도록 합니다.

직접 모델: pnpm test:docker:live-models (스크립트: scripts/test-live-models-docker.sh)
ACP 바인드 스모크: pnpm test:docker:live-acp-bind (스크립트: scripts/test-live-acp-bind-docker.sh)
CLI 백엔드 스모크: pnpm test:docker:live-cli-backend (스크립트: scripts/test-live-cli-backend-docker.sh)
Codex 앱 서버 하네스 스모크: pnpm test:docker:live-codex-harness (스크립트: scripts/test-live-codex-harness-docker.sh)
Gateway + 개발 에이전트: pnpm test:docker:live-gateway (스크립트: scripts/test-live-gateway-models-docker.sh)
Open WebUI 라이브 스모크: pnpm test:docker:openwebui (스크립트: scripts/e2e/openwebui-docker.sh)
온보딩 마법사 (TTY, 전체 스캐폴딩): pnpm test:docker:onboard (스크립트: scripts/e2e/onboard-docker.sh)
Gateway 네트워킹 (컨테이너 2개, WS 인증 + 상태 확인): pnpm test:docker:gateway-network (스크립트: scripts/e2e/gateway-network-docker.sh)
MCP 채널 브리지 (시드된 Gateway + stdio 브리지 + 원시 Claude 알림 프레임 스모크): pnpm test:docker:mcp-channels (스크립트: scripts/e2e/mcp-channels-docker.sh)
플러그인 (설치 스모크 + /plugin 별칭 + Claude 번들 재시작 의미론): pnpm test:docker:plugins (스크립트: scripts/e2e/plugins-docker.sh)

라이브 모델 Docker 러너는 현재 체크아웃을 읽기 전용으로 바인드 마운트하고 컨테이너 내부의 임시 작업 디렉터리에 스테이징합니다. 이는 런타임 이미지를 가볍게 유지하면서도 정확한 로컬 소스/설정에 대해 Vitest를 실행할 수 있게 합니다. 스테이징 단계에서는 .pnpm-store, .worktrees, __openclaw_vitest__, 앱 로컬 .build 또는 Gradle 출력 디렉터리와 같은 대용량 로컬 전용 캐시 및 앱 빌드 결과물을 건너뛰어 Docker 라이브 실행 시 머신별 아티팩트를 복사하느라 시간을 낭비하지 않도록 합니다. 또한 OPENCLAW_SKIP_CHANNELS=1을 설정하여 Gateway 라이브 프로브가 컨테이너 내부에서 실제 Telegram/Discord 등의 채널 워커를 시작하지 않도록 합니다. test:docker:live-models는 여전히 pnpm test:live를 실행하므로, 해당 Docker 레인에서 Gateway 라이브 커버리지를 좁히거나 제외해야 할 때는 OPENCLAW_LIVE_GATEWAY_*를 함께 전달하세요. test:docker:openwebui는 상위 수준의 호환성 스모크 테스트입니다. OpenAI 호환 HTTP 엔드포인트가 활성화된 OpenClaw Gateway 컨테이너를 시작하고, 해당 Gateway에 고정된 Open WebUI 컨테이너를 실행한 뒤, Open WebUI를 통해 로그인하고 /api/models가 openclaw/default를 노출하는지 확인한 다음, Open WebUI의 /api/chat/completions 프록시를 통해 실제 채팅 요청을 보냅니다. 첫 실행은 Docker가 Open WebUI 이미지를 가져오거나 Open WebUI가 자체 콜드 스타트 설정을 완료해야 하므로 눈에 띄게 느릴 수 있습니다. 이 레인은 사용 가능한 라이브 모델 키를 필요로 하며, OPENCLAW_PROFILE_FILE(~/.profile 기본값)이 Docker 실행 시 이를 제공하는 주요 방법입니다. 성공적으로 실행되면 { "ok": true, "model": "openclaw/default", ... }와 같은 작은 JSON 페이로드가 출력됩니다. test:docker:mcp-channels는 의도적으로 결정론적이며 실제 Telegram, Discord 또는 iMessage 계정이 필요하지 않습니다. 시드된 Gateway 컨테이너를 부팅하고 openclaw mcp serve를 생성하는 두 번째 컨테이너를 시작한 다음, 실제 stdio MCP 브리지를 통해 라우팅된 대화 검색, 트랜스크립트 읽기, 첨부 파일 메타데이터, 라이브 이벤트 큐 동작, 아웃바운드 전송 라우팅 및 Claude 스타일 채널 + 권한 알림을 검증합니다. 알림 확인은 원시 stdio MCP 프레임을 직접 검사하므로, 특정 클라이언트 SDK가 노출하는 내용뿐만 아니라 브리지가 실제로 방출하는 내용을 검증합니다.

수동 ACP 일반 언어 스레드 스모크 (CI 아님):

bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
이 스크립트는 회귀/디버그 워크플로를 위해 유지하세요. ACP 스레드 라우팅 검증을 위해 다시 필요할 수 있으므로 삭제하지 마세요.

유용한 환경 변수:

OPENCLAW_CONFIG_DIR=... (기본값: ~/.openclaw) /home/node/.openclaw에 마운트됨
OPENCLAW_WORKSPACE_DIR=... (기본값: ~/.openclaw/workspace) /home/node/.openclaw/workspace에 마운트됨
OPENCLAW_PROFILE_FILE=... (기본값: ~/.profile) /home/node/.profile에 마운트되고 테스트 실행 전 소싱됨
OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1은 OPENCLAW_PROFILE_FILE에서 소싱된 환경 변수만 확인하며, 임시 설정/워크스페이스 디렉터리를 사용하고 외부 CLI 인증 마운트를 사용하지 않음
OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (기본값: ~/.cache/openclaw/docker-cli-tools) Docker 내부의 캐시된 CLI 설치를 위해 /home/node/.npm-global에 마운트됨
$HOME 아래의 외부 CLI 인증 디렉터리/파일은 /host-auth... 아래에 읽기 전용으로 마운트된 후 테스트 시작 전 /home/node/...로 복사됨
- 기본 디렉터리: .minimax
- 기본 파일: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
- 좁혀진 공급자 실행은 OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS에서 추론된 필요한 디렉터리/파일만 마운트함
- OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none 또는 쉼표로 구분된 목록(예: OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex)으로 수동 재정의 가능
OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... 실행 범위를 좁힘
OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... 컨테이너 내 공급자 필터링
OPENCLAW_SKIP_DOCKER_BUILD=1 재빌드가 필요 없는 재실행을 위해 기존 openclaw:local-live 이미지 재사용
OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 자격 증명이 프로필 저장소에서 오도록 보장(환경 변수 아님)
OPENCLAW_OPENWEBUI_MODEL=... Open WebUI 스모크를 위해 Gateway가 노출할 모델 선택
OPENCLAW_OPENWEBUI_PROMPT=... Open WebUI 스모크에서 사용하는 nonce-check 프롬프트 재정의
OPENWEBUI_IMAGE=... 고정된 Open WebUI 이미지 태그 재정의

문서 상태 확인

문서 수정 후 문서 검사를 실행하세요: pnpm check:docs. 페이지 내 제목 확인도 필요한 경우 전체 Mintlify 앵커 유효성 검사를 실행하세요: pnpm docs:check-links:anchors.

AI Setup Assistant

오프라인 회귀 테스트 (CI-safe)

이 테스트들은 실제 외부 제공자 없이도 실제 파이프라인과 동일하게 동작하는 회귀 테스트입니다.

Gateway 도구 호출 (Mock OpenAI, 실제 Gateway + 에이전트 루프): src/gateway/gateway.test.ts (케이스: “runs a mock OpenAI tool call end-to-end via gateway agent loop”)
Gateway 마법사 (WS wizard.start/wizard.next, 설정 작성 및 인증 강제): src/gateway/gateway.test.ts (케이스: “runs wizard over ws and writes auth token config”)

src/gateway/gateway.test.ts

에이전트 신뢰성 평가 (Skills)

이미 “에이전트 신뢰성 평가”와 유사하게 동작하는 몇 가지 CI-safe 테스트가 준비되어 있습니다.

실제 Gateway + 에이전트 루프를 통한 Mock 도구 호출 (src/gateway/gateway.test.ts).
세션 연결 및 설정 효과를 검증하는 엔드투엔드 마법사 흐름 (src/gateway/gateway.test.ts).

OpenClaw의 스킬(참고: Skills) 기능에서 아직 부족한 부분은 다음과 같습니다:

의사결정(Decisioning): 프롬프트에 스킬이 나열될 때, 에이전트가 올바른 스킬을 선택하는지(또는 관련 없는 스킬을 피하는지) 확인해야 합니다.
규정 준수(Compliance): 에이전트가 사용 전 SKILL.md를 읽고 필수 단계나 인자를 따르는지 확인해야 합니다.
워크플로우 계약(Workflow contracts): 도구 순서, 세션 기록 유지, 샌드박스 경계를 검증하는 다중 턴 시나리오가 필요합니다.

향후 평가는 결정론적 방식을 우선시해야 합니다:

Mock 제공자를 사용하여 도구 호출 및 순서, 스킬 파일 읽기, 세션 연결을 검증하는 시나리오 러너.
스킬 중심의 소규모 시나리오 모음 (사용 vs 회피, 게이팅, 프롬프트 인젝션).
CI-safe 테스트 모음이 구축된 후에만 선택적으로 실행 가능한 라이브 평가.

Contract tests (plugin and channel shape)

Contract tests는 등록된 모든 플러그인과 채널이 인터페이스 계약을 준수하는지 확인하는 역할을 합니다. 이 테스트들은 발견된 모든 플러그인을 순회하며 형태와 동작에 대한 일련의 검증을 수행합니다. 기본 pnpm test 유닛 테스트 단계에서는 공유되는 seam 및 smoke 파일을 의도적으로 건너뛰므로, 채널이나 제공자 인터페이스를 수정할 때는 contract 명령어를 직접 실행해야 합니다.

Commands

모든 계약 테스트: pnpm test:contracts
채널 계약 테스트 전용: pnpm test:contracts:channels
제공자 계약 테스트 전용: pnpm test:contracts:plugins

Channel contracts

src/channels/plugins/contracts/*.contract.test.ts 경로에 위치하며 다음 항목들을 검증합니다:

plugin - 기본 플러그인 형태 (id, name, capabilities)
setup - 설정 마법사 계약
session-binding - 세션 바인딩 동작
outbound-payload - 메시지 페이로드 구조
inbound - 인바운드 메시지 처리
actions - 채널 액션 핸들러
threading - 스레드 ID 처리
directory - 디렉토리/로스터 API
group-policy - 그룹 정책 적용

Provider status contracts

src/plugins/contracts/*.contract.test.ts 경로에 위치하며 다음 항목들을 검증합니다:

status - 채널 상태 프로브
registry - 플러그인 레지스트리 형태

Provider contracts

src/plugins/contracts/*.contract.test.ts 경로에 위치하며 다음 항목들을 검증합니다:

auth - 인증 흐름 계약
auth-choice - 인증 선택
catalog - 모델 카탈로그 API
discovery - 플러그인 발견
loader - 플러그인 로딩
runtime - 제공자 런타임
shape - 플러그인 형태/인터페이스
wizard - 설정 마법사

When to run

플러그인 SDK 내보내기나 하위 경로를 변경한 후
채널 또는 제공자 플러그인을 추가하거나 수정한 후
플러그인 등록 또는 발견 로직을 리팩토링한 후

Contract tests는 GitHub CI 환경에서 실행되며 실제 API 키를 요구하지 않습니다.

Adding regressions (guidance)

실제 환경에서 발견된 제공자나 모델 문제를 해결할 때는 다음과 같은 가이드를 따르세요.

가능하다면 CI 환경에서 안전하게 실행 가능한 회귀 테스트를 추가하세요 (제공자 모킹/스텁 사용, 또는 정확한 요청 형태 변환 캡처).
속도 제한이나 인증 정책처럼 실제 환경에서만 발생하는 문제라면, 테스트 범위를 좁게 유지하고 환경 변수를 통해 선택적으로 실행되도록 하세요.
버그를 잡아낼 수 있는 가장 작은 계층을 타겟팅하는 것이 좋습니다:
- 제공자 요청 변환/재생 버그 → 직접 모델 테스트
- Gateway 세션/기록/도구 파이프라인 버그 → Gateway 라이브 smoke 테스트 또는 CI 환경에서 안전한 Gateway 모의 테스트
SecretRef 순회 가드레일:
- src/secrets/exec-secret-ref-id-parity.test.ts는 레지스트리 메타데이터(listSecretTargetRegistryEntries())에서 SecretRef 클래스당 하나의 샘플 타겟을 추출한 뒤, 순회 세그먼트 실행 ID가 거부되는지 확인합니다.
- src/secrets/target-registry-data.ts에 새로운 includeInPlan SecretRef 타겟 제품군을 추가하는 경우, 해당 테스트의 classifyTargetClass를 업데이트하세요. 이 테스트는 분류되지 않은 타겟 ID에 대해 의도적으로 실패를 발생시켜 새로운 클래스가 실수로 누락되는 것을 방지합니다.

pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

OpenClaw 테스트 가이드: 단위부터 라이브 테스트까지

빠른 시작

QA 전용 러너

테스트 스위트 (실행 위치)

단위 / 통합 (기본값)

E2E (Gateway 스모크)

E2E: OpenShell 백엔드 스모크

라이브 (실제 제공자 + 실제 모델)

어떤 스위트를 실행해야 하나요?

실시간: Android 노드 기능 스윕

실시간: 모델 스모크 테스트 (프로필 키)

계층 1: 직접 모델 완료 (Gateway 없음)

계층 2: Gateway + 개발 에이전트 스모크 (실제 “@openclaw” 동작)

실시간: CLI 백엔드 스모크 (Claude, Codex, Gemini 또는 기타 로컬 CLI)

실시간: ACP 바인드 스모크 (/acp spawn ... --bind here)

Live: Codex app-server harness smoke

Live: 모델 매트릭스 (커버리지 범위)

최신 스모크 세트 (도구 호출 + 이미지)

기준: 도구 호출 (읽기 + 선택적 실행)

비전: 이미지 전송 (첨부 파일 → 멀티모달 메시지)

애그리게이터 / 대체 Gateway

자격 증명 (절대 커밋하지 마세요)

Deepgram 라이브 (오디오 전사)

BytePlus coding plan live

ComfyUI workflow media live

Image generation live

Music generation live

Video generation live

Media live harness

Docker 러너 (Linux 환경 확인용 선택 사항)

문서 상태 확인

오프라인 회귀 테스트 (CI-safe)

에이전트 신뢰성 평가 (Skills)

Contract tests (plugin and channel shape)

Commands

Channel contracts

Provider status contracts

Provider contracts

When to run

Adding regressions (guidance)

아직 막혀 있나요?

실시간: ACP 바인드 스모크 (`/acp spawn ... --bind here`)