測試

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.

• 每個套件涵蓋的範圍（以及刻意_不_涵蓋的範圍）。
• 常見工作流程要執行哪些命令（本機、推送前、偵錯）。
• live 測試如何探索憑證並選擇模型/供應商。
• 如何為真實世界的模型/供應商問題加入迴歸測試。

​

快速開始

• 完整閘門（推送前預期執行）：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

• Live 套件（模型 + Gateway 工具/圖片探測）：pnpm test:live
• 安靜地指定一個 live 檔案：pnpm test:live -- src/agents/models.profiles.live.test.ts
• 執行時效能報告：派送 OpenClaw Performance，並使用 live_gpt54=true 來進行真實 openai/gpt-5.4 代理程式回合，或使用 deep_profile=true 來產生 Kova CPU/堆積/追蹤成品。每日排程執行會在 CLAWGRIT_REPORTS_TOKEN 已設定時，將 mock-provider、deep-profile 與 GPT 5.4 通道成品發布到 openclaw/clawgrit-reports。mock-provider 報告也包含原始碼層級的 Gateway 啟動、記憶體、 Plugin 壓力、重複 fake-model hello-loop，以及 CLI 啟動數據。
• Docker live 模型掃描：pnpm test:docker:live-models
  • 每個選取的模型現在會執行一個文字回合加上一個小型檔案讀取風格探測。 中繼資料宣告支援 image 輸入的模型也會執行一個微型圖片回合。 在隔離供應商失敗時，可用 OPENCLAW_LIVE_MODEL_FILE_PROBE=0 或 OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 停用額外探測。
  • CI 覆蓋範圍：每日 OpenClaw Scheduled Live And E2E Checks 與手動 OpenClaw Release Checks 都會以 include_live_suites: true 呼叫可重用的 live/E2E 工作流程， 其中包含依供應商分片的獨立 Docker live 模型矩陣作業。
  • 若要集中重新執行 CI，請以 include_live_suites: true 與 live_models_only: true 派送 OpenClaw Live And E2E Checks (Reusable)。
  • 將新的高訊號供應商祕密加入 scripts/ci-hydrate-live-auth.sh， 以及 .github/workflows/openclaw-live-and-e2e-checks-reusable.yml 和其 排程/發布呼叫端。
• 原生 Codex 繫結聊天煙霧測試：pnpm test:docker:live-codex-bind
  • 針對 Codex app-server 路徑執行 Docker live 通道，以 /codex bind 繫結合成 Slack DM，演練 /codex fast 與 /codex permissions，接著驗證純文字回覆與圖片附件會透過原生 Plugin 繫結路由，而非 ACP。
• Codex app-server harness 煙霧測試：pnpm test:docker:live-codex-harness
  • 透過 Plugin 擁有的 Codex app-server harness 執行 Gateway 代理程式回合， 驗證 /codex status 與 /codex models，並預設演練圖片、 cron MCP、子代理程式與 Guardian 探測。隔離其他 Codex app-server 失敗時，可用 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 停用子代理程式探測。若要集中檢查子代理程式，請停用其他探測： OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness。 除非設定 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0， 否則這會在子代理程式探測後結束。
• Codex 隨需安裝煙霧測試：pnpm test:docker:codex-on-demand
  • 在 Docker 中安裝已封裝的 OpenClaw tarball，執行 OpenAI API 金鑰 onboarding，並驗證 Codex Plugin 加上 @openai/codex 相依套件 已隨需下載到受管理的 npm 根目錄。
• Live Plugin 工具相依性煙霧測試：pnpm test:docker:live-plugin-tool
  • 封裝一個含有真實 slugify 相依套件的 fixture Plugin，透過 npm-pack: 安裝，驗證受管理 npm 根目錄下的相依套件，然後要求 live OpenAI 模型呼叫 Plugin 工具並回傳隱藏的 slug。
• Crestodian 救援命令煙霧測試：pnpm test:live:crestodian-rescue-channel
  • 針對訊息頻道救援命令介面的選用雙重保險檢查。 它會演練 /crestodian status、排入持久模型 變更、回覆 /crestodian yes，並驗證稽核/設定寫入路徑。
• Crestodian planner Docker 煙霧測試：pnpm test:docker:crestodian-planner
  • 在無設定的容器中執行 Crestodian，並在 PATH 上提供假的 Claude CLI， 驗證模糊 planner fallback 會轉換為已稽核的具型別設定寫入。
• Crestodian 首次執行 Docker 煙霧測試：pnpm test:docker:crestodian-first-run
  • 從空的 OpenClaw 狀態目錄開始，將裸 openclaw 路由到 Crestodian，套用 setup/model/agent/Discord Plugin + SecretRef 寫入， 驗證設定，並驗證稽核項目。相同的 Ring 0 設定路徑也由 QA Lab 中的 pnpm openclaw qa suite --scenario crestodian-ring-zero-setup 涵蓋。
• Moonshot/Kimi 成本煙霧測試：設定 MOONSHOT_API_KEY 後，執行 openclaw models list --provider moonshot --json，接著針對 moonshot/kimi-k2.6 執行隔離的 openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json。 驗證 JSON 報告 Moonshot/K2.6，且助理逐字稿儲存正規化的 usage.cost。

​

QA 專用執行器

• pnpm openclaw qa suite
  • 直接在主機上執行由 repo 支援的 QA 情境。
  • 預設會使用隔離的 gateway worker 平行執行多個選取的情境。qa-channel 預設並行數為 4（受限於選取的情境數量）。使用 --concurrency <count> 調整 worker 數量，或使用 --concurrency 1 走較舊的序列通道。
  • 當任何情境失敗時，以非零狀態結束。若你想取得成品但不想要失敗的結束碼，請使用 --allow-failures。
  • 支援 provider 模式 live-frontier、mock-openai 和 aimock。aimock 會啟動由本機 AIMock 支援的 provider 伺服器，用於實驗性的 fixture 與 protocol-mock 覆蓋率，而不會取代具情境感知能力的 mock-openai 通道。
• pnpm test:plugins:kitchen-sink-live
  • 透過 QA Lab 執行即時 OpenAI Kitchen Sink Plugin 測試套件。它會安裝外部 Kitchen Sink 套件、驗證 plugin SDK 介面清單、探測 /healthz 和 /readyz、記錄 Gateway CPU/RSS 證據、執行一次即時 OpenAI 回合，並檢查對抗式診斷。需要即時 OpenAI 驗證，例如 OPENAI_API_KEY。在已 hydrated 的 Testbox 工作階段中，若存在 openclaw-testbox-env helper，會自動載入 Testbox 即時驗證 profile。
• pnpm test:gateway:cpu-scenarios
  • 執行 Gateway 啟動 bench，以及一小組 mock QA Lab 情境包（channel-chat-baseline、memory-failure-fallback、gateway-restart-inflight-run），並在 .artifacts/gateway-cpu-scenarios/ 底下寫入合併的 CPU 觀察摘要。
  • 預設只標記持續性的高 CPU 觀察（--cpu-core-warn 加上 --hot-wall-warn-ms），因此短暫的啟動尖峰會被記錄為指標，而不會看起來像持續數分鐘的 Gateway 滿載迴歸。
  • 使用建置後的 dist 成品；若 checkout 中還沒有最新的 runtime 輸出，請先執行 build。
• pnpm openclaw qa suite --runner multipass
  • 在一次性的 Multipass Linux VM 中執行相同的 QA suite。
  • 保持與主機上 qa suite 相同的情境選取行為。
  • 重用與 qa suite 相同的 provider/model 選取旗標。
  • 即時執行會轉送適合 guest 使用且受支援的 QA 驗證輸入：以 env 為基礎的 provider 金鑰、QA 即時 provider config 路徑，以及存在時的 CODEX_HOME。
  • 輸出目錄必須維持在 repo root 底下，讓 guest 能透過掛載的 workspace 回寫。
  • 在 .artifacts/qa-e2e/... 底下寫入一般 QA 報告與摘要，以及 Multipass logs。
• pnpm qa:lab:up
  • 啟動由 Docker 支援的 QA 網站，用於 operator 風格的 QA 工作。
• pnpm test:docker:npm-onboard-channel-agent
  • 從目前 checkout 建置 npm tarball、在 Docker 中全域安裝、執行非互動式 OpenAI API-key onboarding、預設設定 Telegram、驗證封裝後的 plugin runtime 載入時不需要啟動依賴修復、執行 doctor，並針對 mocked OpenAI endpoint 執行一次本機 agent 回合。
  • 使用 OPENCLAW_NPM_ONBOARD_CHANNEL=discord 以 Discord 執行相同的 packaged-install 通道。
• pnpm test:docker:session-runtime-context
  • 針對嵌入式 runtime context transcripts 執行可重現的 built-app Docker smoke。它會驗證隱藏的 OpenClaw runtime context 會以非顯示 custom message 持久化，而不是洩漏到可見的 user turn，接著植入受影響的損壞 session JSONL，並驗證 openclaw doctor --fix 會將其重寫到 active branch 並建立備份。
• pnpm test:docker:npm-telegram-live
  • 在 Docker 中安裝 OpenClaw package candidate、執行 installed-package onboarding、透過已安裝的 CLI 設定 Telegram，然後以該已安裝套件作為 SUT Gateway，重用即時 Telegram QA 通道。
  • wrapper 只會從 checkout 掛載 qa-lab harness source；已安裝套件擁有 dist、openclaw/plugin-sdk 與 bundled plugin runtime，因此該通道不會把目前 checkout 的 plugins 混入受測套件。
  • 預設為 OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta；設定 OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz 或 OPENCLAW_CURRENT_PACKAGE_TGZ，即可測試已解析的本機 tarball，而不是從 registry 安裝。
  • 使用與 pnpm openclaw qa telegram 相同的 Telegram env credentials 或 Convex credential source。針對 CI/release automation，設定 OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex，加上 OPENCLAW_QA_CONVEX_SITE_URL 和 role secret。若 CI 中存在 OPENCLAW_QA_CONVEX_SITE_URL 與 Convex role secret，Docker wrapper 會自動選擇 Convex。
  • wrapper 會在 Docker build/install 工作前，先於主機上驗證 Telegram 或 Convex credential env。只有在刻意偵錯 pre-credential setup 時，才設定 OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1。
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer 只會針對此通道覆寫共用的 OPENCLAW_QA_CREDENTIAL_ROLE。
  • GitHub Actions 將此通道公開為手動 maintainer workflow NPM Telegram Beta E2E。它不會在 merge 時執行。該 workflow 使用 qa-live-shared environment 與 Convex CI credential leases。
• GitHub Actions 也公開 Package Acceptance，用於針對單一 candidate package 進行 side-run product proof。它接受受信任的 ref、已發布 npm spec、HTTPS tarball URL 加上 SHA-256，或來自另一個 run 的 tarball artifact，會上傳標準化的 openclaw-current.tgz 作為 package-under-test，然後使用 smoke、package、product、full 或 custom lane profiles 執行既有的 Docker E2E scheduler。設定 telegram_mode=mock-openai 或 live-frontier，即可針對相同的 package-under-test artifact 執行 Telegram QA workflow。
  • 最新 beta product proof：

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

• 精確 tarball URL proof 需要 digest：

gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

• Artifact proof 會從另一個 Actions run 下載 tarball artifact：

gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke

• pnpm test:docker:plugins
  • 在 Docker 中打包並安裝目前的 OpenClaw build、啟動已設定 OpenAI 的 Gateway，接著透過 config 編輯啟用 bundled channel/plugins。
  • 驗證 setup discovery 會讓未設定的 downloadable plugins 保持不存在、第一次設定後的 doctor repair 會明確安裝每個缺少的 downloadable plugin，且第二次重啟不會執行隱藏的依賴修復。
  • 也會安裝已知的較舊 npm baseline、在執行 openclaw update --tag <candidate> 前啟用 Telegram，並驗證 candidate 的 post-update doctor 會清理 legacy plugin dependency debris，而不需要 harness-side postinstall repair。
• pnpm test:parallels:npm-update
  • 跨 Parallels guests 執行原生 packaged-install update smoke。每個選取的平台會先安裝要求的 baseline package，然後在同一個 guest 中執行已安裝的 openclaw update 命令，並驗證已安裝版本、更新狀態、Gateway readiness，以及一次本機 agent 回合。
  • 迭代單一 guest 時，使用 --platform macos、--platform windows 或 --platform linux。使用 --json 取得 summary artifact path 與每個通道的狀態。
  • OpenAI 通道預設使用 openai/gpt-5.5 進行即時 agent-turn proof。若刻意驗證其他 OpenAI model，請傳入 --model <provider/model> 或設定 OPENCLAW_PARALLELS_OPENAI_MODEL。
  • 將長時間本機執行包在主機 timeout 中，避免 Parallels transport stall 消耗剩餘測試時間：
    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    
  • script 會在 /tmp/openclaw-parallels-npm-update.* 底下寫入巢狀通道 logs。在假設外層 wrapper 卡住前，先檢查 windows-update.log、macos-update.log 或 linux-update.log。
  • Windows update 在冷 guest 上可能會花 10 到 15 分鐘執行 post-update doctor 與 package update 工作；只要巢狀 npm debug log 持續推進，這仍然是正常狀態。
  • 不要將此 aggregate wrapper 與個別 Parallels macOS、Windows 或 Linux smoke lanes 平行執行。它們共用 VM 狀態，可能在 snapshot restore、package serving 或 guest Gateway state 上衝突。
  • post-update proof 會執行一般 bundled plugin surface，因為 speech、image generation 和 media understanding 等 capability facades 即使在 agent turn 本身只檢查簡單文字回應時，也會透過 bundled runtime APIs 載入。
• pnpm openclaw qa aimock
  • 只啟動本機 AIMock provider server，用於直接 protocol smoke testing。
• pnpm openclaw qa matrix
  • 針對一次性的 Docker-backed Tuwunel homeserver 執行 Matrix 即時 QA 通道。僅限 source-checkout，packaged installs 不會出貨 qa-lab。
  • 完整 CLI、profile/scenario catalog、env vars 與 artifact layout：Matrix QA。
• pnpm openclaw qa telegram
  • 使用來自 env 的 driver 與 SUT bot tokens，針對真實 private group 執行 Telegram 即時 QA 通道。
  • 需要 OPENCLAW_QA_TELEGRAM_GROUP_ID、OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN 和 OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN。group id 必須是數字 Telegram chat id。
  • 支援 --credential-source convex 以使用共用 pooled credentials。預設使用 env mode，或設定 OPENCLAW_QA_CREDENTIAL_SOURCE=convex 以選擇 pooled leases。
  • 預設涵蓋 canary、mention gating、command addressing、/status、bot-to-bot mentioned replies，以及 core native command replies。mock-openai 預設也涵蓋 deterministic reply-chain 與 Telegram final-message streaming 迴歸。使用 --list-scenarios 查看 session_status 等可選 probes。
  • 當任何情境失敗時，以非零狀態結束。若你想取得成品但不想要失敗的結束碼，請使用 --allow-failures。
  • 需要同一個 private group 中有兩個不同的 bots，且 SUT bot 必須公開 Telegram username。
  • 為了穩定觀察 bot-to-bot，請在 @BotFather 中為兩個 bots 啟用 Bot-to-Bot Communication Mode，並確保 driver bot 能觀察 group bot traffic。
  • 在 .artifacts/qa-e2e/... 底下寫入 Telegram QA report、summary 與 observed-messages artifact。回覆情境包含從 driver send request 到觀察到 SUT reply 的 RTT。

@Mantis telegram
@Mantis telegram scenario=telegram-status-command
@Mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

@Mantis telegram desktop proof

• pnpm openclaw qa mantis telegram-desktop-builder
  • 租用或重用 Crabbox Linux 桌面、安裝原生 Telegram Desktop、使用租用的 Telegram SUT bot token 設定 OpenClaw、啟動 Gateway，並從可見的 VNC 桌面錄製截圖/MP4 證據。
  • 預設為 --credential-source convex，因此工作流程只需要 Convex broker secret。若要使用與 pnpm openclaw qa telegram 相同的 OPENCLAW_QA_TELEGRAM_* 變數，請使用 --credential-source env。
  • Telegram Desktop 仍需要使用者登入/個人資料。bot token 只會設定 OpenClaw。對 base64 .tgz 個人資料封存檔使用 --telegram-profile-archive-env <name>，或使用 --keep-lease 並透過 VNC 手動登入一次。
  • 在輸出目錄下寫入 mantis-telegram-desktop-builder-report.md、mantis-telegram-desktop-builder-summary.json、telegram-desktop-builder.png 和 telegram-desktop-builder.mp4。

​

透過 Convex 共用 Telegram 憑證（v1）

• qa/convex-credential-broker/

• OPENCLAW_QA_CONVEX_SITE_URL（例如 https://your-deployment.convex.site）
• 所選角色的一個 secret：
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER 用於 maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI 用於 ci
• 憑證角色選擇：
  • CLI：--credential-role maintainer|ci
  • Env 預設值：OPENCLAW_QA_CREDENTIAL_ROLE（在 CI 中預設為 ci，否則為 maintainer）

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS（預設 1200000）
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS（預設 30000）
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS（預設 90000）
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS（預設 15000）
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX（預設 /qa-credentials/v1）
• OPENCLAW_QA_CREDENTIAL_OWNER_ID（選用 trace id）
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 允許 local-only 開發使用 loopback http:// Convex URLs。

pnpm openclaw qa credentials doctor
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>

• POST /acquire
  • Request: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Success: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Exhausted/retryable: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /payload-chunk
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Success: { status: "ok", index, data }
• POST /heartbeat
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Success: { status: "ok" }（或空的 2xx）
• POST /release
  • Request: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Success: { status: "ok" }（或空的 2xx）
• POST /admin/add（僅 maintainer secret）
  • Request: { kind, actorId, payload, note?, status? }
  • Success: { status: "ok", credential }
• POST /admin/remove（僅 maintainer secret）
  • Request: { credentialId, actorId }
  • Success: { status: "ok", changed, credential }
  • Active lease guard: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list（僅 maintainer secret）
  • Request: { kind?, status?, includePayload?, limit? }
  • Success: { status: "ok", credentials, count }

• { groupId: string, driverToken: string, sutToken: string }
• groupId 必須是數字 Telegram chat id string。
• admin/add 會針對 kind: "telegram" 驗證此 shape，並拒絕格式錯誤的 payloads。

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId、testerUserId 和 telegramApiId 必須是數字 strings。
• tdlibArchiveSha256 和 desktopTdataArchiveSha256 必須是 SHA-256 hex strings。
• kind: "telegram-user" 代表一個 Telegram burner account。請將租約視為 account-wide：TDLib CLI driver 與 Telegram Desktop visual witness 會從相同 payload 還原，且同一時間只應有一個工作持有該租約。

tmp=$(mktemp -d /tmp/openclaw-telegram-user.XXXXXX)
node --import tsx scripts/e2e/telegram-user-credential.ts lease-restore \
  --user-driver-dir "$tmp/user-driver" \
  --desktop-workdir "$tmp/desktop" \
  --lease-file "$tmp/lease.json"
TELEGRAM_USER_DRIVER_STATE_DIR="$tmp/user-driver" \
  uv run ~/.codex/skills/custom/telegram-e2e-bot-to-bot/scripts/user-driver.py status --json
node --import tsx scripts/e2e/telegram-user-credential.ts release --lease-file "$tmp/lease.json"

pnpm qa:telegram-user:crabbox -- start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review
pnpm qa:telegram-user:crabbox -- send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status
pnpm qa:telegram-user:crabbox -- finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

• send --session <file> --text <message> 會透過真實 TDLib 使用者送出，並等待 SUT reply。
• run --session <file> -- <remote command> 會在 Crabbox 上執行任意 command 並儲存其 output，例如 bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh && python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'。
• screenshot --session <file> 會擷取目前可見桌面。
• status --session <file> 會列印 lease 與 WebVNC command。
• finish --session <file> 會停止 recorder、擷取 screenshot/video/motion-trim artifacts、釋放 Convex credential、停止本機 SUT processes，並停止 Crabbox lease，除非傳入 --keep-box。
• publish --session <file> --pr <number> 預設會發布僅含 GIF 的 PR comment。只有在刻意需要 logs 或 JSON artifacts 時，才傳入 --full-artifacts。

pnpm qa:telegram-user:crabbox -- --text /status

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

​

將通道加入 QA

​

Test suites（在哪裡執行什麼）

​

Unit / integration（預設）

• Command: pnpm test
• Config: untargeted runs 會使用 vitest.full-*.config.ts shard set，並可能將 multi-project shards 展開為 per-project configs，以便 parallel scheduling
• Files: src/**/*.test.ts、packages/**/*.test.ts 和 test/**/*.test.ts 下的 core/unit inventories；UI unit tests 會在專用的 unit-ui shard 中執行
• Scope:
  • Pure unit tests
  • In-process integration tests（Gateway auth、routing、tooling、parsing、config）
  • 已知 bugs 的 deterministic regressions
• Expectations:
  • 在 CI 中執行
  • 不需要真實 keys
  • 應該快速且穩定
  • Resolver 與 public-surface loader tests 必須使用生成的 tiny Plugin fixtures 證明廣泛的 api.js 與 runtime-api.js fallback behavior，而不是使用真實 bundled Plugin source APIs。真實 Plugin API loads 屬於 Plugin-owned contract/integration suites。

• 預設測試安裝會略過可選的原生 Discord opus 建置。Discord 語音接收使用純 JS 的 opusscript 解碼器，而 @discordjs/opus 在 allowBuilds 中保持停用，因此本機測試與 Testbox lane 不會編譯原生 addon。
• 如果你刻意需要比較原生 opus 建置，請使用專用的 Discord 語音效能或 live lane。不要在預設 allowBuilds 中將 @discordjs/opus 設為 true；那會讓不相關的安裝/測試迴圈編譯原生程式碼。

​

穩定性（gateway）

• 命令：pnpm test:stability:gateway
• Config：vitest.gateway.config.ts，強制使用一個 worker
• 範圍：
  • 預設啟用 diagnostics 並啟動真實 loopback Gateway
  • 透過 diagnostic event path 驅動合成 gateway message、memory 與 large-payload churn
  • 透過 Gateway WS RPC 查詢 diagnostics.stability
  • 覆蓋 diagnostic stability bundle persistence helpers
  • 斷言 recorder 保持有界、合成 RSS sample 維持在 pressure budget 以下，且 per-session queue depth 會 drain 回零
• 預期：
  • CI-safe 且不需要 key
  • 用於 stability-regression follow-up 的窄 lane，不是完整 Gateway suite 的替代品

​

E2E（gateway smoke）

• 命令：pnpm test:e2e
• Config：vitest.e2e.config.ts
• 檔案：src/**/*.e2e.test.ts、test/**/*.e2e.test.ts，以及 extensions/ 底下的 bundled-plugin E2E 測試
• 執行期預設值：
  • 使用 Vitest threads 搭配 isolate: false，與 repo 其餘部分一致。
  • 使用 adaptive workers（CI：最多 2 個，本機：預設 1 個）。
  • 預設以 silent mode 執行，以降低 console I/O overhead。
• 實用 override：
  • OPENCLAW_E2E_WORKERS=<n> 強制指定 worker count（上限 16）。
  • OPENCLAW_E2E_VERBOSE=1 重新啟用 verbose console output。
• 範圍：
  • 多 instance gateway 端對端行為
  • WebSocket/HTTP surface、node pairing，以及較重的 networking
• 預期：
  • 在 CI 中執行（當 pipeline 啟用時）
  • 不需要真實 key
  • 比單元測試有更多 moving parts（可能較慢）

​

E2E：OpenShell backend smoke

• 命令：pnpm test:e2e:openshell
• 檔案：extensions/openshell/src/backend.e2e.test.ts
• 範圍：
  • 透過 Docker 在 host 上啟動隔離的 OpenShell gateway
  • 從暫時本機 Dockerfile 建立 sandbox
  • 透過真實 sandbox ssh-config + SSH exec 測試 OpenClaw 的 OpenShell backend
  • 透過 sandbox fs bridge 驗證 remote-canonical filesystem 行為
• 預期：
  • 僅 opt-in；不屬於預設 pnpm test:e2e 執行
  • 需要本機 openshell CLI 加上可運作的 Docker daemon
  • 使用隔離的 HOME / XDG_CONFIG_HOME，接著銷毀測試 gateway 與 sandbox
• 實用 override：
  • OPENCLAW_E2E_OPENSHELL=1 在手動執行較廣泛 e2e suite 時啟用該測試
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell 指向非預設 CLI binary 或 wrapper script

​

Live（真實 provider + 真實 model）

• 命令：pnpm test:live
• 設定：vitest.live.config.ts
• 檔案：src/**/*.live.test.ts、test/**/*.live.test.ts，以及 extensions/ 下的 bundled-plugin 即時測試
• 預設值：由 pnpm test:live 啟用（設定 OPENCLAW_LIVE_TEST=1）
• 範圍：
  • 「這個提供者/模型在 今天 使用真實憑證時是否真的可用？」
  • 捕捉提供者格式變更、工具呼叫特殊行為、驗證問題與速率限制行為
• 預期：
  • 設計上並非 CI 穩定（真實網路、真實提供者政策、配額、服務中斷）
  • 會花錢 / 使用速率限制配額
  • 偏好執行縮小範圍的子集，而不是「全部」
• 即時執行會 source ~/.profile 以取得缺少的 API 金鑰。
• 預設情況下，即時執行仍會隔離 HOME，並將設定/驗證材料複製到暫時測試 home，因此單元 fixture 無法變更你真正的 ~/.openclaw。
• 只有在你刻意需要即時測試使用你真正的 home 目錄時，才設定 OPENCLAW_LIVE_USE_REAL_HOME=1。
• pnpm test:live 現在預設採用較安靜的模式：保留 [live] ... 進度輸出，但抑制額外的 ~/.profile 通知，並靜音 Gateway bootstrap 記錄/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 做每次即時執行的覆寫；測試會在遇到速率限制回應時重試。
• 進度/Heartbeat 輸出：
  • 即時套件現在會將進度行輸出到 stderr，因此即使 Vitest 主控台擷取很安靜，長時間的提供者呼叫仍可看出正在活動。
  • vitest.live.config.ts 停用 Vitest 主控台攔截，因此提供者/Gateway 進度行會在即時執行期間立即串流。
  • 使用 OPENCLAW_LIVE_HEARTBEAT_MS 調整直接模型 Heartbeat。
  • 使用 OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS 調整 Gateway/探測 Heartbeat。

​

我應該執行哪個套件？

• 編輯邏輯/測試：執行 pnpm test（如果你變更很多，也執行 pnpm test:coverage）
• 觸及 Gateway 網路 / WS 協定 / 配對：加上 pnpm test:e2e
• 偵錯「我的 bot 掛了」/ 提供者特定失敗 / 工具呼叫：執行縮小範圍的 pnpm test:live

​

即時（觸及網路）測試

​

Docker runner（選用的「可在 Linux 運作」檢查）

• 即時模型 runner：test:docker:live-models 和 test:docker:live-gateway 只會在 repo Docker 映像中執行各自相符的 profile-key 即時檔案（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 即時 runner 預設使用較小的 smoke 上限，讓完整 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。只有在你明確想要較大的完整掃描時， 才覆寫這些 env var。
• test:docker:all 會先透過 test:docker:live-build 建置一次即時 Docker 映像，接著透過 scripts/package-openclaw-for-docker.mjs 將 OpenClaw 封裝一次為 npm tarball，然後建置/重用兩個 scripts/e2e/Dockerfile 映像。bare 映像只是用於安裝/更新/Plugin 相依性 lane 的 Node/Git runner；這些 lane 會掛載預先建置的 tarball。functional 映像會將同一個 tarball 安裝到 /app，用於已建置 app 功能 lane。Docker lane 定義位於 scripts/lib/docker-e2e-scenarios.mjs；規劃器邏輯位於 scripts/lib/docker-e2e-plan.mjs；scripts/test-docker-all.mjs 會執行選取的計畫。彙總使用加權本機排程器：OPENCLAW_DOCKER_ALL_PARALLELISM 控制處理程序 slot，而資源上限會避免繁重即時、npm-install 與多服務 lane 全部同時啟動。如果單一 lane 比目前上限更重，排程器仍可在 pool 為空時啟動它，然後讓它單獨執行，直到容量再次可用。預設值為 10 個 slot、OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9、OPENCLAW_DOCKER_ALL_NPM_LIMIT=10 與 OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7；只有在 Docker host 有更多餘裕時，才調整 OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT 或 OPENCLAW_DOCKER_ALL_DOCKER_LIMIT。runner 預設會執行 Docker preflight、移除過期的 OpenClaw E2E container、每 30 秒列印狀態、將成功 lane 計時儲存在 .artifacts/docker-tests/lane-timings.json，並在後續執行時使用這些計時優先啟動較長的 lane。使用 OPENCLAW_DOCKER_ALL_DRY_RUN=1 可列印加權 lane manifest，而不建置或執行 Docker；或使用 node scripts/test-docker-all.mjs --plan-json 列印所選 lane、package/image 需求與憑證的 CI 計畫。
• Package Acceptance 是 GitHub 原生套件 gate，用於判斷「這個可安裝 tarball 是否能作為產品運作？」它會從 source=npm、source=ref、source=url 或 source=artifact 解析一個候選套件，將其上傳為 package-under-test，然後針對該確切 tarball 執行可重用的 Docker E2E lane，而不是重新封裝所選 ref。profile 依廣度排序為：smoke、package、product 和 full。關於套件/更新/Plugin 合約、已發布升級 survivor 矩陣、release 預設值與失敗分流，請參閱測試更新與 Plugin。
• 建置與 release 檢查會在 tsdown 後執行 scripts/check-cli-bootstrap-imports.mjs。guard 會從 dist/entry.js 和 dist/cli/run-main.js 巡覽靜態建置圖，並在命令分派前的 pre-dispatch startup 匯入 Commander、prompt UI、undici 或 logging 等套件相依性時失敗；它也會讓 bundled Gateway run chunk 保持在預算內，並拒絕已知 cold Gateway 路徑的靜態匯入。已封裝 CLI smoke 也涵蓋 root help、onboard help、doctor help、status、config schema，以及 model-list 命令。
• 套件驗收舊版相容性上限為 2026.4.25（包含 2026.4.25-beta.*）。在該截止點之前，harness 只容忍已出貨套件的 metadata 缺口：省略的 private QA inventory 項目、缺少 gateway install --wrapper、tarball 衍生 git fixture 中缺少 patch 檔案、缺少持久化的 update.channel、舊版 Plugin 安裝記錄位置、缺少 marketplace 安裝記錄持久化，以及 plugins update 期間的設定 metadata 遷移。對於 2026.4.25 之後的套件，這些路徑都是嚴格失敗。
• Container smoke runner：test:docker:openwebui、test:docker:onboard、test:docker:npm-onboard-channel-agent、test:docker:skill-install、test:docker:update-channel-switch、test:docker:upgrade-survivor、test:docker:published-upgrade-survivor、test:docker:session-runtime-context、test:docker:agents-delete-shared-workspace、test:docker:gateway-network、test:docker:browser-cdp-snapshot、test:docker:mcp-channels、test:docker:pi-bundle-mcp-tools、test:docker:cron-mcp-cleanup、test:docker:plugins、test:docker:plugin-update、test:docker:plugin-lifecycle-matrix 和 test:docker:config-reload 會啟動一個或多個真實 container，並驗證較高層級的整合路徑。

• 直接模型：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；預設涵蓋 Claude、Codex 和 Gemini，並透過 pnpm test:docker:live-acp-bind:droid 和 pnpm test:docker:live-acp-bind:opencode 嚴格涵蓋 Droid/OpenCode）
• CLI 後端煙霧測試：pnpm test:docker:live-cli-backend（指令碼：scripts/test-live-cli-backend-docker.sh）
• Codex app-server harness 煙霧測試：pnpm test:docker:live-codex-harness（指令碼：scripts/test-live-codex-harness-docker.sh）
• Gateway + 開發代理程式：pnpm test:docker:live-gateway（指令碼：scripts/test-live-gateway-models-docker.sh）
• 可觀測性煙霧測試：pnpm qa:otel:smoke 是私人 QA 原始碼 checkout 路徑。它刻意不屬於套件 Docker 發行路徑，因為 npm tarball 會省略 QA Lab。
• Open WebUI 即時煙霧測試：pnpm test:docker:openwebui（指令碼：scripts/e2e/openwebui-docker.sh）
• 入門精靈（TTY、完整 scaffold）：pnpm test:docker:onboard（指令碼：scripts/e2e/onboard-docker.sh）
• Npm tarball 入門/頻道/代理程式煙霧測試：pnpm test:docker:npm-onboard-channel-agent 會在 Docker 中全域安裝已打包的 OpenClaw tarball，透過 env-ref 入門流程設定 OpenAI，並預設設定 Telegram，執行 doctor，然後執行一次模擬的 OpenAI 代理程式回合。使用 OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz 重用預先建置的 tarball，使用 OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 跳過主機重建，或使用 OPENCLAW_NPM_ONBOARD_CHANNEL=discord 或 OPENCLAW_NPM_ONBOARD_CHANNEL=slack 切換頻道。
• Skill 安裝煙霧測試：pnpm test:docker:skill-install 會在 Docker 中全域安裝已打包的 OpenClaw tarball，在設定中停用上傳封存檔安裝，從搜尋解析目前即時 ClawHub skill slug，使用 openclaw skills install 安裝它，並驗證已安裝的 skill 以及 .clawhub origin/lock 中繼資料。
• 更新頻道切換煙霧測試：pnpm test:docker:update-channel-switch 會在 Docker 中全域安裝已打包的 OpenClaw tarball，從套件 stable 切換到 git dev，驗證持久化頻道和 Plugin 更新後運作，接著切回套件 stable 並檢查更新狀態。
• 升級倖存者煙霧測試：pnpm test:docker:upgrade-survivor 會將已打包的 OpenClaw tarball 安裝到一個髒的舊使用者 fixture 上，其中包含代理程式、頻道設定、Plugin allowlists、過期的 Plugin 依賴狀態，以及既有 workspace/session 檔案。它會在沒有即時供應商或頻道金鑰的情況下執行套件更新與非互動式 doctor，然後啟動 local loopback Gateway，並檢查設定/狀態保留以及啟動/狀態預算。
• 已發布升級倖存者煙霧測試：pnpm test:docker:published-upgrade-survivor 預設會安裝 openclaw@latest，植入逼真的既有使用者檔案，用 baked command recipe 設定該基準，驗證產生的設定，將該已發布安裝更新到候選 tarball，執行非互動式 doctor，寫入 .artifacts/upgrade-survivor/summary.json，然後啟動 local loopback Gateway，並檢查已設定 intents、狀態保留、啟動、/healthz、/readyz 和 RPC 狀態預算。使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 覆寫單一基準，使用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 要求彙總排程器展開精確本機基準，例如 openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15，並使用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS 展開 issue 形狀的 fixtures，例如 reported-issues；reported-issues 集合包含 configured-plugin-installs，用於自動外部 OpenClaw Plugin 安裝修復。Package Acceptance 會將這些公開為 published_upgrade_survivor_baseline、published_upgrade_survivor_baselines 和 published_upgrade_survivor_scenarios，解析像 last-stable-4 或 all-since-2026.4.23 這類中繼基準 token，而 Full Release Validation 會將 release-soak 套件 gate 展開為 last-stable-4 2026.4.23 2026.5.2 2026.4.15 加上 reported-issues。
• Session runtime context 煙霧測試：pnpm test:docker:session-runtime-context 會驗證隱藏 runtime context transcript 持久化，以及 doctor 修復受影響的重複 prompt-rewrite 分支。
• Bun 全域安裝煙霧測試：bash scripts/e2e/bun-global-install-smoke.sh 會打包目前樹狀結構，在隔離 home 中用 bun install -g 安裝，並驗證 openclaw infer image providers --json 會回傳 bundled image providers，而不是卡住。使用 OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz 重用預先建置的 tarball，使用 OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 跳過主機建置，或使用 OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local 從已建置的 Docker 映像複製 dist/。
• 安裝器 Docker 煙霧測試：bash scripts/test-install-sh-docker.sh 會在其 root、update 和 direct-npm 容器之間共用一個 npm 快取。Update 煙霧測試在升級到候選 tarball 前，預設以 npm latest 作為 stable 基準。在本機使用 OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 覆寫，或在 GitHub 上使用 Install Smoke workflow 的 update_baseline_version 輸入覆寫。非 root 安裝器檢查會保留隔離的 npm 快取，避免 root 擁有的快取項目遮蔽使用者本機安裝行為。設定 OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache，可在本機重跑時重用 root/update/direct-npm 快取。
• Install Smoke CI 使用 OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1 跳過重複的 direct-npm 全域更新；需要直接 npm install -g 覆蓋時，請在本機執行不帶該 env 的指令碼。
• Agents 刪除共用 workspace CLI 煙霧測試：pnpm test:docker:agents-delete-shared-workspace（指令碼：scripts/e2e/agents-delete-shared-workspace-docker.sh）預設會建置根 Dockerfile 映像，在隔離容器 home 中植入兩個代理程式與一個 workspace，執行 agents delete --json，並驗證有效 JSON 以及保留 workspace 的行為。使用 OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1 重用 install-smoke 映像。
• Gateway 網路（兩個容器、WS 驗證 + health）：pnpm test:docker:gateway-network（指令碼：scripts/e2e/gateway-network-docker.sh）
• Browser CDP snapshot 煙霧測試：pnpm test:docker:browser-cdp-snapshot（指令碼：scripts/e2e/browser-cdp-snapshot-docker.sh）會建置 source E2E 映像加上一個 Chromium layer，以原始 CDP 啟動 Chromium，執行 browser doctor --deep，並驗證 CDP role snapshots 涵蓋 link URLs、cursor-promoted clickables、iframe refs 和 frame metadata。
• OpenAI Responses web_search minimal reasoning regression：pnpm test:docker:openai-web-search-minimal（指令碼：scripts/e2e/openai-web-search-minimal-docker.sh）會透過 Gateway 執行模擬的 OpenAI server，驗證 web_search 會將 reasoning.effort 從 minimal 提高到 low，然後強制供應商 schema reject，並檢查原始 detail 會出現在 Gateway logs 中。
• MCP 頻道橋接（植入的 Gateway + stdio bridge + 原始 Claude notification-frame 煙霧測試）：pnpm test:docker:mcp-channels（指令碼：scripts/e2e/mcp-channels-docker.sh）
• Pi bundle MCP tools（真實 stdio MCP server + embedded Pi profile allow/deny 煙霧測試）：pnpm test:docker:pi-bundle-mcp-tools（指令碼：scripts/e2e/pi-bundle-mcp-tools-docker.sh）
• Cron/subagent MCP cleanup（真實 Gateway + stdio MCP child 在隔離 cron 和一次性 subagent 執行後 teardown）：pnpm test:docker:cron-mcp-cleanup（指令碼：scripts/e2e/cron-mcp-cleanup-docker.sh）
• Plugins（本機路徑、file:、具 hoisted dependencies 的 npm registry、git moving refs、ClawHub kitchen-sink、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 煙霧測試）：pnpm test:docker:plugins（指令碼：scripts/e2e/plugins-docker.sh） 設定 OPENCLAW_PLUGINS_E2E_CLAWHUB=0 可跳過 ClawHub 區塊，或使用 OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC 和 OPENCLAW_PLUGINS_E2E_CLAWHUB_ID 覆寫預設的 kitchen-sink package/runtime 配對。若沒有 OPENCLAW_CLAWHUB_URL/CLAWHUB_URL，測試會使用 hermetic 本機 ClawHub fixture server。
• Plugin 更新 unchanged 煙霧測試：pnpm test:docker:plugin-update（指令碼：scripts/e2e/plugin-update-unchanged-docker.sh）
• Plugin 生命週期矩陣煙霧測試：pnpm test:docker:plugin-lifecycle-matrix 會在裸容器中安裝已打包的 OpenClaw tarball，安裝 npm Plugin，切換啟用/停用，透過本機 npm registry 對其升級與降級，刪除已安裝的程式碼，接著驗證 uninstall 仍會移除過期狀態，同時記錄每個生命週期階段的 RSS/CPU metrics。
• 設定 reload metadata 煙霧測試：pnpm test:docker:config-reload（指令碼：scripts/e2e/config-reload-source-docker.sh）
• Plugins：pnpm test:docker:plugins 涵蓋本機路徑、file:、具 hoisted dependencies 的 npm registry、git moving refs、ClawHub fixtures、marketplace updates，以及 Claude-bundle enable/inspect 的 install/update 煙霧測試。pnpm test:docker:plugin-update 涵蓋已安裝 Plugin 的 unchanged update 行為。pnpm test:docker:plugin-lifecycle-matrix 涵蓋具資源追蹤的 npm Plugin install、enable、disable、upgrade、downgrade，以及 missing-code uninstall。

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• 保留此 script 供 regression/debug workflow 使用。ACP thread routing validation 可能還會再次需要它，因此不要刪除。

• 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 的 env vars，使用臨時 config/workspace dirs，且不掛載外部 CLI auth
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=...（預設：~/.cache/openclaw/docker-cli-tools）掛載到 /home/node/.npm-global，用於 Docker 內快取的 CLI 安裝
• $HOME 底下的外部 CLI auth dirs/files 會以唯讀方式掛載到 /host-auth... 下，接著在測試開始前複製到 /home/node/...
  • 預設 dirs：.minimax
  • 預設 files：~/.codex/auth.json、~/.codex/config.toml、.claude.json、~/.claude/.credentials.json、~/.claude/settings.json、~/.claude/settings.local.json
  • 縮窄範圍的 provider 執行只會掛載從 OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS 推斷出的必要 dirs/files
  • 可用 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=... 用於在容器內篩選 providers
• OPENCLAW_SKIP_DOCKER_BUILD=1 可在不需要重新建置的重跑中重用既有的 openclaw:local-live 映像
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 用於確保 creds 來自 profile store（而不是 env）
• OPENCLAW_OPENWEBUI_MODEL=... 用於選擇 Gateway 為 Open WebUI smoke 暴露的模型
• OPENCLAW_OPENWEBUI_PROMPT=... 用於覆寫 Open WebUI smoke 使用的 nonce-check prompt
• OPENWEBUI_IMAGE=... 用於覆寫釘選的 Open WebUI 映像標籤

​

Docs 健全性檢查

​

離線 regression（CI 安全）

• Gateway tool calling（mock OpenAI，真實 gateway + agent loop）：src/gateway/gateway.test.ts（case: “runs a mock OpenAI tool call end-to-end via gateway agent loop”）
• Gateway wizard（WS wizard.start/wizard.next，寫入 config + 強制 auth）：src/gateway/gateway.test.ts（case: “runs wizard over ws and writes auth token config”）

​

Agent reliability evals（skills）

• 透過真實 gateway + agent loop 進行 mock tool-calling（src/gateway/gateway.test.ts）。
• 驗證 session wiring 與 config effects 的 end-to-end wizard flows（src/gateway/gateway.test.ts）。

• 決策： 當 prompt 中列出 skills 時，agent 是否會選擇正確的 skill（或避開不相關的 skill）？
• 合規性： agent 是否會在使用前讀取 SKILL.md，並遵循必要的 steps/args？
• Workflow contracts： 斷言 tool order、session history carryover 與 sandbox boundaries 的 multi-turn scenarios。

• 使用 mock providers 的 scenario runner，用於斷言 tool calls + order、skill file reads 與 session wiring。
• 一小套專注於 skill 的 scenarios（使用 vs 避免、gating、prompt injection）。
• Optional live evals（opt-in、env-gated）只在 CI 安全 suite 到位後加入。

​

Contract tests（Plugin 與 channel shape）

​

命令

• 所有 contracts：pnpm test:contracts
• 僅 channel contracts：pnpm test:contracts:channels
• 僅 provider contracts：pnpm test:contracts:plugins

​

Channel contracts

• plugin - 基本 Plugin shape（id、name、capabilities）
• setup - Setup wizard contract
• session-binding - Session binding behavior
• outbound-payload - Message payload structure
• inbound - Inbound message handling
• actions - Channel action handlers
• threading - Thread ID handling
• directory - Directory/roster API
• group-policy - Group policy enforcement

​

Provider status contracts

• status - Channel status probes
• registry - Plugin registry shape

​

Provider contracts

• auth - Auth flow contract
• auth-choice - Auth choice/selection
• catalog - Model catalog API
• discovery - Plugin discovery
• loader - Plugin loading
• runtime - Provider runtime
• shape - Plugin shape/interface
• wizard - Setup wizard

​

何時執行

• 變更 plugin-sdk exports 或 subpaths 後
• 新增或修改 channel 或 provider Plugin 後
• 重構 Plugin registration 或 discovery 後

​

新增 regressions（指引）

• 盡可能新增 CI 安全的 regression（mock/stub provider，或 capture 確切的 request-shape transformation）
• 如果本質上只能 live-only（rate limits、auth policies），請讓 live test 保持狹窄，並透過 env vars opt-in
• 優先鎖定能捕捉 bug 的最小層級：
  • provider request conversion/replay bug → direct models test
  • gateway session/history/tool pipeline bug → gateway live smoke 或 CI 安全的 gateway mock test
• SecretRef traversal guardrail：
  • src/secrets/exec-secret-ref-id-parity.test.ts 會從 registry metadata（listSecretTargetRegistryEntries()）為每個 SecretRef class 衍生一個 sampled target，接著斷言 traversal-segment exec ids 會被拒絕。
  • 如果你在 src/secrets/target-registry-data.ts 中新增新的 includeInPlan SecretRef target family，請更新該測試中的 classifyTargetClass。此測試會刻意在未分類 target ids 上失敗，讓新的 classes 不能被無聲跳過。

​

相關

• 測試 live
• 測試 updates 與 plugins
• CI