OpenClaw 測試指南：從單元測試到真實 Provider 驗證

寫過 AI 應用的開發者都知道，最痛苦的不是寫程式碼，而是測試。有時候 Local 跑得好好的，上線後 Provider API 一改或 Gateway 網路一抖，整個 Bot 就掛了。

你需要一套能兼顧速度與真實性的測試流程，而不是每次都靠手動測試來燒錢。OpenClaw 提供了三種測試套件，讓你從快速的邏輯驗證到昂貴的真實環境測試都能輕鬆搞定。

需要準備的東西

在開始測試之前，請確保你已經準備好：

pnpm：用於執行所有測試指令
API Key：如果你要跑 Live 測試，需要準備對應 Provider 的憑證
Docker：如果你需要在 Linux 環境下驗證功能

快速開始

這是最快的路徑，建議你在 Push 程式碼之前，至少跑過一次完整的檢查：

# 完整檢查（建議推 code 前執行）
pnpm lint && pnpm build && pnpm test

# 執行單元測試並查看覆蓋率
pnpm test:coverage

# 執行 E2E 測試（驗證 Gateway 網路）
pnpm test:e2e

# 執行 Live 測試（使用真實 Provider，會產生費用）
pnpm test:live

Test Suites

OpenClaw 的測試分為三個等級，你可以根據目前的開發階段選擇合適的套件：

測試類型	指令	範圍	速度	需要 Key？	CI 執行
Unit / Integration	`pnpm test`	純邏輯、進程內整合、回歸測試	快 ⚡	否	是
E2E (Gateway Smoke)	`pnpm test:e2e`	多實例 Gateway、WebSocket、HTTP 面、節點配對	較慢	否	是 (需開啟)
Live (Real Providers)	`pnpm test:live`	對真實 Provider 發送 API 請求	視網路而定	是	否

如何選擇測試時機

修改邏輯或測試： 使用 pnpm test
調整 Gateway 網路架構： 增加 pnpm test:e2e
遇到「Bot 壞了」或 Provider 出問題： 使用縮小範圍的 pnpm test:live

Live Testing 詳細說明

Live 測試分為兩個層級，幫助你釐清問題出在哪：

第一層：直接模型測試 (Direct Model Completion)

路徑： src/agents/models.profiles.live.test.ts

這會跳過 Gateway 直接測試 Provider。當你想確認「是 API 壞了」還是「我的 Pipeline 壞了」時非常有用。

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

第二層：Gateway + Agent 冒煙測試

路徑： src/gateway/gateway-models.profiles.live.test.ts

這會測試完整的 Pipeline：Gateway → Agent → Model → Tools。包含讀取測試、執行與讀取測試，以及圖片 OCR 測試。

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

縮小 Live 測試範圍

為了省錢跟節省時間，建議使用 allowlists 只跑特定的模型：

# 單一模型，直接測試
OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts

# 單一模型，透過 Gateway
OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

# 同時測試多個 Provider
OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash-preview" pnpm test:live

Docker 測試環境

如果你想在 Linux 環境驗證功能，可以使用 Docker Runner：

pnpm test:docker:live-models       # 直接測試模型
pnpm test:docker:live-gateway      # Gateway + Agent
pnpm test:docker:onboard           # 註冊引導精靈
pnpm test:docker:gateway-network   # 雙容器網路測試
pnpm test:docker:plugins           # Plugin 載入測試

Docker 環境變數配置

變數	預設值	描述
`OPENCLAW_CONFIG_DIR`	`~/.openclaw`	掛載至 `/home/node/.openclaw`
`OPENCLAW_WORKSPACE_DIR`	`~/.openclaw/workspace`	掛載至 `/home/node/.openclaw/workspace`
`OPENCLAW_LIVE_GATEWAY_MODELS`	—	指定測試模型
`OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS`	`0`	強制僅使用 Profile 中的憑證

增加回歸測試 (Regressions)

當你修復了一個 Provider 或模型的問題後：

優先考慮 CI 安全： 儘可能使用 Mock 或 Stub 模擬 Provider。
必要時才用 Live： 保持測試範圍精確並使用環境變數隔離。
針對正確的層級：
- Provider 的 Bug → models.profiles.live.test.ts
- Pipeline 的 Bug → gateway-models.profiles.live.test.ts

疑難排解

如果你在測試中遇到問題，可以先檢查以下幾點：

API 壞了還是 Pipeline 壞了？ 先跑 Layer 1 測試（直接測試模型），如果 Layer 1 過了但 Layer 2 沒過，那就是 Gateway 或 Agent 的問題。
憑證問題： Live 測試會從 ~/.openclaw/credentials/、openclaw.json 或環境變數中尋找 Key。你可以執行 openclaw models list 確認目前的模型狀態。
Deepgram 測試失敗： 確保你有設定 DEEPGRAM_API_KEY=... 並開啟 DEEPGRAM_LIVE_TEST=1。

還是搞不定？我們的 AI Setup Assistant 可以幫你解決測試相關的問題。

下一步

Logging → — 暸解 Log 檔案與控制台輸出
Debugging → — 使用 Watch 模式與原始串流調試
Contributing → — 參與開發的指南

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。