跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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

在臨時 live 檢查前先載入 ~/.profile，讓提供者金鑰和本機工具 路徑與你的 shell 相符： 
source ~/.profile
安全的媒體煙霧測試： 
pnpm openclaw infer tts convert --local --json \
  --text "OpenClaw live smoke." \
  --output /tmp/openclaw-live-smoke.mp3
安全的語音通話就緒煙霧測試： 
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 應用程式

​
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 容錯：允許小錯誤）
若要查看你的機器上可測試的項目（以及精確的 provider/model ID），請執行：
openclaw models list
openclaw models list --json

​
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 配方預設關閉，除非明確要求。
範例： 
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 設定煙霧測試： 
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 配方： 
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。
  • 它會在 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 探測變為嚴格。
範例： 
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
單一 agent Docker recipes： 
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： 
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： 
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 等）
不要在 docs 中 hardcode「all models」。權威清單是你機器上 discoverModels(...) 回傳的內容，加上可用的 keys。

​
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 煙霧測試： 
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

​
相關

  • 測試 - 單元、整合、QA 和 Docker 套件