openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-TW translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 23:42:46 +00:00
parent 3bf3a86c4a
commit d04ab98130
8 changed files with 1157 additions and 1103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

373
docs/zh-TW/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- 您需要了解為什麼 CI 作業有執行或未執行
- 你正在偵錯一項失敗的 GitHub Actions 檢查
- 你正在協調一次發布驗證的執行或重新執行
- 您正在變更 ClawSweeper 分派或 GitHub 活動轉送
summary: CI 作業圖、範圍閘門、發行總括項目與本機命令對應项
- 你需要了解 CI 作業為何執行或未執行
- 你正在偵錯失敗的 GitHub Actions 檢查
- 你正在協調發布驗證的執行或重新執行
- 你正在變更 ClawSweeper 分派或 GitHub 活動轉送
summary: CI 作業圖、範圍閘門、發行總括，以及本機指令對應方式
title: CI 管線
x-i18n:
generated_at: "2026-05-02T22:17:33Z"
generated_at: "2026-05-02T23:39:23Z"
model: gpt-5.5
provider: openai
source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016
source_hash: 321fe0a061044f75b8e1d03b4d3e76d4f8dd2dae0ebc58831887fc20af953cf1
source_path: ci.md
workflow: 16
---
OpenClaw CI 會在每次推送到 `main` 以及每個 pull request 時執行。`preflight` 工作會分類差異，並在只有不相關區域變更時關閉昂貴的路徑。手動 `workflow_dispatch` 執行會刻意略過智慧範圍界定，並展開完整圖表以供候選版本與廣泛驗證使用。Android 路徑透過 `include_android` 維持選擇性啟用。僅限發布的 Plugin 涵蓋範圍位於獨立的 [`Plugin 預發布`](#plugin-prerelease) 工作流程中，且只會從 [`完整發布驗證`](#full-release-validation) 或明確的手動派發執行。
OpenClaw CI 會在每次推送到 `main` 以及每個 pull request 時執行。`preflight` 工作會分類差異，並在只有無關區域變更時關閉昂貴的執行線。手動 `workflow_dispatch` 執行會刻意略過智慧範圍判定，並展開完整圖形，用於發行候選版本與廣泛驗證。Android 執行線會透過 `include_android` 保持選擇性啟用。僅限發行版的 Plugin 涵蓋範圍位於獨立的 [`Plugin Prerelease`](#plugin-prerelease) 工作流程中，且只會從 [`Full Release Validation`](#full-release-validation) 或明確的手動派發執行。
## 管線概覽
| 工作 | 目的 | 執行時機 |
| 工作 | 用途 | 執行時機 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | 偵測僅文件變更、變更範圍、變更的 extensions，並建置 CI manifest | 非草稿推送與 PR 一律執行 |
| `security-scm-fast` | 透過 `zizmor` 進行私鑰偵測與工作流程稽核 | 非草稿推送與 PR 一律執行 |
| `security-dependency-audit` | 針對 npm advisories 進行不需相依套件的 production lockfile 稽核 | 非草稿推送與 PR 一律執行 |
| `security-fast` | 快速安全工作所需的彙總結果 | 非草稿推送與 PR 一律執行 |
| `check-dependencies` | 僅 production Knip 相依套件檢查，加上未使用檔案 allowlist guard | Node 相關變更 |
| `build-artifacts` | 建置 `dist/`、Control UI、built-artifact 檢查，以及可重複使用的下游 artifacts | Node 相關變更 |
| `checks-fast-core` | 快速 Linux 正確性路徑，例如 bundled/plugin-contract/protocol 檢查 | Node 相關變更 |
| `checks-fast-contracts-channels` | 分片的 channel contract 檢查，並提供穩定的彙總檢查結果 | Node 相關變更 |
| `checks-node-core-test` | Core Node 測試分片，不包含 channel、bundled、contract 與 extension 路徑 | Node 相關變更 |
| `check` | 分片的主要本機 gate 等效項：prod types、lint、guards、test types，以及 strict smoke | Node 相關變更 |
| `check-additional` | Architecture、boundary、prompt snapshot drift、extension-surface guards、package-boundary，以及 gateway-watch 分片 | Node 相關變更 |
| `build-smoke` | Built-CLI smoke 測試與 startup-memory smoke | Node 相關變更 |
| `checks` | built-artifact channel 測試的驗證器 | Node 相關變更 |
| `checks-node-compat-node22` | Node 22 相容性建置與 smoke 路徑 | 發布用手動 CI 派發 |
| `check-docs` | 文件格式、lint 與 broken-link 檢查 | 文件已變更 |
| `skills-python` | Python 支援的 Skills 的 Ruff + pytest | Python-skill 相關變更 |
| `checks-windows` | Windows 專屬 process/path 測試，加上共用 runtime import specifier 回歸 | Windows 相關變更 |
| `macos-node` | 使用共用 built artifacts 的 macOS TypeScript 測試路徑 | macOS 相關變更 |
| `macos-swift` | macOS app 的 Swift lint、建置與測試 | macOS 相關變更 |
| `android` | 兩種 flavor 的 Android unit tests，加上一個 debug APK 建置 | Android 相關變更 |
| `test-performance-agent` | 可信活動後每日 Codex 慢速測試最佳化 | Main CI 成功或手動派發 |
| `openclaw-performance` | 每日/隨選 Kova runtime 效能報告，包含 mock-provider、deep-profile 與 GPT 5.4 live 路徑 | 排程與手動派發 |
| `preflight` | 偵測僅文件變更、變更範圍、變更的 extensions，並建置 CI manifest | 一律在非草稿推送與 PR 上執行 |
| `security-scm-fast` | 透過 `zizmor` 偵測私密金鑰並稽核工作流程 | 一律在非草稿推送與 PR 上執行 |
| `security-dependency-audit` | 對 npm advisories 執行不需依賴項目的 production lockfile 稽核 | 一律在非草稿推送與 PR 上執行 |
| `security-fast` | 快速安全性工作的必要彙總 | 一律在非草稿推送與 PR 上執行 |
| `check-dependencies` | Production Knip 僅依賴項目檢查，加上未使用檔案 allowlist 保護 | Node 相關變更 |
| `build-artifacts` | 建置 `dist/`、Control UI、內建成品檢查，以及可重用的下游成品 | Node 相關變更 |
| `checks-fast-core` | 快速 Linux 正確性執行線，例如 bundled、Plugin 合約、通訊協定檢查 | Node 相關變更 |
| `checks-fast-contracts-channels` | 分片的通道合約檢查，並提供穩定的彙總檢查結果 | Node 相關變更 |
| `checks-node-core-test` | Core Node 測試分片，排除通道、bundled、合約與 extension 執行線 | Node 相關變更 |
| `check` | 分片的主要本機 gate 等效項目：prod types、lint、guards、test types，以及嚴格 smoke | Node 相關變更 |
| `check-additional` | 架構、邊界、prompt snapshot drift、extension surface guards、package-boundary，以及 gateway-watch 分片 | Node 相關變更 |
| `build-smoke` | 已建置 CLI smoke tests 與 startup-memory smoke | Node 相關變更 |
| `checks` | 已建置成品通道測試的驗證器 | Node 相關變更 |
| `checks-node-compat-node22` | Node 22 相容性建置與 smoke 執行線 | 發行用手動 CI 派發 |
| `check-docs` | 文件格式、lint 與斷鏈檢查 | 文件已變更 |
| `skills-python` | Python-backed Skills 的 Ruff + pytest | Python Skills 相關變更 |
| `checks-windows` | Windows 專用 process/path 測試，以及共享 runtime import specifier 回歸檢查 | Windows 相關變更 |
| `macos-node` | 使用共享建置成品的 macOS TypeScript 測試執行線 | macOS 相關變更 |
| `macos-swift` | macOS app 的 Swift lint、建置與測試 | macOS 相關變更 |
| `android` | 兩種 flavor 的 Android 單元測試，加上一個 debug APK 建置 | Android 相關變更 |
| `test-performance-agent` | 受信任活動後的每日 Codex 慢速測試最佳化 | Main CI 成功或手動派發 |
| `openclaw-performance` | 每日/隨選 Kova runtime 效能報告，包含 mock-provider、deep-profile 與 GPT 5.4 live 執行線 | 排程與手動派發 |
## 快速失敗順序
## Fail-fast 順序
1. `preflight` 決定哪些路徑實際存在。`docs-scope` 與 `changed-scope` 邏輯是此工作內的步驟，不是獨立工作。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 與 `skills-python` 會快速失敗，不等待較重的 artifact 與平台矩陣工作。
3. `build-artifacts` 會與快速 Linux 路徑重疊，讓下游消費者可在共用建置就緒後立即開始。
4. 較重的平台與 runtime 路徑隨後展開：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 與 `android`。
1. `preflight` 會決定哪些執行線根本存在。`docs-scope` 與 `changed-scope` 邏輯是此工作內的步驟，不是獨立工作。
2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 與 `skills-python` 會快速失敗，不等待較重的成品與平台矩陣工作。
3. `build-artifacts` 會與快速 Linux 執行線重疊，讓下游消費者可在共享建置準備好後立即開始。
4. 較重的平台與 runtime 執行線隨後展開：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 與 `android`。
當同一個 PR 或 `main` ref 有較新的推送落地時，GitHub 可能會將被取代的工作標記為 `cancelled`。除非相同 ref 的最新執行也失敗，否則請將其視為 CI 噪音。彙總分片檢查使用 `!cancelled() && always()`，因此仍會回報正常的分片失敗，但在整個工作流程已被取代後不會繼續排隊。自動 CI concurrency key 已版本化為 (`CI-v7-*`)，因此 GitHub 端舊 queue group 中的 zombie 不會無限期阻擋新的 main 執行。手動 full-suite 執行使用 `CI-manual-v1-*`，且不會取消正在執行的工作。
當同一個 PR 或 `main` ref 上有較新的推送進來時，GitHub 可能會將被取代的工作標記為 `cancelled`。除非同一個 ref 的最新執行也失敗，否則應將其視為 CI 雜訊。彙總分片檢查使用 `!cancelled() && always()`，因此仍會回報正常的分片失敗，但在整個工作流程已被取代後不會再排入佇列。自動 CI concurrency key 有版本標記（`CI-v7-*`），因此 GitHub 端舊佇列群組中的 zombie 不會無限期阻塞較新的 main 執行。手動 full-suite 執行使用 `CI-manual-v1-*`，且不會取消進行中的執行。
## 範圍與路由
範圍邏輯位於 `scripts/ci-changed-scope.mjs`，並由 `src/scripts/ci-changed-scope.test.ts` 中的單元測試涵蓋。手動派發會略過 changed-scope 偵測，並讓 preflight manifest 表現得像每個 scoped area 都已變更。
範圍邏輯位於 `scripts/ci-changed-scope.mjs`，並由 `src/scripts/ci-changed-scope.test.ts` 中的單元測試涵蓋。手動派發會略過 changed-scope 偵測，並讓 preflight manifest 的行為如同每個 scoped area 都已變更。
- **CI 工作流程編輯**會驗證 Node CI 圖表與工作流程 linting，但本身不會強制 Windows、Android 或 macOS native builds；這些平台路徑仍限於平台來源變更。
- **僅 CI 路由編輯、選定的低成本 core-test fixture 編輯，以及窄範圍 Plugin contract helper/test-routing 編輯**會使用快速 Node-only manifest 路徑：`preflight`、security，以及單一 `checks-fast-core` 任務。當變更限於該快速任務直接涵蓋的 routing 或 helper surfaces 時，此路徑會略過 build artifacts、Node 22 compatibility、channel contracts、full core shards、bundled-plugin shards 與 additional guard matrices。
- **Windows Node 檢查**限於 Windows 專屬 process/path wrappers、npm/pnpm/UI runner helpers、package manager config，以及執行該路徑的 CI 工作流程 surfaces；不相關的 source、Plugin、install-smoke 與 test-only 變更會留在 Linux Node 路徑。
- **CI 工作流程編輯**會驗證 Node CI 圖形與工作流程 linting，但不會單獨強制 Windows、Android 或 macOS 原生建置；這些平台執行線仍限定於平台原始碼變更。
- **僅 CI 路由編輯、選定的廉價核心測試 fixture 編輯，以及狹窄的 Plugin 合約 helper/test-routing 編輯**會使用快速 Node-only manifest 路徑：`preflight`、security，以及單一 `checks-fast-core` 任務。當變更僅限於該快速任務直接 exercised 的 routing 或 helper surface 時，該路徑會略過建置成品、Node 22 相容性、通道合約、完整 core 分片、bundled-Plugin 分片與額外 guard 矩陣。
- **Windows Node 檢查**限定於 Windows 專用 process/path wrappers、npm/pnpm/UI runner helpers、package manager config，以及執行該執行線的 CI 工作流程 surface；無關的原始碼、Plugin、install-smoke 與僅測試變更會留在 Linux Node 執行線上。
最慢的 Node 測試家族會被拆分或平衡，讓每個工作維持小型且不過度保留 runners：channel contracts 以三個加權分片執行，小型 core unit 路徑會配對，auto-reply 以四個平衡 worker 執行（並將 reply 子樹拆成 agent-runner、dispatch 與 commands/state-routing 分片），而 agentic gateway/plugin configs 會分散到既有的 source-only agentic Node 工作中，而不是等待 built artifacts。廣泛的 browser、QA、media 與其他 Plugin 測試使用其專用的 Vitest configs，而不是共用的 Plugin catch-all。Include-pattern 分片會使用 CI 分片名稱記錄 timing entries，因此 `.artifacts/vitest-shard-timings.json` 可以區分整個 config 與已過濾分片。`check-additional` 會將 package-boundary compile/canary 工作放在一起，並將 runtime topology architecture 與 gateway watch coverage 分開；boundary guard 分片會在單一工作內並行執行其小型獨立 guards，包括 `pnpm prompt:snapshots:check`，使 Codex happy-path prompt drift 固定在造成它的 PR 上。Gateway watch、channel tests 與 core support-boundary 分片會在 `dist/` 與 `dist-runtime/` 已建置後，於 `build-artifacts` 內並行執行。
最慢的 Node 測試系列會被拆分或平衡，讓每個工作維持小型而不過度保留 runner：通道合約以三個加權分片執行，小型 core unit 執行線成對配置，auto-reply 以四個平衡 worker 執行（reply subtree 會拆成 agent-runner、dispatch 與 commands/state-routing 分片），而 agentic gateway/Plugin config 會分散在既有的 source-only agentic Node 工作中，而不是等待建置成品。廣泛的 browser、QA、media 與 miscellaneous Plugin 測試會使用各自專用的 Vitest config，而不是共享 Plugin catch-all。Include-pattern 分片會使用 CI 分片名稱記錄 timing entries，因此 `.artifacts/vitest-shard-timings.json` 可區分整個 config 與 filtered shard。`check-additional` 會將 package-boundary compile/canary 工作放在一起，並將 runtime topology architecture 與 gateway watch coverage 分開；boundary guard 分片會在單一工作內並行執行其小型獨立 guards，包含 `pnpm prompt:snapshots:check`，因此 Codex runtime happy-path prompt drift 會被釘在造成它的 PR 上。Gateway watch、通道測試與 core support-boundary 分片會在 `dist/` 與 `dist-runtime/` 已建置完成後，於 `build-artifacts` 內並行執行。
Android CI 會同時執行 `testPlayDebugUnitTest` 與 `testThirdPartyDebugUnitTest`，接著建置 Play debug APK。third-party flavor 沒有獨立的 source set 或 manifest；其 unit-test 路徑仍會以 SMS/call-log BuildConfig flags 編譯該 flavor，同時避免在每次 Android 相關推送時重複執行 debug APK packaging 工作。
Android CI 會同時執行 `testPlayDebugUnitTest` 與 `testThirdPartyDebugUnitTest`，然後建置 Play debug APK。third-party flavor 沒有獨立的 source set 或 manifest；其 unit-test 執行線仍會使用 SMS/call-log BuildConfig flags 編譯該 flavor，同時避免在每次 Android 相關推送時重複執行 debug APK packaging 工作。
`check-dependencies` 分片會執行 `pnpm deadcode:dependencies`（僅 production Knip 相依套件檢查，固定使用最新 Knip 版本，並在 `dlx` 安裝時停用 pnpm 的 minimum release age）與 `pnpm deadcode:unused-files`，後者會將 Knip 的 production unused-file findings 與 `scripts/deadcode-unused-files.allowlist.mjs` 比較。當 PR 新增未經審查的未使用檔案，或留下過時的 allowlist entry 時，unused-file guard 會失敗，同時保留 Knip 無法靜態解析的刻意 dynamic Plugin、generated、build、live-test 與 package bridge surfaces。
`check-dependencies` 分片會執行 `pnpm deadcode:dependencies`（production Knip 僅依賴項目檢查，釘選到最新 Knip 版本，並在 `dlx` install 時停用 pnpm 的 minimum release age）與 `pnpm deadcode:unused-files`，後者會將 Knip 的 production unused-file findings 與 `scripts/deadcode-unused-files.allowlist.mjs` 比對。當 PR 新增未審查的未使用檔案或留下過時的 allowlist entry 時，unused-file guard 會失敗，同時保留 Knip 無法靜態解析的刻意 dynamic Plugin、generated、build、live-test 與 package bridge surfaces。
## ClawSweeper 活動轉送
`.github/workflows/clawsweeper-dispatch.yml` 是從 OpenClaw repository activity 到 ClawSweeper 的目標端橋接。它不會 checkout 或執行不受信任的 pull request code。此工作流程會從 `CLAWSWEEPER_APP_PRIVATE_KEY` 建立 GitHub App token，然後將精簡的 `repository_dispatch` payloads 派發至 `openclaw/clawsweeper`。
`.github/workflows/clawsweeper-dispatch.yml` 是從 OpenClaw repository activity 到 ClawSweeper 的目標端橋接。它不會 checkout 或執行不受信任的 pull request code。該工作流程會從 `CLAWSWEEPER_APP_PRIVATE_KEY` 建立 GitHub App token，然後將精簡的 `repository_dispatch` payload 派發到 `openclaw/clawsweeper`。
此工作流程有四個路徑：
該工作流程有四條執行線：
- `clawsweeper_item` 用於精確的 issue 與 pull request review requests；
- `clawsweeper_comment` 用於 issue comments 中明確的 ClawSweeper commands；
- `clawsweeper_commit_review` 用於 `main` 推送上的 commit-level review requests；
- `github_activity` 用於 ClawSweeper agent 可檢查的一般 GitHub activity。
- `clawsweeper_commit_review` 用於 `main` pushes 上的 commit-level review requests；
- `github_activity` 用於 ClawSweeper agent 可能檢查的一般 GitHub activity。
`github_activity` 路徑只會轉送正規化 metadata：event type、action、actor、repository、item number、URL、title、state，以及存在時 comments 或 reviews 的短摘錄。它刻意避免轉送完整 webhook body。`openclaw/clawsweeper` 中的接收工作流程是 `.github/workflows/github-activity.yml`，會將正規化事件發布到 ClawSweeper agent 的 OpenClaw Gateway hook。
`github_activity` 執行線只會轉送正規化 metadata：event type、action、actor、repository、item number、URL、title、state，以及 comments 或 reviews 存在時的短 excerpt。它刻意避免轉送完整 webhook body。`openclaw/clawsweeper` 中的接收工作流程是 `.github/workflows/github-activity.yml`，會將正規化事件送到 ClawSweeper agent 的 OpenClaw Gateway hook。
一般活動是觀察，而非預設遞送。ClawSweeper agent 會在其 prompt 中收到 Discord 目標，且只有當事件令人意外、可行動、有風險或具營運用途時，才應發布到 `#clawsweeper`。例行開啟、編輯、bot churn、重複 webhook 噪音，以及正常 review traffic 應產生 `NO_REPLY`。
一般活動是 observation，不是預設 delivery。ClawSweeper agent 會在其 prompt 中收到 Discord target，且只有當事件令人意外、可行動、有風險或具作業用途時，才應發佈到 `#clawsweeper`。例行開啟、編輯、bot churn、重複 webhook 雜訊與正常 review traffic 應產生 `NO_REPLY`。
在整條路徑中，請將 GitHub titles、comments、bodies、review text、branch names 與 commit messages 視為不受信任的資料。它們是 summarization 與 triage 的輸入，不是工作流程或 agent runtime 的指令。
## 手動派發
手動 CI 分派會執行與一般 CI 相同的作業圖，但會強制啟用每個非 Android 範圍的 lane：Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS，以及 Control UI i18n。獨立的手動 CI 分派只會在 `include_android=true` 時執行 Android；完整發布 umbrella 會透過傳入 `include_android=true` 啟用 Android。Plugin 預發布靜態檢查、僅發布用的 `agentic-plugins` shard、完整 extension 批次掃描，以及 Plugin 預發布 Docker lane 會從 CI 中排除。Docker 預發布套件只會在 `Full Release Validation` 以已啟用發布驗證 gate 的方式分派獨立的 `Plugin Prerelease` workflow 時執行。
手動 CI dispatch 會執行與一般 CI 相同的工作圖，但會強制啟用每個非 Android 範圍的 lane：Linux Node 分片、bundled-plugin 分片、channel contract、Node 22 相容性、`check`、`check-additional`、build smoke、文件檢查、Python skills、Windows、macOS，以及 Control UI i18n。獨立的手動 CI dispatch 只會在 `include_android=true` 時執行 Android；完整 release umbrella 會透過傳遞 `include_android=true` 啟用 Android。Plugin 預發布靜態檢查、僅限 release 的 `agentic-plugins` 分片、完整 extension 批次掃描，以及 Plugin 預發布 Docker lane 會從 CI 中排除。Docker 預發布套件只會在 `Full Release Validation` dispatch 已啟用 release-validation gate 的個別 `Plugin Prerelease` workflow 時執行。
手動執行會使用唯一的並行群組，因此發布候選完整套件不會被同一 ref 上的另一個 push 或 PR 執行取消。選用的 `target_ref` 輸入可讓受信任的呼叫者使用所選分派 ref 的 workflow 檔案，針對分支、標籤或完整 commit SHA 執行該圖。
手動執行會使用唯一的 concurrency group，因此 release candidate 的完整套件不會被同一 ref 上的另一個 push 或 PR 執行取消。選用的 `target_ref` 輸入可讓受信任的呼叫者針對分支、標籤或完整 commit SHA 執行該工作圖，同時使用所選 dispatch ref 中的 workflow 檔案。
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,12 +98,12 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## 執行器
| 執行器 | 作業 |
| 執行器 | 工作 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`、快速安全性作業與彙總（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 檢查、分片 channel contract 檢查、除 lint 以外的 `check` shard、`check-additional` shard 與彙總、Node 測試彙總驗證器、文件檢查、Python skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 託管的 Ubuntu，讓 Blacksmith matrix 能更早排入佇列 |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、較低權重的 extension shard、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types`，以及 `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 測試 shard、bundled Plugin 測試 shard、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（對 CPU 足夠敏感，8 vCPU 的成本高於節省的時間）；install-smoke Docker 建置（32-vCPU 佇列時間成本高於節省的時間） |
| `ubuntu-24.04` | `preflight`、快速安全性工作與彙總（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol/contract/bundled 檢查、分片 channel contract 檢查、除了 lint 以外的 `check` 分片、`check-additional` 分片與彙總、Node test aggregate verifier、文件檢查、Python skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 託管的 Ubuntu，讓 Blacksmith 矩陣可以更早排隊 |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`、較低權重的 extension 分片、`checks-fast-core`、`checks-node-compat-node22`、`check-prod-types` 和 `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node test 分片、bundled Plugin test 分片、`android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`（對 CPU 足夠敏感，以至於 8 vCPU 的成本高於節省的成本）；install-smoke Docker 建置（32-vCPU 排隊時間成本高於節省的成本） |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 會退回到 `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 會退回到 `macos-latest` |
@ -137,30 +137,30 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## OpenClaw 效能
`OpenClaw Performance` 是產品/執行階段效能 workflow。它每天在 `main` 上執行，也可以手動分派：
`OpenClaw Performance` 是 product/runtime 效能 workflow。它每天在 `main` 上執行，也可以手動 dispatch：
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true
```
該 workflow 會從已釘選的發布安裝 OCM，並從已釘選的 `kova_ref` 輸入安裝 Kova，接著執行三個 lane：
此 workflow 會從 pinned release 安裝 OCM，並從 pinned `kova_ref` 輸入安裝 Kova，然後執行三個 lane：
- `mock-provider`：Kova 診斷情境，針對本機建置的執行階段，並使用具決定性的假 OpenAI 相容驗證。
- `mock-deep-profile`：啟動、Gateway，以及 agent-turn 熱點的 CPU/heap/trace profiling。
- `mock-provider`：針對 local-build runtime 執行 Kova diagnostic scenarios，並使用 deterministic fake OpenAI-compatible auth。
- `mock-deep-profile`：針對啟動、Gateway 和 agent-turn 熱點進行 CPU/heap/trace profiling。
- `live-gpt54`：真實的 OpenAI `openai/gpt-5.4` agent turn，當 `OPENAI_API_KEY` 不可用時略過。
mock-provider lane 也會在 Kova 通過後執行 OpenClaw 原生 source probe：預設、hook 與 50-Plugin 啟動案例中的 Gateway 開機時序與記憶體；重複的 mock-OpenAI `channel-chat-baseline` hello loop；以及針對已啟動 Gateway 的 CLI 啟動命令。source probe Markdown 摘要位於報告 bundle 的 `source/index.md`，旁邊附有原始 JSON。
mock-provider lane 也會在 Kova pass 後執行 OpenClaw 原生 source probe：default、hook 和 50-Plugin 啟動案例中的 Gateway boot timing 與記憶體；重複的 mock-OpenAI `channel-chat-baseline` hello loop；以及針對已啟動 Gateway 的 CLI 啟動命令。source probe Markdown 摘要位於 report bundle 的 `source/index.md`，原始 JSON 則在旁邊。
每個 lane 都會上傳 GitHub artifact。設定 `CLAWGRIT_REPORTS_TOKEN` 時，該 workflow 也會將 `report.json`、`report.md`、bundle、`index.md`，以及 source-probe artifact commit 到 `openclaw/clawgrit-reports` 的 `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` 底下。目前分支指標會寫入 `openclaw-performance/<ref>/latest-<lane>.json`。
每個 lane 都會上傳 GitHub artifact。設定 `CLAWGRIT_REPORTS_TOKEN` 時，workflow 也會將 `report.json`、`report.md`、bundle、`index.md` 和 source-probe artifact commit 到 `openclaw/clawgrit-reports` 的 `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` 底下。目前的分支指標會寫入為 `openclaw-performance/<ref>/latest-<lane>.json`。
## 完整發布驗證
## 完整 Release Validation
`Full Release Validation` 是「發布前執行所有項目」的手動 umbrella workflow。它接受分支、標籤或完整 commit SHA，使用該目標分派手動 `CI` workflow，為僅發布用 Plugin/package/static/Docker 證明分派 `Plugin Prerelease`，並為 install smoke、package acceptance、Docker release-path 套件、live/E2E、OpenWebUI、QA Lab parity、Matrix，以及 Telegram lane 分派 `OpenClaw Release Checks`。搭配 `rerun_group=all` 與 `release_profile=full` 時，它也會針對 release checks 的 `release-package-under-test` artifact 執行 `NPM Telegram Beta E2E`。發布後，傳入 `npm_telegram_package_spec` 以針對已發布的 npm package 重新執行相同的 Telegram package lane。
`Full Release Validation` 是用於「release 前執行所有項目」的手動 umbrella workflow。它接受分支、標籤或完整 commit SHA，使用該 target dispatch 手動 `CI` workflow，dispatch `Plugin Prerelease` 以提供僅限 release 的 Plugin/package/static/Docker proof，並 dispatch `OpenClaw Release Checks` 以執行 install smoke、package acceptance、Docker release-path suite、live/E2E、OpenWebUI、QA Lab parity、Matrix 和 Telegram lane。搭配 `rerun_group=all` 和 `release_profile=full` 時，它也會針對 release checks 產生的 `release-package-under-test` artifact 執行 `NPM Telegram Beta E2E`。發布後，傳入 `npm_telegram_package_spec` 可針對已發布的 npm package 重新執行同一個 Telegram package lane。
請參閱[完整發布驗證](/zh-TW/reference/full-release-validation)，了解階段 matrix、精確的 workflow 作業名稱、profile 差異、artifact，以及聚焦重新執行 handle。
請參閱[完整 release validation](/zh-TW/reference/full-release-validation)，了解 stage matrix、精確的 workflow job 名稱、profile 差異、artifact，以及聚焦 rerun handle。
`OpenClaw Release Publish` 是手動的變更式發布 workflow。請在發布標籤存在且 OpenClaw npm preflight 成功後，從 `release/YYYY.M.D` 或 `main` 分派它。它會驗證 `pnpm plugins:sync:check`，為所有可發布的 Plugin package 分派 `Plugin NPM Release`，為相同發布 SHA 分派 `Plugin ClawHub Release`，然後才使用已儲存的 `preflight_run_id` 分派 `OpenClaw NPM Release`。
`OpenClaw Release Publish` 是會變更狀態的手動 release workflow。在 release tag 存在且 OpenClaw npm preflight 成功後，從 `release/YYYY.M.D` 或 `main` dispatch 它。它會驗證 `pnpm plugins:sync:check`，針對所有可發布的 Plugin package dispatch `Plugin NPM Release`，針對同一個 release SHA dispatch `Plugin ClawHub Release`，然後才用已儲存的 `preflight_run_id` dispatch `OpenClaw NPM Release`。
```bash
gh workflow run openclaw-release-publish.yml \
@ -170,38 +170,35 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
若要在快速變動的分支上取得釘選 commit 證明，請使用 helper，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
若要在快速變動的分支上取得 pinned commit proof，請使用 helper，而不是 `gh workflow run ... --ref main -f ref=<sha>`：
```bash
pnpm ci:full-release --sha <full-sha>
```
GitHub workflow 分派 ref 必須是分支或標籤，不能是原始 commit SHA。該 helper 會在目標 SHA 推送臨時 `release-ci/<sha>-...` 分支，從該已釘選 ref 分派 `Full Release Validation`，驗證每個子 workflow 的 `headSha` 都符合目標，並在執行完成時刪除臨時分支。如果任何子 workflow 在不同 SHA 執行，umbrella 驗證器也會失敗。
GitHub workflow dispatch ref 必須是分支或標籤，不能是原始 commit SHA。helper 會在 target SHA 上推送暫時的 `release-ci/<sha>-...` 分支，從該 pinned ref dispatch `Full Release Validation`，驗證每個 child workflow 的 `headSha` 都符合 target，並在執行完成後刪除暫時分支。如果任何 child workflow 在不同的 SHA 上執行，umbrella verifier 也會失敗。
`release_profile` 控制傳入 release checks 的 live/provider 廣度。手動發布 workflow 預設為 `stable`；只有在你刻意想要廣泛的 advisory provider/media matrix 時，才使用 `full`。
`release_profile` 會控制傳入 release checks 的 live/provider 廣度。手動 release workflow 預設為 `stable`；只有在你有意需要廣泛的 advisory provider/media matrix 時才使用 `full`。
- `minimum` 保留最快的 OpenAI/core 發布關鍵 lane。
- `stable` 加入穩定的 provider/backend 集合。
- `minimum` 保留最快的 OpenAI/core release-critical lane。
- `stable` 加入 stable provider/backend set。
- `full` 執行廣泛的 advisory provider/media matrix。
umbrella 會記錄已分派的子執行 ID，而最終的 `Verify full validation` 作業會重新檢查目前子執行結論，並為每個子執行附加最慢作業表。如果子 workflow 重新執行後轉為綠燈，只需重新執行 parent verifier 作業，即可重新整理 umbrella 結果與時序摘要。
umbrella 會記錄 dispatch 的 child run id，最終的 `Verify full validation` job 會重新檢查目前 child run 的 conclusion，並為每個 child run 附加最慢 job 表格。如果 child workflow 被重新執行並轉為綠燈，只需重新執行 parent verifier job，即可更新 umbrella result 與 timing summary。
為了復原，`Full Release Validation` 和 `OpenClaw Release Checks` 都接受 `rerun_group`。針對發行候選版使用 `all`，只針對一般完整 CI 子項使用 `ci`，只針對 Plugin 預發行子項使用 `plugin-prerelease`，針對每個發行子項使用 `release-checks`，或在 umbrella 上使用更窄的群組：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。這會讓失敗的發行 box 在聚焦修正後，重新執行的範圍保持有界。
若要復原，`Full Release Validation` 與 `OpenClaw Release Checks` 都接受 `rerun_group`。針對發布候選版本使用 `all`，只針對一般完整 CI 子工作使用 `ci`，只針對 Plugin 預發行子工作使用 `plugin-prerelease`，針對每個發布子工作使用 `release-checks`，或在 umbrella 上使用更窄的群組：`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 或 `npm-telegram`。這會讓聚焦修正後重新執行失敗的發布 box 時保持範圍受限。
`OpenClaw Release Checks` 使用受信任的 workflow ref，將選取的 ref 解析一次成 `release-package-under-test` tarball，然後把該成品傳給即時/E2E 發行路徑 Docker workflow 和套件驗收 shard。這可讓發行 box 之間的套件位元組保持一致，並避免在多個子 job 中重新打包同一個候選版。
`OpenClaw Release Checks` 使用受信任的工作流程 ref，將所選 ref 解析一次成 `release-package-under-test` tarball，然後將該成品傳給 live/E2E 發布路徑 Docker 工作流程和套件驗收分片。這會讓發布 box 之間的套件位元組保持一致，並避免在多個子工作中重新打包同一個候選版本。
針對 `ref=main` 和 `rerun_group=all` 的重複 `Full Release Validation` 執行
會取代較舊的 umbrella。父監控器會在父項被取消時，取消任何它
已經分派的子 workflow，因此較新的 main 驗證不會卡在過時的兩小時 release-check 執行後面。發行分支/標籤
驗證和聚焦重新執行群組會保持 `cancel-in-progress: false`。
針對 `ref=main` 與 `rerun_group=all` 的重複 `Full Release Validation` 執行會取代較舊的 umbrella。父監控器在父工作被取消時，會取消任何已分派的子工作流程，因此較新的 main 驗證不會卡在過期的兩小時 release-check 執行後面。發布分支/標籤驗證與聚焦重新執行群組會保留 `cancel-in-progress: false`。
## 即時和 E2E shards
## Live 與 E2E 分片
發行即時/E2E 子項保留廣泛的原生 `pnpm test:live` 覆蓋範圍，但它會透過 `scripts/test-live-shard.mjs` 以命名 shards 執行，而不是一個序列 job：
發布 live/E2E 子工作保留廣泛的原生 `pnpm test:live` 覆蓋範圍，但會透過 `scripts/test-live-shard.mjs` 以具名分片執行，而不是單一序列工作：
- `native-live-src-agents`
- `native-live-src-gateway-core`
- provider 篩選的 `native-live-src-gateway-profiles` jobs
- 依 provider 篩選的 `native-live-src-gateway-profiles` 工作
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -209,61 +206,59 @@ umbrella 會記錄已分派的子執行 ID，而最終的 `Verify full validatio
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- 分割的媒體音訊/影片 shards，以及 provider 篩選的音樂 shards
- 拆分的媒體音訊/影片分片，以及依 provider 篩選的音樂分片
這會維持相同的檔案覆蓋範圍，同時讓緩慢的即時 provider 失敗更容易重新執行和診斷。聚合的 `native-live-extensions-o-z`、`native-live-extensions-media` 和 `native-live-extensions-media-music` shard 名稱仍可用於手動一次性重新執行。
這會保持相同的檔案覆蓋範圍，同時讓緩慢的 live provider 失敗更容易重新執行和診斷。彙總的 `native-live-extensions-o-z`、`native-live-extensions-media` 與 `native-live-extensions-media-music` 分片名稱仍可用於手動一次性重新執行。
原生即時媒體 shards 會在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中執行，該映像由 `Live Media Runner Image` workflow 建置。該映像預先安裝 `ffmpeg` 和 `ffprobe`；媒體 job 只會在設定前驗證二進位檔。請讓 Docker 支援的即時套件在一般 Blacksmith runners 上執行 — container jobs 不適合啟動巢狀 Docker 測試。
原生 live 媒體分片在 `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` 中執行，該映像由 `Live Media Runner Image` 工作流程建置。該映像預先安裝 `ffmpeg` 與 `ffprobe`；媒體工作只會在設定前驗證二進位檔。將 Docker 支援的 live 套件保留在一般 Blacksmith runner 上；容器工作不是啟動巢狀 Docker 測試的正確位置。
Docker 支援的即時模型/backend shards 會針對每個選取的 commit 使用獨立的共用 `ghcr.io/openclaw/openclaw-live-test:<sha>` 映像。即時發行 workflow 會建置並推送該映像一次，然後 Docker 即時模型、provider 分 shard 的 Gateway、CLI backend、ACP bind 和 Codex harness shards 會以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行。Gateway Docker shards 具備明確的 script 層級 `timeout` 上限，低於 workflow job timeout，因此卡住的 container 或清理路徑會快速失敗，而不是耗完整個 release-check 預算。如果這些 shards 各自重新建置完整來源 Docker target，表示發行執行設定錯誤，且會把壁鐘時間浪費在重複映像建置上。
Docker 支援的 live 模型/後端分片會為每個所選 commit 使用個別共用的 `ghcr.io/openclaw/openclaw-live-test:<sha>` 映像。live 發布工作流程會建置並推送該映像一次，然後 Docker live 模型、provider 分片 Gateway、CLI 後端、ACP 綁定與 Codex harness 分片會以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行。Gateway Docker 分片帶有明確的腳本層級 `timeout` 上限，低於工作流程工作逾時，因此卡住的容器或清理路徑會快速失敗，而不是消耗整個 release-check 預算。如果這些分片各自重新建置完整來源 Docker target，則發布執行設定錯誤，會在重複映像建置上浪費實際時間。
## 套件驗收
當問題是「這個可安裝的 OpenClaw 套件是否能作為產品運作？」時，使用 `Package Acceptance`。它不同於一般 CI：一般 CI 驗證來源樹，而套件驗收會透過使用者安裝或更新後使用的同一套 Docker E2E harness 驗證單一 tarball。
當問題是「這個可安裝的 OpenClaw 套件是否能作為產品運作？」時，請使用 `Package Acceptance`。它不同於一般 CI：一般 CI 驗證來源樹，而套件驗收會透過使用者安裝或更新後會執行的相同 Docker E2E harness，驗證單一 tarball。
### Jobs
### 工作
1. `resolve_package` 會 checkout `workflow_ref`、解析一個套件候選、寫入 `.artifacts/docker-e2e-package/openclaw-current.tgz`、寫入 `.artifacts/docker-e2e-package/package-candidate.json`、將兩者上傳為 `package-under-test` 成品，並在 GitHub step summary 中印出來源、workflow ref、package ref、版本、SHA-256 和 profile。
2. `docker_acceptance` 會以 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 呼叫 `openclaw-live-and-e2e-checks-reusable.yml`。可重用 workflow 會下載該成品、驗證 tarball 清單、在需要時準備 package-digest Docker 映像，並針對該套件執行選取的 Docker lanes，而不是打包 workflow checkout。當 profile 選取多個目標 `docker_lanes` 時，可重用 workflow 會準備套件和共用映像一次，然後將這些 lanes 展開成具備唯一成品的平行目標 Docker jobs。
3. `package_telegram` 可選擇性呼叫 `NPM Telegram Beta E2E`。當 `telegram_mode` 不是 `none` 時會執行，且在套件驗收解析出套件時安裝同一個 `package-under-test` 成品；獨立的 Telegram dispatch 仍可安裝已發布的 npm spec。
4. `summary` 會在套件解析、Docker 驗收或選用 Telegram lane 失敗時讓 workflow 失敗。
1. `resolve_package` 會 checkout `workflow_ref`、解析一個套件候選版本、寫入 `.artifacts/docker-e2e-package/openclaw-current.tgz`、寫入 `.artifacts/docker-e2e-package/package-candidate.json`、將兩者作為 `package-under-test` 成品上傳，並在 GitHub 步驟摘要中列印來源、工作流程 ref、套件 ref、版本、SHA-256 與 profile。
2. `docker_acceptance` 會以 `ref=workflow_ref` 與 `package_artifact_name=package-under-test` 呼叫 `openclaw-live-and-e2e-checks-reusable.yml`。可重用工作流程會下載該成品、驗證 tarball inventory、在需要時準備 package-digest Docker 映像，並針對該套件執行所選 Docker lane，而不是打包工作流程 checkout。當 profile 選取多個目標 `docker_lanes` 時，可重用工作流程會準備套件與共用映像一次，然後將這些 lane 展開為平行的目標 Docker 工作，並使用唯一成品。
3. `package_telegram` 可選擇呼叫 `NPM Telegram Beta E2E`。當 `telegram_mode` 不是 `none` 時會執行，並在 Package Acceptance 已解析套件時安裝相同的 `package-under-test` 成品；獨立 Telegram dispatch 仍可安裝已發布的 npm spec。
4. `summary` 會在套件解析、Docker 驗收或選用 Telegram lane 失敗時讓工作流程失敗。
### 候選來源
- `source=npm` 只接受 `openclaw@alpha`、`openclaw@beta`、`openclaw@latest`，或確切的 OpenClaw 發行版本，例如 `openclaw@2026.4.27-beta.2`。用於已發布的預發行/穩定版驗收。
- `source=ref` 會打包受信任的 `package_ref` 分支、標籤或完整 commit SHA。resolver 會抓取 OpenClaw 分支/標籤、驗證選取的 commit 可從儲存庫分支歷史或發行標籤到達、在 detached worktree 中安裝 deps，並使用 `scripts/package-openclaw-for-docker.mjs` 打包。
- `source=npm` 只接受 `openclaw@beta`、`openclaw@latest` 或精確的 OpenClaw 發布版本，例如 `openclaw@2026.4.27-beta.2`。將此用於已發布的預發行/穩定驗收。
- `source=ref` 會打包受信任的 `package_ref` 分支、標籤或完整 commit SHA。解析器會擷取 OpenClaw 分支/標籤，驗證所選 commit 可從儲存庫分支歷史或發布標籤到達，在 detached worktree 中安裝相依項，並使用 `scripts/package-openclaw-for-docker.mjs` 打包。
- `source=url` 會下載 HTTPS `.tgz`；必須提供 `package_sha256`。
- `source=artifact` 會從 `artifact_run_id` 和 `artifact_name` 下載一個 `.tgz`；`package_sha256` 為選用，但外部共享成品應提供。
- `source=artifact` 會從 `artifact_run_id` 與 `artifact_name` 下載一個 `.tgz`；`package_sha256` 是選用，但應為外部共享成品提供。
保持 `workflow_ref` 和 `package_ref` 分離。`workflow_ref` 是執行測試的受信任 workflow/harness 程式碼。`package_ref` 是 `source=ref` 時會被打包的來源 commit。這讓目前的測試 harness 可以驗證較舊的受信任來源 commit，而不需執行舊的 workflow 邏輯。
請將 `workflow_ref` 與 `package_ref` 分開。`workflow_ref` 是執行測試的受信任工作流程/harness 程式碼。`package_ref` 是 `source=ref` 時會被打包的來源 commit。這讓目前的測試 harness 能驗證較舊的受信任來源 commit，而不執行舊的工作流程邏輯。
### 套件 profiles
### 套件 profile
- `smoke` — `npm-onboard-channel-agent`、`gateway-network`、`config-reload`
- `package` — `npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`upgrade-survivor`、`published-upgrade-survivor`、`plugins-offline`、`plugin-update`
- `product` — `package` 加上 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui`
- `full` — 包含 OpenWebUI 的完整 Docker 發行路徑 chunks
- `custom` — 確切的 `docker_lanes`；當 `suite_profile=custom` 時為必要
- `full` — 含 OpenWebUI 的完整 Docker 發布路徑區塊
- `custom` — 精確的 `docker_lanes`；當 `suite_profile=custom` 時必填
`package` profile 使用離線 Plugin 覆蓋範圍，因此已發布套件驗證不會受限於即時 ClawHub 可用性。選用 Telegram lane 會在 `NPM Telegram Beta E2E` 中重用 `package-under-test` 成品，並保留已發布 npm spec 路徑給獨立 dispatch。
`package` profile 使用離線 Plugin 覆蓋範圍，因此已發布套件驗證不會受 live ClawHub 可用性限制。選用 Telegram lane 會在 `NPM Telegram Beta E2E` 中重用 `package-under-test` 成品，並保留已發布 npm spec 路徑供獨立 dispatch 使用。
如需專用的更新與 Plugin 測試政策，包括本機命令、
Docker lanes、套件驗收輸入、發行預設值和失敗分流，
請參閱[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。
如需專用的更新與 Plugin 測試政策，包括本機命令、Docker lane、Package Acceptance 輸入、發布預設值與失敗分診，請參閱[測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。
發行檢查會以 `source=artifact`、準備好的發行套件成品、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 和 `telegram_mode=mock-openai` 呼叫套件驗收。這會讓套件遷移、更新、過期 Plugin 相依性清理、已設定 Plugin 安裝修復、離線 Plugin、Plugin 更新和 Telegram 證明都位於同一個已解析的套件 tarball 上。在 Full Release Validation 或 OpenClaw Release Checks 上設定 `package_acceptance_package_spec`，即可針對已出貨的 npm 套件執行相同矩陣，而不是針對 SHA 建置的成品。跨 OS 發行檢查仍涵蓋 OS 特定的 onboarding、安裝程式和平台行為；套件/更新產品驗證應從套件驗收開始。`published-upgrade-survivor` Docker lane 每次執行會驗證一個已發布套件基準。在套件驗收中，已解析的 `package-under-test` tarball 永遠是候選，而 `published_upgrade_survivor_baseline` 會選取 fallback 已發布基準，預設為 `openclaw@latest`；失敗 lane 重新執行命令會保留該基準。設定 `published_upgrade_survivor_baselines=all-since-2026.4.23` 可將 Full Release CI 擴展到從 `2026.4.23` 到 `latest` 的每個穩定 npm 發行版；`release-history` 仍可用於以較舊的日期前錨點進行手動更廣泛抽樣。設定 `published_upgrade_survivor_scenarios=reported-issues` 可把相同基準擴展到問題形狀的 fixtures，涵蓋 Feishu config、保留的 bootstrap/persona 檔案、已設定的 OpenClaw Plugin 安裝、tilde log 路徑，以及過時 legacy Plugin 相依性 roots。獨立的 `Update Migration` workflow 會在問題是完整的已發布更新清理，而不是一般 Full Release CI 廣度時，使用含有 `all-since-2026.4.23` 和 `plugin-deps-cleanup` 的 `update-migration` Docker lane。本機聚合執行可透過 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 傳入確切套件 specs，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`（例如 `openclaw@2026.4.15`）保留單一 lane，或設定 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 以使用情境矩陣。已發布 lane 會以內建的 `openclaw config set` 命令 recipe 設定基準，在 `summary.json` 中記錄 recipe 步驟，並在 Gateway 啟動後探測 `/healthz`、`/readyz` 和 RPC 狀態。Windows packaged 和 installer fresh lanes 也會驗證已安裝套件能從原始絕對 Windows 路徑匯入 browser-control override。OpenAI 跨 OS agent-turn smoke 在設定時預設為 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則為 `openai/gpt-5.4`，因此安裝與 Gateway 證明會保持在 GPT-5 測試模型上，同時避免 GPT-4.x 預設值。
發布檢查會以 `source=artifact`、已準備的發布套件成品、`suite_profile=custom`、`docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues` 與 `telegram_mode=mock-openai` 呼叫 Package Acceptance。這會讓套件遷移、更新、過期 Plugin 相依項清理、已設定 Plugin 安裝修復、離線 Plugin、Plugin 更新與 Telegram 證明使用同一個已解析的套件 tarball。設定 Full Release Validation 或 OpenClaw Release Checks 上的 `package_acceptance_package_spec`，即可針對已發布 npm 套件而非 SHA 建置成品執行相同矩陣。跨 OS 發布檢查仍涵蓋 OS 專屬的 onboarding、安裝程式與平台行為；套件/更新產品驗證應從 Package Acceptance 開始。`published-upgrade-survivor` Docker lane 每次執行會驗證一個已發布套件基準線。在 Package Acceptance 中，已解析的 `package-under-test` tarball 一律是候選版本，而 `published_upgrade_survivor_baseline` 選取 fallback 已發布基準線，預設為 `openclaw@latest`；失敗 lane 重新執行命令會保留該基準線。設定 `published_upgrade_survivor_baselines=all-since-2026.4.23`，即可將 Full Release CI 擴展到從 `2026.4.23` 到 `latest` 的每個穩定 npm 發布；`release-history` 仍可用於以較舊日期前錨點進行手動更廣泛取樣。設定 `published_upgrade_survivor_scenarios=reported-issues`，即可將相同基準線擴展到針對 Feishu 設定、保留的 bootstrap/persona 檔案、已設定的 OpenClaw Plugin 安裝、波浪號記錄路徑與過期舊版 Plugin 相依項根目錄的 issue 形狀 fixture。當問題是完整的已發布更新清理，而不是一般 Full Release CI 廣度時，個別的 `Update Migration` 工作流程會搭配 `all-since-2026.4.23` 與 `plugin-deps-cleanup` 使用 `update-migration` Docker lane。本機彙總執行可以透過 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` 傳入精確套件 spec，使用 `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` 保留單一 lane，例如 `openclaw@2026.4.15`，或設定 `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` 以執行情境矩陣。已發布 lane 會以內建的 `openclaw config set` 命令 recipe 設定基準線，在 `summary.json` 中記錄 recipe 步驟，並在 Gateway 啟動後探測 `/healthz`、`/readyz` 以及 RPC 狀態。Windows packaged 與 installer fresh lane 也會驗證已安裝套件可以從原始絕對 Windows 路徑匯入 browser-control override。OpenAI 跨 OS agent-turn smoke 在設定時預設使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因此安裝與 Gateway 證明會停留在 GPT-5 測試模型上，同時避免 GPT-4.x 預設值。
### Legacy 相容性窗口
### 舊版相容性窗口
套件驗收針對已發布套件有有界的 legacy 相容性窗口。到 `2026.4.25` 為止的套件（包括 `2026.4.25-beta.*`）可使用相容性路徑：
Package Acceptance 對已發布套件具有有界的舊版相容性窗口。到 `2026.4.25` 為止的套件，包括 `2026.4.25-beta.*`，可使用相容性路徑：
- `dist/postinstall-inventory.json` 中已知的私有 QA 項目可能指向 tarball 省略的檔案；
- 當套件未公開 `gateway install --wrapper` 旗標時，`doctor-switch` 可略過該 persistence 子案例；
- `update-channel-switch` 可從 tarball 衍生的 fake git fixture 中修剪遺失的 `pnpm.patchedDependencies`，且可記錄遺失的已持久化 `update.channel`；
- Plugin smokes 可讀取 legacy 安裝記錄位置，或接受遺失的 marketplace 安裝記錄 persistence；
- `plugin-update` 可允許 config metadata 遷移，同時仍要求安裝記錄和 no-reinstall 行為保持不變。
- 當套件未公開該 flag 時，`doctor-switch` 可略過 `gateway install --wrapper` 持久化子案例；
- `update-channel-switch` 可從 tarball 衍生的 fake git fixture 修剪缺少的 `pnpm.patchedDependencies`，並可記錄缺少持久化的 `update.channel`；
- Plugin smoke 可讀取舊版 install-record 位置，或接受缺少 marketplace install-record 持久化；
- `plugin-update` 可允許 config metadata 遷移，同時仍要求 install record 與不重新安裝行為保持不變。
已發布的 `2026.4.26` 套件也可能針對已出貨的本機建置 metadata stamp 檔案發出警告。後續套件必須滿足現代合約；相同條件會失敗，而不是警告或略過。
已發布的 `2026.4.26` 套件也可針對已出貨的本機建置 metadata stamp 檔案發出警告。較新的套件必須滿足現代合約；相同條件會失敗，而不是警告或略過。
### 範例
@ -306,110 +301,110 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
偵錯失敗的 package acceptance 執行時，請從 `resolve_package` 摘要開始，確認套件來源、版本和 SHA-256。接著檢查 `docker_acceptance` 子執行及其 Docker 成品：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 記錄、階段計時，以及重新執行命令。請優先重新執行失敗的套件設定檔或精確的 Docker lane，而不是重新執行完整的 release validation。
偵錯失敗的套件驗收執行時，請從 `resolve_package` 摘要開始，確認套件來源、版本和 SHA-256。接著檢查 `docker_acceptance` 子執行及其 Docker 成品：`.artifacts/docker-tests/**/summary.json`、`failures.json`、lane 記錄、階段計時，以及重新執行命令。請優先重新執行失敗的套件設定檔或精確的 Docker lane，而不是重新執行完整發行驗證。
## 安裝煙霧測試
獨立的 `Install Smoke` workflow 會透過自己的 `preflight` job 重複使用相同的範圍腳本。它會將 smoke coverage 分成 `run_fast_install_smoke` 和 `run_full_install_smoke`。
獨立的 `Install Smoke` workflow 會透過自己的 `preflight` job 重用相同的範圍腳本。它將煙霧測試覆蓋範圍分成 `run_fast_install_smoke` 和 `run_full_install_smoke`。
- **快速路徑**會在 pull request 觸及 Docker/package surface、內建 Plugin 套件/manifest 變更，或 Docker smoke job 會執行的 core plugin/channel/gateway/Plugin SDK surface 時執行。僅來源碼的內建 Plugin 變更、僅測試編輯，以及僅文件編輯不會保留 Docker worker。快速路徑會建置一次根 Dockerfile 映像、檢查 CLI、執行 agents delete shared-workspace CLI smoke、執行 container gateway-network e2e、驗證內建 extension build arg，並在 240 秒彙總命令逾時內執行有界的 bundled-plugin Docker 設定檔（每個情境的 Docker 執行會另外設上限）。
- **完整路徑**會保留 QR package install 和 installer Docker/update coverage，用於 nightly 排程執行、手動 dispatch、workflow-call release check，以及真正觸及 installer/package/Docker surface 的 pull request。在完整模式中，install-smoke 會準備或重複使用一個 target-SHA GHCR 根 Dockerfile smoke 映像，接著將 QR package install、根 Dockerfile/gateway smoke、installer/update smoke，以及快速 bundled-plugin Docker E2E 作為個別 job 執行，讓 installer 工作不必等在根映像 smoke 後面。
- **快速路徑**會針對觸及 Docker/套件表面、綑綁 Plugin 套件/manifest 變更，或 Docker 煙霧測試 job 會涵蓋的核心 Plugin/channel/gateway/Plugin SDK 表面的 pull request 執行。僅來源的綑綁 Plugin 變更、僅測試編輯，以及僅文件編輯不會保留 Docker worker。快速路徑會建置一次根 Dockerfile 映像、檢查 CLI、執行 agents delete shared-workspace CLI 煙霧測試、執行容器 gateway-network e2e、驗證綑綁 extension 建置參數，並在 240 秒彙總命令逾時內執行受限的綑綁 Plugin Docker 設定檔（每個情境的 Docker run 另行加上上限）。
- **完整路徑**會保留 QR 套件安裝和安裝程式 Docker/update 覆蓋範圍，供每晚排程執行、手動 dispatch、workflow-call 發行檢查，以及真正觸及安裝程式/套件/Docker 表面的 pull request 使用。在完整模式中，install-smoke 會準備或重用一個目標 SHA 的 GHCR 根 Dockerfile 煙霧測試映像，然後將 QR 套件安裝、根 Dockerfile/gateway 煙霧測試、安裝程式/update 煙霧測試，以及快速綑綁 Plugin Docker E2E 作為個別 job 執行，讓安裝程式工作不必排在根映像煙霧測試之後。
`main` push（包含 merge commit）不會強制使用完整路徑；當 changed-scope 邏輯會在 push 上要求完整 coverage 時，workflow 會保留快速 Docker smoke，並將完整 install smoke 留給 nightly 或 release validation。
`main` push（包含 merge commit）不會強制使用完整路徑；當變更範圍邏輯會在 push 上要求完整覆蓋範圍時，workflow 會保留快速 Docker 煙霧測試，並將完整安裝煙霧測試留給每晚或發行驗證。
緩慢的 Bun global install image-provider smoke 會由 `run_bun_global_install_smoke` 另外控管。它會在 nightly schedule 和 release checks workflow 中執行，手動 `Install Smoke` dispatch 也可以選擇加入，但 pull request 和 `main` push 不會執行。QR 和 installer Docker 測試會保留各自以安裝為重點的 Dockerfile。
較慢的 Bun 全域安裝 image-provider 煙霧測試由 `run_bun_global_install_smoke` 另行控管。它會在每晚排程和 release checks workflow 中執行，且手動 `Install Smoke` dispatch 可以選擇加入，但 pull request 和 `main` push 不會執行。QR 和安裝程式 Docker 測試保留各自以安裝為重點的 Dockerfile。
## 本機 Docker E2E
`pnpm test:docker:all` 會預先建置一個共用 live-test 映像，將 OpenClaw 打包一次成 npm tarball，並建置兩個共用的 `scripts/e2e/Dockerfile` 映像：
`pnpm test:docker:all` 會預先建置一個共享 live-test 映像、將 OpenClaw 打包一次為 npm tarball，並建置兩個共享的 `scripts/e2e/Dockerfile` 映像：
- 用於 installer/update/plugin-dependency lane 的純 Node/Git runner；
- 將同一個 tarball 安裝到 `/app`、用於一般功能 lane 的功能性映像。
- 一個供安裝程式/update/Plugin 相依 lane 使用的裸 Node/Git runner；
- 一個功能映像，會將相同 tarball 安裝到 `/app`，供一般功能 lane 使用。
Docker lane 定義位於 `scripts/lib/docker-e2e-scenarios.mjs`，planner 邏輯位於 `scripts/lib/docker-e2e-plan.mjs`，runner 只會執行選取的 plan。scheduler 會透過 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 為每個 lane 選取映像，接著以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行 lane。
Docker lane 定義位於 `scripts/lib/docker-e2e-scenarios.mjs`，planner 邏輯位於 `scripts/lib/docker-e2e-plan.mjs`，runner 只會執行選取的計畫。scheduler 會使用 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 依 lane 選擇映像，然後以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行 lane。
### 可調參數
| 變數 | 預設值 | 用途 |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 一般 lane 的 main-pool slot 數量。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | 對 provider 敏感的 tail-pool slot 數量。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 並行 live lane 上限，避免 provider throttling。 |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | 一般 lane 的主集區 slot 數量。 |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Provider 敏感 tail-pool slot 數量。 |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | 並行 live lane 上限，避免 provider 節流。 |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | 並行 npm install lane 上限。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 並行 multi-service lane 上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | lane 啟動之間的錯開時間，用於避免 Docker daemon create storm；設為 `0` 則不錯開。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每個 lane 的 fallback 逾時（120 分鐘）；選取的 live/tail lane 會使用更嚴格的上限。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` 會列印 scheduler plan 而不執行 lane。 |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | 以逗號分隔的精確 lane 清單；略過 cleanup smoke，讓 agent 能重現單一失敗 lane。 |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | 並行多服務 lane 上限。 |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | lane 啟動之間的錯開時間，用於避免 Docker daemon create 風暴；設定 `0` 表示不錯開。 |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | 每個 lane 的備援逾時（120 分鐘）；選定的 live/tail lane 使用更嚴格的上限。 |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | 未設定 | `1` 會列印 scheduler 計畫而不執行 lane。 |
| `OPENCLAW_DOCKER_ALL_LANES` | 未設定 | 以逗號分隔的精確 lane 清單；略過清理煙霧測試，讓 agent 能重現單一失敗 lane。 |
比有效上限更重的 lane 仍可從空 pool 啟動，然後單獨執行直到釋放容量。本機彙總會預先檢查 Docker、移除過期的 OpenClaw E2E container、輸出 active-lane 狀態、保存 lane timing 以進行 longest-first 排序，並預設在第一次失敗後停止排程新的 pooled lane。
比有效上限更重的 lane 仍可從空集區啟動，然後獨自執行直到釋放容量。本機彙總流程會預先檢查 Docker、移除過期的 OpenClaw E2E 容器、輸出 active-lane 狀態、保存 lane 計時以便最長優先排序，且預設會在第一次失敗後停止排程新的 pooled lane。
### 可重用的 live/E2E workflow
可重用的 live/E2E workflow 會詢問 `scripts/test-docker-all.mjs --plan-json` 需要哪個套件、映像種類、live 映像、lane，以及 credential coverage。`scripts/docker-e2e.mjs` 接著會將該 plan 轉換成 GitHub output 和 summary。它會透過 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下載目前執行的 package artifact，或從 `package_artifact_run_id` 下載 package artifact；驗證 tarball inventory；在 plan 需要 package-installed lane 時，透過 Blacksmith 的 Docker layer cache 建置並推送帶有 package digest 標籤的 bare/functional GHCR Docker E2E 映像；並重複使用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` input 或現有 package-digest 映像，而不是重新建置。Docker 映像拉取會以有界的 180 秒單次嘗試逾時重試，讓卡住的 registry/cache stream 能快速重試，而不是耗掉大部分 CI critical path。
可重用的 live/E2E workflow 會詢問 `scripts/test-docker-all.mjs --plan-json` 需要哪個套件、映像種類、live 映像、lane 和憑證覆蓋範圍。`scripts/docker-e2e.mjs` 接著會將該計畫轉換成 GitHub 輸出和摘要。它會透過 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下載目前執行的套件成品，或從 `package_artifact_run_id` 下載套件成品；驗證 tarball 清單；在計畫需要已安裝套件的 lane 時，透過 Blacksmith 的 Docker layer cache 建置並推送以套件 digest 標記的 bare/functional GHCR Docker E2E 映像；並重用提供的 `docker_e2e_bare_image`/`docker_e2e_functional_image` input 或既有的套件 digest 映像，而不是重新建置。Docker 映像 pull 會使用受限的每次嘗試 180 秒逾時重試，讓卡住的 registry/cache stream 能快速重試，而不是消耗大部分 CI 關鍵路徑。
### Release path chunk
### 發行路徑分塊
Release Docker coverage 會執行較小的 chunked job，並使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，讓每個 chunk 只拉取所需的映像種類，並透過同一個 weighted scheduler 執行多個 lane：
發行 Docker 覆蓋範圍會以較小的 chunked job 搭配 `OPENCLAW_SKIP_DOCKER_BUILD=1` 執行，讓每個 chunk 只 pull 它需要的映像種類，並透過相同的加權 scheduler 執行多個 lane：
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
目前的 release Docker chunk 是 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及從 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍然是 aggregate plugin/runtime alias。`install-e2e` lane alias 仍然是兩個 provider installer lane 的 aggregate manual rerun alias。
目前的發行 Docker chunk 為 `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`，以及 `plugins-runtime-install-a` 到 `plugins-runtime-install-h`。`plugins-runtime-core`、`plugins-runtime` 和 `plugins-integrations` 仍是彙總 Plugin/runtime alias。`install-e2e` lane alias 仍是兩個 provider 安裝程式 lane 的彙總手動重新執行 alias。
當 full release-path coverage 要求時，OpenWebUI 會併入 `plugins-runtime-services`，並只在 OpenWebUI-only dispatch 時保留獨立的 `openwebui` chunk。Bundled-channel update lane 會針對暫時性 npm 網路失敗重試一次。
當完整 release-path 覆蓋範圍要求 OpenWebUI 時，OpenWebUI 會併入 `plugins-runtime-services`，並且只在 OpenWebUI-only dispatch 時保留獨立的 `openwebui` chunk。綑綁 channel update lane 會針對暫時性 npm 網路失敗重試一次。
每個 chunk 都會上傳 `.artifacts/docker-tests/`，其中包含 lane 記錄、timing、`summary.json`、`failures.json`、phase timing、scheduler plan JSON、slow-lane 表格，以及每個 lane 的重新執行命令。workflow 的 `docker_lanes` input 會針對準備好的映像執行選取的 lane，而不是執行 chunk job，這會把 failed-lane 偵錯限制在一個目標 Docker job，並為該次執行準備、下載或重複使用 package artifact；如果選取的 lane 是 live Docker lane，目標 job 會在本機為該次重新執行建置 live-test 映像。產生的每個 lane GitHub 重新執行命令會在存在時包含 `package_artifact_run_id`、`package_artifact_name` 和準備好的映像 input，因此失敗的 lane 可以重複使用失敗執行中的精確套件與映像。
每個 chunk 都會上傳 `.artifacts/docker-tests/`，其中包含 lane 記錄、計時、`summary.json`、`failures.json`、階段計時、scheduler plan JSON、slow-lane 表格，以及每個 lane 的重新執行命令。workflow 的 `docker_lanes` input 會針對已準備的映像執行選取的 lane，而不是 chunk job，這會將失敗 lane 偵錯限制在一個目標 Docker job 中，並為該次執行準備、下載或重用套件成品；如果選取的 lane 是 live Docker lane，目標 job 會在本機為該次重新執行建置 live-test 映像。產生的每個 lane GitHub 重新執行命令會在這些值存在時包含 `package_artifact_run_id`、`package_artifact_name` 和已準備的映像 input，因此失敗的 lane 可以重用失敗執行中的精確套件和映像。
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
排程的 live/E2E workflow 每天執行完整的 release-path Docker suite。
排程的 live/E2E workflow 會每天執行完整的 release-path Docker suite。
## Plugin 預發行
## Plugin 預先發布
`Plugin Prerelease` 是成本更高的 product/package coverage，因此它是由 `Full Release Validation` 或明確 operator dispatch 的獨立 workflow。一般 pull request、`main` push 和獨立的手動 CI dispatch 會保持關閉該 suite。它會在八個 extension worker 之間平衡內建 Plugin 測試；這些 extension shard job 會一次最多執行兩個 Plugin config group，每個 group 使用一個 Vitest worker 和較大的 Node heap，讓 import-heavy 的 Plugin 批次不會建立額外 CI job。僅 release 的 Docker prerelease path 會將目標 Docker lane 以小批次執行，避免為一到三分鐘的 job 保留數十個 runner。
`Plugin Prerelease` 是成本較高的產品/套件覆蓋範圍，因此是由 `Full Release Validation` 或明確的操作人員 dispatch 的獨立 workflow。一般 pull request、`main` push，以及獨立的手動 CI dispatch 都會關閉該 suite。它會將綑綁 Plugin 測試平衡分配到八個 extension worker；這些 extension shard job 一次最多執行兩個 Plugin config group，每個 group 使用一個 Vitest worker 和較大的 Node heap，讓匯入量大的 Plugin 批次不會建立額外的 CI job。僅發行的 Docker 預先發布路徑會以小群組批次執行目標 Docker lane，以避免為一到三分鐘的 job 保留數十個 runner。
## QA Lab
QA Lab 在主要 smart-scoped workflow 之外有專用 CI lane。Agentic parity 巢狀位於廣泛的 QA 和 release harness 之下，而不是獨立的 PR workflow。當 parity 應隨廣泛 validation run 一起執行時，請使用 `Full Release Validation` 搭配 `rerun_group=qa-parity`。
QA Lab 在主要智慧範圍 workflow 之外有專用 CI lane。Agentic parity 巢狀於廣泛的 QA 和發行 harness 下，而不是獨立的 PR workflow。當 parity 應隨廣泛驗證執行一起進行時，請使用 `Full Release Validation` 並指定 `rerun_group=qa-parity`。
- `QA-Lab - All Lanes` workflow 會在 `main` 上 nightly 執行並可手動 dispatch；它會將 mock parity lane、live Matrix lane，以及 live Telegram 和 Discord lane 展開為平行 job。Live job 使用 `qa-live-shared` environment，而 Telegram/Discord 使用 Convex lease。
- `QA-Lab - All Lanes` workflow 會每晚在 `main` 上執行，也可手動 dispatch；它會將 mock parity lane、live Matrix lane，以及 live Telegram 和 Discord lane 展開為平行 job。Live job 使用 `qa-live-shared` environment，而 Telegram/Discord 使用 Convex lease。
Release checks 會使用 deterministic mock provider 和 mock-qualified model（`mock-openai/gpt-5.5` 與 `mock-openai/gpt-5.5-alt`）執行 Matrix 和 Telegram live transport lane，讓 channel contract 與 live model latency 和一般 provider-plugin startup 隔離。live transport gateway 會停用 memory search，因為 QA parity 會另外涵蓋 memory 行為；provider connectivity 由獨立的 live model、native provider 和 Docker provider suite 涵蓋。
Release checks 會使用 deterministic mock provider 和 mock-qualified model（`mock-openai/gpt-5.5` 與 `mock-openai/gpt-5.5-alt`）執行 Matrix 和 Telegram live transport lane，因此 channel contract 會與 live model latency 和一般 provider-plugin startup 隔離。live transport gateway 會停用 memory search，因為 QA parity 會另行涵蓋 memory 行為；provider 連線能力由獨立的 live model、native provider 和 Docker provider suite 涵蓋。
Matrix 對 scheduled 和 release gate 使用 `--profile fast`，並只在 checked-out CLI 支援時加入 `--fail-fast`。CLI 預設值和手動 workflow input 仍為 `all`；手動 `matrix_profile=all` dispatch 一律會將完整 Matrix coverage shard 成 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` job。
Matrix 會針對排程與發行 gate 使用 `--profile fast`，只有在 checked-out CLI 支援時才加入 `--fail-fast`。CLI 預設值和手動 workflow input 仍為 `all`；手動 `matrix_profile=all` dispatch 一律會將完整 Matrix 覆蓋範圍分片成 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` job。
`OpenClaw Release Checks` 也會在 release approval 前執行 release-critical QA Lab lane；它的 QA parity gate 會將 candidate 和 baseline pack 作為平行 lane job 執行，接著將兩者的 artifact 下載到一個小型 report job 中，供最終 parity comparison 使用。
`OpenClaw Release Checks` 也會在發行核准前執行發行關鍵的 QA Lab lane；其 QA parity gate 會將 candidate 和 baseline pack 作為平行 lane job 執行，然後將兩個成品下載到小型 report job 中，進行最終 parity 比較。
對一般 PR，請依循 scoped CI/check evidence，而不是將 parity 視為必要 status。
對一般 PR，請遵循 scoped CI/check 證據，而不是將 parity 視為必要狀態。
## CodeQL
`CodeQL` 工作流程刻意設計為範圍狹窄的第一輪安全掃描器，而不是完整的儲存庫掃描。每日、手動，以及非草稿 pull request 防護執行會掃描 Actions 工作流程程式碼，加上最高風險的 JavaScript/TypeScript 表面，並使用高信心安全查詢，篩選高/重大 `security-severity`。
`CodeQL` 工作流程刻意設計為範圍狹窄的第一輪安全掃描器，而不是完整的儲存庫掃描。每日、手動，以及非草稿拉取請求防護執行會掃描 Actions 工作流程程式碼，以及風險最高的 JavaScript/TypeScript 表面，並使用篩選到高/嚴重 `security-severity` 的高可信度安全查詢。
pull request 防護保持輕量：它只會在 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 底下有變更時啟動，並執行與排程工作流程相同的高信心安全矩陣。Android 與 macOS CodeQL 不包含在 PR 預設值中。
拉取請求防護維持輕量：它只會針對 `.github/actions`、`.github/codeql`、`.github/workflows`、`packages` 或 `src` 底下的變更啟動，並執行與排程工作流程相同的高可信度安全矩陣。Android 與 macOS CodeQL 不列入 PR 預設值。
### 安全類別
| 類別 | 表面 |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | 身分驗證、機密、沙箱、Cron，以及 Gateway 基準 |
| `/codeql-security-high/channel-runtime-boundary` | 核心通道實作合約，加上通道 Plugin 執行階段、Gateway、Plugin SDK、機密、稽核接觸點 |
| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 解析、網路防護、web-fetch，以及 Plugin SDK SSRF 政策表面 |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP 伺服器、程序執行協助程式、對外傳遞，以及代理工具執行門檻 |
| `/codeql-security-high/plugin-trust-boundary` | Plugin 安裝、載入器、manifest、registry、套件管理器安裝、原始碼載入，以及 Plugin SDK 套件合約信任表面 |
| `/codeql-security-high/core-auth-secrets` | 驗證、秘密、沙箱、Cron 與 Gateway 基準 |
| `/codeql-security-high/channel-runtime-boundary` | 核心通道實作合約，加上通道 Plugin 執行階段、Gateway、Plugin SDK、秘密、稽核接觸點 |
| `/codeql-security-high/network-ssrf-boundary` | 核心 SSRF、IP 剖析、網路防護、web-fetch，以及 Plugin SDK SSRF 政策表面 |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP 伺服器、程序執行輔助工具、對外傳遞，以及代理工具執行閘門 |
| `/codeql-security-high/plugin-trust-boundary` | Plugin 安裝、載入器、清單、登錄、套件管理器安裝、來源載入，以及 Plugin SDK 套件合約信任表面 |
### 平台特定安全分片
- `CodeQL Android Critical Security` — 排程的 Android 安全分片。在工作流程健全性接受的最小 Blacksmith Linux runner 上，為 CodeQL 手動建置 Android 應用程式。上傳到 `/codeql-critical-security/android` 底下。
- `CodeQL macOS Critical Security` — 每週/手動的 macOS 安全分片。在 Blacksmith macOS 上為 CodeQL 手動建置 macOS 應用程式，從上傳的 SARIF 中篩除相依性建置結果，並上傳到 `/codeql-critical-security/macos` 底下。保留在每日預設值之外，因為即使乾淨時，macOS 建置也主導執行時間。
- `CodeQL Android Critical Security` — 排程的 Android 安全分片。會在工作流程健全性接受的最小 Blacksmith Linux 執行器上，手動建置 Android 應用程式以供 CodeQL 使用。上傳至 `/codeql-critical-security/android`。
- `CodeQL macOS Critical Security` — 每週/手動的 macOS 安全分片。會在 Blacksmith macOS 上手動建置 macOS 應用程式以供 CodeQL 使用，從上傳的 SARIF 中篩除相依性建置結果，並上傳至 `/codeql-critical-security/macos`。由於 macOS 建置即使乾淨也主導執行時間，因此保留在每日預設值之外。
### 重大品質類別
### 關鍵品質類別
`CodeQL Critical Quality` 是對應的非安全分片。它只在較小的 Blacksmith Linux runner 上，對狹窄的高價值表面執行錯誤嚴重性、非安全的 JavaScript/TypeScript 品質查詢。它的 pull request 防護刻意比排程設定檔更小：非草稿 PR 只會針對代理命令/模型/工具執行與回覆分派程式碼、設定結構描述/遷移/IO 程式碼、身分驗證/機密/沙箱/安全程式碼、核心通道與內建通道 Plugin 執行階段、Gateway protocol/server-method、記憶體執行階段/SDK 黏合程式碼、MCP/程序/對外傳遞、供應商執行階段/模型目錄、工作階段診斷/傳遞佇列、Plugin 載入器、Plugin SDK/套件合約，或 Plugin SDK 回覆執行階段變更，執行對應的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 和 `plugin-sdk-reply-runtime` 分片。CodeQL 設定與品質工作流程變更會執行全部十二個 PR 品質分片。
`CodeQL Critical Quality` 是相對應的非安全分片。它只會在較小的 Blacksmith Linux 執行器上，針對狹窄的高價值表面執行錯誤嚴重性、非安全的 JavaScript/TypeScript 品質查詢。它的拉取請求防護刻意小於排程設定檔：非草稿 PR 只會針對代理命令/模型/工具執行與回覆分派程式碼、設定結構描述/遷移/IO 程式碼、驗證/秘密/沙箱/安全程式碼、核心通道與內建通道 Plugin 執行階段、Gateway 協定/伺服器方法、記憶體執行階段/SDK 膠合層、MCP/程序/對外傳遞、提供者執行階段/模型目錄、工作階段診斷/傳遞佇列、Plugin 載入器、Plugin SDK/套件合約，或 Plugin SDK 回覆執行階段變更，執行相對應的 `agent-runtime-boundary`、`config-boundary`、`core-auth-secrets`、`channel-runtime-boundary`、`gateway-runtime-boundary`、`memory-runtime-boundary`、`mcp-process-runtime-boundary`、`provider-runtime-boundary`、`session-diagnostics-boundary`、`plugin-boundary`、`plugin-sdk-package-contract` 與 `plugin-sdk-reply-runtime` 分片。CodeQL 設定與品質工作流程變更會執行全部十二個 PR 品質分片。
手動分派接受：
@ -417,40 +412,40 @@ pull request 防護保持輕量：它只會在 `.github/actions`、`.github/code
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
狹窄設定檔是用來單獨執行一個品質分片的教學/迭代掛鉤。
窄設定檔是用於單獨執行一個品質分片的教學/迭代掛鉤。
| 類別 | 表面 |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | 身分驗證、機密、沙箱、Cron，以及 Gateway 安全邊界程式碼 |
| `/codeql-critical-quality/config-boundary` | 設定結構描述、遷移、正規化，以及 IO 合約 |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway protocol 結構描述與 server method 合約 |
| `/codeql-critical-quality/core-auth-secrets` | 驗證、秘密、沙箱、Cron 與 Gateway 安全邊界程式碼 |
| `/codeql-critical-quality/config-boundary` | 設定結構描述、遷移、正規化與 IO 合約 |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway 協定結構描述與伺服器方法合約 |
| `/codeql-critical-quality/channel-runtime-boundary` | 核心通道與內建通道 Plugin 實作合約 |
| `/codeql-critical-quality/agent-runtime-boundary` | 命令執行、模型/供應商分派、自動回覆分派與佇列，以及 ACP 控制平面執行階段合約 |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 伺服器與工具橋接、程序監督協助程式，以及對外傳遞合約 |
| `/codeql-critical-quality/memory-runtime-boundary` | 記憶體主機 SDK、記憶體執行階段 facade、記憶體 Plugin SDK 別名、記憶體執行階段啟用黏合程式碼，以及記憶體 doctor 命令 |
| `/codeql-critical-quality/session-diagnostics-boundary` | 回覆佇列內部、工作階段傳遞佇列、對外工作階段繫結/傳遞協助程式、診斷事件/記錄套件表面，以及工作階段 doctor CLI 合約 |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK 傳入回覆分派、回覆 payload/分塊/執行階段協助程式、通道回覆選項、傳遞佇列，以及工作階段/執行緒繫結協助程式 |
| `/codeql-critical-quality/provider-runtime-boundary` | 模型目錄正規化、供應商身分驗證與探索、供應商執行階段註冊、供應商預設值/目錄，以及 web/search/fetch/embedding registry |
| `/codeql-critical-quality/ui-control-plane` | 控制 UI 啟動、本機持久化、Gateway 控制流程，以及任務控制平面執行階段合約 |
| `/codeql-critical-quality/web-media-runtime-boundary` | 核心 web fetch/search、媒體 IO、媒體理解、影像產生，以及媒體產生執行階段合約 |
| `/codeql-critical-quality/plugin-boundary` | 載入器、registry、公開表面，以及 Plugin SDK 進入點合約 |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 已發布套件端 Plugin SDK 原始碼與 Plugin 套件合約協助程式 |
| `/codeql-critical-quality/agent-runtime-boundary` | 命令執行、模型/提供者分派、自動回覆分派與佇列，以及 ACP 控制平面執行階段合約 |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP 伺服器與工具橋接、程序監督輔助工具，以及對外傳遞合約 |
| `/codeql-critical-quality/memory-runtime-boundary` | 記憶體主機 SDK、記憶體執行階段外觀、記憶體 Plugin SDK 別名、記憶體執行階段啟用膠合層，以及記憶體 doctor 命令 |
| `/codeql-critical-quality/session-diagnostics-boundary` | 回覆佇列內部、工作階段傳遞佇列、對外工作階段繫結/傳遞輔助工具、診斷事件/記錄套件表面，以及工作階段 doctor CLI 合約 |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK 傳入回覆分派、回覆承載/分塊/執行階段輔助工具、通道回覆選項、傳遞佇列，以及工作階段/執行緒繫結輔助工具 |
| `/codeql-critical-quality/provider-runtime-boundary` | 模型目錄正規化、提供者驗證與探索、提供者執行階段註冊、提供者預設值/目錄，以及網頁/搜尋/擷取/嵌入登錄 |
| `/codeql-critical-quality/ui-control-plane` | 控制 UI 啟動程序、本機持久化、Gateway 控制流程，以及任務控制平面執行階段合約 |
| `/codeql-critical-quality/web-media-runtime-boundary` | 核心網頁擷取/搜尋、媒體 IO、媒體理解、影像產生，以及媒體產生執行階段合約 |
| `/codeql-critical-quality/plugin-boundary` | 載入器、登錄、公開表面，以及 Plugin SDK 進入點合約 |
| `/codeql-critical-quality/plugin-sdk-package-contract` | 已發布套件端 Plugin SDK 來源與 Plugin 套件合約輔助工具 |
品質與安全保持分離，這樣品質發現就能在不遮蔽安全訊號的情況下排程、測量、停用或擴充。Swift、Python 與內建 Plugin CodeQL 擴充，只有在狹窄設定檔已有穩定執行時間與訊號之後，才應以限定範圍或分片的後續工作加入回來。
品質與安全分開，讓品質發現可以在不遮蔽安全訊號的情況下排程、量測、停用或擴充。Swift、Python 與內建 Plugin 的 CodeQL 擴充，應只在窄設定檔具有穩定執行時間與訊號後，作為有範圍或分片的後續工作加回。
## 維護工作流程
### Docs Agent
`Docs Agent` 工作流程是一條事件驅動的 Codex 維護通道，用於讓現有文件與最近落地的變更保持一致。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，手動分派也可以直接執行它。當 `main` 已經前進，或過去一小時內已建立另一個未略過的 Docs Agent 執行時，workflow-run 呼叫會略過。執行時，它會審查從前一個未略過的 Docs Agent 來源 SHA 到目前 `main` 的提交範圍，因此每小時一次的執行可以涵蓋自上次文件檢查以來累積的所有 main 變更。
`Docs Agent` 工作流程是事件驅動的 Codex 維護通道，用於讓現有文件與最近落地的變更保持一致。它沒有純排程：`main` 上成功的非 bot 推送 CI 執行可以觸發它，也可以透過手動分派直接執行。當 `main` 已推進，或過去一小時內已建立另一個未略過的 Docs Agent 執行時，工作流程執行叫用會略過。執行時，它會審查從上一個未略過的 Docs Agent 來源 SHA 到目前 `main` 的提交範圍，因此每小時一次的執行可以涵蓋自上次文件檢查以來累積的所有 main 變更。
### Test Performance Agent
`Test Performance Agent` 工作流程是一條事件驅動的 Codex 維護通道，用於慢速測試。它沒有純排程：`main` 上成功的非 bot push CI 執行可以觸發它，但如果另一個 workflow-run 呼叫在該 UTC 日已經執行或正在執行，它會略過。手動分派會繞過該每日活動門檻。此通道會建置完整套件分組的 Vitest 效能報告，讓 Codex 只做保留涵蓋率的小型測試效能修正，而不是廣泛重構，接著重新執行完整套件報告，並拒絕會降低通過基準測試數量的變更。如果基準有失敗測試，Codex 只能修正明顯失敗，而且代理之後的完整套件報告必須通過，才會提交任何內容。當 `main` 在 bot push 落地前前進時，此通道會 rebase 已驗證的 patch、重新執行 `pnpm check:changed`，並重試 push；有衝突的過期 patch 會被略過。它使用 GitHub-hosted Ubuntu，讓 Codex action 能維持與 docs agent 相同的 drop-sudo 安全姿態。
`Test Performance Agent` 工作流程是事件驅動的 Codex 維護通道，用於慢速測試。它沒有純排程：`main` 上成功的非 bot 推送 CI 執行可以觸發它，但如果同一個 UTC 日已有另一個工作流程執行叫用已執行或正在執行，它會略過。手動分派會繞過該每日活動閘門。此通道會建立完整套件分組的 Vitest 效能報告，讓 Codex 只進行保留覆蓋率的小型測試效能修正，而不是大型重構，接著重新執行完整套件報告，並拒絕會降低通過基準測試數量的變更。如果基準有失敗測試，Codex 只能修正明顯失敗，而代理之後的完整套件報告必須通過後才會提交任何內容。當 `main` 在 bot 推送落地前推進時，此通道會 rebase 已驗證的修補、重新執行 `pnpm check:changed`，並重試推送；有衝突的過期修補會略過。它使用 GitHub 託管的 Ubuntu，讓 Codex action 可以維持與文件代理相同的 drop-sudo 安全態勢。
### 合併後的重複 PR
`Duplicate PRs After Merge` 工作流程是供維護者用於落地後清理重複項目的手動工作流程。它預設為 dry-run，且只有在 `apply=true` 時才會關閉明確列出的 PR。在修改 GitHub 之前，它會驗證已落地 PR 已合併，且每個重複項目都有共用的引用 issue 或重疊的已變更 hunk。
`Duplicate PRs After Merge` 工作流程是供維護者在落地後清理重複項目的手動工作流程。它預設為 dry-run，且只有在 `apply=true` 時才會關閉明確列出的 PR。在變更 GitHub 前，它會驗證落地 PR 已合併，且每個重複項目都有共享的參照議題或重疊的變更 hunk。
```bash
gh workflow run duplicate-after-merge.yml \
@ -459,29 +454,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## 本機檢查門檻與變更路由
## 本機檢查閘門與變更路由
本機 changed-lane 邏輯位於 `scripts/changed-lanes.mjs`，並由 `scripts/check-changed.mjs` 執行。該本機檢查門檻在架構邊界方面比廣泛的 CI 平台範圍更嚴格：
本機變更通道邏輯位於 `scripts/changed-lanes.mjs`，並由 `scripts/check-changed.mjs` 執行。該本機檢查閘門在架構邊界上比廣泛的 CI 平台範圍更嚴格：
- 核心正式環境變更會執行核心 prod 與核心測試 typecheck，加上核心 lint/guard；
- 只有核心測試的變更只會執行核心測試 typecheck，加上核心 lint；
- extension 正式環境變更會執行 extension prod 與 extension 測試 typecheck，加上 extension lint；
- 只有 extension 測試的變更會執行 extension 測試 typecheck，加上 extension lint；
- 公開 Plugin SDK 或 Plugin 合約變更會擴展到 extension typecheck，因為 extension 依賴那些核心合約（Vitest extension 掃描仍是明確的測試工作）；
- 只有 release metadata 的版本 bump 會執行目標式版本/設定/root-dependency 檢查；
- 未知的根目錄/設定變更會以失敗安全方式進入所有檢查通道。
- 核心生產變更會執行核心 prod 與核心 test 型別檢查，加上核心 lint/guard；
- 僅核心測試的變更只會執行核心 test 型別檢查，加上核心 lint；
- 擴充生產變更會執行擴充 prod 與擴充 test 型別檢查，加上擴充 lint；
- 僅擴充測試的變更會執行擴充 test 型別檢查，加上擴充 lint；
- 公開 Plugin SDK 或 Plugin 合約變更會擴展到擴充型別檢查，因為擴充依賴那些核心合約（Vitest 擴充掃描仍然是明確的測試工作）；
- 僅發布中繼資料的版本升級會執行目標版本/設定/根相依性檢查；
- 未知的根目錄/設定變更會安全失敗到所有檢查通道。
本機 changed-test 路由位於 `scripts/test-projects.test-support.mjs`，且刻意比 `check:changed` 更便宜：直接測試編輯會執行自身，原始碼編輯優先使用明確對應，接著才是同層測試與匯入圖依賴項。共用 group-room 傳遞設定是明確對應之一：對群組可見回覆設定、來源回覆傳遞模式，或 message-tool 系統提示的變更，會路由通過核心回覆測試，加上 Discord 與 Slack 傳遞迴歸測試，讓共用預設變更在第一次 PR push 前就失敗。只有在變更足夠涵蓋整個 harness，使廉價對應集合不再是可信代理時，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
本機變更測試路由位於 `scripts/test-projects.test-support.mjs`，且刻意比 `check:changed` 便宜：直接測試編輯會執行自身，來源編輯會優先使用明確映射，接著是同層測試與匯入圖相依項。共享群組房間傳遞設定是明確映射之一：對群組可見回覆設定、來源回覆傳遞模式，或訊息工具系統提示的變更，會透過核心回覆測試加上 Discord 與 Slack 傳遞回歸測試路由，讓共享預設值變更在第一次 PR 推送前就失敗。只有當變更足夠涵蓋整個測試框架，使便宜的映射集合不是可信代理時，才使用 `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`。
## Testbox 驗證
從存放庫根目錄執行 Testbox，並在需要廣泛驗證時優先使用全新預熱的 box。在把緩慢的 gate 花在重複使用、過期，或剛回報異常大型同步的 box 之前，請先在 box 內執行 `pnpm testbox:sanity`。
從儲存庫根目錄執行 Testbox，且進行廣泛驗證時優先使用全新預熱的 box。在把耗時檢查關卡用於重複使用、已過期，或剛回報非預期大型同步的 box 之前，請先在該 box 內執行 `pnpm testbox:sanity`。
當必要的根目錄檔案（例如 `pnpm-lock.yaml`）消失，或 `git status --short` 顯示至少 200 個已追蹤檔案遭刪除時，健全性檢查會快速失敗。這通常表示遠端同步狀態不是 PR 的可信副本；請停止該 box，並改為預熱新的 box，而不是除錯產品測試失敗。對於刻意大量刪除的 PR，請在該次健全性執行中設定 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
當必要的根目錄檔案如 `pnpm-lock.yaml` 消失，或 `git status --short` 顯示至少 200 個已追蹤刪除項目時，健全性檢查會快速失敗。這通常表示遠端同步狀態不是 PR 的可信副本；請停止該 box 並改為預熱新的 box，而不是偵錯產品測試失敗。對於刻意大量刪除的 PR，請為該次健全性執行設定 `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`。
`pnpm testbox:run` 也會終止在同步階段停留超過五分鐘且沒有同步後輸出的本機 Blacksmith CLI 呼叫。設定 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可停用該防護，或針對異常大型的本機 diff 使用較大的毫秒值。
`pnpm testbox:run` 也會終止在同步階段停留超過五分鐘且沒有同步後輸出的本機 Blacksmith CLI 呼叫。設定 `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` 可停用該保護；若本機差異異常龐大，則可使用較大的毫秒值。
當 Blacksmith 無法使用，或偏好使用自有雲端容量時，Crabbox 是此存放庫擁有的第二條 Linux 驗證遠端 box 路徑。預熱一個 box，透過專案工作流程 hydrate 它，然後透過 Crabbox CLI 執行命令：
當 Blacksmith 無法使用，或偏好使用自有雲端容量時，Crabbox 是儲存庫自有的第二條遠端 box Linux 驗證路徑。預熱一個 box，透過專案工作流程補齊其環境，接著透過 Crabbox CLI 執行命令：
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -490,7 +485,7 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` 負責 provider、同步與 GitHub Actions hydrate 預設值。它會排除本機 `.git`，讓已 hydrate 的 Actions checkout 保留自己的遠端 Git 中繼資料，而不是同步維護者本機的 remote 與 object store；也會排除不應被傳輸的本機執行階段/建置成品。`.github/workflows/crabbox-hydrate.yml` 負責 checkout、Node/pnpm 設定、`origin/main` fetch，以及後續 `crabbox run --id <cbx_id>` 命令會 source 的非機密環境交接。
`.crabbox.yaml` 管理提供者、同步與 GitHub Actions 環境補齊預設值。它會排除本機 `.git`，讓已補齊環境的 Actions checkout 保留自己的遠端 Git 中繼資料，而不是同步維護者本機的遠端與物件儲存；也會排除不應被傳輸的本機執行階段與建置成品。`.github/workflows/crabbox-hydrate.yml` 管理 checkout、Node/pnpm 設定、`origin/main` 擷取，以及後續 `crabbox run --id <cbx_id>` 命令會載入的非祕密環境交接。
## 相關內容

223
docs/zh-TW/concepts/system-prompt.md
View File

@ -1,93 +1,148 @@
---
read_when:
- 編輯系統提示詞文字、工具清單或時間/Heartbeat 區段
- 編輯系統提示文字、工具清單，或時間/Heartbeat 區段
- 變更工作區啟動程序或 Skills 注入行為
summary: OpenClaw 系統提示包含哪些內容，以及如何組裝
title: 系統提示
summary: OpenClaw 系統提示詞包含哪些內容以及如何組裝
title: 系統提示詞
x-i18n:
generated_at: "2026-05-02T22:18:03Z"
generated_at: "2026-05-02T23:39:08Z"
model: gpt-5.5
provider: openai
source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c
source_hash: f8e0234453812c16cf5d273096d335049bf435ca76ade36200caf4bb344624e5
source_path: concepts/system-prompt.md
workflow: 16
---
OpenClaw 會為每次代理執行建構自訂系統提示。此提示由 **OpenClaw 擁有**，不使用 pi-coding-agent 預設提示。
OpenClaw 會為每次代理執行建構自訂系統提示。此提示由 **OpenClaw 擁有**，不使用 pi-coding-agent 的預設提示。
提示由 OpenClaw 組裝，並注入每次代理執行。
提供者 Plugin 可以貢獻具快取感知能力的提示指引，而不取代完整的 OpenClaw 擁有提示。提供者執行階段可以：
Provider plugins 可以提供具快取感知的提示指引，而不取代
完整的 OpenClaw 擁有提示。Provider runtime 可以：
- 取代一小組具名核心區段（`interaction_style`、`tool_call_style`、`execution_bias`）
- 取代一小組具名核心區段（`interaction_style`、
`tool_call_style`、`execution_bias`）
- 在提示快取邊界上方注入**穩定前綴**
- 在提示快取邊界下方注入**動態後綴**
請將提供者擁有的貢獻用於模型系列特定調校。保留舊版 `before_prompt_build` 提示變異功能，用於相容性或真正全域性的提示變更，而不是一般提供者行為。
請使用 provider 擁有的貢獻來進行模型家族專屬調整。保留舊版
`before_prompt_build` 提示變更，用於相容性或真正全域的提示
變更，而非一般 provider 行為。
OpenAI GPT-5 系列覆蓋層會讓核心執行規則保持精簡，並加入模型特定指引，涵蓋角色固定、精簡輸出、工具紀律、平行查詢、交付項覆蓋、驗證、缺少脈絡，以及終端機工具衛生。
OpenAI GPT-5 家族覆蓋層會保持核心執行規則精簡，並加入
模型專屬指引，涵蓋人格鎖定、精簡輸出、工具紀律、
平行查詢、交付成果涵蓋、驗證、缺失脈絡，以及
終端機工具衛生。
## 結構
提示刻意保持精簡，並使用固定區段：
- **工具**：結構化工具事實來源提醒，以及執行階段工具使用指引。
- **執行偏向**：精簡的跟進指引：針對可執行請求在回合內行動、持續進行直到完成或受阻、從弱工具結果中恢復、即時檢查可變狀態，並在最終回覆前驗證。
- **安全**：簡短的護欄提醒，避免追求權力的行為或繞過監督。
- **Skills**（可用時）：告知模型如何按需載入 Skill 指示。
- **OpenClaw 自我更新**：如何使用 `config.schema.lookup` 安全檢查設定、使用 `config.patch` 修補設定、使用 `config.apply` 取代完整設定，並且只在使用者明確要求時執行 `update.run`。僅限擁有者的 `gateway` 工具也會拒絕重寫 `tools.exec.ask` / `tools.exec.security`，包含會正規化為這些受保護執行路徑的舊版 `tools.bash.*` 別名。
- **工具**：結構化工具的真實來源提醒，以及執行階段工具使用指引。
- **執行偏向**：精簡的跟進指引：對可執行請求在同一回合採取行動，
持續進行直到完成或受阻，從薄弱工具結果中復原，現場檢查可變狀態，
並在最終回覆前驗證。
- **安全**：簡短護欄提醒，避免追求權力的行為或繞過監督。
- **Skills**（可用時）：告知模型如何按需載入 skill 指示。
- **OpenClaw 自我更新**：如何使用
`config.schema.lookup` 安全檢查設定、使用 `config.patch` 修補設定、
使用 `config.apply` 取代完整設定，並且只在使用者明確要求時執行
`update.run`。僅限擁有者的 `gateway` 工具也會拒絕重寫
`tools.exec.ask` / `tools.exec.security`，包括會正規化到這些受保護
exec 路徑的舊版 `tools.bash.*` 別名。
- **工作區**：工作目錄（`agents.defaults.workspace`）。
- **文件**：OpenClaw 文件的本機路徑（repo 或 npm 套件），以及何時閱讀。
- **工作區檔案（已注入）**：表示啟動檔案已包含於下方。
- **沙盒**（啟用時）：表示沙盒化執行階段、沙盒路徑，以及是否可用提升權限的 exec。
- **工作區檔案（已注入）**：表示 bootstrap 檔案會包含在下方。
- **沙箱**（啟用時）：表示沙箱化執行階段、沙箱路徑，以及是否可使用提升權限的 exec。
- **目前日期與時間**：使用者本地時間、時區與時間格式。
- **回覆標籤**：支援提供者的選用回覆標籤語法。
- **Heartbeat**：預設代理啟用 Heartbeat 時的 Heartbeat 提示與確認行為。
- **執行階段**：主機、作業系統、node、模型、repo 根目錄（偵測到時）、思考層級（一行）。
- **回覆標籤**：受支援 provider 的選用回覆標籤語法。
- **Heartbeat**：當預設代理啟用 Heartbeat 時的 Heartbeat 提示與 ack 行為。
- **執行階段**：主機、作業系統、Node、模型、repo 根目錄（偵測到時）、思考層級（一行）。
- **推理**：目前可見性層級 + /reasoning 切換提示。
OpenClaw 會將大型穩定內容（包含 **專案脈絡**）保留在內部提示快取邊界上方。易變的頻道/工作階段區段，例如 Control UI 嵌入指引、**訊息**、**語音**、**群組聊天脈絡**、**反應**、**Heartbeat** 與 **執行階段**，會附加在該邊界下方，讓具備前綴快取的本機後端能在不同頻道回合間重用穩定的工作區前綴。同樣地，當接受的 schema 已承載該執行階段細節時，工具描述也應避免嵌入目前頻道名稱。
OpenClaw 會將大型穩定內容（包括**專案脈絡**）保留在
內部提示快取邊界上方。易變的頻道/工作階段區段，例如
Control UI 嵌入指引、**訊息**、**語音**、**群組聊天脈絡**、
**反應**、**Heartbeat** 與**執行階段**，會附加在該邊界下方，
讓具有前綴快取的本機後端可跨頻道回合重用穩定的工作區前綴。
同樣地，當接受的 schema 已攜帶該執行階段細節時，工具描述應避免
嵌入目前頻道名稱。
工具區段也包含長時間執行工作的執行階段指引：
- 將 Cron 用於未來跟進（`check back later`、提醒、週期性工作），而不是 `exec` 睡眠迴圈、`yieldMs` 延遲技巧，或重複的 `process` 輪詢
- 只將 `exec` / `process` 用於現在啟動並在背景持續執行的命令
- 啟用自動完成喚醒時，只啟動命令一次，並在其輸出或失敗時依賴推送式喚醒路徑
- 當需要檢查執行中命令的記錄、狀態、輸入或介入時，使用 `process`
- 如果任務較大，優先使用 `sessions_spawn`；子代理完成是推送式的，並會自動向請求者回報
- 不要只是為了等待完成而在迴圈中輪詢 `subagents list` / `sessions_list`
- 對未來跟進（`check back later`、提醒、週期性工作）使用 Cron，
而不是 `exec` sleep 迴圈、`yieldMs` 延遲技巧，或重複的 `process`
輪詢
- 只有對現在開始並持續在背景執行的命令，才使用 `exec` / `process`
- 當啟用自動完成喚醒時，啟動命令一次，並在它輸出或失敗時依賴
推送式喚醒路徑
- 當你需要檢查正在執行的命令時，使用 `process` 取得記錄、狀態、
輸入或介入
- 如果任務更大，優先使用 `sessions_spawn`；子代理完成採推送式，
且會自動向請求者公告
- 不要只為了等待完成而在迴圈中輪詢 `subagents list` / `sessions_list`
啟用實驗性 `update_plan` 工具時，工具區段也會告知模型僅將其用於非瑣碎的多步驟工作、精確保持一個 `in_progress` 步驟，並避免在每次更新後重複整份計畫。
當啟用實驗性的 `update_plan` 工具時，工具區段也會告知模型
只將它用於非簡單的多步驟工作、確保正好一個 `in_progress` 步驟，
並避免在每次更新後重複整個計畫。
系統提示中的安全護欄屬於建議性質。它們引導模型行為，但不強制執行政策。請使用工具政策、exec 核准、沙盒化與頻道 allowlist 進行硬性強制；操作員可以依設計停用這些機制。
系統提示中的安全護欄是建議性質。它們會引導模型行為，但不強制執行政策。請使用工具政策、exec 核准、沙箱化與頻道允許清單進行硬性執行；操作者可按設計停用這些機制。
在具備原生核准卡片/按鈕的頻道上，執行階段提示現在會告知代理優先依賴該原生核准 UI。只有在工具結果表示聊天核准不可用，或手動核准是唯一路徑時，才應包含手動 `/approve` 命令。
在具備原生核准卡片/按鈕的頻道上，執行階段提示現在會告知
代理優先依賴該原生核准 UI。只有當工具結果表示聊天核准不可用，
或手動核准是唯一途徑時，才應包含手動 `/approve` 命令。
## 提示模式
OpenClaw 可以為子代理轉譯較小的系統提示。執行階段會為每次執行設定 `promptMode`（不是使用者可見設定）：
OpenClaw 可以為子代理渲染較小的系統提示。執行階段會為每次執行設定
`promptMode`（不是面向使用者的設定）：
- `full`（預設）：包含上述所有區段。
- `minimal`：用於子代理；省略 **Skills**、**記憶回想**、**OpenClaw 自我更新**、**模型別名**、**使用者身分**、**回覆標籤**、**訊息**、**靜默回覆** 與 **Heartbeat**。工具、**安全**、工作區、沙盒、目前日期與時間（已知時）、執行階段，以及注入的脈絡仍會保留。
- `none`：只回傳基礎身分行。
- `minimal`：用於子代理；省略 **Skills**、**記憶回想**、**OpenClaw
自我更新**、**模型別名**、**使用者身分**、**回覆標籤**、
**訊息**、**靜默回覆** 與 **Heartbeat**。工具、**安全**、
工作區、沙箱、目前日期與時間（已知時）、執行階段，以及注入的
脈絡仍可使用。
- `none`：只傳回基礎身分行。
當 `promptMode=minimal` 時，額外注入的提示會標示為 **子代理脈絡**，而不是 **群組聊天脈絡**。
當 `promptMode=minimal` 時，額外注入的提示會標示為**子代理脈絡**，
而不是**群組聊天脈絡**。
對於頻道自動回覆執行，當直接/群組聊天脈絡已包含已解析的對話特定 `NO_REPLY` 行為時，OpenClaw 可以省略通用的 **靜默回覆** 區段。這可避免在全域系統提示和頻道脈絡中重複 token 機制。
對於頻道自動回覆執行，當直接/群組聊天脈絡已包含已解析的
對話專屬 `NO_REPLY` 行為時，OpenClaw 可以省略通用的**靜默回覆**
區段。這可避免在全域系統提示與頻道脈絡中同時重複 token 機制。
## 提示快照
OpenClaw 會在 `test/fixtures/agents/prompt-snapshots/happy-path/` 下保留已提交的 Codex/message-tool 執行階段 happy-path 提示快照。它們會轉譯選定的 app-server thread/turn 參數，以及重建的模型綁定提示層堆疊，用於 Telegram 直接訊息、Discord 群組與 Heartbeat 回合。該堆疊包含從 Codex 模型目錄/快取形狀產生的固定 Codex `gpt-5.5` 模型提示 fixture、Codex happy-path 權限開發者文字、OpenClaw 開發者指示、使用者回合輸入，以及動態工具規格的參照。
OpenClaw 會將 Codex runtime 快樂路徑的已提交提示快照保存在
`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/` 下。它們會渲染
選定的 app-server thread/turn 參數，以及重建的模型綁定提示
層堆疊，用於 Telegram 直接訊息、Discord 群組與 Heartbeat 回合。該堆疊
包含從 Codex 的模型目錄/快取形狀產生的固定 Codex `gpt-5.5`
模型提示 fixture、Codex 快樂路徑權限 developer 文字、
OpenClaw developer 指示、使用者回合輸入，以及動態工具規格的參照。
使用 `pnpm prompt:snapshots:sync-codex-model` 重新整理固定的 Codex 模型提示 fixture。預設情況下，腳本會先尋找 `$CODEX_HOME/models_cache.json` 中的 Codex 執行階段快取，接著尋找 `~/.codex/models_cache.json`，最後才退回到維護者 Codex checkout 慣例位置 `~/code/codex/codex-rs/models-manager/models.json`。如果這些來源都不存在，命令會結束且不變更已提交的 fixture。傳入 `--catalog <path>` 可從特定 `models_cache.json` 或 `models.json` 檔案重新整理。
使用 `pnpm prompt:snapshots:sync-codex-model` 重新整理固定的 Codex 模型提示 fixture。預設情況下，此腳本會先尋找
Codex 在 `$CODEX_HOME/models_cache.json` 的執行階段快取，接著是
`~/.codex/models_cache.json`，最後才退回到維護者 Codex
checkout 慣例位置 `~/code/codex/codex-rs/models-manager/models.json`。如果
這些來源都不存在，命令會結束且不變更已提交的 fixture。傳入
`--catalog <path>` 可從特定的 `models_cache.json`
或 `models.json` 檔案重新整理。
這些快照仍不是逐位元組相同的原始 OpenAI 請求擷取。Codex 可以在 OpenClaw 送出 thread 和 turn 參數後，在 Codex 執行階段內加入執行階段擁有的工作區脈絡，例如 `AGENTS.md`、環境脈絡、記憶、應用程式/Plugin 指示，以及未來的協作模式指示。
這些快照仍不是逐位元組一致的原始 OpenAI 請求擷取。OpenClaw 傳送 thread 與 turn
參數後，Codex 仍可在 Codex runtime 內加入 runtime 擁有的工作區脈絡，
例如 `AGENTS.md`、環境脈絡、記憶、app/plugin 指示，以及未來的協作模式
指示。
使用 `pnpm prompt:snapshots:gen` 重新產生它們，並使用 `pnpm prompt:snapshots:check` 驗證漂移。CI 會在額外的 boundary shard 中執行漂移檢查，讓提示變更與快照更新保持附著於同一個 PR。
使用 `pnpm prompt:snapshots:gen` 重新產生它們，並使用
`pnpm prompt:snapshots:check` 驗證漂移。CI 會在額外的
boundary shard 中執行漂移檢查，讓提示變更與快照更新保持附著在同一個
PR。
## 工作區啟動注入
## 工作區 bootstrap 注入
啟動檔案會被修剪並附加在 **專案脈絡** 下，讓模型無需明確讀取即可看到身分與設定檔脈絡：
Bootstrap 檔案會經裁剪後附加在**專案脈絡**之下，讓模型不需明確讀取即可看到身分與設定檔脈絡：
- `AGENTS.md`
- `SOUL.md`
@ -98,42 +153,72 @@ OpenClaw 會在 `test/fixtures/agents/prompt-snapshots/happy-path/` 下保留已
- `BOOTSTRAP.md`（僅限全新工作區）
- `MEMORY.md`（存在時）
除非套用檔案特定 gate，否則這些檔案全都會在每個回合**注入脈絡視窗**。當預設代理停用 Heartbeat，或 `agents.defaults.heartbeat.includeSystemPromptSection` 為 false 時，正常執行會省略 `HEARTBEAT.md`。請讓注入檔案保持精簡，尤其是 `MEMORY.md`，它可能會隨時間成長，導致出乎預期的高脈絡使用量與更頻繁的 Compaction。
除非套用檔案專屬 gate，否則所有這些檔案都會在每個回合中
**注入到脈絡視窗**。當預設代理停用 Heartbeat，或
`agents.defaults.heartbeat.includeSystemPromptSection` 為 false 時，
一般執行會省略 `HEARTBEAT.md`。保持注入檔案精簡，尤其是
`MEMORY.md`，它可能隨時間增長，導致非預期的高脈絡用量與更頻繁的
Compaction。
當工作階段在原生 Codex harness 上執行時，Codex 會透過自己的
專案文件探索載入 `AGENTS.md`。OpenClaw 仍會解析其餘
bootstrap 檔案，並將它們作為 Codex 設定指示轉送，因此 `SOUL.md`、
`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 與
`MEMORY.md` 會維持相同的工作區脈絡角色，而不重複
`AGENTS.md`。
<Note>
`memory/*.md` 每日檔案**不是**一般啟動專案脈絡的一部分。在普通回合中，它們會透過 `memory_search` 和 `memory_get` 工具按需存取，因此除非模型明確讀取，否則不會計入脈絡視窗。裸 `/new` 和 `/reset` 回合是例外：執行階段可以將近期每日記憶作為一次性啟動脈絡區塊前置於該第一個回合。
`memory/*.md` 每日檔案**不是**一般 bootstrap 專案脈絡的一部分。在一般回合中，它們會透過 `memory_search` 和 `memory_get` 工具按需存取，因此除非模型明確讀取它們，否則不會計入脈絡視窗。裸 `/new` 和 `/reset` 回合是例外：執行階段可將最近的每日記憶作為一次性的啟動脈絡區塊，前置到該第一回合。
</Note>
大型檔案會以標記截斷。每個檔案的最大大小由 `agents.defaults.bootstrapMaxChars` 控制（預設：12000）。跨檔案注入的啟動內容總量上限由 `agents.defaults.bootstrapTotalMaxChars` 控制（預設：60000）。缺少檔案會注入簡短的缺少檔案標記。發生截斷時，OpenClaw 可以在專案脈絡中注入警告區塊；可用 `agents.defaults.bootstrapPromptTruncationWarning` 控制此行為（`off`、`once`、`always`；預設：`once`）。
大型檔案會以標記截斷。每個檔案的最大大小由
`agents.defaults.bootstrapMaxChars` 控制（預設：12000）。跨檔案注入的
bootstrap 內容總量由 `agents.defaults.bootstrapTotalMaxChars` 限制
（預設：60000）。缺失檔案會注入簡短的缺失檔案標記。發生截斷時，
OpenClaw 可在專案脈絡中注入警告區塊；使用
`agents.defaults.bootstrapPromptTruncationWarning` 控制此行為（`off`、`once`、`always`；
預設：`once`）。
子代理工作階段只會注入 `AGENTS.md` 和 `TOOLS.md`（其他啟動檔案會被過濾掉，以保持子代理脈絡精簡）。
子代理工作階段只會注入 `AGENTS.md` 和 `TOOLS.md`（其他 bootstrap 檔案
會被濾除，以保持子代理脈絡精簡）。
內部 hook 可以透過 `agent:bootstrap` 攔截此步驟，以變異或取代注入的啟動檔案（例如將 `SOUL.md` 換成替代人格）。
內部 hook 可透過 `agent:bootstrap` 攔截此步驟，以變更或取代
注入的 bootstrap 檔案（例如將 `SOUL.md` 換成替代人格）。
如果你想讓代理聽起來較不通用，請從 [SOUL.md 人格指南](/zh-TW/concepts/soul) 開始。
如果你想讓代理聽起來不那麼泛用，請從
[SOUL.md 人格指南](/zh-TW/concepts/soul) 開始。
若要檢查每個注入檔案貢獻多少內容（原始與注入、截斷，加上工具 schema 開銷），請使用 `/context list` 或 `/context detail`。請參閱 [脈絡](/zh-TW/concepts/context)。
若要檢查每個注入檔案貢獻多少內容（原始與注入、截斷，以及工具 schema 額外負擔），請使用 `/context list` 或 `/context detail`。請參閱[脈絡](/zh-TW/concepts/context)。
## 時間處理
當使用者時區已知時，系統提示會包含專用的 **目前日期與時間** 區段。為了讓提示快取保持穩定，現在它只包含**時區**（不包含動態時鐘或時間格式）。
當使用者時區已知時，系統提示會包含專用的**目前日期與時間**區段。
為保持提示快取穩定，現在只會包含**時區**（不包含動態時鐘或時間格式）。
當代理需要目前時間時，請使用 `session_status`；狀態卡片包含時間戳記行。同一工具也可以選擇性地設定每工作階段模型覆寫（`model=default` 會清除它）。
當代理需要目前時間時，請使用 `session_status`；狀態卡片包含
時間戳記行。同一工具也可選擇設定每工作階段的模型覆蓋
（`model=default` 會清除它）。
使用以下項目設定：
設定項目：
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat`（`auto` | `12` | `24`）
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
請參閱 [日期與時間](/zh-TW/date-time) 以取得完整行為細節。
完整行為細節請參閱[日期與時間](/zh-TW/date-time)。
## Skills
當存在符合資格的 Skills 時，OpenClaw 會注入精簡的**可用 Skills 清單**（`formatSkillsForPrompt`），其中包含每個 Skill 的**檔案路徑**。提示會指示模型使用 `read` 載入列出位置（工作區、受管理或內建）中的 SKILL.md。如果沒有符合資格的 Skills，則會省略 Skills 區段。
當存在符合資格的 skills 時，OpenClaw 會注入精簡的**可用 skills 清單**
（`formatSkillsForPrompt`），其中包含每個 skill 的**檔案路徑**。提示會
指示模型使用 `read` 載入列出位置（工作區、受管理或 bundled）中的
SKILL.md。若沒有符合資格的 skills，則會省略 Skills 區段。
資格包含 Skill 中繼資料 gate、執行階段環境/設定檢查，以及設定 `agents.defaults.skills` 或 `agents.list[].skills` 時的有效代理 Skill allowlist。
資格包含 skill metadata gates、執行階段環境/設定檢查，以及設定
`agents.defaults.skills` 或 `agents.list[].skills` 時的有效代理 skill 允許清單。
Plugin 內建 Skills 只有在其擁有的 Plugin 啟用時才符合資格。這讓工具 Plugin 能公開更深入的操作指南，而不必將所有指引直接嵌入每個工具描述中。
Plugin-bundled skills 只有在其所屬 plugin 啟用時才符合資格。
這讓工具 plugins 能揭露更深入的操作指南，而不需將所有
指引直接嵌入每個工具描述。
```
<available_skills>
@ -145,34 +230,28 @@ Plugin 內建 Skills 只有在其擁有的 Plugin 啟用時才符合資格。這
</available_skills>
```
這會讓基礎提示保持精簡，同時仍啟用目標式 Skill 使用。
這會讓基礎提示保持精簡，同時仍能啟用目標式 skill 使用。
Skills 清單預算由 Skills 子系統擁有：
skills 清單預算由 skills 子系統擁有：
- 全域預設：`skills.limits.maxSkillsPromptChars`
- 每代理覆寫：`agents.list[].skillsLimits.maxSkillsPromptChars`
- 每代理覆蓋：`agents.list[].skillsLimits.maxSkillsPromptChars`
通用有界執行階段摘錄使用不同介面：
通用的有界執行階段摘錄使用不同介面：
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
此分離讓 Skills 大小設定與執行階段讀取/注入大小設定保持分開，例如 `memory_get`、即時工具結果，以及 Compaction 後的 AGENTS.md 重新整理。
這樣的拆分會將 Skills 大小設定與執行階段讀取／注入大小設定分開，例如 `memory_get`、即時工具結果，以及 Compaction 後的 AGENTS.md 重新整理。
## 文件
系統提示包含一個 **文件** 區段。當本機文件可用時，它會指向本機 OpenClaw 文件目錄（Git checkout 中的 `docs/`，或隨附 npm 套件的文件）。如果本機文件不可用，則會改用
[https://docs.openclaw.ai](https://docs.openclaw.ai)。
系統提示包含一個 **文件** 區段。當本機文件可用時，它會指向本機 OpenClaw 文件目錄（Git checkout 中的 `docs/`，或 bundled npm package docs）。如果本機文件不可用，則會退回到 [https://docs.openclaw.ai](https://docs.openclaw.ai)。
同一區段也包含 OpenClaw 原始碼位置。Git checkout 會公開本機原始碼根目錄，讓代理可以直接檢查程式碼。套件安裝則包含 GitHub 原始碼 URL，並指示代理在文件不完整或過時時到該處檢閱原始碼。提示也會提及公開文件鏡像、社群 Discord，以及用於探索 Skills 的 ClawHub
([https://clawhub.ai](https://clawhub.ai))。它會指示模型在處理 OpenClaw 行為、命令、設定或架構時先查閱文件，並在可行時自行執行 `openclaw status`（只有在缺乏存取權時才詢問使用者）。
特別針對設定，它會指引代理使用 `gateway` 工具動作
`config.schema.lookup` 取得精確的欄位層級文件與限制，然後再參閱
`docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md`
以取得更廣泛的指引。
同一區段也包含 OpenClaw 原始碼位置。Git checkouts 會公開本機原始碼根目錄，讓代理程式可以直接檢查程式碼。套件安裝會包含 GitHub 原始碼 URL，並告知代理程式在文件不完整或過時時到該處檢閱原始碼。提示也會註明公開文件鏡像、社群 Discord，以及用於探索 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。它會告知模型，對於 OpenClaw 行為、命令、設定或架構，應先查閱文件，並在可行時自行執行 `openclaw status`（只有在缺乏存取權時才詢問使用者）。特別針對設定，它會將代理程式指向 `gateway` 工具動作 `config.schema.lookup`，以取得精確的欄位層級文件與限制，然後再參閱 `docs/gateway/configuration.md` 和 `docs/gateway/configuration-reference.md` 取得更廣泛的指引。
## 相關
- [代理執行階段](/zh-TW/concepts/agent)
- [代理工作區](/zh-TW/concepts/agent-workspace)
- [上下文引擎](/zh-TW/concepts/context-engine)
- [代理程式執行階段](/zh-TW/concepts/agent)
- [代理程式工作區](/zh-TW/concepts/agent-workspace)
- [Context engine](/zh-TW/concepts/context-engine)

115
docs/zh-TW/nodes/audio.md
View File

@ -1,52 +1,53 @@
---
read_when:
- 變更音訊轉錄或媒體處理
summary: 傳入音訊／語音訊息的下載、轉錄與注入回覆方式
summary: 傳入音訊/語音訊息如何下載、轉錄並注入回覆中
title: 音訊與語音訊息
x-i18n:
generated_at: "2026-04-30T03:17:30Z"
generated_at: "2026-05-02T23:38:58Z"
model: gpt-5.5
provider: openai
source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7
source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1
source_path: nodes/audio.md
workflow: 16
---
# 音訊 / 語音備忘錄（2026-01-17）
# 音訊 / 語音訊息 (2026-01-17)
## 可用功能
## 可運作項目
- **媒體理解（音訊）**：如果啟用（或自動偵測到）音訊理解，OpenClaw 會：
1. 找出第一個音訊附件（本機路徑或 URL），並視需要下載。
2. 在傳送到每個模型項目之前強制套用 `maxBytes`。
3. 依序執行第一個符合資格的模型項目（provider 或 CLI）。
4. 如果失敗或略過（大小/逾時），會嘗試下一個項目。
5. 成功時，會以 `[Audio]` 區塊取代 `Body`，並設定 `{{Transcript}}`。
- **指令解析**：轉錄成功時，`CommandBody`/`RawBody` 會設定為逐字稿，因此斜線指令仍可運作。
- **媒體理解（音訊）**：如果已啟用音訊理解（或已自動偵測），OpenClaw 會：
1. 找到第一個音訊附件（本機路徑或 URL），並視需要下載。
2. 在傳送到每個模型項目之前套用 `maxBytes` 限制。
3. 依序執行第一個符合資格的模型項目（提供者或 CLI）。
4. 如果失敗或略過（大小/逾時），就嘗試下一個項目。
5. 成功時，會將 `Body` 取代為 `[Audio]` 區塊，並設定 `{{Transcript}}`。
- **命令解析**：轉錄成功時，`CommandBody`/`RawBody` 會設為逐字稿，讓斜線命令仍可運作。
- **詳細記錄**：在 `--verbose` 中，我們會記錄轉錄何時執行，以及何時取代本文。
- **控制 UI 聽寫**：聊天撰寫器可以將瀏覽器錄製的麥克風片段傳送到 `chat.transcribeAudio`。該 Gateway RPC 會將片段寫入暫存本機檔案、執行相同的音訊轉錄管線、將草稿文字傳回瀏覽器，並刪除暫存檔。它本身不會建立代理執行。
## 自動偵測（預設）
如果你**未設定模型**，且 `tools.media.audio.enabled` **沒有**設為 `false`，
OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項時停止：
如果你**未設定模型**，且 `tools.media.audio.enabled` **未**設為 `false`，
OpenClaw 會依下列順序自動偵測，並在第一個可運作的選項停止：
1. **作用中的回覆模型**，當其 provider 支援音訊理解時。
1. 當其提供者支援音訊理解時，使用**作用中的回覆模型**。
2. **本機 CLI**（若已安裝）
- `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder/decoder/joiner/tokens）
- `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，並包含 encoder/decoder/joiner/tokens）
- `whisper-cli`（來自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或內建的 tiny 模型）
- `whisper`（Python CLI；自動下載模型）
3. **Gemini CLI**（`gemini`），使用 `read_many_files`
4. **Provider 驗證**
- `whisper`（Python CLI；會自動下載模型）
3. 使用 `read_many_files` 的 **Gemini CLI** (`gemini`)
4. **提供者身分驗證**
- 會先嘗試已設定且支援音訊的 `models.providers.*` 項目
- 內建後援順序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
- 內建備援順序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
若要停用自動偵測，請設定 `tools.media.audio.enabled: false`。
若要自訂，請設定 `tools.media.audio.models`。
注意：在 macOS/Linux/Windows 上，二進位檔偵測是盡力而為；請確認 CLI 位於 `PATH` 上（我們會展開 `~`），或設定明確的 CLI 模型並使用完整指令路徑。
注意：二進位檔偵測會盡力支援 macOS/Linux/Windows；請確認 CLI 位於 `PATH`（我們會展開 `~`），或設定含完整命令路徑的明確 CLI 模型。
## 設定範例
### Provider + CLI 後援（OpenAI + Whisper CLI）
### 提供者 + CLI 備援（OpenAI + Whisper CLI）
```json5
{
@ -70,7 +71,7 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
}
```
### 僅 Provider 且具範圍控管
### 僅使用提供者並以範圍控管
```json5
{
@ -89,7 +90,7 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
}
```
### 僅 Provider（Deepgram）
### 僅使用提供者（Deepgram）
```json5
{
@ -104,7 +105,7 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
}
```
### 僅 Provider（Mistral Voxtral）
### 僅使用提供者（Mistral Voxtral）
```json5
{
@ -119,7 +120,7 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
}
```
### 僅 Provider（SenseAudio）
### 僅使用提供者（SenseAudio）
```json5
{
@ -134,7 +135,7 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
}
```
### 將逐字稿回顯到聊天室（選擇啟用）
### 將逐字稿回傳到聊天（選擇啟用）
```json5
{
@ -153,28 +154,28 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
## 注意事項與限制
- Provider 驗證遵循標準模型驗證順序（驗證設定檔、環境變數、`models.providers.*.apiKey`）。
- 提供者身分驗證遵循標準模型驗證順序（驗證設定檔、環境變數、`models.providers.*.apiKey`）。
- Groq 設定詳細資訊：[Groq](/zh-TW/providers/groq)。
- 使用 `provider: "deepgram"` 時，Deepgram 會讀取 `DEEPGRAM_API_KEY`。
- Deepgram 設定詳細資訊：[Deepgram（音訊轉錄）](/zh-TW/providers/deepgram)。
- Mistral 設定詳細資訊：[Mistral](/zh-TW/providers/mistral)。
- 使用 `provider: "senseaudio"` 時，SenseAudio 會讀取 `SENSEAUDIO_API_KEY`。
- SenseAudio 設定詳細資訊：[SenseAudio](/zh-TW/providers/senseaudio)。
- 音訊 provider 可透過 `tools.media.audio` 覆寫 `baseUrl`、`headers` 和 `providerOptions`。
- 預設大小上限為 20MB（`tools.media.audio.maxBytes`）。超過大小的音訊會在該模型被略過，並嘗試下一個項目。
- 低於 1024 位元組的極小/空白音訊檔案，會在 provider/CLI 轉錄前被略過。
- 音訊的預設 `maxChars` **未設定**（完整逐字稿）。設定 `tools.media.audio.maxChars` 或各項目的 `maxChars` 以裁切輸出。
- 音訊提供者可以透過 `tools.media.audio` 覆寫 `baseUrl`、`headers` 和 `providerOptions`。
- 預設大小上限為 20MB（`tools.media.audio.maxBytes`）。超過大小的音訊會針對該模型略過，並嘗試下一個項目。
- 小於 1024 位元組的極小/空白音訊檔，會在提供者/CLI 轉錄前略過。
- 音訊的預設 `maxChars` **未設定**（完整逐字稿）。設定 `tools.media.audio.maxChars` 或每個項目的 `maxChars` 以修剪輸出。
- OpenAI 自動預設值為 `gpt-4o-mini-transcribe`；若要更高準確度，請設定 `model: "gpt-4o-transcribe"`。
- 使用 `tools.media.audio.attachments` 處理多個語音備忘錄（`mode: "all"` + `maxAttachments`）。
- 範本可透過 `{{Transcript}}` 使用逐字稿。
- `tools.media.audio.echoTranscript` 預設關閉；啟用後，可在代理處理前將逐字稿確認傳回原始聊天室。
- `tools.media.audio.echoFormat` 會自訂回顯文字（預留位置：`{transcript}`）。
- CLI stdout 有上限（5MB）；請保持 CLI 輸出精簡。
- CLI `args` 應使用 `{{MediaPath}}` 代表本機音訊檔案路徑。執行 `openclaw doctor --fix`，可從較舊的 `audio.transcription.command` 設定遷移已棄用的 `{input}` 預留位置。
- 使用 `tools.media.audio.attachments` 處理多個語音訊息（`mode: "all"` + `maxAttachments`）。
- 逐字稿可在範本中作為 `{{Transcript}}` 使用。
- `tools.media.audio.echoTranscript` 預設為關閉；啟用後會在代理處理前，將逐字稿確認傳回原始聊天。
- `tools.media.audio.echoFormat` 會自訂回傳文字（預留位置：`{transcript}`）。
- CLI stdout 會有上限（5MB）；請保持 CLI 輸出精簡。
- CLI `args` 應使用 `{{MediaPath}}` 作為本機音訊檔路徑。執行 `openclaw doctor --fix`，將較舊 `audio.transcription.command` 設定中已棄用的 `{input}` 預留位置遷移。
### Proxy 環境支援
以 provider 為基礎的音訊轉錄會遵循標準傳出 Proxy 環境變數：
以提供者為基礎的音訊轉錄會遵循標準輸出 Proxy 環境變數：
- `HTTPS_PROXY`
- `HTTP_PROXY`
@ -183,42 +184,42 @@ OpenClaw 會依照下列順序自動偵測，並在找到第一個可用選項
- `http_proxy`
- `all_proxy`
如果沒有設定 Proxy 環境變數，會使用直接連線。如果 Proxy 設定格式錯誤，OpenClaw 會記錄警告並退回直接擷取。
如果未設定 Proxy 環境變數，會使用直接對外連線。如果 Proxy 設定格式錯誤，OpenClaw 會記錄警告並退回直接擷取。
## 群組中的提及偵測
當群組聊天設定 `requireMention: true` 時，OpenClaw 現在會在檢查提及之前**先**轉錄音訊。這讓語音備忘錄即使包含提及也能被處理。
當群組聊天設定 `requireMention: true` 時，OpenClaw 現在會在檢查提及**之前**轉錄音訊。這讓語音訊息即使包含提及也能被處理。
**運作方式：**
1. 如果語音訊息沒有文字本文，且群組要求提及，OpenClaw 會執行「預檢」轉錄。
2. 逐字稿會檢查提及模式（例如 `@BotName`、表情符號觸發條件）。
3. 如果找到提及，訊息會進入完整回覆流程。
4. 逐字稿會用於提及偵測，因此語音備忘錄可以通過提及門檻。
1. 如果語音訊息沒有文字本文，且群組需要提及，OpenClaw 會執行「預檢」轉錄。
2. 逐字稿會檢查提及模式（例如 `@BotName`、表情符號觸發）。
3. 如果找到提及，訊息會進入完整回覆管線。
4. 逐字稿會用於提及偵測，讓語音訊息能通過提及門檻。
**後援行為：**
**備援行為：**
- 如果預檢期間轉錄失敗（逾時、API 錯誤等），訊息會根據僅文字的提及偵測來處理。
- 這確保混合訊息（文字 + 音訊）絕不會被錯誤丟棄。
- 如果預檢期間轉錄失敗（逾時、API 錯誤等），訊息會根據純文字提及偵測來處理。
- 這可確保混合訊息（文字 + 音訊）永遠不會被錯誤丟棄。
**針對每個 Telegram 群組/主題選擇退出：**
**每個 Telegram 群組/主題可選擇停用：**
- 設定 `channels.telegram.groups.<chatId>.disableAudioPreflight: true`，即可略過該群組的預檢逐字稿提及檢查。
- 設定 `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`，即可針對每個主題覆寫（`true` 代表略過，`false` 代表強制啟用）。
- 預設為 `false`（符合提及門檻條件時啟用預檢）。
- 設定 `channels.telegram.groups.<chatId>.disableAudioPreflight: true`，以略過該群組的預檢逐字稿提及檢查。
- 設定 `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight`，以針對每個主題覆寫（`true` 表示略過，`false` 表示強制啟用）。
- 預設為 `false`（符合提及門控條件時啟用預檢）。
**範例：** 使用者在設定 `requireMention: true` 的 Telegram 群組中傳送語音備忘錄，內容說「Hey @Claude, what's the weather?」。該語音備忘錄會被轉錄、偵測到提及，然後代理會回覆。
**範例：** 使用者在設定 `requireMention: true` 的 Telegram 群組中傳送語音訊息，內容是「Hey @Claude, what's the weather?」。語音訊息會被轉錄、偵測到提及，然後代理回覆。
## 注意陷阱
- 範圍規則採用第一個符合項目勝出。`chatType` 會正規化為 `direct`、`group` 或 `room`。
- 確認你的 CLI 以 0 結束並列印純文字；JSON 需要透過 `jq -r .text` 進行處理。
- 範圍規則採用第一個符合者優先。`chatType` 會標準化為 `direct`、`group` 或 `room`。
- 確認你的 CLI 以 0 結束並列印純文字；JSON 需要透過 `jq -r .text` 處理。
- 對於 `parakeet-mlx`，如果你傳入 `--output-dir`，當 `--output-format` 為 `txt`（或省略）時，OpenClaw 會讀取 `<output-dir>/<media-basename>.txt`；非 `txt` 輸出格式會退回 stdout 解析。
- 保持合理逾時（`timeoutSeconds`，預設 60 秒），避免阻塞回覆佇列。
- 保持合理的逾時設定（`timeoutSeconds`，預設 60 秒），以避免阻塞回覆佇列。
- 預檢轉錄只會處理**第一個**音訊附件以進行提及偵測。其他音訊會在主要媒體理解階段處理。
## 相關
- [媒體理解](/zh-TW/nodes/media-understanding)
- [Talk 模式](/zh-TW/nodes/talk)
- [對話模式](/zh-TW/nodes/talk)
- [語音喚醒](/zh-TW/nodes/voicewake)

743
docs/zh-TW/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

59
docs/zh-TW/providers/arcee.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 你想要搭配 OpenClaw 使用 Arcee AI
- 你需要 API 金鑰環境變數或 CLI 驗證選項
- 需要 API 金鑰環境變數或 CLI 驗證選項
summary: Arcee AI 設定（身分驗證 + 模型選擇）
title: Arcee AI
x-i18n:
generated_at: "2026-04-30T03:29:03Z"
generated_at: "2026-05-02T23:39:04Z"
model: gpt-5.5
provider: openai
source_hash: 54989e1706901fedc8a0c816ca7ee7f877fa4b973697540dd90cb9182420043f
source_hash: 622ee5288aec3ae0b45d3f06ba65fd6f972e07d7a7596ae3905d6fbdac0bf737
source_path: providers/arcee.md
workflow: 16
---
[Arcee AI](https://arcee.ai) 透過 OpenAI 相容 API 提供 Trinity 系列的 mixture-of-experts 模型存取。所有 Trinity 模型皆採 Apache 2.0 授權。
[Arcee AI](https://arcee.ai) 透過 OpenAI 相容 API 提供 Trinity 系列混合專家模型的存取。所有 Trinity 模型皆採用 Apache 2.0 授權。
Arcee AI 模型可以直接透過 Arcee 平台存取，也可以透過 [OpenRouter](/zh-TW/providers/openrouter) 存取。
Arcee AI 模型可以直接透過 Arcee 平台存取，或透過 [OpenRouter](/zh-TW/providers/openrouter) 存取。
| 屬性 | 值 |
| -------- | ------------------------------------------------------------------------------------- |
| 提供者 | `arcee` |
| 認證 | `ARCEEAI_API_KEY`（直接）或 `OPENROUTER_API_KEY`（透過 OpenRouter） |
| Provider | `arcee` |
| Auth | `ARCEEAI_API_KEY`（直接）或 `OPENROUTER_API_KEY`（透過 OpenRouter） |
| API | OpenAI 相容 |
| 基底 URL | `https://api.arcee.ai/api/v1`（直接）或 `https://openrouter.ai/api/v1`（OpenRouter） |
| 基礎 URL | `https://api.arcee.ai/api/v1`（直接）或 `https://openrouter.ai/api/v1`（OpenRouter） |
## 開始使用
@ -32,7 +32,7 @@ Arcee AI 模型可以直接透過 Arcee 平台存取，也可以透過 [OpenRout
<Step title="取得 API 金鑰">
在 [Arcee AI](https://chat.arcee.ai/) 建立 API 金鑰。
</Step>
<Step title="執行 onboarding">
<Step title="執行上線導覽">
```bash
openclaw onboard --auth-choice arceeai-api-key
```
@ -56,7 +56,7 @@ Arcee AI 模型可以直接透過 Arcee 平台存取，也可以透過 [OpenRout
<Step title="取得 API 金鑰">
在 [OpenRouter](https://openrouter.ai/keys) 建立 API 金鑰。
</Step>
<Step title="執行 onboarding">
<Step title="執行上線導覽">
```bash
openclaw onboard --auth-choice arceeai-openrouter
```
@ -72,7 +72,7 @@ Arcee AI 模型可以直接透過 Arcee 平台存取，也可以透過 [OpenRout
}
```
相同的模型 ref 可用於直接與 OpenRouter 設定（例如 `arcee/trinity-large-thinking`）。
相同的模型參照可同時用於直接與 OpenRouter 設定（例如 `arcee/trinity-large-thinking`）。
</Step>
</Steps>
@ -105,37 +105,36 @@ Arcee AI 模型可以直接透過 Arcee 平台存取，也可以透過 [OpenRout
OpenClaw 目前隨附此 Arcee 目錄：
| 模型 ref | 名稱 | 輸入 | Context | 成本（每 100 萬輸入/輸出） | 備註 |
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |
| `arcee/trinity-large-thinking` | Trinity Large Thinking | 文字 | 256K | $0.25 / $0.90 | 預設模型；已啟用推理 |
| `arcee/trinity-large-preview` | Trinity Large Preview | 文字 | 128K | $0.25 / $1.00 | 通用；400B 參數，13B active |
| `arcee/trinity-mini` | Trinity Mini 26B | 文字 | 128K | $0.045 / $0.15 | 快速且成本效益高；函式呼叫 |
| 模型參照 | 名稱 | 輸入 | 上下文 | 成本（每 100 萬輸入/輸出） | 備註 |
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ------------------------------------------ |
| `arcee/trinity-large-thinking` | Trinity Large Thinking | text | 256K | $0.25 / $0.90 | 預設模型；已啟用推理；無工具 |
| `arcee/trinity-large-preview` | Trinity Large Preview | text | 128K | $0.25 / $1.00 | 通用；400B 參數，13B 啟用 |
| `arcee/trinity-mini` | Trinity Mini 26B | text | 128K | $0.045 / $0.15 | 快速且成本效益高；函式呼叫 |
<Tip>
onboarding 預設集會將 `arcee/trinity-large-thinking` 設為預設模型。
上線導覽預設集會將 `arcee/trinity-large-thinking` 設為預設模型。它僅支援推理/文字，不支援工具使用或函式呼叫。
</Tip>
## 支援的功能
| 功能 | 支援 |
| --------------------------------------------- | ---------------------------- |
| Streaming | 是 |
| 工具使用 / 函式呼叫 | 是 |
| 結構化輸出（JSON 模式與 JSON schema） | 是 |
| Extended thinking | 是（Trinity Large Thinking） |
| 功能 | 支援 |
| --------------------------------------------- | ------------------------------------------- |
| 串流 | 是 |
| 工具使用 / 函式呼叫 | 依模型而定；Trinity Large Thinking 不支援 |
| 結構化輸出（JSON 模式和 JSON schema） | 是 |
| 延伸思考 | 是（Trinity Large Thinking） |
<AccordionGroup>
<Accordion title="環境注意事項">
如果 Gateway 以 daemon（launchd/systemd）執行，請確保 `ARCEEAI_API_KEY`
（或 `OPENROUTER_API_KEY`）可供該程序使用（例如放在
`~/.openclaw/.env`，或透過 `env.shellEnv`）。
（或 `OPENROUTER_API_KEY`）可供該程序使用（例如在
`~/.openclaw/.env` 中，或透過 `env.shellEnv`）。
</Accordion>
<Accordion title="OpenRouter 路由">
透過 OpenRouter 使用 Arcee 模型時，適用相同的 `arcee/*` 模型 ref。
OpenClaw 會根據你的認證選擇透明地處理路由。請參閱
[OpenRouter 提供者文件](/zh-TW/providers/openrouter)，了解 OpenRouter 專屬的
設定詳細資訊。
透過 OpenRouter 使用 Arcee 模型時，適用相同的 `arcee/*` 模型參照。
OpenClaw 會根據你的驗證選擇透明地處理路由。如需 OpenRouter 專屬
設定詳細資訊，請參閱 [OpenRouter provider docs](/zh-TW/providers/openrouter)。
</Accordion>
</AccordionGroup>
@ -146,6 +145,6 @@ onboarding 預設集會將 `arcee/trinity-large-thinking` 設為預設模型。
透過單一 API 金鑰存取 Arcee 模型和許多其他模型。
</Card>
<Card title="模型選擇" href="/zh-TW/concepts/model-providers" icon="layers">
選擇提供者、模型 ref 與容錯移轉行為。
選擇 providers、模型參照與容錯移轉行為。
</Card>
</CardGroup>

379
docs/zh-TW/reference/RELEASING.md
View File

@ -1,24 +1,23 @@
---
read_when:
- 正在尋找公開發布通道定義
- 尋找公開發布頻道定義
- 執行發布驗證或套件驗收
- 尋找版本命名與發布節奏
summary: 發布通道、操作者檢查清單、驗證箱、版本命名與節奏
summary: 發布通道、操作員檢查清單、驗證環境、版本命名與發布節奏
title: 發布政策
x-i18n:
generated_at: "2026-05-02T21:03:11Z"
generated_at: "2026-05-02T23:39:17Z"
model: gpt-5.5
provider: openai
source_hash: 493cb8b42f0e15f3bf5f8fb9be7d01fd626f4f16db9ac0a85e6efa747ef12d12
source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw 有四個公開發行通道：
OpenClaw 有三個公開發行通道：
- stable：預設發布到 npm `beta`，或在明確要求時發布到 npm `latest` 的標籤化發行版
- alpha：發布到 npm `alpha` 的預先發行標籤
- beta：發布到 npm `beta` 的預先發行標籤
- stable：預設發布到 npm `beta` 的標記版本，或在明確要求時發布到 npm `latest`
- beta：發布到 npm `beta` 的預發行標籤
- dev：`main` 的移動最新狀態
## 版本命名
@ -27,136 +26,115 @@ OpenClaw 有四個公開發行通道：
- Git 標籤：`vYYYY.M.D`
- 穩定版修正發行版本：`YYYY.M.D-N`
- Git 標籤：`vYYYY.M.D-N`
- Alpha 預先發行版本：`YYYY.M.D-alpha.N`
- Git 標籤：`vYYYY.M.D-alpha.N`
- Beta 預先發行版本：`YYYY.M.D-beta.N`
- Beta 預發行版本：`YYYY.M.D-beta.N`
- Git 標籤：`vYYYY.M.D-beta.N`
- 月份或日期不要補零
- `latest` 代表目前已提升的穩定版 npm 發行版
- `alpha` 代表目前的 alpha 安裝目標
- `beta` 代表目前的 beta 安裝目標
- 穩定版與穩定版修正發行預設發布到 npm `beta`；發行操作人員可以明確指定 `latest`，或稍後提升已驗證的 beta 建置
- 每個穩定版 OpenClaw 發行都會同時出貨 npm 套件與 macOS 應用程式；
beta 發行通常會先驗證並發布 npm/套件路徑，除非明確要求，否則
mac 應用程式的建置/簽署/公證保留給穩定版
- `latest` 表示目前已提升的穩定版 npm 發行版本
- `beta` 表示目前的 beta 安裝目標
- 穩定版與穩定版修正發行版本預設發布到 npm `beta`；發行操作人員可以明確指定 `latest`，或稍後提升已審核的 beta 組建
- 每個穩定版 OpenClaw 發行版本都會同時發布 npm 套件和 macOS 應用程式；
beta 發行版本通常會先驗證並發布 npm/套件路徑，而 Mac 應用程式的組建/簽署/公證則保留給穩定版，除非明確要求
## 發行節奏
- 發行採 beta 優先推進
- 穩定版只會在最新 beta 驗證完成後推出
- 維護者通常會從目前 `main` 建立的 `release/YYYY.M.D` 分支切出發行，
- 發行會先進入 beta
- 只有在最新 beta 驗證完成後才會進入穩定版
- 維護者通常會從目前 `main` 建立的 `release/YYYY.M.D` 分支切出發行版本，
讓發行驗證與修正不會阻塞 `main` 上的新開發
- 如果 beta 標籤已推送或發布且需要修正，維護者會切出下一個 `-beta.N` 標籤，而不是刪除或重新建立舊的 beta 標籤
- 詳細的發行程序、核准、憑證與復原注意事項
僅限維護者查看
- 詳細的發行程序、核准、憑證與復原注意事項僅限維護者使用
## 發行操作人員檢查清單
此檢查清單是發行流程的公開形態。私人憑證、
簽署、公證、dist-tag 復原與緊急回滾細節會留在
僅限維護者的發行執行手冊中。
此檢查清單是發行流程的公開形狀。私有憑證、簽署、公證、dist-tag 復原與緊急回復細節保留在僅限維護者使用的發行操作手冊中。
1. 從目前的 `main` 開始：拉取最新內容，確認目標提交已推送，
並確認目前 `main` CI 綠燈程度足以從它建立分支。
2. 使用 `/changelog` 從真實提交歷史重寫最上方的 `CHANGELOG.md` 區段，
保持項目面向使用者，提交、推送，並在建立分支前再次 rebase/pull。
並確認目前 `main` 的 CI 狀態足以從它建立分支。
2. 使用 `/changelog` 依據真實提交歷史重寫最上方的 `CHANGELOG.md` 區段，保持項目面向使用者，提交並推送，然後在建立分支前再 rebase/pull 一次。
3. 檢閱
`src/plugins/compat/registry.ts` 與
`src/commands/doctor/shared/deprecation-compat.ts` 中的發行相容性記錄。只有在升級路徑仍被涵蓋時才移除過期相容性，或記錄為何有意保留。
`src/plugins/compat/registry.ts` 和
`src/commands/doctor/shared/deprecation-compat.ts` 中的發行相容性記錄。只有在升級路徑仍被涵蓋時才移除已過期的相容性，否則記錄為何刻意保留。
4. 從目前的 `main` 建立 `release/YYYY.M.D`；不要直接在 `main` 上進行一般發行工作。
5. 針對預期標籤更新每個必要的版本位置，執行
`pnpm plugins:sync`，讓可發布的 Plugin 套件共享發行版本與相容性中繼資料，接著執行本機決定性預檢：
5. 為預定標籤提升所有必要版本位置，執行
`pnpm plugins:sync`，讓可發布的 Plugin 套件共用發行版本與相容性中繼資料，然後執行本機確定性預檢：
`pnpm check:test-types`、`pnpm check:architecture`、
`pnpm build && pnpm ui:build`、`pnpm plugins:sync:check`，以及
`pnpm build && pnpm ui:build`、`pnpm plugins:sync:check` 和
`pnpm release:check`。
6. 以 `preflight_only=true` 執行 `OpenClaw NPM Release`。在標籤存在前，
允許使用完整 40 字元的發行分支 SHA 進行僅限驗證的預檢。儲存成功的 `preflight_run_id`。
7. 針對發行分支、標籤或完整提交 SHA，以 `Full Release Validation` 啟動所有預發行測試。這是四個大型發行測試盒的唯一手動入口點：Vitest、Docker、QA Lab 與 Package。
8. 如果驗證失敗，請在發行分支上修正，並重新執行可證明該修正的最小失敗檔案、通道、工作流程作業、套件設定檔、提供者或模型允許清單。只有在變更範圍使先前證據失效時，才重新執行完整總控流程。
9. 對於 alpha 或 beta，標記 `vYYYY.M.D-alpha.N` 或 `vYYYY.M.D-beta.N`，然後從
相符的 `release/YYYY.M.D` 分支執行 `OpenClaw Release Publish`。它會驗證 `pnpm plugins:sync:check`，
先將所有可發布的 Plugin 套件發布到 npm，接著將同一組發布到 ClawHub，
然後使用相符的 dist-tag 提升已準備好的 OpenClaw npm 預檢成品。發布後，針對已發布的 `openclaw@YYYY.M.D-alpha.N`、`openclaw@alpha`、
`openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 套件執行發布後套件驗收。如果已推送或
已發布的預先發行需要修正，請切出下一個相符的預先發行編號；
不要刪除或重寫舊的預先發行。
10. 對於穩定版，只有在已驗證的 beta 或發行候選版具備
所需驗證證據後才繼續。穩定版 npm 發布也透過
`OpenClaw Release Publish` 進行，並透過
`preflight_run_id` 重用成功的預檢成品；穩定版 macOS 發行就緒也需要
在 `main` 上具備已封裝的 `.zip`、`.dmg`、`.dSYM.zip` 與更新後的 `appcast.xml`。
11. 發布後，執行 npm 發布後驗證器；需要發布後通道證明時，執行可選的獨立已發布 npm Telegram E2E；
在需要時進行 dist-tag 提升；從完整相符的 `CHANGELOG.md` 區段產生 GitHub 發行/預先發行說明；
並執行發行公告步驟。
6. 以 `preflight_only=true` 執行 `OpenClaw NPM Release`。在標籤存在之前，允許使用完整 40 字元的發行分支 SHA 進行僅驗證預檢。保存成功的 `preflight_run_id`。
7. 針對發行分支、標籤或完整提交 SHA，以 `Full Release Validation` 啟動所有預發行測試。這是四個大型發行測試箱的單一手動入口點：Vitest、Docker、QA Lab 和 Package。
8. 如果驗證失敗，請在發行分支上修正，並重新執行能證明修正的最小失敗檔案、通道、工作流程作業、套件設定檔、提供者或模型允許清單。只有在變更範圍使先前證據過期時，才重新執行完整總括流程。
9. 對於 beta，標記 `vYYYY.M.D-beta.N`，然後從相符的 `release/YYYY.M.D` 分支執行 `OpenClaw Release Publish`。它會驗證 `pnpm plugins:sync:check`，先將所有可發布的 Plugin 套件發布到 npm，再將相同集合發布到 ClawHub，然後使用相符的 dist-tag 提升已準備好的 OpenClaw npm 預檢成品。發布後，針對已發布的 `openclaw@YYYY.M.D-beta.N` 或 `openclaw@beta` 套件執行發布後套件接受測試。如果已推送或已發布的預發行版本需要修正，請切出下一個相符的預發行編號；不要刪除或重寫舊的預發行版本。
10. 對於穩定版，只有在已審核的 beta 或發行候選版本具備必要驗證證據後才繼續。穩定版 npm 發布也會透過
`OpenClaw Release Publish`，使用 `preflight_run_id` 重用成功的預檢成品；穩定版 macOS 發行就緒狀態也需要 `main` 上的已封裝 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的 `appcast.xml`。
11. 發布後，執行 npm 發布後驗證器、在需要發布後通道證明時執行選用的獨立已發布 npm Telegram E2E、在需要時進行 dist-tag 提升、依據完整相符的 `CHANGELOG.md` 區段撰寫 GitHub 發行/預發行說明，以及完成發行公告步驟。
## 發行預檢
- 在發布預檢前執行 `pnpm check:test-types`，讓測試 TypeScript 在較快的本機 `pnpm check` 閘門之外也保持涵蓋
- 在發布預檢前執行 `pnpm check:architecture`，讓更廣泛的匯入循環與架構邊界檢查在較快的本機閘門之外也保持通過
- 在 `pnpm release:check` 前執行 `pnpm build && pnpm ui:build`，讓預期的 `dist/*` 發布成品與 Control UI bundle 存在，以供封裝驗證步驟使用
- 在根版本號提升後、打標籤前執行 `pnpm plugins:sync`。它會更新可發布的 Plugin 套件版本、OpenClaw peer/API 相容性中繼資料、建置中繼資料，以及 Plugin 變更記錄 stub，以符合核心發布版本。`pnpm plugins:sync:check` 是非變更式發布防護；如果忘記此步驟，發布工作流程會在任何 registry 變更前失敗。
- 在發布核准前執行手動 `Full Release Validation` 工作流程，從單一進入點啟動所有預發布測試盒。它接受分支、標籤或完整提交 SHA，分派手動 `CI`，並分派 `OpenClaw Release Checks`，涵蓋安裝煙霧測試、套件接受度、Docker 發布路徑套件、live/E2E、OpenWebUI、QA Lab parity、Matrix，以及 Telegram lanes。使用 `release_profile=full` 和 `rerun_group=all` 時，它也會針對 release checks 產生的 `release-package-under-test` artifact 執行套件 Telegram E2E。發布後若同一個 Telegram E2E 也應證明已發布的 npm 套件，請提供 `npm_telegram_package_spec`。發布後若 Package Acceptance 應針對已出貨的 npm 套件，而不是 SHA 建置 artifact，執行其套件/更新矩陣，請提供 `package_acceptance_package_spec`。當私有證據報告應證明驗證符合已發布的 npm 套件，但不強制執行 Telegram E2E 時，請提供 `evidence_package_spec`。範例：
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 當你想在發布工作持續進行時，為套件候選版本取得旁路證明，請執行手動 `Package Acceptance` 工作流程。對 `openclaw@alpha`、`openclaw@beta`、`openclaw@latest` 或精確發布版本使用 `source=npm`；使用 `source=ref` 以目前的 `workflow_ref` harness 封裝受信任的 `package_ref` 分支/標籤/SHA；使用 `source=url` 指向需要 SHA-256 的 HTTPS tarball；或使用 `source=artifact` 指向另一個 GitHub Actions run 上傳的 tarball。此工作流程會將候選版本解析為 `package-under-test`，針對該 tarball 重用 Docker E2E 發布排程器，並可用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 針對同一 tarball 執行 Telegram QA。當所選 Docker lanes 包含 `published-upgrade-survivor` 時，套件 artifact 就是候選版本，而 `published_upgrade_survivor_baseline` 會選取已發布的基準版本。
- 在發行預檢前執行 `pnpm check:test-types`，讓測試 TypeScript 在較快的本機 `pnpm check` 關卡之外仍受到涵蓋
- 在發行預檢前執行 `pnpm check:architecture`，讓更廣泛的匯入循環與架構邊界檢查在較快的本機關卡之外保持綠燈
- 在 `pnpm release:check` 前執行 `pnpm build && pnpm ui:build`，讓預期的 `dist/*` 發行成品與 Control UI bundle 存在，以供打包驗證步驟使用
- 在根版本升級之後、標記之前執行 `pnpm plugins:sync`。它會更新可發布的 plugin 套件版本、OpenClaw 對等/API 相容性中繼資料、建置中繼資料，以及 plugin changelog stub，使其符合核心發行版本。`pnpm plugins:sync:check` 是不會變更內容的發行防護；如果忘記此步驟，發布工作流程會在任何 registry 變更前失敗。
- 在發行核准前執行手動 `Full Release Validation` 工作流程，從單一入口點啟動所有發行前測試箱。它接受分支、標籤或完整 commit SHA，派發手動 `CI`，並派發 `OpenClaw Release Checks`，涵蓋安裝 smoke、套件驗收、Docker 發行路徑套件、live/E2E、OpenWebUI、QA Lab parity、Matrix 與 Telegram 線路。使用 `release_profile=full` 與 `rerun_group=all` 時，它也會針對 release checks 產生的 `release-package-under-test` 成品執行套件 Telegram E2E。發布後，如果同一個 Telegram E2E 也應驗證已發布的 npm 套件，請提供 `npm_telegram_package_spec`。發布後，如果 Package Acceptance 應針對已出貨的 npm 套件，而不是 SHA 建置成品執行其套件/更新矩陣，請提供 `package_acceptance_package_spec`。如果私有證據報告應證明驗證符合已發布的 npm 套件，但不強制執行 Telegram E2E，請提供 `evidence_package_spec`。範例：`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 當你希望在發行工作持續進行時，為套件候選版本取得旁路證明，請執行手動 `Package Acceptance` 工作流程。使用 `source=npm` 來指定 `openclaw@beta`、`openclaw@latest` 或精確的發行版本；使用 `source=ref` 以目前的 `workflow_ref` harness 打包受信任的 `package_ref` 分支/標籤/SHA；使用 `source=url` 來指定需要 SHA-256 的 HTTPS tarball；或使用 `source=artifact` 來指定另一個 GitHub Actions 執行上傳的 tarball。該工作流程會將候選版本解析為 `package-under-test`，針對該 tarball 重用 Docker E2E 發行排程器，並可使用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 對同一個 tarball 執行 Telegram QA。當選取的 Docker 線路包含 `published-upgrade-survivor` 時，套件成品就是候選版本，而 `published_upgrade_survivor_baseline` 會選取已發布的基準版本。
範例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
常用 profile：
- `smoke`：安裝/channel/agent、Gateway 網路，以及設定重新載入 lanes
- `package`：artifact 原生套件/更新/Plugin lanes，不含 OpenWebUI 或 live ClawHub
- `product`：package profile 加上 MCP channels、cron/subagent 清理、OpenAI 網頁搜尋，以及 OpenWebUI
- `full`：含 OpenWebUI 的 Docker 發布路徑區塊
- `custom`：用於聚焦重跑的精確 `docker_lanes` 選擇
- 當你只需要發布候選版本的完整一般 CI 涵蓋範圍時，直接執行手動 `CI` 工作流程。手動 CI 分派會略過 changed scoping，並強制執行 Linux Node shards、內建 Plugin shards、channel contracts、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python skills、Windows、macOS、Android，以及 Control UI i18n lanes。
常見設定檔：
- `smoke`：安裝/頻道/代理、Gateway 網路，以及設定重新載入線路
- `package`：不含 OpenWebUI 或 live ClawHub 的成品原生套件/更新/plugin 線路
- `product`：套件設定檔加上 MCP 頻道、cron/subagent 清理、OpenAI 網頁搜尋與 OpenWebUI
- `full`：含 OpenWebUI 的 Docker 發行路徑區塊
- `custom`：用於聚焦重跑的精確 `docker_lanes` 選取
- 當你只需要發行候選版本的完整正常 CI 覆蓋時，請直接執行手動 `CI` 工作流程。手動 CI 派發會略過變更範圍判定，並強制執行 Linux Node shards、bundled-plugin shards、頻道合約、Node 22 相容性、`check`、`check-additional`、建置 smoke、文件檢查、Python skills、Windows、macOS、Android 與 Control UI i18n 線路。
範例：`gh workflow run ci.yml --ref release/YYYY.M.D`
- 驗證發布遙測時執行 `pnpm qa:otel:smoke`。它會透過本機 OTLP/HTTP receiver 執行 QA-lab，並驗證匯出的 trace span 名稱、有界屬性，以及內容/識別碼遮蔽，不需要 Opik、Langfuse 或其他外部 collector。
- 每次標記發布前執行 `pnpm release:check`
- 在標籤存在後，執行 `OpenClaw Release Publish` 進行會造成變更的發布序列。從 `release/YYYY.M.D` 分派它（或在發布 main 可達標籤時從 `main` 分派），傳入發布標籤與成功的 OpenClaw npm `preflight_run_id`，並保留預設 Plugin 發布範圍 `all-publishable`，除非你刻意執行聚焦修復。此工作流程會序列化 Plugin npm 發布、Plugin ClawHub 發布，以及 OpenClaw npm 發布，避免核心套件早於其外部化 Plugin 發布。
- 發布檢查現在會在獨立的手動工作流程中執行：
- 驗證發行遙測時執行 `pnpm qa:otel:smoke`。它會透過本機 OTLP/HTTP 接收器演練 QA-lab，並驗證匯出的 trace span 名稱、有界屬性，以及內容/識別碼遮蔽，而不需要 Opik、Langfuse 或其他外部收集器。
- 每個加上標籤的發行前都執行 `pnpm release:check`
- 在標籤存在後，執行 `OpenClaw Release Publish` 以進行會變更狀態的發布序列。從 `release/YYYY.M.D` 派發它（或在發布 main 可到達的標籤時從 `main` 派發），傳入發行標籤與成功的 OpenClaw npm `preflight_run_id`，並保留預設的 plugin 發布範圍 `all-publishable`，除非你刻意執行聚焦修復。該工作流程會序列化 plugin npm 發布、plugin ClawHub 發布與 OpenClaw npm 發布，確保核心套件不會早於其外部化 plugins 發布。
- 發行檢查現在在獨立的手動工作流程中執行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 也會在發布核准前執行 QA Lab mock parity lane、快速 live Matrix profile，以及 Telegram QA lane。live lanes 使用 `qa-live-shared` 環境；Telegram 也使用 Convex CI credential leases。當你想平行取得完整 Matrix transport、media 與 E2EE inventory 時，請使用 `matrix_profile=all` 和 `matrix_shards=true` 執行手動 `QA-Lab - All Lanes` 工作流程。
- 跨 OS 安裝與升級 runtime 驗證是公開 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，兩者會直接呼叫可重用工作流程 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 此拆分是刻意設計：保持真正的 npm 發布路徑短小、確定且聚焦於 artifact，而較慢的 live 檢查留在自己的 lane 中，避免拖慢或阻擋發布
- 帶有 secret 的發布檢查應透過 `Full Release Validation` 分派，或從 `main`/release 工作流程 ref 分派，讓工作流程邏輯與 secrets 維持受控
- `OpenClaw Release Checks` 接受分支、標籤或完整提交 SHA，只要解析出的提交可從 OpenClaw 分支或發布標籤到達
- `OpenClaw NPM Release` 僅驗證預檢也接受目前完整 40 字元的工作流程分支提交 SHA，不需要已推送的標籤
- 該 SHA 路徑僅供驗證，不能升級為真正發布
- 在 SHA 模式中，工作流程只會為套件中繼資料檢查合成 `v<package.json version>`；真正發布仍需要真正的發布標籤
- 兩個工作流程都把真正發布與 promotion 路徑保留在 GitHub-hosted runners 上，而非變更式驗證路徑可使用較大的 Blacksmith Linux runners
- 該工作流程會使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`，並同時使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流程 secrets
- npm 發布預檢不再等待獨立的 release checks lane
- `OpenClaw Release Checks` 也會在發行核准前執行 QA Lab mock parity 線路、快速 live Matrix 設定檔，以及 Telegram QA 線路。live 線路使用 `qa-live-shared` 環境；Telegram 也會使用 Convex CI 憑證租約。當你希望平行取得完整 Matrix 傳輸、媒體與 E2EE inventory 時，請使用 `matrix_profile=all` 與 `matrix_shards=true` 執行手動 `QA-Lab - All Lanes` 工作流程。
- 跨作業系統安裝與升級執行階段驗證是公開 `OpenClaw Release Checks` 與 `Full Release Validation` 的一部分，它們會直接呼叫可重用工作流程 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 這種拆分是刻意的：讓真正的 npm 發行路徑保持短、確定且專注於成品，而較慢的 live 檢查留在自己的線路中，避免拖慢或阻擋發布
- 帶有密鑰的發行檢查應透過 `Full Release Validation` 派發，或從 `main`/發行工作流程 ref 派發，讓工作流程邏輯與 secrets 保持受控
- `OpenClaw Release Checks` 接受分支、標籤或完整 commit SHA，只要解析出的 commit 可從 OpenClaw 分支或發行標籤到達
- `OpenClaw NPM Release` 僅驗證預檢也接受目前完整 40 字元的工作流程分支 commit SHA，不需要已推送的標籤
- 該 SHA 路徑僅供驗證，不能提升為真正的發布
- 在 SHA 模式中，工作流程只會為套件中繼資料檢查合成 `v<package.json version>`；真正發布仍需要真正的發行標籤
- 兩個工作流程都將真正的發布與提升路徑保留在 GitHub 託管 runner 上，而不會變更狀態的驗證路徑可使用較大的 Blacksmith Linux runner
- 該工作流程會使用 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`，並同時使用 `OPENAI_API_KEY` 與 `ANTHROPIC_API_KEY` 工作流程 secrets
- npm 發行預檢不再等待獨立的發行檢查線路
- 在核准前執行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或相符的 beta/correction 標籤）
- npm 發布後，執行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或相符的 beta/correction 版本），在全新的暫存 prefix 中驗證已發布 registry 安裝路徑
- beta 發布後，執行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共用租用 Telegram credential pool，針對已發布的 npm 套件驗證已安裝套件的 onboarding、Telegram 設定，以及真實 Telegram E2E。本機 maintainer 一次性執行可省略 Convex vars，並直接傳入三個 `OPENCLAW_QA_TELEGRAM_*` env credentials。
- Maintainer 可透過手動 `NPM Telegram Beta E2E` 工作流程，從 GitHub Actions 執行同一個發布後檢查。它刻意僅限手動執行，不會在每次 merge 時執行。
- Maintainer 發布自動化現在使用先預檢後 promotion：
- npm 發布後，執行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或相符的 beta/correction 版本），以在全新的暫存 prefix 中驗證已發布 registry 的安裝路徑
- beta 發布後，執行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享的租用 Telegram 憑證池，針對已發布的 npm 套件驗證已安裝套件 onboarding、Telegram 設定，以及真正的 Telegram E2E。本機 maintainer 的一次性執行可以省略 Convex 變數，並直接傳入三個 `OPENCLAW_QA_TELEGRAM_*` env 憑證。
- Maintainer 可以透過手動 `NPM Telegram Beta E2E` 工作流程，從 GitHub Actions 執行相同的發布後檢查。它刻意只支援手動執行，不會在每次 merge 時執行。
- Maintainer 發行自動化現在使用先預檢再提升：
- 真正的 npm 發布必須通過成功的 npm `preflight_run_id`
- 真正的 npm 發布必須從與成功預檢 run 相同的 `main` 或 `release/YYYY.M.D` 分支分派
- stable npm 發布預設為 `beta`
- stable npm 發布可透過工作流程輸入明確指定 `latest`
- 基於 token 的 npm dist-tag 變更現在位於 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，原因是 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公開 repo 保持 OIDC-only 發布
- 公開 `macOS Release` 僅供驗證；當標籤只存在於 release 分支，但工作流程從 `main` 分派時，請設定 `public_release_branch=release/YYYY.M.D`
- 真正的私有 mac 發布必須通過成功的私有 mac `preflight_run_id` 和 `validate_run_id`
- 真正的發布路徑會 promotion 已準備好的 artifact，而不是再次重新建置它們
- 對於像 `YYYY.M.D-N` 這樣的 stable correction 發布，發布後 verifier 也會檢查從 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同暫存 prefix 升級路徑，讓發布 correction 無法悄悄讓較舊的全域安裝停留在基礎 stable payload
- npm 發布預檢會 fail closed，除非 tarball 同時包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，這樣我們才不會再次出貨空的瀏覽器 dashboard
- 發布後驗證也會檢查已發布的 Plugin entrypoints 和套件中繼資料是否存在於已安裝的 registry 版面中。若某次發布缺少 Plugin runtime payload，postpublish verifier 會失敗，且不能 promotion 到 `latest`。
- `pnpm test:install:smoke` 也會對候選更新 tarball 強制執行 npm pack `unpackedSize` 預算，因此 installer e2e 能在發布 publish 路徑前捕捉意外的 pack 膨脹
- 如果發布工作觸及 CI 規劃、擴充功能 timing manifests，或擴充功能測試矩陣，請在核准前重新產生並檢閱 planner 擁有的 `plugin-prerelease-extension-shard` 矩陣輸出，來源為 `.github/workflows/plugin-prerelease.yml`，讓發布說明不會描述過期的 CI 版面
- Stable macOS 發布準備度也包含 updater surfaces：
- GitHub release 最終必須包含已封裝的 `.zip`、`.dmg` 和 `.dSYM.zip`
- `main` 上的 `appcast.xml` 必須在發布後指向新的 stable zip
- 已封裝 app 必須保持非 debug bundle id、非空 Sparkle feed URL，以及高於或等於該發布版本 canonical Sparkle build floor 的 `CFBundleVersion`
- 真正的 npm 發布必須從成功預檢執行所在的同一個 `main` 或 `release/YYYY.M.D` 分支派發
- 穩定版 npm 發行預設為 `beta`
- 穩定版 npm 發布可透過工作流程輸入明確指定 `latest`
- 基於 token 的 npm dist-tag 變更現在位於 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 以確保安全，因為 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公開 repo 保持僅 OIDC 發布
- 公開 `macOS Release` 僅供驗證；當標籤只存在於發行分支，但工作流程從 `main` 派發時，請設定 `public_release_branch=release/YYYY.M.D`
- 真正的私有 mac 發布必須通過成功的私有 mac `preflight_run_id` 與 `validate_run_id`
- 真正的發布路徑會提升已準備好的成品，而不是再次重建它們
- 對於像 `YYYY.M.D-N` 這樣的穩定版修正版發行，發布後驗證器也會檢查相同暫存 prefix 中從 `YYYY.M.D` 到 `YYYY.M.D-N` 的升級路徑，確保發行修正版不會悄悄讓較舊的全域安裝停留在基礎穩定版 payload 上
- npm 發行預檢會 fail closed，除非 tarball 同時包含 `dist/control-ui/index.html` 與非空的 `dist/control-ui/assets/` payload，避免我們再次出貨空的瀏覽器儀表板
- 發布後驗證也會檢查已發布 plugin 進入點與套件中繼資料是否存在於已安裝的 registry 版面中。若發行版本缺少 plugin 執行階段 payload，發布後驗證器會失敗，且不能提升為 `latest`。
- `pnpm test:install:smoke` 也會針對候選更新 tarball 強制執行 npm pack `unpackedSize` 預算，因此 installer e2e 會在發行發布路徑前抓出意外的 pack 膨脹
- 如果發行工作觸及 CI 規劃、extension timing manifests 或 extension test matrices，請在核准前重新產生並審查由 planner 擁有的 `plugin-prerelease-extension-shard` 矩陣輸出，來源為 `.github/workflows/plugin-prerelease.yml`，以免發行說明描述過時的 CI 版面
- 穩定版 macOS 發行準備狀態也包含 updater surfaces：
- GitHub release 最終必須包含打包好的 `.zip`、`.dmg` 與 `.dSYM.zip`
- 發布後，`main` 上的 `appcast.xml` 必須指向新的穩定版 zip
- 打包後的 app 必須保留非 debug bundle id、非空的 Sparkle feed URL，以及等於或高於該發行版本 canonical Sparkle build floor 的 `CFBundleVersion`
## 發布測試盒
## 發行測試箱
`Full Release Validation` 是 operator 從單一進入點啟動所有預發布測試的方式。若要在快速變動分支上取得 pinned commit 證明，請使用 helper，讓每個 child workflow 都從固定在目標 SHA 的暫存分支執行：
`Full Release Validation` 是 operators 從單一入口點啟動所有發行前測試的方式。若要在快速變動分支上取得 pinned commit 證明，請使用 helper，讓每個子工作流程都從固定在目標 SHA 的暫存分支執行：
```bash
pnpm ci:full-release --sha <full-sha>
```
helper 會推送 `release-ci/<sha>-...`，從該分支分派 `Full Release Validation` 並帶入 `ref=<sha>`，驗證每個 child workflow 的 `headSha` 都符合目標，然後刪除暫存分支。這能避免意外證明了較新的 `main` child run。
該 helper 會推送 `release-ci/<sha>-...`，從該分支派發 `Full Release Validation` 並帶入 `ref=<sha>`，驗證每個子工作流程的 `headSha` 都符合目標，然後刪除暫存分支。這可避免意外證明較新的 `main` 子執行。
若要驗證 release 分支或標籤，請從受信任的 `main` 工作流程 ref 執行，並將 release 分支或標籤作為 `ref` 傳入：
若要驗證發行分支或標籤，請從受信任的 `main` 工作流程 ref 執行，並將發行分支或標籤作為 `ref` 傳入：
```bash
gh workflow run full-release-validation.yml \
@ -168,21 +146,21 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
工作流程會解析目標 ref，使用 `target_ref=<release-ref>` 派送手動 `CI`，派送 `OpenClaw Release Checks`，並在 `release_profile=full` 且 `rerun_group=all` 時，或設定 `npm_telegram_package_spec` 時，派送獨立的套件 Telegram E2E。`OpenClaw Release Checks` 接著會展開安裝冒煙測試、跨 OS 發行檢查、live/E2E Docker 發行路徑涵蓋、包含 Telegram 套件 QA 的 Package Acceptance、QA Lab parity、live Matrix，以及 live Telegram。只有當 `Full Release Validation` 摘要顯示 `normal_ci` 和 `release_checks` 成功時，完整執行才可接受。在 full/all 模式中，`npm_telegram` 子項也必須成功；在 full/all 以外則會略過，除非已提供已發布的 `npm_telegram_package_spec`。最終驗證器摘要會包含每個子執行的最慢工作表，因此發行管理員無需下載記錄也能看到目前的關鍵路徑。
請參閱 [完整發行驗證](/zh-TW/reference/full-release-validation)，了解完整階段矩陣、精確的工作流程工作名稱、stable 與 full 設定檔差異、成品，以及聚焦重新執行控制項。
子工作流程會從執行 `Full Release Validation` 的受信任 ref 派送，通常是 `--ref main`，即使目標 `ref` 指向較舊的發行分支或標籤也一樣。沒有獨立的 Full Release Validation workflow-ref 輸入；請透過選擇工作流程執行 ref 來選擇受信任的測試框架。
不要在移動中的 `main` 上使用 `--ref main -f ref=<sha>` 作為精確提交證明；原始提交 SHA 無法作為工作流程派送 ref，因此請使用 `pnpm ci:full-release --sha <sha>` 建立釘選的暫時分支。
工作流程會解析目標參照，使用 `target_ref=<release-ref>` 觸發手動 `CI`，觸發 `OpenClaw Release Checks`，並在 `release_profile=full` 搭配 `rerun_group=all` 時，或設定 `npm_telegram_package_spec` 時，觸發獨立套件 Telegram E2E。`OpenClaw Release Checks` 接著會展開執行安裝煙霧測試、跨 OS 發布檢查、即時/E2E Docker 發布路徑涵蓋、含 Telegram 套件 QA 的 Package Acceptance、QA Lab 對等性、即時 Matrix，以及即時 Telegram。只有當 `Full Release Validation` 摘要顯示 `normal_ci` 和 `release_checks` 成功時，完整執行才可接受。在 full/all 模式中，`npm_telegram` 子項也必須成功；在 full/all 以外會略過，除非提供了已發布的 `npm_telegram_package_spec`。最終驗證器摘要包含每個子執行的最慢作業表，因此發布管理者無需下載日誌即可查看目前的關鍵路徑。
請參閱 [完整版本驗證](/zh-TW/reference/full-release-validation)，了解完整階段矩陣、確切工作流程作業名稱、stable 與 full 設定檔差異、成品，以及聚焦重跑控制項。
子工作流程會從執行 `Full Release Validation` 的受信任參照觸發，通常是 `--ref main`，即使目標 `ref` 指向較舊的發布分支或標籤也是如此。沒有獨立的 Full Release Validation 工作流程參照輸入；請透過選擇工作流程執行參照來選擇受信任的執行框架。
不要在移動中的 `main` 上使用 `--ref main -f ref=<sha>` 取得確切提交證明；原始提交 SHA 不能作為工作流程觸發參照，因此請使用 `pnpm ci:full-release --sha <sha>` 建立釘選的暫時分支。
使用 `release_profile` 選擇 live/provider 涵蓋範圍：
使用 `release_profile` 選擇即時/提供者涵蓋範圍：
- `minimum`：最快的發行關鍵 OpenAI/核心 live 與 Docker 路徑
- `stable`：minimum 加上用於發行核准的穩定 provider/backend 涵蓋
- `full`：stable 加上廣泛的 advisory provider/media 涵蓋
- `minimum`: 最快的發布關鍵 OpenAI/核心即時測試與 Docker 路徑
- `stable`: 最低範圍加上發布核准所需的穩定提供者/後端涵蓋範圍
- `full`: 穩定範圍加上廣泛的參考性提供者/媒體涵蓋範圍
`OpenClaw Release Checks` 會使用受信任的工作流程 ref，將目標 ref 解析一次為 `release-package-under-test`，並在發行路徑 Docker 檢查與 Package Acceptance 中重用該成品。這能讓所有面向套件的機器使用相同位元組，並避免重複建置套件。
當 repo/org 變數已設定時，跨 OS OpenAI 安裝冒煙測試會使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因為此 lane 是在證明套件安裝、onboarding、Gateway 啟動，以及一輪 live agent，而不是對最慢的預設模型進行基準測試。更廣泛的 live provider 矩陣仍然是模型特定涵蓋的所在。
`OpenClaw Release Checks` 會使用受信任工作流程參照，將目標參照解析一次為 `release-package-under-test`，並在發布路徑 Docker 檢查和 Package Acceptance 中重用該成品。這會讓所有面向套件的測試箱都使用相同位元組內容，並避免重複建置套件。
跨 OS OpenAI 安裝煙霧測試會在設定儲存庫/組織變數時使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否則使用 `openai/gpt-5.4`，因為這條測試線是在證明套件安裝、初始設定、Gateway 啟動，以及一次即時代理程式回合，而不是對最慢的預設模型進行基準測試。較廣的即時提供者矩陣仍是特定模型涵蓋範圍的位置。
依發行階段使用這些變體：
請依發布階段使用這些變體：
```bash
# Validate an unpublished release candidate branch.
@ -212,24 +190,23 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
不要在聚焦修正後的第一次重新執行時使用完整 umbrella。如果某一台機器失敗，請使用失敗的子工作流程、工作、Docker lane、套件設定檔、模型 provider，或 QA lane 作為下一個證明。只有在修正變更了共享發行編排，或使先前所有機器的證據過時時，才再次執行完整 umbrella。umbrella 的最終驗證器會重新檢查已記錄的子工作流程執行 ID，因此在子工作流程成功重新執行後，只要重新執行失敗的 `Verify full validation` 父工作即可。
不要把完整總括流程當成聚焦修正後的第一次重跑。如果某個測試箱失敗，請使用失敗的子工作流程、作業、Docker 測試線、套件設定檔、模型提供者，或 QA 測試線進行下一次證明。只有在修正變更了共用發布編排，或讓先前所有測試箱的證據失效時，才再次執行完整總括流程。總括流程的最終驗證器會重新檢查已記錄的子工作流程執行 ID，因此在子工作流程成功重跑後，只需重跑失敗的 `Verify full validation` 父作業。
若要進行有界復原，請將 `rerun_group` 傳給 umbrella。`all` 是真正的發行候選執行，`ci` 只執行一般 CI 子項，`plugin-prerelease` 只執行僅限發行的 Plugin 子項，`release-checks` 執行每個發行機器，而較窄的發行群組是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。
聚焦的 `npm-telegram` 重新執行需要 `npm_telegram_package_spec`；使用 `release_profile=full` 的 full/all 執行會使用 release-checks 套件成品。
若要進行有界復原，請將 `rerun_group` 傳給總括流程。`all` 是真正的發布候選版本執行，`ci` 只執行一般 CI 子項，`plugin-prerelease` 只執行僅發布用 Plugin 子項，`release-checks` 會執行每個發布測試箱，而較窄的發布群組是 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live` 和 `npm-telegram`。
聚焦的 `npm-telegram` 重跑需要 `npm_telegram_package_spec`；使用 `release_profile=full` 的 full/all 執行會使用發布檢查套件成品。
### Vitest
Vitest 機器是手動 `CI` 子工作流程。手動 CI 會刻意略過變更範圍判定，並強制對發行候選執行一般測試圖：Linux Node shards、bundled-Plugin shards、channel contracts、Node 22 相容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android，以及 Control UI i18n。
Vitest 測試箱是手動 `CI` 子工作流程。手動 CI 會刻意略過變更範圍限定，並強制發布候選版本使用一般測試圖：Linux Node 分片、隨附 Plugin 分片、通道合約、Node 22 相容性、`check`、`check-additional`、建置煙霧測試、文件檢查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。
使用這台機器回答「原始碼樹是否通過完整的一般測試套件？」
它不等同於發行路徑產品驗證。要保留的證據：
使用這個測試箱回答「原始碼樹是否通過完整的一般測試套件？」它不同於發布路徑產品驗證。請保留的證據：
- 顯示已派送 `CI` 執行 URL 的 `Full Release Validation` 摘要
- `CI` 執行在精確目標 SHA 上為綠色
- 調查迴歸時，來自 CI 工作的失敗或緩慢 shard 名稱
- 當執行需要效能分析時，Vitest 計時成品，例如 `.artifacts/vitest-shard-timings.json`
- `Full Release Validation` 摘要，顯示已觸發的 `CI` 執行 URL
- `CI` 在確切目標 SHA 上通過
- 調查迴歸時 CI 作業中的失敗或緩慢分片名稱
- 當執行需要效能分析時的 Vitest 計時成品，例如 `.artifacts/vitest-shard-timings.json`
只有當發行需要確定性的一般 CI，但不需要 Docker、QA Lab、live、跨 OS 或套件機器時，才直接執行手動 CI：
只有當發布需要確定性的一般 CI，但不需要 Docker、QA Lab、即時、跨 OS 或套件測試箱時，才直接執行手動 CI：
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -237,53 +214,52 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker 機器位於 `OpenClaw Release Checks` 中，透過 `openclaw-live-and-e2e-checks-reusable.yml`，以及發行模式的 `install-smoke` 工作流程。它會透過封裝的 Docker 環境驗證發行候選，而不只是原始碼層級測試。
Docker 測試箱位於 `OpenClaw Release Checks` 中，透過 `openclaw-live-and-e2e-checks-reusable.yml` 以及發布模式 `install-smoke` 工作流程執行。它會透過封裝的 Docker 環境驗證發布候選版本，而不只是原始碼層級測試。
發行 Docker 涵蓋包括：
發布 Docker 涵蓋範圍包括：
- 啟用緩慢 Bun 全域安裝冒煙測試的完整安裝冒煙測試
- 依目標 SHA 準備/重用根 Dockerfile 冒煙映像，並將 QR、root/gateway，以及 installer/Bun 冒煙工作作為獨立 install-smoke shards 執行
- repository E2E lanes
- 發行路徑 Docker 區塊：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`，以及 `plugins-runtime-install-h`
- 要求時，`plugins-runtime-services` 區塊內的 OpenWebUI 涵蓋
- 拆分的 bundled Plugin 安裝/解除安裝 lanes，從 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23`
- 當發行檢查包含 live suites 時，live/E2E provider suites 與 Docker live model 涵蓋
- 啟用緩慢 Bun 全域安裝煙霧測試的完整安裝煙霧測試
- 依目標 SHA 準備/重用根 Dockerfile 煙霧測試映像，QR、根/Gateway，以及安裝器/Bun 煙霧測試作業會作為獨立 install-smoke 分片執行
- 儲存庫 E2E 測試線
- 發布路徑 Docker 區塊：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`，以及 `plugins-runtime-install-h`
- 要求時，在 `plugins-runtime-services` 區塊內的 OpenWebUI 涵蓋範圍
- 拆分的隨附 Plugin 安裝/解除安裝測試線 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23`
- 當發布檢查包含即時測試套件時，涵蓋即時/E2E 提供者套件與 Docker 即時模型
重新執行前先使用 Docker 成品。發行路徑排程器會上傳 `.artifacts/docker-tests/`，其中包含 lane 記錄、`summary.json`、`failures.json`、階段計時、排程器計畫 JSON，以及重新執行命令。若要進行聚焦復原，請在可重用 live/E2E 工作流程上使用 `docker_lanes=<lane[,lane]>`，而不是重新執行所有發行區塊。產生的重新執行命令會在可用時包含先前的 `package_artifact_run_id` 和已準備的 Docker 映像輸入，因此失敗的 lane 可以重用相同的 tarball 和 GHCR 映像。
重新執行前先使用 Docker 成品。發布路徑排程器會上傳 `.artifacts/docker-tests/`，其中包含測試線日誌、`summary.json`、`failures.json`、階段計時、排程器計畫 JSON，以及重跑命令。若要進行聚焦復原，請在可重用的即時/E2E 工作流程上使用 `docker_lanes=<lane[,lane]>`，而不是重跑所有發布區塊。產生的重跑命令會在可用時包含先前的 `package_artifact_run_id` 和已準備的 Docker 映像輸入，因此失敗的測試線可以重用相同的 tar 封裝檔和 GHCR 映像。
### QA Lab
QA Lab 機器也是 `OpenClaw Release Checks` 的一部分。它是 agentic 行為與 channel 層級的發行門檻，獨立於 Vitest 與 Docker 套件機制。
QA Lab 測試箱也是 `OpenClaw Release Checks` 的一部分。它是代理式行為和通道層級的發布門檻，與 Vitest 和 Docker 套件機制分開。
發行 QA Lab 涵蓋包括：
發布 QA Lab 涵蓋範圍包括：
- 使用 agentic parity pack，將 OpenAI 候選 lane 與 Opus 4.6 baseline 比較的 mock parity lane
- 使用 `qa-live-shared` 環境的快速 live Matrix QA 設定檔
- 使用 Convex CI 認證租約的 live Telegram QA lane
- 當發行 telemetry 需要明確本機證明時的 `pnpm qa:otel:smoke`
- 使用代理式對等性包，將 OpenAI 候選測試線與 Opus 4.6 基準比較的模擬對等性測試線
- 使用 `qa-live-shared` 環境的快速即時 Matrix QA 設定檔
- 使用 Convex CI 憑證租約的 Telegram 即時 QA 測試線
- 當發布遙測需要明確本機證明時執行 `pnpm qa:otel:smoke`
使用這台機器回答「發行在 QA 情境與 live channel flows 中是否正確運作？」
核准發行時，請保留 parity、Matrix 和 Telegram lanes 的成品 URL。完整 Matrix 涵蓋仍可作為手動分片 QA-Lab 執行使用，而不是預設的發行關鍵 lane。
使用這個測試箱回答「發布版本在 QA 情境和即時通道流程中的行為是否正確？」核准發布時，請保留對等性、Matrix 和 Telegram 測試線的成品 URL。完整 Matrix 涵蓋範圍仍可作為手動分片 QA-Lab 執行取得，而不是預設的發布關鍵測試線。
### 套件
套件機器是可安裝產品門檻。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支援。解析器會將候選正規化為 Docker E2E 使用的 `package-under-test` tarball、驗證套件 inventory、記錄套件版本與 SHA-256，並讓工作流程測試框架 ref 與套件來源 ref 分離。
套件測試箱是可安裝產品門檻。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支援。解析器會將候選項正規化為 Docker E2E 使用的 `package-under-test` tar 封裝檔、驗證套件清單、記錄套件版本與 SHA-256，並讓工作流程執行框架參照與套件來源參照保持分離。
支援的候選來源：
- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精確的 OpenClaw 發行版本
- `source=ref`：使用選定的 `workflow_ref` 測試框架封裝受信任的 `package_ref` 分支、標籤或完整提交 SHA
- `source=url`：下載需要 `package_sha256` 的 HTTPS `.tgz`
- `source=artifact`：重用由另一個 GitHub Actions 執行上傳的 `.tgz`
- `source=npm`: `openclaw@beta`、`openclaw@latest`，或確切的 OpenClaw 發布版本
- `source=ref`: 使用所選 `workflow_ref` 執行框架，打包受信任的 `package_ref` 分支、標籤或完整提交 SHA
- `source=url`: 下載 HTTPS `.tgz`，並提供必要的 `package_sha256`
- `source=artifact`: 重用另一個 GitHub Actions 執行上傳的 `.tgz`
`OpenClaw Release Checks` 會以 `source=artifact`、已準備的發行套件成品、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues`，以及 `telegram_mode=mock-openai` 執行 Package Acceptance。Package Acceptance 會針對同一個已解析 tarball 保持 migration、update、陳舊 Plugin 依賴清理、offline Plugin fixtures、Plugin update，以及 Telegram 套件 QA。升級矩陣涵蓋從 `2026.4.23` 到 `latest` 的每個穩定 npm 已發布 baseline；對於已出貨的候選，使用 `source=npm` 的 Package Acceptance，或在發布前對 SHA 支援的本機 npm tarball 使用 `source=ref`/`source=artifact`。它是 GitHub 原生的替代方案，取代過去大多數需要 Parallels 的套件/update 涵蓋。跨 OS 發行檢查對 OS 特定 onboarding、安裝程式與平台行為仍然重要，但套件/update 產品驗證應優先使用 Package Acceptance。
`OpenClaw Release Checks` 會使用 `source=artifact`、已準備的發布套件成品、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues`，以及 `telegram_mode=mock-openai` 執行 Package Acceptance。Package Acceptance 會讓遷移、更新、過期 Plugin 依賴清理、離線 Plugin 夾具、Plugin 更新，以及 Telegram 套件 QA 都針對同一個已解析的 tar 封裝檔執行。升級矩陣涵蓋從 `2026.4.23` 到 `latest` 的每個 npm 已發布穩定基準；對已出貨候選版本使用 `source=npm` 的 Package Acceptance，或在發布前對有 SHA 支援的本機 npm tar 封裝檔使用 `source=ref`/`source=artifact`。它是 GitHub 原生替代方案，可取代先前大多數需要 Parallels 的套件/更新涵蓋範圍。跨 OS 發布檢查對 OS 特定的初始設定、安裝器和平台行為仍然重要，但套件/更新產品驗證應優先使用 Package Acceptance。
update 與 Plugin 驗證的標準檢查清單是 [測試 updates 和 plugins](/zh-TW/help/testing-updates-plugins)。在決定哪個本機、Docker、Package Acceptance 或 release-check lane 能證明 Plugin install/update、doctor cleanup，或已發布套件 migration 變更時，請使用它。
從每個穩定 `2026.4.23+` 套件進行的完整已發布 update migration 是獨立的手動 `Update Migration` 工作流程，不屬於 Full Release CI。
更新與 Plugin 驗證的標準檢查清單是 [測試更新與 Plugin](/zh-TW/help/testing-updates-plugins)。判斷哪個本機、Docker、Package Acceptance 或發布檢查測試線能證明 Plugin 安裝/更新、診斷清理，或已發布套件遷移變更時，請使用它。
從每個穩定 `2026.4.23+` 套件進行完整已發布更新遷移，是獨立的手動 `Update Migration` 工作流程，不屬於完整發布 CI。
舊版 package-acceptance 寬容性是刻意限時的。到 `2026.4.25` 為止的套件，可針對已發布到 npm 的 metadata gaps 使用相容性路徑：tarball 中缺少的 private QA inventory entries、缺少 `gateway install --wrapper`、tarball 衍生 git fixture 中缺少 patch files、缺少持久化的 `update.channel`、舊版 Plugin install-record locations、缺少 marketplace install-record persistence，以及 `plugins update` 期間的 config metadata migration。已發布的 `2026.4.26` 套件可能會針對已出貨的本機建置 metadata stamp files 發出警告。後續套件必須滿足現代套件合約；這些相同缺口會使發行驗證失敗。
舊版套件驗收寬限刻意設有時間限制。`2026.4.25` 以前的套件可針對已發布到 npm 的中繼資料缺口使用相容性路徑：tar 封裝檔中缺少私有 QA 清單項目、缺少 `gateway install --wrapper`、tar 封裝檔衍生的 Git 夾具中缺少補丁檔案、缺少持久化的 `update.channel`、舊版 Plugin 安裝記錄位置、缺少市集安裝記錄持久化，以及 `plugins update` 期間的設定中繼資料遷移。已發布的 `2026.4.26` 套件可針對已出貨的本機建置中繼資料戳記檔提出警告。後續套件必須滿足現代套件合約；同樣的缺口會使發布驗證失敗。
當發行問題是關於實際可安裝套件時，請使用更廣泛的 Package Acceptance 設定檔：
當發布問題關於實際可安裝套件時，使用較廣的 Package Acceptance 設定檔：
```bash
gh workflow run package-acceptance.yml \
@ -297,28 +273,29 @@ gh workflow run package-acceptance.yml \
常見套件設定檔：
- `smoke`：快速套件安裝/channel/agent、Gateway 網路，以及 config reload lanes
- `package`：沒有 live ClawHub 的 install/update/Plugin 套件合約；這是 release-check 預設值
- `product`：`package` 加上 MCP channels、cron/subagent cleanup、OpenAI web search，以及 OpenWebUI
- `full`：包含 OpenWebUI 的 Docker 發行路徑區塊
- `custom`：用於聚焦重新執行的精確 `docker_lanes` 清單
- `smoke`: 快速套件安裝/通道/代理程式、Gateway 網路，以及設定重新載入測試線
- `package`: 不含即時 ClawHub 的安裝/更新/Plugin 套件合約；這是發布檢查預設值
- `product`: `package` 加上 MCP 通道、Cron/子代理程式清理、OpenAI 網頁搜尋，以及 OpenWebUI
- `full`: 含 OpenWebUI 的 Docker 發布路徑區塊
- `custom`: 用於聚焦重跑的精確 `docker_lanes` 清單
針對套件候選版的 Telegram 證明，請在 Package Acceptance 上啟用 `telegram_mode=mock-openai` 或
對於套件候選 Telegram 證明，請在 Package Acceptance 上啟用 `telegram_mode=mock-openai` 或
`telegram_mode=live-frontier`。該工作流程會將解析後的
`package-under-test` tarball 傳入 Telegram lane；獨立的
`package-under-test` tarball 傳入 Telegram 通道；獨立的
Telegram 工作流程仍接受已發布的 npm 規格，用於發布後檢查。
## 發布自動化
`OpenClaw Release Publish` 是一般的變更型發布進入點。它會依照發行所需的順序協調 trusted-publisher 工作流程：
`OpenClaw Release Publish` 是一般會變更狀態的發布入口點。它會依照發行所需的順序協調受信任發布者工作流程：
1. 簽出發行標籤並解析其 commit SHA。
2. 驗證該標籤可從 `main` 或 `release/*` 連到。
2. 驗證該標籤可從 `main` 或 `release/*` 觸及。
3. 執行 `pnpm plugins:sync:check`。
4. 使用 `publish_scope=all-publishable` 和
`ref=<release-sha>` 分派 `Plugin NPM Release`。
5. 使用相同 scope 和 SHA 分派 `Plugin ClawHub Release`。
6. 使用發行標籤、npm dist-tag，以及已儲存的 `preflight_run_id` 分派 `OpenClaw NPM Release`。
5. 使用相同範圍和 SHA 分派 `Plugin ClawHub Release`。
6. 使用發行標籤、npm dist-tag，以及已儲存的
`preflight_run_id` 分派 `OpenClaw NPM Release`。
Beta 發布範例：
@ -330,17 +307,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Alpha 發布範例：
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D-alpha.N \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=alpha
```
穩定版發布到預設 beta dist-tag：
穩定版發布到預設的 beta dist-tag：
```bash
gh workflow run openclaw-release-publish.yml \
@ -350,7 +317,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
穩定版直接提升到 `latest` 是明確操作：
直接將穩定版提升到 `latest` 需要明確指定：
```bash
gh workflow run openclaw-release-publish.yml \
@ -360,63 +327,63 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=latest
```
只有在需要聚焦修復或重新發布工作時，才使用較低階的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流程。若要修復選定的 Plugin，請將 `plugin_publish_scope=selected` 和 `plugins=@openclaw/name` 傳給
`OpenClaw Release Publish`；或者在不得發布 OpenClaw 套件時，直接分派子工作流程。
僅在聚焦修復或重新發布工作時，才使用較低階的 `Plugin NPM Release` 和 `Plugin ClawHub Release` 工作流程。若要修復選定的 Plugin，請將
`plugin_publish_scope=selected` 和 `plugins=@openclaw/name` 傳給
`OpenClaw Release Publish`；或在不得發布 OpenClaw 套件時，直接分派子工作流程。
## NPM 工作流程輸入
`OpenClaw NPM Release` 接受以下由操作員控制的輸入：
- `tag`：必填的發行標籤，例如 `v2026.4.2`、`v2026.4.2-1`，或
`v2026.4.2-alpha.1` 或 `v2026.4.2-beta.1`；當 `preflight_only=true` 時，也可以是目前完整的 40 字元工作流程分支 commit SHA，用於僅驗證的預檢
- `preflight_only`：`true` 表示僅驗證、建置、封裝；`false` 表示實際發布路徑
- `preflight_run_id`：實際發布路徑必填，讓工作流程重用成功預檢執行所準備的 tarball
- `tag`：必要的發行標籤，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；當 `preflight_only=true` 時，也可以是目前完整的 40 字元工作流程分支 commit SHA，用於僅驗證的預檢
- `preflight_only`：`true` 表示僅驗證、建置和封裝，`false` 表示實際發布路徑
- `preflight_run_id`：實際發布路徑必填，讓工作流程重用成功預檢執行中準備好的 tarball
- `npm_dist_tag`：發布路徑的 npm 目標標籤；預設為 `beta`
`OpenClaw Release Publish` 接受以下由操作員控制的輸入：
- `tag`：必填的發行標籤；必須已存在
- `preflight_run_id`：成功的 `OpenClaw NPM Release` 預檢執行 id；
當 `publish_openclaw_npm=true` 時必填
- `tag`：必要的發行標籤；必須已存在
- `preflight_run_id`：成功的 `OpenClaw NPM Release` 預檢執行 ID；當 `publish_openclaw_npm=true` 時必填
- `npm_dist_tag`：OpenClaw 套件的 npm 目標標籤
- `plugin_publish_scope`：預設為 `all-publishable`；只有在聚焦修復工作時才使用 `selected`
- `plugin_publish_scope`：預設為 `all-publishable`；僅在聚焦修復工作時使用 `selected`
- `plugins`：當 `plugin_publish_scope=selected` 時，以逗號分隔的 `@openclaw/*` 套件名稱
- `publish_openclaw_npm`：預設為 `true`；只有在將工作流程用作僅 Plugin 修復協調器時才設為 `false`
- `publish_openclaw_npm`：預設為 `true`；僅在將工作流程用作僅 Plugin 修復協調器時設為 `false`
`OpenClaw Release Checks` 接受以下由操作員控制的輸入：
- `ref`：要驗證的分支、標籤，或完整 commit SHA。帶有祕密的檢查要求解析後的 commit 可從 OpenClaw 分支或發行標籤連到。
- `ref`：要驗證的分支、標籤或完整 commit SHA。帶有祕密的檢查要求解析後的 commit 可從 OpenClaw 分支或發行標籤觸及。
規則：
- 穩定版與修正版標籤可以發布到 `beta` 或 `latest`
- Alpha 預發行標籤只能發布到 `alpha`
- 穩定版和修正版標籤可發布到 `beta` 或 `latest`
- Beta 預發行標籤只能發布到 `beta`
- 對於 `OpenClaw NPM Release`，只有在 `preflight_only=true` 時才允許完整 commit SHA 輸入
- `OpenClaw Release Checks` 和 `Full Release Validation` 永遠都只做驗證
- 實際發布路徑必須使用預檢期間使用的相同 `npm_dist_tag`；工作流程會在發布繼續前驗證該中繼資料
- `OpenClaw Release Checks` 和 `Full Release Validation` 一律僅用於驗證
- 實際發布路徑必須使用預檢期間使用的相同 `npm_dist_tag`；工作流程會在發布前繼續驗證該中繼資料
## 穩定版 npm 發行順序
切出穩定版 npm 發行時：
1. 使用 `preflight_only=true` 執行 `OpenClaw NPM Release`
- 標籤存在前，你可以使用目前完整的工作流程分支 commit SHA，對預檢工作流程進行僅驗證的 dry run
2. 一般 beta 優先流程請選擇 `npm_dist_tag=beta`；只有在你有意直接發布穩定版時才選擇 `latest`
3. 當你想從單一手動工作流程取得一般 CI，加上即時 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆蓋率時，請在發行分支、發行標籤或完整 commit SHA 上執行 `Full Release Validation`
4. 如果你有意只需要確定性的一般測試圖，請改在發行 ref 上執行手動 `CI` 工作流程
- 在標籤存在之前，你可以使用目前完整的工作流程分支 commit SHA，對預檢工作流程進行僅驗證的試執行
2. 一般 beta 優先流程請選擇 `npm_dist_tag=beta`；只有在你有意直接發布穩定版時，才選擇 `latest`
3. 當你想從單一手動工作流程取得一般 CI，加上即時提示快取、Docker、QA Lab、Matrix 和 Telegram 覆蓋時，請在發行分支、發行標籤或完整 commit SHA 上執行 `Full Release Validation`
4. 如果你刻意只需要確定性的標準測試圖，請改在發行 ref 上執行手動 `CI` 工作流程
5. 儲存成功的 `preflight_run_id`
6. 使用相同的 `tag`、相同的 `npm_dist_tag`，以及已儲存的 `preflight_run_id` 執行 `OpenClaw Release Publish`；它會先將外部化 Plugin 發布到 npm 和 ClawHub，再提升 OpenClaw npm 套件
7. 如果發行落在 `beta`，請使用私有的
7. 如果發行落在 `beta`，請使用私有
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
工作流程，將該穩定版本從 `beta` 提升到 `latest`
8. 如果發行有意直接發布到 `latest`，且 `beta` 應立即跟隨相同的穩定版建置，請使用同一個私有工作流程，將兩個 dist-tag 都指向該穩定版本；或讓其排程的自我修復同步稍後移動 `beta`
8. 如果發行是刻意直接發布到 `latest`，且 `beta`
應立即跟隨同一個穩定建置，請使用相同的私有工作流程，將兩個 dist-tag 指向該穩定版本；或讓其排程的自我修復同步稍後移動 `beta`
dist-tag 變更位於私有 repo 中以確保安全，因為它仍然需要 `NPM_TOKEN`，而公開 repo 則維持僅 OIDC 發布。
dist-tag 變更位於私有 repo 中是出於安全考量，因為它仍需要 `NPM_TOKEN`，而公開 repo 保持僅使用 OIDC 發布。
這會讓直接發布路徑和 beta 優先提升路徑都保有文件記錄，並且對操作員可見。
這讓直接發布路徑和 beta 優先提升路徑都已文件化，且對操作員可見。
如果維護者必須退回使用本機 npm 驗證，請只在專用 tmux 工作階段內執行任何 1Password CLI (`op`) 命令。不要直接從主要代理 shell 呼叫 `op`；將它保留在 tmux 內，能讓提示、警示和 OTP 處理可觀察，並防止重複的主機警示。
如果維護者必須退回使用本機 npm 驗證，請只在專用 tmux 工作階段內執行任何 1Password CLI (`op`) 命令。不要直接從主要代理 shell 呼叫 `op`；將它放在 tmux 內可讓提示、警示和 OTP 處理可被觀察，並避免重複的主機警示。
## 公開參考
@ -430,9 +397,9 @@ dist-tag 變更位於私有 repo 中以確保安全，因為它仍然需要 `NPM
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
維護者會使用
維護者使用
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
中的私有發行文件作為實際操作手冊。
中的私有發行文件作為實際執行手冊。
## 相關

290
docs/zh-TW/web/control-ui.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 你想要透過瀏覽器操作 Gateway
- 你想要無需 SSH 通道即可存取 Tailnet
- 您想從瀏覽器操作 Gateway
- 你想要無需 SSH 隧道即可存取 Tailnet
sidebarTitle: Control UI
summary: Gateway 的瀏覽器式控制介面（聊天、節點、設定）
summary: 基於瀏覽器的 Gateway 控制 UI（聊天、節點、設定）
title: 控制介面
x-i18n:
generated_at: "2026-05-02T21:06:57Z"
generated_at: "2026-05-02T23:39:08Z"
model: gpt-5.5
provider: openai
source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c
source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208
source_path: web/control-ui.md
workflow: 16
---
控制介面是由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程式：
控制 UI 是一個小型 **Vite + Lit** 單頁應用程式，由 Gateway 提供服務：
- 預設：`http://<host>:18789/`
- 選用前綴：設定 `gateway.controlUi.basePath`（例如 `/openclaw`）
- 可選前綴：設定 `gateway.controlUi.basePath`（例如 `/openclaw`）
它會在同一個連接埠上**直接與 Gateway WebSocket** 通訊。
@ -29,124 +29,125 @@ x-i18n:
如果頁面載入失敗，請先啟動 Gateway：`openclaw gateway`。
驗證會在 WebSocket 交握期間透過以下方式提供：
驗證會在 WebSocket 握手期間透過以下方式提供：
- `connect.params.auth.token`
- `connect.params.auth.password`
- 當 `gateway.auth.allowTailscale: true` 時的 Tailscale Serve 身分標頭
- 當 `gateway.auth.mode: "trusted-proxy"` 時的受信任代理身分標頭
- 當 `gateway.auth.mode: "trusted-proxy"` 時的受信任 Proxy 身分標頭
儀表板設定面板會為目前的瀏覽器分頁工作階段和所選 Gateway URL 保留一個權杖；密碼不會被持久保存。初始設定通常會在首次連線時為共用密鑰驗證產生 Gateway 權杖，但當 `gateway.auth.mode` 是 `"password"` 時，也可以使用密碼驗證。
儀表板設定面板會為目前的瀏覽器分頁工作階段和所選 Gateway URL 保留一個權杖；密碼不會持久保存。Onboarding 通常會在第一次連線時為共享密鑰驗證產生 Gateway 權杖，但當 `gateway.auth.mode` 為 `"password"` 時，密碼驗證也可以使用。
## 裝置配對（首次連線）
## 裝置配對（第一次連線）
當你從新的瀏覽器或裝置連線到控制介面時，Gateway 通常需要**一次性配對核准**。這是一項安全措施，用來防止未授權存取。
當你從新的瀏覽器或裝置連線到控制 UI 時，Gateway 通常會要求**一次性配對核准**。這是一項安全措施，用於防止未授權存取。
**你會看到的內容：**「disconnected (1008): pairing required」
<Steps>
<Step title="列出待處理請求">
<Step title="列出待處理要求">
```bash
openclaw devices list
```
</Step>
<Step title="依請求 ID 核准">
<Step title="依要求 ID 核准">
```bash
openclaw devices approve <requestId>
```
</Step>
</Steps>
如果瀏覽器使用已變更的驗證詳細資料（角色/範圍/公開金鑰）重試配對，先前待處理的請求會被取代，並建立新的 `requestId`。核准前請重新執行 `openclaw devices list`。
如果瀏覽器以已變更的驗證詳細資料（角色/範圍/公開金鑰）重試配對，先前的待處理要求會被取代，並建立新的 `requestId`。核准前請重新執行 `openclaw devices list`。
如果瀏覽器已配對，而你將它從讀取存取變更為寫入/管理員存取，這會被視為核准升級，而不是靜默重新連線。OpenClaw 會保留舊的核准、阻擋更廣泛範圍的重新連線，並要求你明確核准新的範圍集合。
如果瀏覽器已經配對，而你將它從讀取存取變更為寫入/管理員存取，這會被視為核准升級，而不是靜默重新連線。OpenClaw 會保留舊核准有效、封鎖更高權限的重新連線，並要求你明確核准新的範圍集合。
核准後，系統會記住該裝置，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤銷它，否則不需要重新核准。請參閱[裝置 CLI](/zh-TW/cli/devices)了解權杖輪替和撤銷。
核准後，裝置會被記住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤銷它，否則不需要重新核准。請參閱[裝置 CLI](/zh-TW/cli/devices)了解權杖輪替和撤銷。
<Note>
- 直接的 local loopback 瀏覽器連線（`127.0.0.1` / `localhost`）會自動核准。
- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分驗證通過，且瀏覽器提供其裝置身分時，Tailscale Serve 可以針對控制介面操作員工作階段略過配對往返流程。
- 直接 Tailnet 繫結、區域網路瀏覽器連線，以及沒有裝置身分的瀏覽器設定檔，仍需要明確核准。
- 每個瀏覽器設定檔都會產生唯一的裝置 ID，因此切換瀏覽器或清除瀏覽器資料都會需要重新配對。
- 直接 local loopback 瀏覽器連線（`127.0.0.1` / `localhost`）會自動核准。
- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分驗證通過，且瀏覽器呈現其裝置身分時，Tailscale Serve 可以為控制 UI 操作者工作階段略過配對往返。
- 直接 Tailnet 綁定、LAN 瀏覽器連線，以及沒有裝置身分的瀏覽器設定檔仍需要明確核准。
- 每個瀏覽器設定檔都會產生唯一裝置 ID，因此切換瀏覽器或清除瀏覽器資料都需要重新配對。
</Note>
## 個人身分（瀏覽器本機）
控制介面支援每個瀏覽器各自的個人身分（顯示名稱和頭像），會附加到傳出的訊息，以便在共用工作階段中標示歸屬。它存在於瀏覽器儲存空間中，範圍限於目前的瀏覽器設定檔，不會同步到其他裝置，也不會在伺服器端持久保存，除了你實際送出的訊息上一般的逐字稿作者身分中繼資料。清除網站資料或切換瀏覽器會將它重設為空白。
控制 UI 支援每個瀏覽器的個人身分（顯示名稱和頭像），並附加到傳出訊息，以便在共享工作階段中標示歸屬。它存在於瀏覽器儲存空間中，範圍限於目前瀏覽器設定檔，不會同步到其他裝置，也不會在伺服器端持久保存，除了你實際傳送的訊息上一般逐字稿作者身分中繼資料之外。清除網站資料或切換瀏覽器會將它重設為空白。
同樣的瀏覽器本機模式也適用於助理頭像覆寫。上傳的助理頭像只會在本機瀏覽器上覆蓋 Gateway 解析出的身分，且絕不會透過 `config.patch` 往返傳送。共用的 `ui.assistant.avatar` 設定欄位仍可供直接寫入該欄位的非 UI 用戶端使用（例如指令碼化 Gateway 或自訂儀表板）。
相同的瀏覽器本機模式也適用於助理頭像覆寫。上傳的助理頭像只會在本機瀏覽器上覆蓋 Gateway 解析出的身分，且永遠不會透過 `config.patch` 往返。共享的 `ui.assistant.avatar` 設定欄位仍可供直接寫入該欄位的非 UI 用戶端使用（例如指令碼化 Gateway 或自訂儀表板）。
## 執行階段設定端點
控制介面會從 `/__openclaw/control-ui-config.json` 擷取其執行階段設定。該端點受到與其餘 HTTP 介面相同的 Gateway 驗證保護：未驗證的瀏覽器無法擷取它，而成功擷取需要已經有效的 Gateway 權杖/密碼、Tailscale Serve 身分，或受信任代理身分。
控制 UI 會從 `/__openclaw/control-ui-config.json` 擷取其執行階段設定。該端點受與其餘 HTTP 介面相同的 Gateway 驗證保護：未驗證的瀏覽器無法擷取它，而成功擷取需要已有有效的 Gateway 權杖/密碼、Tailscale Serve 身分，或受信任 Proxy 身分。
## 語言支援
控制介面可以在首次載入時依據你的瀏覽器語言環境進行本地化。若要之後覆寫它，請開啟 **總覽 -> Gateway 存取 -> 語言**。語言環境選擇器位於 Gateway 存取卡片中，而不是外觀底下。
控制 UI 可以在第一次載入時根據你的瀏覽器語言環境進行本地化。若要稍後覆寫，請開啟 **Overview -> Gateway Access -> Language**。語言環境選擇器位於 Gateway Access 卡片中，而不是 Appearance 底下。
- 支援的語言環境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
- 非英文翻譯會在瀏覽器中延遲載入。
- 所選語言環境會儲存在瀏覽器儲存空間中，並在未來造訪時重複使用。
- 缺少的翻譯鍵會回退為英文。
- 選取的語言環境會儲存在瀏覽器儲存空間中，並在未來造訪時重複使用。
- 缺少的翻譯鍵會退回英文。
文件翻譯會針對相同的非英文語言環境集合產生，但文件網站內建的 Mintlify 語言選擇器受限於 Mintlify 接受的語言環境代碼。泰文（`th`）和波斯文（`fa`）文件仍會在發布 repo 中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。
文件翻譯會針對相同的非英文語言環境集合產生，但文件網站內建的 Mintlify 語言選擇器僅限於 Mintlify 接受的語言環境代碼。泰文（`th`）和波斯文（`fa`）文件仍會在發布 repo 中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。
## 外觀主題
外觀面板保留內建的 Claw、Knot 和 Dash 主題，並加上一個瀏覽器本機 tweakcn 匯入槽。若要匯入主題，請開啟 [tweakcn 主題](https://tweakcn.com/themes)，選擇或建立主題，點擊**分享**，並將複製的主題連結貼到外觀中。匯入器也接受 `https://tweakcn.com/r/themes/<id>` 註冊表 URL、像 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 這樣的編輯器 URL、相對 `/themes/<id>` 路徑、原始主題 ID，以及像 `amethyst-haze` 這樣的預設主題名稱。
Appearance 面板保留內建的 Claw、Knot 和 Dash 主題，外加一個瀏覽器本機 tweakcn 匯入槽。若要匯入主題，請開啟 [tweakcn themes](https://tweakcn.com/themes)，選擇或建立主題，按一下 **Share**，並將複製的主題連結貼到 Appearance。匯入器也接受 `https://tweakcn.com/r/themes/<id>` 登錄 URL、像 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 這樣的編輯器 URL、相對 `/themes/<id>` 路徑、原始主題 ID，以及預設主題名稱，例如 `amethyst-haze`。
匯入的主題只會儲存在目前的瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。取代匯入的主題會更新唯一的本機槽；如果匯入的主題已被選取，清除它會將作用中主題切回 Claw。
匯入的主題只會儲存在目前的瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。替換匯入的主題會更新該本機槽；清除它時，如果匯入的主題目前被選取，作用中主題會切回 Claw。
## 它現在可以做什麼
<AccordionGroup>
<Accordion title="聊天與語音交談">
- 透過 Gateway WS 與模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。
- 透過瀏覽器即時工作階段進行語音交談。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限制的一次性瀏覽器權杖，而僅後端即時語音 Plugin 則使用 Gateway 轉送傳輸。轉送會將供應商憑證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並透過 `chat.send` 將 `openclaw_agent_consult` 工具呼叫送回較大的已設定 OpenClaw 模型。
- 在聊天中串流工具呼叫與即時工具輸出卡片（代理程式事件）。
- 使用伺服器端 STT 對 Chat 編寫器口述（`chat.transcribeAudio`）。瀏覽器會錄製一段短麥克風片段並傳送到 Gateway，由 Gateway 執行設定的 `tools.media.audio` 轉錄管線，並在不向瀏覽器暴露供應商憑證的情況下傳回草稿文字。
- 透過瀏覽器即時工作階段進行語音交談。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限的一次性瀏覽器權杖，而僅後端即時語音 Plugin 使用 Gateway 轉送傳輸。轉送會將供應商憑證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並透過 `chat.send` 將 `openclaw_agent_consult` 工具呼叫送回較大的已設定 OpenClaw 模型。
- 在 Chat 中串流工具呼叫與即時工具輸出卡片（代理事件）。
</Accordion>
<Accordion title="頻道、執行個體、工作階段、Dreaming">
- 頻道：內建加上隨附/外部 Plugin 頻道狀態、QR 登入，以及每個頻道的設定（`channels.status`、`web.login.*`、`config.patch`）。
- 執行個體：上線狀態清單與重新整理（`system-presence`）。
- 工作階段：清單與每個工作階段的模型/思考/快速/詳細/追蹤/推理覆寫（`sessions.list`、`sessions.patch`）。
- Dreaming：Dreaming 狀態、啟用/停用切換，以及 Dream Diary 閱讀器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
<Accordion title="頻道、執行個體、工作階段、dreams">
- 頻道：內建加上已綁定/外部 Plugin 頻道狀態、QR 登入，以及每個頻道設定（`channels.status`、`web.login.*`、`config.patch`）。
- 執行個體：存在清單與重新整理（`system-presence`）。
- 工作階段：清單與每個工作階段的模型/thinking/fast/verbose/trace/reasoning 覆寫（`sessions.list`、`sessions.patch`）。
- Dreams：dreaming 狀態、啟用/停用切換，以及 Dream Diary 閱讀器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
</Accordion>
<Accordion title="Cron、Skills、Node、執行核准">
- Cron 作業：列出/新增/編輯/執行/啟用/停用與執行歷史（`cron.*`）。
<Accordion title="Cron、Skills、節點、exec 核准">
- Cron 工作：列出/新增/編輯/執行/啟用/停用與執行歷史記錄（`cron.*`）。
- Skills：狀態、啟用/停用、安裝、API 金鑰更新（`skills.*`）。
- Node：清單與能力（`node.list`）。
- 執行核准：編輯 Gateway 或 Node 允許清單，以及 `exec host=gateway/node` 的詢問政策（`exec.approvals.*`）。
- 節點：清單與能力（`node.list`）。
- Exec 核准：編輯 Gateway 或節點允許清單，以及 `exec host=gateway/node` 的詢問政策（`exec.approvals.*`）。
</Accordion>
<Accordion title="設定">
- 檢視/編輯 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。
- 套用並透過驗證重新啟動（`config.apply`），並喚醒最後一個作用中工作階段。
- 寫入包含基底雜湊保護，以防止覆寫並行編輯。
- 寫入（`config.set`/`config.apply`/`config.patch`）會針對提交的設定承載中的參照，預先檢查作用中 SecretRef 解析；未解析的作用中提交參照會在寫入前被拒絕。
- 結構描述與表單算繪（`config.schema` / `config.schema.lookup`，包含欄位 `title` / `description`、符合的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin 與頻道結構描述）；只有當快照具備安全的原始往返能力時，才可使用原始 JSON 編輯器。
- 如果快照無法安全地往返原始文字，控制介面會強制使用表單模式，並針對該快照停用原始模式。
- 原始 JSON 編輯器的「重設為已儲存」會保留原始撰寫形狀（格式、註解、`$include` 版面），而不是重新算繪扁平化快照，因此當快照可以安全往返時，外部編輯可在重設後保留下來。
- 結構化 SecretRef 物件值會在表單文字輸入中以唯讀方式算繪，以防止意外發生物件轉字串的損壞。
- 套用並以驗證重新啟動（`config.apply`），並喚醒最後一個作用中的工作階段。
- 寫入包含 base-hash 防護，以防止覆蓋並行編輯。
- 寫入（`config.set`/`config.apply`/`config.patch`）會針對已提交設定酬載中的 refs 預先檢查作用中 SecretRef 解析；未解析的作用中已提交 refs 會在寫入前遭拒。
- Schema 與表單呈現（`config.schema` / `config.schema.lookup`，包括欄位 `title` / `description`、相符的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin 與頻道 schema）；只有當快照具有安全的原始往返時，Raw JSON 編輯器才可用。
- 如果快照無法安全地往返原始文字，控制 UI 會強制使用表單模式，並停用該快照的原始模式。
- Raw JSON 編輯器的「Reset to saved」會保留原始撰寫的形狀（格式、註解、`$include` 版面），而不是重新呈現扁平化快照，因此當快照可以安全往返時，外部編輯會在重設後保留下來。
- 結構化 SecretRef 物件值會在表單文字輸入中以唯讀方式呈現，以防止意外的物件到字串毀損。
</Accordion>
<Accordion title="偵錯、記錄、更新">
- 偵錯：狀態/健康狀態/模型快照、事件記錄，以及手動 RPC 呼叫（`status`、`health`、`models.list`）。
- 記錄：即時追蹤 Gateway 檔案記錄，並支援篩選/匯出（`logs.tail`）。
- 更新：執行套件/git 更新並重新啟動（`update.run`），附帶重新啟動報告，然後在重新連線後輪詢 `update.status`，以驗證正在執行的 Gateway 版本。
- 偵錯：狀態/健康情況/模型快照、事件記錄，以及手動 RPC 呼叫（`status`、`health`、`models.list`）。
- 記錄：Gateway 檔案記錄的即時尾端追蹤，包含篩選/匯出（`logs.tail`）。
- 更新：執行套件/git 更新並重新啟動（`update.run`），附帶重新啟動報告，然後在重新連線後輪詢 `update.status` 以驗證執行中的 Gateway 版本。
</Accordion>
<Accordion title="Cron 作業面板注意事項">
- 對於隔離作業，傳送預設會公告摘要。如果你想要僅內部執行，可以切換為無。
- 選取公告時，會出現頻道/目標欄位。
- Webhook 模式使用 `delivery.mode = "webhook"`，且 `delivery.to` 設為有效的 HTTP(S) Webhook URL。
- 對於主要工作階段作業，可使用 Webhook 和無傳送模式。
- 進階編輯控制項包含執行後刪除、清除代理程式覆寫、Cron 精確/錯開選項、代理程式模型/思考覆寫，以及盡力傳送切換。
<Accordion title="Cron 工作面板注意事項">
- 對於隔離工作，傳遞預設為宣布摘要。如果你想要僅限內部執行，可以切換為無。
- 選取宣布時，會出現頻道/目標欄位。
- Webhook 模式使用 `delivery.mode = "webhook"`，並將 `delivery.to` 設為有效的 HTTP(S) Webhook URL。
- 對於主工作階段工作，Webhook 和無傳遞模式可用。
- 進階編輯控制項包含執行後刪除、清除代理覆寫、Cron exact/stagger 選項、代理模型/thinking 覆寫，以及盡力傳遞切換。
- 表單驗證會以欄位層級錯誤內嵌顯示；無效值會停用儲存按鈕，直到修正為止。
- 設定 `cron.webhookToken` 以傳送專用 bearer 權杖；如果省略，Webhook 會在沒有驗證標頭的情況下送出。
- 已棄用的回退：已儲存的舊版作業若具有 `notify: true`，在遷移前仍可使用 `cron.webhook`。
- 已棄用的備援：具有 `notify: true` 的已儲存舊工作仍可使用 `cron.webhook`，直到遷移為止。
</Accordion>
</AccordionGroup>
@ -154,85 +155,86 @@ x-i18n:
## 聊天行為
<AccordionGroup>
<Accordion title="傳送與歷史記錄語意">
<Accordion title="傳送與歷史記錄語義">
- `chat.send` 是**非阻塞**的：它會立即以 `{ runId, status: "started" }` 確認，回應則透過 `chat` 事件串流傳送。
- Chat 上傳接受圖片以及非影片檔案。圖片會保留原生圖片路徑；其他檔案會儲存為受管理媒體，並在歷史記錄中顯示為附件連結。
- 使用相同的 `idempotencyKey` 重新傳送時，執行期間會回傳 `{ status: "in_flight" }`，完成後會回傳 `{ status: "ok" }`。
- 為了 UI 安全，`chat.history` 回應有大小限制。當逐字稿項目過大時，Gateway 可能會截斷長文字欄位、省略大型中繼資料區塊，並以佔位符（`[chat.history omitted: message too large]`）取代過大的訊息。
- 助理／產生的圖片會保存為受管理媒體參照，並透過已驗證的 Gateway 媒體 URL 回傳，因此重新載入不依賴原始 base64 圖片承載資料持續留在聊天歷史記錄回應中。
- `chat.history` 也會從可見的助理文字中移除僅供顯示的行內指令標籤（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、純文字工具呼叫 XML 承載資料（包含 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`，以及被截斷的工具呼叫區塊），以及外洩的 ASCII／全形模型控制權杖，並省略整個可見文字只有精確靜默權杖 `NO_REPLY` / `no_reply` 的助理項目。
- 在作用中的傳送期間和最終歷史記錄重新整理期間，如果 `chat.history` 短暫回傳較舊的快照，聊天檢視會保留本機樂觀的使用者／助理訊息可見；一旦 Gateway 歷史記錄追上，權威逐字稿就會取代這些本機訊息。
- `chat.inject` 會將助理備註附加到工作階段逐字稿，並廣播 `chat` 事件以進行僅限 UI 的更新（無代理執行、無頻道傳遞）。
- 聊天標頭的模型與思考選擇器會透過 `sessions.patch` 立即修補作用中的工作階段；它們是持久的工作階段覆寫，而不是僅限單回合的傳送選項。
- 在 Control UI 中輸入 `/new` 會建立並切換到與 New Chat 相同的全新儀表板工作階段。輸入 `/reset` 會保留 Gateway 對目前工作階段的明確原地重設。
- 聊天模型選擇器會請求 Gateway 已設定的模型檢視。如果存在 `agents.defaults.models`，該允許清單會驅動選擇器。否則，選擇器會顯示明確的 `models.providers.*.models` 項目，以及具有可用驗證的提供者。完整型錄仍可透過除錯用的 `models.list` RPC 搭配 `view: "all"` 使用。
- 當新的 Gateway 工作階段使用量報告顯示高上下文壓力時，聊天撰寫區域會顯示上下文通知；在建議的 Compaction 等級時，會顯示執行一般工作階段 Compaction 路徑的精簡按鈕。過期的權杖快照會被隱藏，直到 Gateway 再次回報新的使用量。
- `chat.transcribeAudio` 是用於 Chat 草稿的一次性聽寫輔助工具。它接受瀏覽器錄製的 base64 音訊，將上傳內容維持在 Gateway WebSocket 影格限制以下，寫入暫存本機檔案，以作用中的 Gateway 設定執行媒體理解音訊轉錄，回傳 `{ text, provider, model }`，並移除暫存檔案。它不會建立 agent run，且與即時 Talk 分開。
- Chat 上傳接受圖片及非影片檔案。圖片會保留原生圖片路徑；其他檔案會儲存為受管理媒體，並在歷史記錄中顯示為附件連結。
- 使用相同的 `idempotencyKey` 重新傳送時，執行中會回傳 `{ status: "in_flight" }`，完成後會回傳 `{ status: "ok" }`。
- 為了 UI 安全，`chat.history` 回應有大小限制。當逐字稿項目過大時，Gateway 可能會截斷長文字欄位、省略龐大的中繼資料區塊，並以預留位置（`[chat.history omitted: message too large]`）取代過大的訊息。
- Assistant/產生的圖片會保存為受管理媒體參照，並透過已驗證的 Gateway 媒體 URL 回傳，因此重新載入不依賴原始 base64 圖片酬載保留在聊天歷史記錄回應中。
- `chat.history` 也會從可見的 assistant 文字中移除僅供顯示的行內指示標籤（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、純文字工具呼叫 XML 酬載（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`，以及截斷的工具呼叫區塊），以及外洩的 ASCII/全形模型控制權杖，並省略整段可見文字只等於精確靜默權杖 `NO_REPLY` / `no_reply` 的 assistant 項目。
- 在作用中的傳送期間以及最終歷史記錄重新整理時，如果 `chat.history` 短暫回傳較舊的快照，聊天檢視會讓本機樂觀使用者/assistant 訊息保持可見；等 Gateway 歷史記錄追上後，正式逐字稿會取代那些本機訊息。
- `chat.inject` 會將 assistant 備註附加到工作階段逐字稿，並廣播 `chat` 事件以供僅限 UI 的更新使用（沒有 agent run，沒有通道傳遞）。
- 聊天標頭的模型與思考選擇器會透過 `sessions.patch` 立即修補作用中工作階段；它們是持久的工作階段覆寫，不是僅限單輪的傳送選項。
- 在 Control UI 中輸入 `/new` 會建立並切換到與 New Chat 相同的全新儀表板工作階段。輸入 `/reset` 會保留 Gateway 對目前工作階段的明確就地重設。
- 聊天模型選擇器會請求 Gateway 設定的模型檢視。如果存在 `agents.defaults.models`，該 allowlist 會驅動選擇器。否則，選擇器會顯示明確的 `models.providers.*.models` 項目，以及具有可用驗證的 provider。完整目錄仍可透過偵錯用 `models.list` RPC 搭配 `view: "all"` 取得。
- 當新的 Gateway 工作階段用量報告顯示高脈絡壓力時，聊天撰寫區會顯示脈絡通知；在建議的 Compaction 層級，會顯示一個 compact 按鈕，以執行一般的工作階段 Compaction 路徑。過時的 token 快照會被隱藏，直到 Gateway 再次回報新的用量。
</Accordion>
<Accordion title="Talk 模式（瀏覽器即時）">
Talk 模式使用已註冊的即時語音提供者。使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 設定 OpenAI，或使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey` 設定 Google；Voice Call 即時提供者設定仍可作為備援重複使用。瀏覽器絕不會收到標準提供者 API 金鑰。OpenAI 會收到用於 WebRTC 的短期 Realtime 用戶端密鑰。Google Live 會收到用於瀏覽器 WebSocket 工作階段的一次性受限 Live API 驗證權杖，其指示與工具宣告由 Gateway 鎖定到權杖中。只公開後端即時橋接的提供者會透過 Gateway 中繼傳輸執行，因此憑證與供應商 socket 會保留在伺服器端，而瀏覽器音訊則透過已驗證的 Gateway RPC 移動。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫端提供的指示覆寫。
Talk 模式使用已註冊的即時語音 provider。使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 設定 OpenAI，或使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey` 設定 Google；Voice Call 即時 provider 設定仍可作為後援重複使用。瀏覽器永遠不會收到標準 provider API key。OpenAI 會收到用於 WebRTC 的臨時 Realtime 用戶端密鑰。Google Live 會收到用於瀏覽器 WebSocket 工作階段的一次性受限 Live API 驗證 token，且指令與工具宣告會由 Gateway 鎖定在該 token 中。僅公開後端即時橋接的 provider 會透過 Gateway relay transport 執行，因此憑證和 vendor socket 會留在伺服器端，而瀏覽器音訊則透過已驗證的 Gateway RPC 傳輸。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫端提供的指令覆寫。
在 Chat 撰寫器中，Talk 控制項是麥克風聽寫按鈕旁的波形按鈕。Talk 啟動時，撰寫器狀態列會顯示 `Connecting Talk...`，音訊已連線時顯示 `Talk live`，或即時工具呼叫正透過 `chat.send` 諮詢已設定的較大模型時顯示 `Asking OpenClaw...`。
在 Chat 撰寫器中，Talk 控制項是麥克風聽寫按鈕旁的波紋按鈕。Talk 啟動時，撰寫器狀態列會顯示 `Connecting Talk...`，音訊連線後顯示 `Talk live`，或在即時工具呼叫正透過 `chat.send` 諮詢已設定的較大型模型時顯示 `Asking OpenClaw...`。
維護者即時 smoke：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 會驗證 OpenAI 瀏覽器 WebRTC SDP 交換、Google Live 受限權杖瀏覽器 WebSocket 設定，以及使用假麥克風媒體的 Gateway 中繼瀏覽器配接器。此命令只列印提供者狀態，且不記錄密鑰。
維護者即時煙霧測試：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 會驗證 OpenAI 瀏覽器 WebRTC SDP 交換、Google Live 受限 token 瀏覽器 WebSocket 設定，以及使用假麥克風媒體的 Gateway relay 瀏覽器配接器。該命令只列印 provider 狀態，不會記錄秘密。
</Accordion>
<Accordion title="停止與中止">
- 按一下 **Stop**（呼叫 `chat.abort`）。
- 執行作用中時，一般後續訊息會排入佇列。按一下已排入佇列訊息上的 **Steer**，將該後續訊息注入正在執行的回合。
- 執行中有作用中的 run 時，一般後續訊息會排入佇列。按一下佇列訊息上的 **Steer**，可將該後續訊息注入正在執行的回合。
- 輸入 `/stop`（或獨立的中止片語，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以帶外中止。
- `chat.abort` 支援 `{ sessionKey }`（無 `runId`），可中止該工作階段的所有作用中執行。
- `chat.abort` 支援 `{ sessionKey }`（無 `runId`）以中止該工作階段的所有作用中 run。
</Accordion>
<Accordion title="中止部分保留">
- 當執行被中止時，部分助理文字仍可顯示在 UI 中。
- 當存在已緩衝輸出時，Gateway 會將已中止的部分助理文字保存到逐字稿歷史記錄。
- 保存的項目包含中止中繼資料，讓逐字稿消費者能分辨中止部分與正常完成輸出。
- 當 run 被中止時，部分 assistant 文字仍可顯示在 UI 中。
- 當存在已緩衝的輸出時，Gateway 會將中止的部分 assistant 文字保存到逐字稿歷史記錄。
- 保存的項目包含中止中繼資料，讓逐字稿消費者可分辨中止部分與正常完成輸出。
</Accordion>
</AccordionGroup>
## PWA 安裝與 Web Push
Control UI 隨附 `manifest.webmanifest` 和 service worker，因此現代瀏覽器可以將其安裝為獨立 PWA。Web Push 可讓 Gateway 即使在分頁或瀏覽器視窗未開啟時，也能以通知喚醒已安裝的 PWA。
Control UI 隨附 `manifest.webmanifest` 和 service worker，因此現代瀏覽器可以將它安裝為獨立 PWA。即使分頁或瀏覽器視窗未開啟，Web Push 也能讓 Gateway 透過通知喚醒已安裝的 PWA。
| 介面 | 功能 |
| 表面 | 功能 |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | PWA manifest。瀏覽器會在可連線後提供「安裝應用程式」。 |
| `ui/public/manifest.webmanifest` | PWA manifest。瀏覽器在可到達後會提供「Install app」。 |
| `ui/public/sw.js` | 處理 `push` 事件和通知點擊的 service worker。 |
| `push/vapid-keys.json`（位於 OpenClaw 狀態目錄下） | 自動產生的 VAPID 金鑰組，用於簽署 Web Push 承載資料。 |
| `push/vapid-keys.json`（位於 OpenClaw state dir 下） | 自動產生的 VAPID keypair，用於簽署 Web Push 酬載。 |
| `push/web-push-subscriptions.json` | 保存的瀏覽器訂閱端點。 |
當你想固定金鑰（用於多主機部署、密鑰輪替或測試）時，請透過 Gateway 程序上的環境變數覆寫 VAPID 金鑰組：
當你想固定金鑰時（用於多主機部署、秘密輪替或測試），可在 Gateway 程序上透過 env vars 覆寫 VAPID keypair：
- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT`（預設為 `mailto:openclaw@localhost`）
Control UI 使用這些受範圍限制的 Gateway 方法來註冊與測試瀏覽器訂閱：
Control UI 使用這些受 scope 限制的 Gateway 方法來註冊和測試瀏覽器訂閱：
- `push.web.vapidPublicKey` — 擷取作用中的 VAPID 公開金鑰。
- `push.web.subscribe` — 註冊 `endpoint` 加上 `keys.p256dh`/`keys.auth`。
- `push.web.unsubscribe` — 移除已註冊的端點。
- `push.web.test` — 將測試通知傳送到呼叫端的訂閱。
- `push.web.vapidPublicKey` — 擷取作用中的 VAPID public key。
- `push.web.subscribe` — 註冊 `endpoint` 以及 `keys.p256dh`/`keys.auth`。
- `push.web.unsubscribe` — 移除已註冊的 endpoint。
- `push.web.test` — 將測試通知傳送到呼叫者的訂閱。
<Note>
Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/configuration) 了解中繼支援的推播）以及現有的 `push.test` 方法，後者以原生行動裝置配對為目標。
Web Push 獨立於 iOS APNS relay 路徑（請參閱 [設定](/zh-TW/gateway/configuration) 了解 relay 支援的 push）以及現有的 `push.test` 方法，後者目標是原生行動裝置配對。
</Note>
## 託管嵌入
助理訊息可以使用 `[embed ...]` 短代碼行內呈現託管的 Web 內容。iframe sandbox 政策由 `gateway.controlUi.embedSandbox` 控制：
Assistant 訊息可使用 `[embed ...]` shortcode 行內呈現託管網頁內容。iframe sandbox 政策由 `gateway.controlUi.embedSandbox` 控制：
<Tabs>
<Tab title="strict">
停用託管嵌入內的指令碼執行。
停用託管嵌入中的 script 執行。
</Tab>
<Tab title="scripts（預設）">
允許互動式嵌入，同時保持來源隔離；這是預設值，通常足以支援自含式瀏覽器遊戲／小工具。
允許互動式嵌入，同時保持來源隔離；這是預設值，通常足以支援自含式瀏覽器遊戲/widgets。
</Tab>
<Tab title="trusted">
在 `allow-scripts` 之上加入 `allow-same-origin`，用於有意需要更強權限的同站文件。
在 `allow-scripts` 之上加入 `allow-same-origin`，用於有意需要更強權限的 same-site 文件。
</Tab>
</Tabs>
@ -249,14 +251,14 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
```
<Warning>
只有在嵌入文件確實需要同源行為時，才使用 `trusted`。對多數代理產生的遊戲與互動式畫布而言，`scripts` 是較安全的選擇。
只有在嵌入文件確實需要 same-origin 行為時才使用 `trusted`。對大多數 agent 產生的遊戲和互動畫布而言，`scripts` 是較安全的選擇。
</Warning>
絕對外部 `http(s)` 嵌入 URL 預設仍會被封鎖。如果你有意讓 `[embed url="https://..."]` 載入第三方頁面，請設定 `gateway.controlUi.allowExternalEmbedUrls: true`。
預設會封鎖絕對外部 `http(s)` 嵌入 URL。如果你有意讓 `[embed url="https://..."]` 載入第三方頁面，請設定 `gateway.controlUi.allowExternalEmbedUrls: true`。
## 聊天訊息寬度
群組聊天訊息使用易讀的預設最大寬度。寬螢幕部署可以透過設定 `gateway.controlUi.chatMessageMaxWidth` 覆寫，而不必修補 bundled CSS：
分組聊天訊息使用易讀的預設 max-width。寬螢幕部署可透過設定 `gateway.controlUi.chatMessageMaxWidth` 覆寫，而不必修補隨附的 CSS：
```json5
{
@ -268,7 +270,7 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
}
```
該值會在到達瀏覽器前經過驗證。支援的值包含一般長度與百分比，例如 `960px` 或 `82%`，以及受限制的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。
該值在到達瀏覽器前會先經過驗證。支援的值包括純長度和百分比，例如 `960px` 或 `82%`，以及受限制的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。
## Tailnet 存取（建議）
@ -284,16 +286,16 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
- `https://<magicdns>/`（或你設定的 `gateway.controlUi.basePath`）
預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，Control UI／WebSocket Serve 請求可以透過 Tailscale 身分標頭（`tailscale-user-login`）驗證。OpenClaw 會透過 `tailscale whois` 解析 `x-forwarded-for` 位址並將其與標頭比對，以驗證身分，而且只有在請求透過 loopback 命中並帶有 Tailscale 的 `x-forwarded-*` 標頭時才會接受。對於具有瀏覽器裝置身分的 Control UI 操作員工作階段，這個已驗證的 Serve 路徑也會略過裝置配對往返；無裝置的瀏覽器與 node 角色連線仍會遵循一般裝置檢查。如果你想要求即使是 Serve 流量也必須使用明確的共享密鑰憑證，請設定 `gateway.auth.allowTailscale: false`。然後使用 `gateway.auth.mode: "token"` 或 `"password"`。
預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，Control UI/WebSocket Serve 請求可透過 Tailscale 身分標頭（`tailscale-user-login`）驗證。OpenClaw 會透過 `tailscale whois` 解析 `x-forwarded-for` 位址並與標頭比對來驗證身分，且僅在請求命中 loopback 並帶有 Tailscale 的 `x-forwarded-*` 標頭時接受這些請求。對具有瀏覽器裝置身分的 Control UI operator 工作階段，此已驗證的 Serve 路徑也會略過裝置配對往返；無裝置瀏覽器和 node-role 連線仍會遵循一般裝置檢查。如果你想即使是 Serve 流量也要求明確的 shared-secret 憑證，請設定 `gateway.auth.allowTailscale: false`。接著使用 `gateway.auth.mode: "token"` 或 `"password"`。
對於該非同步 Serve 身分路徑，同一用戶端 IP 與驗證範圍的失敗驗證嘗試，會在寫入速率限制前被序列化。因此，同一瀏覽器的並行錯誤重試可能會在第二個請求上顯示 `retry later`，而不是兩個普通不相符在平行中競爭。
對於該 async Serve 身分路徑，來自相同用戶端 IP 和 auth scope 的驗證失敗嘗試會在 rate-limit 寫入前被序列化。因此，來自同一瀏覽器的並行錯誤重試可能會在第二個請求顯示 `retry later`，而不是兩個單純不相符並行競爭。
<Warning>
無權杖 Serve 驗證假設 gateway 主機是可信任的。如果該主機上可能執行不可信的本機程式碼，請要求權杖／密碼驗證。
無 token 的 Serve auth 假設 gateway 主機受信任。如果不受信任的本機程式碼可能在該主機上執行，請要求 token/password auth。
</Warning>
</Tab>
<Tab title="繫結到 tailnet + 權杖">
<Tab title="繫結到 tailnet + token">
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
@ -302,25 +304,25 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
- `http://<tailscale-ip>:18789/`（或你設定的 `gateway.controlUi.basePath`）
將相符的共享密鑰貼到 UI 設定中（以 `connect.params.auth.token` 或 `connect.params.auth.password` 傳送）。
將相符的 shared secret 貼到 UI 設定中（以 `connect.params.auth.token` 或 `connect.params.auth.password` 傳送）。
</Tab>
</Tabs>
## 不安全的 HTTP
如果你透過純 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）開啟儀表板，瀏覽器會在**非安全上下文**中執行並封鎖 WebCrypto。預設情況下，OpenClaw 會**封鎖**沒有裝置身分的 Control UI 連線。
如果你透過純 HTTP（`http://<lan-ip>` 或 `http://<tailscale-ip>`）開啟儀表板，瀏覽器會在**非安全脈絡**中執行並封鎖 WebCrypto。預設情況下，OpenClaw 會**封鎖**沒有裝置身分的 Control UI 連線。
記錄於文件的例外：
已記錄的例外：
- 僅限 localhost 的不安全 HTTP 相容性，搭配 `gateway.controlUi.allowInsecureAuth=true`
- 透過 `gateway.auth.mode: "trusted-proxy"` 成功的操作員 Control UI 驗證
- 緊急破例 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- 透過 `gateway.auth.mode: "trusted-proxy"` 成功完成操作員控制 UI 驗證
- 緊急避險 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**建議修正：**使用 HTTPS（Tailscale Serve），或在本機開啟 UI：
- `https://<magicdns>/`（Serve）
- `http://127.0.0.1:18789/`（在 gateway 主機上）
- `http://127.0.0.1:18789/`（在 Gateway 主機上）
<AccordionGroup>
<Accordion title="不安全驗證切換行為">
@ -336,12 +338,12 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
`allowInsecureAuth` 只是本機相容性切換：
- 它允許 localhost 控制 UI 工作階段在非安全 HTTP 環境中，不具備裝置身分也能繼續進行。
- 它允許 localhost 控制 UI 工作階段在非安全 HTTP 情境中不需裝置身分即可繼續。
- 它不會略過配對檢查。
- 它不會放寬遠端（非 localhost）裝置身分要求。
</Accordion>
<Accordion title="僅限緊急破例">
<Accordion title="僅供緊急避險">
```json5
{
gateway: {
@ -353,52 +355,52 @@ Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/con
```
<Warning>
`dangerouslyDisableDeviceAuth` 會停用控制 UI 裝置身分檢查，並造成嚴重的安全性降級。緊急使用後請盡快還原。
`dangerouslyDisableDeviceAuth` 會停用控制 UI 裝置身分檢查，這是嚴重的安全性降級。緊急使用後請盡快還原。
</Warning>
</Accordion>
<Accordion title="受信任 Proxy 注意事項">
- 成功的受信任 Proxy 驗證可以在沒有裝置身分的情況下允許**操作員**控制 UI 工作階段進入。
- 這**不會**延伸到節點角色控制 UI 工作階段。
- 同主機 loopback 反向 Proxy 仍不符合受信任 Proxy 驗證；請參閱[受信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。
<Accordion title="trusted-proxy 注意事項">
- 成功的 trusted-proxy 驗證可以允許**操作員**控制 UI 工作階段不需裝置身分即可進入。
- 這**不會**延伸到 node-role 控制 UI 工作階段。
- 同一主機的 loopback 反向代理仍無法滿足 trusted-proxy 驗證；請參閱 [trusted-proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。
</Accordion>
</AccordionGroup>
HTTPS 設定指引請參閱 [Tailscale](/zh-TW/gateway/tailscale)。
請參閱 [Tailscale](/zh-TW/gateway/tailscale) 取得 HTTPS 設定指引。
## 內容安全政策
控制 UI 隨附嚴格的 `img-src` 政策：只允許**同源**資產、`data:` URL，以及本機產生的 `blob:` URL。遠端 `http(s)` 和協定相對圖片 URL 會被瀏覽器拒絕，且不會發出網路擷取。
控制 UI 內建嚴格的 `img-src` 政策：只允許**同源**資產、`data:` URL，以及本機產生的 `blob:` URL。遠端 `http(s)` 與協定相對圖片 URL 會被瀏覽器拒絕，且不會發出網路擷取。
實務上的含義：
實務上的意思是：
- 透過相對路徑提供的頭像和圖片（例如 `/avatars/<id>`）仍會呈現，包括 UI 擷取並轉換成本機 `blob:` URL 的已驗證頭像路由。
- 內嵌 `data:image/...` URL 仍會呈現（適用於協定內承載內容）。
- 透過相對路徑提供的頭像與圖片（例如 `/avatars/<id>`）仍會呈現，包括 UI 擷取並轉換成本機 `blob:` URL 的已驗證頭像路由。
- 行內 `data:image/...` URL 仍會呈現（對協定內酬載很有用）。
- 控制 UI 建立的本機 `blob:` URL 仍會呈現。
- 頻道中繼資料送出的遠端頭像 URL 會在控制 UI 的頭像輔助工具中被移除，並改用內建標誌／徽章，因此遭入侵或惡意頻道無法強迫操作員瀏覽器擷取任意遠端圖片。
- 頻道中繼資料輸出的遠端頭像 URL 會在控制 UI 的頭像輔助程式中被移除，並替換成內建 logo/badge，因此遭入侵或惡意的頻道無法強制操作員瀏覽器擷取任意遠端圖片。
你不需要變更任何設定即可取得此行為，它一律啟用且不可設定。
你不需要變更任何設定即可取得此行為，它永遠啟用且不可設定。
## 頭像路由驗證
設定 Gateway 驗證後，控制 UI 頭像端點會要求與 API 其餘部分相同的 Gateway token：
設定 Gateway 驗證時，控制 UI 頭像端點需要與 API 其餘部分相同的 Gateway token：
- `GET /avatar/<agentId>` 只會對已驗證呼叫者傳回頭像圖片。`GET /avatar/<agentId>?meta=1` 會依照相同規則傳回頭像中繼資料。
- 對任一路由的未驗證要求都會被拒絕（與同層的助理媒體路由一致）。這可防止頭像路由在其他方面受保護的主機上洩漏代理身分。
- 控制 UI 本身會在擷取頭像時，以 bearer header 轉送 Gateway token，並使用已驗證的 blob URL，讓圖片仍可在儀表板中呈現。
- `GET /avatar/<agentId>` 只會向已驗證呼叫端回傳頭像圖片。`GET /avatar/<agentId>?meta=1` 會依照相同規則回傳頭像中繼資料。
- 對任一路由的未驗證請求都會被拒絕（與相鄰的 assistant-media 路由一致）。這可防止頭像路由在其他部分受保護的主機上洩漏 agent 身分。
- 控制 UI 本身在擷取頭像時會將 Gateway token 作為 bearer header 轉送，並使用已驗證的 blob URL，讓圖片仍可在儀表板中呈現。
如果你停用 Gateway 驗證（不建議在共用主機上這麼做），頭像路由也會依照 Gateway 其餘部分的行為變成未驗證。
如果停用 Gateway 驗證（不建議在共用主機上這麼做），頭像路由也會變成未驗證，與 Gateway 其餘部分一致。
## 建置 UI
Gateway 會從 `dist/control-ui` 提供靜態檔案。使用以下指令建置：
Gateway 會從 `dist/control-ui` 提供靜態檔案。請使用以下指令建置：
```bash
pnpm ui:build
```
選用的絕對基底（當你想要固定資產 URL 時）：
選用的絕對 base（當你想要固定資產 URL 時）：
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -410,11 +412,11 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
pnpm ui:dev
```
然後將 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。
接著將 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。
## 偵錯／測試：開發伺服器 + 遠端 Gateway
## 除錯／測試：開發伺服器 + 遠端 Gateway
控制 UI 是靜態檔案；WebSocket 目標可以設定，並且可與 HTTP 來源不同。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。
控制 UI 是靜態檔案；WebSocket 目標可設定，且可與 HTTP origin 不同。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。
<Steps>
<Step title="啟動 UI 開發伺服器">
@ -427,7 +429,7 @@ pnpm ui:dev
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
```
選用的一次性驗證（如有需要）：
選用的一次性驗證（如需要）：
```text
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
@ -440,15 +442,15 @@ pnpm ui:dev
<Accordion title="注意事項">
- `gatewayUrl` 會在載入後儲存在 localStorage，並從 URL 中移除。
- 如果你透過 `gatewayUrl` 傳入完整的 `ws://` 或 `wss://` 端點，請對 `gatewayUrl` 值進行 URL 編碼，讓瀏覽器正確解析查詢字串。
- `token` 應盡可能透過 URL fragment（`#token=...`）傳入。Fragment 不會傳送到伺服器，可避免要求記錄和 Referer 外洩。舊版 `?token=` 查詢參數仍會為了相容性匯入一次，但僅作為備援，且會在啟動後立即移除。
- 盡可能透過 URL fragment（`#token=...`）傳遞 `token`。Fragments 不會傳送到伺服器，可避免請求記錄與 Referer 洩漏。舊版 `?token=` 查詢參數仍會為了相容性匯入一次，但只作為備援，並會在啟動後立即移除。
- `password` 只會保留在記憶體中。
- 設定 `gatewayUrl` 後，UI 不會回退使用設定或環境憑證。請明確提供 `token`（或 `password`）。缺少明確憑證會造成錯誤。
- 當 Gateway 位於 TLS 後方時，請使用 `wss://`（Tailscale Serve、HTTPS Proxy 等）。
- `gatewayUrl` 只會在頂層視窗中被接受（不可嵌入），以防止 clickjacking。
- 非 loopback 控制 UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整來源）。這包含遠端開發設定。
- Gateway 啟動時可能會根據有效的執行階段繫結和連接埠，植入本機來源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但遠端瀏覽器來源仍需要明確項目。
- 除非是嚴格控管的本機測試，否則不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器來源，而不是「符合我正在使用的任何主機」。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host-header 來源備援模式，但這是危險的安全模式。
- 設定 `gatewayUrl` 時，UI 不會回退到設定或環境憑證。請明確提供 `token`（或 `password`）。缺少明確憑證是錯誤。
- 當 Gateway 位於 TLS 後方時（Tailscale Serve、HTTPS proxy 等），請使用 `wss://`。
- `gatewayUrl` 只會在頂層視窗中接受（不可嵌入），以防止 clickjacking。
- 非 loopback 的控制 UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整 origins）。這包含遠端開發設定。
- Gateway 啟動時可能會依據有效的執行階段 bind 與 port，植入 `http://localhost:<port>` 和 `http://127.0.0.1:<port>` 等本機 origins，但遠端瀏覽器 origins 仍需要明確項目。
- 除非是嚴格受控的本機測試，否則不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器 origin，而不是「符合我正在使用的任何主機」。
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host-header origin fallback 模式，但這是危險的安全模式。
</Accordion>
</AccordionGroup>
@ -465,11 +467,11 @@ pnpm ui:dev
}
```
遠端存取設定詳細資訊：[遠端存取](/zh-TW/gateway/remote)。
遠端存取設定詳細資料：[遠端存取](/zh-TW/gateway/remote)。
## 相關內容
## 相關
- [儀表板](/zh-TW/web/dashboard) — Gateway 儀表板
- [健康狀態檢查](/zh-TW/gateway/health) — Gateway 健康狀態監控
- [健康檢查](/zh-TW/gateway/health) — Gateway 健康監控
- [TUI](/zh-TW/web/tui) — 終端使用者介面
- [WebChat](/zh-TW/web/webchat) — 瀏覽器型聊天介面
- [WebChat](/zh-TW/web/webchat) — 瀏覽器式聊天介面

78
docs/zh-TW/web/webchat.md
View File

@ -1,13 +1,13 @@
---
read_when:
- 偵錯或設定 WebChat 存取權
summary: Loopback WebChat 靜態託管與聊天 UI 的 Gateway WS 使用方式
summary: 回送 WebChat 靜態主機與聊天介面的 Gateway WS 使用方式
title: 網頁聊天
x-i18n:
generated_at: "2026-05-02T21:07:22Z"
generated_at: "2026-05-02T23:39:01Z"
model: gpt-5.5
provider: openai
source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d
source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f
source_path: web/webchat.md
workflow: 16
---
@ -17,54 +17,54 @@ x-i18n:
## 這是什麼
- Gateway 的原生聊天 UI（沒有嵌入式瀏覽器，也沒有本機靜態伺服器）。
- 使用與其他頻道相同的工作階段與路由規則。
- 確定性路由：回覆一律回到 WebChat。
- 使用與其他通道相同的工作階段和路由規則。
- 確定性路由：回覆一律送回 WebChat。
## 快速開始
1. 啟動 Gateway。
2. 開啟 WebChat UI（macOS/iOS 應用程式）或 Control UI 聊天分頁。
3. 確認已設定有效的 Gateway 驗證路徑（預設為 shared-secret，
2. 開啟 WebChat UI（macOS/iOS app）或 Control UI 聊天分頁。
3. 確認已設定有效的 Gateway 驗證路徑（預設為共享密鑰，
即使在 loopback 上也是如此）。
## 運作方式（行為）
- UI 會連線到 Gateway WebSocket，並使用 `chat.history`、`chat.send` 和 `chat.inject`。
- `chat.history` 會為了穩定性受到限制：Gateway 可能會截斷過長文字欄位、省略大型中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。
- 對於現代 append-only 工作階段檔案，`chat.history` 會遵循作用中的逐字稿分支，因此被放棄的重寫分支與已被取代的提示副本不會在 WebChat 中呈現。
- Control UI 會記住 `chat.history` 回傳的後端 Gateway `sessionId`，並在後續 `chat.send` 呼叫中包含它，因此重新連線與頁面重新整理會繼續同一個已儲存的對話，除非使用者開始或重設工作階段。
- Control UI 會在產生新的 `chat.send` 執行 ID 之前，合併同一工作階段、訊息與附件的重複進行中提交；Gateway 仍會對重用相同冪等性金鑰的重複請求進行去重。
- `chat.history` 也會進行顯示正規化：只在執行階段使用的 OpenClaw 上下文、
inbound envelope 包裝器、行內傳遞指示標籤
例如 `[[reply_to_*]]` 與 `[[audio_as_voice]]`、純文字 tool-call XML
- UI 會連線到 Gateway WebSocket，並使用 `chat.history`、`chat.send`、`chat.inject` 和 `chat.transcribeAudio`。
- `chat.history` 會受限以維持穩定性：Gateway 可能會截斷過長的文字欄位、省略大型中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。
- 對於現代僅附加的工作階段檔案，`chat.history` 會沿用作用中的逐字稿分支，因此遭放棄的重寫分支和已被取代的提示副本不會在 WebChat 中呈現。
- Control UI 會記住 `chat.history` 回傳的後端 Gateway `sessionId`，並在後續 `chat.send` 呼叫中包含它，因此重新連線和頁面重新整理會延續相同的已儲存對話，除非使用者啟動或重設工作階段。
- 在產生新的 `chat.send` 執行 id 之前，Control UI 會合併同一工作階段、訊息和附件的重複進行中提交；Gateway 仍會對重複使用相同冪等鍵的重複請求進行去重。
- `chat.history` 也會進行顯示正規化：僅執行期使用的 OpenClaw 情境、
傳入信封包裝器、內嵌遞送指令標籤
例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、純文字工具呼叫 XML
payload（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>`，以及被截斷的 tool-call 區塊），以及
洩漏的 ASCII/全形模型控制 token 都會從可見文字中移除，
並且會省略整段可見文字只有精確靜默
token `NO_REPLY` / `no_reply` 的 assistant 項目。
- 標記為推理的回覆 payload（`isReasoning: true`）會從 WebChat assistant 內容、逐字稿重播文字與音訊內容區塊中排除，因此僅供思考用的 payload 不會顯示為可見的 assistant 訊息或可播放音訊。
- `chat.inject` 會直接將 assistant 備註附加到逐字稿，並廣播給 UI（沒有代理執行）。
- 已中止的執行可在 UI 中保留部分 assistant 輸出。
- 當存在已緩衝輸出時，Gateway 會將已中止的部分 assistant 文字保存到逐字稿歷史，並以中止中繼資料標記這些項目。
- 歷史一律從 Gateway 擷取（不監看本機檔案）。
- 如果無法連上 Gateway，WebChat 會是唯讀。
`<function_calls>...</function_calls>`，以及被截斷的工具呼叫區塊），以及
洩漏出的 ASCII/全形模型控制 token 都會從可見文字中移除，
且整段可見文字只有精確靜默 token `NO_REPLY` / `no_reply` 的 assistant 項目會被省略。
- 標記為 reasoning 的回覆 payload（`isReasoning: true`）會從 WebChat assistant 內容、逐字稿重播文字和音訊內容區塊中排除，因此僅供思考的 payload 不會顯示為可見的 assistant 訊息或可播放音訊。
- `chat.transcribeAudio` 為 Control UI 聊天撰寫器提供伺服器端聽寫功能。瀏覽器會錄製麥克風音訊、以 base64 傳送到 Gateway，然後 Gateway 執行已設定的 `tools.media.audio` 管線。回傳的逐字稿會插入草稿；在使用者送出前不會啟動任何 agent 執行。
- `chat.inject` 會直接將 assistant 註記附加到逐字稿，並將它廣播到 UI（不會執行 agent）。
- 已中止的執行可以讓部分 assistant 輸出持續顯示在 UI 中。
- 當存在已緩衝輸出時，Gateway 會將已中止的部分 assistant 文字保存到逐字稿歷史中，並以中止中繼資料標記這些項目。
- 歷史一律從 Gateway 擷取（不會監看本機檔案）。
- 如果無法連上 Gateway，WebChat 會是唯讀狀態。
## Control UI 代理工具面板
## Control UI agent 工具面板
- Control UI `/agents` 工具面板有兩個獨立檢視：
- **Available Right Now** 使用 `tools.effective(sessionKey=...)`，並顯示目前
工作階段在執行階段實際可用的內容，包括核心、Plugin 與頻道擁有的工具。
- **Tool Configuration** 使用 `tools.catalog`，並保持聚焦於設定檔、覆寫與
- **目前可用** 使用 `tools.effective(sessionKey=...)`，並顯示目前
工作階段在執行期實際可使用的內容，包括核心、plugin 和通道擁有的工具。
- **工具設定** 使用 `tools.catalog`，並聚焦於設定檔、覆寫和
目錄語意。
- 執行階段可用性是以工作階段為範圍。在同一個代理上切換工作階段可能會改變
**Available Right Now** 清單。
- 設定編輯器不代表執行階段可用；有效存取權仍會遵循原則
優先順序（`allow`/`deny`、每個代理與 provider/channel 覆寫）。
- 執行期可用性以工作階段為範圍。在同一個 agent 上切換工作階段可能會改變
**目前可用** 清單。
- 設定編輯器不代表執行期可用性；有效存取仍會遵循政策
優先順序（`allow`/`deny`、每個 agent 以及 provider/channel 覆寫）。
## 遠端使用
- 遠端模式會透過 SSH/Tailscale 將 Gateway WebSocket 建立隧道。
- 遠端模式會透過 SSH/Tailscale 將 Gateway WebSocket 建立 tunnel。
- 你不需要執行獨立的 WebChat 伺服器。
## 設定參考（WebChat）
@ -73,18 +73,18 @@ x-i18n:
WebChat 選項：
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷過長文字欄位，並可能以佔位符取代過大的訊息。用戶端也可以傳送每個請求的 `maxChars`，以針對單一 `chat.history` 呼叫覆寫此預設值。
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷過長的文字欄位，並可能以預留位置取代過大的訊息。用戶端也可以傳送每次請求的 `maxChars`，以便在單次 `chat.history` 呼叫中覆寫此預設值。
相關全域選項：
- `gateway.port`、`gateway.bind`：WebSocket 主機/連接埠。
- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：
shared-secret WebSocket 驗證。
- `gateway.auth.allowTailscale`：啟用時，瀏覽器 Control UI 聊天分頁可使用 Tailscale
共享密鑰 WebSocket 驗證。
- `gateway.auth.allowTailscale`：啟用時，瀏覽器 Control UI 聊天分頁可以使用 Tailscale
Serve 身分標頭。
- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的 **non-loopback** 代理來源後方瀏覽器用戶端使用的反向代理驗證（請參閱 [受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)）。
- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的 **非 loopback** proxy 來源後方瀏覽器用戶端使用的反向 proxy 驗證（請參閱[受信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)）。
- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：遠端 Gateway 目標。
- `session.*`：工作階段儲存與主要金鑰預設值。
- `session.*`：工作階段儲存和主要鍵預設值。
## 相關