Langsung ke konten utama

​
Pengujian

OpenClaw memiliki tiga suite Vitest (unit/integrasi, e2e, live) dan sekumpulan kecil runner Docker. Dokumen ini adalah panduan “cara kami menguji”:
  • Apa saja yang dicakup setiap suite (dan apa yang secara sengaja tidak dicakup)
  • Perintah mana yang dijalankan untuk alur kerja umum (lokal, sebelum push, debugging)
  • Bagaimana pengujian live menemukan kredensial dan memilih model/penyedia
  • Cara menambahkan regresi untuk masalah model/penyedia di dunia nyata

​
Mulai cepat

Pada kebanyakan hari:
  • Gate penuh (diharapkan sebelum push): pnpm build && pnpm check && pnpm test
  • Menjalankan suite penuh lokal yang lebih cepat di mesin yang lapang: pnpm test:max
  • Loop watch Vitest langsung (konfigurasi proyek modern): pnpm test:watch
  • Penargetan file langsung sekarang juga merutekan path extension/channel: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
Saat Anda menyentuh pengujian atau ingin keyakinan ekstra:
  • Gate cakupan: pnpm test:coverage
  • Suite E2E: pnpm test:e2e
Saat men-debug penyedia/model nyata (memerlukan kredensial nyata):
  • Suite live (probe model + alat/gambar gateway): pnpm test:live
  • Targetkan satu file live secara senyap: pnpm test:live -- src/agents/models.profiles.live.test.ts
Tip: saat Anda hanya memerlukan satu kasus gagal, sebaiknya persempit pengujian live melalui variabel env allowlist yang dijelaskan di bawah.

​
Suite pengujian (apa yang berjalan di mana)

Anggap suite ini sebagai “tingkat realisme yang makin tinggi” (dan semakin rentan gagal/mahal):

​
Unit / integrasi (default)

  • Perintah: pnpm test
  • Konfigurasi: Vitest projects native melalui vitest.config.ts
  • File: inventaris inti/unit di src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts, dan pengujian node ui yang masuk allowlist dan dicakup oleh vitest.unit.config.ts
  • Cakupan:
    • Pengujian unit murni
    • Pengujian integrasi in-process (auth gateway, routing, tooling, parsing, konfigurasi)
    • Regresi deterministik untuk bug yang diketahui
  • Ekspektasi:
    • Berjalan di CI
    • Tidak memerlukan kunci nyata
    • Harus cepat dan stabil
  • Catatan proyek:
    • pnpm test, pnpm test:watch, dan pnpm test:changed sekarang semuanya menggunakan konfigurasi root projects Vitest native yang sama.
    • Filter file langsung dirutekan secara native melalui graf proyek root, jadi pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts berfungsi tanpa wrapper khusus.
  • Catatan embedded runner:
    • Saat Anda mengubah input penemuan alat pesan atau konteks runtime compaction, pertahankan kedua tingkat cakupan.
    • Tambahkan regresi helper yang terfokus untuk batas routing/normalisasi murni.
    • Jaga juga suite integrasi embedded runner ini tetap sehat: src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts, dan src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
    • Suite tersebut memverifikasi bahwa scoped id dan perilaku compaction tetap mengalir melalui path run.ts / compact.ts yang nyata; pengujian helper saja bukan pengganti yang memadai untuk path integrasi tersebut.
  • Catatan pool:
    • Konfigurasi dasar Vitest sekarang menggunakan default threads.
    • Konfigurasi Vitest bersama juga menetapkan isolate: false dan menggunakan runner non-isolated di seluruh konfigurasi root project, e2e, dan live.
    • Jalur UI root mempertahankan setup jsdom dan optimizer-nya, tetapi sekarang juga berjalan pada runner non-isolated bersama.
    • pnpm test mewarisi default threads + isolate: false yang sama dari konfigurasi projects vitest.config.ts root.
    • Peluncur bersama scripts/run-vitest.mjs sekarang juga menambahkan --no-maglev untuk proses child Node Vitest secara default guna mengurangi churn kompilasi V8 saat menjalankan run lokal besar. Tetapkan OPENCLAW_VITEST_ENABLE_MAGLEV=1 jika Anda perlu membandingkan dengan perilaku V8 standar.
  • Catatan iterasi lokal cepat:
    • pnpm test:changed menjalankan konfigurasi proyek native dengan --changed origin/main.
    • pnpm test:max dan pnpm test:changed:max mempertahankan konfigurasi proyek native yang sama, hanya dengan batas worker yang lebih tinggi.
    • Auto-scaling worker lokal sekarang sengaja lebih konservatif dan juga mengurangi skala saat load average host sudah tinggi, sehingga beberapa run Vitest bersamaan secara default tidak terlalu merusak.
    • Konfigurasi dasar Vitest menandai file proyek/konfigurasi sebagai forceRerunTriggers agar rerun mode changed tetap benar ketika wiring pengujian berubah.
    • Konfigurasi mempertahankan OPENCLAW_VITEST_FS_MODULE_CACHE tetap aktif pada host yang didukung; tetapkan OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path jika Anda ingin satu lokasi cache eksplisit untuk profiling langsung.
  • Catatan debug performa:
    • pnpm test:perf:imports mengaktifkan pelaporan durasi import Vitest beserta output rincian import.
    • pnpm test:perf:imports:changed membatasi tampilan profiling yang sama ke file yang berubah sejak origin/main.
    • pnpm test:perf:profile:main menulis profil CPU thread utama untuk overhead startup dan transform Vitest/Vite.
    • pnpm test:perf:profile:runner menulis profil CPU+heap runner untuk suite unit dengan paralelisme file dinonaktifkan.

​
E2E (smoke gateway)

  • Perintah: pnpm test:e2e
  • Konfigurasi: vitest.e2e.config.ts
  • File: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
  • Default runtime:
    • Menggunakan Vitest threads dengan isolate: false, selaras dengan bagian repo lainnya.
    • Menggunakan worker adaptif (CI: hingga 2, lokal: default 1).
    • Berjalan dalam mode senyap secara default untuk mengurangi overhead I/O konsol.
  • Override yang berguna:
    • OPENCLAW_E2E_WORKERS=<n> untuk memaksa jumlah worker (dibatasi hingga 16).
    • OPENCLAW_E2E_VERBOSE=1 untuk mengaktifkan kembali output konsol verbose.
  • Cakupan:
    • Perilaku end-to-end gateway multi-instance
    • Permukaan WebSocket/HTTP, pairing node, dan jaringan yang lebih berat
  • Ekspektasi:
    • Berjalan di CI (saat diaktifkan di pipeline)
    • Tidak memerlukan kunci nyata
    • Lebih banyak bagian bergerak dibanding pengujian unit (bisa lebih lambat)

​
E2E: smoke backend OpenShell

  • Perintah: pnpm test:e2e:openshell
  • File: test/openshell-sandbox.e2e.test.ts
  • Cakupan:
    • Memulai gateway OpenShell terisolasi di host melalui Docker
    • Membuat sandbox dari Dockerfile lokal sementara
    • Menguji backend OpenShell OpenClaw melalui sandbox ssh-config + eksekusi SSH nyata
    • Memverifikasi perilaku filesystem kanonis-remote melalui bridge fs sandbox
  • Ekspektasi:
    • Hanya opt-in; bukan bagian dari run default pnpm test:e2e
    • Memerlukan CLI openshell lokal dan daemon Docker yang berfungsi
    • Menggunakan HOME / XDG_CONFIG_HOME terisolasi, lalu menghancurkan gateway pengujian dan sandbox
  • Override yang berguna:
    • OPENCLAW_E2E_OPENSHELL=1 untuk mengaktifkan pengujian saat menjalankan suite e2e yang lebih luas secara manual
    • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell untuk menunjuk ke biner CLI non-default atau skrip wrapper

​
Live (penyedia nyata + model nyata)

  • Perintah: pnpm test:live
  • Konfigurasi: vitest.live.config.ts
  • File: src/**/*.live.test.ts
  • Default: aktif oleh pnpm test:live (menetapkan OPENCLAW_LIVE_TEST=1)
  • Cakupan:
    • “Apakah penyedia/model ini benar-benar bekerja hari ini dengan kredensial nyata?”
    • Menangkap perubahan format penyedia, keanehan pemanggilan alat, masalah auth, dan perilaku rate limit
  • Ekspektasi:
    • Secara desain tidak stabil untuk CI (jaringan nyata, kebijakan penyedia nyata, kuota, gangguan)
    • Berbiaya / menggunakan rate limit
    • Sebaiknya jalankan subset yang dipersempit, bukan “semuanya”
  • Run live mengambil ~/.profile untuk mendapatkan kunci API yang hilang.
  • Secara default, run live tetap mengisolasi HOME dan menyalin materi config/auth ke home pengujian sementara agar fixture unit tidak dapat memodifikasi ~/.openclaw Anda yang nyata.
  • Tetapkan OPENCLAW_LIVE_USE_REAL_HOME=1 hanya jika Anda memang sengaja ingin pengujian live menggunakan direktori home nyata Anda.
  • pnpm test:live sekarang default ke mode yang lebih senyap: tetap menampilkan output progres [live] ..., tetapi menekan notifikasi ~/.profile tambahan dan membisukan log bootstrap gateway/chatter Bonjour. Tetapkan OPENCLAW_LIVE_TEST_QUIET=0 jika Anda ingin log startup lengkap kembali.
  • Rotasi API key (khusus penyedia): tetapkan *_API_KEYS dengan format koma/titik koma atau *_API_KEY_1, *_API_KEY_2 (misalnya OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) atau override per-live melalui OPENCLAW_LIVE_*_KEY; pengujian akan mencoba ulang pada respons rate limit.
  • Output progres/heartbeat:
    • Suite live sekarang memancarkan baris progres ke stderr agar pemanggilan penyedia yang lama terlihat aktif meskipun capture konsol Vitest senyap.
    • vitest.live.config.ts menonaktifkan intersepsi konsol Vitest agar baris progres penyedia/gateway langsung mengalir selama run live.
    • Atur heartbeat model langsung dengan OPENCLAW_LIVE_HEARTBEAT_MS.
    • Atur heartbeat gateway/probe dengan OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

​
Suite mana yang harus saya jalankan?

Gunakan tabel keputusan ini:
  • Mengedit logika/pengujian: jalankan pnpm test (dan pnpm test:coverage jika Anda banyak mengubah)
  • Menyentuh jaringan gateway / protokol WS / pairing: tambahkan pnpm test:e2e
  • Men-debug “bot saya mati” / kegagalan khusus penyedia / pemanggilan alat: jalankan pnpm test:live yang dipersempit

​
Live: sapuan kapabilitas node Android

  • Pengujian: src/gateway/android-node.capabilities.live.test.ts
  • Skrip: pnpm android:test:integration
  • Tujuan: memanggil setiap perintah yang saat ini diiklankan oleh node Android yang terhubung dan menegaskan perilaku kontrak perintah.
  • Cakupan:
    • Setup manual/prasyarat (suite ini tidak memasang/menjalankan/melakukan pairing aplikasi).
    • Validasi gateway node.invoke per perintah untuk node Android yang dipilih.
  • Pra-setup yang diperlukan:
    • Aplikasi Android sudah terhubung + dipairing ke gateway.
    • Aplikasi tetap berada di foreground.
    • Izin/persetujuan capture telah diberikan untuk kapabilitas yang Anda harapkan lolos.
  • Override target opsional:
    • OPENCLAW_ANDROID_NODE_ID atau OPENCLAW_ANDROID_NODE_NAME.
    • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
  • Detail setup Android lengkap: Aplikasi Android

​
Live: smoke model (kunci profil)

Pengujian live dibagi menjadi dua lapisan agar kita dapat mengisolasi kegagalan:
  • “Model langsung” memberi tahu kita apakah penyedia/model dapat menjawab sama sekali dengan kunci yang diberikan.
  • “Smoke gateway” memberi tahu kita apakah pipeline gateway+agen penuh berfungsi untuk model tersebut (sesi, riwayat, alat, kebijakan sandbox, dll.).

​
Lapisan 1: penyelesaian model langsung (tanpa gateway)

  • Pengujian: src/agents/models.profiles.live.test.ts
  • Tujuan:
    • Mengenumerasi model yang ditemukan
    • Menggunakan getApiKeyForModel untuk memilih model yang Anda punya kredensialnya
    • Menjalankan penyelesaian kecil per model (dan regresi terarah jika diperlukan)
  • Cara mengaktifkan:
    • pnpm test:live (atau OPENCLAW_LIVE_TEST=1 jika memanggil Vitest secara langsung)
  • Tetapkan OPENCLAW_LIVE_MODELS=modern (atau all, alias untuk modern) agar suite ini benar-benar berjalan; jika tidak, suite ini dilewati agar pnpm test:live tetap fokus pada smoke gateway
  • Cara memilih model:
    • OPENCLAW_LIVE_MODELS=modern untuk menjalankan allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
    • OPENCLAW_LIVE_MODELS=all adalah alias untuk allowlist modern
    • atau OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (allowlist dipisahkan koma)
  • Cara memilih penyedia:
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (allowlist dipisahkan koma)
  • Asal kunci:
    • Secara default: profile store dan fallback env
    • Tetapkan OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 untuk memaksa profile store saja
  • Mengapa ini ada:
    • Memisahkan “API penyedia rusak / kunci tidak valid” dari “pipeline agen gateway rusak”
    • Menampung regresi kecil dan terisolasi (contoh: replay reasoning + alur tool-call OpenAI Responses/Codex Responses)

​
Lapisan 2: smoke gateway + agen dev (apa yang sebenarnya dilakukan “@openclaw”)

  • Pengujian: src/gateway/gateway-models.profiles.live.test.ts
  • Tujuan:
    • Menjalankan gateway in-process
    • Membuat/menambal sesi agent:dev:* (override model per run)
    • Mengiterasi model-dengan-kunci dan menegaskan:
      • respons yang “bermakna” (tanpa alat)
      • pemanggilan alat nyata berfungsi (probe read)
      • probe alat ekstra opsional (probe exec+read)
      • path regresi OpenAI (tool-call-only → tindak lanjut) tetap berfungsi
  • Detail probe (agar Anda dapat menjelaskan kegagalan dengan cepat):
    • Probe read: pengujian menulis file nonce di workspace dan meminta agen untuk read file tersebut serta mengembalikan nonce.
    • Probe exec+read: pengujian meminta agen untuk menulis nonce ke file temp melalui exec, lalu read kembali.
    • Probe gambar: pengujian melampirkan PNG yang dibuat (kucing + kode acak) dan mengharapkan model mengembalikan cat <CODE>.
    • Referensi implementasi: src/gateway/gateway-models.profiles.live.test.ts dan src/gateway/live-image-probe.ts.
  • Cara mengaktifkan:
    • pnpm test:live (atau OPENCLAW_LIVE_TEST=1 jika memanggil Vitest secara langsung)
  • Cara memilih model:
    • Default: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
    • OPENCLAW_LIVE_GATEWAY_MODELS=all adalah alias untuk allowlist modern
    • Atau tetapkan OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (atau daftar dipisahkan koma) untuk mempersempit
  • Cara memilih penyedia (hindari “semua OpenRouter”):
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (allowlist dipisahkan koma)
  • Probe alat + gambar selalu aktif dalam pengujian live ini:
    • probe read + probe exec+read (stress alat)
    • probe gambar berjalan saat model mengiklankan dukungan input gambar
    • Alur (tingkat tinggi):
      • Pengujian membuat PNG kecil dengan “CAT” + kode acak (src/gateway/live-image-probe.ts)
      • Mengirimkannya melalui agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
      • Gateway mengurai lampiran menjadi images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
      • Embedded agent meneruskan pesan pengguna multimodal ke model
      • Penegasan: balasan berisi cat + kodenya (toleransi OCR: kesalahan kecil diperbolehkan)
Tip: untuk melihat apa yang bisa Anda uji di mesin Anda (dan id provider/model yang tepat), jalankan: 
openclaw models list
openclaw models list --json

​
Live: smoke backend CLI (Claude CLI atau CLI lokal lainnya)

  • Pengujian: src/gateway/gateway-cli-backend.live.test.ts
  • Tujuan: memvalidasi pipeline Gateway + agen menggunakan backend CLI lokal, tanpa menyentuh konfigurasi default Anda.
  • Aktifkan:
    • pnpm test:live (atau OPENCLAW_LIVE_TEST=1 jika memanggil Vitest secara langsung)
    • OPENCLAW_LIVE_CLI_BACKEND=1
  • Default:
    • Model: claude-cli/claude-sonnet-4-6
    • Perintah: claude
    • Argumen: ["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]
  • Override (opsional):
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-6"
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
    • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
    • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","stream-json","--include-partial-messages","--verbose","--permission-mode","bypassPermissions"]'
    • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 untuk mengirim lampiran gambar nyata (path disuntikkan ke prompt).
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" untuk meneruskan path file gambar sebagai argumen CLI alih-alih melalui injeksi prompt.
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (atau "list") untuk mengontrol cara argumen gambar diteruskan saat IMAGE_ARG ditetapkan.
    • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 untuk mengirim giliran kedua dan memvalidasi alur resume.
  • OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 untuk membiarkan konfigurasi MCP Claude CLI tetap aktif (default menyuntikkan --mcp-config kosong ketat sementara agar server MCP ambient/global tetap nonaktif selama smoke).
Contoh: 
OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-6" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
Resep Docker: 
pnpm test:docker:live-cli-backend
Catatan:
  • Runner Docker berada di scripts/test-live-cli-backend-docker.sh.
  • Runner ini menjalankan smoke backend CLI live di dalam image Docker repo sebagai pengguna non-root node, karena Claude CLI menolak bypassPermissions saat dipanggil sebagai root.
  • Untuk claude-cli, runner ini memasang paket Linux @anthropic-ai/claude-code ke prefix yang dapat ditulis dan di-cache di OPENCLAW_DOCKER_CLI_TOOLS_DIR (default: ~/.cache/openclaw/docker-cli-tools).
  • Untuk claude-cli, smoke live menyuntikkan konfigurasi MCP kosong ketat kecuali Anda menetapkan OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0.
  • Runner ini menyalin ~/.claude ke container jika tersedia, tetapi pada mesin yang autentikasi Claude-nya bergantung pada ANTHROPIC_API_KEY, runner ini juga mempertahankan ANTHROPIC_API_KEY / ANTHROPIC_API_KEY_OLD untuk child Claude CLI melalui OPENCLAW_LIVE_CLI_BACKEND_PRESERVE_ENV.

​
Live: smoke bind ACP (/acp spawn ... --bind here)

  • Pengujian: src/gateway/gateway-acp-bind.live.test.ts
  • Tujuan: memvalidasi alur bind percakapan ACP nyata dengan agen ACP live:
    • kirim /acp spawn <agent> --bind here
    • bind percakapan saluran pesan sintetis di tempat
    • kirim tindak lanjut normal pada percakapan yang sama
    • verifikasi bahwa tindak lanjut masuk ke transkrip sesi ACP yang terikat
  • Aktifkan:
    • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
    • OPENCLAW_LIVE_ACP_BIND=1
  • Default:
    • Agen ACP: claude
    • Saluran sintetis: konteks percakapan gaya DM Slack
    • Backend ACP: acpx
  • Override:
    • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
    • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
    • OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=/full/path/to/acpx
  • Catatan:
    • Jalur ini menggunakan permukaan gateway chat.send dengan field originating-route sintetis admin-only agar pengujian dapat melampirkan konteks saluran pesan tanpa berpura-pura mengirim secara eksternal.
    • Saat OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND tidak ditetapkan, pengujian menggunakan perintah acpx yang dikonfigurasi/dibundel. Jika auth harness Anda bergantung pada variabel env dari ~/.profile, sebaiknya gunakan perintah acpx kustom yang mempertahankan env penyedia.
Contoh: 
OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
Resep Docker: 
pnpm test:docker:live-acp-bind
Catatan Docker:
  • Runner Docker berada di scripts/test-live-acp-bind-docker.sh.
  • Runner ini mengambil ~/.profile, menyalin home auth CLI yang cocok (~/.claude atau ~/.codex) ke container, memasang acpx ke prefix npm yang dapat ditulis, lalu memasang live CLI yang diminta (@anthropic-ai/claude-code atau @openai/codex) jika belum ada.
  • Di dalam Docker, runner menetapkan OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx agar acpx mempertahankan variabel env penyedia dari profile yang diambil agar tetap tersedia untuk CLI harness child.

​
Resep live yang direkomendasikan

Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling tidak rentan gagal:
  • Satu model, langsung (tanpa gateway):
    • OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts
  • Satu model, smoke gateway:
    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Pemanggilan alat di beberapa penyedia:
    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
  • Fokus Google (API key Gemini + Antigravity):
    • Gemini (API key): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
    • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
Catatan:
  • google/... menggunakan API Gemini (API key).
  • google-antigravity/... menggunakan bridge OAuth Antigravity (endpoint agen gaya Cloud Code Assist).
  • google-gemini-cli/... menggunakan Gemini CLI lokal di mesin Anda (auth terpisah + keanehan tooling).
  • Gemini API vs Gemini CLI:
    • API: OpenClaw memanggil API Gemini yang di-host Google melalui HTTP (API key / auth profil); inilah yang biasanya dimaksud sebagian besar pengguna dengan “Gemini”.
    • CLI: OpenClaw melakukan shell out ke biner gemini lokal; ini memiliki auth sendiri dan dapat berperilaku berbeda (streaming/dukungan alat/perbedaan versi).

​
Live: matriks model (apa yang kami cakup)

Tidak ada “daftar model CI” yang tetap (live bersifat opt-in), tetapi inilah model-model yang direkomendasikan untuk dicakup secara rutin pada mesin pengembang yang memiliki kunci.

​
Set smoke modern (pemanggilan alat + gambar)

Ini adalah run “model umum” yang kami harapkan tetap berfungsi:
  • OpenAI (non-Codex): openai/gpt-5.4 (opsional: openai/gpt-5.4-mini)
  • OpenAI Codex: openai-codex/gpt-5.4
  • Anthropic: anthropic/claude-opus-4-6 (atau anthropic/claude-sonnet-4-6)
  • Google (Gemini API): google/gemini-3.1-pro-preview dan google/gemini-3-flash-preview (hindari model Gemini 2.x yang lebih lama)
  • Google (Antigravity): google-antigravity/claude-opus-4-6-thinking dan google-antigravity/gemini-3-flash
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/MiniMax-M2.7
Jalankan smoke gateway dengan alat + gambar: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

​
Dasar: pemanggilan alat (Read + Exec opsional)

Pilih setidaknya satu per keluarga penyedia:
  • OpenAI: openai/gpt-5.4 (atau openai/gpt-5.4-mini)
  • Anthropic: anthropic/claude-opus-4-6 (atau anthropic/claude-sonnet-4-6)
  • Google: google/gemini-3-flash-preview (atau google/gemini-3.1-pro-preview)
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/MiniMax-M2.7
Cakupan tambahan opsional (baik jika ada):
  • xAI: xai/grok-4 (atau versi terbaru yang tersedia)
  • Mistral: mistral/… (pilih satu model yang mampu “tools” yang Anda aktifkan)
  • Cerebras: cerebras/… (jika Anda memiliki akses)
  • LM Studio: lmstudio/… (lokal; pemanggilan alat bergantung pada mode API)

​
Vision: pengiriman gambar (lampiran → pesan multimodal)

Sertakan setidaknya satu model yang mampu gambar dalam OPENCLAW_LIVE_GATEWAY_MODELS (varian Claude/Gemini/OpenAI yang mendukung vision, dll.) untuk menguji probe gambar.

​
Aggregator / gateway alternatif

Jika Anda memiliki kunci yang diaktifkan, kami juga mendukung pengujian melalui:
  • OpenRouter: openrouter/... (ratusan model; gunakan openclaw models scan untuk menemukan kandidat yang mampu alat+gambar)
  • OpenCode: opencode/... untuk Zen dan opencode-go/... untuk Go (auth melalui OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)
Lebih banyak penyedia yang bisa Anda sertakan dalam matriks live (jika Anda memiliki kredensial/konfigurasi):
  • Bawaan: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
  • Melalui models.providers (endpoint kustom): minimax (cloud/API), serta proxy yang kompatibel dengan OpenAI/Anthropic apa pun (LM Studio, vLLM, LiteLLM, dll.)
Tip: jangan mencoba meng-hardcode “semua model” dalam dokumentasi. Daftar yang otoritatif adalah apa pun yang dikembalikan discoverModels(...) di mesin Anda + kunci apa pun yang tersedia.

​
Kredensial (jangan pernah commit)

Pengujian live menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktisnya:
  • Jika CLI berfungsi, pengujian live seharusnya menemukan kunci yang sama.
  • Jika pengujian live mengatakan “tidak ada kredensial”, debug dengan cara yang sama seperti Anda men-debug openclaw models list / pemilihan model.
  • Profil auth per agen: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (inilah yang dimaksud “kunci profil” dalam pengujian live)
  • Konfigurasi: ~/.openclaw/openclaw.json (atau OPENCLAW_CONFIG_PATH)
  • Direktori state lama: ~/.openclaw/credentials/ (disalin ke home live bertahap saat ada, tetapi bukan penyimpanan utama kunci profil)
  • Run lokal live secara default menyalin konfigurasi aktif, file auth-profiles.json per agen, credentials/ lama, dan direktori auth CLI eksternal yang didukung ke home pengujian sementara; override path agents.*.workspace / agentDir dihapus dari konfigurasi bertahap itu agar probe tetap tidak menyentuh workspace host nyata Anda.
Jika Anda ingin mengandalkan kunci env (misalnya diekspor di ~/.profile), jalankan pengujian lokal setelah source ~/.profile, atau gunakan runner Docker di bawah (runner ini dapat me-mount ~/.profile ke dalam container).

​
Deepgram live (transkripsi audio)

  • Pengujian: src/media-understanding/providers/deepgram/audio.live.test.ts
  • Aktifkan: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

​
BytePlus coding plan live

  • Pengujian: src/agents/byteplus.live.test.ts
  • Aktifkan: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
  • Override model opsional: BYTEPLUS_CODING_MODEL=ark-code-latest

​
Image generation live

  • Pengujian: src/image-generation/runtime.live.test.ts
  • Perintah: pnpm test:live src/image-generation/runtime.live.test.ts
  • Cakupan:
    • Mengenumerasi setiap plugin penyedia image-generation yang terdaftar
    • Memuat variabel env penyedia yang hilang dari login shell Anda (~/.profile) sebelum melakukan probe
    • Menggunakan kunci API live/env sebelum auth profile yang tersimpan secara default, sehingga kunci pengujian lama di auth-profiles.json tidak menutupi kredensial shell nyata
    • Melewati penyedia yang tidak memiliki auth/profil/model yang dapat digunakan
    • Menjalankan varian stock image-generation melalui kapabilitas runtime bersama:
      • google:flash-generate
      • google:pro-generate
      • google:pro-edit
      • openai:default-generate
  • Penyedia bundled saat ini yang dicakup:
    • openai
    • google
  • Penyempitan opsional:
    • 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"
  • Perilaku auth opsional:
    • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 untuk memaksa auth profile-store dan mengabaikan override env-only

​
Runner Docker (pemeriksaan opsional “berfungsi di Linux”)

Runner Docker ini dibagi menjadi dua kelompok:
  • Runner model live: test:docker:live-models dan test:docker:live-gateway hanya menjalankan file live kunci-profil yang sesuai di dalam image Docker repo (src/agents/models.profiles.live.test.ts dan src/gateway/gateway-models.profiles.live.test.ts), me-mount direktori konfigurasi dan workspace lokal Anda (serta mengambil ~/.profile jika di-mount). Entry point lokal yang sesuai adalah test:live:models-profiles dan test:live:gateway-profiles.
  • Runner live Docker secara default menggunakan batas smoke yang lebih kecil agar sapuan Docker penuh tetap praktis: test:docker:live-models default ke OPENCLAW_LIVE_MAX_MODELS=12, dan test:docker:live-gateway default ke OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000, dan OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Override variabel env tersebut saat Anda secara eksplisit menginginkan pemindaian menyeluruh yang lebih besar.
  • test:docker:all membangun image Docker live sekali melalui test:docker:live-build, lalu menggunakannya kembali untuk dua jalur live Docker tersebut.
  • Runner smoke container: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels, dan test:docker:plugins menyalakan satu atau lebih container nyata dan memverifikasi path integrasi tingkat lebih tinggi.
Runner Docker model live juga hanya melakukan bind-mount pada home auth CLI yang diperlukan (atau semua yang didukung saat run tidak dipersempit), lalu menyalinnya ke home container sebelum run agar OAuth CLI eksternal dapat me-refresh token tanpa memodifikasi penyimpanan auth host:
  • Model langsung: pnpm test:docker:live-models (skrip: scripts/test-live-models-docker.sh)
  • Smoke bind ACP: pnpm test:docker:live-acp-bind (skrip: scripts/test-live-acp-bind-docker.sh)
  • Smoke backend CLI: pnpm test:docker:live-cli-backend (skrip: scripts/test-live-cli-backend-docker.sh)
  • Gateway + agen dev: pnpm test:docker:live-gateway (skrip: scripts/test-live-gateway-models-docker.sh)
  • Smoke live Open WebUI: pnpm test:docker:openwebui (skrip: scripts/e2e/openwebui-docker.sh)
  • Wizard onboarding (TTY, scaffolding penuh): pnpm test:docker:onboard (skrip: scripts/e2e/onboard-docker.sh)
  • Jaringan gateway (dua container, auth WS + health): pnpm test:docker:gateway-network (skrip: scripts/e2e/gateway-network-docker.sh)
  • Bridge channel MCP (Gateway berisi seed + bridge stdio + smoke notification-frame Claude mentah): pnpm test:docker:mcp-channels (skrip: scripts/e2e/mcp-channels-docker.sh)
  • Plugins (install smoke + alias /plugin + semantik restart bundle Claude): pnpm test:docker:plugins (skrip: scripts/e2e/plugins-docker.sh)
Runner Docker model live juga melakukan bind-mount checkout saat ini sebagai read-only dan men-stage-nya ke workdir sementara di dalam container. Ini menjaga image runtime tetap ramping sambil tetap menjalankan Vitest terhadap source/config lokal Anda yang persis. Runner ini juga menetapkan OPENCLAW_SKIP_CHANNELS=1 agar probe gateway live tidak memulai worker channel Telegram/Discord/dll. nyata di dalam container. test:docker:live-models tetap menjalankan pnpm test:live, jadi teruskan juga OPENCLAW_LIVE_GATEWAY_* saat Anda perlu mempersempit atau mengecualikan cakupan live gateway dari jalur Docker tersebut. test:docker:openwebui adalah smoke kompatibilitas tingkat lebih tinggi: runner ini memulai container gateway OpenClaw dengan endpoint HTTP yang kompatibel OpenAI diaktifkan, memulai container Open WebUI yang dipin terhadap gateway itu, masuk melalui Open WebUI, memverifikasi /api/models mengekspos openclaw/default, lalu mengirim permintaan chat nyata melalui proxy /api/chat/completions milik Open WebUI. Run pertama bisa terasa jauh lebih lambat karena Docker mungkin perlu menarik image Open WebUI dan Open WebUI mungkin perlu menyelesaikan setup cold-start-nya sendiri. Jalur ini mengharapkan kunci model live yang dapat digunakan, dan OPENCLAW_PROFILE_FILE (~/.profile secara default) adalah cara utama untuk menyediakannya dalam run Dockerized. Run yang berhasil mencetak payload JSON kecil seperti { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels sengaja deterministik dan tidak memerlukan akun Telegram, Discord, atau iMessage nyata. Runner ini menyalakan Gateway container berisi seed, memulai container kedua yang memunculkan openclaw mcp serve, lalu memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, routing pengiriman keluar, serta notifikasi saluran + izin gaya Claude melalui bridge MCP stdio nyata. Pemeriksaan notifikasi menginspeksi frame MCP stdio mentah secara langsung sehingga smoke ini memvalidasi apa yang sebenarnya dipancarkan bridge, bukan hanya apa yang kebetulan ditampilkan oleh SDK klien tertentu. Smoke thread plain-language ACP manual (bukan CI):
  • bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
  • Pertahankan skrip ini untuk alur kerja regresi/debug. Skrip ini mungkin diperlukan lagi untuk validasi routing thread ACP, jadi jangan dihapus.
Variabel env yang berguna:
  • OPENCLAW_CONFIG_DIR=... (default: ~/.openclaw) di-mount ke /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR=... (default: ~/.openclaw/workspace) di-mount ke /home/node/.openclaw/workspace
  • OPENCLAW_PROFILE_FILE=... (default: ~/.profile) di-mount ke /home/node/.profile dan diambil sebelum menjalankan pengujian
  • OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (default: ~/.cache/openclaw/docker-cli-tools) di-mount ke /home/node/.npm-global untuk instalasi CLI yang di-cache di dalam Docker
  • Direktori auth CLI eksternal di bawah $HOME di-mount read-only di bawah /host-auth/..., lalu disalin ke /home/node/... sebelum pengujian dimulai
    • Default: mount semua direktori yang didukung (.codex, .claude, .minimax)
    • Run penyedia yang dipersempit hanya me-mount direktori yang diperlukan yang diinferensikan dari OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
    • Override manual dengan OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none, atau daftar dipisahkan koma seperti OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
  • OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... untuk mempersempit run
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... untuk memfilter penyedia di dalam container
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 untuk memastikan kredensial berasal dari profile store (bukan env)
  • OPENCLAW_OPENWEBUI_MODEL=... untuk memilih model yang diekspos gateway untuk smoke Open WebUI
  • OPENCLAW_OPENWEBUI_PROMPT=... untuk menimpa prompt pemeriksaan nonce yang digunakan smoke Open WebUI
  • OPENWEBUI_IMAGE=... untuk menimpa tag image Open WebUI yang dipin

​
Kewarasan dokumentasi

Jalankan pemeriksaan dokumentasi setelah mengedit dokumentasi: pnpm check:docs. Jalankan validasi anchor Mintlify penuh saat Anda juga memerlukan pemeriksaan heading dalam halaman: pnpm docs:check-links:anchors.

​
Regresi offline (aman untuk CI)

Ini adalah regresi “pipeline nyata” tanpa penyedia nyata:
  • Pemanggilan alat gateway (mock OpenAI, gateway + loop agen nyata): src/gateway/gateway.test.ts (kasus: “runs a mock OpenAI tool call end-to-end via gateway agent loop”)
  • Wizard gateway (WS wizard.start/wizard.next, menulis config + auth enforced): src/gateway/gateway.test.ts (kasus: “runs wizard over ws and writes auth token config”)

​
Evaluasi keandalan agen (Skills)

Kami sudah memiliki beberapa pengujian aman-CI yang berperilaku seperti “evaluasi keandalan agen”:
  • Mock tool-calling melalui gateway + loop agen nyata (src/gateway/gateway.test.ts).
  • Alur wizard end-to-end yang memvalidasi wiring sesi dan efek konfigurasi (src/gateway/gateway.test.ts).
Apa yang masih kurang untuk Skills (lihat Skills):
  • Pengambilan keputusan: saat Skills dicantumkan dalam prompt, apakah agen memilih Skill yang tepat (atau menghindari yang tidak relevan)?
  • Kepatuhan: apakah agen membaca SKILL.md sebelum digunakan dan mengikuti langkah/argumen yang diwajibkan?
  • Kontrak alur kerja: skenario multi-giliran yang menegaskan urutan alat, carryover riwayat sesi, dan batas sandbox.
Evaluasi mendatang sebaiknya tetap deterministik terlebih dahulu:
  • Runner skenario yang menggunakan penyedia tiruan untuk menegaskan tool call + urutan, pembacaan file Skill, dan wiring sesi.
  • Sekumpulan kecil skenario yang berfokus pada Skill (gunakan vs hindari, gating, injeksi prompt).
  • Evaluasi live opsional (opt-in, digating env) hanya setelah suite aman-CI tersedia.

​
Pengujian kontrak (bentuk plugin dan channel)

Pengujian kontrak memverifikasi bahwa setiap plugin dan channel yang terdaftar sesuai dengan kontrak antarmukanya. Pengujian ini mengiterasi semua plugin yang ditemukan dan menjalankan rangkaian penegasan bentuk dan perilaku. Jalur unit default pnpm test dengan sengaja melewati file seam bersama dan smoke ini; jalankan perintah kontrak secara eksplisit saat Anda menyentuh permukaan channel atau penyedia bersama.

​
Perintah

  • Semua kontrak: pnpm test:contracts
  • Hanya kontrak channel: pnpm test:contracts:channels
  • Hanya kontrak penyedia: pnpm test:contracts:plugins

​
Kontrak channel

Berada di src/channels/plugins/contracts/*.contract.test.ts:
  • plugin - Bentuk plugin dasar (id, nama, kapabilitas)
  • setup - Kontrak wizard setup
  • session-binding - Perilaku pengikatan sesi
  • outbound-payload - Struktur payload pesan
  • inbound - Penanganan pesan masuk
  • actions - Handler aksi channel
  • threading - Penanganan ID thread
  • directory - API direktori/roster
  • group-policy - Penerapan kebijakan grup

​
Kontrak status penyedia

Berada di src/plugins/contracts/*.contract.test.ts.
  • status - Probe status channel
  • registry - Bentuk registry plugin

​
Kontrak penyedia

Berada di src/plugins/contracts/*.contract.test.ts:
  • auth - Kontrak alur auth
  • auth-choice - Pilihan/seleksi auth
  • catalog - API katalog model
  • discovery - Penemuan plugin
  • loader - Pemuatan plugin
  • runtime - Runtime penyedia
  • shape - Bentuk/antarmuka plugin
  • wizard - Wizard setup

​
Kapan dijalankan

  • Setelah mengubah export atau subpath plugin-sdk
  • Setelah menambahkan atau memodifikasi plugin channel atau penyedia
  • Setelah me-refactor pendaftaran atau penemuan plugin
Pengujian kontrak berjalan di CI dan tidak memerlukan kunci API nyata.

​
Menambahkan regresi (panduan)

Saat Anda memperbaiki masalah penyedia/model yang ditemukan dalam live:
  • Tambahkan regresi aman-CI jika memungkinkan (mock/stub penyedia, atau tangkap transformasi bentuk permintaan yang tepat)
  • Jika bug itu secara inheren hanya live (rate limit, kebijakan auth), buat pengujian live tetap sempit dan opt-in melalui variabel env
  • Sebaiknya targetkan lapisan terkecil yang menangkap bug:
    • bug konversi/replay permintaan penyedia → pengujian model langsung
    • bug pipeline sesi/riwayat/alat gateway → smoke live gateway atau pengujian mock gateway aman-CI
  • Guardrail traversal SecretRef:
    • src/secrets/exec-secret-ref-id-parity.test.ts menurunkan satu target sampel per kelas SecretRef dari metadata registry (listSecretTargetRegistryEntries()), lalu menegaskan bahwa exec id segmen traversal ditolak.
    • Jika Anda menambahkan keluarga target SecretRef includeInPlan baru di src/secrets/target-registry-data.ts, perbarui classifyTargetClass dalam pengujian tersebut. Pengujian ini sengaja gagal pada target id yang belum diklasifikasikan sehingga kelas baru tidak dapat dilewati secara diam-diam.