---
read_when:
    - 執行即時模型矩陣 / CLI 後端 / ACP / media-provider 冒煙測試
    - 即時測試憑證解析偵錯
    - 新增一個提供者專屬的實際連線測試
sidebarTitle: Live tests
summary: 即時（觸及網路）測試：模型矩陣、CLI 後端、ACP、媒體提供者、憑證
title: 測試：即時測試套件
x-i18n:
    generated_at: "2026-05-10T19:38:41Z"
    model: gpt-5.5
    provider: openai
    source_hash: cb020672cd71d03b2cfc78b135c7c39862823c421c0f2f31bae69a42f9c3437f
    source_path: help/testing-live.md
    workflow: 16
---

如需快速開始、QA 執行器、單元/整合套件和 Docker 流程，請參閱
[測試](/zh-TW/help/testing)。本頁涵蓋 **live**（會觸及網路）的測試
套件：模型矩陣、CLI 後端、ACP 和媒體提供者 live 測試，以及
憑證處理。

## Live：本機設定檔煙霧命令

在臨時 live 檢查前先載入 `~/.profile`，讓提供者金鑰和本機工具
路徑與你的 shell 相符：

```bash
source ~/.profile
```

安全的媒體煙霧測試：

```bash
pnpm openclaw infer tts convert --local --json \
  --text "OpenClaw live smoke." \
  --output /tmp/openclaw-live-smoke.mp3
```

安全的語音通話就緒煙霧測試：

```bash
pnpm openclaw voicecall setup --json
pnpm openclaw voicecall smoke --to "+15555550123"
```

除非同時提供 `--yes`，否則 `voicecall smoke` 是 dry run。只有在你有意
撥出真實通知電話時才使用 `--yes`。對 Twilio、Telnyx 和
Plivo 來說，成功的就緒檢查需要公開 Webhook URL；local-only
loopback/私有後援會依設計遭拒。

## Live：Android Node 能力掃描

- 測試：`src/gateway/android-node.capabilities.live.test.ts`
- 腳本：`pnpm android:test:integration`
- 目標：叫用已連線 Android Node **目前宣告的每個命令**，並斷言命令契約行為。
- 範圍：
  - 已預先處理/手動設定（此套件不會安裝/執行/配對應用程式）。
  - 針對所選 Android Node 逐命令驗證 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 應用程式](/zh-TW/platforms/android)

## Live：模型煙霧測試（設定檔金鑰）

Live 測試分為兩層，方便我們隔離失敗：

- 「直接模型」告訴我們該提供者/模型能否使用指定金鑰回答。
- 「Gateway 煙霧測試」告訴我們完整 Gateway+agent 管線是否能為該模型運作（工作階段、歷史、工具、沙盒政策等）。

### 第 1 層：直接模型完成（無 Gateway）

- 測試：`src/agents/models.profiles.live.test.ts`
- 目標：
  - 列舉已探索的模型
  - 使用 `getApiKeyForModel` 選擇你有憑證的模型
  - 每個模型執行一次小型 completion（並在需要時執行目標式回歸測試）
- 啟用方式：
  - `pnpm test:live`（或在直接叫用 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
- 設定 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，modern 的別名）才會實際執行此套件；否則會略過，以讓 `pnpm test:live` 專注於 Gateway 煙霧測試
- 選擇模型的方式：
  - `OPENCLAW_LIVE_MODELS=modern` 會執行現代 allowlist（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
  - `OPENCLAW_LIVE_MODELS=all` 是現代 allowlist 的別名
  - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗號分隔 allowlist）
  - Modern/all 掃描預設使用精選高訊號上限；設定 `OPENCLAW_LIVE_MAX_MODELS=0` 可進行完整 modern 掃描，或設定正數作為較小上限。
  - 完整掃描會使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 作為整個直接模型測試逾時。預設值：60 分鐘。
  - 直接模型探測預設以 20 路平行執行；設定 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 可覆寫。
- 選擇提供者的方式：
  - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗號分隔 allowlist）
- 金鑰來源：
  - 預設：設定檔儲存區和環境變數後援
  - 設定 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以強制只使用 **設定檔儲存區**
- 存在原因：
  - 將「提供者 API 壞掉 / 金鑰無效」與「Gateway agent 管線壞掉」分開
  - 包含小型、隔離的回歸測試（範例：OpenAI Responses/Codex Responses 推理重播 + 工具呼叫流程）

### 第 2 層：Gateway + 開發 agent 煙霧測試（「@openclaw」實際做的事）

- 測試：`src/gateway/gateway-models.profiles.live.test.ts`
- 目標：
  - 啟動程序內 Gateway
  - 建立/修補 `agent:dev:*` 工作階段（每次執行覆寫模型）
  - 迭代有金鑰的模型並斷言：
    - 「有意義」的回應（無工具）
    - 真實工具叫用可運作（讀取探測）
    - 選用額外工具探測（執行+讀取探測）
    - 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`）
- 選擇模型的方式：
  - 預設：modern allowlist（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern allowlist 的別名
  - 或設定 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗號清單）以縮小範圍
  - Modern/all Gateway 掃描預設使用精選高訊號上限；設定 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可進行完整 modern 掃描，或設定正數作為較小上限。
- 選擇提供者的方式（避免「OpenRouter 全部」）：
  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗號分隔 allowlist）
- 此 live 測試一律啟用工具 + 圖片探測：
  - `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 容錯：允許小錯誤）

<Tip>
若要查看你的機器上可測試的項目（以及精確的 `provider/model` ID），請執行：

```bash
openclaw models list
openclaw models list --json
```

</Tip>

## Live：CLI 後端煙霧測試（Claude、Codex、Gemini 或其他本機 CLI）

- 測試：`src/gateway/gateway-cli-backend.live.test.ts`
- 目標：使用本機 CLI 後端驗證 Gateway + agent 管線，而不觸及你的預設設定。
- 後端專屬煙霧測試預設值位於所屬 extension 的 `cli-backend.ts` 定義中。
- 啟用：
  - `pnpm test:live`（或在直接叫用 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
  - `OPENCLAW_LIVE_CLI_BACKEND=1`
- 預設值：
  - 預設提供者/模型：`claude-cli/claude-sonnet-4-6`
  - 命令/引數/圖片行為來自所屬 CLI 後端 Plugin 中繼資料。
- 覆寫（選用）：
  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
  - `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` 可傳送真實圖片附件（路徑會注入 prompt）。Docker 配方預設關閉，除非明確要求。
  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 可將圖片檔案路徑作為 CLI 引數傳遞，而非注入 prompt。
  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）可在設定 `IMAGE_ARG` 時控制圖片引數的傳遞方式。
  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 可傳送第二回合並驗證續接流程。
  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 可在所選模型支援切換目標時，選擇加入 Claude Sonnet -> Opus 同工作階段連續性探測。Docker 配方為了整體可靠性預設關閉。
  - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 可選擇加入 MCP/工具 local loopback 探測。Docker 配方預設關閉，除非明確要求。

範例：

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

低成本 Gemini MCP 設定煙霧測試：

```bash
OPENCLAW_LIVE_TEST=1 \
  pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```

這不會要求 Gemini 產生回應。它會寫入 OpenClaw 提供給 Gemini 的相同系統
設定，然後執行 `gemini --debug mcp list`，以證明已儲存的
`transport: "streamable-http"` 伺服器會正規化為 Gemini 的 HTTP MCP
形狀，並可連線到本機 streamable-HTTP MCP 伺服器。

Docker 配方：

```bash
pnpm test:docker:live-cli-backend
```

單一提供者 Docker 配方：

```bash
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`。
- 它會在 repo Docker 映像中，以非 root 的 `node` 使用者執行 live CLI 後端煙霧測試。
- 它會從所屬 extension 解析 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` 需要透過含有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json` 或來自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`，提供可攜式 Claude Code 訂閱 OAuth。它會先證明 Docker 中的直接 `claude -p`，再執行兩個 Gateway CLI 後端回合，且不保留 Anthropic API 金鑰環境變數。此訂閱 lane 預設停用 Claude MCP/工具和圖片探測，因為 Claude 目前會將第三方應用程式使用量導向額外使用量計費，而非一般訂閱方案限制。
- Live CLI 後端煙霧測試現在會針對 Claude、Codex 和 Gemini 執行相同的端對端流程：文字回合、圖片分類回合，接著透過 Gateway CLI 驗證 MCP `cron` 工具呼叫。
- Claude 的預設煙霧測試也會將工作階段從 Sonnet 修補為 Opus，並驗證續接的工作階段仍記得先前的筆記。

## Live：APNs HTTP/2 Proxy 可達性

- 測試：`src/infra/push-apns-http2.live.test.ts`
- 目標：透過本機 HTTP CONNECT Proxy 通道連到 Apple 的沙盒 APNs 端點、送出 APNs HTTP/2 驗證請求，並斷言 Apple 真實的 `403 InvalidProviderToken` 回應會經由 Proxy 路徑傳回。
- 啟用：
  - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
- 選用逾時：
  - `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`

## Live：ACP 綁定煙霧測試（`/acp spawn ... --bind here`）

- 測試：`src/gateway/gateway-acp-bind.live.test.ts`
- 目標：使用即時 ACP agent 驗證真實的 ACP 對話綁定流程：
  - 傳送 `/acp spawn <agent> --bind here`
  - 在原處綁定一個合成的訊息頻道對話
  - 在同一個對話中傳送一般後續訊息
  - 驗證後續訊息落入已綁定的 ACP 工作階段 transcript
- 啟用：
  - `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=droid`
  - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini`
  - `OPENCLAW_LIVE_ACP_BIND_AGENT=opencode`
  - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
  - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
  - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5`
  - `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL=opencode/kimi-k2.6`
  - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_TRANSCRIPT=1`
  - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- 備註：
  - 此 lane 使用 Gateway `chat.send` surface，搭配僅限管理員的合成 originating-route 欄位，讓測試能附加訊息頻道情境，而不假裝向外部遞送。
  - 當 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未設定時，測試會使用內嵌 `acpx` Plugin 內建的 agent registry，對應選取的 ACP harness agent。
  - 預設情況下，已綁定工作階段的 cron MCP 建立採最佳努力，因為外部 ACP harnesses 可能會在 bind/image proof 通過後取消 MCP 呼叫；設定 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可讓該 bind 後 cron 探測變為嚴格。

範例：

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

Docker recipe：

```bash
pnpm test:docker:live-acp-bind
```

單一 agent Docker recipes：

```bash
pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:droid
pnpm test:docker:live-acp-bind:gemini
pnpm test:docker:live-acp-bind:opencode
```

Docker 備註：

- Docker runner 位於 `scripts/test-live-acp-bind-docker.sh`。
- 預設會依序針對彙總的即時 CLI agents 執行 ACP bind smoke：`claude`、`codex`，接著 `gemini`。
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 來縮小矩陣。
- 它會載入 `~/.profile`，將相符的 CLI auth material staged 到容器中，接著在缺少時安裝請求的即時 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、透過 `https://app.factory.ai/cli` 的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 後端本身是來自官方 `acpx` Plugin 的內嵌 `acpx/runtime` package。
- Droid Docker variant 會 staged `~/.factory` 作為 settings，轉送 `FACTORY_API_KEY`，且需要該 API key，因為本機 Factory OAuth/keyring auth 無法移植到容器中。它使用 ACPX 內建的 `droid exec --output-format acp` registry entry。
- OpenCode Docker variant 是嚴格的單一 agent regression lane。它在載入 `~/.profile` 後，從 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（預設 `opencode/kimi-k2.6`）寫入暫時的 `OPENCODE_CONFIG_CONTENT` 預設模型，而 `pnpm test:docker:live-acp-bind:opencode` 需要已綁定 assistant transcript，而非接受通用的 bind 後 skip。
- 直接的 `acpx` CLI 呼叫僅是用於在 Gateway 之外比較行為的手動/workaround 路徑。Docker ACP bind smoke 會測試 OpenClaw 的內嵌 `acpx` runtime 後端。

## 即時：Codex app-server harness smoke

- 目標：透過一般 Gateway `agent` method 驗證 Plugin 擁有的 Codex harness：
  - 載入 bundled `codex` Plugin
  - 選取 `openai/gpt-5.5`，這會預設將 OpenAI agent turns 路由 through Codex
  - 以選取的 Codex harness，向 `openai/gpt-5.5` 傳送第一個 Gateway agent turn
  - 傳送第二個 turn 到同一個 OpenClaw 工作階段，並驗證 app-server thread 可以恢復
  - 透過相同 Gateway command path 執行 `/codex status` 和 `/codex models`
  - 可選擇執行兩個 Guardian-reviewed escalated shell probes：一個應核准的 benign command，以及一個應拒絕的 fake-secret upload，讓 agent 回問
- 測試：`src/gateway/gateway-codex-harness.live.test.ts`
- 啟用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
- 預設模型：`openai/gpt-5.5`
- 選用 image probe：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 選用 MCP/tool probe：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- 選用 Guardian probe：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- smoke 會強制 provider/model `agentRuntime.id: "codex"`，因此損壞的 Codex harness 無法透過靜默 fallback 到 PI 而通過。
- Auth：來自本機 Codex subscription login 的 Codex app-server auth。Docker smokes 在適用時也可以為非 Codex probes 提供 `OPENAI_API_KEY`，以及選用複製的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。

本機 recipe：

```bash
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_GUARDIAN_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.5 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts
```

Docker recipe：

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

Docker 備註：

- Docker runner 位於 `scripts/test-live-codex-harness-docker.sh`。
- 它會載入 mounted `~/.profile`、傳遞 `OPENAI_API_KEY`、在存在時複製 Codex CLI auth files、將 `@openai/codex` 安裝到可寫入的 mounted npm prefix、stage source tree，接著只執行 Codex-harness 即時測試。
- Docker 預設會啟用 image、MCP/tool 和 Guardian probes。需要較窄的 debug run 時，請設定 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 使用相同的明確 Codex runtime config，因此 legacy aliases 或 PI fallback 無法隱藏 Codex harness regression。

### 建議的即時 recipes

狹窄且明確的 allowlists 最快且最不容易不穩定：

- 單一模型，直接（無 Gateway）：
  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`

- 單一模型，Gateway smoke：
  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

- 跨多個 providers 的 tool calling：
  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

- Google focus（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`

- Google adaptive thinking smoke：
  - 如果本機 keys 位於 shell profile：`source ~/.profile`
  - Gemini 3 dynamic default：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
  - Gemini 2.5 dynamic budget：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`

備註：

- `google/...` 使用 Gemini API（API key）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist-style agent endpoint）。
- `google-gemini-cli/...` 使用你機器上的本機 Gemini CLI（獨立 auth + tooling quirks）。
- Gemini API 與 Gemini CLI：
  - API：OpenClaw 透過 HTTP 呼叫 Google hosted Gemini API（API key / profile auth）；這是多數使用者所指的「Gemini」。
  - CLI：OpenClaw shell out 到本機 `gemini` binary；它有自己的 auth，且行為可能不同（streaming/tool support/version skew）。

## 即時：模型矩陣（涵蓋範圍）

沒有固定的「CI model list」（即時測試是 opt-in），但以下是在有 keys 的開發機上建議定期涵蓋的模型。

### 現代 smoke set（tool calling + image）

這是我們期望持續可用的「common models」run：

- OpenAI（非 Codex）：`openai/gpt-5.5`
- OpenAI Codex OAuth：`openai-codex/gpt-5.5`
- 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`
- DeepSeek：`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro`
- Z.AI（GLM）：`zai/glm-5.1`
- MiniMax：`minimax/MiniMax-M2.7`

使用 tools + image 執行 Gateway smoke：
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,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,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

### 基準：tool calling（Read + 選用 Exec）

每個 provider family 至少選一個：

- OpenAI：`openai/gpt-5.5`
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
- Google：`google/gemini-3-flash-preview`（或 `google/gemini-3.1-pro-preview`）
- DeepSeek：`deepseek/deepseek-v4-flash`
- Z.AI（GLM）：`zai/glm-5.1`
- MiniMax：`minimax/MiniMax-M2.7`

選用額外涵蓋範圍（nice to have）：

- xAI：`xai/grok-4.3`（或最新可用版本）
- Mistral：`mistral/`…（挑選一個你已啟用且具備「tools」能力的模型）
- Cerebras：`cerebras/`…（如果你有 access）
- LM Studio：`lmstudio/`…（本機；tool calling 取決於 API mode）

### Vision：image send（attachment → multimodal message）

在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一個具備 image 能力的模型（Claude/Gemini/OpenAI vision-capable variants 等），以 exercise image probe。

### Aggregators / alternate gateways

如果你已啟用 keys，我們也支援透過以下項目測試：

- OpenRouter：`openrouter/...`（數百個模型；使用 `openclaw models scan` 尋找具備 tool+image 能力的 candidates）
- OpenCode：Zen 用 `opencode/...`，Go 用 `opencode-go/...`（透過 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` auth）

可納入即時矩陣的更多 providers（如果你有 creds/config）：

- 內建：`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`（custom endpoints）：`minimax`（cloud/API），以及任何 OpenAI/Anthropic-compatible proxy（LM Studio、vLLM、LiteLLM 等）

<Tip>
不要在 docs 中 hardcode「all models」。權威清單是你機器上 `discoverModels(...)` 回傳的內容，加上可用的 keys。
</Tip>

## Credentials（絕不 commit）

即時測試會以 CLI 相同方式探索 credentials。實際含義：

- 如果 CLI 可運作，即時測試應該會找到相同的金鑰。
- 如果即時測試顯示「沒有憑證」，請用你偵錯 `openclaw models list` / 模型選擇的相同方式偵錯。

- 每個代理的驗證設定檔：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（這就是即時測試中「設定檔金鑰」的意思）
- 設定：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 舊版狀態目錄：`~/.openclaw/credentials/`（存在時會複製到暫存的即時主目錄，但不是主要的設定檔金鑰儲存區）
- 本機即時執行預設會將作用中的設定、每個代理的 `auth-profiles.json` 檔案、舊版 `credentials/`，以及支援的外部 CLI 驗證目錄複製到暫時測試主目錄；暫存的即時主目錄會略過 `workspace/` 和 `sandboxes/`，並移除 `agents.*.workspace` / `agentDir` 路徑覆寫，讓探測不會碰到你真實主機的工作區。

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

## Deepgram 即時測試（音訊轉錄）

- 測試：`extensions/deepgram/audio.live.test.ts`
- 啟用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`

## BytePlus 編碼計畫即時測試

- 測試：`extensions/byteplus/live.test.ts`
- 啟用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- 選用模型覆寫：`BYTEPLUS_CODING_MODEL=ark-code-latest`

## ComfyUI 工作流程媒體即時測試

- 測試：`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` 路徑
  - 除非已設定 `plugins.entries.comfy.config.<capability>`，否則略過每項能力
  - 在變更 comfy 工作流程提交、輪詢、下載或 Plugin 註冊後很有用

## 圖片生成即時測試

- 測試：`test/image-generation.runtime.live.test.ts`
- 指令：`pnpm test:live test/image-generation.runtime.live.test.ts`
- 測試框架：`pnpm test:live:media image`
- 範圍：
  - 列舉每個已註冊的圖片生成提供者 Plugin
  - 在探測前，從你的登入 shell（`~/.profile`）載入缺少的提供者環境變數
  - 預設優先使用即時/環境 API 金鑰，而不是已儲存的驗證設定檔，讓 `auth-profiles.json` 中過時的測試金鑰不會遮蔽真實的 shell 憑證
  - 略過沒有可用驗證/設定檔/模型的提供者
  - 透過共用圖片生成執行階段執行每個已設定的提供者：
    - `<provider>:generate`
    - 當提供者宣告支援編輯時，執行 `<provider>:edit`
- 目前涵蓋的隨附提供者：
  - `deepinfra`
  - `fal`
  - `google`
  - `minimax`
  - `openai`
  - `openrouter`
  - `vydra`
  - `xai`
- 選用縮小範圍：
  - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"`
  - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"`
  - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
  - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
- 選用驗證行為：
  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可強制使用設定檔儲存區驗證，並忽略僅環境變數的覆寫

對於已發布的 CLI 路徑，在提供者/執行階段即時測試通過後，新增一個 `infer` 煙霧測試：

```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
openclaw infer image providers --json
openclaw infer image generate \
  --model google/gemini-3.1-flash-image-preview \
  --prompt "Minimal flat test image: one blue square on a white background, no text." \
  --output ./openclaw-infer-image-smoke.png \
  --json
```

這涵蓋 CLI 引數解析、設定/預設代理解析、隨附 Plugin 啟用、共用圖片生成執行階段，以及即時提供者請求。Plugin 相依套件預期會在執行階段載入前存在。

## 音樂生成即時測試

- 測試：`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`）載入提供者環境變數
  - 預設優先使用即時/環境 API 金鑰，而不是已儲存的驗證設定檔，讓 `auth-profiles.json` 中過時的測試金鑰不會遮蔽真實的 shell 憑證
  - 略過沒有可用驗證/設定檔/模型的提供者
  - 可用時執行兩種已宣告的執行階段模式：
    - 使用僅含提示的輸入執行 `generate`
    - 當提供者宣告 `capabilities.edit.enabled` 時執行 `edit`
  - 目前共用通道涵蓋範圍：
    - `google`：`generate`、`edit`
    - `minimax`：`generate`
    - `comfy`：獨立的 Comfy 即時測試檔案，不屬於這個共用掃描
- 選用縮小範圍：
  - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
  - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- 選用驗證行為：
  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可強制使用設定檔儲存區驗證，並忽略僅環境變數的覆寫

## 影片生成即時測試

- 測試：`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 提供者、每個提供者一次文字轉影片請求、一秒的龍蝦提示，以及由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 提供的每提供者操作上限（預設為 `180000`）
  - 預設略過 FAL，因為提供者端佇列延遲可能主導發行時間；傳入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可明確執行它
  - 在探測前，從你的登入 shell（`~/.profile`）載入提供者環境變數
  - 預設優先使用即時/環境 API 金鑰，而不是已儲存的驗證設定檔，讓 `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` 即時涵蓋範圍：
    - 只有在選取的模型是 `runway/gen4_aleph` 時才涵蓋 `runway`
  - 目前在共用掃描中已宣告但略過的 `videoToVideo` 提供者：
    - `alibaba`、`qwen`、`xai`，因為這些路徑目前需要遠端 `http(s)` / MP4 參考 URL
    - `google`，因為目前的共用 Gemini/Veo 通道使用以本機緩衝區支援的輸入，而共用掃描不接受該路徑
    - `openai`，因為目前的共用通道缺少組織特定影片修補/混編存取保證
- 選用縮小範圍：
  - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,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` 可強制使用設定檔儲存區驗證，並忽略僅環境變數的覆寫

## 媒體即時測試框架

- 指令：`pnpm test:live:media`
- 目的：
  - 透過一個儲存庫原生進入點執行共用的圖片、音樂和影片即時測試套件
  - 從 `~/.profile` 自動載入缺少的提供者環境變數
  - 預設自動將每個套件縮小到目前有可用驗證的提供者
  - 重用 `scripts/test-live.mjs`，因此 Heartbeat 和安靜模式行為會保持一致
- 範例：
  - `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`

## 相關

- [測試](/zh-TW/help/testing) - 單元、整合、QA 和 Docker 套件