測試

測試

OpenClaw 擁有三個 Vitest 套件（單元/整合、E2E、即時）以及一小組 Docker 執行器。

本文是一份「我們如何進行測試」的指南：

• 各個套件涵蓋的內容（以及刻意不涵蓋的內容）
• 針對常見工作流程（本地、推送前、除錯）應執行的指令
• 即時測試如何探索憑證並選擇模型/提供者
• 如何為真實世界的模型/提供者問題加入回歸測試

快速入門

大多數時候：

• 完整閘道（推送前預期執行）： pnpm build && pnpm check && pnpm test
• 在資源充足的機器上進行更快的本機完整套件執行： pnpm test:max

當您修改測試或需要更多信心時：

• 覆蓋率閘道： pnpm test:coverage
• E2E 套件： pnpm test:e2e

當除錯真實的提供商/模型時（需要真實憑證）：

• Live 套件（模型 + 閘道工具/圖像探測）： pnpm test:live
• 安靜地針對單一 Live 檔案： pnpm test:live -- src/agents/models.profiles.live.test.ts

提示：當您只需要一個失敗案例時，建議優先使用下文所述的允許清單環境變數來縮小 Live 測試範圍。

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

可以將這些測試套件視為「真實性遞增」（以及不穩定性/成本遞增）：

單元 / 整合（預設）

• 指令：pnpm test
• 設定：scripts/test-parallel.mjs（執行 vitest.unit.config.ts、vitest.extensions.config.ts、vitest.gateway.config.ts）
• 檔案：src/**/*.test.ts，打包的插件 **/*.test.ts
• 範圍：
  • 純單元測試
  • 程序內整合測試（gateway auth、routing、tooling、parsing、config）
  • 針對已知錯誤的決定性回歸測試
• 預期：
  • 在 CI 中執行
  • 不需要真實金鑰
  • 應快速且穩定
• 排程器備註：
  • pnpm test 目前會保留一個小型簽入的行為清單，用於真實的 pool/isolation 覆寫，以及另一個針對最慢單元檔案的計時快照。
  • 僅限擴充功能的本機執行現在也使用已提交的擴充功能計時快照，再加上在高記憶體主機上稍微粗略一點的共用批次目標，因此當兩次已測量的共用執行足夠時，共用擴充功能通道可避免產生額外的批次。
  • 高記憶體本機擴充功能共用批次現在也以比以前稍高的工作程序上限執行，這在不改變獨立擴充功能通道的情況下，縮短了剩餘的兩個共用擴充功能批次。
  • 高記憶體本機頻道執行現在重複使用已提交的頻道計時快照，將共用頻道通道分割成幾個已測量的批次，而不是一個長時間的共用工作程序。
  • 高記憶體本機頻道共用批次也以比共用單元批次稍低的工作程序上限執行，這有助於目標頻道重新執行避免 CPU 過度訂閱，一旦獨立頻道通道已在執行中。
  • 針對性的本機通道重新執行現在會提早一些開始分割共享通道工作，這能避免中等規模的針對性重新執行因一個過大的共享通道批次而成為關鍵路徑上的瓶頸。
  • 針對性的本機單元重新執行也會將中等規模的共享單元選擇分割為經過測量的批次，這有助於大型專注的重新執行進行重疊執行，而不是在單一漫長的共享單元通道後等待。
  • 高記憶體本機多表面執行也會使用略粗糙的共享 unit-fast 批次，因此混合規劃器在後續表面能夠重疊之前，花費在啟動額外共享單元工作者的時間會減少。
  • 共享單元、擴充功能、通道和閘道執行皆維持在 Vitest forks 上。
  • 此包裝器會將經過測量的分叉隔離例外與繁重的單例通道保持在 test/fixtures/test-parallel.behavior.json 中明確呈現。
  • 包裝器將測量到最重的檔案剝離到專用通道，而不是依賴不斷增加且需要手動維護的排除清單。
  • CLI 啟動效能基準測試現在具有不同的已儲存輸出：pnpm test:startup:bench:smoke 將目標的 smok e 檔案寫入 .artifacts/cli-startup-bench-smoke.json，pnpm test:startup:bench:save 將完整套件的檔案寫入 .artifacts/cli-startup-bench-all.json 並包含 runs=5 和 warmup=1，而 pnpm test:startup:bench:update 會使用 runs=5 和 warmup=1 重新整理簽入的 fixture（位於 test/fixtures/cli-startup-bench.json）。
  • 對於僅限介面的本機執行，單元、擴充功能和通道共享通道可以重疊其獨立的熱點，而不是在單一序列前綴後等待。
  • 對於多介面本機執行，wrapper 會保持共享介面階段的順序，但同一共享階段內的批次現在會一起擴展，延遲的獨立工作可以重疊下一個共享階段，而多餘的 unit-fast 頭空間現在會提早啟動該延遲工作，而不是讓那些插槽處於閒置狀態。
  • 在主要的套件形狀變更後，使用 pnpm test:perf:update-timings 和 pnpm test:perf:update-timings:extensions 重新整理時間快照。
• 嵌入式執行器注意事項：
  • 當您變更 message-tool 探索輸入或壓縮執行時間上下文時， 請保持兩個層級的覆蓋率。
  • 為純路由/正規化邊界新增專注的輔助回歸測試。
  • 同時保持嵌入式執行器整合套件的健康狀態： 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 路徑；僅輔助測試並非 這些整合路徑的充分替代方案。
• 集區注意事項：
  • 基礎 Vitest 設定仍然預設為 forks。
  • 單元、通道、擴充功能和 gateway wrapper 通道都預設為 forks。
  • 單元、通道和擴充功能設定預設為 isolate: false，以便更快地啟動檔案。
  • pnpm test 也會在 wrapper 層級傳遞 --isolate=false。
  • 使用 OPENCLAW_TEST_ISOLATE=1 pnpm test 重新選擇加入 Vitest 檔案隔離。
  • OPENCLAW_TEST_NO_ISOLATE=0 或 OPENCLAW_TEST_NO_ISOLATE=false 也會強制執行隔離執行。
• 快速本機迭代說明：
  • pnpm test:changed 使用 --changed origin/main 執行包裝器。
  • pnpm test:changed:max 保持相同的變更檔案篩選器，但使用包裝器的積極本機規劃器設定檔。
  • pnpm test:max 揭示相同的規劃器設定檔以進行完整的本機執行。
  • 在支援的本機 Node 版本（包括 Node 25）上，一般設定檔可以使用頂層通道平行處理。當您需要更積極的本機執行時，pnpm test:max 仍然會更用力地推動規劃器。
  • 基礎 Vitest 設定將包裝器清單/設定檔標記為 forceRerunTriggers，以便當排程器輸入變更時，變更模式重新執行能保持正確。
  • 包裝器在支援的主機上保持啟用 OPENCLAW_VITEST_FS_MODULE_CACHE，但會分配一個通道本機的 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH，以便並發的 Vitest 處理程序不會在一個共用的實驗性快取目錄上發生競爭。
  • 如果您想要一個用於直接單次執行分析的明確快取位置，請設定 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path。
• 效能除錯說明：
  • pnpm test:perf:imports 啟用 Vitest 匯入持續時間報告以及匯入分解輸出。
  • pnpm test:perf:imports:changed 將相同的分析視圖範圍限制在自 origin/main 以來變更的檔案。
  • pnpm test:perf:profile:main 為 Vitest/Vite 啟動和轉換負擔寫入主執行緒 CPU 設定檔。
  • pnpm test:perf:profile:runner 為停用檔案平行處理的單元套件寫入執行器 CPU + 堆積設定檔。

E2E (gateway smoke)

• 指令：pnpm test:e2e
• 設定：vitest.e2e.config.ts
• 檔案：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts
• 執行時期預設值：
  • 使用 Vitest forks 進行確定性的跨檔案隔離。
  • 使用自適應工作者 (CI：最多 2 個，本機：預設 1 個)。
  • 預設以靜默模式執行，以減少主控台 I/O 負擔。
• 有用的覆寫：
  • OPENCLAW_E2E_WORKERS=<n> 強制設定工作者數量（上限 16 個）。
  • OPENCLAW_E2E_VERBOSE=1 重新啟用詳細的主控台輸出。
• 範圍：
  • 多實例閘道端對端行為
  • WebSocket/HTTP 介面、節點配對以及較重的網路處理
• 預期：
  • 在 CI 中執行（當在管線中啟用時）
  • 不需要真實的金鑰
  • 比單元測試有更多運作部件（可能較慢）

E2E：OpenShell 後端冒煙測試

• 指令：pnpm test:e2e:openshell
• 檔案：test/openshell-sandbox.e2e.test.ts
• 範圍：
  • 透過 Docker 在主機上啟動隔離的 OpenShell 閘道
  • 從暫存的本地 Dockerfile 建立沙箱
  • 透過真實的 sandbox ssh-config + SSH exec 測試 OpenClaw 的 OpenShell 後端
  • 透過沙箱 fs 橋接器驗證遠端規範的檔案系統行為
• 預期：
  • 僅供選用；不是預設 pnpm test:e2e 執行的一部分
  • 需要本機 openshell CLI 以及可運作的 Docker 守護程序
  • 使用隔離的 HOME / XDG_CONFIG_HOME，然後銷毀測試閘道和沙箱
• 有用的覆寫：
  • OPENCLAW_E2E_OPENSHELL=1 用於在手動執行更廣泛的 e2e 套件時啟用此測試
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell 用於指向非預設的 CLI 二進位檔或包裝腳本

Live（真實供應商 + 真實模型）

• 指令：pnpm test:live
• 設定：vitest.live.config.ts
• 檔案：src/**/*.live.test.ts
• 預設：由 pnpm test:live 啟用（設定 OPENCLAW_LIVE_TEST=1）
• 範圍：
  • 「此供應商/模型在今天是否真的能使用真實憑證運作？」
  • 捕捉供應商格式變更、工具呼叫怪癖、驗證問題以及速率限制行為
• 預期：
  • 設計上不具 CI 穩定性（真實網路、真實供應商政策、配額、服務中斷）
  • 需要花費金錢 / 使用速率限制
  • 建議執行縮小的子集，而不是「全部」
• Live 執行會 source ~/.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 金鑰輪替（特定於提供者）：使用逗號/分號格式設定 *_API_KEYS 或 *_API_KEY_1、*_API_KEY_2（例如 OPENAI_API_KEYS、ANTHROPIC_API_KEYS、GEMINI_API_KEYS）或透過 OPENCLAW_LIVE_*_KEY 進行個別 live 覆寫；測試在收到速率限制回應時會重試。
• 進度/心跳輸出：
  • Live 測試套件現在會將進度行發送至 stderr，以便即使 Vitest 控制台擷取處於安靜狀態，冗長的提供者呼叫也能顯示為活動狀態。
  • vitest.live.config.ts 會停用 Vitest 控制台攔截，以便提供者/gateway 的進度行在 live 執行期間立即串流輸出。
  • 使用 OPENCLAW_LIVE_HEARTBEAT_MS 調整直接模型心跳。
  • 使用 OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS 調整 gateway/probe 心跳。

我應該執行哪個測試套件？

請使用此決策表：

• 編輯邏輯/測試：執行 pnpm test（如果您做了大量變更，則執行 pnpm test:coverage）
• 涉及 gateway 網路功能 / WS 協定 / 配對：新增 pnpm test:e2e
• 除錯「我的機器人當機了」/ 特定提供者失敗 / 工具呼叫：執行縮小範圍的 pnpm test:live

Live：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)

Live 測試分為兩層，以便我們隔離故障：

• 「直接模型」告訴我們供應商/模型是否能使用給定的金鑰進行回應。
• 「Gateway smoke」告訴我們完整的 gateway+agent 管線對該模型是否正常運作（sessions、history、tools、sandbox policy 等）。

Layer 1: Direct model completion (no 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 smoke
• 如何選擇模型：
  • OPENCLAW_LIVE_MODELS=modern 以執行 modern 允許清單（Opus/Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4）
  • OPENCLAW_LIVE_MODELS=all 是 modern 允許清單的別名
  • 或 OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-6,..."（逗號分隔允許清單）
• 如何選擇供應商：
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"（逗號分隔允許清單）
• 金鑰來源：
  • 預設：profile store 和 env 後備
  • 設定 OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 以僅強制執行 profile store
• 存在原因：
  • 將「供應商 API 故障 / 金鑰無效」與「gateway agent 管線故障」分開
  • 包含小型、獨立的迴歸測試（例如：OpenAI Responses/Codex Responses reasoning 重放 + tool-call 流程）

Layer 2: Gateway + dev agent smoke (what “@openclaw” actually does)

• 測試：src/gateway/gateway-models.profiles.live.test.ts
• 目標：
  • 啟動程序內 gateway
  • 建立/修補 agent:dev:* session（每次執行的模型覆蓋）
  • 迭代帶有金鑰的模型並斷言：
    • 「有意義的」回應（無工具）
    • 真實的工具調用正常運作（read probe）
    • 選用的額外工具探測（exec+read probe）
    • OpenAI 迴歸路徑（僅工具呼叫 → 後續追蹤）持續運作正常
• 探測詳細資訊（以便您快速解釋失敗原因）：
  • read 探測：測試在工作區寫入一個 nonce 檔案，並要求代理程式 read 它並回傳 nonce。
  • exec+read 探測：測試要求代理程式將 nonce exec-寫入到暫存檔，然後 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"（或逗號分隔清單）以縮小範圍
• 如何選擇供應商（避免「全部使用 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）
    • 嵌入式代理程式將多模態使用者訊息轉發給模型
    • 斷言：回覆包含 cat + 該代碼（OCR 容錯度：允許輕微錯誤）

提示：若要查看您可以在機器上測試什麼（以及確切的 provider/model ID），請執行：

openclaw models list
openclaw models list --json

即時：Anthropic setup-token 冒煙測試

• 測試：src/agents/anthropic.setup-token.live.test.ts
• 目標：驗證 Claude Code CLI setup-token（或貼上的 setup-token 設定檔）能否完成 Anthropic 提示。
• 啟用：
  • pnpm test:live (或 OPENCLAW_LIVE_TEST=1 若直接調用 Vitest)
  • OPENCLAW_LIVE_SETUP_TOKEN=1
• Token 來源 (擇一):
  • 設定檔: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
  • 原始 Token: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
• 模型覆寫 (選用):
  • OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-6

設定範例:

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

Live: CLI 後端冒煙測試 (Claude Code CLI 或其他本地 CLI)

• 測試: src/gateway/gateway-cli-backend.live.test.ts
• 目標: 使用本地 CLI 後端驗證 Gateway + agent 管線，而不修改您的預設配置。
• 啟用:
  • pnpm test:live (或 OPENCLAW_LIVE_TEST=1 若直接調用 Vitest)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• 預設值:
  • 模型: claude-cli/claude-sonnet-4-6
  • 指令: claude
  • 參數: ["-p","--output-format","json","--permission-mode","bypassPermissions"]
• 覆寫 (選用):
  • 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","json","--permission-mode","bypassPermissions"]'
  • OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
  • 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_DISABLE_MCP_CONFIG=0 以保持 Claude Code CLI MCP 配置啟用 (預設會使用暫時的空檔案停用 MCP 配置)。

範例:

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

Docker 配方:

pnpm test:docker:live-cli-backend

備註:

• Docker 執行器位於 scripts/test-live-cli-backend-docker.sh。
• 它會在儲存庫 Docker 映像檔內以非 root 使用者 node 身份執行 live CLI-backend 冒煙測試，因為 Claude CLI 在以 root 身分調用時會拒絕 bypassPermissions。
• 針對 claude-cli，它會將 Linux @anthropic-ai/claude-code 套件安裝到 OPENCLAW_DOCKER_CLI_TOOLS_DIR 的可寫入快取前綴 (預設: ~/.cache/openclaw/docker-cli-tools)。
• 當可用時，它會將 ~/.claude 複製到容器中，但在 Claude 驗證由 ANTHROPIC_API_KEY 支援的機器上，它也會透過 OPENCLAW_LIVE_CLI_BACKEND_PRESERVE_ENV 為子 Claude CLI 保留 ANTHROPIC_API_KEY / ANTHROPIC_API_KEY_OLD。

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

• Test: src/gateway/gateway-acp-bind.live.test.ts
• 目標：使用即時 ACP agent 驗證真實的 ACP conversation-bind 流程：
  • send /acp spawn <agent> --bind here
  • bind a synthetic message-channel conversation in place
  • send a normal follow-up on that same conversation
  • verify the follow-up lands in the bound ACP session transcript
• 啟用：
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• 預設值：
  • ACP agent: claude
  • Synthetic channel: Slack DM-style conversation context
  • ACP backend: acpx
• 覆寫：
  • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
  • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
  • OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=/full/path/to/acpx
• 註記：
  • 此通道使用具有僅限管理員的 synthetic originating-route 欄位的 gateway chat.send surface，以便測試可以附加 message-channel context 而無需假裝從外部傳遞。
  • 當 OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND 未設定時，測試會使用已配置/捆綁的 acpx 指令。如果您的 harness auth 取決於來自 ~/.profile 的環境變數，請優先使用保留 provider env 的自訂 acpx 指令。

範例：

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

Docker recipe:

pnpm test:docker:live-acp-bind

Docker notes:

• Docker runner 位於 scripts/test-live-acp-bind-docker.sh。
• 它來源於 ~/.profile，將匹配的 CLI auth home (~/.claude 或 ~/.codex) 複製到容器中，將 acpx 安裝到可寫入的 npm 前綴，然後如果缺少則安裝請求的即時 CLI (@anthropic-ai/claude-code 或 @openai/codex)。
• 在 Docker 內，runner 設定 OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx，以便 acpx 保留來自來源設定檔的 provider env vars 供子 harness CLI 使用。

推薦的即時配方

狹窄、明確的允許清單是最快且最不不穩定的：

• 單一模型，直接（無閘道）：

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

• 單一模型，閘道冒煙測試：

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

• 跨多個供應商的工具呼叫：

  • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,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 金鑰 + Antigravity）：

  • Gemini (API 金鑰): 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

備註：

• google/... 使用 Gemini API (API 金鑰)。
• google-antigravity/... 使用 Antigravity OAuth 橋接器 (Cloud Code Assist 風格的代理端點)。
• google-gemini-cli/... 使用您機器上的本機 Gemini CLI (獨立的驗證 + 工具怪癖)。
• Gemini API vs Gemini CLI：
  • API：OpenClaw 透過 HTTP 呼叫 Google 託管的 Gemini API (API 金鑰 / 設定檔驗證)；這是大多數使用者所指的「Gemini」。
  • CLI：OpenClaw 呼叫本機 gemini 二進位檔；它有自己的驗證方式，且可能表現不同 (串流/工具支援/版本差異)。

Live：模型矩陣 (涵蓋範圍)

沒有固定的「CI 模型清單」(live 是選用的)，但這些是在擁有金鑰的開發機上定期涵蓋的建議模型。

現代冒煙測試集 (工具呼叫 + 圖片)

這是我們期望持續運作的「通用模型」執行：

• OpenAI (非 Codex): openai/gpt-5.2 (選用: openai/gpt-5.1)
• 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

執行包含工具與圖片的閘道冒煙測試： OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,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

基準：工具呼叫 (讀取 + 選用執行)

每個供應商系列至少選擇一個：

• OpenAI: openai/gpt-5.2 (或 openai/gpt-5-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 支援視覺的變體等)，以測試圖片探測功能。

聚合器 / 替代閘道

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

• OpenRouter: openrouter/... (數百個模型；使用 openclaw models scan 來尋找支援工具和圖片的候選模型)
• OpenCode: opencode/... 用於 Zen 以及 opencode-go/... 用於 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 正常運作，即時測試應該會找到相同的金鑰。

• 如果即時測試顯示「沒有憑證」，請像偵錯 openclaw models list / 模型選擇一樣進行偵錯。

• 設定檔儲存：~/.openclaw/credentials/（首選；即測試中所指的「設定檔金鑰」）

• 設定：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）

• 即時本機執行預設會將使用中的設定加上認證儲存複製到暫存的測試家目錄；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

BytePlus 編碼計畫即時

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

影像生成即時

• 測試：src/image-generation/runtime.live.test.ts
• 指令：pnpm test:live src/image-generation/runtime.live.test.ts
• 範圍：
  • 列舉每個已註冊的影像生成提供者外掛程式
  • 在探測之前，從您的登入 shell（~/.profile）載入遺失的提供者環境變數
  • 預設優先使用即時/環境 API 金鑰而非儲存的認證設定檔，因此 auth-profiles.json 中的過時測試金鑰不會遮蔽真實的 shell 憑證
  • 略過沒有可用認證/設定檔/模型的提供者
  • 透過共享執行時期功能執行庫存影像生成變體：
    • 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 以強制使用設定檔儲存認證並忽略僅限環境變數的覆寫

Docker 執行程式（可選的「適用於 Linux」檢查）

這些 Docker 執行程式分為兩類：

• 即時模型執行程式：test:docker:live-models 和 test:docker:live-gateway 在儲存庫 Docker 映像檔內執行 pnpm test:live，掛載您的本機設定目錄和工作區（如果已掛載，則來源化 ~/.profile）。
• 容器冒煙執行程式：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)
• 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 網路功能 (兩個容器、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。它們也會設定 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 化執行中提供它的主要方式。成功的執行會列印一個小的 JSON 載荷，例如 { "ok": true, "model": "openclaw/default", ... }。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_CLI_TOOLS_DIR=... (預設： ~/.cache/openclaw/docker-cli-tools) 掛載至 /home/node/.npm-global 以用於 Docker 內的快取 CLI 安裝
• $HOME 下的外部 CLI 認證目錄會以唯讀方式掛載於 /host-auth/... 下，然後在測試開始前複製到 /home/node/...
  • 預設：掛載所有支援的目錄 (.codex, .claude, .minimax)
  • 縮小的供應商執行僅掛載從 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_LIVE_REQUIRE_PROFILE_KEYS=1 以確保憑證來自設定檔存放區（而非環境變數）
• 使用 OPENCLAW_OPENWEBUI_MODEL=... 以選擇由閘道為 Open WebUI smoke 測試公開的模型
• 使用 OPENCLAW_OPENWEBUI_PROMPT=... 以覆蓋 Open WebUI smoke 測試使用的 nonce 檢查提示詞
• 使用 OPENWEBUI_IMAGE=... 以覆蓋固定的 Open WebUI 映像檔標籤

文件檢查

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

離線迴歸測試 (CI-safe)

這些是沒有真實供應商的「真實管線」迴歸測試：

• 閘道工具呼叫 (模擬 OpenAI、真實閘道 + agent 迴圈)： 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”)

Agent 可靠性評估 (skills)

我們已經有幾個符合 CI 安全的測試，其行為類似於「agent reliability evals」：

• 透過真實的 gateway + agent 迴圈進行 Mock 工具呼叫 (src/gateway/gateway.test.ts)。
• 端到端的精靈流程，用於驗證 session 接線和配置效果 (src/gateway/gateway.test.ts)。

Skills 目前仍缺少的部分 (請參閱 Skills)：

• 決策： 當 prompt 中列出了 skills 時，agent 是否會選擇正確的 skill (或避免不相關的)？
• 合規性： agent 是否在使用前讀取 SKILL.md 並遵循必要的步驟/引數？
• 工作流程合約： 斷言工具順序、session 歷史傳遞和沙箱邊界的多輪對話場景。

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

• 使用 mock 提供者的場景執行器，以斷言工具呼叫 + 順序、skill 檔案讀取和 session 接線。
• 一小组專注於 skills 的場景 (使用 vs 避免、閘道、prompt 注入)。
• 可選的線上評估 (opt-in, env-gated) 僅在 CI 安全的測試套件就位後進行。

合約測試 (plugin 和 channel 形狀)

合約測試會驗證每個已註冊的 plugin 和 channel 是否符合其介面合約。它們會遍歷所有發現的 plugins 並執行一系列形狀和行為斷言。預設的 pnpm test 單元通道會刻意跳過這些共享的 seam 和 smoke 檔案；當您觸及共享的 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 - 目錄/名單 API
• group-policy - 群組策略執行

提供者狀態合約

位於 src/plugins/contracts/*.contract.test.ts。

• status - 頻道狀態探測
• registry - 外掛程式註冊表形狀

提供者合約

位於 src/plugins/contracts/*.contract.test.ts：

• auth - 驗證流程合約
• auth-choice - 驗證選擇/選取
• catalog - 模型目錄 API
• discovery - 外掛程式探索
• loader - 外掛程式載入
• runtime - 提供者執行時期
• shape - 外掛程式形狀/介面
• wizard - 設定精靈

何時執行

• 變更 plugin-sdk 匯出或子路徑之後
• 新增或修改頻道或提供者外掛程式之後
• 重構外掛程式註冊或探索之後

合約測試在 CI 中執行，不需要真實的 API 金鑰。

新增迴歸測試 (指導原則)

當您修復在 live 中發現的提供者/模型問題時：

• 如果可能的話，新增一個 CI 安全的迴歸測試 (模擬/存根提供者，或擷取確切的請求形狀轉換)
• 如果本質上僅限 live (速率限制、驗證策略)，請保持 live 測試狹窄，並透過環境變數選擇加入
• 優先針對能捕捉錯誤的最小層級：
  • 提供者請求轉換/重放錯誤 → 直接模型測試
  • 閘道會話/歷史/工具管線錯誤 → 閘道 live 冒煙測試或 CI 安全的閘道模擬測試
• SecretRef 遍歷防護機制：
  • src/secrets/exec-secret-ref-id-parity.test.ts 從註冊表元資料 (listSecretTargetRegistryEntries()) 為每個 SecretRef 類別衍生一個採樣目標，然後斷言遍歷區段 exec id 被拒絕。
  • 如果您在 src/secrets/target-registry-data.ts 中新增新的 includeInPlan SecretRef 目標家族，請在該測試中更新 classifyTargetClass。該測試會在未分類的目標 id 上故意失敗，以免新類別被無聲略過。