OpenClaw 測試指南：單元、整合與 E2E 測試完整流程

快速開始

大部分日常開發工作：

完整閘門檢查（推送前必做）：pnpm build && pnpm check && pnpm check:test-types && pnpm test
在效能較好的機器上進行更快速的本地完整套件測試：pnpm test:max
直接使用 Vitest 監控模式：pnpm test:watch
直接指定檔案路徑，現在也支援 extension 與 channel 路徑：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

當你需要除錯真實的 provider 或 model 時（需要真實憑證）：

Live 套件（包含 model 與 Gateway 工具/圖像探測）：pnpm test:live
安靜地針對單一 Live 測試檔案執行：pnpm test:live -- src/agents/models.profiles.live.test.ts

提示：當你只需要測試一個失敗案例時，建議透過下方描述的 allowlist 環境變數來縮小 Live 測試範圍。

QA 專用執行器

這些指令與主要測試套件並列，當你需要 QA 實驗室的真實環境時可以使用：

pnpm openclaw qa suite
- 直接在主機上執行 repo 支援的 QA 場景。
- 預設會使用隔離的 Gateway worker 並行執行多個選定的場景。qa-channel 預設並發數為 4（受限於選定的場景數量）。使用 --concurrency <count> 來調整 worker 數量，或使用 --concurrency 1 進行舊式的序列執行。
- 當任何場景失敗時會以非零狀態碼退出。如果你想在不觸發失敗退出的情況下取得產出物，請使用 --allow-failures。
- 支援 live-frontier、mock-openai 與 aimock 等 provider 模式。aimock 會啟動一個本地的 AIMock 支援的 provider 伺服器，用於實驗性的 fixture 與協定模擬覆蓋，而不會取代場景感知的 mock-openai 通道。
pnpm openclaw qa suite --runner multipass
- 在拋棄式的 Multipass Linux VM 內執行相同的 QA 套件。
- 保留與主機上 qa suite 相同的場景選擇行為。
- 重用與 qa suite 相同的 provider/model 選擇 flags。
- Live 執行會轉發對 guest 實用的 QA 驗證輸入：基於環境變數的 provider 金鑰、QA Live provider 設定路徑，以及存在的 CODEX_HOME。
- 輸出目錄必須保持在 repo 根目錄之下，以便 guest 可以透過掛載的工作區寫回資料。
- 將一般的 QA 報告、摘要以及 Multipass 日誌寫入 .artifacts/qa-e2e/...。
pnpm qa:lab:up
- 啟動 Docker 支援的 QA 站點，用於操作員風格的 QA 工作。
pnpm openclaw qa aimock
- 僅啟動本地 AIMock provider 伺服器，用於直接的協定冒煙測試。
pnpm openclaw qa matrix
- 針對拋棄式的 Docker 支援 Tuwunel homeserver 執行 Matrix Live QA 通道。
- 此 QA 主機目前僅限於 repo/開發使用。打包後的 OpenClaw 安裝不包含 qa-lab，因此不會暴露 openclaw qa。
- Repo checkout 會直接載入捆綁的執行器；無需額外的插件安裝步驟。
- 預先配置三個臨時的 Matrix 使用者（driver、sut、observer）加上一個私人房間，然後啟動一個以真實 Matrix 插件作為 SUT 傳輸的 QA Gateway 子程序。
- 預設使用固定的穩定版 Tuwunel 映像檔 ghcr.io/matrix-construct/tuwunel:v1.5.1。當你需要測試不同映像檔時，請覆寫 OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE。
- Matrix 不會暴露共享的憑證來源 flags，因為該通道會在本地配置拋棄式使用者。
- 將 Matrix QA 報告、摘要、觀察到的事件產出物以及合併的 stdout/stderr 輸出日誌寫入 .artifacts/qa-e2e/...。
pnpm openclaw qa telegram
- 針對真實私人群組執行 Telegram Live QA 通道，使用來自環境變數的 driver 與 SUT bot token。
- 需要 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 以選擇池化租賃。
- 當任何場景失敗時會以非零狀態碼退出。如果你想在不觸發失敗退出的情況下取得產出物，請使用 --allow-failures。
- 需要在同一個私人群組中有兩個不同的 bot，且 SUT bot 必須公開 Telegram 使用者名稱。
- 為了穩定的 bot 對 bot 觀察，請在 @BotFather 中為兩個 bot 啟用 Bot-to-Bot Communication Mode，並確保 driver bot 可以觀察到群組內的 bot 流量。
- 將 Telegram QA 報告、摘要以及觀察到的訊息產出物寫入 .artifacts/qa-e2e/...。

測試套件（在哪裡執行什麼）

將這些套件視為「真實性遞增」（同時也伴隨著不穩定性與成本增加）：

單元 / 整合測試（預設）

指令：pnpm test
設定：在現有的範圍化 Vitest 專案上進行十次序列分片執行 (vitest.full-*.config.ts)
檔案：src/**/*.test.ts、packages/**/*.test.ts、test/**/*.test.ts 下的核心/單元清單，以及 vitest.unit.config.ts 涵蓋的白名單 ui node 測試。
範圍：
- 純單元測試
- 程序內整合測試（Gateway 驗證、路由、工具、解析、設定）
- 已知錯誤的確定性回歸測試
期望：
- 在 CI 中執行
- 不需要真實金鑰
- 應該快速且穩定
專案說明：
- 未指定的 pnpm test 現在執行十一個較小的分片設定（core-unit-src、core-unit-security、core-unit-ui、core-unit-support、core-support-boundary、core-contracts、core-bundled、core-runtime、agentic、auto-reply、extensions），而不是一個巨大的原生根專案程序。這能降低負載機器上的峰值 RSS，並避免 auto-reply/extension 工作拖累不相關的套件。
- pnpm test --watch 仍然使用原生的根 vitest.config.ts 專案圖，因為多分片監控循環並不實用。
- pnpm test、pnpm test:watch 與 pnpm test:perf:imports 會優先將明確的檔案/目錄目標路由到範圍化通道，因此 pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts 不會支付完整的根專案啟動成本。
- pnpm test:changed 會在 diff 僅觸及可路由的原始碼/測試檔案時，將變更的 git 路徑展開到相同的範圍化通道；設定/安裝編輯仍會回退到廣泛的根專案重跑。
- pnpm check:changed 是針對小型工作的正常智慧型本地閘門。它將 diff 分類為核心、核心測試、擴充功能、擴充功能測試、應用程式、文件與工具，然後執行匹配的型別檢查/lint/測試通道。公開的 Plugin SDK 與插件合約變更包含擴充功能驗證，因為擴充功能依賴這些核心合約。
- 來自 agents、commands、plugins、auto-reply 輔助工具、plugin-sdk 及類似純工具區域的輕量級單元測試會透過 unit-fast 通道路由，該通道會跳過 test/setup-openclaw-runtime.ts；有狀態/執行時期負載重的檔案則留在現有的通道上。
- 選定的 plugin-sdk 與 commands 輔助原始檔也會將變更模式的執行對應到這些輕量通道中的明確兄弟測試，因此輔助工具的編輯避免了為該目錄重跑完整的重型套件。
- auto-reply 現在有三個專用儲存桶：頂層核心輔助工具、頂層 reply.* 整合測試，以及 src/auto-reply/reply/** 子樹。這能讓最重的 reply harness 工作避開廉價的 status/chunk/token 測試。
嵌入式執行器說明：
- 當你變更訊息工具發現輸入或壓縮執行時期上下文時，請保持兩個層級的覆蓋。
- 為純路由/正規化邊界新增聚焦的輔助回歸測試。
- 同時保持嵌入式執行器整合套件的健康：src/agents/pi-embedded-runner/compact.hooks.test.ts、src/agents/pi-embedded-runner/run.overflow-compaction.test.ts 與 src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts。
- 這些套件驗證範圍化 ID 與壓縮行為是否仍流經真實的 run.ts / compact.ts 路徑；僅有輔助工具的測試不足以替代這些整合路徑。
Pool 說明：
- 基礎 Vitest 設定現在預設為 threads。
- 共享的 Vitest 設定也修復了 isolate: false，並在根專案、e2e 與 Live 設定中使用了非隔離執行器。
- 根 UI 通道保留其 jsdom 設定與優化器，但現在也執行在共享的非隔離執行器上。
- 每個 pnpm test 分片都繼承了來自共享 Vitest 設定的相同 threads + isolate: false 預設值。
- 共享的 scripts/run-vitest.mjs 啟動器現在預設為 Vitest 子 Node 程序新增 --no-maglev，以減少大型本地執行期間的 V8 編譯變動。如果你需要與標準 V8 行為進行比較，請設定 OPENCLAW_VITEST_ENABLE_MAGLEV=1。
快速本地迭代說明：
- pnpm changed:lanes 顯示 diff 觸發了哪些架構通道。
- Pre-commit hook 在暫存格式化/linting 後執行 pnpm check:changed --staged，因此僅限核心的 commit 不會支付擴充功能測試成本，除非它們觸及公開的擴充功能合約。
- pnpm test:changed 在變更路徑能乾淨地對應到較小套件時，會透過範圍化通道路由。
- pnpm test:max 與 pnpm test:changed:max 保留相同的路由行為，只是有更高的 worker 上限。
- 本地 worker 自動擴展現在刻意保持保守，且在主機負載平均值已經很高時會退避，因此多個並發的 Vitest 執行預設造成的損害較小。
- 基礎 Vitest 設定將專案/設定檔標記為 forceRerunTriggers，以便在測試接線變更時，變更模式的重跑保持正確。
- 設定在支援的主機上保持啟用 OPENCLAW_VITEST_FS_MODULE_CACHE；如果你想要一個明確的快取位置進行直接分析，請設定 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path。
效能除錯說明：
- pnpm test:perf:imports 啟用 Vitest 匯入持續時間報告以及匯入細分輸出。
- pnpm test:perf:imports:changed 將相同的分析視角限縮在自 origin/main 以來變更的檔案。
pnpm test:perf:changed:bench -- --ref <git-ref> 比較路由後的 test:changed 與該 commit diff 的原生根專案路徑，並列印牆鐘時間與 macOS 最大 RSS。
pnpm test:perf:changed:bench -- --worktree 透過將變更的檔案列表路由到 scripts/test-projects.mjs 與根 Vitest 設定，來對目前的髒樹進行基準測試。
- pnpm test:perf:profile:main 為 Vitest/Vite 啟動與轉換開銷寫入主執行緒 CPU 設定檔。
- pnpm test:perf:profile:runner 為單元套件寫入執行器 CPU+堆積設定檔，並停用檔案並行處理。

E2E（Gateway 冒煙測試）

指令：pnpm test:e2e
設定：vitest.e2e.config.ts
檔案：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts
執行時期預設值：
- 使用 Vitest threads 搭配 isolate: false，與 repo 其餘部分一致。
- 使用自適應 worker（CI：最多 2 個，本地：預設 1 個）。
- 預設在靜默模式下執行，以減少控制台 I/O 開銷。
有用的覆寫：
- OPENCLAW_E2E_WORKERS=<n> 強制指定 worker 數量（上限為 16）。
- OPENCLAW_E2E_VERBOSE=1 重新啟用詳細的控制台輸出。
範圍：
- 多實例 Gateway 端對端行為
- WebSocket/HTTP 介面、節點配對與更繁重的網路操作
期望：
- 在 CI 中執行（當 pipeline 中啟用時）
- 不需要真實金鑰
- 比單元測試有更多移動部件（可能較慢）

E2E：OpenShell 後端冒煙測試

指令：pnpm test:e2e:openshell
檔案：test/openshell-sandbox.e2e.test.ts
範圍：
- 透過 Docker 在主機上啟動隔離的 OpenShell Gateway
- 從臨時的本地 Dockerfile 建立沙盒
- 透過真實的 sandbox ssh-config + SSH exec 執行 OpenClaw 的 OpenShell 後端
- 透過沙盒 fs bridge 驗證遠端標準檔案系統行為
期望：
- 僅限選擇性加入；不屬於預設的 pnpm test:e2e 執行範圍
- 需要本地 openshell CLI 以及運作中的 Docker daemon
- 使用隔離的 HOME / XDG_CONFIG_HOME，然後銷毀測試 Gateway 與沙盒
有用的覆寫：
- OPENCLAW_E2E_OPENSHELL=1 在手動執行更廣泛的 e2e 套件時啟用此測試
- OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell 指向非預設的 CLI 二進位檔或包裝腳本

Live（真實 Provider + 真實 Model）

指令：pnpm test:live
設定：vitest.live.config.ts
檔案：src/**/*.live.test.ts
預設：由 pnpm test:live 啟用（設定 OPENCLAW_LIVE_TEST=1）
範圍：
- 「這個 provider/model 今天真的能用真實憑證運作嗎？」
- 捕捉 provider 格式變更、工具呼叫怪癖、驗證問題與速率限制行為
期望：
- 設計上不保證 CI 穩定（真實網路、真實 provider 政策、配額、中斷）
- 花費金錢 / 使用速率限制
- 建議執行縮小後的子集，而不是「全部」
Live 執行會讀取 ~/.profile 以取得遺失的 API 金鑰。
預設情況下，Live 執行仍會隔離 HOME 並將設定/驗證資料複製到臨時測試主目錄，因此單元 fixture 無法變更你真實的 ~/.openclaw。
僅在你有意讓 Live 測試使用真實主目錄時，才設定 OPENCLAW_LIVE_USE_REAL_HOME=1。
pnpm test:live 現在預設為較安靜的模式：它保留 [live] ... 進度輸出，但會抑制額外的 ~/.profile 通知並靜音 Gateway 引導日誌/Bonjour 雜訊。如果你想恢復完整的啟動日誌，請設定 OPENCLAW_LIVE_TEST_QUIET=0。
API 金鑰輪替（特定於 provider）：設定 *_API_KEYS 並使用逗號/分號格式，或使用 *_API_KEY_1、*_API_KEY_2（例如 OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS），或透過 OPENCLAW_LIVE_*_KEY 進行每項 Live 覆寫；測試會在收到速率限制回應時重試。
進度/心跳輸出：
- Live 套件現在會將進度行發送到 stderr，因此即使 Vitest 控制台捕捉處於靜默狀態，長時間的 provider 呼叫也能清楚顯示為活動狀態。
- vitest.live.config.ts 停用了 Vitest 控制台攔截，因此 provider/Gateway 進度行會在 Live 執行期間立即串流輸出。
- 使用 OPENCLAW_LIVE_HEARTBEAT_MS 調整直接模型心跳。
- 使用 OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS 調整 Gateway/探測心跳。

我應該執行哪個套件？

請參考此決策表：

編輯邏輯/測試：執行 pnpm test（如果你變更了很多內容，請執行 pnpm test:coverage）
觸及 Gateway 網路 / WS 協定 / 配對：新增 pnpm test:e2e
除錯「我的 bot 掛了」 / 特定 provider 的失敗 / 工具呼叫：執行縮小範圍的 pnpm test:live

AI Setup Assistant

Android 節點功能掃描 (Live: Android node capability sweep)

這項測試能確保 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

模型冒煙測試 (Live: model smoke (profile keys))

即時測試分為兩個層級，讓我們能精確隔離故障點：

「直接模型」測試告訴我們提供者/模型是否能使用給定的 key 進行回應。
「Gateway 冒煙」測試則確認該模型的完整 Gateway+agent 管線（包含會話、歷史記錄、工具、sandbox 政策等）運作正常。

第一層：直接模型完成測試 (無 Gateway)

此層級測試旨在驗證 API 連線與模型回應的基本能力，不涉及複雜的 Gateway 流程。

測試檔案：src/agents/models.profiles.live.test.ts
目標：
- 列舉已發現的模型。
- 使用 getApiKeyForModel 選擇你有權限的模型。
- 針對每個模型執行小型完成測試（以及必要的目標回歸測試）。
如何啟用：
- pnpm test:live（若直接呼叫 Vitest，則使用 OPENCLAW_LIVE_TEST=1）。
設定 OPENCLAW_LIVE_MODELS=modern（或 all，這是 modern 的別名）來實際執行此套件；否則測試會跳過，以保持 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,..."（逗號分隔白名單）。
- Modern/all 掃描預設為精選的高訊號上限；設定 OPENCLAW_LIVE_MAX_MODELS=0 可進行詳盡的現代掃描，或設定正整數以限制數量。
如何選擇提供者：
- OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"（逗號分隔白名單）。
Key 的來源：
- 預設：profile store 與環境變數備援。
- 設定 OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 以強制僅使用 profile store。
存在原因：
- 將「提供者 API 故障 / key 無效」與「Gateway agent 管線故障」分開。
- 包含小型、獨立的回歸測試（例如：OpenAI Responses/Codex Responses 推理重播 + 工具呼叫流程）。

第二層：Gateway + 開發 agent 冒煙測試 (OpenClaw 的實際運作方式)

此層級測試驗證完整的 agent 互動流程，確保工具呼叫與多模態功能在 Gateway 環境下運作無誤。

測試檔案：src/gateway/gateway-models.profiles.live.test.ts
目標：
- 啟動一個進程內 (in-process) 的 Gateway。
- 建立/修補 agent:dev:* 會話（每次執行時覆寫模型）。
- 迭代帶有 key 的模型並斷言：
  - 「有意義」的回應（無工具）。
  - 實際的工具呼叫運作正常（讀取探測）。
  - 選用的額外工具探測（執行+讀取探測）。
  - OpenAI 回歸路徑（僅工具呼叫 → 後續追蹤）持續運作。
探測細節（方便你快速解釋故障原因）：
- read 探測：測試會在工作區寫入一個 nonce 檔案，並要求 agent read 它並回傳該 nonce。
- exec+read 探測：測試要求 agent 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"（或逗號列表）來縮小範圍。
- Modern/all Gateway 掃描預設為精選的高訊號上限；設定 OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 可進行詳盡的現代掃描，或設定正整數以限制數量。
如何選擇提供者（避免「OpenRouter 全部」）：
- 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)。
  - 嵌入式 agent 將多模態使用者訊息轉發給模型。
  - 斷言：回覆包含 cat + 代碼（OCR 容錯：允許輕微錯誤）。

小撇步：若要查看你機器上能測試的項目（以及精確的 provider/model ID），請執行：

openclaw models list
openclaw models list --json

CLI 後端冒煙測試 (Live: CLI backend smoke (Claude, Codex, Gemini, or other local CLIs))

此測試驗證 Gateway 與 agent 管線在本地 CLI 後端下的表現，且不會更動你的預設設定。

測試檔案：src/gateway/gateway-cli-backend.live.test.ts
目標：在不觸碰預設設定的情況下，使用本地 CLI 後端驗證 Gateway + agent 管線。
後端特定的冒煙測試預設值位於所屬擴充功能的 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。
它以非 root 的 node 使用者身分在 repo Docker 映像檔內執行即時 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，然後執行兩輪 Gateway CLI 後端對話，且不保留 Anthropic API-key 環境變數。此訂閱通道預設停用 Claude MCP/工具與圖像探測，因為 Claude 目前將第三方應用程式使用量透過額外計費處理，而非納入一般訂閱方案限制。
即時 CLI 後端冒煙測試現在針對 Claude、Codex 與 Gemini 執行相同的端對端流程：文字對話、圖像分類對話，以及透過 Gateway CLI 驗證的 MCP cron 工具呼叫。
Claude 的預設冒煙測試還會將會話從 Sonnet 修補為 Opus，並驗證恢復後的會話仍記得先前的筆記。

ACP 綁定冒煙測試 (Live: ACP bind smoke (`/acp spawn ... --bind here`))

此測試驗證透過即時 ACP agent 進行的 ACP 對話綁定流程。

測試檔案：src/gateway/gateway-acp-bind.live.test.ts
目標：使用即時 ACP agent 驗證真實的 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 agents：claude,codex,gemini
- 直接 pnpm test:live ... 的 ACP agent：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 未設定時，測試會使用嵌入式 acpx 插件內建的 agent 註冊表來處理所選的 ACP harness agent。

範例：

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

單一 agent 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 agents 執行 ACP 綁定冒煙測試：claude、codex，然後是 gemini。
使用 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 能讓子 harness CLI 使用來自已載入設定檔的提供者環境變數。

Live: Codex app-server harness smoke

這個測試的主要目標是透過標準的 Gateway 來驗證插件所屬的 Codex harness。你可以透過以下步驟來進行驗證：

載入已打包的 codex 插件。
設定 OPENCLAW_AGENT_RUNTIME=codex。
發送第一個 Gateway agent 請求到 codex/gpt-5.4。
發送第二個請求到同一個 OpenClaw session，並驗證 app-server thread 是否能成功恢復。
透過相同的 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/tool 探測：OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
此 smoke 測試會設定 OPENCLAW_AGENT_HARNESS_FALLBACK=none，確保損壞的 Codex harness 不會因為靜默回退到 PI 而通過測試。
驗證方式：使用來自 shell 或 profile 的 OPENAI_API_KEY，以及選用的 ~/.codex/auth.json 和 ~/.codex/config.toml 檔案。

Local recipe:

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 recipe:

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

Docker notes:

Docker 執行器位於 scripts/test-live-codex-harness-docker.sh。
它會載入掛載的 ~/.profile，傳遞 OPENAI_API_KEY，在存在時複製 Codex CLI 驗證檔案，將 @openai/codex 安裝到可寫入的掛載 npm prefix，暫存原始碼樹，然後僅執行 Codex-harness 的 live test。
Docker 預設啟用圖像和 MCP/tool 探測。當你需要進行更精確的除錯時，請設定 OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 或 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0。
Docker 同時會匯出 OPENCLAW_AGENT_HARNESS_FALLBACK=none，以符合 live test 的設定，防止 openai-codex/* 或 PI 回退掩蓋 Codex harness 的回歸問題。

Recommended live recipes

使用明確且範圍狹窄的允許清單（allowlists）通常執行速度最快且最穩定：

單一模型，直接呼叫（不經過 Gateway）：
- OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts
單一模型，Gateway smoke 測試：
- OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
跨多個供應商的工具呼叫：
- 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
Google 專注測試（Gemini API key + 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

Notes:

google/... 使用 Gemini API (API key)。
google-antigravity/... 使用 Antigravity OAuth bridge (類似 Cloud Code Assist 的 agent 端點)。
google-gemini-cli/... 使用你機器上的本地 Gemini CLI (有獨立的驗證與工具特性)。
Gemini API 與 Gemini CLI 的區別：
- API: OpenClaw 透過 HTTP 呼叫 Google 託管的 Gemini API (使用 API key / profile 驗證)；這也是大多數使用者所指的「Gemini」。
- CLI: OpenClaw 呼叫本地的 gemini 二進位檔案；它有自己的驗證機制，且行為可能有所不同（串流、工具支援、版本差異）。

Live: model matrix (what we cover)

雖然沒有固定的「CI 模型列表」（live 測試是選擇性加入的），但以下是建議在開發機器上使用金鑰定期測試的模型。

Modern smoke set (tool calling + image)

這是我們預期能持續運作的「常見模型」執行集：

OpenAI (非 Codex): openai/gpt-5.4 (選用: openai/gpt-5.4-mini)
OpenAI Codex: openai-codex/gpt-5.4
Anthropic: anthropic/claude-opus-4-6 (或 anthropic/claude-sonnet-4-6)
Google (Gemini API): google/gemini-3.1-pro-preview 和 google/gemini-3-flash-preview (避免使用較舊的 Gemini 2.x 模型)
Google (Antigravity): google-antigravity/claude-opus-4-6-thinking 和 google-antigravity/gemini-3-flash
Z.AI (GLM): zai/glm-4.7
MiniMax: minimax/MiniMax-M2.7

執行包含工具與圖像的 Gateway smoke 測試： 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

Baseline: tool calling (Read + optional Exec)

請為每個供應商系列至少選擇一個模型：

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 模式)

Vision: image send (attachment → multimodal message)

在 OPENCLAW_LIVE_GATEWAY_MODELS 中包含至少一個具備圖像能力的模型（Claude/Gemini/OpenAI 視覺能力變體等），以執行圖像探測。

Aggregators / alternate gateways

如果你已啟用金鑰，我們也支援透過以下方式進行測試：

OpenRouter: openrouter/... (數百種模型；使用 openclaw models scan 尋找具備工具與圖像能力的候選模型)
OpenCode: opencode/... 用於 Zen，opencode-go/... 用於 Go (透過 OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY 驗證)

更多你可以納入 live 矩陣的供應商（如果你有憑證/配置）：

內建: 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(...) 回傳的內容，以及你可用的金鑰。

Credentials (never commit)

Live 測試發現憑證的方式與 CLI 相同。實際影響如下：

如果 CLI 可以運作，live 測試應該也能找到相同的金鑰。
如果 live 測試顯示「no creds」，請依照除錯 openclaw models list / 模型選擇的方式進行除錯。
每個 agent 的驗證設定檔：~/.openclaw/agents/<agentId>/agent/auth-profiles.json (這就是 live 測試中「profile keys」的含義)
配置：~/.openclaw/openclaw.json (或 OPENCLAW_CONFIG_PATH)
舊版狀態目錄：~/.openclaw/credentials/ (存在時會被複製到暫存的 live home 中，但不是主要的 profile-key 儲存區)
本地 live 執行預設會複製活動配置、每個 agent 的 auth-profiles.json 檔案、舊版 credentials/ 以及支援的外部 CLI 驗證目錄到暫存的測試 home 中；暫存的 live home 會跳過 workspace/ 和 sandboxes/，並且會移除 agents.*.workspace / agentDir 路徑覆蓋，以確保探測不會影響你真實的主機工作區。

如果你想依賴環境變數金鑰（例如在 ~/.profile 中匯出的金鑰），請在 source ~/.profile 之後執行本地測試，或使用下方的 Docker 執行器（它們可以將 ~/.profile 掛載到容器中）。

Deepgram live (audio transcription)

測試：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

BytePlus coding plan live

你可以透過執行測試來驗證 OpenClaw 的 BytePlus coding plan 功能是否正常運作。請確保你的環境變數設定正確，以便順利進行整合測試。

測試檔案路徑：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

ComfyUI workflow media live

此區塊用於測試 OpenClaw 的 ComfyUI workflow 媒體處理能力，確保在變更工作流程提交、輪詢、下載或插件註冊後功能依然穩定。

測試檔案路徑：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> 中進行設定，否則將跳過各項功能。
- 此測試在調整工作流程提交、輪詢、下載或插件註冊後特別實用。

Image generation live

透過 OpenClaw 的圖像生成即時測試，你可以驗證所有已註冊的圖像生成供應商插件是否能正確運作。系統會優先使用環境變數中的 API 金鑰，確保測試結果準確。

測試檔案路徑：src/image-generation/runtime.live.test.ts
執行測試指令：

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

使用測試工具：

pnpm test:live:media image

測試範圍與機制：
- 列舉所有已註冊的圖像生成供應商插件。
- 在探測前從你的登入 shell (~/.profile) 載入缺失的供應商環境變數。
- 預設優先使用 live/env API 金鑰而非儲存的認證設定檔，避免 auth-profiles.json 中的過期金鑰干擾測試。
- 跳過沒有可用認證、設定檔或模型的供應商。
- 透過共享的 runtime 功能執行標準圖像生成變體：
  - 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

Music generation live

此測試涵蓋 OpenClaw 的音樂生成功能，確保共享的供應商路徑運作正常，並支援多種生成模式。

測試檔案路徑：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。
- 在探測前從你的登入 shell (~/.profile) 載入供應商環境變數。
- 預設優先使用 live/env API 金鑰，避免 auth-profiles.json 中的過期金鑰干擾。
- 跳過沒有可用認證、設定檔或模型的供應商。
- 當供應商宣告 capabilities.edit.enabled 時，會同時執行 generate（僅提示詞輸入）與 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

AI Setup Assistant

Video generation live

OpenClaw video generation live 測試能確保你的影音生成功能在真實環境下運作正常。這些測試會執行共享的影音生成供應商路徑，並預設採用發布安全的冒煙測試路徑：不包含 FAL 供應商、每個供應商執行一次文字轉影片請求、使用一秒的 lobster 提示詞，並透過 OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS（預設為 180000）限制每個供應商的操作時間。

測試檔案：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
預設會跳過 FAL，因為供應商端的隊列延遲可能會影響發布時間；若要明確執行，請傳入 --video-providers fal 或設定 OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"。
測試會在探測前從你的登入 shell（~/.profile）載入供應商環境變數。
預設會優先使用 live/env API keys 而非儲存的驗證設定檔，確保 auth-profiles.json 中的過期測試金鑰不會覆蓋真實的 shell 憑證。
自動跳過沒有可用驗證、設定檔或模型的供應商。
預設僅執行 generate。
設定 OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 可在可用時執行宣告的轉換模式：
- 當供應商宣告 capabilities.imageToVideo.enabled 且選定的供應商/模型在共享掃描中接受緩衝區支援的本地圖像輸入時，執行 imageToVideo。
- 當供應商宣告 capabilities.videoToVideo.enabled 且選定的供應商/模型在共享掃描中接受緩衝區支援的本地影片輸入時，執行 videoToVideo。
目前在共享掃描中宣告但已跳過的 imageToVideo 供應商：
- vydra，因為內建的 veo3 僅支援文字，且內建的 kling 需要遠端圖像 URL。
供應商特定的 Vydra 覆蓋範圍：
- OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
- 該檔案會執行 veo3 文字轉影片，並預設包含一個使用遠端圖像 URL 固定裝置的 kling 通道。
目前的 videoToVideo live 覆蓋範圍：
- 僅在選定模型為 runway/gen4_aleph 時支援 runway。
目前在共享掃描中宣告但已跳過的 videoToVideo 供應商：
- 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。
- OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000 可縮短每個供應商的操作上限，進行更激進的冒煙測試。
選擇性驗證行為：
- OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 可強制使用設定檔儲存的驗證，並忽略僅限環境變數的覆蓋。

Media live harness

Media live harness 提供了一個統一的入口，讓你能夠輕鬆驗證各類媒體生成功能。它會自動處理環境變數載入與供應商篩選，確保測試流程的一致性。

指令：pnpm test:live:media
目的：
- 透過單一 repo 原生入口點執行共享的圖像、音樂與影片 live 套件。
- 從 ~/.profile 自動載入缺失的供應商環境變數。
- 預設將每個套件自動縮小範圍至目前擁有可用驗證的供應商。
- 重複使用 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

AI Setup Assistant

Docker runners (選用「Linux 環境驗證」)

這些 Docker runners 分為兩大類，協助你確保程式碼在 Linux 環境下的執行狀況：

Live-model runners：test:docker:live-models 和 test:docker:live-gateway 僅會在 repo 的 Docker 映像檔內執行對應的 profile-key live 檔案（分別為 src/agents/models.profiles.live.test.ts 和 src/gateway/gateway-models.profiles.live.test.ts），並掛載你的本地配置目錄與工作區（若有掛載則會 source ~/.profile）。對應的本地入口點為 test:live:models-profiles 和 test:live:gateway-profiles。
Docker live runners 預設會採用較小的 smoke cap，以確保完整的 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 建置一次 live Docker 映像檔，然後在兩個 live Docker 執行路徑中重複使用。
Container smoke runners：test:docker:openwebui、test:docker:onboard、test:docker:gateway-network、test:docker:mcp-channels 以及 test:docker:plugins 會啟動一個或多個真實容器，並驗證更高層級的整合路徑。

這些 live-model Docker runners 僅會 bind-mount 所需的 CLI 認證主目錄（若執行未受限則會掛載所有支援的目錄），並在執行前將其複製到容器主目錄，這樣外部 CLI OAuth 就能在不變更主機認證儲存的情況下重新整理 token：

Direct models：pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
ACP bind smoke：pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh)
CLI backend smoke：pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
Codex app-server harness smoke：pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
Gateway + dev agent：pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
Open WebUI live smoke：pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
Onboarding wizard (TTY, full scaffolding)：pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
Gateway networking (two containers, WS auth + health)：pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke)：pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
Plugins (install smoke + /plugin alias + Claude-bundle restart semantics)：pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh)

這些 live-model Docker runners 同時會將當前的 checkout 以唯讀方式 bind-mount，並將其暫存到容器內的臨時工作目錄。這能保持執行時映像檔的輕量化，同時仍能針對你精確的本地原始碼/配置執行 Vitest。暫存步驟會跳過大型的本地快取與應用程式建置輸出，例如 .pnpm-store、.worktrees、__openclaw_vitest__ 以及應用程式本地的 .build 或 Gradle 輸出目錄，確保 Docker live 執行不會花費數分鐘複製機器特定的產物。它們也會設定 OPENCLAW_SKIP_CHANNELS=1，確保 Gateway live 探測不會在容器內啟動真實的 Telegram/Discord 等頻道 worker。 test:docker:live-models 仍會執行 pnpm test:live，因此當你需要縮小或排除該 Docker 路徑的 Gateway live 覆蓋範圍時，請一併傳入 OPENCLAW_LIVE_GATEWAY_*。 test:docker:openwebui 是一種更高層級的相容性 smoke 測試：它會啟動一個 OpenClaw Gateway 容器並啟用 OpenAI 相容的 HTTP 端點，針對該 Gateway 啟動一個固定的 Open WebUI 容器，透過 Open WebUI 登入，驗證 /api/models 是否公開 openclaw/default，然後透過 Open WebUI 的 /api/chat/completions proxy 發送真實的聊天請求。首次執行可能會明顯較慢，因為 Docker 可能需要拉取 Open WebUI 映像檔，且 Open WebUI 可能需要完成自身的冷啟動設定。此路徑預期會有可用的 live model key，而 OPENCLAW_PROFILE_FILE（預設為 ~/.profile）是在 Docker 化執行中提供該 key 的主要方式。成功執行會印出類似 { "ok": true, "model": "openclaw/default", ... } 的小型 JSON 負載。 test:docker:mcp-channels 是刻意具備確定性的，不需要真實的 Telegram、Discord 或 iMessage 帳號。它會啟動一個已植入資料的 Gateway 容器，啟動第二個執行 openclaw mcp serve 的容器，然後驗證路由對話發現、文字記錄讀取、附件元資料、即時事件佇列行為、對外發送路由，以及透過真實 stdio MCP bridge 進行的 Claude 風格頻道與權限通知。通知檢查會直接檢視原始的 stdio MCP 影格，因此該 smoke 測試驗證的是 bridge 實際發出的內容，而不僅僅是特定客戶端 SDK 碰巧呈現的內容。

手動 ACP 純文字執行緒 smoke（非 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 並在執行測試前 source
OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 用於僅驗證從 OPENCLAW_PROFILE_FILE source 的環境變數，使用臨時配置/工作區目錄且不掛載外部 CLI 認證
OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (預設: ~/.cache/openclaw/docker-cli-tools) 掛載至 /home/node/.npm-global，用於 Docker 內部的快取 CLI 安裝
$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 確保憑證來自 profile 儲存庫（而非環境變數）
OPENCLAW_OPENWEBUI_MODEL=... 用於選擇 Gateway 為 Open WebUI smoke 暴露的模型
OPENCLAW_OPENWEBUI_PROMPT=... 用於覆寫 Open WebUI smoke 使用的 nonce-check 提示詞
OPENWEBUI_IMAGE=... 用於覆寫固定的 Open WebUI 映像檔標籤

文件健全性檢查

在編輯文件後執行文件檢查：pnpm check:docs。當你需要進行頁面內標題檢查時，執行完整的 Mintlify anchor 驗證：pnpm docs:check-links:anchors。

AI Setup Assistant

離線回歸測試 (CI-safe)

這些是無需真實供應商即可運行的「真實管線」回歸測試，確保系統在隔離環境下依然穩定。

Gateway 工具調用（模擬 OpenAI，使用真實 Gateway + agent loop）：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」）。

// Gateway tool calling test case
it("runs a mock OpenAI tool call end-to-end via gateway agent loop", async () => {
  // implementation details
});

// Gateway wizard test case
it("runs wizard over ws and writes auth token config", async () => {
  // implementation details
});

代理可靠性評估 (Skills)

我們目前已經擁有少量類似「代理可靠性評估」的 CI-safe 測試，這些測試能驗證 OpenClaw 在處理任務時的穩定性。

透過真實 Gateway + agent loop 進行模擬工具調用 (src/gateway/gateway.test.ts)。
端到端引導程式流程，用於驗證 session 連線與配置效果 (src/gateway/gateway.test.ts)。

針對 Skills 目前仍缺少的部分：

決策能力 (Decisioning)：當提示詞中列出多項技能時，代理是否能選出正確的技能，或避開不相關的技能？
合規性 (Compliance)：代理在使用前是否會閱讀 SKILL.md 並遵循必要的步驟與參數？
工作流合約 (Workflow contracts)：多輪對話場景，用於斷言工具執行順序、session 歷史記錄的延續性以及沙盒邊界。

未來的評估應優先保持確定性：

使用模擬供應商的場景執行器，以斷言工具調用與順序、技能檔案讀取以及 session 連線。
一套針對技能的小型測試套件（使用 vs 避免、門控、提示詞注入）。
僅在 CI-safe 套件就緒後，才考慮加入可選的即時評估（需選擇性加入，並透過環境變數進行限制）。

合約測試 (plugin and channel shape)

OpenClaw 合約測試能確保每個已註冊的 plugin 與 channel 都符合其介面合約。這些測試會遍歷所有已發現的 plugin，並執行一系列關於形狀與行為的斷言。預設的 pnpm test 單元測試流程會刻意跳過這些共享的介面與冒煙測試檔案；當你修改共享的 channel 或 provider 介面時，請務必明確執行合約測試指令。

指令

你可以透過以下指令來執行不同範圍的測試：

所有合約測試：pnpm test:contracts
僅執行 Channel 合約測試：pnpm test:contracts:channels
僅執行 Provider 合約測試：pnpm test:contracts:plugins

Channel 合約

這些測試位於 src/channels/plugins/contracts/*.contract.test.ts：

plugin - 基礎 plugin 形狀 (id, name, capabilities)
setup - 設定精靈合約
session-binding - Session 綁定行為
outbound-payload - 訊息 payload 結構
inbound - 入站訊息處理
actions - Channel 動作處理器
threading - Thread ID 處理
directory - Directory/roster API
group-policy - 群組政策執行

Provider 狀態合約

這些測試位於 src/plugins/contracts/*.contract.test.ts：

status - Channel 狀態探測
registry - Plugin 註冊表形狀

Provider 合約

這些測試位於 src/plugins/contracts/*.contract.test.ts：

auth - 驗證流程合約
auth-choice - 驗證選擇
catalog - 模型目錄 API
discovery - Plugin 發現機制
loader - Plugin 載入機制
runtime - Provider 執行環境
shape - Plugin 形狀/介面
wizard - 設定精靈

何時執行

修改 plugin-sdk 匯出內容或子路徑之後
新增或修改 channel 或 provider plugin 之後
重構 plugin 註冊或發現機制之後

合約測試會在 CI 中執行，且不需要真實的 API keys。

加入回歸測試 (指引)

當你在實際環境中修復了 provider 或模型的相關問題時，請參考以下建議來加入測試：

若可能，請加入 CI 安全的回歸測試（使用 mock/stub provider，或捕捉確切的請求形狀轉換）。
若問題僅限於實際環境（如速率限制、驗證政策），請保持該測試範圍狹窄，並透過環境變數進行選擇性執行。
優先針對能捕捉到錯誤的最小層級進行測試：
- 若是 provider 請求轉換或重放錯誤 → 直接進行模型測試。
- 若是 Gateway session/history/tool 管線錯誤 → 執行 Gateway 冒煙測試或 CI 安全的 Gateway mock 測試。
SecretRef 遍歷防護機制：
- src/secrets/exec-secret-ref-id-parity.test.ts 會從註冊表元數據 (listSecretTargetRegistryEntries()) 中為每個 SecretRef 類別導出一個採樣目標，然後斷言遍歷片段的執行 ID 是否被拒絕。
- 如果你在 src/secrets/target-registry-data.ts 中新增了 includeInPlan 的 SecretRef 目標系列，請務必更新該測試中的 classifyTargetClass。此測試會刻意在未分類的目標 ID 上失敗，以確保新的類別不會被默默跳過。

AI Setup Assistant

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 測試指南：單元、整合與 E2E 測試完整流程

快速開始

QA 專用執行器

測試套件（在哪裡執行什麼）

單元 / 整合測試（預設）

E2E（Gateway 冒煙測試）

E2E：OpenShell 後端冒煙測試

Live（真實 Provider + 真實 Model）

我應該執行哪個套件？

Android 節點功能掃描 (Live: Android node capability sweep)

模型冒煙測試 (Live: model smoke (profile keys))

第一層：直接模型完成測試 (無 Gateway)

第二層：Gateway + 開發 agent 冒煙測試 (OpenClaw 的實際運作方式)

CLI 後端冒煙測試 (Live: CLI backend smoke (Claude, Codex, Gemini, or other local CLIs))

ACP 綁定冒煙測試 (Live: ACP bind smoke (/acp spawn ... --bind here))

Live: Codex app-server harness smoke

Recommended live recipes

Live: model matrix (what we cover)

Modern smoke set (tool calling + image)

Baseline: tool calling (Read + optional Exec)

Vision: image send (attachment → multimodal message)

Aggregators / alternate gateways

Credentials (never commit)

Deepgram live (audio transcription)

BytePlus coding plan live

ComfyUI workflow media live

Image generation live

Music generation live

Video generation live

Media live harness

Docker runners (選用「Linux 環境驗證」)

文件健全性檢查

離線回歸測試 (CI-safe)

代理可靠性評估 (Skills)

合約測試 (plugin and channel shape)

指令

Channel 合約

Provider 狀態合約

Provider 合約

何時執行

加入回歸測試 (指引)

還是卡住了？

ACP 綁定冒煙測試 (Live: ACP bind smoke (`/acp spawn ... --bind here`))