chore(i18n): refresh zh-TW translations

2026-05-04 18:25:55 +00:00 · 2026-05-04 18:25:55 +00:00 · 1b57c9d8ad
commit 1b57c9d8ad
parent 5b92d2771e
11 changed files with 1123 additions and 1057 deletions
--- a/docs/zh-TW/channels/zalouser.md
+++ b/docs/zh-TW/channels/zalouser.md
@ -5,44 +5,42 @@ read_when:
 summary: 透過原生 zca-js（QR 登入）支援 Zalo 個人帳號、功能與設定
 title: Zalo 個人版
 x-i18n:
-    generated_at: "2026-05-02T22:17:16Z"
+    generated_at: "2026-05-04T18:23:38Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
+    source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
    source_path: channels/zalouser.md
    workflow: 16
 ---

-狀態：實驗性。此整合會透過 OpenClaw 內的原生 `zca-js` 自動化一個**個人 Zalo 帳號**。
+狀態：實驗性。此整合透過 OpenClaw 內部的原生 `zca-js` 自動化一個**個人 Zalo 帳號**。

 <Warning>
-這是非官方整合，可能導致帳號停權或封鎖。請自行承擔風險使用。
+這是非官方整合，可能導致帳號遭停權或封鎖。請自行承擔使用風險。
 </Warning>

-## 內建 Plugin
+## 捆綁的 Plugin

-Zalo Personal 會作為目前 OpenClaw 版本中的內建 Plugin 隨附，因此一般
-封裝建置不需要另外安裝。
+Zalo Personal 以捆綁 Plugin 的形式隨目前的 OpenClaw 版本提供，因此一般封裝建置不需要另外安裝。

-如果你使用較舊的建置版本，或自訂安裝中排除了 Zalo Personal，
-請直接安裝 npm 套件：
+如果你使用的是較舊的建置，或自訂安裝排除了 Zalo Personal，請直接安裝 npm 套件：

 - 透過 CLI 安裝：`openclaw plugins install @openclaw/zalouser`
- 固定版本：`openclaw plugins install @openclaw/zalouser@2026.5.2`
+- 指定版本：`openclaw plugins install @openclaw/zalouser@2026.5.2`
 - 或從原始碼 checkout 安裝：`openclaw plugins install ./path/to/local/zalouser-plugin`
- 詳細資訊：[Plugin](/zh-TW/tools/plugin)
+- 詳細資料：[Plugins](/zh-TW/tools/plugin)

 不需要外部 `zca`/`openzca` CLI 二進位檔。

 ## 快速設定（初學者）

 1. 確認 Zalo Personal Plugin 可用。
-   - 目前封裝的 OpenClaw 版本已經內建。
-   - 較舊或自訂安裝可用上方命令手動加入。
+   - 目前封裝的 OpenClaw 發行版本已經內建它。
+   - 較舊或自訂安裝可使用上述命令手動加入。
 2. 登入（QR，在 Gateway 機器上）：
   - `openclaw channels login --channel zalouser`
   - 使用 Zalo 行動應用程式掃描 QR code。
-3. 啟用 channel：
+3. 啟用頻道：

 ```json5
 {
@ -56,22 +54,22 @@ Zalo Personal 會作為目前 OpenClaw 版本中的內建 Plugin 隨附，因此
 ```

 4. 重新啟動 Gateway（或完成設定）。
-5. DM 存取預設為配對；第一次聯絡時核准配對碼。
+5. DM 存取預設為配對；首次聯絡時核准配對碼。

 ## 它是什麼

 - 完全透過 `zca-js` 在程序內執行。
 - 使用原生事件監聽器接收傳入訊息。
 - 透過 JS API 直接傳送回覆（文字/媒體/連結）。
- 專為無法使用 Zalo Bot API 的「個人帳號」使用案例設計。
+- 設計給 Zalo Bot API 無法使用時的「個人帳號」使用情境。

 ## 命名

-Channel id 是 `zalouser`，用來明確表示這會自動化一個**個人 Zalo 使用者帳號**（非官方）。我們保留 `zalo` 給未來可能的官方 Zalo API 整合。
+頻道 id 是 `zalouser`，用來明確表示這會自動化一個**個人 Zalo 使用者帳號**（非官方）。我們保留 `zalo` 給未來可能的官方 Zalo API 整合。

 ## 尋找 ID（目錄）

-使用目錄 CLI 探索 peer/group 及其 ID：
+使用目錄 CLI 探索對等對象/群組及其 ID：

 ```bash
 openclaw directory self --channel zalouser
@ -81,16 +79,18 @@ openclaw directory groups list --channel zalouser --query "work"

 ## 限制

- 外送文字會被分段為約 2000 個字元（Zalo 用戶端限制）。
+- 傳出文字會分段為約 2000 個字元（Zalo 用戶端限制）。
 - 預設會封鎖串流。

 ## 存取控制（DM）

 `channels.zalouser.dmPolicy` 支援：`pairing | allowlist | open | disabled`（預設：`pairing`）。

-`channels.zalouser.allowFrom` 接受使用者 ID 或名稱。設定期間，名稱會使用 Plugin 的程序內聯絡人查找解析為 ID。
+`channels.zalouser.allowFrom` 應使用穩定的 Zalo 使用者 ID。在互動式設定期間，輸入的名稱可以使用 Plugin 的程序內聯絡人查找解析為 ID。

-透過以下方式核准：
+如果原始名稱仍留在設定中，啟動時只有在啟用 `channels.zalouser.dangerouslyAllowNameMatching: true` 時才會解析它。若沒有該選擇加入，執行階段的傳送者檢查只使用 ID，原始名稱會被忽略，不會用於授權。
+
+透過以下命令核准：

 - `openclaw pairing list zalouser`
 - `openclaw pairing approve zalouser <code>`
@ -98,17 +98,17 @@ openclaw directory groups list --channel zalouser --query "work"
 ## 群組存取（選用）

 - 預設：`channels.zalouser.groupPolicy = "open"`（允許群組）。未設定時，使用 `channels.defaults.groupPolicy` 覆寫預設值。
- 使用以下設定限制為允許清單：
+- 使用以下設定限制為 allowlist：
  - `channels.zalouser.groupPolicy = "allowlist"`
-  - `channels.zalouser.groups`（key 應為穩定的群組 ID；啟動時會盡可能將名稱解析為 ID）
+  - `channels.zalouser.groups`（鍵應為穩定的群組 ID；只有在啟用 `channels.zalouser.dangerouslyAllowNameMatching: true` 時，啟動時才會將名稱解析為 ID）
  - `channels.zalouser.groupAllowFrom`（控制允許群組中的哪些傳送者可以觸發 bot）
 - 封鎖所有群組：`channels.zalouser.groupPolicy = "disabled"`。
- 設定精靈可以提示輸入群組允許清單。
- 啟動時，OpenClaw 會將允許清單中的群組/使用者名稱解析為 ID，並記錄對應關係。
- 群組允許清單比對預設僅使用 ID。未解析的名稱不會用於驗證，除非啟用 `channels.zalouser.dangerouslyAllowNameMatching: true`。
- `channels.zalouser.dangerouslyAllowNameMatching: true` 是緊急相容模式，會重新啟用可變的群組名稱比對。
- 如果未設定 `groupAllowFrom`，runtime 會回退使用 `allowFrom` 進行群組傳送者檢查。
- 傳送者檢查同時套用於一般群組訊息與控制命令（例如 `/new`、`/reset`）。
+- 設定精靈可以提示輸入群組 allowlist。
+- 啟動時，OpenClaw 只有在啟用 `channels.zalouser.dangerouslyAllowNameMatching: true` 時，才會將 allowlist 中的群組/使用者名稱解析為 ID 並記錄對應關係。
+- 群組 allowlist 比對預設只使用 ID。未解析的名稱會被忽略，不會用於授權，除非啟用 `channels.zalouser.dangerouslyAllowNameMatching: true`。
+- `channels.zalouser.dangerouslyAllowNameMatching: true` 是緊急相容模式，會重新啟用可變的啟動名稱解析與執行階段群組名稱比對。
+- 如果未設定 `groupAllowFrom`，執行階段會回退使用 `allowFrom` 進行群組傳送者檢查。
+- 傳送者檢查同時適用於一般群組訊息和控制命令（例如 `/new`）。

 範例：

@ -130,12 +130,12 @@ openclaw directory groups list --channel zalouser --query "work"
 ### 群組提及閘控

 - `channels.zalouser.groups.<group>.requireMention` 控制群組回覆是否需要提及。
- 解析順序：精確群組 id/名稱 -> 正規化群組 slug -> `*` -> 預設（`true`）。
- 這同時套用於允許清單群組與開放群組模式。
- 引用 bot 訊息會視為群組啟用的隱含提及。
+- 解析順序：精確群組 id/name -> 正規化群組 slug -> `*` -> 預設值（`true`）。
+- 這同時適用於 allowlist 群組和開放群組模式。
+- 引用 bot 訊息會算作群組啟用的隱含提及。
 - 已授權的控制命令（例如 `/new`）可以略過提及閘控。
- 當群組訊息因需要提及而被略過時，OpenClaw 會將其儲存為待處理群組歷史，並在下一則已處理群組訊息中包含它。
- 群組歷史限制預設為 `messages.groupChat.historyLimit`（fallback `50`）。你可以用 `channels.zalouser.historyLimit` 針對每個帳號覆寫。
+- 當群組訊息因需要提及而被略過時，OpenClaw 會將其儲存為待處理的群組歷史，並在下一則已處理的群組訊息中包含它。
+- 群組歷史限制預設為 `messages.groupChat.historyLimit`（後備值 `50`）。你可以使用 `channels.zalouser.historyLimit` 為每個帳號覆寫。

 範例：

@ -155,7 +155,7 @@ openclaw directory groups list --channel zalouser --query "work"

 ## 多帳號

-帳號會對應到 OpenClaw state 中的 `zalouser` profile。範例：
+帳號會對應到 OpenClaw 狀態中的 `zalouser` profile。範例：

 ```json5
 {
@ -171,34 +171,34 @@ openclaw directory groups list --channel zalouser --query "work"
 }
 ```

-## 輸入中、反應與送達確認
+## 輸入中、回應和送達確認

- OpenClaw 會在派送回覆前傳送輸入中事件（best-effort）。
- channel actions 中，`zalouser` 支援訊息反應 action `react`。
-  - 使用 `remove: true` 從訊息移除特定反應 emoji。
-  - 反應語意：[反應](/zh-TW/tools/reactions)
- 對於包含事件 metadata 的傳入訊息，OpenClaw 會傳送 delivered + seen acknowledgements（best-effort）。
+- OpenClaw 會在分派回覆前傳送輸入中事件（盡力而為）。
+- 頻道動作中，`zalouser` 支援訊息回應動作 `react`。
+  - 使用 `remove: true` 從訊息中移除特定回應 emoji。
+  - 回應語意：[Reactions](/zh-TW/tools/reactions)
+- 對於包含事件中繼資料的傳入訊息，OpenClaw 會傳送已送達 + 已讀確認（盡力而為）。

 ## 疑難排解

-**登入沒有保留：**
+**登入無法保留：**

 - `openclaw channels status --probe`
 - 重新登入：`openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`

-**允許清單/群組名稱未解析：**
+**Allowlist/群組名稱未解析：**

- 在 `allowFrom`/`groupAllowFrom`/`groups` 中使用數字 ID，或使用精確的好友/群組名稱。
+- 在 `allowFrom`/`groupAllowFrom` 中使用數字 ID，並在 `groups` 中使用穩定的群組 ID。如果你刻意需要精確好友/群組名稱，請啟用 `channels.zalouser.dangerouslyAllowNameMatching: true`。

 **從舊的 CLI 型設定升級：**

 - 移除任何舊的外部 `zca` 程序假設。
- 此 channel 現在完全在 OpenClaw 中執行，不需要外部 CLI 二進位檔。
+- 此頻道現在完全在 OpenClaw 中執行，不需要外部 CLI 二進位檔。

 ## 相關

- [Channels 概觀](/zh-TW/channels) — 所有支援的 channel
- [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
- [群組](/zh-TW/channels/groups) — 群組聊天行為與提及閘控
- [Channel 路由](/zh-TW/channels/channel-routing) — 訊息的 session 路由
- [安全性](/zh-TW/gateway/security) — 存取模型與強化
+- [頻道概覽](/zh-TW/channels) — 所有支援的頻道
+- [Pairing](/zh-TW/channels/pairing) — DM 驗證和配對流程
+- [Groups](/zh-TW/channels/groups) — 群組聊天行為和提及閘控
+- [Channel Routing](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
+- [Security](/zh-TW/gateway/security) — 存取模型和強化
--- a/docs/zh-TW/cli/daemon.md
+++ b/docs/zh-TW/cli/daemon.md
@ -1,14 +1,14 @@
 ---
 read_when:
-    - 你仍在腳本中使用 `openclaw daemon ...`
-    - 你需要服務生命週期命令 (install/start/stop/restart/status)
-summary: '`openclaw daemon` 的 CLI 參考資料（Gateway 服務管理的舊版別名）'
+    - 你仍然在腳本中使用 `openclaw daemon ...`
+    - 您需要服務生命週期指令（install/start/stop/restart/status）
+summary: '`openclaw daemon` 的 CLI 參考（Gateway 服務管理的舊版別名）'
 title: 常駐程式
 x-i18n:
-    generated_at: "2026-05-02T22:17:27Z"
+    generated_at: "2026-05-04T18:23:41Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512
+    source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05
    source_path: cli/daemon.md
    workflow: 16
 ---
@ -19,7 +19,7 @@ Gateway 服務管理命令的舊版別名。

 `openclaw daemon ...` 會對應到與 `openclaw gateway ...` 服務命令相同的服務控制介面。

-## 使用方式
+## 用法

 ```bash
 openclaw daemon status
@ -32,40 +32,41 @@ openclaw daemon uninstall

 ## 子命令

- `status`：顯示服務安裝狀態並探測 Gateway 健康狀態
- `install`：安裝服務（`launchd`/`systemd`/`schtasks`）
- `uninstall`：移除服務
- `start`：啟動服務
- `stop`：停止服務
- `restart`：重新啟動服務
+- `status`: 顯示服務安裝狀態並探查 Gateway 健全狀態
+- `install`: 安裝服務（`launchd`/`systemd`/`schtasks`）
+- `uninstall`: 移除服務
+- `start`: 啟動服務
+- `stop`: 停止服務
+- `restart`: 重新啟動服務

 ## 常用選項

- `status`：`--url`、`--token`、`--password`、`--timeout`、`--no-probe`、`--require-rpc`、`--deep`、`--json`
- `install`：`--port`、`--runtime <node|bun>`、`--token`、`--force`、`--json`
- `restart`：`--force`、`--wait <duration>`、`--json`
+- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- `restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
 - 生命週期（`uninstall|start|stop`）：`--json`

 注意事項：

- `status` 會在可能時解析已設定的驗證 SecretRefs 以供探測驗證使用。
- 如果必要的驗證 SecretRef 在此命令路徑中無法解析，當探測連線能力/驗證失敗時，`daemon status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析秘密來源。
- 如果探測成功，未解析的 auth-ref 警告會被抑制，以避免誤判。
- `status --deep` 會新增一次盡力而為的系統層級服務掃描。當它找到其他類似 gateway 的服務時，人類可讀輸出會列印清理提示，並警告每台機器仍然通常建議只執行一個 gateway。
- 在 Linux systemd 安裝中，`status` 的 token drift 檢查會包含 `Environment=` 和 `EnvironmentFile=` 兩種 unit 來源。
- Drift 檢查會使用合併後的執行時環境來解析 `gateway.auth.token` SecretRefs（先使用服務命令環境，再退回程序環境）。
- 如果 token 驗證並未實際啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或未設定 mode 且 password 可能勝出、沒有 token 候選可勝出），token drift 檢查會略過設定 token 解析。
- 當 token 驗證需要 token，且 `gateway.auth.token` 由 SecretRef 管理時，`install` 會驗證該 SecretRef 可解析，但不會將解析後的 token 持久化到服務環境中繼資料。
- 如果 token 驗證需要 token，且已設定的 token SecretRef 無法解析，安裝會以關閉狀態失敗。
- 如果同時設定了 `gateway.auth.token` 和 `gateway.auth.password`，且未設定 `gateway.auth.mode`，安裝會被阻擋，直到明確設定 mode。
- 在 macOS 上，`install` 會讓 LaunchAgent plists 僅限擁有者存取，並透過僅限擁有者存取的檔案與 wrapper 載入受管理的服務環境值，而不是將 API keys 或 auth-profile env refs 序列化到 `EnvironmentVariables`。
- 如果你有意在同一台主機上執行多個 gateways，請隔離連接埠、設定/狀態和工作區；請參閱 [/gateway#multiple-gateways-same-host](/zh-TW/gateway#multiple-gateways-same-host)。
+- `status` 會在可行時解析已設定的驗證 SecretRefs，以供探查驗證使用。
+- 如果此命令路徑中必要的驗證 SecretRef 無法解析，當探查連線能力或驗證失敗時，`daemon status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析祕密來源。
+- 如果探查成功，未解析的 auth-ref 警告會被抑制，以避免誤判。
+- `status --deep` 會加入盡力而為的系統層級服務掃描。當它找到其他類似 Gateway 的服務時，人類可讀輸出會列印清理提示，並警告每台機器一個 Gateway 仍是一般建議。
+- 在 Linux systemd 安裝中，`status` 權杖漂移檢查會同時包含 `Environment=` 與 `EnvironmentFile=` 單元來源。
+- 漂移檢查會使用合併後的執行階段環境（先使用服務命令環境，再回退到程序環境）解析 `gateway.auth.token` SecretRefs。
+- 如果權杖驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可能優先、也沒有權杖候選可優先），權杖漂移檢查會略過設定權杖解析。
+- 當權杖驗證需要權杖且 `gateway.auth.token` 由 SecretRef 管理時，`install` 會驗證該 SecretRef 可解析，但不會將解析後的權杖持久化到服務環境中繼資料。
+- 如果權杖驗證需要權杖，而已設定的權杖 SecretRef 無法解析，安裝會以關閉狀態失敗。
+- 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，安裝會被阻止，直到明確設定模式為止。
+- 在 macOS 上，`install` 會讓 LaunchAgent plist 僅限擁有者存取，並透過僅限擁有者存取的檔案與包裝器載入受管理的服務環境值，而不是將 API 金鑰或 auth-profile 環境參照序列化到 `EnvironmentVariables`。
+- 如果你有意在同一部主機上執行多個 Gateway，請隔離連接埠、設定/狀態與工作區；請參閱 [/gateway#multiple-gateways-same-host](/zh-TW/gateway#multiple-gateways-same-host)。
+- `restart --safe` 會要求執行中的 Gateway 預先檢查作用中的工作，並在作用中工作清空後排程一次合併後的重新啟動。一般的 `restart` 會保留現有的服務管理器行為；`--force` 仍是立即覆寫路徑。

-## 建議使用
+## 建議

-目前的文件與範例請使用 [`openclaw gateway`](/zh-TW/cli/gateway)。
+請使用 [`openclaw gateway`](/zh-TW/cli/gateway) 取得目前文件與範例。

 ## 相關

 - [CLI 參考](/zh-TW/cli)
- [Gateway runbook](/zh-TW/gateway)
+- [Gateway 執行手冊](/zh-TW/gateway)
--- a/docs/zh-TW/cli/gateway.md
+++ b/docs/zh-TW/cli/gateway.md
@ -1,31 +1,31 @@
 ---
 read_when:
    - 從 CLI 執行 Gateway（開發或伺服器）
-    - 偵錯 Gateway 驗證、繫結模式與連線能力
+    - 偵錯 Gateway 身分驗證、繫結模式與連線能力
    - 透過 Bonjour 探索 Gateway（本機 + 廣域 DNS-SD）
 sidebarTitle: Gateway
-summary: OpenClaw Gateway CLI (`openclaw gateway`) — 執行、查詢及探索 Gateway
+summary: OpenClaw Gateway CLI (`openclaw gateway`) — 執行、查詢並探索 Gateway
 title: Gateway
 x-i18n:
-    generated_at: "2026-05-02T22:17:33Z"
+    generated_at: "2026-05-04T18:23:42Z"
    model: gpt-5.5
    provider: openai
-    source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
+    source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
    source_path: cli/gateway.md
    workflow: 16
 ---

-Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、鉤子）。此頁面的子命令位於 `openclaw gateway …` 之下。
+Gateway 是 OpenClaw 的 WebSocket 伺服器（通道、節點、工作階段、hook）。本頁中的子命令位於 `openclaw gateway …` 之下。

 <CardGroup cols={3}>
  <Card title="Bonjour 探索" href="/zh-TW/gateway/bonjour">
    本機 mDNS + 廣域 DNS-SD 設定。
  </Card>
  <Card title="探索概覽" href="/zh-TW/gateway/discovery">
-    OpenClaw 如何公告並尋找 Gateway。
+    OpenClaw 如何公布並尋找 Gateway。
  </Card>
  <Card title="組態" href="/zh-TW/gateway/configuration">
-    最上層 Gateway 組態鍵。
+    頂層 Gateway 組態鍵。
  </Card>
 </CardGroup>

@ -45,12 +45,12 @@ openclaw gateway run

 <AccordionGroup>
  <Accordion title="啟動行為">
-    - 預設情況下，除非 `~/.openclaw/openclaw.json` 中設定了 `gateway.mode=local`，否則 Gateway 會拒絕啟動。臨時/開發執行請使用 `--allow-unconfigured`。
-    - 預期 `openclaw onboard --mode local` 和 `openclaw setup` 會寫入 `gateway.mode=local`。如果檔案存在但缺少 `gateway.mode`，請將其視為損壞或被覆寫的組態並修復，而不是隱含假設為本機模式。
+    - 依預設，除非 `~/.openclaw/openclaw.json` 中設定了 `gateway.mode=local`，否則 Gateway 會拒絕啟動。針對臨時/開發執行，請使用 `--allow-unconfigured`。
+    - `openclaw onboard --mode local` 和 `openclaw setup` 預期會寫入 `gateway.mode=local`。如果檔案存在但缺少 `gateway.mode`，請將其視為損壞或被覆寫的組態並修復，而不是隱含假設為本機模式。
    - 如果檔案存在且缺少 `gateway.mode`，Gateway 會將其視為可疑的組態損壞，並拒絕替你「猜測為本機」。
-    - 未經驗證而綁定到 loopback 以外的位址會被封鎖（安全護欄）。
-    - `SIGUSR1` 會在授權時觸發程序內重新啟動（`commands.restart` 預設啟用；設定 `commands.restart: false` 可封鎖手動重新啟動，同時仍允許 Gateway 工具/組態套用/更新）。
-    - `SIGINT`/`SIGTERM` 處理常式會停止 Gateway 程序，但不會還原任何自訂終端狀態。如果你用 TUI 或 raw-mode 輸入包裝 CLI，請在結束前還原終端。
+    - 未經驗證就綁定到 loopback 以外的位置會被封鎖（安全護欄）。
+    - `SIGUSR1` 會在獲授權時觸發程序內重新啟動（`commands.restart` 預設啟用；設定 `commands.restart: false` 可封鎖手動重新啟動，同時仍允許 Gateway 工具/組態套用/更新）。
+    - `SIGINT`/`SIGTERM` 處理常式會停止 Gateway 程序，但不會還原任何自訂終端狀態。如果你用 TUI 或原始模式輸入包裝 CLI，請在結束前還原終端。

  </Accordion>
 </AccordionGroup>
@ -64,40 +64,40 @@ openclaw gateway run
  監聽器綁定模式。
 </ParamField>
 <ParamField path="--auth <token|password>" type="string">
-  覆寫驗證模式。
+  驗證模式覆寫。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  覆寫權杖（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。
+  Token 覆寫（也會為程序設定 `OPENCLAW_GATEWAY_TOKEN`）。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  覆寫密碼。
+  密碼覆寫。
 </ParamField>
 <ParamField path="--password-file <path>" type="string">
  從檔案讀取 Gateway 密碼。
 </ParamField>
 <ParamField path="--tailscale <off|serve|funnel>" type="string">
-  透過 Tailscale 公開 Gateway。
+  透過 Tailscale 暴露 Gateway。
 </ParamField>
 <ParamField path="--tailscale-reset-on-exit" type="boolean">
  關閉時重設 Tailscale serve/funnel 組態。
 </ParamField>
 <ParamField path="--allow-unconfigured" type="boolean">
-  允許在組態中沒有 `gateway.mode=local` 的情況下啟動 Gateway。僅為臨時/開發 bootstrap 略過啟動護欄；不會寫入或修復組態檔。
+  允許在組態中沒有 `gateway.mode=local` 時啟動 Gateway。僅針對臨時/開發啟動程序繞過啟動護欄；不會寫入或修復組態檔。
 </ParamField>
 <ParamField path="--dev" type="boolean">
-  若缺少則建立開發組態 + 工作區（略過 BOOTSTRAP.md）。
+  如果缺少，建立開發組態 + 工作區（略過 BOOTSTRAP.md）。
 </ParamField>
 <ParamField path="--reset" type="boolean">
  重設開發組態 + 認證 + 工作階段 + 工作區（需要 `--dev`）。
 </ParamField>
 <ParamField path="--force" type="boolean">
-  啟動前終止所選連接埠上的任何現有監聽器。
+  啟動前終止所選連接埠上的任何既有監聽器。
 </ParamField>
 <ParamField path="--verbose" type="boolean">
  詳細記錄。
 </ParamField>
 <ParamField path="--cli-backend-logs" type="boolean">
-  只在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。
+  僅在主控台顯示 CLI 後端記錄（並啟用 stdout/stderr）。
 </ParamField>
 <ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
  WebSocket 記錄樣式。
@ -112,15 +112,25 @@ openclaw gateway run
  原始串流 jsonl 路徑。
 </ParamField>

+## 重新啟動 Gateway
+
+```bash
+openclaw gateway restart
+openclaw gateway restart --safe
+openclaw gateway restart --force
+```
+
+`openclaw gateway restart --safe` 會要求執行中的 Gateway 在重新啟動前預檢作用中的 OpenClaw 工作。如果佇列作業、回覆遞送、嵌入式執行或任務執行仍在作用中，Gateway 會回報阻礙項目，合併重複的安全重新啟動請求，並在作用中工作清空後重新啟動。純 `restart` 會保留既有的服務管理員行為以維持相容性。只有在你明確想要立即覆寫路徑時才使用 `--force`。
+
 <Warning>
-內嵌 `--password` 可能會在本機程序清單中暴露。建議使用 `--password-file`、環境變數，或由 SecretRef 支援的 `gateway.auth.password`。
+行內 `--password` 可能會暴露在本機程序清單中。請優先使用 `--password-file`、環境變數，或由 SecretRef 支援的 `gateway.auth.password`。
 </Warning>

-### 啟動效能分析
+### 啟動效能剖析

- 設定 `OPENCLAW_GATEWAY_STARTUP_TRACE=1`，在 Gateway 啟動期間記錄各階段耗時，包括每階段的 `eventLoopMax` 延遲，以及 installed-index、manifest registry、startup planning 和 owner-map 工作的 Plugin 查詢表耗時。
- 設定 `OPENCLAW_DIAGNOSTICS=timeline` 並搭配 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，為外部 QA harness 寫入 best-effort JSONL 啟動診斷時間軸。你也可以在組態中用 `diagnostics.flags: ["timeline"]` 啟用此旗標；路徑仍由環境提供。加入 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件迴圈樣本。
- 執行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 來基準測試 Gateway 啟動。此基準測試會記錄第一個程序輸出、`/healthz`、`/readyz`、啟動 trace 耗時、事件迴圈延遲，以及 Plugin 查詢表耗時細節。
+- 設定 `OPENCLAW_GATEWAY_STARTUP_TRACE=1`，可在 Gateway 啟動期間記錄各階段耗時，包括每階段的 `eventLoopMax` 延遲，以及已安裝索引、manifest 登錄、啟動規劃和 owner-map 工作的 Plugin 查找表耗時。
+- 設定 `OPENCLAW_DIAGNOSTICS=timeline` 搭配 `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`，可為外部 QA 測試架構寫入盡力而為的 JSONL 啟動診斷時間軸。你也可以在組態中使用 `diagnostics.flags: ["timeline"]` 啟用此旗標；路徑仍由環境提供。加入 `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` 可包含事件迴圈樣本。
+- 執行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 來基準測試 Gateway 啟動。此基準測試會記錄第一個程序輸出、`/healthz`、`/readyz`、啟動追蹤耗時、事件迴圈延遲，以及 Plugin 查找表耗時細節。

 ## 查詢執行中的 Gateway

@ -128,14 +138,14 @@ openclaw gateway run

 <Tabs>
  <Tab title="輸出模式">
-    - 預設：人類可讀（在 TTY 中著色）。
-    - `--json`：機器可讀 JSON（無樣式/spinner）。
-    - `--no-color`（或 `NO_COLOR=1`）：保留人類版面配置但停用 ANSI。
+    - 預設：人類可讀（TTY 中會有色彩）。
+    - `--json`：機器可讀 JSON（無樣式/旋轉指示器）。
+    - `--no-color`（或 `NO_COLOR=1`）：停用 ANSI，同時保留人類可讀版面。

  </Tab>
  <Tab title="共用選項">
    - `--url <url>`：Gateway WebSocket URL。
-    - `--token <token>`：Gateway 權杖。
+    - `--token <token>`：Gateway token。
    - `--password <password>`：Gateway 密碼。
    - `--timeout <ms>`：逾時/預算（依命令而異）。
    - `--expect-final`：等待「final」回應（agent 呼叫）。
@ -144,7 +154,7 @@ openclaw gateway run
 </Tabs>

 <Note>
-設定 `--url` 時，CLI 不會退回使用組態或環境認證。請明確傳入 `--token` 或 `--password`。缺少明確認證會造成錯誤。
+當你設定 `--url` 時，CLI 不會回退使用組態或環境認證。請明確傳入 `--token` 或 `--password`。缺少明確認證是一項錯誤。
 </Note>

 ### `gateway health`
@ -153,7 +163,7 @@ openclaw gateway run
 openclaw gateway health --url ws://127.0.0.1:18789
 ```

-HTTP `/healthz` 端點是存活探測：伺服器能回應 HTTP 後即會返回。HTTP `/readyz` 端點更嚴格，當啟動中的 Plugin sidecar、通道或已設定的鉤子仍在穩定時會維持紅燈。本機或已驗證的詳細就緒回應會包含 `eventLoop` 診斷區塊，其中有事件迴圈延遲、事件迴圈使用率、CPU 核心比例，以及 `degraded` 旗標。
+HTTP `/healthz` 端點是存活探針：伺服器能回應 HTTP 時就會回傳。HTTP `/readyz` 端點更嚴格，會在啟動中的 Plugin sidecar、通道或已設定 hook 仍在穩定時維持紅燈。本機或已驗證的詳細就緒回應包含 `eventLoop` 診斷區塊，其中有事件迴圈延遲、事件迴圈使用率、CPU 核心比例，以及 `degraded` 旗標。

 ### `gateway usage-cost`

@ -182,16 +192,16 @@ openclaw gateway stability --json
 ```

 <ParamField path="--limit <limit>" type="number" default="25">
-  要包含的近期事件最大數量（最大 `1000`）。
+  要包含的近期事件數上限（最大 `1000`）。
 </ParamField>
 <ParamField path="--type <type>" type="string">
  依診斷事件類型篩選，例如 `payload.large` 或 `diagnostic.memory.pressure`。
 </ParamField>
 <ParamField path="--since-seq <seq>" type="number">
-  只包含診斷序號之後的事件。
+  僅包含診斷序號之後的事件。
 </ParamField>
 <ParamField path="--bundle [path]" type="string">
-  讀取持久化的穩定性 bundle，而不是呼叫執行中的 Gateway。使用 `--bundle latest`（或只用 `--bundle`）讀取狀態目錄下最新的 bundle，或直接傳入 bundle JSON 路徑。
+  讀取持久化的穩定性套件，而不是呼叫執行中的 Gateway。針對狀態目錄下最新的套件，請使用 `--bundle latest`（或只用 `--bundle`），或直接傳入套件 JSON 路徑。
 </ParamField>
 <ParamField path="--export" type="boolean">
  寫入可分享的支援診斷 zip，而不是列印穩定性細節。
@ -201,16 +211,16 @@ openclaw gateway stability --json
 </ParamField>

 <AccordionGroup>
-  <Accordion title="隱私與 bundle 行為">
-    - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已遮蔽的工作階段摘要。它們不會保留聊天文字、Webhook 內文、工具輸出、原始請求或回應內文、權杖、Cookie、祕密值、主機名稱，或原始工作階段 ID。設定 `diagnostics.enabled: false` 可完全停用記錄器。
-    - 在 Gateway 發生致命結束、關閉逾時，以及重新啟動時的啟動失敗時，若記錄器有事件，OpenClaw 會將相同的診斷快照寫入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 檢查最新的 bundle；`--limit`、`--type` 和 `--since-seq` 也適用於 bundle 輸出。
+  <Accordion title="隱私與套件行為">
+    - 記錄會保留操作中繼資料：事件名稱、計數、位元組大小、記憶體讀數、佇列/工作階段狀態、通道/Plugin 名稱，以及已遮蔽的工作階段摘要。它們不會保留聊天文字、webhook 主體、工具輸出、原始請求或回應主體、token、cookie、秘密值、主機名稱，或原始工作階段 ID。設定 `diagnostics.enabled: false` 可完全停用記錄器。
+    - 在 Gateway 致命結束、關閉逾時和重新啟動啟動失敗時，若記錄器有事件，OpenClaw 會將相同的診斷快照寫入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。用 `openclaw gateway stability --bundle latest` 檢查最新套件；`--limit`、`--type` 和 `--since-seq` 也適用於套件輸出。

  </Accordion>
 </AccordionGroup>

 ### `gateway diagnostics export`

-寫入本機診斷 zip，設計用於附加到錯誤報告。隱私模型與 bundle 內容請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。
+寫入本機診斷 zip，設計用於附加到錯誤回報。關於隱私模型與套件內容，請參閱[診斷匯出](/zh-TW/gateway/diagnostics)。

 ```bash
 openclaw gateway diagnostics export
@ -228,31 +238,31 @@ openclaw gateway diagnostics export --json
  要檢查的記錄位元組數上限。
 </ParamField>
 <ParamField path="--url <url>" type="string">
-  健康快照的 Gateway WebSocket URL。
+  用於健康快照的 Gateway WebSocket URL。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  健康快照的 Gateway 權杖。
+  用於健康快照的 Gateway token。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  健康快照的 Gateway 密碼。
+  用於健康快照的 Gateway 密碼。
 </ParamField>
 <ParamField path="--timeout <ms>" type="number" default="3000">
  狀態/健康快照逾時。
 </ParamField>
 <ParamField path="--no-stability-bundle" type="boolean">
-  略過持久化穩定性 bundle 查詢。
+  略過持久化穩定性套件查找。
 </ParamField>
 <ParamField path="--json" type="boolean">
-  以 JSON 列印寫入路徑、大小和 manifest。
+  以 JSON 列印寫入的路徑、大小和 manifest。
 </ParamField>

-匯出內容包含 manifest、Markdown 摘要、組態形狀、已清理的組態細節、已清理的記錄摘要、已清理的 Gateway 狀態/健康快照，以及存在時最新的穩定性 bundle。
+匯出內容包含 manifest、Markdown 摘要、組態形狀、已清理的組態細節、已清理的記錄摘要、已清理的 Gateway 狀態/健康快照，以及最新的穩定性套件（若存在）。

-它是為分享而設計。它會保留有助於除錯的操作細節，例如安全的 OpenClaw 記錄欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、Plugin ID、提供者 ID、非祕密功能設定，以及已遮蔽的操作記錄訊息。它會省略或遮蔽聊天文字、Webhook 內文、工具輸出、認證、Cookie、帳號/訊息識別碼、提示/指令文字、主機名稱，以及祕密值。當 LogTape 風格訊息看起來像使用者/聊天/工具 payload 文字時，匯出只會保留有訊息被省略，以及其位元組數。
+這是用來分享的。它會保留有助於偵錯的操作細節，例如安全的 OpenClaw 記錄欄位、子系統名稱、狀態碼、持續時間、已設定模式、連接埠、Plugin ID、provider ID、非秘密功能設定，以及已遮蔽的操作記錄訊息。它會省略或遮蔽聊天文字、webhook 主體、工具輸出、認證、cookie、帳號/訊息識別碼、提示/指示文字、主機名稱和秘密值。當 LogTape 風格訊息看起來像使用者/聊天/工具 payload 文字時，匯出只會保留該訊息已被省略，以及其位元組數。

 ### `gateway status`

-`gateway status` 會顯示 Gateway 服務（launchd/systemd/schtasks），外加可選的連線能力/驗證能力探測。
+`gateway status` 會顯示 Gateway 服務（launchd/systemd/schtasks），並加上選用的連線能力/驗證能力探測。

 ```bash
 openclaw gateway status
@ -261,63 +271,63 @@ openclaw gateway status --require-rpc
 ```

 <ParamField path="--url <url>" type="string">
-  加入明確的探測目標。仍會探測已設定的遠端 + localhost。
+  新增明確的探測目標。已設定的遠端與 localhost 仍會被探測。
 </ParamField>
 <ParamField path="--token <token>" type="string">
-  探測的權杖驗證。
+  探測使用的 Token 驗證。
 </ParamField>
 <ParamField path="--password <password>" type="string">
-  探測的密碼驗證。
+  探測使用的密碼驗證。
 </ParamField>
 <ParamField path="--timeout <ms>" type="number" default="10000">
  探測逾時。
 </ParamField>
 <ParamField path="--no-probe" type="boolean">
-  略過連線能力探測（僅服務檢視）。
+  跳過連線能力探測（僅服務檢視）。
 </ParamField>
 <ParamField path="--deep" type="boolean">
  也掃描系統層級服務。
 </ParamField>
 <ParamField path="--require-rpc" type="boolean">
-  將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零代碼結束。不能與 `--no-probe` 搭配使用。
+  將預設連線能力探測升級為讀取探測，並在該讀取探測失敗時以非零狀態結束。不可與 `--no-probe` 搭配使用。
 </ParamField>

 <AccordionGroup>
  <Accordion title="狀態語意">
-    - `gateway status` 即使在本機 CLI 設定缺失或無效時，仍可用於診斷。
-    - 預設的 `gateway status` 會驗證服務狀態、WebSocket 連線，以及握手時可見的驗證能力。它不會驗證讀取/寫入/管理操作。
-    - 對首次裝置驗證而言，診斷探測不會變更狀態：如果已有快取的裝置 Token，會重用它，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
-    - `gateway status` 會在可行時解析已設定的驗證 SecretRefs，以用於探測驗證。
-    - 如果此命令路徑中所需的驗證 SecretRef 無法解析，當探測連線/驗證失敗時，`gateway status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析 Secret 來源。
-    - 如果探測成功，未解析的驗證參照警告會被抑制，以避免誤報。
-    - 當只知道服務正在監聽還不夠，而你也需要讀取範圍的 RPC 呼叫保持健康時，請在指令碼和自動化中使用 `--require-rpc`。
-    - `--deep` 會加入盡力掃描額外的 launchd/systemd/schtasks 安裝。偵測到多個類 Gateway 服務時，人類可讀輸出會列印清理提示，並警告多數設定應該每台機器只執行一個 Gateway。
-    - 人類可讀輸出包含解析後的檔案記錄路徑，以及 CLI 與服務設定路徑/有效性的快照，協助診斷設定檔或狀態目錄漂移。
+    - 即使本機 CLI 設定缺失或無效，`gateway status` 仍可用於診斷。
+    - 預設的 `gateway status` 會證明服務狀態、WebSocket 連線，以及握手時可見的驗證能力。它不會證明讀取／寫入／管理操作。
+    - 診斷探測對首次裝置驗證不會造成變更：若既有快取裝置 Token 存在，會重複使用它，但不會只為了檢查狀態而建立新的 CLI 裝置身分或唯讀裝置配對記錄。
+    - `gateway status` 會在可能時解析已設定的驗證 SecretRefs，以供探測驗證使用。
+    - 如果此命令路徑中必要的驗證 SecretRef 未解析，當探測連線能力／驗證失敗時，`gateway status --json` 會回報 `rpc.authWarning`；請明確傳入 `--token`/`--password`，或先解析祕密來源。
+    - 如果探測成功，未解析驗證參照警告會被抑制，以避免誤報。
+    - 當僅有監聽中的服務仍不足夠，且你還需要讀取範圍 RPC 呼叫也保持健康時，請在指令碼與自動化中使用 `--require-rpc`。
+    - `--deep` 會加入對額外 launchd/systemd/schtasks 安裝的盡力掃描。偵測到多個類 Gateway 服務時，人類可讀輸出會列印清理提示，並警告大多數設定應該每台機器只執行一個 Gateway。
+    - 人類可讀輸出包含已解析的檔案日誌路徑，以及 CLI 與服務設定路徑／有效性快照，以協助診斷設定檔或狀態目錄偏移。

  </Accordion>
-  <Accordion title="Linux systemd 驗證漂移檢查">
-    - 在 Linux systemd 安裝上，服務驗證漂移檢查會從 unit 讀取 `Environment=` 和 `EnvironmentFile=` 值（包含 `%h`、加引號的路徑、多個檔案，以及選用的 `-` 檔案）。
-    - 漂移檢查會使用合併後的執行階段環境解析 `gateway.auth.token` SecretRefs（先使用服務命令環境，再回退到程序環境）。
-    - 如果 Token 驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可勝出、沒有 Token 候選可勝出），Token 漂移檢查會略過設定 Token 解析。
+  <Accordion title="Linux systemd 驗證偏移檢查">
+    - 在 Linux systemd 安裝中，服務驗證偏移檢查會從 unit 讀取 `Environment=` 與 `EnvironmentFile=` 值（包括 `%h`、加引號的路徑、多個檔案，以及選用的 `-` 檔案）。
+    - 偏移檢查會使用合併後的執行階段環境解析 `gateway.auth.token` SecretRefs（先使用服務命令環境，再回退到處理程序環境）。
+    - 如果 Token 驗證實際上未啟用（明確的 `gateway.auth.mode` 為 `password`/`none`/`trusted-proxy`，或模式未設定且密碼可能優先、且沒有 Token 候選可優先），Token 偏移檢查會跳過設定 Token 解析。

  </Accordion>
 </AccordionGroup>

 ### `gateway probe`

-`gateway probe` 是「除錯一切」命令。它一律會探測：
+`gateway probe` 是「偵錯一切」命令。它一律會探測：

- 你設定的遠端 Gateway（如果已設定），以及
- localhost (loopback) **即使已設定遠端**。
+- 你已設定的遠端 Gateway（如果已設定），以及
+- localhost（loopback），**即使已設定遠端**。

-如果你傳入 `--url`，該明確目標會加在兩者之前。人類可讀輸出會將目標標示為：
+如果你傳入 `--url`，該明確目標會被加入兩者之前。人類可讀輸出會將目標標示為：

 - `URL (explicit)`
 - `Remote (configured)` 或 `Remote (configured, inactive)`
 - `Local loopback`

 <Note>
-如果多個 Gateway 可連線，它會全部列印出來。當你使用隔離的設定檔/連接埠時（例如救援 Bot），支援多個 Gateway，但大多數安裝仍只執行單一 Gateway。
+如果可連線到多個 Gateway，它會全部列印出來。當你使用隔離的設定檔／連接埠時（例如救援 bot），支援多個 Gateway，但大多數安裝仍只執行單一 Gateway。
 </Note>

 ```bash
@ -327,51 +337,51 @@ openclaw gateway probe --json

 <AccordionGroup>
  <Accordion title="解讀">
-    - `Reachable: yes` 表示至少有一個目標接受了 WebSocket 連線。
-    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 會回報探測能驗證的驗證能力。它與可連線性是分開的。
-    - `Read probe: ok` 表示讀取範圍的詳細 RPC 呼叫（`health`/`status`/`system-presence`/`config.get`）也已成功。
-    - `Read probe: limited - missing scope: operator.read` 表示連線成功，但讀取範圍 RPC 受限。這會回報為**降級**可連線性，而不是完全失敗。
-    - `Connect: ok` 之後出現 `Read probe: failed` 表示 Gateway 已接受 WebSocket 連線，但後續讀取診斷逾時或失敗。這也是**降級**可連線性，而不是無法連線的 Gateway。
-    - 如同 `gateway status`，probe 會重用既有的快取裝置驗證，但不會建立首次裝置身分或配對狀態。
-    - 只有在沒有任何探測目標可連線時，結束代碼才會是非零。
+    - `Reachable: yes` 表示至少一個目標接受了 WebSocket 連線。
+    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 會回報探測能夠證明的驗證能力。這與可達性是分開的。
+    - `Read probe: ok` 表示讀取範圍詳細 RPC 呼叫（`health`/`status`/`system-presence`/`config.get`）也成功。
+    - `Read probe: limited - missing scope: operator.read` 表示連線成功，但讀取範圍 RPC 受限。這會回報為**降級**可達性，而不是完全失敗。
+    - `Read probe: failed` 在 `Connect: ok` 之後出現，表示 Gateway 接受了 WebSocket 連線，但後續讀取診斷逾時或失敗。這同樣是**降級**可達性，不是無法到達 Gateway。
+    - 與 `gateway status` 一樣，探測會重複使用既有快取裝置驗證，但不會建立首次裝置身分或配對狀態。
+    - 只有在沒有任何被探測的目標可達時，結束碼才會是非零。

  </Accordion>
  <Accordion title="JSON 輸出">
    頂層：

-    - `ok`：至少有一個目標可連線。
-    - `degraded`：至少有一個目標接受了連線，但未完成完整詳細 RPC 診斷。
-    - `capability`：在可連線目標中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
-    - `primaryTargetId`：依此順序視為作用中勝出者的最佳目標：明確 URL、SSH tunnel、已設定遠端，然後是 local loopback。
-    - `warnings[]`：盡力提供的警告記錄，包含 `code`、`message`，以及選用的 `targetIds`。
-    - `network`：從目前設定與主機網路推導出的 local loopback/tailnet URL 提示。
-    - `discovery.timeoutMs` 和 `discovery.count`：此探測回合使用的實際探索預算/結果數量。
+    - `ok`：至少一個目標可達。
+    - `degraded`：至少一個目標接受了連線，但未完成完整的詳細 RPC 診斷。
+    - `capability`：在可達目標中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
+    - `primaryTargetId`：依此順序視為作用中勝出者的最佳目標：明確 URL、SSH tunnel、已設定的遠端，然後是 local loopback。
+    - `warnings[]`：盡力提供的警告記錄，含 `code`、`message`，以及選用的 `targetIds`。
+    - `network`：從目前設定與主機網路衍生出的 local loopback/tailnet URL 提示。
+    - `discovery.timeoutMs` 與 `discovery.count`：此探測回合實際使用的探索預算／結果數。

    每個目標（`targets[].connect`）：

-    - `ok`：連線後的可連線性 + 降級分類。
+    - `ok`：連線加上降級分類後的可達性。
    - `rpcOk`：完整詳細 RPC 成功。
    - `scopeLimited`：詳細 RPC 因缺少 operator 範圍而失敗。

    每個目標（`targets[].auth`）：

-    - `role`：可用時，`hello-ok` 中回報的驗證角色。
-    - `scopes`：可用時，`hello-ok` 中回報的已授予範圍。
-    - `capability`：該目標呈現的驗證能力分類。
+    - `role`：可用時，在 `hello-ok` 中回報的驗證角色。
+    - `scopes`：可用時，在 `hello-ok` 中回報的已授予範圍。
+    - `capability`：該目標顯示的驗證能力分類。

  </Accordion>
  <Accordion title="常見警告代碼">
    - `ssh_tunnel_failed`：SSH tunnel 設定失敗；命令已回退到直接探測。
-    - `multiple_gateways`：有超過一個目標可連線；除非你刻意執行隔離設定檔，例如救援 Bot，否則這並不尋常。
-    - `auth_secretref_unresolved`：無法為失敗的目標解析已設定的驗證 SecretRef。
+    - `multiple_gateways`：有多個目標可達；除非你有意執行隔離設定檔，例如救援 bot，否則這並不常見。
+    - `auth_secretref_unresolved`：已設定的驗證 SecretRef 無法為失敗目標解析。
    - `probe_scope_limited`：WebSocket 連線成功，但讀取探測因缺少 `operator.read` 而受限。

  </Accordion>
 </AccordionGroup>

-#### 透過 SSH 的遠端連線（Mac 應用程式一致性）
+#### 透過 SSH 遠端連線（Mac app parity）

-macOS 應用程式的「透過 SSH 的遠端」模式使用本機連接埠轉送，因此遠端 Gateway（可能只綁定到 loopback）可在 `ws://127.0.0.1:<port>` 連線。
+macOS app 的「Remote over SSH」模式使用本機連接埠轉送，因此遠端 Gateway（可能只繫結到 loopback）可在 `ws://127.0.0.1:<port>` 連線。

 CLI 等效命令：

@ -386,10 +396,10 @@ openclaw gateway probe --ssh user@gateway-host
  身分檔案。
 </ParamField>
 <ParamField path="--ssh-auto" type="boolean">
-  從解析後的探索端點（`local.` 加上已設定的廣域網域，如有）選擇第一個探索到的 Gateway 主機作為 SSH 目標。會忽略僅 TXT 的提示。
+  從已解析的探索端點（`local.` 加上已設定的廣域網域，如有）選擇第一個探索到的 Gateway 主機作為 SSH 目標。純 TXT 提示會被忽略。
 </ParamField>

-設定（選用，作為預設值使用）：
+設定（選用，用作預設值）：

 - `gateway.remote.sshTarget`
 - `gateway.remote.sshIdentity`
@ -404,7 +414,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
 ```

 <ParamField path="--params <json>" type="string" default="{}">
-  params 的 JSON 物件字串。
+  參數用的 JSON 物件字串。
 </ParamField>
 <ParamField path="--url <url>" type="string">
  Gateway WebSocket URL。
@ -419,7 +429,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
  逾時預算。
 </ParamField>
 <ParamField path="--expect-final" type="boolean">
-  主要用於會在最終承載之前串流中間事件的代理風格 RPC。
+  主要用於 agent 樣式的 RPC，這類 RPC 會在最終 payload 前串流中繼事件。
 </ParamField>
 <ParamField path="--json" type="boolean">
  機器可讀 JSON 輸出。
@ -441,7 +451,9 @@ openclaw gateway uninstall

 ### 使用 wrapper 安裝

-當受管理服務必須透過另一個可執行檔啟動時，例如 Secret 管理器 shim 或 run-as 輔助工具，請使用 `--wrapper`。wrapper 會接收一般 Gateway 參數，並負責最後 exec `openclaw` 或帶有這些參數的 Node。
+當受管理服務必須透過另一個可執行檔啟動時，請使用 `--wrapper`，例如
+secrets manager shim 或 run-as helper。wrapper 會接收一般 Gateway 引數，並
+負責最終以這些引數 exec `openclaw` 或 Node。

 ```bash
 cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -455,14 +467,17 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
 openclaw gateway restart
 ```

-你也可以透過環境設定 wrapper。`gateway install` 會驗證路徑是可執行檔，將 wrapper 寫入服務 `ProgramArguments`，並在服務環境中保留 `OPENCLAW_WRAPPER`，以供後續強制重新安裝、更新和 doctor 修復使用。
+你也可以透過環境設定 wrapper。`gateway install` 會驗證該路徑是
+可執行檔，將 wrapper 寫入服務 `ProgramArguments`，並在服務環境中保存
+`OPENCLAW_WRAPPER`，供日後強制重新安裝、更新與 doctor
+修復使用。

 ```bash
 OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
 openclaw doctor
 ```

-若要移除已保留的 wrapper，請在重新安裝時清除 `OPENCLAW_WRAPPER`：
+若要移除已保存的 wrapper，請在重新安裝時清除 `OPENCLAW_WRAPPER`：

 ```bash
 OPENCLAW_WRAPPER= openclaw gateway install --force
@ -478,18 +493,18 @@ openclaw gateway restart

  </Accordion>
  <Accordion title="生命週期行為">
-    - 使用 `gateway restart` 重新啟動受管理服務。不要串接 `gateway stop` 和 `gateway start` 來代替重新啟動；在 macOS 上，`gateway stop` 會刻意先停用 LaunchAgent 再停止它。
-    - `gateway restart --wait 30s` 會覆寫該次重新啟動的已設定重啟排空預算。裸數字為毫秒；也接受 `s`、`m` 和 `h` 等單位。`--wait 0` 會無限期等待。
-    - `gateway restart --force` 會略過作用中工作排空並立即重新啟動。當操作員已檢查列出的任務阻擋項，並希望 Gateway 立即恢復時使用。
+    - 使用 `gateway restart` 重新啟動受管理服務。不要將 `gateway stop` 與 `gateway start` 串接作為重新啟動的替代方式；在 macOS 上，`gateway stop` 會在停止 LaunchAgent 前刻意停用它。
+    - `gateway restart --wait 30s` 會覆寫此次重新啟動設定的重啟排空預算。裸數字為毫秒；接受 `s`、`m`、`h` 等單位。`--wait 0` 會無限期等待。
+    - `gateway restart --force` 會跳過作用中工作排空並立即重新啟動。當操作員已檢查列出的任務阻擋項，且希望 Gateway 立即恢復時使用。
    - 生命週期命令接受 `--json` 以供指令碼使用。

  </Accordion>
  <Accordion title="安裝時的驗證與 SecretRefs">
-    - 當 Token 驗證需要 Token，且 `gateway.auth.token` 由 SecretRef 管理時，`gateway install` 會驗證 SecretRef 可解析，但不會將解析後的 Token 保留到服務環境中繼資料。
-    - 如果 Token 驗證需要 Token，而設定的 Token SecretRef 無法解析，安裝會封閉失敗，而不是保留回退明文。
-    - 對 `gateway run` 的密碼驗證，優先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或以 SecretRef 支援的 `gateway.auth.password`，而不是行內 `--password`。
-    - 在推斷驗證模式下，僅存在於 shell 的 `OPENCLAW_GATEWAY_PASSWORD` 不會放寬安裝 Token 要求；安裝受管理服務時請使用持久設定（`gateway.auth.password` 或設定 `env`）。
-    - 如果同時設定 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，安裝會被阻擋，直到明確設定模式。
+    - 當 Token 驗證需要 Token，且 `gateway.auth.token` 由 SecretRef 管理時，`gateway install` 會驗證 SecretRef 可解析，但不會將已解析 Token 保存到服務環境中繼資料。
+    - 如果 Token 驗證需要 Token，且已設定的 Token SecretRef 未解析，安裝會以失敗關閉，而不是保存回退純文字。
+    - 對 `gateway run` 的密碼驗證，優先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支援的 `gateway.auth.password`，而不是內嵌 `--password`。
+    - 在推斷驗證模式中，僅 shell 的 `OPENCLAW_GATEWAY_PASSWORD` 不會放寬安裝 Token 要求；安裝受管理服務時，請使用持久設定（`gateway.auth.password` 或設定 `env`）。
+    - 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，安裝會被封鎖，直到明確設定模式。

  </Accordion>
 </AccordionGroup>
@ -498,19 +513,19 @@ openclaw gateway restart

 `gateway discover` 會掃描 Gateway beacon（`_openclaw-gw._tcp`）。

- Multicast DNS-SD：`local.`
- Unicast DNS-SD（Wide-Area Bonjour）：選擇一個網域（例如：`openclaw.internal.`）並設定 split DNS + DNS 伺服器；請參閱 [Bonjour](/zh-TW/gateway/bonjour)。
+- 多點傳播 DNS-SD：`local.`
+- 單點傳播 DNS-SD（Wide-Area Bonjour）：選擇一個網域（例如：`openclaw.internal.`）並設定分割 DNS + DNS 伺服器；請參閱 [Bonjour](/zh-TW/gateway/bonjour)。

-只有啟用 Bonjour 探索（預設）的 Gateway 會公告 beacon。
+只有啟用 Bonjour 探索功能的 Gateway（預設）會公告信標。

-Wide-Area 探索記錄包含（TXT）：
+廣域探索記錄包含（TXT）：

 - `role`（Gateway 角色提示）
 - `transport`（傳輸提示，例如 `gateway`）
- `gatewayPort`（WebSocket 連接埠，通常為 `18789`）
- `sshPort`（選用；缺少時用戶端預設 SSH 目標為 `22`）
+- `gatewayPort`（WebSocket 連接埠，通常是 `18789`）
+- `sshPort`（選用；不存在時用戶端預設 SSH 目標為 `22`）
 - `tailnetDns`（MagicDNS 主機名稱，可用時）
- `gatewayTls` / `gatewayTlsSha256`（TLS 已啟用 + 憑證指紋）
+- `gatewayTls` / `gatewayTlsSha256`（已啟用 TLS + 憑證指紋）
 - `cliPath`（寫入廣域區域的遠端安裝提示）

 ### `gateway discover`
@ -520,7 +535,7 @@ openclaw gateway discover
 ```

 <ParamField path="--timeout <ms>" type="number" default="2000">
-  每個命令的逾時（browse/resolve）。
+  每個命令的逾時時間（瀏覽/解析）。
 </ParamField>
 <ParamField path="--json" type="boolean">
  機器可讀輸出（也會停用樣式/旋轉指示器）。
@ -534,8 +549,8 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
 ```

 <Note>
- CLI 會掃描 `local.` 加上已啟用時所設定的廣域網域。
- JSON 輸出中的 `wsUrl` 來自解析後的服務端點，而不是僅 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
+- 啟用廣域網域時，CLI 會掃描 `local.` 加上已設定的廣域網域。
+- JSON 輸出中的 `wsUrl` 是從已解析的服務端點衍生而來，而不是來自僅限 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
 - 在 `local.` mDNS 上，只有當 `discovery.mdns.mode` 為 `full` 時，才會廣播 `sshPort` 和 `cliPath`。廣域 DNS-SD 仍會寫入 `cliPath`；`sshPort` 在那裡也維持選用。

 </Note>
--- a/docs/zh-TW/cli/models.md
+++ b/docs/zh-TW/cli/models.md
@ -1,29 +1,29 @@
 ---
 read_when:
-    - 你想變更預設模型或檢視提供者驗證狀態
-    - 您想掃描可用的模型/提供者並偵錯驗證設定檔
-summary: '`openclaw models` 的 CLI 參考（status/list/set/scan、別名、備援、身分驗證）'
+    - 您想要變更預設模型或檢視提供者驗證狀態
+    - 你想掃描可用的模型/提供者並偵錯驗證設定檔
+summary: CLI 參考：`openclaw models`（status/list/set/scan、別名、備援、身分驗證）
 title: 模型
 x-i18n:
-    generated_at: "2026-05-01T02:44:44Z"
+    generated_at: "2026-05-04T18:23:43Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
+    source_hash: dc7842f02e29aa0ac2ae88f3d42bba71f1890a58ab22d818dbee0585bc562fea
    source_path: cli/models.md
    workflow: 16
 ---

 # `openclaw models`

-模型探索、掃描與設定（預設模型、備援、認證設定檔）。
+模型探索、掃描與設定（預設模型、備援、驗證設定檔）。

 相關：

 - 供應商 + 模型：[模型](/zh-TW/providers/models)
- 模型選擇概念 + `/models` 斜線命令：[模型概念](/zh-TW/concepts/models)
- 供應商認證設定：[開始使用](/zh-TW/start/getting-started)
+- 模型選擇概念 + `/models` 斜線指令：[模型概念](/zh-TW/concepts/models)
+- 供應商驗證設定：[開始使用](/zh-TW/start/getting-started)

-## 常用命令
+## 常用指令

 ```bash
 openclaw models status
@ -32,69 +32,71 @@ openclaw models set <model-or-alias>
 openclaw models scan
 ```

-`openclaw models status` 會顯示解析後的預設/備援模型，以及認證概覽。
-當供應商用量快照可用時，OAuth/API 金鑰狀態區段會包含
-供應商用量視窗與配額快照。
-目前支援用量視窗的供應商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI
-Codex、MiniMax、Xiaomi 與 z.ai。用量認證會在可用時來自供應商專屬掛鉤；
-否則 OpenClaw 會退回使用認證設定檔、環境變數或設定中相符的 OAuth/API 金鑰
+`openclaw models status` 會顯示解析後的預設/備援，加上驗證概覽。
+當供應商使用量快照可用時，OAuth/API 金鑰狀態區段會包含
+供應商使用視窗與配額快照。
+目前的使用視窗供應商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI
+Codex、MiniMax、Xiaomi 與 z.ai。可用時，使用量驗證會來自供應商特定掛鉤；
+否則 OpenClaw 會退回使用來自驗證設定檔、環境或設定中相符的 OAuth/API 金鑰
 憑證。
-在 `--json` 輸出中，`auth.providers` 是感知環境變數/設定/儲存區的供應商
-概覽，而 `auth.oauth` 只代表認證儲存區設定檔健康狀態。
-加入 `--probe` 可對每個已設定的供應商設定檔執行即時認證探測。
-探測是真實請求（可能會消耗 token 並觸發速率限制）。
-使用 `--agent <id>` 檢查已設定代理程式的模型/認證狀態。省略時，
-命令會在已設定時使用 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`，否則使用
-已設定的預設代理程式。
-探測列可來自認證設定檔、環境變數憑證或 `models.json`。
+在 `--json` 輸出中，`auth.providers` 是會感知環境/設定/儲存區的供應商
+概覽，而 `auth.oauth` 只代表驗證儲存區設定檔的健康狀態。
+加入 `--probe` 可對每個已設定的供應商設定檔執行即時驗證探測。
+探測是真實請求（可能會消耗權杖並觸發速率限制）。
+使用 `--agent <id>` 可檢查已設定代理程式的模型/驗證狀態。省略時，
+指令會使用已設定的預設代理程式，若已設定則改用
+`OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`。
+探測列可能來自驗證設定檔、環境憑證或 `models.json`。

 注意事項：

 - `models set <model-or-alias>` 接受 `provider/model` 或別名。
- `models list` 是唯讀的：它會讀取設定、認證設定檔、既有目錄
+- `models list` 是唯讀的：它會讀取設定、驗證設定檔、現有目錄
  狀態與供應商擁有的目錄列，但不會重寫
  `models.json`。
- `Auth` 欄位是供應商層級且唯讀。它是根據本機
-  認證設定檔中繼資料、環境變數標記、已設定的供應商金鑰、本機供應商
-  標記、AWS Bedrock 環境變數/設定檔標記，以及 Plugin 合成認證中繼資料計算而成；
+- `Auth` 欄位是供應商層級且唯讀。它會依據本機
+  驗證設定檔中繼資料、環境標記、已設定的供應商金鑰、本機供應商
+  標記、AWS Bedrock 環境/設定檔標記，以及 Plugin 合成驗證中繼資料計算；
  它不會載入供應商執行階段、讀取鑰匙圈祕密、呼叫供應商
  API，或證明精確的逐模型執行就緒狀態。
- `models list --all --provider <id>` 可以包含來自 Plugin 資訊清單或隨附供應商目錄中繼資料的供應商擁有靜態目錄
-  列，即使你尚未向該供應商完成認證也一樣。這些列仍會顯示為
-  不可用，直到設定相符認證為止。
- `models list` 會在供應商目錄
-  探索緩慢時讓控制平面保持回應。預設與已設定檢視會在短暫等待後退回使用已設定或
+- `models list --all --provider <id>` 可以包含來自 Plugin 資訊清單或
+  隨附供應商目錄中繼資料的供應商擁有靜態目錄列，即使你
+  尚未向該供應商驗證也一樣。這些列仍會顯示為
+  不可用，直到設定了相符的驗證。
+- `models list` 會在供應商目錄探索緩慢時維持控制平面回應。
+  預設與已設定視圖會在短暫等待後退回使用已設定或
  合成模型列，並讓探索在
-  背景中完成。當你需要精確完整的已探索目錄，且
+  背景完成。當你需要精確完整的已探索目錄，且
  願意等待供應商探索時，請使用 `--all`。
 - 廣泛的 `models list --all` 會將資訊清單目錄列合併到登錄列之上，
  而不載入供應商執行階段補充掛鉤。供應商篩選的資訊清單
-  快速路徑只使用標記為 `static` 的供應商；標記為 `refreshable` 的供應商
-  保持以登錄/快取為基礎並附加資訊清單列作為補充，而
-  標記為 `runtime` 的供應商則保持使用登錄/執行階段探索。
- `models list` 會保持原生模型中繼資料與執行階段上限分開。在表格
-  輸出中，當有效執行階段
-  上限不同於原生上下文視窗時，`Ctx` 會顯示 `contextTokens/contextWindow`；當供應商公開該上限時，JSON 列會包含 `contextTokens`。
- `models list --provider <id>` 依供應商 id 篩選，例如 `moonshot` 或
+  快速路徑只使用標記為 `static` 的供應商；標記為 `refreshable`
+  的供應商維持由登錄/快取支援，並將資訊清單列附加為補充，
+  而標記為 `runtime` 的供應商則維持使用登錄/執行階段探索。
+- `models list` 會將原生模型中繼資料與執行階段上限分開處理。在表格
+  輸出中，當有效執行階段上限與原生內容視窗不同時，`Ctx` 會顯示
+  `contextTokens/contextWindow`；當供應商公開該上限時，JSON 列會包含
+  `contextTokens`。
+- `models list --provider <id>` 會依供應商 id 篩選，例如 `moonshot` 或
  `openai-codex`。它不接受互動式供應商
  選擇器中的顯示標籤，例如 `Moonshot AI`。
- 模型參照會透過在**第一個** `/` 分割來剖析。如果模型 ID 包含 `/`（OpenRouter 風格），請包含供應商前綴（範例：`openrouter/moonshotai/kimi-k2`）。
+- 模型參照會透過 **第一個** `/` 分割來解析。如果模型 ID 包含 `/`（OpenRouter 風格），請包含供應商前綴（範例：`openrouter/moonshotai/kimi-k2`）。
 - 如果省略供應商，OpenClaw 會先將輸入解析為別名，接著
-  解析為該精確模型 id 在已設定供應商中的唯一相符項目，之後才
+  解析為該精確模型 id 在已設定供應商中的唯一相符項目，然後才
  退回使用已設定的預設供應商並顯示棄用警告。
  如果該供應商不再公開已設定的預設模型，OpenClaw
  會退回使用第一個已設定的供應商/模型，而不是顯示
  過時的已移除供應商預設值。
- `models status` 可能會在認證輸出中為非祕密預留位置顯示 `marker(<value>)`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是將它們遮罩為祕密。
+- `models status` 在驗證輸出中可能會對非祕密預留位置顯示 `marker(<value>)`（例如 `OPENAI_API_KEY`、`secretref-managed`、`minimax-oauth`、`oauth:chutes`、`ollama-local`），而不是將它們遮蔽為祕密。

 ### 模型掃描

-`models scan` 會讀取 OpenRouter 的公開 `:free` 目錄，並針對
-備援用途為候選項目排序。目錄本身是公開的，因此僅中繼資料掃描不需要
+`models scan` 會讀取 OpenRouter 的公開 `:free` 目錄，並為備援用途
+排序候選項目。目錄本身是公開的，因此僅中繼資料掃描不需要
 OpenRouter 金鑰。

-預設情況下，OpenClaw 會嘗試透過即時模型呼叫探測工具與影像支援。
-如果未設定 OpenRouter 金鑰，命令會退回僅中繼資料
+預設情況下，OpenClaw 會嘗試透過即時模型呼叫探測工具與圖片支援。
+如果沒有設定 OpenRouter 金鑰，指令會退回僅中繼資料
 輸出，並說明 `:free` 模型仍需要 `OPENROUTER_API_KEY` 才能進行
 探測與推論。

@ -123,17 +125,17 @@ OpenRouter 金鑰。
 - `--json`
 - `--plain`
 - `--check`（結束碼 1=已過期/缺少，2=即將過期）
- `--probe`（即時探測已設定的認證設定檔）
- `--probe-provider <name>`（探測單一供應商）
+- `--probe`（對已設定的驗證設定檔進行即時探測）
+- `--probe-provider <name>`（探測一個供應商）
 - `--probe-profile <id>`（重複或以逗號分隔的設定檔 id）
 - `--probe-timeout <ms>`
 - `--probe-concurrency <n>`
 - `--probe-max-tokens <n>`
- `--agent <id>`（已設定代理程式 id；覆寫 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）
+- `--agent <id>`（已設定的代理程式 id；覆寫 `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`）

-`--json` 會保留 stdout 給 JSON 承載使用。認證設定檔、供應商，
-以及啟動診斷會路由到 stderr，因此指令碼可以將 stdout 直接管線傳入
-`jq` 等工具。
+`--json` 會保留 stdout 只用於 JSON 承載。驗證設定檔、供應商
+與啟動診斷會導向 stderr，讓指令稿可以將 stdout 直接管線輸入
+到 `jq` 等工具。

 探測狀態分類：

@ -146,14 +148,14 @@ OpenRouter 金鑰。
 - `unknown`
 - `no_model`

-可預期的探測詳細資訊/原因碼案例：
+可預期的探測詳細資料/原因碼案例：

 - `excluded_by_auth_order`：已存在儲存的設定檔，但明確的
-  `auth.order.<provider>` 省略了它，因此探測會回報該排除狀態，而不是
-  嘗試它。
+  `auth.order.<provider>` 省略了它，因此探測會回報該排除，而不是
+  嘗試使用它。
 - `missing_credential`、`invalid_expires`、`expired`、`unresolved_ref`：
  設定檔存在，但不符合資格/無法解析。
- `no_model`：供應商認證存在，但 OpenClaw 無法為該供應商解析出可探測的
+- `no_model`：供應商驗證存在，但 OpenClaw 無法為該供應商解析出可探測的
  模型候選項目。

 ## 別名 + 備援
@ -163,45 +165,52 @@ openclaw models aliases list
 openclaw models fallbacks list
 ```

-## 認證設定檔
+## 驗證設定檔

 ```bash
 openclaw models auth add
+openclaw models auth list [--provider <id>] [--json]
 openclaw models auth login --provider <id>
 openclaw models auth setup-token --provider <id>
 openclaw models auth paste-token
 ```

-`models auth add` 是互動式認證輔助工具。它可以啟動供應商認證
+`models auth add` 是互動式驗證輔助工具。它可以啟動供應商驗證
 流程（OAuth/API 金鑰），或依據你選擇的
-供應商，引導你手動貼上 token。
+供應商引導你手動貼上權杖。

-`models auth login` 會執行供應商 Plugin 的認證流程（OAuth/API 金鑰）。使用
-`openclaw plugins list` 查看已安裝的供應商。
-使用 `openclaw models auth --agent <id> <subcommand>` 將認證結果寫入
-特定已設定代理程式儲存區。父層 `--agent` 旗標會被
-`add`、`login`、`setup-token`、`paste-token` 與 `login-github-copilot` 採用。
+`models auth list` 會列出所選代理程式已儲存的驗證設定檔，而不
+列印權杖、API 金鑰或 OAuth 祕密資料。使用 `--provider <id>` 可
+篩選至單一供應商，例如 `openai-codex`；使用 `--json` 可供指令稿處理。
+
+`models auth login` 會執行供應商 Plugin 的驗證流程（OAuth/API 金鑰）。使用
+`openclaw plugins list` 查看已安裝哪些供應商。
+使用 `openclaw models auth --agent <id> <subcommand>` 可將驗證結果寫入
+特定已設定的代理程式儲存區。父層 `--agent` 旗標會由
+`add`、`list`、`login`、`setup-token`、`paste-token` 與
+`login-github-copilot` 遵循。

 範例：

 ```bash
 openclaw models auth login --provider openai-codex --set-default
+openclaw models auth list --provider openai-codex
 ```

 注意事項：

- `setup-token` 與 `paste-token` 仍是供應商的通用 token 命令，
-  供公開 token 認證方法的供應商使用。
- `setup-token` 需要互動式 TTY，並執行供應商的 token 認證
+- `setup-token` 與 `paste-token` 仍是供公開權杖驗證方法之供應商使用的通用權杖指令。
+- `setup-token` 需要互動式 TTY，並會執行供應商的權杖驗證
  方法（當該供應商公開
-  其中一個方法時，預設使用該供應商的 `setup-token` 方法）。
- `paste-token` 接受在其他地方產生或來自自動化的 token 字串。
- `paste-token` 需要 `--provider`，會提示輸入 token 值，並將
-  它寫入預設設定檔 id `<provider>:manual`，除非你傳入
+  `setup-token` 方法時，預設使用該方法）。
+- `paste-token` 接受在其他地方產生或來自自動化的權杖字串。
+- `paste-token` 需要 `--provider`，會提示輸入權杖值，並寫入
+  預設設定檔 id `<provider>:manual`，除非你傳入
  `--profile-id`。
- `paste-token --expires-in <duration>` 會根據相對持續時間（例如 `365d` 或 `12h`）儲存絕對 token 到期時間。
- Anthropic 注意事項：Anthropic 員工告訴我們 OpenClaw 風格的 Claude CLI 使用方式已再次獲准，因此 OpenClaw 會將 Claude CLI 重用與 `claude -p` 使用方式視為此整合受認可的做法，除非 Anthropic 發布新政策。
- Anthropic `setup-token` / `paste-token` 仍可作為受支援的 OpenClaw token 路徑使用，但 OpenClaw 現在會在可用時優先使用 Claude CLI 重用與 `claude -p`。
+- `paste-token --expires-in <duration>` 會從相對持續時間（例如 `365d` 或 `12h`）
+  儲存絕對權杖到期時間。
+- Anthropic 注意事項：Anthropic 員工告訴我們，OpenClaw 風格的 Claude CLI 使用方式再次被允許，因此除非 Anthropic 發布新政策，否則 OpenClaw 會將 Claude CLI 重用與 `claude -p` 使用方式視為此整合的受准方式。
+- Anthropic `setup-token` / `paste-token` 仍可作為受支援的 OpenClaw 權杖路徑，但 OpenClaw 現在偏好可用時重用 Claude CLI 與 `claude -p`。

 ## 相關

--- a/docs/zh-TW/cli/proxy.md
+++ b/docs/zh-TW/cli/proxy.md
@ -1,32 +1,32 @@
 ---
 read_when:
-    - 您需要在部署前驗證操作員管理的代理路由
-    - 你需要在本機擷取 OpenClaw 傳輸流量以進行偵錯
-    - 你想要檢查除錯代理工作階段、二進位大型物件或內建查詢預設
-summary: CLI 參考，用於 `openclaw proxy`，包括操作員管理的代理驗證與本機偵錯代理擷取檢查器
+    - 您需要在部署前驗證由操作員管理的代理路由
+    - 您需要在本機擷取 OpenClaw 傳輸流量以進行偵錯
+    - 您想要檢查除錯代理工作階段、大型二進位物件，或內建查詢預設集
+summary: '`openclaw proxy` 的 CLI 參考，包括由操作員管理的代理驗證，以及本機偵錯代理擷取檢查器'
 title: 代理
 x-i18n:
-    generated_at: "2026-05-04T07:03:03Z"
+    generated_at: "2026-05-04T18:23:54Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
+    source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
    source_path: cli/proxy.md
    workflow: 16
 ---

 # `openclaw proxy`

-驗證由操作員管理的代理路由，或執行本機明確除錯代理
-並檢查擷取到的流量。
+驗證由操作員管理的代理路由，或執行本機明確偵錯代理
+並檢查已擷取的流量。

-使用 `validate` 在啟用 OpenClaw 代理路由前，預先檢查由操作員管理的轉送代理。其他指令是用於傳輸層調查的除錯工具：它們可以啟動本機代理、在啟用擷取的情況下執行子指令、列出擷取工作階段、查詢常見流量模式、讀取擷取的 blob，並清除本機擷取資料。
+使用 `validate` 在啟用 OpenClaw 代理路由前，預先檢查由操作員管理的轉送代理。其他命令則是用於傳輸層級調查的偵錯工具：它們可以啟動本機代理、在啟用擷取的情況下執行子命令、列出擷取工作階段、查詢常見流量模式、讀取已擷取的 blob，以及清除本機擷取資料。

-## 指令
+## 命令

 ```bash
 openclaw proxy start [--host <host>] [--port <port>]
 openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
-openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
+openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
 openclaw proxy coverage
 openclaw proxy sessions [--limit <count>]
 openclaw proxy query --preset <name> [--session <id>]
@ -36,17 +36,19 @@ openclaw proxy purge

 ## 驗證

-`openclaw proxy validate` 會從 `--proxy-url`、設定或 `OPENCLAW_PROXY_URL` 檢查實際生效的由操作員管理的代理 URL。當沒有啟用並設定代理時，它會回報設定問題；請使用 `--proxy-url` 在變更設定前進行一次性預先檢查。預設情況下，它會驗證公開目的地可透過代理成功連線，且代理無法連線到暫時的 loopback canary。自訂拒絕目的地採用失敗關閉：HTTP 回應與不明確的傳輸失敗都會失敗，除非你可以另外驗證部署特定的拒絕訊號。
+`openclaw proxy validate` 會從 `--proxy-url`、設定或 `OPENCLAW_PROXY_URL` 檢查有效的由操作員管理的代理 URL。當沒有啟用並設定代理時，它會回報設定問題；請使用 `--proxy-url` 在變更設定前進行一次性預先檢查。預設情況下，它會驗證可透過代理成功連線至公開目的地，且代理無法連線至暫時的 loopback canary。自訂拒絕目的地採失敗關閉模式：HTTP 回應和不明確的傳輸失敗都會視為失敗，除非你可以另外驗證部署專屬的拒絕訊號。加入 `--apns-reachable` 也會透過代理開啟 APNs HTTP/2 CONNECT 通道，並確認沙盒 APNs 有回應；此探測會使用刻意無效的提供者權杖，因此 APNs `403 InvalidProviderToken` 回應即代表可達性訊號成功。

 選項：

 - `--json`：列印機器可讀的 JSON。
- `--proxy-url <url>`：驗證此代理 URL，而不是設定或環境變數。
- `--allowed-url <url>`：新增預期可透過代理成功連線的目的地。可重複使用以檢查多個目的地。
- `--denied-url <url>`：新增預期會被代理封鎖的目的地。可重複使用以檢查多個目的地。
- `--timeout-ms <ms>`：每個請求的逾時時間，以毫秒為單位。
+- `--proxy-url <url>`：驗證此代理 URL，而非設定或環境變數。
+- `--allowed-url <url>`：加入預期可透過代理成功連線的目的地。可重複使用以檢查多個目的地。
+- `--denied-url <url>`：加入預期會被代理封鎖的目的地。可重複使用以檢查多個目的地。
+- `--apns-reachable`：也驗證沙盒 APNs HTTP/2 可透過代理連線。
+- `--apns-authority <url>`：搭配 `--apns-reachable` 探測的 APNs authority（預設為 `https://api.sandbox.push.apple.com`；正式環境為 `https://api.push.apple.com`）。
+- `--timeout-ms <ms>`：每個請求的逾時時間，單位為毫秒。

-請參閱[網路代理](/zh-TW/security/network-proxy)以了解部署指引與拒絕語義。
+請參閱[網路代理](/zh-TW/security/network-proxy)以取得部署指引和拒絕語意。

 ## 查詢預設集

@ -59,13 +61,13 @@ openclaw proxy purge
 - `missing-ack`
 - `error-bursts`

-## 注意事項
+## 備註

- `start` 預設為 `127.0.0.1`，除非設定了 `--host`。
- `run` 會啟動本機除錯代理，然後執行 `--` 之後的指令。
- 除錯代理的直接上游轉送會開啟上游 socket 以供診斷。當 OpenClaw 受管理代理模式啟用時，預設會停用代理請求與 CONNECT 通道的直接轉送；只有在已核准的本機診斷中，才設定 `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1`。
- 當代理設定或目的地檢查失敗時，`validate` 會以代碼 1 結束。
- 擷取內容是本機除錯資料；完成後請使用 `openclaw proxy purge`。
+- `start` 預設為 `127.0.0.1`，除非已設定 `--host`。
+- `run` 會啟動本機偵錯代理，然後執行 `--` 之後的命令。
+- 偵錯代理的直接上游轉送會開啟上游 socket 以供診斷使用。當 OpenClaw 管理代理模式啟用時，代理請求和 CONNECT 通道的直接轉送預設為停用；只有在核准的本機診斷中，才設定 `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1`。
+- `validate` 會在代理設定或目的地檢查失敗時，以代碼 1 結束。
+- 擷取內容是本機偵錯資料；完成後請使用 `openclaw proxy purge`。

 ## 相關

--- a/docs/zh-TW/gateway/cli-backends.md
+++ b/docs/zh-TW/gateway/cli-backends.md
@ -1,43 +1,43 @@
 ---
 read_when:
-    - 你需要在 API 供應商發生故障時有可靠的備援。
-    - 您正在執行 Codex CLI 或其他本機人工智慧 CLI，並想重複使用它們
+    - 您需要在 API 提供者失敗時有可靠的備援
+    - 你正在執行 Codex CLI 或其他本機人工智慧 CLI，並想重複使用它們
    - 你想了解用於 CLI 後端工具存取的 MCP 回送橋接器
-summary: CLI 後端：具備可選 MCP 工具橋接器的本機 AI CLI 備援
+summary: CLI 後端：具備選用 MCP 工具橋接的本機 AI CLI 備援
 title: CLI 後端
 x-i18n:
-    generated_at: "2026-05-02T20:47:28Z"
+    generated_at: "2026-05-04T18:23:50Z"
    model: gpt-5.5
    provider: openai
-    source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
+    source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
    source_path: gateway/cli-backends.md
    workflow: 16
 ---

-OpenClaw 可以在 API 供應商停機、受速率限制或暫時異常時，執行**本機 AI CLI** 作為**純文字備援**。這是刻意保守的設計：
+OpenClaw 可以在 API 供應商停機、受到速率限制，或暫時行為異常時，將**本機 AI CLI** 作為**純文字備援**執行。這是刻意保守的設計：

- **OpenClaw 工具不會直接注入**，但具有 `bundleMcp: true`
-  的後端可以透過 loopback MCP 橋接器接收 Gateway 工具。
- 支援該功能的 CLI 可使用 **JSONL 串流**。
- **支援工作階段**（因此後續回合會保持連貫）。
+- **OpenClaw 工具不會直接注入**，但具備 `bundleMcp: true`
+  的後端可以透過 loopback MCP 橋接器接收 gateway 工具。
+- 支援它的 CLI 可使用 **JSONL 串流**。
+- **支援會話**（因此後續回合可保持一致）。
 - 如果 CLI 接受圖片路徑，**可以傳遞圖片**。

-這被設計為**安全網**，而不是主要路徑。當你想要「始終可用」的文字回應，而不依賴外部 API 時，請使用它。
+這是設計為**安全網**，而不是主要路徑。當你想要「永遠可用」的文字回應，而且不依賴外部 API 時使用它。

-如果你想要具備 ACP 工作階段控制、背景工作、執行緒/對話繫結，以及持久外部程式碼工作階段的完整 harness runtime，請改用
+如果你想要具備 ACP 會話控制、背景工作、執行緒/對話繫結，以及持久外部編碼會話的完整 harness runtime，請改用
 [ACP Agents](/zh-TW/tools/acp-agents)。CLI 後端不是 ACP。

-## 適合初學者的快速開始
+## 適合初學者的快速入門

-你可以**不使用任何設定**就使用 Codex CLI（內建 OpenAI Plugin
+你可以**不使用任何設定**直接使用 Codex CLI（隨附的 OpenAI plugin
 會註冊預設後端）：

 ```bash
 openclaw agent --message "hi" --model codex-cli/gpt-5.5
 ```

-如果你的 Gateway 在 launchd/systemd 下執行且 PATH 很精簡，只要加入
-command 路徑即可：
+如果你的 gateway 在 launchd/systemd 下執行且 PATH 很精簡，只要加入
+命令路徑：

 ```json5
 {
@ -53,14 +53,14 @@ command 路徑即可：
 }
 ```

-就這樣。除了 CLI 本身之外，不需要金鑰，也不需要額外驗證設定。
+就這樣。除了 CLI 本身之外，不需要金鑰，也不需要額外的驗證設定。

-如果你在 Gateway 主機上將內建 CLI 後端作為**主要訊息供應商**使用，現在當你的設定在模型參照或
-`agents.defaults.cliBackends` 下明確參照該後端時，OpenClaw 會自動載入擁有該後端的內建 Plugin。
+如果你在 gateway 主機上將隨附的 CLI 後端作為**主要訊息供應商**使用，當你的設定在 model ref 或
+`agents.defaults.cliBackends` 下明確引用該後端時，OpenClaw 現在會自動載入擁有該後端的隨附 plugin。

 ## 作為備援使用

-將 CLI 後端加入你的備援清單，讓它只在主要模型失敗時執行：
+將 CLI 後端加入你的備援清單，使其只在主要模型失敗時執行：

 ```json5
 {
@ -81,10 +81,10 @@ command 路徑即可：

 注意事項：

- 如果你使用 `agents.defaults.models`（允許清單），也必須把 CLI 後端模型包含在其中。
+- 如果你使用 `agents.defaults.models`（允許清單），也必須把你的 CLI 後端模型包含在其中。
 - 如果主要供應商失敗（驗證、速率限制、逾時），OpenClaw 會接著嘗試 CLI 後端。

-## 設定概覽
+## 設定概觀

 所有 CLI 後端都位於：

@ -92,8 +92,8 @@ command 路徑即可：
 agents.defaults.cliBackends
 ```

-每個項目都以**供應商 id** 作為鍵（例如 `codex-cli`、`my-cli`）。
-供應商 id 會成為你的模型參照左側：
+每個項目都以**供應商 ID** 作為鍵（例如 `codex-cli`、`my-cli`）。
+供應商 ID 會成為你的模型參照左側：

 ```
 <provider>/<model>
@ -141,30 +141,48 @@ agents.defaults.cliBackends

 ## 運作方式

-1. 根據供應商前綴（`codex-cli/...`）**選擇後端**。
-2. 使用相同的 OpenClaw 提示 + 工作區內容**建立系統提示**。
-3. 使用工作階段 id（如果支援）**執行 CLI**，讓歷史記錄保持一致。
-   內建 `claude-cli` 後端會針對每個 OpenClaw 工作階段保持一個 Claude stdio 行程存活，並透過 stream-json stdin 傳送後續回合。
+1. 根據供應商前綴（`codex-cli/...`）**選取後端**。
+2. 使用相同的 OpenClaw prompt + 工作區內容**建立系統提示**。
+3. 以會話 ID（若支援）**執行 CLI**，讓歷史保持一致。
+   隨附的 `claude-cli` 後端會為每個 OpenClaw 會話保持一個 Claude stdio 程序存活，並透過 stream-json stdin 傳送後續回合。
 4. **剖析輸出**（JSON 或純文字）並回傳最終文字。
-5. 針對每個後端**持久保存工作階段 id**，讓後續回合重用同一個 CLI 工作階段。
+5. 依後端**持久化會話 ID**，讓後續回合重複使用相同的 CLI 會話。

 <Note>
-內建 Anthropic `claude-cli` 後端再次受到支援。Anthropic 員工告訴我們，OpenClaw 風格的 Claude CLI 使用方式再次被允許，因此除非 Anthropic 發布新政策，OpenClaw 會將這個整合中的
-`claude -p` 使用視為已核准。
+隨附的 Anthropic `claude-cli` 後端已再次受到支援。Anthropic 工作人員
+告訴我們，OpenClaw 風格的 Claude CLI 使用方式已再次被允許，因此 OpenClaw 會將
+`claude -p` 用法視為此整合的核准用法，除非 Anthropic 發布
+新政策。
 </Note>

-內建 OpenAI `codex-cli` 後端會透過 Codex 的 `model_instructions_file` 設定覆寫（`-c
-model_instructions_file="..."`）傳遞 OpenClaw 的系統提示。Codex 不公開 Claude 風格的
-`--append-system-prompt` 旗標，因此 OpenClaw 會為每個新的 Codex CLI 工作階段將組裝好的提示寫入暫存檔。
+隨附的 OpenAI `codex-cli` 後端會透過 Codex 的 `model_instructions_file` 設定覆寫（`-c
+model_instructions_file="..."`）傳遞 OpenClaw 的系統提示。Codex 不提供 Claude 風格的
+`--append-system-prompt` 旗標，因此 OpenClaw 會為每個新的 Codex CLI 會話將組裝好的提示寫入
+暫存檔。

-內建 Anthropic `claude-cli` 後端會以兩種方式接收 OpenClaw Skills 快照：附加系統提示中的精簡 OpenClaw Skills 目錄，以及透過 `--plugin-dir` 傳入的暫存 Claude Code Plugin。該 Plugin 只包含該 agent/工作階段符合資格的 Skills，因此 Claude Code 的原生 skill 解析器會看到與 OpenClaw 原本會在提示中公告的相同篩選集合。Skill env/API 金鑰覆寫仍會由 OpenClaw 套用到該次執行的子行程環境。
+隨附的 Anthropic `claude-cli` 後端會以兩種方式接收 OpenClaw skills 快照：附加系統提示中的精簡 OpenClaw skills 目錄，以及
+透過 `--plugin-dir` 傳入的暫存 Claude Code plugin。該 plugin 僅包含
+該 agent/會話符合資格的 skills，因此 Claude Code 的原生 skill
+解析器會看到與 OpenClaw 原本會在
+提示中公告的相同已篩選集合。Skill env/API key 覆寫仍會由 OpenClaw 套用到該次執行的
+子程序環境。

-Claude CLI 也有自己的非互動權限模式。OpenClaw 會將它對應到既有的執行策略，而不是新增 Claude 專用設定：當有效要求的執行策略是 YOLO（`tools.exec.security: "full"` 且
+Claude CLI 也有自己的非互動權限模式。OpenClaw 會將該模式對應到
+既有的 exec 政策，而不是加入 Claude 專屬設定：當有效請求的 exec 政策為 YOLO（`tools.exec.security: "full"` 且
 `tools.exec.ask: "off"`）時，OpenClaw 會加入 `--permission-mode bypassPermissions`。
-每個 agent 的 `agents.list[].tools.exec` 設定會覆寫該 agent 的全域 `tools.exec`。若要強制使用不同的 Claude 模式，請在
-`agents.defaults.cliBackends.claude-cli.args` 和相符的 `resumeArgs` 下設定明確的原始後端參數，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。
+每個 agent 的 `agents.list[].tools.exec` 設定會覆寫該 agent 的全域 `tools.exec`。
+若要強制使用不同的 Claude 模式，請在
+`agents.defaults.cliBackends.claude-cli.args` 和相符的 `resumeArgs` 下設定明確的原始後端引數，
+例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。

-在 OpenClaw 能使用內建 `claude-cli` 後端之前，Claude Code 本身必須已經在同一台主機上登入：
+隨附的 Anthropic `claude-cli` 後端也會將 OpenClaw `/think` 層級
+對應到 Claude Code 原生的 `--effort` 旗標，用於非 off 層級。`minimal` 和
+`low` 對應至 `low`，`adaptive` 和 `medium` 對應至 `medium`，而 `high`、
+`xhigh` 和 `max` 直接對應。其他 CLI 後端需要其所屬 plugin
+宣告等效的 argv mapper，`/think` 才能影響產生的 CLI。
+
+在 OpenClaw 可以使用隨附的 `claude-cli` 後端之前，Claude Code 本身
+必須已在同一台主機上登入：

 ```bash
 claude auth login
@ -172,49 +190,64 @@ claude auth status --text
 openclaw models auth login --provider anthropic --method cli --set-default
 ```

-只有在 `claude` 執行檔尚未位於 `PATH` 上時，才使用 `agents.defaults.cliBackends.claude-cli.command`。
+只有當 `claude` binary 尚未位於 `PATH` 上時，才使用 `agents.defaults.cliBackends.claude-cli.command`。

-## 工作階段
+## 會話

- 如果 CLI 支援工作階段，請在 ID 需要插入多個旗標時設定 `sessionArg`（例如 `--session-id`）或
+- 如果 CLI 支援會話，當 ID 需要插入多個旗標時，請設定 `sessionArg`（例如 `--session-id`）或
  `sessionArgs`（預留位置 `{sessionId}`）。
- 如果 CLI 使用具有不同旗標的**恢復子命令**，請設定
-  `resumeArgs`（恢復時取代 `args`），並可選擇性設定 `resumeOutput`
-  （用於非 JSON 恢復）。
+- 如果 CLI 使用具有不同旗標的**resume 子命令**，請設定
+  `resumeArgs`（在恢復時取代 `args`），並可選擇設定 `resumeOutput`
+  （用於非 JSON resume）。
 - `sessionMode`：
-  - `always`：一律傳送工作階段 id（如果沒有儲存的 id，則使用新的 UUID）。
-  - `existing`：只有在先前已有儲存的工作階段 id 時才傳送。
-  - `none`：永不傳送工作階段 id。
- `claude-cli` 預設為 `liveSession: "claude-stdio"`、`output: "jsonl"`，
-  且 `input: "stdin"`，因此後續回合會在即時 Claude 行程仍啟用時重用它。溫熱 stdio 現在是預設值，也包含省略傳輸欄位的自訂設定。如果 Gateway 重新啟動或閒置行程結束，OpenClaw 會從已儲存的 Claude 工作階段 id 恢復。恢復前會根據既有可讀的專案 transcript 驗證已儲存的工作階段 id，因此虛假的繫結會以 `reason=transcript-missing`
-  清除，而不是在 `--resume` 下靜默啟動新的 Claude CLI 工作階段。
- Claude 即時工作階段會保留有界 JSONL 輸出防護。預設值允許每回合最多
-  8 MiB 與 20,000 行原始 JSONL。工具密集的 Claude 回合可以透過每個後端的
+  - `always`：永遠傳送會話 ID（若未儲存則使用新的 UUID）。
+  - `existing`：只有在先前已儲存時才傳送會話 ID。
+  - `none`：永不傳送會話 ID。
+- `claude-cli` 預設為 `liveSession: "claude-stdio"`、`output: "jsonl"`、
+  和 `input: "stdin"`，因此後續回合會在即時 Claude 程序仍作用中時重複使用它。
+  Warm stdio 現在是預設值，包括省略 transport 欄位的自訂設定。
+  如果 Gateway 重新啟動或閒置程序結束，OpenClaw 會從已儲存的 Claude 會話 ID 恢復。已儲存的會話
+  ID 會在 resume 前根據現有可讀取的專案 transcript 進行驗證，
+  因此 phantom bindings 會以 `reason=transcript-missing`
+  清除，而不是在 `--resume` 下靜默啟動新的 Claude CLI 會話。
+- Claude 即時會話保有有界 JSONL 輸出防護。預設允許每回合最多
+  8 MiB 和 20,000 原始 JSONL 行。工具密集的 Claude 回合可以透過每個後端的
  `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
-  和 `maxTurnLines` 提高限制；OpenClaw 會將這些設定限制在 64 MiB 與 100,000
-  行以內。
- 已儲存的 CLI 工作階段是供應商擁有的連續性。隱含的每日工作階段重設不會切斷它們；`/reset` 和明確的 `session.reset` 策略仍然會。
+  和 `maxTurnLines` 提高上限；OpenClaw 會將這些設定限制在 64 MiB 和 100,000
+  行。
+- 已儲存的 CLI 會話是供應商擁有的連續性。隱含的每日會話
+  重設不會切斷它們；`/reset` 和明確的 `session.reset` 政策仍然
+  會切斷。

 序列化注意事項：

- `serialize: true` 會保持同一 lane 的執行順序。
- 大多數 CLI 會在同一個供應商 lane 上序列化。
- 當選取的驗證身分變更時，OpenClaw 會放棄重用已儲存的 CLI 工作階段，包括已變更的 auth profile id、靜態 API 金鑰、靜態 token，或 CLI 公開的 OAuth 帳戶身分。OAuth access 與 refresh token 輪替不會切斷已儲存的 CLI 工作階段。如果 CLI 未公開穩定的 OAuth 帳戶 id，OpenClaw 會讓該 CLI 強制執行恢復權限。
+- `serialize: true` 會讓相同 lane 的執行保持順序。
+- 大多數 CLI 會在一個供應商 lane 上序列化。
+- 當選取的驗證身分變更時，OpenClaw 會放棄重複使用已儲存的 CLI 會話，
+  包括變更的驗證 profile ID、靜態 API key、靜態 token，或 CLI 暴露的 OAuth
+  帳號身分。OAuth access 和 refresh token
+  輪替不會切斷已儲存的 CLI 會話。如果 CLI 不暴露
+  穩定的 OAuth 帳號 ID，OpenClaw 會讓該 CLI 強制執行 resume 權限。

-## 來自 claude-cli 工作階段的備援前置內容
+## 來自 claude-cli 會話的備援前置內容

-當 `claude-cli` 嘗試容錯移轉到
-[`agents.defaults.model.fallbacks`](/zh-TW/concepts/model-failover) 中的非 CLI 候選項時，OpenClaw 會使用從 Claude Code 位於 `~/.claude/projects/` 的本機
-JSONL transcript 擷取的內容前置段來播種下一次嘗試。若沒有此種子，備援供應商會從冷啟動開始，因為 OpenClaw 自己的工作階段 transcript 對 `claude-cli` 執行而言是空的。
+當 `claude-cli` 嘗試故障轉移到
+[`agents.defaults.model.fallbacks`](/zh-TW/concepts/model-failover) 中的非 CLI 候選項時，OpenClaw 會使用從 `~/.claude/projects/` 的 Claude Code 本機
+JSONL transcript 擷取的內容前置內容來播種
+下一次嘗試。若沒有這個種子，備援
+供應商會冷啟動，因為 OpenClaw 自己的會話 transcript 對 `claude-cli` 執行而言是空的。

 - 前置內容會優先使用最新的 `/compact` 摘要或 `compact_boundary`
-  標記，然後在字元預算內附加邊界後最近的回合。邊界前的回合會被丟棄，因為摘要已經代表了它們。
+  標記，接著附加最近的邊界後回合，直到字元
+  預算為止。邊界前回合會被丟棄，因為摘要已代表
+  它們。
 - 工具區塊會合併為精簡的 `(tool call: name)` 和
-  `(tool result: …)` 提示，以確保提示預算合理。如果摘要溢出，會標示為
-  `(truncated)`。
+  `(tool result: …)` 提示，以保持 prompt 預算真實。若摘要
+  溢出，會標示為 `(truncated)`。
 - 同供應商的 `claude-cli` 到 `claude-cli` 備援會依賴 Claude 自己的
  `--resume`，並略過前置內容。
- 種子會重用既有的 Claude 工作階段檔案路徑驗證，因此無法讀取任意路徑。
+- 種子會重複使用現有的 Claude 會話檔路徑驗證，因此
+  無法讀取任意路徑。

 ## 圖片（傳遞）

@ -225,25 +258,29 @@ imageArg: "--image",
 imageMode: "repeat"
 ```

-OpenClaw 會將 base64 圖片寫入暫存檔。如果設定了 `imageArg`，那些路徑會作為 CLI 參數傳遞。如果缺少 `imageArg`，OpenClaw 會將檔案路徑附加到提示中（路徑注入），這對會從純路徑自動載入本機檔案的 CLI 已經足夠。
+OpenClaw 會將 base64 圖片寫入暫存檔。如果設定了 `imageArg`，這些
+路徑會作為 CLI 引數傳遞。如果缺少 `imageArg`，OpenClaw 會將
+檔案路徑附加到 prompt（路徑注入），這對於會從純路徑自動
+載入本機檔案的 CLI 已足夠。

 ## 輸入 / 輸出

- `output: "json"`（預設）會嘗試剖析 JSON，並擷取文字 + 工作階段 id。
- 對於 Gemini CLI JSON 輸出，當 `usage` 缺少或為空時，OpenClaw 會從 `response` 讀取回覆文字，並從
-  `stats` 讀取使用量。
- `output: "jsonl"` 會剖析 JSONL 串流（例如 Codex CLI `--json`），並擷取最終 agent 訊息以及存在時的工作階段識別碼。
+- `output: "json"`（預設）會嘗試剖析 JSON 並擷取文字 + 會話 ID。
+- 對於 Gemini CLI JSON 輸出，當 `usage` 缺少或為空時，OpenClaw 會從 `response` 讀取回覆文字，並
+  從 `stats` 讀取 usage。
+- `output: "jsonl"` 會剖析 JSONL 串流（例如 Codex CLI `--json`），並擷取最終 agent 訊息與存在的會話
+  識別碼。
 - `output: "text"` 會將 stdout 視為最終回應。

 輸入模式：

- `input: "arg"`（預設）會將提示作為最後一個 CLI 參數傳遞。
- `input: "stdin"` 會透過 stdin 傳送提示。
- 如果提示很長且設定了 `maxPromptArgChars`，則會使用 stdin。
+- `input: "arg"`（預設）會將 prompt 作為最後一個 CLI 引數傳遞。
+- `input: "stdin"` 會透過 stdin 傳送 prompt。
+- 如果 prompt 很長且設定了 `maxPromptArgChars`，則會使用 stdin。

-## 預設值（Plugin 擁有）
+## 預設值（plugin 擁有）

-內建 OpenAI Plugin 也會為 `codex-cli` 註冊預設值：
+隨附的 OpenAI plugin 也會為 `codex-cli` 註冊預設值：

 - `command: "codex"`
 - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -254,7 +291,7 @@ OpenClaw 會將 base64 圖片寫入暫存檔。如果設定了 `imageArg`，那
 - `imageArg: "--image"`
 - `sessionMode: "existing"`

-內建 Google Plugin 也會為 `google-gemini-cli` 註冊預設值：
+隨附的 Google plugin 也會為 `google-gemini-cli` 註冊預設值：

 - `command: "gemini"`
 - `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -265,7 +302,7 @@ OpenClaw 會將 base64 圖片寫入暫存檔。如果設定了 `imageArg`，那
 - `sessionMode: "existing"`
 - `sessionIdFields: ["session_id", "sessionId"]`

-先決條件：本機 Gemini CLI 必須已安裝，且可在 `PATH` 上以
+先決條件：本機 Gemini CLI 必須已安裝，並可在 `PATH` 上以
 `gemini` 使用（`brew install gemini-cli` 或
 `npm install -g @google/gemini-cli`）。

@ -277,19 +314,20 @@ Gemini CLI JSON 注意事項：
 - 如果缺少 `stats.input`，OpenClaw 會從
  `stats.input_tokens - stats.cached` 推導輸入 token。

-只在需要時覆寫（常見情況：絕對 `command` 路徑）。
+只有在需要時才覆寫（常見情況：絕對 `command` 路徑）。

 ## Plugin 擁有的預設值

 CLI 後端預設值現在是 Plugin 介面的一部分：

- Plugin 會透過 `api.registerCliBackend(...)` 註冊它們。
+- Plugin 使用 `api.registerCliBackend(...)` 註冊它們。
 - 後端 `id` 會成為模型參照中的提供者前綴。
 - `agents.defaults.cliBackends.<id>` 中的使用者設定仍會覆寫 Plugin 預設值。
- 後端專屬設定清理會透過選用的
-  `normalizeConfig` hook 保持由 Plugin 擁有。
+- 後端特定的設定清理仍透過選用的
+  `normalizeConfig` hook 由 Plugin 擁有。

-需要微小提示/訊息相容性 shim 的 Plugin，可以宣告雙向文字轉換，而不需要取代提供者或 CLI 後端：
+需要小型提示/訊息相容性 shim 的 Plugin，可以宣告
+雙向文字轉換，而不必替換提供者或 CLI 後端：

 ```typescript
 api.registerTextTransforms({
@ -306,58 +344,60 @@ api.registerTextTransforms({
 });
 ```

-`input` 會重寫傳給 CLI 的系統提示和使用者提示。`output`
-會在 OpenClaw 處理自身的控制標記和頻道傳遞之前，重寫串流助理 delta 和剖析後的最終文字。
+`input` 會重寫傳遞給 CLI 的系統提示與使用者提示。`output`
+會在 OpenClaw 處理自己的控制標記與頻道傳遞之前，重寫串流的助理差異與解析後的最終文字。

 對於會輸出 Claude Code stream-json 相容 JSONL 的 CLI，請在該後端的設定上設定
 `jsonlDialect: "claude-stream-json"`。

-## Bundle MCP 覆蓋層
+## Bundle MCP 疊加

-CLI 後端**不會**直接接收 OpenClaw 工具呼叫，但後端可以使用
-`bundleMcp: true` 選擇加入產生的 MCP 設定覆蓋層。
+CLI 後端**不會**直接接收 OpenClaw 工具呼叫，但後端可以
+透過 `bundleMcp: true` 選擇加入產生的 MCP 設定疊加。

 目前的內建行為：

 - `claude-cli`：產生嚴格的 MCP 設定檔
 - `codex-cli`：針對 `mcp_servers` 的行內設定覆寫；產生的
-  OpenClaw loopback 伺服器會標記 Codex 的每伺服器工具核准模式，
-  因此 MCP 呼叫不會卡在本機核准提示上
+  OpenClaw loopback 伺服器會標記 Codex 的逐伺服器工具核准模式，
+  因此 MCP 呼叫不會因本機核准提示而停滯
 - `google-gemini-cli`：產生 Gemini 系統設定檔

 啟用 bundle MCP 時，OpenClaw 會：

- 啟動 loopback HTTP MCP 伺服器，向 CLI 程序公開 Gateway 工具
- 使用每個工作階段的權杖（`OPENCLAW_MCP_TOKEN`）驗證橋接
- 將工具存取範圍限定在目前工作階段、帳戶和頻道情境
- 載入目前工作區已啟用的 bundle-MCP 伺服器
- 將它們與任何既有的後端 MCP 設定/設定形狀合併
- 使用擁有該後端的 Plugin 所屬整合模式重寫啟動設定
+- 啟動一個 loopback HTTP MCP 伺服器，向 CLI 程序公開 Gateway 工具
+- 使用每個工作階段的 token（`OPENCLAW_MCP_TOKEN`）驗證橋接
+- 將工具存取範圍限定在目前的工作階段、帳戶與頻道情境
+- 載入目前工作區啟用的 bundle-MCP 伺服器
+- 將它們與任何現有的後端 MCP 設定/設定形狀合併
+- 使用擁有 extension 的後端擁有整合模式重寫啟動設定

-如果未啟用任何 MCP 伺服器，當後端選擇加入 bundle MCP 時，OpenClaw 仍會注入嚴格設定，讓背景執行保持隔離。
+如果沒有啟用任何 MCP 伺服器，當後端選擇加入 bundle MCP 時，
+OpenClaw 仍會注入嚴格設定，讓背景執行保持隔離。

-工作階段範圍的內建 MCP runtime 會快取以便在工作階段內重複使用，然後在閒置
-`mcp.sessionIdleTtlMs` 毫秒後回收（預設 10
-分鐘；設為 `0` 可停用）。一次性嵌入式執行，例如驗證探測、
-slug 產生和 Active Memory 回想請求，會在執行結束時清理，讓 stdio
-子程序和 Streamable HTTP/SSE 串流不會在執行結束後繼續存在。
+工作階段範圍的內建 MCP runtime 會快取以在工作階段內重複使用，然後
+在閒置 `mcp.sessionIdleTtlMs` 毫秒後收回（預設 10
+分鐘；設定為 `0` 可停用）。一次性嵌入式執行，例如驗證探測、
+slug 產生，以及 active-memory recall，會在執行結束時請求清理，讓 stdio
+子程序與 Streamable HTTP/SSE 串流不會比該次執行活得更久。

 ## 限制

 - **沒有直接的 OpenClaw 工具呼叫。** OpenClaw 不會將工具呼叫注入
-  CLI 後端通訊協定。後端只有在選擇加入 `bundleMcp: true` 時，才會看到
-  Gateway 工具。
- **串流因後端而異。** 某些後端會串流 JSONL；其他後端會緩衝到結束為止。
+  CLI 後端協定。後端只有在選擇加入
+  `bundleMcp: true` 時才會看到 Gateway 工具。
+- **串流是後端特定的。** 有些後端會串流 JSONL；其他後端會緩衝
+  直到結束。
 - **結構化輸出**取決於 CLI 的 JSON 格式。
- **Codex CLI 工作階段**會透過文字輸出繼續（沒有 JSONL），其結構化程度低於初始
-  `--json` 執行。OpenClaw 工作階段仍會正常運作。
+- **Codex CLI 工作階段**會透過文字輸出續接（沒有 JSONL），這比初始
+  `--json` 執行更不具結構。OpenClaw 工作階段仍會正常運作。

 ## 疑難排解

 - **找不到 CLI**：將 `command` 設為完整路徑。
 - **模型名稱錯誤**：使用 `modelAliases` 將 `provider/model` → CLI 模型。
 - **沒有工作階段連續性**：確保已設定 `sessionArg`，且 `sessionMode` 不是
-  `none`（Codex CLI 目前無法使用 JSON 輸出繼續）。
+  `none`（Codex CLI 目前無法使用 JSON 輸出續接）。
 - **圖片被忽略**：設定 `imageArg`（並確認 CLI 支援檔案路徑）。

 ## 相關
--- a/docs/zh-TW/help/testing-live.md
+++ b/docs/zh-TW/help/testing-live.md
@ -1,28 +1,28 @@
 ---
 read_when:
-    - 執行即時模型矩陣 / CLI 後端 / ACP / media-provider 冒煙測試
+    - 執行即時模型矩陣 / CLI 後端 / ACP / 媒體提供者冒煙測試
    - 偵錯即時測試憑證解析
-    - 新增特定提供者的即時測試
+    - 新增提供者特定的即時測試
 sidebarTitle: Live tests
 summary: 實際（會觸及網路的）測試：模型矩陣、CLI 後端、ACP、媒體提供者、憑證
 title: 測試：即時測試套件
 x-i18n:
-    generated_at: "2026-05-03T21:35:49Z"
+    generated_at: "2026-05-04T18:23:51Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
+    source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
    source_path: help/testing-live.md
    workflow: 16
 ---

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

-## 即時：本機設定檔煙霧測試命令
+## Live：本機設定檔煙霧測試指令

-在臨時即時檢查前先載入 `~/.profile`，讓供應商金鑰與本機工具
+在臨時 live 檢查前先 source `~/.profile`，讓提供者金鑰與本機工具
 路徑和你的 shell 一致：

 ```bash
@ -44,95 +44,96 @@ pnpm openclaw voicecall setup --json
 pnpm openclaw voicecall smoke --to "+15555550123"
 ```

-除非同時提供 `--yes`，否則 `voicecall smoke` 是乾跑。只有在你刻意想要發出真正的通知通話時才使用 `--yes`。對 Twilio、Telnyx 和 Plivo 而言，成功的就緒檢查需要公開 Webhook URL；local loopback/私人備援依設計會被拒絕。
+`voicecall smoke` 是 dry run，除非同時提供 `--yes`。只有在你刻意想撥出真實通知電話時，才使用 `--yes`。對 Twilio、Telnyx 與 Plivo 而言，成功的就緒檢查需要公開 Webhook URL；依設計會拒絕僅限本機的
+loopback／私有備援。

-## 即時：Android 節點能力掃描
+## Live：Android Node 能力掃描

 - 測試：`src/gateway/android-node.capabilities.live.test.ts`
 - 指令碼：`pnpm android:test:integration`
- 目標：叫用已連線 Android 節點**目前公告的每一個命令**，並斷言命令合約行為。
+- 目標：呼叫已連線 Android Node **目前宣告的每個指令**，並斷言指令合約行為。
 - 範圍：
-  - 需預先處理/手動設定（此套件不會安裝/執行/配對應用程式）。
-  - 對所選 Android 節點逐一驗證 Gateway `node.invoke` 命令。
+  - 預先條件／手動設定（此套件不會安裝／執行／配對 App）。
+  - 針對選定 Android Node 逐一驗證 Gateway `node.invoke` 指令。
 - 必要的預先設定：
-  - Android 應用程式已連線並配對到 Gateway。
-  - 應用程式保持在前景。
-  - 對你預期會通過的能力，已授予權限/擷取同意。
+  - Android App 已連線並配對至 Gateway。
+  - App 保持在前景。
+  - 已授予你預期會通過的能力所需權限／擷取同意。
 - 選用目標覆寫：
  - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
  - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
- 完整 Android 設定詳細資訊：[Android 應用程式](/zh-TW/platforms/android)
+- 完整 Android 設定詳細資訊：[Android App](/zh-TW/platforms/android)

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

-即時測試分成兩層，讓我們可以隔離失敗：
+Live 測試分成兩層，讓我們可以隔離失敗：

- 「直接模型」告訴我們供應商/模型是否完全能用指定金鑰回應。
- 「Gateway 煙霧測試」告訴我們該模型的完整 gateway+agent 管線是否可運作（工作階段、歷史、工具、沙箱政策等）。
+- 「直接模型」告訴我們提供者／模型是否能用指定金鑰回應。
+- 「Gateway 煙霧測試」告訴我們該模型的完整 Gateway+代理管線是否能運作（工作階段、歷史、工具、沙箱政策等）。

 ### 第 1 層：直接模型補全（無 Gateway）

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

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

 - 測試：`src/gateway/gateway-models.profiles.live.test.ts`
 - 目標：
  - 啟動程序內 Gateway
-  - 建立/修補 `agent:dev:*` 工作階段（每次執行覆寫模型）
-  - 迭代具有金鑰的模型並斷言：
-    - 「有意義」的回應（無工具）
-    - 真正的工具叫用可運作（讀取探測）
+  - 建立／修補 `agent:dev:*` 工作階段（每次執行覆寫模型）
+  - 迭代有金鑰的模型並斷言：
+    - 「有意義的」回應（無工具）
+    - 真實工具呼叫可運作（讀取探測）
    - 選用額外工具探測（執行+讀取探測）
-    - OpenAI 回歸路徑（僅工具呼叫 → 後續追問）持續可運作
+    - OpenAI 回歸路徑（僅工具呼叫 → 後續回合）持續可運作
 - 探測詳細資訊（讓你能快速解釋失敗）：
-  - `read` 探測：測試會在工作區寫入 nonce 檔案，並要求 agent `read` 它並回顯 nonce。
-  - `exec+read` 探測：測試會要求 agent 以 `exec` 將 nonce 寫入暫存檔，然後再 `read` 回來。
-  - 圖片探測：測試附加一張產生的 PNG（貓 + 隨機程式碼），並預期模型回傳 `cat <CODE>`。
+  - `read` 探測：測試會在工作區寫入 nonce 檔案，並要求代理 `read` 它且回傳 nonce。
+  - `exec+read` 探測：測試會要求代理用 `exec` 將 nonce 寫入暫存檔，然後再 `read` 回來。
+  - 圖片探測：測試附加產生的 PNG（貓 + 隨機碼），並預期模型回傳 `cat <CODE>`。
  - 實作參考：`src/gateway/gateway-models.profiles.live.test.ts` 與 `src/gateway/live-image-probe.ts`。
 - 啟用方式：
-  - `pnpm test:live`（或在直接叫用 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
- 選取模型的方式：
+  - `pnpm test:live`（或在直接呼叫 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
+- 選擇模型的方式：
  - 預設：modern 允許清單（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4.3）
  - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern 允許清單的別名
-  - 或設定 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗號清單）來縮小範圍
-  - Modern/all Gateway 掃描預設使用精選的高訊號上限；設定 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可進行完整 modern 掃描，或設定正數作為較小上限。
- 選取供應商的方式（避免「OpenRouter 全部」）：
-  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗號分隔允許清單）
- 此即時測試一律啟用工具 + 圖片探測：
+  - 或設定 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗號清單）以縮小範圍
+  - Modern/all Gateway 掃描預設使用精選的高訊號上限；設定 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 進行完整 modern 掃描，或設定正數作為較小上限。
+- 選擇提供者的方式（避免「OpenRouter 全部」）：
+  - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗號允許清單）
+- 此 live 測試中的工具 + 圖片探測一律啟用：
  - `read` 探測 + `exec+read` 探測（工具壓力測試）
-  - 當模型公告支援圖片輸入時會執行圖片探測
-  - 流程（高層次）：
-    - 測試產生含有「CAT」+ 隨機程式碼的小型 PNG（`src/gateway/live-image-probe.ts`）
+  - 當模型宣告支援圖片輸入時執行圖片探測
+  - 流程（高階）：
+    - 測試會產生帶有「CAT」+ 隨機碼的小型 PNG（`src/gateway/live-image-probe.ts`）
    - 透過 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 傳送
-    - Gateway 將附件剖析到 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
-    - 內嵌 agent 將多模態使用者訊息轉送給模型
-    - 斷言：回覆包含 `cat` + 程式碼（OCR 容錯：允許小錯誤）
+    - Gateway 將附件解析成 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
+    - 嵌入式代理將多模態使用者訊息轉送給模型
+    - 斷言：回覆包含 `cat` + 該代碼（OCR 容錯：允許輕微錯誤）

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

 ```bash
 openclaw models list
@ -141,27 +142,27 @@ openclaw models list --json

 </Tip>

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

 - 測試：`src/gateway/gateway-cli-backend.live.test.ts`
- 目標：使用本機 CLI 後端驗證 Gateway + agent 管線，而不觸碰你的預設設定。
- 後端專屬煙霧測試預設值位於擁有該後端的 extension `cli-backend.ts` 定義中。
+- 目標：使用本機 CLI 後端驗證 Gateway + 代理管線，且不觸及你的預設設定。
+- 後端專屬煙霧測試預設值位於所屬 Plugin 的 `cli-backend.ts` 定義。
 - 啟用：
-  - `pnpm test:live`（或在直接叫用 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
+  - `pnpm test:live`（或在直接呼叫 Vitest 時使用 `OPENCLAW_LIVE_TEST=1`）
  - `OPENCLAW_LIVE_CLI_BACKEND=1`
 - 預設值：
-  - 預設供應商/模型：`claude-cli/claude-sonnet-4-6`
-  - 命令/引數/圖片行為來自擁有該 CLI 後端的 Plugin metadata。
+  - 預設提供者／模型：`claude-cli/claude-sonnet-4-6`
+  - 指令／參數／圖片行為來自所屬 CLI 後端 Plugin 中繼資料。
 - 覆寫（選用）：
  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
  - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
  - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
-  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 會傳送真正的圖片附件（路徑會注入提示中）。除非明確要求，Docker 配方預設關閉此項。
-  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 會將圖片檔案路徑作為 CLI 引數傳入，而非注入提示。
-  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用來控制設定 `IMAGE_ARG` 時圖片引數的傳遞方式。
-  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 會送出第二輪並驗證恢復流程。
-  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 會在所選模型支援切換目標時，選擇加入 Claude Sonnet -> Opus 同工作階段連續性探測。Docker 配方為了彙總可靠性，預設關閉此項。
-  - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 會選擇加入 MCP/tool loopback 探測。除非明確要求，Docker 配方預設關閉此項。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 以傳送真實圖片附件（路徑會注入提示詞）。Docker 配方預設會關閉此項，除非明確要求。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 以將圖片檔案路徑作為 CLI 參數傳遞，而非注入提示詞。
+  - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）以在設定 `IMAGE_ARG` 時控制圖片參數的傳遞方式。
+  - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 以傳送第二回合並驗證恢復流程。
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 以在所選模型支援切換目標時，選擇加入 Claude Sonnet -> Opus 同工作階段連續性探測。Docker 配方為了整體可靠性，預設會關閉此項。
+  - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 以選擇加入 MCP／工具 loopback 探測。Docker 配方預設會關閉此項，除非明確要求。

 範例：

@ -171,15 +172,15 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
 ```

-便宜的 Gemini MCP 設定煙霧測試：
+低成本 Gemini MCP 設定煙霧測試：

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

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

@ -189,7 +190,7 @@ Docker 配方：
 pnpm test:docker:live-cli-backend
 ```

-單一供應商 Docker 配方：
+單一提供者 Docker 配方：

 ```bash
 pnpm test:docker:live-cli-backend:claude
@ -198,30 +199,39 @@ pnpm test:docker:live-cli-backend:codex
 pnpm test:docker:live-cli-backend:gemini
 ```

-注意事項：
+注意：

 - Docker 執行器位於 `scripts/test-live-cli-backend-docker.sh`。
- 它會以非 root 的 `node` 使用者，在 repo Docker 映像內執行即時 CLI 後端煙霧測試。
- 它會從擁有該後端的 extension 解析 CLI 煙霧測試 metadata，然後將相符的 Linux CLI 套件（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安裝到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的快取可寫入前綴（預設：`~/.cache/openclaw/docker-cli-tools`）。
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要透過 `~/.claude/.credentials.json` 搭配 `claudeAiOauth.subscriptionType`，或透過來自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`，取得可攜式 Claude Code 訂閱 OAuth。它會先在 Docker 中證明直接 `claude -p` 可行，然後在不保留 Anthropic API 金鑰環境變數的情況下，執行兩輪 Gateway CLI 後端。此訂閱通道預設停用 Claude MCP/tool 與圖片探測，因為 Claude 目前會將第三方應用程式使用量導向額外用量計費，而不是一般訂閱方案限制。
- 即時 CLI 後端煙霧測試現在會對 Claude、Codex 和 Gemini 執行相同的端對端流程：文字輪次、圖片分類輪次，接著透過 gateway CLI 驗證 MCP `cron` 工具呼叫。
- Claude 的預設煙霧測試也會將工作階段從 Sonnet 修補為 Opus，並驗證恢復後的工作階段仍記得先前的筆記。
+- 它會以非 root `node` 使用者，在 repo Docker 映像中執行 live CLI 後端煙霧測試。
+- 它會從所屬 Plugin 解析 CLI 煙霧測試中繼資料，然後將相符的 Linux CLI 套件（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安裝到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的可寫快取前綴（預設：`~/.cache/openclaw/docker-cli-tools`）。
+- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可攜式 Claude Code 訂閱 OAuth，來源可為帶有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或來自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`。它會先在 Docker 中證明直接 `claude -p` 可運作，接著在不保留 Anthropic API 金鑰環境變數的情況下執行兩個 Gateway CLI 後端回合。此訂閱路線預設會停用 Claude MCP／工具與圖片探測，因為 Claude 目前會將第三方 App 用量導向額外用量計費，而非一般訂閱方案限制。
+- live CLI 後端煙霧測試現在會對 Claude、Codex 與 Gemini 執行相同的端到端流程：文字回合、圖片分類回合，然後是透過 Gateway CLI 驗證的 MCP `cron` 工具呼叫。
+- Claude 的預設煙霧測試也會將工作階段從 Sonnet 修補為 Opus，並驗證恢復的工作階段仍記得先前的筆記。

-## 即時：ACP 綁定煙霧測試（`/acp spawn ... --bind here`）
+## Live：APNs HTTP/2 proxy 可達性
+
+- 測試：`src/infra/push-apns-http2.live.test.ts`
+- 目標：透過本機 HTTP CONNECT proxy 通道連到 Apple 的沙箱 APNs 端點，送出 APNs HTTP/2 驗證請求，並斷言 Apple 的真實 `403 InvalidProviderToken` 回應會透過 proxy 路徑傳回。
+- 啟用：
+  - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
+- 選用逾時：
+  - `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
+
+## Live：ACP 繫結煙霧測試（`/acp spawn ... --bind here`）

 - 測試：`src/gateway/gateway-acp-bind.live.test.ts`
- 目標：使用即時 ACP agent 驗證真實的 ACP 對話綁定流程：
+- 目標：使用即時 ACP 代理驗證真正的 ACP 對話綁定流程：
  - 傳送 `/acp spawn <agent> --bind here`
-  - 就地綁定一個合成的訊息通道對話
-  - 在同一個對話傳送一般後續訊息
-  - 驗證後續訊息會進入已綁定的 ACP 工作階段逐字稿
+  - 就地綁定合成的訊息通道對話
+  - 在同一個對話中傳送一般後續訊息
+  - 確認後續訊息進入已綁定 ACP 工作階段的記錄
 - 啟用：
  - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
  - `OPENCLAW_LIVE_ACP_BIND=1`
 - 預設值：
-  - Docker 中的 ACP agents：`claude,codex,gemini`
-  - 直接執行 `pnpm test:live ...` 時的 ACP agent：`claude`
-  - 合成 channel：Slack DM 風格的對話脈絡
+  - Docker 中的 ACP 代理：`claude,codex,gemini`
+  - 直接執行 `pnpm test:live ...` 時的 ACP 代理：`claude`
+  - 合成通道：Slack DM 風格的對話情境
  - ACP 後端：`acpx`
 - 覆寫：
  - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
@ -237,9 +247,9 @@ pnpm test:docker:live-cli-backend:gemini
  - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
 - 注意事項：
-  - 此 lane 使用 gateway `chat.send` 介面，並帶有僅限管理員使用的合成來源路由欄位，讓測試可以附加訊息通道脈絡，而不假裝向外部遞送。
-  - 未設定 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 時，測試會使用內嵌 `acpx` Plugin 針對所選 ACP harness agent 的內建 agent 登錄。
-  - 已綁定工作階段的 cron MCP 建立預設為最佳努力，因為外部 ACP harness 可能會在綁定/影像證明通過後取消 MCP 呼叫；設定 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可讓綁定後的 cron 探測變為嚴格。
+  - 此通道使用 Gateway `chat.send` 介面，並搭配僅限管理員的合成來源路由欄位，讓測試可以附加訊息通道情境，而不假裝進行外部投遞。
+  - 未設定 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 時，測試會使用內嵌 `acpx` Plugin 的內建代理登錄，來選取 ACP 測試框架代理。
+  - 已綁定工作階段的 Cron MCP 建立預設採最佳努力方式，因為外部 ACP 測試框架可能在綁定／圖片驗證通過後取消 MCP 呼叫；設定 `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` 可讓該綁定後 Cron 探測變成嚴格模式。

 範例：

@ -255,7 +265,7 @@ Docker 配方：
 pnpm test:docker:live-acp-bind
 ```

-單一 agent Docker 配方：
+單一代理 Docker 配方：

 ```bash
 pnpm test:docker:live-acp-bind:claude
@ -267,31 +277,38 @@ pnpm test:docker:live-acp-bind:opencode

 Docker 注意事項：

- Docker runner 位於 `scripts/test-live-acp-bind-docker.sh`。
- 預設會依序對彙總的即時 CLI agents 執行 ACP 綁定 smoke：`claude`、`codex`，然後是 `gemini`。
+- Docker 執行器位於 `scripts/test-live-acp-bind-docker.sh`。
+- 預設會依序對彙總的即時 CLI 代理執行 ACP 綁定煙霧測試：`claude`、`codex`，然後是 `gemini`。
 - 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` 來縮小矩陣。
- 它會載入 `~/.profile`，將相符的 CLI 驗證資料暫存到容器中，然後在缺少時安裝要求的即時 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、Factory Droid via `https://app.factory.ai/cli`、`@google/gemini-cli` 或 `opencode-ai`）。ACP 後端本身是官方 `acpx` Plugin 中內嵌的 `acpx/runtime` 套件。
- Droid Docker 變體會暫存 `~/.factory` 作為設定、轉送 `FACTORY_API_KEY`，且需要該 API key，因為本機 Factory OAuth/keyring 驗證無法攜入容器。它使用 ACPX 的內建 `droid exec --output-format acp` 登錄項目。
- OpenCode Docker 變體是嚴格的單一 agent regression lane。它會在載入 `~/.profile` 後，從 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（預設 `opencode/kimi-k2.6`）寫入暫時的 `OPENCODE_CONFIG_CONTENT` 預設模型，而且 `pnpm test:docker:live-acp-bind:opencode` 會要求已綁定的 assistant 逐字稿，而不是接受一般的綁定後略過。
- 直接呼叫 `acpx` CLI 只是用於在 Gateway 外比較行為的手動/因應路徑。Docker ACP 綁定 smoke 會測試 OpenClaw 內嵌的 `acpx` runtime 後端。
+- 它會載入 `~/.profile`，將相符的 CLI 驗證資料暫存到容器中，然後在缺少時安裝要求的即時 CLI（`@anthropic-ai/claude-code`、`@openai/codex`、透過 `https://app.factory.ai/cli` 的 Factory Droid、`@google/gemini-cli` 或 `opencode-ai`）。ACP 後端本身是官方 `acpx` Plugin 中內嵌的 `acpx/runtime` 套件。
+- Droid Docker 變體會暫存 `~/.factory` 作為設定，轉送 `FACTORY_API_KEY`，並要求該 API 金鑰，因為本機 Factory OAuth／鑰匙圈驗證無法攜入容器。它使用 ACPX 內建的 `droid exec --output-format acp` 登錄項目。
+- OpenCode Docker 變體是嚴格的單一代理回歸通道。它會在載入 `~/.profile` 後，從 `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL`（預設 `opencode/kimi-k2.6`）寫入暫時的 `OPENCODE_CONFIG_CONTENT` 預設模型，且 `pnpm test:docker:live-acp-bind:opencode` 會要求已綁定的助理記錄，而不是接受一般的綁定後略過。
+- 直接 `acpx` CLI 呼叫僅是用於在 Gateway 外比較行為的手動／權宜路徑。Docker ACP 綁定煙霧測試會測試 OpenClaw 內嵌的 `acpx` 執行階段後端。

-## 即時：Codex app-server harness smoke
+## 即時：Codex 應用伺服器測試框架煙霧測試

- 目標：透過一般 gateway `agent` 方法驗證 Plugin 擁有的 Codex harness：
-  - 載入隨附的 `codex` Plugin
+- 目標：透過一般 Gateway
+  `agent` 方法驗證 Plugin 擁有的 Codex 測試框架：
+  - 載入內建 `codex` Plugin
  - 選取 `OPENCLAW_AGENT_RUNTIME=codex`
-  - 在強制使用 Codex harness 的情況下，將第一個 gateway agent 回合傳送到 `openai/gpt-5.5`
-  - 將第二個回合傳送到同一個 OpenClaw 工作階段，並驗證 app-server thread 可以恢復
-  - 透過同一個 gateway command 路徑執行 `/codex status` 和 `/codex models`
-  - 選擇性執行兩個經 Guardian 審查的 escalated shell 探測：一個應核准的良性 command，以及一個應拒絕、讓 agent 回問的假 secret 上傳
+  - 在強制使用 Codex 測試框架的情況下，向 `openai/gpt-5.5` 傳送第一個 Gateway 代理回合
+  - 向同一個 OpenClaw 工作階段傳送第二個回合，並確認應用伺服器
+    執行緒可恢復
+  - 透過相同的 Gateway 命令
+    路徑執行 `/codex status` 和 `/codex models`
+  - 選擇性執行兩個經 Guardian 審核的提升權限 shell 探測：一個應核准的良性
+    命令，以及一個應拒絕的假秘密上傳，讓代理回問
 - 測試：`src/gateway/gateway-codex-harness.live.test.ts`
 - 啟用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
 - 預設模型：`openai/gpt-5.5`
- 選用影像探測：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- 選用 MCP/tool 探測：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
+- 選用圖片探測：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
+- 選用 MCP／工具探測：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
 - 選用 Guardian 探測：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- smoke 使用 `agentRuntime.id: "codex"`，因此損壞的 Codex harness 無法透過靜默回退到 PI 而通過。
- 驗證：來自本機 Codex 訂閱登入的 Codex app-server 驗證。Docker smoke 在適用時也可以為非 Codex 探測提供 `OPENAI_API_KEY`，再加上選用複製的 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
+- 煙霧測試使用 `agentRuntime.id: "codex"`，因此壞掉的 Codex 測試框架無法
+  透過靜默退回 PI 而通過。
+- 驗證：來自本機 Codex 訂閱登入的 Codex 應用伺服器驗證。Docker
+  煙霧測試也可以在適用時為非 Codex 探測提供 `OPENAI_API_KEY`，
+  並可選擇性複製 `~/.codex/auth.json` 和 `~/.codex/config.toml`。

 本機配方：

@ -314,49 +331,56 @@ pnpm test:docker:live-codex-harness

 Docker 注意事項：

- Docker runner 位於 `scripts/test-live-codex-harness-docker.sh`。
- 它會載入掛載的 `~/.profile`、傳遞 `OPENAI_API_KEY`、在存在時複製 Codex CLI 驗證檔案、將 `@openai/codex` 安裝到可寫入的掛載 npm 前綴、暫存原始碼樹，然後只執行 Codex-harness 即時測試。
- Docker 預設啟用影像、MCP/tool 和 Guardian 探測。當你需要較窄的除錯執行時，設定 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`、`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
- Docker 使用相同的明確 Codex runtime config，因此舊版別名或 PI 回退無法隱藏 Codex harness regression。
+- Docker 執行器位於 `scripts/test-live-codex-harness-docker.sh`。
+- 它會載入掛載的 `~/.profile`、傳遞 `OPENAI_API_KEY`、在存在時複製 Codex CLI
+  驗證檔案、將 `@openai/codex` 安裝到可寫入的掛載 npm
+  前綴、暫存原始碼樹，然後只執行 Codex 測試框架即時測試。
+- Docker 預設啟用圖片、MCP／工具和 Guardian 探測。當你需要較窄的除錯
+  執行時，請設定
+  `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
+  `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
+  `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
+- Docker 使用相同的明確 Codex 執行階段設定，因此舊版別名或 PI
+  退回無法隱藏 Codex 測試框架回歸。

 ### 建議的即時配方

-狹窄、明確的 allowlists 最快且最不易不穩定：
+狹窄且明確的允許清單最快且最不容易不穩：

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

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

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

- Google 聚焦（Gemini API key + Antigravity）：
-  - Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+- Google 焦點（Gemini API 金鑰 + Antigravity）：
+  - Gemini（API 金鑰）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
  - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

- Google adaptive thinking smoke：
-  - 如果本機 key 位於 shell profile：`source ~/.profile`
-  - Gemini 3 動態預設值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
+- Google 自適應思考煙霧測試：
+  - 如果本機金鑰位於 shell 設定檔：`source ~/.profile`
+  - Gemini 3 動態預設：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
  - Gemini 2.5 動態預算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`

 注意事項：

- `google/...` 使用 Gemini API（API key）。
- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 風格的 agent endpoint）。
- `google-gemini-cli/...` 使用你機器上的本機 Gemini CLI（獨立的驗證與工具特性）。
+- `google/...` 使用 Gemini API（API 金鑰）。
+- `google-antigravity/...` 使用 Antigravity OAuth 橋接器（Cloud Code Assist 風格代理端點）。
+- `google-gemini-cli/...` 使用你機器上的本機 Gemini CLI（獨立驗證 + 工具行為差異）。
 - Gemini API 與 Gemini CLI：
-  - API：OpenClaw 透過 HTTP 呼叫 Google 託管的 Gemini API（API key / profile 驗證）；這是大多數使用者所說的「Gemini」。
-  - CLI：OpenClaw shell out 到本機 `gemini` binary；它有自己的驗證，而且行為可能不同（streaming/tool 支援/版本落差）。
+  - API：OpenClaw 透過 HTTP 呼叫 Google 託管的 Gemini API（API 金鑰／設定檔驗證）；這是大多數使用者所指的「Gemini」。
+  - CLI：OpenClaw 會 shell 到本機 `gemini` 二進位檔；它有自己的驗證方式，且可能表現不同（串流／工具支援／版本偏差）。

-## 即時：模型矩陣（我們涵蓋的範圍）
+## 即時：模型矩陣（涵蓋範圍）

-沒有固定的「CI 模型清單」（即時測試為選擇加入），但以下是在具備 key 的開發機上建議定期涵蓋的模型。
+沒有固定的「CI 模型清單」（即時測試需選擇加入），但以下是建議在有金鑰的開發機上定期涵蓋的**建議**模型。

-### 現代 smoke 組合（tool calling + image）
+### 現代煙霧測試集合（工具呼叫 + 圖片）

-這是我們期望持續運作的「常用模型」執行：
+這是我們預期要持續可用的「常用模型」執行：

 - OpenAI（非 Codex）：`openai/gpt-5.5`
 - OpenAI Codex OAuth：`openai-codex/gpt-5.5`
@ -367,12 +391,12 @@ Docker 注意事項：
 - Z.AI（GLM）：`zai/glm-5.1`
 - MiniMax：`minimax/MiniMax-M2.7`

-使用 tools + image 執行 gateway smoke：
+使用工具 + 圖片執行 Gateway 煙霧測試：
 `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

-### 基準線：tool calling（Read + 選用 Exec）
+### 基準：工具呼叫（Read + 選用 Exec）

-每個 provider 系列至少選一個：
+每個供應商家族至少挑選一個：

 - OpenAI：`openai/gpt-5.5`
 - Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
@ -381,81 +405,81 @@ Docker 注意事項：
 - Z.AI（GLM）：`zai/glm-5.1`
 - MiniMax：`minimax/MiniMax-M2.7`

-選用的額外涵蓋範圍（有則更好）：
+選用的額外涵蓋（建議具備）：

 - xAI：`xai/grok-4.3`（或最新可用版本）
- Mistral：`mistral/`…（挑一個你已啟用且支援「tools」的模型）
+- Mistral：`mistral/`…（挑選一個你已啟用且支援「tools」的模型）
 - Cerebras：`cerebras/`…（如果你有存取權）
- LM Studio：`lmstudio/`…（本機；tool calling 取決於 API 模式）
+- LM Studio：`lmstudio/`…（本機；工具呼叫取決於 API 模式）

-### Vision：影像傳送（attachment → multimodal message）
+### 視覺：圖片傳送（附件 → 多模態訊息）

-在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中包含至少一個支援影像的模型（Claude/Gemini/OpenAI 支援 vision 的變體等），以測試影像探測。
+在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一個支援圖片的模型（Claude／Gemini／支援視覺的 OpenAI 變體等），以測試圖片探測。

-### Aggregators / 替代 gateway
+### 聚合器／替代閘道

-如果你已啟用 key，我們也支援透過以下方式測試：
+如果你已啟用金鑰，我們也支援透過以下方式測試：

- OpenRouter：`openrouter/...`（數百個模型；使用 `openclaw models scan` 找出支援 tool+image 的候選模型）
- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（透過 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 驗證）
+- OpenRouter：`openrouter/...`（數百個模型；使用 `openclaw models scan` 尋找支援工具 + 圖片的候選項）
+- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（透過 `OPENCODE_API_KEY`／`OPENCODE_ZEN_API_KEY` 驗證）

-你可以納入即時矩陣的更多 provider（如果你有憑證/config）：
+你可以納入即時矩陣的更多供應商（如果你有憑證／設定）：

 - 內建：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
- 透過 `models.providers`（自訂 endpoint）：`minimax`（cloud/API），以及任何與 OpenAI/Anthropic 相容的 proxy（LM Studio、vLLM、LiteLLM 等）
+- 透過 `models.providers`（自訂端點）：`minimax`（雲端／API），以及任何 OpenAI／Anthropic 相容 Proxy（LM Studio、vLLM、LiteLLM 等）

 <Tip>
-不要在文件中硬編碼「所有模型」。權威清單是你機器上 `discoverModels(...)` 回傳的內容，加上可用的 key。
+不要在文件中硬編碼「所有模型」。權威清單是你機器上 `discoverModels(...)` 回傳的內容，加上可用的金鑰。
 </Tip>

-## 憑證（切勿提交）
+## 憑證（絕不提交）

-即時測試會以 CLI 相同的方式探索憑證。實務影響：
+即時測試會以與 CLI 相同的方式探索憑證。實務影響：

- 如果 CLI 可以運作，實際連線測試應該會找到相同的金鑰。
- 如果實際連線測試顯示「沒有憑證」，請用與除錯 `openclaw models list` / 模型選擇相同的方式除錯。
+- 如果 CLI 可用，live 測試應該會找到相同的金鑰。
+- 如果 live 測試顯示「no creds」，請用你偵錯 `openclaw models list` / 模型選擇的相同方式偵錯。

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

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

-## Deepgram 實際連線（音訊轉錄）
+## Deepgram live（音訊轉錄）

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

-## BytePlus 編碼計畫實際連線
+## BytePlus 程式碼規劃 live

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

-## ComfyUI 工作流程媒體實際連線
+## ComfyUI workflow media live

 - 測試：`extensions/comfy/comfy.live.test.ts`
 - 啟用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
 - 範圍：
-  - 測試隨附的 comfy 影像、影片和 `music_generate` 路徑
-  - 除非已設定 `plugins.entries.comfy.config.<capability>`，否則會略過各項能力
-  - 適合在變更 comfy 工作流程提交、輪詢、下載或 Plugin 註冊後使用
+  - 測試隨附的 comfy 圖片、影片與 `music_generate` 路徑
+  - 除非已設定 `plugins.entries.comfy.config.<capability>`，否則略過各項能力
+  - 適合在變更 comfy workflow 提交、輪詢、下載或 Plugin 註冊之後使用

-## 影像生成實際連線
+## 圖像生成 live

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

-對於已出貨的 CLI 路徑，請在供應商/執行階段實際連線測試通過後，加上一個 `infer` 煙霧測試：
+對於已發布的 CLI 路徑，請在 provider/runtime live 測試通過後加入一個 `infer` smoke：

 ```bash
 OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -484,75 +508,75 @@ openclaw infer image generate \
  --json
 ```

-這涵蓋 CLI 引數解析、設定/預設代理解析、隨附 Plugin 啟用、共用影像生成執行階段，以及實際供應商請求。Plugin 相依性預期會在執行階段載入前存在。
+這會涵蓋 CLI 引數解析、設定/default-agent 解析、隨附 Plugin 啟用、共享圖像生成 runtime，以及 live provider 請求。Plugin 依賴項預期會在 runtime 載入前存在。

-## 音樂生成實際連線
+## 音樂生成 live

 - 測試：`extensions/music-generation-providers.live.test.ts`
 - 啟用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- 測試框架：`pnpm test:live:media music`
+- Harness：`pnpm test:live:media music`
 - 範圍：
-  - 測試共用的隨附音樂生成供應商路徑
+  - 測試共享的隨附音樂生成 provider 路徑
  - 目前涵蓋 Google 和 MiniMax
-  - 在探測前，從你的登入 shell（`~/.profile`）載入供應商環境變數
-  - 預設優先使用實際連線/環境 API 金鑰，再使用已儲存的驗證設定檔，因此 `auth-profiles.json` 中過期的測試金鑰不會遮蔽真正的 shell 憑證
-  - 略過沒有可用驗證/設定檔/模型的供應商
-  - 可用時執行兩種宣告的執行階段模式：
-    - 使用僅提示輸入的 `generate`
-    - 當供應商宣告 `capabilities.edit.enabled` 時執行 `edit`
-  - 目前的共用通道涵蓋範圍：
+  - 探測前從你的登入 shell（`~/.profile`）載入 provider 環境變數
+  - 預設優先使用 live/env API 金鑰，而不是已儲存的驗證設定檔，因此 `auth-profiles.json` 中過期的測試金鑰不會遮蔽真正的 shell 認證
+  - 略過沒有可用 auth/profile/model 的 provider
+  - 可用時執行兩種已宣告的 runtime 模式：
+    - 使用僅 prompt 輸入執行 `generate`
+    - 當 provider 宣告 `capabilities.edit.enabled` 時執行 `edit`
+  - 目前共享 lane 涵蓋範圍：
    - `google`：`generate`、`edit`
    - `minimax`：`generate`
-    - `comfy`：獨立的 Comfy 實際連線檔案，不包含在此共用掃描中
- 選用縮小範圍：
+    - `comfy`：獨立的 Comfy live 檔案，不在此共享 sweep 中
+- 可選縮小範圍：
  - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
  - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- 選用驗證行為：
-  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 會強制使用設定檔儲存區驗證，並忽略僅來自環境的覆寫
+- 可選驗證行為：
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 會強制使用設定檔儲存區驗證，並忽略僅 env 的覆寫

-## 影片生成實際連線
+## 影片生成 live

 - 測試：`extensions/video-generation-providers.live.test.ts`
 - 啟用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- 測試框架：`pnpm test:live:media video`
+- Harness：`pnpm test:live:media video`
 - 範圍：
-  - 測試共用的隨附影片生成供應商路徑
-  - 預設使用適合發布的煙霧測試路徑：非 FAL 供應商、每個供應商一個文字轉影片請求、一秒鐘龍蝦提示，以及來自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每個供應商作業上限（預設為 `180000`）
-  - 預設略過 FAL，因為供應商端佇列延遲可能主導發布時間；傳入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可明確執行
-  - 在探測前，從你的登入 shell（`~/.profile`）載入供應商環境變數
-  - 預設優先使用實際連線/環境 API 金鑰，再使用已儲存的驗證設定檔，因此 `auth-profiles.json` 中過期的測試金鑰不會遮蔽真正的 shell 憑證
-  - 略過沒有可用驗證/設定檔/模型的供應商
+  - 測試共享的隨附影片生成 provider 路徑
+  - 預設使用 release-safe smoke 路徑：非 FAL provider、每個 provider 一個 text-to-video 請求、一秒 lobster prompt，以及來自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每個 provider 作業上限（預設為 `180000`）
+  - 預設略過 FAL，因為 provider 端佇列延遲可能主導發布時間；傳入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可明確執行它
+  - 探測前從你的登入 shell（`~/.profile`）載入 provider 環境變數
+  - 預設優先使用 live/env API 金鑰，而不是已儲存的驗證設定檔，因此 `auth-profiles.json` 中過期的測試金鑰不會遮蔽真正的 shell 認證
+  - 略過沒有可用 auth/profile/model 的 provider
  - 預設只執行 `generate`
-  - 設定 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 可在可用時也執行宣告的轉換模式：
-    - 當供應商宣告 `capabilities.imageToVideo.enabled`，且所選供應商/模型在共用掃描中接受以緩衝區為後端的本機影像輸入時，執行 `imageToVideo`
-    - 當供應商宣告 `capabilities.videoToVideo.enabled`，且所選供應商/模型在共用掃描中接受以緩衝區為後端的本機影片輸入時，執行 `videoToVideo`
-  - 目前在共用掃描中已宣告但略過的 `imageToVideo` 供應商：
-    - `vydra`，因為隨附的 `veo3` 僅支援文字，而隨附的 `kling` 需要遠端影像 URL
-  - Vydra 的供應商特定涵蓋範圍：
+  - 設定 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 也會在可用時執行已宣告的轉換模式：
+    - 當 provider 宣告 `capabilities.imageToVideo.enabled`，且所選 provider/model 在共享 sweep 中接受 buffer-backed local 圖像輸入時執行 `imageToVideo`
+    - 當 provider 宣告 `capabilities.videoToVideo.enabled`，且所選 provider/model 在共享 sweep 中接受 buffer-backed local 影片輸入時執行 `videoToVideo`
+  - 目前在共享 sweep 中已宣告但略過的 `imageToVideo` provider：
+    - `vydra`，因為隨附的 `veo3` 只支援文字，而隨附的 `kling` 需要遠端圖像 URL
+  - Provider 專屬的 Vydra 涵蓋範圍：
    - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
-    - 該檔案預設會執行 `veo3` 文字轉影片，以及使用遠端影像 URL 夾具的 `kling` 通道
-  - 目前的 `videoToVideo` 實際連線涵蓋範圍：
-    - 僅當所選模型為 `runway/gen4_aleph` 時執行 `runway`
-  - 目前在共用掃描中已宣告但略過的 `videoToVideo` 供應商：
+    - 該檔案預設會執行 `veo3` text-to-video，以及使用遠端圖像 URL fixture 的 `kling` lane
+  - 目前 `videoToVideo` live 涵蓋範圍：
+    - 只有在所選模型為 `runway/gen4_aleph` 時才涵蓋 `runway`
+  - 目前在共享 sweep 中已宣告但略過的 `videoToVideo` provider：
    - `alibaba`、`qwen`、`xai`，因為這些路徑目前需要遠端 `http(s)` / MP4 參考 URL
-    - `google`，因為目前共用 Gemini/Veo 通道使用以本機緩衝區為後端的輸入，而共用掃描不接受該路徑
-    - `openai`，因為目前共用通道缺少組織特定影片修補/重混存取保證
- 選用縮小範圍：
+    - `google`，因為目前的共享 Gemini/Veo lane 使用 local buffer-backed 輸入，而共享 sweep 不接受該路徑
+    - `openai`，因為目前的共享 lane 缺少 org-specific 影片 inpaint/remix 存取保證
+- 可選縮小範圍：
  - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
  - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
-  - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在預設掃描中包含每個供應商，包括 FAL
-  - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可降低每個供應商的作業上限，用於更積極的煙霧測試執行
- 選用驗證行為：
-  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 會強制使用設定檔儲存區驗證，並忽略僅來自環境的覆寫
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 會在預設 sweep 中包含每個 provider，包括 FAL
+  - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可為積極的 smoke 執行縮短每個 provider 的作業上限
+- 可選驗證行為：
+  - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 會強制使用設定檔儲存區驗證，並忽略僅 env 的覆寫

-## 媒體實際連線測試框架
+## Media live harness

 - 命令：`pnpm test:live:media`
 - 目的：
-  - 透過單一 repo 原生進入點執行共用的影像、音樂和影片實際連線套件
-  - 從 `~/.profile` 自動載入缺少的供應商環境變數
-  - 預設自動將各套件縮小到目前具有可用驗證的供應商
-  - 重複使用 `scripts/test-live.mjs`，因此 Heartbeat 和安靜模式行為會保持一致
+  - 透過單一 repo-native 入口點執行共享的圖像、音樂與影片 live suite
+  - 自動從 `~/.profile` 載入缺少的 provider 環境變數
+  - 預設自動將每個 suite 縮小到目前具有可用驗證的 provider
+  - 重複使用 `scripts/test-live.mjs`，因此 Heartbeat 和 quiet-mode 行為會保持一致
 - 範例：
  - `pnpm test:live:media`
  - `pnpm test:live:media image video --providers openai,google,minimax`
@ -561,4 +585,4 @@ openclaw infer image generate \

 ## 相關

- [測試](/zh-TW/help/testing) — 單元、整合、QA 和 Docker 套件
+- [測試](/zh-TW/help/testing) — unit、integration、QA 和 Docker suite
--- a/docs/zh-TW/plugins/hooks.md
+++ b/docs/zh-TW/plugins/hooks.md
@ -1,26 +1,26 @@
 ---
 read_when:
-    - 你正在建立需要 before_tool_call、before_agent_reply、訊息 hook 或生命週期 hook 的 Plugin
-    - 你需要封鎖、重寫或要求核准來自 Plugin 的工具呼叫
-    - 你正在內部鉤子和 Plugin 鉤子之間做決定
-summary: Plugin 鉤子：攔截代理程式、工具、訊息、工作階段和 Gateway 生命週期事件
+    - 你正在建置一個需要 before_tool_call、before_agent_reply、訊息掛鉤或生命週期掛鉤的 Plugin
+    - 你需要封鎖、重寫，或要求核准來自 Plugin 的工具呼叫
+    - 在內部鉤子與 Plugin 鉤子之間做選擇
+summary: Plugin 掛鉤：攔截代理程式、工具、訊息、工作階段和 Gateway 生命週期事件
 title: Plugin 鉤子
 x-i18n:
-    generated_at: "2026-05-03T21:38:14Z"
+    generated_at: "2026-05-04T18:23:48Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
+    source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
    source_path: plugins/hooks.md
    workflow: 16
 ---

-Plugin hook 是 OpenClaw Plugin 的進程內擴充點。當 Plugin 需要檢查或變更代理程式執行、工具呼叫、訊息流程、工作階段生命週期、子代理程式路由、安裝，或 Gateway 啟動時使用。
+Plugin hooks 是 OpenClaw Plugin 的進程內擴充點。當 Plugin 需要檢查或變更代理執行、工具呼叫、訊息流程、工作階段生命週期、子代理路由、安裝或 Gateway 啟動時，請使用它們。

-如果你需要的是由操作員安裝的小型 `HOOK.md` 指令碼，用於命令和 Gateway 事件，例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`，請改用[內部 hook](/zh-TW/automation/hooks)。
+如果你需要的是一個由操作者安裝的小型 `HOOK.md` 指令碼，用於 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup` 等命令與 Gateway 事件，請改用[內部 hooks](/zh-TW/automation/hooks)。

 ## 快速開始

-從你的 Plugin 進入點使用 `api.on(...)` 註冊具型別的 Plugin hook：
+從你的 Plugin 入口使用 `api.on(...)` 註冊具型別的 Plugin hooks：

 ```typescript
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -52,14 +52,14 @@ export default definePluginEntry({
 });
 ```

-Hook 處理常式會依 `priority` 由高到低循序執行。相同優先順序的 hook 會保留註冊順序。
+Hook 處理常式會依 `priority` 由高到低依序執行。相同優先順序的 hooks 會維持註冊順序。

 `api.on(name, handler, opts?)` 接受：

 - `priority` — 處理常式排序（較高者先執行）。
- `timeoutMs` — 可選的每個 hook 預算。設定後，hook 執行器會在預算用盡後中止該處理常式並繼續下一個，而不是讓緩慢的設定或回想工作消耗呼叫端已設定的模型逾時。省略此值時，會使用 hook 執行器通用套用的預設觀察/決策逾時。
+- `timeoutMs` — 選用的單一 hook 預算。設定後，hook runner 會在預算耗盡後中止該處理常式並繼續下一個，而不是讓緩慢的設定或回憶工作消耗呼叫端設定的模型逾時。省略時會使用 hook runner 通用套用的預設觀察/決策逾時。

-操作員也可以不修補 Plugin 程式碼而設定 hook 預算：
+操作者也可以不修改 Plugin 程式碼就設定 hook 預算：

 ```json
 {
@ -79,62 +79,62 @@ Hook 處理常式會依 `priority` 由高到低循序執行。相同優先順序
 }
 ```

-`hooks.timeouts.<hookName>` 會覆寫 `hooks.timeoutMs`，而後者會覆寫 Plugin 作者在 `api.on(..., { timeoutMs })` 中設定的值。每個已設定的值都必須是正整數，且不得大於 600000 毫秒。已知較慢的 hook 應優先使用每個 hook 的覆寫，避免某個 Plugin 在所有地方都取得較長預算。
+`hooks.timeouts.<hookName>` 會覆寫 `hooks.timeoutMs`，而 `hooks.timeoutMs` 會覆寫 Plugin 作者在 `api.on(..., { timeoutMs })` 設定的值。每個設定值都必須是正整數，且不得大於 600000 毫秒。對已知較慢的 hooks，請優先使用單一 hook 覆寫，避免讓某個 Plugin 到處都取得較長預算。

-每個 hook 都會收到 `event.context.pluginConfig`，也就是註冊該處理常式之 Plugin 的已解析設定。需要目前 Plugin 選項的 hook 決策可使用它；OpenClaw 會針對每個處理常式注入此值，而不會改變其他 Plugin 看到的共享事件物件。
+每個 hook 都會收到 `event.context.pluginConfig`，也就是註冊該處理常式的 Plugin 的已解析設定。當 hook 決策需要目前 Plugin 選項時請使用它；OpenClaw 會逐一處理常式注入此設定，而不會改變其他 Plugin 看到的共享事件物件。

 ## Hook 目錄

-Hook 依其延伸的介面分組。**粗體**名稱接受決策結果（封鎖、取消、覆寫或要求核准）；其餘皆僅供觀察。
+Hooks 依其擴充的表面分組。以**粗體**標示的名稱接受決策結果（封鎖、取消、覆寫或要求核准）；其他全部僅供觀察。

-**代理程式回合**
+**代理回合**

- `before_model_resolve` — 在載入工作階段訊息前覆寫供應商或模型
- `agent_turn_prepare` — 在 prompt hook 之前消耗已排入佇列的 Plugin 回合注入，並加入同回合內容
- `before_prompt_build` — 在模型呼叫前加入動態內容或系統提示文字
- `before_agent_start` — 僅供相容性的合併階段；請優先使用上方兩個 hook
- **`before_agent_reply`** — 以合成回覆或靜默短路模型回合
+- `before_model_resolve` — 在載入工作階段訊息之前覆寫提供者或模型
+- `agent_turn_prepare` — 消耗佇列中的 Plugin 回合注入，並在 prompt hooks 前加入同一回合的脈絡
+- `before_prompt_build` — 在模型呼叫前加入動態脈絡或系統提示文字
+- `before_agent_start` — 僅供相容性的合併階段；請優先使用上方兩個 hooks
+- **`before_agent_reply`** — 使用合成回覆或靜默短路模型回合
 - **`before_agent_finalize`** — 檢查自然最終答案並要求再執行一次模型傳遞
- `agent_end` — 觀察最終訊息、成功狀態和執行期間
- `heartbeat_prompt_contribution` — 為背景監控和生命週期 Plugin 加入僅限 Heartbeat 的內容
+- `agent_end` — 觀察最終訊息、成功狀態與執行時間
+- `heartbeat_prompt_contribution` — 為背景監視器與生命週期 Plugin 加入僅限 Heartbeat 的脈絡

 **對話觀察**

- `model_call_started` / `model_call_ended` — 觀察已清理的供應商/模型呼叫中繼資料、時間、結果，以及有界請求 ID 雜湊，不包含 prompt 或回應內容
- `llm_input` — 觀察供應商輸入（系統提示、prompt、歷史記錄）
- `llm_output` — 觀察供應商輸出
+- `model_call_started` / `model_call_ended` — 觀察已清理的提供者/模型呼叫中繼資料、時間、結果，以及有界的請求 ID 雜湊，不包含提示或回應內容
+- `llm_input` — 觀察提供者輸入（系統提示、提示、歷史）
+- `llm_output` — 觀察提供者輸出

 **工具**

- **`before_tool_call`** — 重寫工具參數、封鎖執行，或要求核准
- `after_tool_call` — 觀察工具結果、錯誤和期間
+- **`before_tool_call`** — 重寫工具參數、封鎖執行或要求核准
+- `after_tool_call` — 觀察工具結果、錯誤與持續時間
 - **`tool_result_persist`** — 重寫由工具結果產生的助理訊息
 - **`before_message_write`** — 檢查或封鎖進行中的訊息寫入（少見）

-**訊息與傳遞**
+**訊息與遞送**

- **`inbound_claim`** — 在代理程式路由前宣告處理傳入訊息（合成回覆）
- `message_received` — 觀察傳入內容、寄件者、執行緒和中繼資料
- **`message_sending`** — 重寫傳出內容或取消傳遞
- `message_sent` — 觀察傳出傳遞成功或失敗
- **`before_dispatch`** — 在通道交接前檢查或重寫傳出分派
- **`reply_dispatch`** — 參與最終回覆分派管線
+- **`inbound_claim`** — 在代理路由前認領入站訊息（合成回覆）
+- `message_received` — 觀察入站內容、傳送者、執行緒與中繼資料
+- **`message_sending`** — 重寫出站內容或取消遞送
+- `message_sent` — 觀察出站遞送成功或失敗
+- **`before_dispatch`** — 在通道交接前檢查或重寫出站派送
+- **`reply_dispatch`** — 參與最終回覆派送管線

 **工作階段與 Compaction**

 - `session_start` / `session_end` — 追蹤工作階段生命週期邊界
- `before_compaction` / `after_compaction` — 觀察或註解 Compaction 週期
+- `before_compaction` / `after_compaction` — 觀察或標註 Compaction 週期
 - `before_reset` — 觀察工作階段重設事件（`/reset`、程式化重設）

-**子代理程式**
+**子代理**

- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — 協調子代理程式路由與完成傳遞
+- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — 協調子代理路由與完成遞送

 **生命週期**

 - `gateway_start` / `gateway_stop` — 隨 Gateway 啟動或停止 Plugin 擁有的服務
- `cron_changed` — 觀察 Gateway 擁有的 Cron 生命週期變更（已新增、已更新、已移除、已開始、已完成、已排程）
- **`before_install`** — 檢查技能或 Plugin 安裝掃描，並可選擇封鎖
+- `cron_changed` — 觀察 Gateway 擁有的 Cron 生命週期變更（新增、更新、移除、已啟動、已完成、已排程）
+- **`before_install`** — 檢查 Skill 或 Plugin 安裝掃描，並可選擇封鎖

 ## 工具呼叫政策

@ -142,11 +142,11 @@ Hook 依其延伸的介面分組。**粗體**名稱接受決策結果（封鎖

 - `event.toolName`
 - `event.params`
- 可選的 `event.runId`
- 可選的 `event.toolCallId`
- 內容欄位，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`、`ctx.runId`、`ctx.jobId`（在 Cron 驅動的執行中設定），以及診斷用的 `ctx.trace`
+- 選用的 `event.runId`
+- 選用的 `event.toolCallId`
+- 脈絡欄位，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`、`ctx.runId`、`ctx.jobId`（在 Cron 驅動的執行中設定），以及診斷用 `ctx.trace`

-它可以傳回：
+它可以回傳：

 ```typescript
 type BeforeToolCallResult = {
@ -169,46 +169,58 @@ type BeforeToolCallResult = {

 規則：

- `block: true` 是終止性決策，會略過較低優先順序的處理常式。
- `block: false` 會被視為沒有決策。
- `params` 會重寫用於執行的工具參數。
- `requireApproval` 會暫停代理程式執行，並透過 Plugin 核准向使用者詢問。`/approve` 命令可以同時核准 exec 和 Plugin 核准。
- 較高優先順序的 hook 要求核准後，較低優先順序的 `block: true` 仍可封鎖。
+- `block: true` 是終止性決策，並會跳過較低優先順序的處理常式。
+- `block: false` 會視為沒有決策。
+- `params` 會重寫執行用的工具參數。
+- `requireApproval` 會暫停代理執行，並透過 Plugin 核准向使用者詢問。`/approve` 命令可以核准 exec 與 Plugin 核准。
+- 較低優先順序的 `block: true` 仍可在較高優先順序的 hook 要求核准後封鎖。
 - `onResolution` 會收到已解析的核准決策 — `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。

-需要主機層級政策的隨附 Plugin 可以使用 `api.registerTrustedToolPolicy(...)` 註冊受信任的工具政策。這些政策會在一般 `before_tool_call` hook 和外部 Plugin 決策之前執行。僅應將它們用於主機信任的閘門，例如工作區政策、預算執行或保留工作流程安全。外部 Plugin 應使用一般的 `before_tool_call` hook。
+需要主機層級政策的內建 Plugin 可以使用 `api.registerTrustedToolPolicy(...)` 註冊受信任的工具政策。這些政策會在一般 `before_tool_call` hooks 和外部 Plugin 決策之前執行。請只將它們用於主機信任的閘門，例如工作區政策、預算執行或保留工作流程安全。外部 Plugin 應使用一般 `before_tool_call` hooks。

 ### 工具結果持久化

-工具結果可以包含結構化的 `details`，用於 UI 呈現、診斷、媒體路由或 Plugin 擁有的中繼資料。請將 `details` 視為執行階段中繼資料，而非 prompt 內容：
+工具結果可以包含結構化的 `details`，用於 UI 呈現、診斷、媒體路由或 Plugin 擁有的中繼資料。請將 `details` 視為執行階段中繼資料，而非提示內容：

- OpenClaw 會在供應商重播和 Compaction 輸入前移除 `toolResult.details`，使中繼資料不會成為模型內容。
- 持久化的工作階段項目只保留有界的 `details`。過大的 details 會以精簡摘要取代，並設為 `persistedDetailsTruncated: true`。
- `tool_result_persist` 和 `before_message_write` 會在最終持久化上限前執行。Hook 仍應保持傳回的 `details` 小巧，並避免只把 prompt 相關文字放在 `details` 中；模型可見的工具輸出應放在 `content`。
+- OpenClaw 會在提供者重放與 Compaction 輸入前移除 `toolResult.details`，因此中繼資料不會變成模型脈絡。
+- 持久化的工作階段項目只會保留有界的 `details`。過大的 details 會被精簡摘要取代，並設定 `persistedDetailsTruncated: true`。
+- `tool_result_persist` 和 `before_message_write` 會在最終持久化上限前執行。Hooks 仍應保持回傳的 `details` 精簡，並避免只把與提示相關的文字放在 `details`；請把模型可見的工具輸出放在 `content`。

-## Prompt 和模型 hook
+## 提示與模型 hooks

-新 Plugin 請使用階段專用的 hook：
+新 Plugin 請使用特定階段的 hooks：

- `before_model_resolve`：只接收目前 prompt 和附件中繼資料。傳回 `providerOverride` 或 `modelOverride`。
- `agent_turn_prepare`：接收目前 prompt、已準備的工作階段訊息，以及為此工作階段耗盡的任何一次性佇列注入。傳回 `prependContext` 或 `appendContext`。
- `before_prompt_build`：接收目前 prompt 和工作階段訊息。傳回 `prependContext`、`appendContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
- `heartbeat_prompt_contribution`：只在 Heartbeat 回合執行，並傳回 `prependContext` 或 `appendContext`。它適用於需要摘要目前狀態、但不變更使用者發起回合的背景監控器。
+- `before_model_resolve`：只接收目前提示與附件中繼資料。回傳 `providerOverride` 或 `modelOverride`。
+- `agent_turn_prepare`：接收目前提示、已準備的工作階段訊息，以及為此工作階段清空的任何精確一次佇列注入。回傳 `prependContext` 或 `appendContext`。
+- `before_prompt_build`：接收目前提示與工作階段訊息。回傳 `prependContext`、`appendContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。
+- `heartbeat_prompt_contribution`：只會在 Heartbeat 回合執行，並回傳 `prependContext` 或 `appendContext`。它適用於需要摘要目前狀態、但不改變使用者啟動回合的背景監視器。

-`before_agent_start` 保留供相容性使用。請優先使用上方明確的 hook，讓你的 Plugin 不依賴舊版合併階段。
+`before_agent_start` 仍保留供相容性使用。請優先使用上方明確的 hooks，避免你的 Plugin 依賴舊版合併階段。

-當 OpenClaw 可以識別作用中執行時，`before_agent_start` 和 `agent_end` 會包含 `event.runId`。相同值也可在 `ctx.runId` 取得。Cron 驅動的執行也會公開 `ctx.jobId`（來源 Cron 工作 ID），讓 Plugin hook 可將指標、副作用或狀態限定於特定排程工作。
+當 OpenClaw 能識別作用中的執行時，`before_agent_start` 和 `agent_end` 會包含 `event.runId`。相同值也可從 `ctx.runId` 取得。Cron 驅動的執行也會公開 `ctx.jobId`（來源 Cron 工作 ID），讓 Plugin hooks 可以將指標、副作用或狀態限定到特定排程工作。

-對於源自通道的執行，`ctx.messageProvider` 是供應商介面，例如 `discord` 或 `telegram`，而當 OpenClaw 能從工作階段金鑰或傳遞中繼資料推導時，`ctx.channelId` 是對話目標識別碼。
+對於通道來源的執行，`ctx.messageProvider` 是提供者表面，例如 `discord` 或 `telegram`，而 `ctx.channelId` 是 OpenClaw 可從工作階段鍵或遞送中繼資料推導時的對話目標識別碼。

-`agent_end` 是觀察 hook，會在回合後以 fire-and-forget 方式執行。Hook 執行器會套用 30 秒逾時，避免卡住的 Plugin 或嵌入端點讓 hook Promise 永久未決。逾時會被記錄，OpenClaw 會繼續；除非 Plugin 也使用自己的中止訊號，否則不會取消 Plugin 擁有的網路工作。
+`agent_end` 是觀察 hook，會在回合結束後以 fire-and-forget 方式執行。Hook runner 會套用 30 秒逾時，因此卡住的 Plugin 或嵌入端點不能讓 hook promise 永遠保持 pending。逾時會被記錄，OpenClaw 會繼續；除非 Plugin 也使用自己的中止訊號，否則不會取消 Plugin 擁有的網路工作。

-使用 `model_call_started` 和 `model_call_ended` 取得不應接收原始 prompt、歷史記錄、回應、標頭、請求主體或供應商請求 ID 的供應商呼叫遙測。這些 hook 包含穩定中繼資料，例如 `runId`、`callId`、`provider`、`model`、可選的 `api`/`transport`、終端 `durationMs`/`outcome`，以及當 OpenClaw 能推導有界供應商請求 ID 雜湊時的 `upstreamRequestIdHash`。
+對於不應接收原始提示、歷史、回應、標頭、請求本文或提供者請求 ID 的提供者呼叫遙測，請使用 `model_call_started` 與 `model_call_ended`。這些 hooks 包含穩定中繼資料，例如 `runId`、`callId`、`provider`、`model`、選用的 `api`/`transport`、終止性的 `durationMs`/`outcome`，以及 OpenClaw 可推導出有界提供者請求 ID 雜湊時的 `upstreamRequestIdHash`。

-`before_agent_finalize` 只會在測試控制架構即將接受自然的最終助理答案時執行。它不是 `/stop` 取消路徑，且不會在使用者中止回合時執行。傳回 `{ action: "revise", reason }` 可要求測試控制架構在最終化前再執行一次模型傳遞，傳回 `{ action:
-"finalize", reason? }` 可強制最終化，或省略結果以繼續。Codex 原生 `Stop` hook 會轉送為此 hook 中的 OpenClaw `before_agent_finalize` 決策。
+`before_agent_finalize` 只會在 harness 即將接受自然的最終助理答案時執行。它不是 `/stop` 取消路徑，也不會在使用者中止回合時執行。回傳 `{ action: "revise", reason }` 可要求 harness 在最終化前再執行一次模型傳遞，回傳 `{ action:
+"finalize", reason? }` 可強制最終化，或省略結果以繼續。Codex 原生 `Stop` hooks 會作為 OpenClaw `before_agent_finalize` 決策轉送到這個 hook。

-需要 `llm_input`、`llm_output`、`before_agent_finalize` 或 `agent_end` 的非隨附 Plugin 必須設定：
+回傳 `action: "revise"` 時，Plugin 可以包含 `retry` 中繼資料，讓額外的模型傳遞有界且可安全重放：
+
+```typescript
+type BeforeAgentFinalizeRetry = {
+  instruction: string;
+  idempotencyKey?: string;
+  maxAttempts?: number;
+};
+```
+
+`instruction` 會附加到傳送給 harness 的修訂原因。`idempotencyKey` 讓主機能針對等價的最終化決策，計算同一個 Plugin 請求的重試次數，而 `maxAttempts` 會限制主機在繼續使用自然最終答案前允許多少次額外傳遞。
+
+需要 `llm_input`、`llm_output`、`before_agent_finalize` 或 `agent_end` 的非內建 Plugin 必須設定：

 ```json
 {
@ -224,65 +236,68 @@ type BeforeToolCallResult = {
 }
 ```

-可依每個 Plugin 使用 `plugins.entries.<id>.hooks.allowPromptInjection=false` 停用會變更 prompt 的 hook 和持久的下一回合注入。
+可逐一 Plugin 使用 `plugins.entries.<id>.hooks.allowPromptInjection=false` 停用會修改提示的 hooks 與持久的下一回合注入。

 ### 工作階段擴充與下一回合注入

-工作流程 Plugin 可以使用 `api.registerSessionExtension(...)` 持久化小型 JSON 相容的工作階段狀態，並透過 Gateway `sessions.pluginPatch` 方法更新它。工作階段資料列會透過 `pluginExtensions` 投射已註冊的擴充狀態，讓 Control UI 和其他用戶端無需了解 Plugin 內部即可呈現 Plugin 擁有的狀態。
+工作流程 Plugin 可以透過 `api.registerSessionExtension(...)` 持久化小型 JSON 相容的會話狀態，並透過 Gateway 的 `sessions.pluginPatch` 方法更新。會話列會透過 `pluginExtensions` 投影已註冊的擴充狀態，讓控制 UI 和其他用戶端能夠呈現 Plugin 擁有的狀態，而不需要了解 Plugin 內部實作。

-當 Plugin 需要持久性上下文準確地只到達下一個模型回合一次時，請使用 `api.enqueueNextTurnInjection(...)`。OpenClaw 會在提示掛鉤之前清空佇列中的注入、丟棄過期的注入，並依每個 Plugin 使用 `idempotencyKey` 去重。這是核准恢復、政策摘要、背景監控差異，以及應在下一回合對模型可見但不應成為永久系統提示文字的命令延續的正確切入點。
+當 Plugin 需要將持久內容精確傳遞到下一次模型回合一次時，請使用 `api.enqueueNextTurnInjection(...)`。OpenClaw 會在提示 hooks 之前排出佇列中的注入、丟棄已過期的注入，並依每個 Plugin 的 `idempotencyKey` 進行去重。這是核准恢復、政策摘要、背景監視器差異，以及應在下一回合對模型可見但不應成為永久系統提示文字的命令延續的正確接縫。

-清理語意是合約的一部分。工作階段擴充清理與執行階段生命週期清理回呼會收到 `reset`、`delete`、`disable` 或 `restart`。主機會在 reset/delete/disable 時移除所屬 Plugin 的持久性工作階段擴充狀態與待處理的下一回合注入；restart 會保留持久性工作階段狀態，同時清理回呼可讓 Plugin 釋放排程器工作、執行內容，以及舊執行階段世代的其他頻外資源。
+清理語意是合約的一部分。會話擴充清理和執行階段生命週期清理回呼會收到 `reset`、`delete`、`disable` 或 `restart`。主機會在 reset/delete/disable 時移除擁有該會話擴充狀態的 Plugin 的持久化狀態與待處理的下一回合注入；restart 會保留持久會話狀態，同時清理回呼讓 Plugin 釋放排程器工作、執行內容，以及舊執行階段世代的其他頻外資源。

-## 訊息掛鉤
+## 訊息 hooks

-將訊息掛鉤用於頻道層級的路由與傳遞政策：
+使用訊息 hooks 處理通道層級的路由和傳遞政策：

- `message_received`：觀察傳入內容、傳送者、`threadId`、`messageId`、`senderId`、選用的執行/工作階段關聯，以及中繼資料。
+- `message_received`：觀察傳入內容、寄件者、`threadId`、`messageId`、`senderId`、選用的執行/會話關聯，以及中繼資料。
 - `message_sending`：重寫 `content` 或回傳 `{ cancel: true }`。
 - `message_sent`：觀察最終成功或失敗。

-對於僅音訊的 TTS 回覆，即使頻道酬載沒有可見文字/標題，`content` 也可能包含隱藏的口述文字稿。重寫該 `content` 只會更新掛鉤可見的文字稿；它不會被呈現為媒體標題。
+對於僅音訊的 TTS 回覆，即使通道承載沒有可見文字/標題，`content` 也可能包含隱藏的語音轉錄。重寫該 `content` 只會更新 hook 可見的轉錄；它不會呈現為媒體標題。

-訊息掛鉤內容會在可用時公開穩定的關聯欄位：`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在讀取舊版中繼資料之前，請優先使用這些一級欄位。
+訊息 hook 內容會在可用時公開穩定的關聯欄位：`ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在讀取舊版中繼資料之前，優先使用這些一級欄位。

-在使用頻道特定中繼資料之前，請優先使用具型別的 `threadId` 和 `replyToId` 欄位。
+使用通道特定中繼資料之前，請優先使用具型別的 `threadId` 和 `replyToId` 欄位。

 決策規則：

 - 帶有 `cancel: true` 的 `message_sending` 是終止性決策。
 - 帶有 `cancel: false` 的 `message_sending` 會被視為沒有決策。
- 重寫後的 `content` 會繼續傳遞至較低優先順序的掛鉤，除非後續掛鉤取消傳遞。
+- 重寫後的 `content` 會繼續傳遞給較低優先順序的 hooks，除非後續 hook 取消傳遞。

-## 安裝掛鉤
+## 安裝 hooks

-`before_install` 會在內建掃描 Skills 與 Plugin 安裝之後執行。回傳額外發現，或回傳 `{ block: true, blockReason }` 以停止安裝。
+`before_install` 會在內建 Skills 和 Plugin 安裝掃描之後執行。回傳其他發現，或回傳 `{ block: true, blockReason }` 以停止安裝。

 `block: true` 是終止性決策。`block: false` 會被視為沒有決策。

 ## Gateway 生命週期

-將 `gateway_start` 用於需要 Gateway 擁有狀態的 Plugin 服務。內容會公開 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，以供 Cron 檢查與更新。使用 `gateway_stop` 清理長時間執行的資源。
+對於需要 Gateway 擁有狀態的 Plugin 服務，請使用 `gateway_start`。內容會公開 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，用於 Cron 檢查與更新。使用 `gateway_stop` 清理長時間執行的資源。

-不要依賴內部 `gateway:startup` 掛鉤來處理 Plugin 擁有的執行階段服務。
+不要依賴內部 `gateway:startup` hook 來處理 Plugin 擁有的執行階段服務。

-`cron_changed` 會針對 Gateway 擁有的 Cron 生命週期事件觸發，並附帶涵蓋 `added`、`updated`、`removed`、`started`、`finished` 和 `scheduled` 原因的具型別事件酬載。事件會攜帶 `PluginHookGatewayCronJob` 快照（包含 `state.nextRunAtMs`、`state.lastRunStatus`，以及存在時的 `state.lastError`）加上 `PluginHookGatewayCronDeliveryStatus`，其值為 `not-requested` | `delivered` | `not-delivered` | `unknown`。移除事件仍會攜帶已刪除的工作快照，讓外部排程器可以協調狀態。同步外部喚醒排程器時，請使用執行階段內容中的 `ctx.getCron?.()` 和 `ctx.config`，並讓 OpenClaw 作為到期檢查與執行的事實來源。
+`cron_changed` 會針對 Gateway 擁有的 Cron 生命週期事件觸發，並帶有具型別的事件承載，涵蓋 `added`、`updated`、`removed`、`started`、`finished` 和 `scheduled` 原因。事件會攜帶 `PluginHookGatewayCronJob` 快照（包括存在時的 `state.nextRunAtMs`、`state.lastRunStatus` 和 `state.lastError`），以及 `PluginHookGatewayCronDeliveryStatus`，其值為 `not-requested` | `delivered` | `not-delivered` | `unknown`。移除事件仍會攜帶已刪除工作的快照，讓外部排程器可以協調狀態。同步外部喚醒排程器時，請使用執行階段內容中的 `ctx.getCron?.()` 和 `ctx.config`，並讓 OpenClaw 作為到期檢查與執行的真實來源。

-## 即將棄用
+## 即將淘汰

-少數與掛鉤相鄰的介面已棄用但仍受支援。請在下一個主要版本之前遷移：
+少數 hook 相鄰介面已淘汰但仍受支援。請在下一個主要版本之前遷移：

- `inbound_claim` 和 `message_received` 處理常式中的**純文字頻道信封**。請讀取 `BodyForAgent` 和結構化的使用者內容區塊，而不是剖析扁平的信封文字。請參閱[純文字頻道信封 → BodyForAgent](/zh-TW/plugins/sdk-migration#active-deprecations)。
- **`before_agent_start`** 仍為相容性保留。新的 Plugin 應使用 `before_model_resolve` 和 `before_prompt_build`，而不是合併階段。
- **`before_tool_call` 中的 `onResolution`** 現在使用具型別的 `PluginApprovalResolution` 聯集（`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`），而不是自由格式的 `string`。
+- `inbound_claim` 和 `message_received` 處理常式中的**純文字通道信封**。請讀取 `BodyForAgent` 和結構化使用者內容區塊，而不是解析扁平信封文字。請參閱
+  [純文字通道信封 → BodyForAgent](/zh-TW/plugins/sdk-migration#active-deprecations)。
+- **`before_agent_start`** 仍保留以維持相容性。新的 Plugin 應使用 `before_model_resolve` 和 `before_prompt_build`，而不是合併階段。
+- **`before_tool_call` 中的 `onResolution`** 現在使用具型別的 `PluginApprovalResolution` 聯集（`allow-once` / `allow-always` / `deny` /
+  `timeout` / `cancelled`），而不是自由格式的 `string`。

-完整清單，包括記憶體能力註冊、供應商思考設定檔、外部驗證供應商、供應商探索型別、任務執行階段存取器，以及 `command-auth` → `command-status` 重新命名，請參閱 [Plugin SDK 遷移 → 作用中的棄用項目](/zh-TW/plugins/sdk-migration#active-deprecations)。
+如需完整清單，包括記憶體能力註冊、提供者思考設定檔、外部驗證提供者、提供者探索型別、任務執行階段存取器，以及 `command-auth` → `command-status` 重新命名，請參閱
+[Plugin SDK 遷移 → 作用中的淘汰項目](/zh-TW/plugins/sdk-migration#active-deprecations)。

 ## 相關

- [Plugin SDK 遷移](/zh-TW/plugins/sdk-migration) — 作用中的棄用項目與移除時間表
+- [Plugin SDK 遷移](/zh-TW/plugins/sdk-migration) — 作用中的淘汰項目與移除時間表
 - [建置 Plugin](/zh-TW/plugins/building-plugins)
 - [Plugin SDK 概觀](/zh-TW/plugins/sdk-overview)
 - [Plugin 進入點](/zh-TW/plugins/sdk-entrypoints)
- [內部掛鉤](/zh-TW/automation/hooks)
- [Plugin 架構內部原理](/zh-TW/plugins/architecture-internals)
+- [內部 hooks](/zh-TW/automation/hooks)
+- [Plugin 架構內部實作](/zh-TW/plugins/architecture-internals)
--- a/docs/zh-TW/plugins/sdk-overview.md
+++ b/docs/zh-TW/plugins/sdk-overview.md
@ -1,30 +1,28 @@
 ---
 read_when:
    - 你需要知道要從哪個 SDK 子路徑匯入
-    - 您需要 OpenClawPluginApi 上所有註冊方法的參考資料
-    - 你正在查詢特定的 SDK 匯出項目
+    - 你需要一份 OpenClawPluginApi 上所有註冊方法的參考文件
+    - 您正在查詢特定的 SDK 匯出項
 sidebarTitle: Plugin SDK overview
 summary: 匯入對應表、註冊 API 參考與 SDK 架構
-title: Plugin SDK 概覽
+title: Plugin SDK 概觀
 x-i18n:
-    generated_at: "2026-05-02T02:56:41Z"
+    generated_at: "2026-05-04T18:24:39Z"
    model: gpt-5.5
    provider: openai
-    source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
+    source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
    source_path: plugins/sdk-overview.md
    workflow: 16
 ---

-Plugin SDK 是 Plugin 與核心之間的型別化合約。此頁面是
-**要匯入什麼**以及**可以註冊什麼**的參考資料。
+Plugin SDK 是 Plugin 與核心之間的型別化契約。此頁是 **要匯入什麼** 與 **可以註冊什麼** 的參考。

 <Note>
-  此頁面適用於在 OpenClaw 內部使用 `openclaw/plugin-sdk/*` 的 Plugin 作者。對於想要透過 Gateway 執行代理程式的外部應用程式、腳本、儀表板、CI 工作和 IDE 擴充功能，請改用
-  [OpenClaw App SDK](/zh-TW/concepts/openclaw-sdk) 和 `@openclaw/sdk` 套件。
+  此頁適用於在 OpenClaw 內使用 `openclaw/plugin-sdk/*` 的 Plugin 作者。若是想要透過 Gateway 執行代理程式的外部應用程式、指令碼、儀表板、CI 作業與 IDE 擴充功能，請改用 [OpenClaw App SDK](/zh-TW/concepts/openclaw-sdk) 與 `@openclaw/sdk` 套件。
 </Note>

 <Tip>
-想找操作指南嗎？從[建置 Plugin](/zh-TW/plugins/building-plugins) 開始；通道 Plugin 請使用[通道 Plugin](/zh-TW/plugins/sdk-channel-plugins)，供應者 Plugin 請使用[供應者 Plugin](/zh-TW/plugins/sdk-provider-plugins)，工具或生命週期 hook Plugin 請使用 [Plugin hooks](/zh-TW/plugins/hooks)。
+想找操作指南嗎？請從 [建置 Plugin](/zh-TW/plugins/building-plugins) 開始；通道 Plugin 請使用 [通道 Plugin](/zh-TW/plugins/sdk-channel-plugins)，提供者 Plugin 請使用 [提供者 Plugin](/zh-TW/plugins/sdk-provider-plugins)，工具或生命週期掛鉤 Plugin 請使用 [Plugin 掛鉤](/zh-TW/plugins/hooks)。
 </Tip>

 ## 匯入慣例
@ -36,50 +34,27 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 ```

-每個子路徑都是小型且自包含的模組。這能讓啟動保持快速，並
-避免循環依賴問題。對於通道專屬的進入點/建置輔助工具，
-偏好使用 `openclaw/plugin-sdk/channel-core`；將 `openclaw/plugin-sdk/core` 保留給
-更廣泛的總覽介面，以及像
-`buildChannelConfigSchema` 這類共用輔助工具。
+每個子路徑都是小型且自足的模組。這能讓啟動保持快速，並避免循環相依問題。對於通道專屬的進入點/建置輔助工具，優先使用 `openclaw/plugin-sdk/channel-core`；將 `openclaw/plugin-sdk/core` 保留給更廣泛的總括表面，以及像 `buildChannelConfigSchema` 這樣的共用輔助工具。

-對於通道設定，請透過 `openclaw.plugin.json#channelConfigs` 發布通道擁有的 JSON Schema。`plugin-sdk/channel-config-schema`
-子路徑用於共用 schema 基本元件和通用建構器。OpenClaw 的
-內建 Plugin 使用 `plugin-sdk/bundled-channel-config-schema` 來保留
-內建通道 schema。已棄用的相容性匯出仍保留在
-`plugin-sdk/channel-config-schema-legacy`；這兩個內建 schema 子路徑都不是
-新 Plugin 的模式。
+對於通道設定，請透過 `openclaw.plugin.json#channelConfigs` 發布通道擁有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路徑用於共用結構描述原語與通用建構器。OpenClaw 內建 Plugin 使用 `plugin-sdk/bundled-channel-config-schema` 來保留內建通道結構描述。已淘汰的相容性匯出仍保留在 `plugin-sdk/channel-config-schema-legacy`；這兩個內建結構描述子路徑都不是新 Plugin 應採用的模式。

 <Warning>
-  請勿匯入帶有供應者或通道品牌的便利接縫（例如
-  `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。
-  內建 Plugin 會在自己的 `api.ts` /
-  `runtime-api.ts` barrel 中組合通用 SDK 子路徑；核心消費者應使用這些 Plugin 本地
-  barrel，或在需求確實跨通道時新增狹窄的通用 SDK 合約。
+  請勿匯入提供者或通道品牌化的便利接縫（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。內建 Plugin 會在各自的 `api.ts` / `runtime-api.ts` barrel 內組合通用 SDK 子路徑；核心消費者應使用那些 Plugin 本地的 barrel，或在需求確實跨通道時新增狹窄的通用 SDK 契約。

-少量內建 Plugin 輔助接縫在有追蹤到擁有者使用情況時，仍會出現在產生的匯出
-對映中。它們僅供內建 Plugin
-維護使用，不建議作為新的第三方
-Plugin 的匯入路徑。
+少數內建 Plugin 輔助接縫在有追蹤到擁有者使用時，仍會出現在產生的匯出對應中。它們僅供內建 Plugin 維護使用，不建議作為新的第三方 Plugin 匯入路徑。

-`openclaw/plugin-sdk/discord` 和 `openclaw/plugin-sdk/telegram-account` 也
-保留為已棄用的相容性 facade，供追蹤到的擁有者使用。請勿
-將這些匯入路徑複製到新的 Plugin；請改用注入的執行階段輔助工具和
-通用通道 SDK 子路徑。
+`openclaw/plugin-sdk/discord` 與 `openclaw/plugin-sdk/telegram-account` 也會作為已淘汰的相容性 facade 保留給已追蹤的擁有者使用。請勿將這些匯入路徑複製到新 Plugin；請改用注入的執行階段輔助工具與通用通道 SDK 子路徑。
 </Warning>

 ## 子路徑參考

-Plugin SDK 以一組依領域分組的狹窄子路徑公開（Plugin
-進入點、通道、供應者、驗證、執行階段、能力、記憶體，以及保留的
-內建 Plugin 輔助工具）。完整目錄按群組整理並附有連結，請參閱
-[Plugin SDK 子路徑](/zh-TW/plugins/sdk-subpaths)。
+Plugin SDK 以一組按領域分組的狹窄子路徑公開（Plugin 進入點、通道、提供者、驗證、執行階段、能力、記憶體，以及保留的內建 Plugin 輔助工具）。完整目錄（已分組並附連結）請參閱 [Plugin SDK 子路徑](/zh-TW/plugins/sdk-subpaths)。

 產生的 200 多個子路徑清單位於 `scripts/lib/plugin-sdk-entrypoints.json`。

 ## 註冊 API

-`register(api)` 回呼會接收一個 `OpenClawPluginApi` 物件，其中包含這些
-方法：
+`register(api)` 回呼會收到一個具有以下方法的 `OpenClawPluginApi` 物件：

 ### 能力註冊

@ -96,97 +71,79 @@ Plugin SDK 以一組依領域分組的狹窄子路徑公開（Plugin
 | `api.registerImageGenerationProvider(...)`       | 影像生成                              |
 | `api.registerMusicGenerationProvider(...)`       | 音樂生成                              |
 | `api.registerVideoGenerationProvider(...)`       | 影片生成                              |
-| `api.registerWebFetchProvider(...)`              | 網頁擷取 / 擷取供應者                 |
+| `api.registerWebFetchProvider(...)`              | 網頁擷取 / 擷取提供者                 |
 | `api.registerWebSearchProvider(...)`             | 網頁搜尋                              |

 ### 工具與命令

-| 方法                           | 註冊內容                                      |
-| ------------------------------ | --------------------------------------------- |
+| 方法                            | 註冊內容                                      |
+| ------------------------------- | --------------------------------------------- |
 | `api.registerTool(tool, opts?)` | 代理程式工具（必要或 `{ optional: true }`）   |
 | `api.registerCommand(def)`      | 自訂命令（繞過 LLM）                          |

-當代理程式需要簡短、由命令擁有的路由提示時，Plugin 命令可以設定 `agentPromptGuidance`。請讓該文字聚焦於命令本身；不要將
-供應者或 Plugin 專屬政策加入核心提示建構器。
+當代理程式需要由命令擁有的簡短路由提示時，Plugin 命令可以設定 `agentPromptGuidance`。該文字應聚焦於命令本身；不要將提供者或 Plugin 專屬政策加入核心提示建構器。

-### 基礎架構
+### 基礎設施

-| 方法                                           | 註冊內容                                |
-| ---------------------------------------------- | --------------------------------------- |
-| `api.registerHook(events, handler, opts?)`     | 事件 hook                               |
-| `api.registerHttpRoute(params)`                | Gateway HTTP 端點                       |
-| `api.registerGatewayMethod(name, handler)`     | Gateway RPC 方法                        |
-| `api.registerGatewayDiscoveryService(service)` | 本機 Gateway 探索廣告器                 |
-| `api.registerCli(registrar, opts?)`            | CLI 子命令                              |
-| `api.registerService(service)`                 | 背景服務                                |
-| `api.registerInteractiveHandler(registration)` | 互動式處理器                            |
-| `api.registerAgentToolResultMiddleware(...)`   | 執行階段工具結果中介軟體                |
-| `api.registerMemoryPromptSupplement(builder)`  | 加成式記憶體相鄰提示區段                |
-| `api.registerMemoryCorpusSupplement(adapter)`  | 加成式記憶體搜尋/讀取語料庫             |
+| 方法                                           | 註冊內容                              |
+| ---------------------------------------------- | ------------------------------------- |
+| `api.registerHook(events, handler, opts?)`     | 事件掛鉤                              |
+| `api.registerHttpRoute(params)`                | Gateway HTTP 端點                     |
+| `api.registerGatewayMethod(name, handler)`     | Gateway RPC 方法                      |
+| `api.registerGatewayDiscoveryService(service)` | 本機 Gateway 探索公告器               |
+| `api.registerCli(registrar, opts?)`            | CLI 子命令                            |
+| `api.registerService(service)`                 | 背景服務                              |
+| `api.registerInteractiveHandler(registration)` | 互動式處理器                          |
+| `api.registerAgentToolResultMiddleware(...)`   | 執行階段工具結果中介軟體              |
+| `api.registerMemoryPromptSupplement(builder)`  | 加成式記憶體相鄰提示區段              |
+| `api.registerMemoryCorpusSupplement(adapter)`  | 加成式記憶體搜尋/讀取語料庫           |

-### 工作流程 Plugin 的主機 hook
+### 工作流程 Plugin 的主機掛鉤

-主機 hook 是需要參與主機生命週期的 Plugin 所使用的 SDK 接縫，而不只是新增供應者、通道或工具。它們是
-通用合約；Plan Mode 可以使用它們，核准工作流程、
-工作區政策閘門、背景監控器、設定精靈和 UI 伴隨
-Plugin 也可以使用。
+主機掛鉤是 SDK 接縫，供需要參與主機生命週期，而不只是新增提供者、通道或工具的 Plugin 使用。它們是通用契約；計畫模式可以使用它們，核准工作流程、工作區政策閘道、背景監控器、設定精靈與 UI 伴隨 Plugin 也可以使用。

-| 方法                                                                     | 它擁有的合約                                                                                                                        |
+| 方法                                                                     | 擁有的契約                                                                                                                          |
 | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `api.registerSessionExtension(...)`                                      | Plugin 擁有、JSON 相容的工作階段狀態，透過 Gateway 工作階段投射                                                                    |
-| `api.enqueueNextTurnInjection(...)`                                      | 對單一工作階段下一個代理程式回合注入的持久、恰好一次內容                                                                            |
-| `api.registerTrustedToolPolicy(...)`                                     | 可封鎖或重寫工具參數的內建/受信任預先 Plugin 工具政策                                                                               |
+| `api.registerSessionExtension(...)`                                      | 由 Plugin 擁有、與 JSON 相容，並透過 Gateway 工作階段投射的工作階段狀態                                                            |
+| `api.enqueueNextTurnInjection(...)`                                      | 針對單一工作階段注入到下一個代理程式回合的持久化、剛好一次內容                                                                     |
+| `api.registerTrustedToolPolicy(...)`                                     | 可封鎖或重寫工具參數的內建/受信任前置 Plugin 工具政策                                                                              |
 | `api.registerToolMetadata(...)`                                          | 不變更工具實作的工具目錄顯示中繼資料                                                                                                |
-| `api.registerCommand(...)`                                               | 具範圍的 Plugin 命令；命令結果可以設定 `continueAgent: true`；Discord 原生命令支援 `descriptionLocalizations`                       |
-| `api.registerControlUiDescriptor(...)`                                   | 工作階段、工具、執行或設定介面的 Control UI 貢獻描述元                                                                              |
-| `api.registerRuntimeLifecycle(...)`                                      | 在重設/刪除/重新載入路徑上清理 Plugin 擁有執行階段資源的回呼                                                                        |
-| `api.registerAgentEventSubscription(...)`                                | 用於工作流程狀態和監控器的已清理事件訂閱                                                                                            |
-| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次執行的 Plugin 暫存狀態，會在終止執行生命週期時清除                                                                              |
-| `api.registerSessionSchedulerJob(...)`                                   | Plugin 擁有的工作階段排程器工作記錄，具決定性清理                                                                                   |
+| `api.registerCommand(...)`                                               | 有範圍的 Plugin 命令；命令結果可設定 `continueAgent: true`；Discord 原生命令支援 `descriptionLocalizations`                         |
+| `api.registerControlUiDescriptor(...)`                                   | 工作階段、工具、執行或設定表面的 Control UI 貢獻描述元                                                                              |
+| `api.registerRuntimeLifecycle(...)`                                      | 在重設/刪除/重新載入路徑上，清理由 Plugin 擁有的執行階段資源之回呼                                                                 |
+| `api.registerAgentEventSubscription(...)`                                | 用於工作流程狀態與監控器的已淨化事件訂閱                                                                                            |
+| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次執行的 Plugin 暫存狀態，會在終端執行生命週期清除                                                                                |
+| `api.registerSessionSchedulerJob(...)`                                   | 由 Plugin 擁有且具決定性清理的工作階段排程器作業記錄                                                                                |

-這些合約刻意拆分權限：
+這些契約刻意拆分權限：

- 外部 Plugin 可以擁有工作階段擴充、UI 描述元、命令、工具
-  中繼資料、下一回合注入和一般 hook。
- 受信任工具政策會在一般 `before_tool_call` hook 之前執行，並且
-  僅限內建，因為它們參與主機安全政策。
- 保留命令所有權僅限內建。外部 Plugin 應使用自己的
-  命令名稱或別名。
- `allowPromptInjection=false` 會停用會變更提示的 hook，包括
-  `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、
-  舊版 `before_agent_start` 的提示欄位，以及
-  `enqueueNextTurnInjection`。
+- 外部 Plugin 可以擁有工作階段擴充、UI 描述元、命令、工具中繼資料、下一回合注入與一般掛鉤。
+- 受信任工具政策會在一般 `before_tool_call` 掛鉤之前執行，且僅限內建，因為它們會參與主機安全政策。
+- 保留命令擁有權僅限內建。外部 Plugin 應使用自己的命令名稱或別名。
+- `allowPromptInjection=false` 會停用會變更提示的掛鉤，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、舊版 `before_agent_start` 的提示欄位，以及 `enqueueNextTurnInjection`。

-非 Plan 使用者範例：
+非計畫消費者範例：

-| Plugin 原型                  | 使用的 hook                                                                                                                          |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| 核准工作流程                 | 工作階段擴充、命令接續、下一回合注入、UI 描述元                                                                                      |
-| 預算/工作區政策閘門          | 受信任工具政策、工具中繼資料、工作階段投射                                                                                           |
-| 背景生命週期監控器           | 執行階段生命週期清理、代理程式事件訂閱、工作階段排程器所有權/清理、Heartbeat 提示貢獻、UI 描述元                                     |
-| 設定或入門精靈               | 工作階段擴充、具範圍的命令、Control UI 描述元                                                                                        |
+| Plugin 原型                 | 使用的掛鉤                                                                                                                          |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| 核准工作流程                | 工作階段擴充、命令延續、下一回合注入、UI 描述元                                                                                    |
+| 預算/工作區政策閘道         | 受信任工具政策、工具中繼資料、工作階段投射                                                                                          |
+| 背景生命週期監控器          | 執行階段生命週期清理、代理程式事件訂閱、工作階段排程器擁有權/清理、Heartbeat 提示貢獻、UI 描述元                                  |
+| 設定或入門精靈              | 工作階段擴充、有範圍的命令、Control UI 描述元                                                                                       |

 <Note>
-  保留的核心管理命名空間（`config.*`、`exec.approvals.*`、`wizard.*`、
-  `update.*`）一律維持 `operator.admin`，即使 Plugin 嘗試指派
-  較窄的 Gateway 方法範圍也一樣。Plugin 擁有的方法請偏好使用 Plugin 專屬前綴。
+  保留的核心管理命名空間（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）一律維持為 `operator.admin`，即使 Plugin 嘗試指派較窄的 Gateway 方法範圍也是如此。Plugin 擁有的方法請優先使用 Plugin 專屬前綴。
 </Note>

 <Accordion title="何時使用工具結果中介軟體">
-  內建 Plugin 可以在需要於執行後、且執行階段將工具結果回饋給模型之前重寫工具結果時，使用 `api.registerAgentToolResultMiddleware(...)`。這是供 tokenjuice 這類非同步輸出縮減器使用的受信任、執行階段中立
-  接縫。
+  內建 Plugin 在需要於執行後、執行階段將工具結果回饋給模型之前重寫工具結果時，可以使用 `api.registerAgentToolResultMiddleware(...)`。這是用於非執行階段特定非同步輸出縮減器（例如 tokenjuice）的受信任接縫。

-內建 Plugin 必須為每個目標執行階段宣告 `contracts.agentToolResultMiddleware`，
-例如 `["pi", "codex"]`。外部 Plugin
-不能註冊此中介軟體；對於不需要模型前工具結果時序的工作，請保留使用一般 OpenClaw Plugin hook。舊的僅限 Pi 的嵌入式
-擴充功能工廠註冊路徑已移除。
+內建 Plugin 必須為每個目標執行階段宣告 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部 Plugin 無法註冊此中介軟體；對於不需要模型前工具結果時機的工作，請使用一般 OpenClaw Plugin 掛鉤。舊的僅限 Pi 內嵌擴充工廠註冊路徑已移除。
 </Accordion>

 ### Gateway 探索註冊

-`api.registerGatewayDiscoveryService(...)` 可讓 Plugin 在 mDNS/Bonjour 等本機探索傳輸上宣告作用中的
-Gateway。啟用本機探索時，OpenClaw 會在 Gateway 啟動期間呼叫該服務、傳入目前的 Gateway 連接埠與非機密的 TXT 提示資料，並在 Gateway 關閉期間呼叫傳回的
-`stop` 處理常式。
+`api.registerGatewayDiscoveryService(...)` 讓 Plugin 在 mDNS/Bonjour 等本機探索傳輸上公告使用中的 Gateway。啟用本機探索時，OpenClaw 會在 Gateway 啟動期間呼叫該服務，傳入目前的 Gateway 連接埠與非機密 TXT 提示資料，並在 Gateway 關閉期間呼叫傳回的 `stop` 處理常式。

 ```typescript
 api.registerGatewayDiscoveryService({
@ -202,16 +159,16 @@ api.registerGatewayDiscoveryService({
 });
 ```

-Gateway 探索 Plugin 不得將宣告的 TXT 值視為機密或驗證資訊。探索只是路由提示；信任仍由 Gateway 驗證與 TLS 釘選負責。
+Gateway 探索 Plugin 不得將公告的 TXT 值視為秘密或驗證。探索只是路由提示；Gateway 驗證與 TLS 釘選仍然負責信任。

 ### CLI 註冊中繼資料

 `api.registerCli(registrar, opts?)` 接受兩種最上層中繼資料：

 - `commands`：由註冊器擁有的明確命令根
- `descriptors`：用於根 CLI 說明、路由，以及延遲 Plugin CLI 註冊的解析時命令描述元
+- `descriptors`：剖析時使用的命令描述元，用於根 CLI 說明、路由，以及延遲 Plugin CLI 註冊

-如果你希望 Plugin 命令在一般根 CLI 路徑中保持延遲載入，請提供涵蓋該註冊器公開的每個最上層命令根的 `descriptors`。
+如果你希望 Plugin 命令在一般根 CLI 路徑中維持延遲載入，請提供涵蓋該註冊器公開之每個最上層命令根的 `descriptors`。

 ```typescript
 api.registerCli(
@ -231,87 +188,84 @@ api.registerCli(
 );
 ```

-只有在不需要延遲根 CLI 註冊時，才單獨使用 `commands`。該即時相容路徑仍受支援，但不會安裝以描述元為後盾、用於解析時延遲載入的預留位置。
+只有在不需要延遲根 CLI 註冊時，才單獨使用 `commands`。該立即載入相容路徑仍受支援，但不會安裝以描述元為後盾、供剖析時延遲載入使用的預留位置。

 ### CLI 後端註冊

-`api.registerCliBackend(...)` 可讓 Plugin 擁有本機 AI CLI 後端（例如 `codex-cli`）的預設設定。
+`api.registerCliBackend(...)` 讓 Plugin 擁有本機 AI CLI 後端的預設設定，例如 `codex-cli`。

- 後端 `id` 會成為模型參照中的提供者前綴，例如 `codex-cli/gpt-5`。
+- 後端 `id` 會成為模型參照中的提供者前置詞，例如 `codex-cli/gpt-5`。
 - 後端 `config` 使用與 `agents.defaults.cliBackends.<id>` 相同的形狀。
- 使用者設定仍然優先。OpenClaw 會在執行 CLI 前，將 `agents.defaults.cliBackends.<id>` 合併到 Plugin 預設值之上。
- 當後端需要在合併後進行相容性重寫時，請使用 `normalizeConfig`（例如正規化舊的旗標形狀）。
+- 使用者設定仍優先。OpenClaw 會先將 `agents.defaults.cliBackends.<id>` 合併覆蓋 Plugin 預設值，再執行 CLI。
+- 當後端需要在合併後進行相容性重寫時，使用 `normalizeConfig`（例如正規化舊旗標形狀）。
+- 對於屬於 CLI 方言的請求範圍 argv 重寫，使用 `resolveExecutionArgs`，例如將 OpenClaw 思考等級對應到原生 effort 旗標。

-### 專屬插槽
+### 獨占插槽

 | 方法                                       | 註冊內容                                                                                                                                                  |
 | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `api.registerContextEngine(id, factory)`   | Context engine（同一時間只有一個作用中）。`assemble()` 回呼會接收 `availableTools` 與 `citationsMode`，讓引擎能調整提示新增內容。 |
-| `api.registerMemoryCapability(capability)` | 統一記憶體能力                                                                                                                                             |
-| `api.registerMemoryPromptSection(builder)` | 記憶體提示區段建構器                                                                                                                                       |
-| `api.registerMemoryFlushPlan(resolver)`    | 記憶體清除計畫解析器                                                                                                                                       |
-| `api.registerMemoryRuntime(runtime)`       | 記憶體執行階段配接器                                                                                                                                       |
+| `api.registerContextEngine(id, factory)`   | 上下文引擎（一次只會有一個啟用）。`assemble()` 回呼會接收 `availableTools` 和 `citationsMode`，讓引擎能調整提示詞附加內容。 |
+| `api.registerMemoryCapability(capability)` | 統一記憶能力                                                                                                                                              |
+| `api.registerMemoryPromptSection(builder)` | 記憶提示詞區段建構器                                                                                                                                      |
+| `api.registerMemoryFlushPlan(resolver)`    | 記憶清除計畫解析器                                                                                                                                        |
+| `api.registerMemoryRuntime(runtime)`       | 記憶執行階段配接器                                                                                                                                        |

-### 記憶體嵌入配接器
+### 記憶嵌入配接器

 | 方法                                           | 註冊內容                         |
 | ---------------------------------------------- | -------------------------------- |
-| `api.registerMemoryEmbeddingProvider(adapter)` | 作用中 Plugin 的記憶體嵌入配接器 |
+| `api.registerMemoryEmbeddingProvider(adapter)` | 供作用中 Plugin 使用的記憶嵌入配接器 |

- `registerMemoryCapability` 是偏好的專屬記憶體 Plugin API。
- `registerMemoryCapability` 也可以公開 `publicArtifacts.listArtifacts(...)`，讓配套 Plugin 能透過
-  `openclaw/plugin-sdk/memory-host-core` 使用匯出的記憶體成品，而不是深入特定記憶體 Plugin 的私有配置。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和
-  `registerMemoryRuntime` 是舊版相容的專屬記憶體 Plugin API。
- `MemoryFlushPlan.model` 可以將清除回合固定到確切的 `provider/model`
-  參照，例如 `ollama/qwen3:8b`，而不繼承作用中的後援鏈。
- `registerMemoryEmbeddingProvider` 可讓作用中的記憶體 Plugin 註冊一個或多個嵌入配接器 ID（例如 `openai`、`gemini`，或自訂的 Plugin 定義 ID）。
- `agents.defaults.memorySearch.provider` 和
-  `agents.defaults.memorySearch.fallback` 等使用者設定會依據那些已註冊的配接器 ID 解析。
+- `registerMemoryCapability` 是偏好的獨占記憶 Plugin API。
+- `registerMemoryCapability` 也可以公開 `publicArtifacts.listArtifacts(...)`，讓同伴 Plugin 能透過 `openclaw/plugin-sdk/memory-host-core` 使用匯出的記憶成品，而不是觸及特定記憶 Plugin 的私有版面配置。
+- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是舊版相容的獨占記憶 Plugin API。
+- `MemoryFlushPlan.model` 可以將清除回合釘選到精確的 `provider/model` 參照，例如 `ollama/qwen3:8b`，而不繼承作用中的後援鏈。
+- `registerMemoryEmbeddingProvider` 讓作用中的記憶 Plugin 註冊一個或多個嵌入配接器 id（例如 `openai`、`gemini`，或自訂的 Plugin 定義 id）。
+- 使用者設定（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）會依據這些已註冊的配接器 id 解析。

 ### 事件與生命週期

-| 方法                                         | 作用             |
-| -------------------------------------------- | ---------------- |
-| `api.on(hookName, handler, opts?)`           | 型別化生命週期 hook |
-| `api.onConversationBindingResolved(handler)` | 對話繫結回呼     |
+| 方法                                         | 作用               |
+| -------------------------------------------- | ------------------ |
+| `api.on(hookName, handler, opts?)`           | 型別化生命週期鉤子 |
+| `api.onConversationBindingResolved(handler)` | 對話繫結回呼       |

-請參閱 [Plugin hooks](/zh-TW/plugins/hooks)，取得範例、常見 hook 名稱與防護語意。
+請參閱 [Plugin 鉤子](/zh-TW/plugins/hooks)，取得範例、常見鉤子名稱，以及防護語義。

-### Hook 決策語意
+### 鉤子決策語義

- `before_tool_call`：傳回 `{ block: true }` 會終止處理。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
+- `before_tool_call`：傳回 `{ block: true }` 是終止決策。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
 - `before_tool_call`：傳回 `{ block: false }` 會被視為沒有決策（等同省略 `block`），而不是覆寫。
- `before_install`：傳回 `{ block: true }` 會終止處理。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
+- `before_install`：傳回 `{ block: true }` 是終止決策。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
 - `before_install`：傳回 `{ block: false }` 會被視為沒有決策（等同省略 `block`），而不是覆寫。
- `reply_dispatch`：傳回 `{ handled: true, ... }` 會終止處理。一旦任何處理常式宣告處理派送，較低優先順序的處理常式與預設模型派送路徑就會被略過。
- `message_sending`：傳回 `{ cancel: true }` 會終止處理。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
+- `reply_dispatch`：傳回 `{ handled: true, ... }` 是終止決策。一旦任何處理常式宣告已處理派送，較低優先順序的處理常式和預設模型派送路徑就會被略過。
+- `message_sending`：傳回 `{ cancel: true }` 是終止決策。一旦任何處理常式設定它，較低優先順序的處理常式就會被略過。
 - `message_sending`：傳回 `{ cancel: false }` 會被視為沒有決策（等同省略 `cancel`），而不是覆寫。
- `message_received`：需要傳入執行緒/主題路由時，請使用型別化的 `threadId` 欄位。將 `metadata` 保留給通道特定的額外資料。
- `message_sending`：先使用型別化的 `replyToId` / `threadId` 路由欄位，再退回使用通道特定的 `metadata`。
- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 取得 Gateway 擁有的啟動狀態，而不是依賴內部 `gateway:startup` hook。
- `cron_changed`：觀察 Gateway 擁有的 Cron 生命週期變更。同步外部喚醒排程器時，使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，並讓 OpenClaw 成為到期檢查與執行的事實來源。
+- `message_received`：當你需要傳入執行緒/主題路由時，使用型別化的 `threadId` 欄位。將 `metadata` 保留給通道特定的額外資料。
+- `message_sending`：在退回到通道特定 `metadata` 之前，先使用型別化的 `replyToId` / `threadId` 路由欄位。
+- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 取得 Gateway 擁有的啟動狀態，而不是依賴內部 `gateway:startup` 鉤子。
+- `cron_changed`：觀察 Gateway 擁有的 Cron 生命週期變更。同步外部喚醒排程器時，使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，並讓 OpenClaw 作為到期檢查與執行的事實來源。

 ### API 物件欄位

-| 欄位                     | 類型                      | 說明                                                                                   |
-| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------- |
-| `api.id`                 | `string`                  | Plugin id                                                                              |
-| `api.name`               | `string`                  | 顯示名稱                                                                               |
-| `api.version`            | `string?`                 | Plugin 版本（選用）                                                                    |
-| `api.description`        | `string?`                 | Plugin 說明（選用）                                                                    |
-| `api.source`             | `string`                  | Plugin 來源路徑                                                                        |
-| `api.rootDir`            | `string?`                 | Plugin 根目錄（選用）                                                                  |
-| `api.config`             | `OpenClawConfig`          | 目前設定快照（可用時為作用中的記憶體內執行階段快照）                                   |
-| `api.pluginConfig`       | `Record<string, unknown>` | 來自 `plugins.entries.<id>.config` 的 Plugin 特定設定                                  |
-| `api.runtime`            | `PluginRuntime`           | [執行階段協助程式](/zh-TW/plugins/sdk-runtime)                                               |
-| `api.logger`             | `PluginLogger`            | 有範圍的記錄器（`debug`、`info`、`warn`、`error`）                                     |
-| `api.registrationMode`   | `PluginRegistrationMode`  | 目前載入模式；`"setup-runtime"` 是完整進入點前的輕量啟動/設定視窗                      |
-| `api.resolvePath(input)` | `(string) => string`      | 解析相對於 Plugin 根目錄的路徑                                                         |
+| 欄位                     | 型別                      | 描述                                                                                       |
+| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
+| `api.id`                 | `string`                  | Plugin id                                                                                  |
+| `api.name`               | `string`                  | 顯示名稱                                                                                   |
+| `api.version`            | `string?`                 | Plugin 版本（選用）                                                                        |
+| `api.description`        | `string?`                 | Plugin 描述（選用）                                                                        |
+| `api.source`             | `string`                  | Plugin 來源路徑                                                                            |
+| `api.rootDir`            | `string?`                 | Plugin 根目錄（選用）                                                                      |
+| `api.config`             | `OpenClawConfig`          | 目前設定快照（可用時為作用中的記憶體內執行階段快照）                                      |
+| `api.pluginConfig`       | `Record<string, unknown>` | 來自 `plugins.entries.<id>.config` 的 Plugin 特定設定                                      |
+| `api.runtime`            | `PluginRuntime`           | [執行階段輔助工具](/zh-TW/plugins/sdk-runtime)                                                   |
+| `api.logger`             | `PluginLogger`            | 範圍化記錄器（`debug`、`info`、`warn`、`error`）                                           |
+| `api.registrationMode`   | `PluginRegistrationMode`  | 目前載入模式；`"setup-runtime"` 是完整進入點前的輕量啟動/設定時段                         |
+| `api.resolvePath(input)` | `(string) => string`      | 解析相對於 Plugin 根目錄的路徑                                                             |

 ## 內部模組慣例

-在你的 Plugin 內，請使用本機 barrel 檔案進行內部匯入：
+在你的 Plugin 內，使用本機 barrel 檔案進行內部匯入：

 ```
 my-plugin/
@ -322,46 +276,45 @@ my-plugin/
 ```

 <Warning>
-  切勿在生產程式碼中透過 `openclaw/plugin-sdk/<your-plugin>`
+  絕不要在生產程式碼中透過 `openclaw/plugin-sdk/<your-plugin>`
  匯入你自己的 Plugin。請透過 `./api.ts` 或
-  `./runtime-api.ts` 路由內部匯入。SDK 路徑僅是外部契約。
+  `./runtime-api.ts` 路由內部匯入。SDK 路徑只屬於外部合約。
 </Warning>

-透過外觀載入的內建 Plugin 公開介面（`api.ts`、`runtime-api.ts`、
-`index.ts`、`setup-entry.ts`，以及類似的公開進入檔案）在 OpenClaw 已執行時，會偏好使用作用中的執行階段設定快照。如果尚未存在執行階段快照，則會退回使用磁碟上已解析的設定檔。
-封裝後的內建 Plugin 外觀應透過 OpenClaw 的 Plugin 外觀載入器載入；直接從 `dist/extensions/...` 匯入會繞過封裝安裝用於 Plugin 擁有程式碼的資訊清單與執行階段 sidecar 檢查。
+透過外觀載入的內建 Plugin 公開介面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts`，以及類似的公開進入檔案），會在 OpenClaw 已在執行時偏好使用作用中的執行階段設定快照。如果尚未存在執行階段快照，它們會退回到磁碟上解析出的設定檔。封裝後的內建 Plugin 外觀應透過 OpenClaw 的 Plugin 外觀載入器載入；直接從 `dist/extensions/...` 匯入會繞過封裝安裝針對 Plugin 擁有程式碼所使用的 manifest 與執行階段 sidecar 檢查。

-提供者 Plugin 可以公開狹窄的 Plugin 本機契約 barrel，供刻意限定提供者的協助程式使用，且該協助程式尚不屬於泛用 SDK 子路徑。內建範例：
+當輔助工具有意為提供者特定，且尚不屬於泛用 SDK 子路徑時，提供者 Plugin 可以公開狹窄的 Plugin 本機合約 barrel。內建範例：

- **Anthropic**：供 Claude beta-header 與 `service_tier` 串流協助程式使用的公開 `api.ts` / `contract-api.ts` seam。
- **`@openclaw/openai-provider`**：`api.ts` 匯出提供者建構器、預設模型協助程式，以及即時提供者建構器。
- **`@openclaw/openrouter-provider`**：`api.ts` 匯出提供者建構器以及上手/設定協助程式。
+- **Anthropic**：供 Claude beta-header 和 `service_tier` 串流輔助工具使用的公開 `api.ts` / `contract-api.ts` 接縫。
+- **`@openclaw/openai-provider`**：`api.ts` 匯出提供者建構器、預設模型輔助工具，以及即時提供者建構器。
+- **`@openclaw/openrouter-provider`**：`api.ts` 匯出提供者建構器，以及 onboarding/設定輔助工具。

 <Warning>
-  Extension 生產程式碼也應避免 `openclaw/plugin-sdk/<other-plugin>`
-  匯入。如果協助程式確實共用，請將它提升到中立的 SDK 子路徑，例如
-  `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他以能力為導向的介面，而不是將兩個 Plugin 耦合在一起。
+  擴充功能生產程式碼也應避免 `openclaw/plugin-sdk/<other-plugin>`
+  匯入。如果輔助工具確實是共用的，請將它提升到中立的 SDK 子路徑，
+  例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
+  以能力為導向的介面，而不是讓兩個 Plugin 彼此耦合。
 </Warning>

-## 相關
+## 相關內容

 <CardGroup cols={2}>
  <Card title="進入點" icon="door-open" href="/zh-TW/plugins/sdk-entrypoints">
-    `definePluginEntry` 和 `defineChannelPluginEntry` 選項。
+    `definePluginEntry` 與 `defineChannelPluginEntry` 選項。
  </Card>
  <Card title="執行階段輔助工具" icon="gears" href="/zh-TW/plugins/sdk-runtime">
    完整的 `api.runtime` 命名空間參考。
  </Card>
-  <Card title="設定與配置" icon="sliders" href="/zh-TW/plugins/sdk-setup">
-    封裝、manifest 和配置 schema。
+  <Card title="設定與組態" icon="sliders" href="/zh-TW/plugins/sdk-setup">
+    封裝、資訊清單與組態結構描述。
  </Card>
  <Card title="測試" icon="vial" href="/zh-TW/plugins/sdk-testing">
    測試工具程式與 lint 規則。
  </Card>
  <Card title="SDK 遷移" icon="arrows-turn-right" href="/zh-TW/plugins/sdk-migration">
-    從已棄用介面遷移。
+    從已棄用的介面遷移。
  </Card>
-  <Card title="Plugin 內部機制" icon="diagram-project" href="/zh-TW/plugins/architecture">
-    深入的架構與 capability 模型。
+  <Card title="Plugin 內部" icon="diagram-project" href="/zh-TW/plugins/architecture">
+    深入的架構與能力模型。
  </Card>
 </CardGroup>
--- a/docs/zh-TW/security/network-proxy.md
+++ b/docs/zh-TW/security/network-proxy.md
@ -1,40 +1,40 @@
 ---
 read_when:
-    - 你需要針對 SSRF 與 DNS 重新綁定攻擊的縱深防禦
+    - 你希望針對 SSRF 與 DNS 重綁定攻擊採取縱深防禦
    - 為 OpenClaw 執行階段流量設定外部正向代理
-summary: 如何將 OpenClaw 執行階段的 HTTP 與 WebSocket 流量透過由操作員管理的篩選代理路由
+summary: 如何透過由操作人員管理的篩選代理伺服器路由 OpenClaw 執行階段的 HTTP 與 WebSocket 流量
 title: 網路代理
 x-i18n:
-    generated_at: "2026-05-04T07:06:06Z"
+    generated_at: "2026-05-04T18:24:32Z"
    model: gpt-5.5
    provider: openai
-    source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
+    source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
    source_path: security/network-proxy.md
    workflow: 16
 ---

-# 網路代理伺服器
+# 網路代理

-OpenClaw 可以透過操作員管理的轉送代理伺服器，路由執行階段的 HTTP 和 WebSocket 流量。這是選用的縱深防禦，適用於需要集中輸出控制、更強 SSRF 防護，以及更好網路稽核能力的部署。
+OpenClaw 可以透過操作者管理的正向代理，路由執行階段的 HTTP 與 WebSocket 流量。對於想要集中出口控制、更強 SSRF 防護，以及更佳網路可稽核性的部署，這是選用的縱深防禦措施。

-OpenClaw 不會隨附、下載、啟動、設定或認證代理伺服器。你可以執行適合自身環境的代理技術，而 OpenClaw 會透過它路由一般行程本機的 HTTP 和 WebSocket 用戶端。
+OpenClaw 不會隨附、下載、啟動、設定或認證代理。你可以執行適合自己環境的代理技術，而 OpenClaw 會透過它路由一般的程序本機 HTTP 與 WebSocket 用戶端。

-## 為什麼使用代理伺服器？
+## 為什麼使用代理？

-代理伺服器為操作員提供單一網路控制點，用於輸出 HTTP 和 WebSocket 流量。即使不只為了 SSRF 強化，這也可能很有用：
+代理讓操作者能有一個針對輸出 HTTP 與 WebSocket 流量的網路控制點。即使不是為了強化 SSRF，這也可能很有用：

- 集中政策：維護單一輸出政策，而不是仰賴每個應用程式 HTTP 呼叫位置都正確套用網路規則。
- 連線時檢查：在 DNS 解析之後、代理伺服器開啟上游連線之前立即評估目的地。
- DNS 重新繫結防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。
- 更廣泛的 JavaScript 覆蓋範圍：透過相同路徑路由一般 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch 及類似用戶端。
- 稽核能力：在輸出邊界記錄允許與拒絕的目的地。
- 操作控制：在不重建 OpenClaw 的情況下強制執行目的地規則、網路分段、速率限制或輸出允許清單。
+- 集中政策：維護單一出口政策，而不是仰賴每個應用程式 HTTP 呼叫位置都正確套用網路規則。
+- 連線時檢查：在 DNS 解析後、代理即將開啟上游連線前，評估目的地。
+- DNS 重新綁定防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。
+- 更廣泛的 JavaScript 覆蓋：將一般的 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch，以及類似用戶端路由到同一路徑。
+- 可稽核性：在出口邊界記錄允許與拒絕的目的地。
+- 營運控制：不必重建 OpenClaw，即可強制套用目的地規則、網路分段、速率限制或輸出允許清單。

-代理路由是一般 HTTP 和 WebSocket 輸出的行程層級護欄。它為操作員提供失敗即關閉的路徑，用於透過自己的篩選代理伺服器路由受支援的 JavaScript HTTP 用戶端，但它不是作業系統層級的網路沙箱，也不會讓 OpenClaw 認證代理伺服器的目的地政策。
+代理路由是一般 HTTP 與 WebSocket 輸出的程序層級防護欄。它讓操作者能以失敗即關閉的路徑，將受支援的 JavaScript HTTP 用戶端透過自己的過濾代理路由，但它不是作業系統層級的網路沙盒，也不代表 OpenClaw 會認證代理的目的地政策。

 ## OpenClaw 如何路由流量

-當 `proxy.enabled=true` 且已設定代理 URL 時，受保護的執行階段行程，例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`，會透過設定的代理伺服器路由一般 HTTP 和 WebSocket 輸出：
+當 `proxy.enabled=true` 且已設定代理 URL 時，受保護的執行階段程序，例如 `openclaw gateway run`、`openclaw node run` 和 `openclaw agent --local`，會透過已設定的代理路由一般 HTTP 與 WebSocket 輸出：

 ```text
 OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
  WebSocket clients      -> operator-managed filtering proxy -> public internet
 ```

-公開契約是路由行為，而不是用來實作它的內部 Node 鉤子。當 Gateway URL 使用 `localhost` 或字面 loopback IP，例如 `127.0.0.1` 或 `[::1]` 時，OpenClaw Gateway 控制平面 WebSocket 用戶端會針對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理伺服器封鎖 loopback 目的地，該控制平面路徑也必須能夠連到 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理伺服器。
+公開契約是路由行為，而不是用來實作它的內部 Node hook。OpenClaw Gateway 控制平面 WebSocket 用戶端在 Gateway URL 使用 `localhost`，或使用像 `127.0.0.1` 或 `[::1]` 這類字面 loopback IP 時，會為 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作者代理封鎖 loopback 目的地，該控制平面路徑也必須能連到 loopback Gateway。一般執行階段 HTTP 與 WebSocket 請求仍會使用已設定的代理。

-在內部，OpenClaw 對此功能使用兩個行程層級路由鉤子：
+在內部，OpenClaw 會針對此功能使用兩個程序層級的路由 hook：

- Undici dispatcher 路由涵蓋 `fetch`、以 undici 為基礎的用戶端，以及提供自己 undici dispatcher 的傳輸。
- `global-agent` 路由涵蓋 Node 核心 `node:http` 和 `node:https` 呼叫者，包括許多建構在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的函式庫。受管理代理模式會強制使用該全域代理，因此明確的 Node HTTP agent 不會意外繞過操作員代理伺服器。
+- Undici dispatcher 路由涵蓋 `fetch`、undici 後援的用戶端，以及提供自身 undici dispatcher 的傳輸。
+- `global-agent` 路由涵蓋 Node 核心 `node:http` 與 `node:https` 呼叫端，包括許多建構在 `http.request`、`https.request`、`http.get` 與 `https.get` 之上的函式庫。受管理代理模式會強制使用該全域代理，避免明確的 Node HTTP agent 意外繞過操作者代理。

-某些 Plugin 擁有自訂傳輸，即使存在行程層級路由，也需要明確接線代理。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此在該擁有者特定的傳輸路徑中，會遵循行程代理環境變數以及受管理的 `OPENCLAW_PROXY_URL` 備援。
+部分 Plugin 擁有自訂傳輸，即使已有程序層級路由，也需要明確接上代理。例如，Telegram 的 Bot API 傳輸使用自己的 HTTP/1 undici dispatcher，因此會在該擁有者專屬傳輸路徑中遵循程序代理環境，以及受管理的 `OPENCLAW_PROXY_URL` 備援。

-代理 URL 本身必須使用 `http://`。HTTPS 目的地仍可透過代理伺服器搭配 HTTP `CONNECT` 支援；這只表示 OpenClaw 預期一個純 HTTP 轉送代理監聽器，例如 `http://127.0.0.1:3128`。
+代理 URL 本身必須使用 `http://`。HTTPS 目的地仍可透過具備 HTTP `CONNECT` 的代理受到支援；這只表示 OpenClaw 預期的是純 HTTP 正向代理監聽器，例如 `http://127.0.0.1:3128`。

-代理伺服器作用中時，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單以目的地為基礎，因此若保留 `localhost` 或 `127.0.0.1`，就會讓高風險 SSRF 目標略過篩選代理伺服器。
+代理啟用時，OpenClaw 會清除 `no_proxy`、`NO_PROXY` 和 `GLOBAL_AGENT_NO_PROXY`。這些繞過清單是以目的地為基礎，因此若將 `localhost` 或 `127.0.0.1` 留在其中，會讓高風險 SSRF 目標略過過濾代理。

-關閉時，OpenClaw 會還原先前的代理環境，並重設快取的行程路由狀態。
+關閉時，OpenClaw 會還原先前的代理環境，並重設快取的程序路由狀態。

 ## 相關代理術語

- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段輸出的輸出轉送代理路由。本頁說明此功能。
+- `proxy.enabled` / `proxy.proxyUrl`：OpenClaw 執行階段輸出的輸出正向代理路由。本頁記錄此功能。
 - `gateway.auth.mode: "trusted-proxy"`：用於 Gateway 存取的輸入身分感知反向代理驗證。請參閱[受信任代理驗證](/zh-TW/gateway/trusted-proxy-auth)。
 - `openclaw proxy`：用於開發與支援的本機除錯代理與擷取檢查器。請參閱 [openclaw proxy](/zh-TW/cli/proxy)。
- 通道或提供者特定的代理設定：特定傳輸的擁有者特定覆寫。當目標是在整個執行階段集中控制輸出時，請優先使用受管理的網路代理。
+- 頻道或供應商專屬代理設定：特定傳輸的擁有者專屬覆寫。若目標是在整個執行階段集中出口控制，請優先使用受管理的網路代理。

 ## 設定

@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

 `proxy.proxyUrl` 的優先順序高於 `OPENCLAW_PROXY_URL`。

-如果 `enabled=true` 但未設定有效的代理 URL，受保護的命令會在啟動時失敗，而不是退回直接網路存取。
+如果 `enabled=true` 但未設定有效的代理 URL，受保護的命令會在啟動時失敗，而不是退回到直接網路存取。

 對於使用 `openclaw gateway start` 啟動的受管理 Gateway 服務，建議將 URL 儲存在設定中：

@ -92,63 +92,63 @@ openclaw gateway install --force
 openclaw gateway start
 ```

-環境備援最適合前景執行。如果你將它用於已安裝的服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或 Scheduled Tasks 以該值啟動 Gateway。
+環境備援最適合前景執行。如果你將它用於已安裝的服務，請將 `OPENCLAW_PROXY_URL` 放入服務的持久環境，例如 `$OPENCLAW_STATE_DIR/.env` 或 `~/.openclaw/.env`，然後重新安裝服務，讓 launchd、systemd 或 Scheduled Tasks 以該值啟動 gateway。

-對於 `openclaw --container ...` 命令，當設定了 `OPENCLAW_PROXY_URL` 時，OpenClaw 會將它轉送至以容器為目標的子 CLI。該 URL 必須能從容器內部連到；`127.0.0.1` 指的是容器本身，而不是主機。除非你明確覆寫該安全檢查，否則 OpenClaw 會拒絕容器目標命令的 loopback 代理 URL。
+對於 `openclaw --container ...` 命令，當 `OPENCLAW_PROXY_URL` 已設定時，OpenClaw 會將它轉送到以容器為目標的子 CLI。該 URL 必須能從容器內部連線；`127.0.0.1` 指的是容器本身，而不是主機。除非你明確覆寫該安全檢查，否則 OpenClaw 會拒絕容器目標命令使用 loopback 代理 URL。

-## 代理伺服器需求
+## 代理需求

-代理政策是安全邊界。OpenClaw 無法驗證代理伺服器是否封鎖正確的目標。
+代理政策是安全邊界。OpenClaw 無法驗證代理是否封鎖了正確目標。

-請設定代理伺服器以：
+請將代理設定為：

- 僅繫結至 loopback 或私有受信任介面。
- 限制存取，使只有 OpenClaw 行程、主機、容器或服務帳戶可以使用它。
+- 僅繫結到 loopback 或私有受信任介面。
+- 限制存取，讓只有 OpenClaw 程序、主機、容器或服務帳號可以使用。
 - 自行解析目的地，並在 DNS 解析後封鎖目的地 IP。
- 針對純 HTTP 請求和 HTTPS `CONNECT` 通道，都在連線時套用政策。
- 拒絕針對 loopback、私有、鏈路本機、中繼資料、多播、保留或文件範圍的目的地式繞過。
- 除非你完全信任 DNS 解析路徑，否則避免使用主機名稱允許清單。
- 記錄目的地、決策、狀態和原因，但不要記錄請求本文、授權標頭、Cookie 或其他祕密。
- 將代理政策納入版本控制，並像審查安全敏感設定一樣審查變更。
+- 對純 HTTP 請求與 HTTPS `CONNECT` 通道，都在連線時套用政策。
+- 拒絕針對 loopback、私人、鏈路本機、中繼資料、多點傳送、保留或文件範圍的目的地式繞過。
+- 除非你完全信任 DNS 解析路徑，否則請避免使用主機名稱允許清單。
+- 記錄目的地、決策、狀態與原因，但不要記錄請求本文、授權標頭、Cookie 或其他秘密。
+- 將代理政策置於版本控制下，並像安全敏感設定一樣審查變更。

-## 建議封鎖的目的地
+## 建議封鎖目的地

-使用此拒絕清單作為任何轉送代理、防火牆或輸出政策的起點。
+請將此拒絕清單作為任何正向代理、防火牆或出口政策的起點。

-OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關的同等性鉤子為 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及 NAT64、6to4、Teredo、ISATAP 和 IPv4 對應形式的內嵌 IPv4 sentinel 處理。維護外部代理政策時，這些檔案是有用的參考，但 OpenClaw 不會自動匯出或在你的代理伺服器中強制執行這些規則。
+OpenClaw 應用程式層級分類器邏輯位於 `src/infra/net/ssrf.ts` 和 `src/shared/net/ip.ts`。相關的對等 hook 是 `BLOCKED_HOSTNAMES`、`BLOCKED_IPV4_SPECIAL_USE_RANGES`、`BLOCKED_IPV6_SPECIAL_USE_RANGES`、`RFC2544_BENCHMARK_PREFIX`，以及針對 NAT64、6to4、Teredo、ISATAP 和 IPv4 對應形式的嵌入式 IPv4 sentinel 處理。維護外部代理政策時，這些檔案是有用的參考，但 OpenClaw 不會自動匯出或在你的代理中強制套用這些規則。

-| 範圍或主機                                                                           | 封鎖原因                                             |
-| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
-| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                  | IPv4 loopback                                        |
-| `::1/128`                                                                            | IPv6 loopback                                        |
-| `0.0.0.0/8`, `::/128`                                                                | 未指定和此網路位址                                   |
-| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                      | RFC1918 私有網路                                     |
-| `169.254.0.0/16`, `fe80::/10`                                                        | 鏈路本機位址和常見雲端中繼資料路徑                   |
-| `169.254.169.254`, `metadata.google.internal`                                        | 雲端中繼資料服務                                     |
-| `100.64.0.0/10`                                                                      | 電信級 NAT 共用位址空間                              |
-| `198.18.0.0/15`, `2001:2::/48`                                                       | 基準測試範圍                                         |
-| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途和文件範圍                                   |
-| `224.0.0.0/4`, `ff00::/8`                                                            | 多播                                                 |
-| `240.0.0.0/4`                                                                        | 保留的 IPv4                                          |
-| `fc00::/7`, `fec0::/10`                                                              | IPv6 本機/私有範圍                                   |
-| `100::/64`, `2001:20::/28`                                                           | IPv6 discard 和 ORCHIDv2 範圍                        |
-| `64:ff9b::/96`, `64:ff9b:1::/48`                                                     | 含內嵌 IPv4 的 NAT64 前綴                            |
-| `2002::/16`, `2001::/32`                                                             | 含內嵌 IPv4 的 6to4 和 Teredo                        |
-| `::/96`, `::ffff:0:0/96`                                                             | IPv4 相容和 IPv4 對應 IPv6                           |
+| 範圍或主機                                                                         | 封鎖原因                                             |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `127.0.0.0/8`, `localhost`, `localhost.localdomain`                                | IPv4 loopback                                        |
+| `::1/128`                                                                          | IPv6 loopback                                        |
+| `0.0.0.0/8`, `::/128`                                                              | 未指定與本網路位址                                   |
+| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`                                    | RFC1918 私有網路                                     |
+| `169.254.0.0/16`, `fe80::/10`                                                      | 鏈路本機位址與常見雲端中繼資料路徑                 |
+| `169.254.169.254`, `metadata.google.internal`                                      | 雲端中繼資料服務                                     |
+| `100.64.0.0/10`                                                                    | 電信級 NAT 共用位址空間                              |
+| `198.18.0.0/15`, `2001:2::/48`                                                     | 基準測試範圍                                         |
+| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | 特殊用途與文件範圍                                   |
+| `224.0.0.0/4`, `ff00::/8`                                                          | 多點傳送                                             |
+| `240.0.0.0/4`                                                                      | 保留 IPv4                                            |
+| `fc00::/7`, `fec0::/10`                                                            | IPv6 本機／私有範圍                                  |
+| `100::/64`, `2001:20::/28`                                                         | IPv6 discard 與 ORCHIDv2 範圍                        |
+| `64:ff9b::/96`, `64:ff9b:1::/48`                                                   | 含嵌入式 IPv4 的 NAT64 前綴                          |
+| `2002::/16`, `2001::/32`                                                           | 含嵌入式 IPv4 的 6to4 與 Teredo                      |
+| `::/96`, `::ffff:0:0/96`                                                           | IPv4 相容與 IPv4 對應的 IPv6                         |

-如果你的雲端提供者或網路平台記載了額外的中繼資料主機或保留範圍，也請加入它們。
+如果你的雲端供應商或網路平台記錄了其他中繼資料主機或保留範圍，也請一併加入。

 ## 驗證

-請從執行 OpenClaw 的相同主機、容器或服務帳戶驗證代理伺服器：
+請從執行 OpenClaw 的同一個主機、容器或服務帳號驗證代理：

 ```bash
 openclaw proxy validate --proxy-url http://127.0.0.1:3128
 ```

-預設情況下，未提供自訂目的地時，此命令會檢查 `https://example.com/` 是否成功，並啟動一個代理伺服器不得連到的暫時 loopback canary。當代理伺服器回傳非 2xx 拒絕回應，或以傳輸失敗封鎖 canary 時，預設拒絕檢查會通過；如果成功回應抵達 canary，則會失敗。如果未啟用且設定代理伺服器，驗證會回報設定問題；在變更設定前，可使用 `--proxy-url` 執行一次性預檢。使用 `--allowed-url` 和 `--denied-url` 測試部署特定的預期。自訂拒絕目的地採失敗即關閉：任何 HTTP 回應都表示目的地可透過代理伺服器連到，而任何傳輸錯誤都會回報為不確定，因為 OpenClaw 無法證明代理伺服器封鎖了可連到的來源。驗證失敗時，命令會以代碼 1 結束。
+預設情況下，若未提供自訂目的地，該命令會檢查 `https://example.com/` 是否成功，並啟動一個代理不得連到的暫時 loopback canary。當代理回傳非 2xx 拒絕回應，或以傳輸失敗封鎖 canary 時，預設拒絕檢查會通過；如果成功回應抵達 canary，則會失敗。如果未啟用並設定代理，驗證會回報設定問題；在變更設定前的一次性預檢，請使用 `--proxy-url`。使用 `--allowed-url` 與 `--denied-url` 測試部署專屬預期。加入 `--apns-reachable` 也會驗證直接 APNs HTTP/2 傳遞能透過代理開啟 CONNECT 通道，並收到沙盒 APNs 回應；該探測會使用刻意無效的供應商權杖，因此預期會得到 `403 InvalidProviderToken`，且會計為可連線。自訂拒絕目的地是失敗即關閉：任何 HTTP 回應都表示目的地可透過代理連到，而任何傳輸錯誤都會回報為無法判定，因為 OpenClaw 無法證明代理封鎖了一個可連線來源。驗證失敗時，命令會以代碼 1 結束。

-使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及每個目的地檢查。代理 URL 認證會在文字和 JSON 輸出中遮蔽：
+使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及各目的地檢查。代理 URL 認證資訊會在文字與 JSON 輸出中被遮蔽：

 ```json
 {
@ -165,6 +165,12 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
      "url": "https://example.com/",
      "ok": true,
      "status": 200
+    },
+    {
+      "kind": "apns",
+      "url": "https://api.sandbox.push.apple.com",
+      "ok": true,
+      "status": 403
    }
  ]
 }
@ -178,9 +184,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
 curl -x http://127.0.0.1:3128 http://169.254.169.254/
 ```

-公開請求應該會成功。loopback 和中繼資料請求應該會被代理封鎖。對於 `openclaw proxy validate`，內建的 loopback 金絲雀檢查可以區分代理拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀檢查，因此除非你的代理公開了可另行驗證的部署專屬拒絕訊號，否則請將 HTTP 回應和不明確的傳輸失敗都視為驗證失敗。
+公開請求應該會成功。回送與中繼資料請求應該會被代理伺服器封鎖。對於 `openclaw proxy validate`，內建的回送金絲雀檢查可以區分代理伺服器拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀檢查，因此除非你的代理伺服器公開了可另行驗證的部署特定拒絕訊號，否則請將 HTTP 回應與模稜兩可的傳輸失敗都視為驗證失敗。

-然後啟用 OpenClaw 代理路由：
+接著啟用 OpenClaw 代理路由：

 ```bash
 openclaw config set proxy.enabled true
@ -198,11 +204,11 @@ proxy:

 ## 限制

- 代理可改善程序本機 JavaScript HTTP 與 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
- 原始 `net`、`tls` 和 `http2` 通訊端、原生附加元件和子程序可能會繞過 Node 層級的代理路由，除非它們繼承並遵循代理環境變數。
- IRC 是不受操作員管理的正向代理路由涵蓋的原始 TCP/TLS 通道。在要求所有輸出流量都必須經過該正向代理的部署中，除非已明確核准直接 IRC 輸出，否則請設定 `channels.irc.enabled=false`。
- 本機除錯代理是診斷工具；當受管理代理模式作用中時，其對代理請求和 CONNECT 通道的直接上游轉送預設為停用。僅針對已核准的本機診斷啟用直接轉送。
- 使用者本機 WebUI 和本機模型伺服器需要時應在操作員代理政策中列入允許清單；OpenClaw 不會為它們公開一般的本機網路繞過機制。
- Gateway 控制平面代理繞過刻意限制為 `localhost` 和字面 loopback IP URL。請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 進行本機直接 Gateway 控制平面連線；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。
+- 代理伺服器可改善行程本機 JavaScript HTTP 與 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
+- 原始 `net`、`tls` 與 `http2` 通訊端、原生附加元件和子行程，除非繼承並遵守代理伺服器環境變數，否則可能會略過 Node 層級的代理路由。
+- IRC 是運算子管理正向代理路由之外的原始 TCP/TLS 通道。在要求所有輸出流量都通過該正向代理伺服器的部署中，除非直接 IRC 輸出流量已明確核准，否則請設定 `channels.irc.enabled=false`。
+- 本機偵錯代理伺服器是診斷工具，且其對代理請求與 CONNECT 通道的直接上游轉送，在受管理代理模式啟用時預設為停用；只有針對已核准的本機診斷才啟用直接轉送。
+- 需要時，使用者本機 WebUI 與本機模型伺服器應加入運算子代理政策的允許清單；OpenClaw 不會為它們公開一般性的本機網路繞過機制。
+- Gateway 控制平面代理繞過刻意限制為 `localhost` 與字面回送 IP URL。請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789` 進行本機直接 Gateway 控制平面連線；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。
 - OpenClaw 不會檢查、測試或認證你的代理政策。
- 請將代理政策變更視為對安全性敏感的營運變更。
+- 請將代理政策變更視為安全性敏感的營運變更。
--- a/docs/zh-TW/tools/thinking.md
+++ b/docs/zh-TW/tools/thinking.md
@ -1,143 +1,144 @@
 ---
 read_when:
-    - 調整思考、快速模式或詳細指令的剖析或預設值
-summary: /think、/fast、/verbose、/trace 的指令語法與推理可見性
+    - 調整思考、快速模式或詳細指令的解析或預設值
+summary: /think、/fast、/verbose、/trace 的指令語法與推理可見度
 title: 思考層級
 x-i18n:
-    generated_at: "2026-05-04T02:46:38Z"
+    generated_at: "2026-05-04T18:24:32Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
+    source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
    source_path: tools/thinking.md
    workflow: 16
 ---

 ## 功能

- 任何傳入本文中的行內指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
+- 在任何傳入本文中使用內嵌指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
 - 層級（別名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
-  - minimal →「think」
-  - low →「think hard」
-  - medium →「think harder」
-  - high →「ultrathink」（最大預算）
-  - xhigh →「ultrathink+」（GPT-5.2+ 與 Codex 模型，加上 Anthropic Claude Opus 4.7 effort）
-  - adaptive → 由提供者管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考）
-  - max → 提供者最大推理（Anthropic Claude Opus 4.7；Ollama 會將此對應到其最高原生 `think` effort）
+  - minimal → 「think」
+  - low → 「think hard」
+  - medium → 「think harder」
+  - high → 「ultrathink」（最大預算）
+  - xhigh → 「ultrathink+」（GPT-5.2+ 和 Codex 模型，加上 Anthropic Claude Opus 4.7 effort）
+  - adaptive → 供應商管理的自適應思考（支援 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 動態思考）
+  - max → 供應商最大推理（Anthropic Claude Opus 4.7；Ollama 會將此對應到其最高原生 `think` effort）
  - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 會對應到 `xhigh`。
  - `highest` 會對應到 `high`。
- 提供者注意事項：
-  - 思考選單與選擇器由提供者設定檔驅動。提供者 Plugin 會宣告所選模型的確切層級集合，包含二元 `on` 等標籤。
-  - `adaptive`、`xhigh` 和 `max` 只會對支援它們的提供者/模型設定檔顯示。針對不支援層級的已輸入指令，會以該模型的有效選項拒絕。
-  - 既有已儲存的不支援層級會依提供者設定檔排名重新對應。`adaptive` 在非自適應模型上會退回到 `medium`，而 `xhigh` 和 `max` 會退回到所選模型支援的最大非 off 層級。
-  - Anthropic Claude 4.6 模型在未設定明確思考層級時，預設為 `adaptive`。
-  - Anthropic Claude Opus 4.7 不會預設使用自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由提供者擁有。
+- 供應商注意事項：
+  - 思考選單和選擇器由供應商設定檔驅動。供應商 Plugin 會宣告所選模型的確切層級集合，包括二元 `on` 等標籤。
+  - 只有支援的供應商/模型設定檔才會顯示 `adaptive`、`xhigh` 和 `max`。對不支援層級輸入的指令，會以該模型的有效選項拒絕。
+  - 既有儲存的不支援層級會依供應商設定檔排名重新對應。在非自適應模型上，`adaptive` 會回退到 `medium`，而 `xhigh` 和 `max` 會回退到所選模型支援的最大非 off 層級。
+  - 未明確設定思考層級時，Anthropic Claude 4.6 模型預設為 `adaptive`。
+  - Anthropic Claude Opus 4.7 不會預設為自適應思考。除非你明確設定思考層級，否則其 API effort 預設值仍由供應商管理。
  - Anthropic Claude Opus 4.7 會將 `/think xhigh` 對應到自適應思考加上 `output_config.effort: "xhigh"`，因為 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 設定。
-  - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到相同的提供者所屬最大 effort 路徑。
-  - DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，而較低的非 off 層級會對應到 `high`。
-  - 具備思考能力的 Ollama 模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。
-  - OpenAI GPT 模型會透過模型專屬的 Responses API effort 支援來對應 `/think`。只有在目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用的推理酬載，而不是傳送不支援的值。
-  - 自訂 OpenAI 相容型目錄項目可以透過將 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 設為包含 `"xhigh"`，選擇啟用 `/think xhigh`。這會使用相同的相容性中繼資料來對應傳出的 OpenAI 推理 effort 酬載，因此選單、工作階段驗證、代理程式 CLI 與 `llm-task` 都會與傳輸行為一致。
-  - 過期設定的 OpenRouter Hunter Alpha 參照會略過代理推理注入，因為該已淘汰路由可能透過推理欄位回傳最終答案文字。
-  - Google Gemini 會將 `/think adaptive` 對應到 Gemini 的提供者所屬動態思考。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定層級仍會對應到該模型系列最接近的 Gemini `thinkingLevel` 或預算。
-  - Anthropic 相容串流路徑上的 MiniMax（`minimax/*`）預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定思考。這可避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` 增量。
-  - Z.AI（`zai/*`）只支援二元思考（`on`/`off`）。任何非 `off` 層級都會被視為 `on`（對應到 `low`）。
-  - Moonshot（`moonshot/*`）會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。
+  - Anthropic Claude Opus 4.7 也公開 `/think max`；它會對應到同一條供應商管理的最大 effort 路徑。
+  - DeepSeek V4 模型公開 `/think xhigh|max`；兩者都會對應到 DeepSeek `reasoning_effort: "max"`，較低的非 off 層級則會對應到 `high`。
+  - 支援思考的 Ollama 模型公開 `/think low|medium|high|max`；`max` 會對應到原生 `think: "high"`，因為 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字串。
+  - OpenAI GPT 模型會依模型專屬的 Responses API effort 支援對應 `/think`。只有目標模型支援時，`/think off` 才會傳送 `reasoning.effort: "none"`；否則 OpenClaw 會省略停用的 reasoning 承載，而不是傳送不支援的值。
+  - 自訂 OpenAI 相容目錄項目可以透過將 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 設為包含 `"xhigh"` 來選擇支援 `/think xhigh`。這會使用同一份用於對應傳出 OpenAI reasoning effort 承載的相容性中繼資料，因此選單、工作階段驗證、agent CLI 和 `llm-task` 會與傳輸行為一致。
+  - 過期設定的 OpenRouter Hunter Alpha 參照會略過代理推理注入，因為該已退役路由可能透過推理欄位回傳最終答案文字。
+  - Google Gemini 會將 `/think adaptive` 對應到 Gemini 由供應商管理的動態思考。Gemini 3 請求會省略固定的 `thinkingLevel`，而 Gemini 2.5 請求會傳送 `thinkingBudget: -1`；固定層級仍會對應到該模型系列最接近的 Gemini `thinkingLevel` 或預算。
+  - Anthropic 相容串流路徑上的 MiniMax (`minimax/*`) 預設為 `thinking: { type: "disabled" }`，除非你在模型參數或請求參數中明確設定思考。這可避免 MiniMax 非原生 Anthropic 串流格式洩漏 `reasoning_content` 差異內容。
+  - Z.AI (`zai/*`) 只支援二元思考（`on`/`off`）。任何非 `off` 層級都會視為 `on`（對應到 `low`）。
+  - Moonshot (`moonshot/*`) 會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。

 ## 解析順序

-1. 訊息上的行內指令（只套用於該訊息）。
+1. 訊息上的內嵌指令（僅套用於該訊息）。
 2. 工作階段覆寫（透過傳送只有指令的訊息設定）。
-3. 每個代理程式預設值（設定中的 `agents.list[].thinkingDefault`）。
+3. 每個 agent 的預設值（設定中的 `agents.list[].thinkingDefault`）。
 4. 全域預設值（設定中的 `agents.defaults.thinkingDefault`）。
-5. 後援：有提供者宣告的預設值時使用該值；否則具備推理能力的模型會解析為 `medium` 或該模型最接近的受支援非 `off` 層級，而非推理模型維持 `off`。
+5. 回退：可用時使用供應商宣告的預設值；否則，具備推理能力的模型會解析為 `medium` 或該模型最接近的支援非 `off` 層級，而不具備推理能力的模型維持 `off`。

 ## 設定工作階段預設值

 - 傳送一則**只有**指令的訊息（允許空白），例如 `/think:medium` 或 `/t high`。
- 該設定會在目前工作階段中持續有效（預設依傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。
- 會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），指令會以提示拒絕，且工作階段狀態保持不變。
- 傳送沒有引數的 `/think`（或 `/think:`）可查看目前思考層級。
+- 這會在目前工作階段中保持生效（預設依傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。
+- 會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），命令會被拒絕並附上提示，工作階段狀態不會變更。
+- 傳送不含引數的 `/think`（或 `/think:`）可查看目前思考層級。

-## 依代理程式套用
+## 依 agent 套用

- **嵌入式 Pi**：已解析的層級會傳遞給處理程序內 Pi 代理程式執行階段。
+- **嵌入式 Pi**：解析出的層級會傳遞給程序內 Pi agent runtime。
+- **Claude CLI 後端**：使用 `claude-cli` 時，非 off 層級會以 `--effort` 傳遞給 Claude Code；請參閱 [CLI 後端](/zh-TW/gateway/cli-backends)。

-## 快速模式（/fast）
+## 快速模式 (/fast)

 - 層級：`on|off`。
 - 只有指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。
- 傳送沒有模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。
+- 傳送不含模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。
 - OpenClaw 會依此順序解析快速模式：
-  1. 行內/只有指令的 `/fast on|off`
+  1. 內嵌/只有指令的 `/fast on|off`
  2. 工作階段覆寫
-  3. 每個代理程式預設值（`agents.list[].fastModeDefault`）
+  3. 每個 agent 的預設值（`agents.list[].fastModeDefault`）
  4. 每個模型設定：`agents.defaults.models["<provider>/<model>"].params.fastMode`
-  5. 後援：`off`
- 對於 `openai/*`，快速模式會透過在受支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。
- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 會在兩種驗證路徑間維持一個共用的 `/fast` 切換。
- 對於直接公開的 `anthropic/*` 請求，包括傳送到 `api.anthropic.com` 的 OAuth 驗證流量，快速模式會對應到 Anthropic 服務層級：`/fast on` 設定 `service_tier=auto`，`/fast off` 設定 `service_tier=standard_only`。
+  5. 回退：`off`
+- 對於 `openai/*`，快速模式會透過在支援的 Responses 請求上傳送 `service_tier=priority`，對應到 OpenAI 優先處理。
+- 對於 `openai-codex/*`，快速模式會在 Codex Responses 上傳送相同的 `service_tier=priority` 旗標。OpenClaw 在兩種驗證路徑間維持一個共用的 `/fast` 切換。
+- 對於直接公開的 `anthropic/*` 請求，包括傳送至 `api.anthropic.com` 的 OAuth 驗證流量，快速模式會對應到 Anthropic 服務層級：`/fast on` 設定 `service_tier=auto`，`/fast off` 設定 `service_tier=standard_only`。
 - 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
- 明確的 Anthropic `serviceTier` / `service_tier` 模型參數會在兩者都設定時覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理基底 URL 略過 Anthropic 服務層級注入。
- `/status` 只會在啟用快速模式時顯示 `Fast`。
+- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理基底 URL 略過 Anthropic 服務層級注入。
+- `/status` 只有在啟用快速模式時才會顯示 `Fast`。

-## 詳細指令（/verbose 或 /v）
+## 詳細指令 (/verbose 或 /v)

 - 層級：`on`（最小）| `full` | `off`（預設）。
- 只有指令的訊息會切換工作階段詳細模式，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。
- `/verbose off` 會儲存明確的工作階段覆寫；可在工作階段 UI 中選擇 `inherit` 清除。
- 行內指令只影響該訊息；否則套用工作階段/全域預設值。
- 傳送沒有引數的 `/verbose`（或 `/verbose:`）可查看目前詳細層級。
- 開啟詳細模式時，會發出結構化工具結果的代理程式（Pi、其他 JSON 代理程式）會將每個工具呼叫作為自己的僅中繼資料訊息傳回；可用時前置 `<emoji> <tool-name>: <arg>`。這些工具摘要會在每個工具開始時立即傳送（分開的訊息泡泡），而不是作為串流增量。
- 工具失敗摘要在一般模式中仍會顯示，但原始錯誤詳細後綴會隱藏，除非詳細模式為 `on` 或 `full`。
- 當詳細模式為 `full` 時，工具輸出也會在完成後轉送（分開的訊息泡泡，截斷至安全長度）。如果你在執行進行中切換 `/verbose on|full|off`，後續工具訊息泡泡會遵循新設定。
- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要與進度草稿工具行的形狀。使用 `"explain"`（預設）可取得精簡的人類標籤，例如 `🛠️ Exec: checking JS syntax`；若你也想附加原始命令/詳細資訊以便偵錯，請使用 `"raw"`。每個代理程式的 `agents.list[].toolProgressDetail` 會覆寫預設值。
-  - `explain`：`🛠️ Exec: check JS syntax for /tmp/app.js`
-  - `raw`：`🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
+- 只有指令的訊息會切換工作階段詳細輸出，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。
+- `/verbose off` 會儲存明確的工作階段覆寫；可透過 Sessions UI 選擇 `inherit` 來清除。
+- 內嵌指令僅影響該訊息；否則會套用工作階段/全域預設值。
+- 傳送不含引數的 `/verbose`（或 `/verbose:`）可查看目前詳細層級。
+- 啟用詳細輸出時，會發出結構化工具結果的 agent（Pi、其他 JSON agent）會將每個工具呼叫以自己的僅中繼資料訊息傳回；可用時前置 `<emoji> <tool-name>: <arg>`。這些工具摘要會在每個工具開始時立即傳送（分開的訊息泡泡），而不是以串流差異內容傳送。
+- 工具失敗摘要在一般模式中仍可見，但原始錯誤詳細資料後綴會隱藏，除非詳細層級為 `on` 或 `full`。
+- 當詳細層級為 `full` 時，工具輸出也會在完成後轉送（分開的訊息泡泡，截斷至安全長度）。如果你在執行進行中切換 `/verbose on|full|off`，後續工具泡泡會遵循新的設定。
+- `agents.defaults.toolProgressDetail` 控制 `/verbose` 工具摘要和進度草稿工具行的形狀。使用 `"explain"`（預設）可取得精簡的人類標籤，例如 `🛠️ Exec: checking JS syntax`；如果你也想附加原始命令/詳細資料以進行偵錯，請使用 `"raw"`。每個 agent 的 `agents.list[].toolProgressDetail` 會覆寫預設值。
+  - `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
+  - `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`

-## Plugin 追蹤指令（/trace）
+## Plugin 追蹤指令 (/trace)

 - 層級：`on` | `off`（預設）。
 - 只有指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 行內指令只影響該訊息；否則套用工作階段/全域預設值。
- 傳送沒有引數的 `/trace`（或 `/trace:`）可查看目前追蹤層級。
- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 所屬的追蹤/偵錯行，例如 Active Memory 偵錯摘要。
- 追蹤行可以出現在 `/status` 中，也可以作為一般助理回覆後的後續診斷訊息。
+- 內嵌指令僅影響該訊息；否則會套用工作階段/全域預設值。
+- 傳送不含引數的 `/trace`（或 `/trace:`）可查看目前追蹤層級。
+- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 擁有的追蹤/偵錯行，例如 Active Memory 偵錯摘要。
+- 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。

-## 推理可見性（/reasoning）
+## 推理可見性 (/reasoning)

 - 層級：`on|off|stream`。
 - 只有指令的訊息會切換是否在回覆中顯示思考區塊。
- 啟用時，推理會作為**分開的訊息**傳送，前置 `Reasoning:`。
- `stream`（僅 Telegram）：在產生回覆時將推理串流到 Telegram 草稿訊息泡泡，然後傳送不含推理的最終答案。
+- 啟用時，推理會以前置 `Reasoning:` 的**分開訊息**傳送。
+- `stream`（僅 Telegram）：在回覆產生時將推理串流到 Telegram 草稿泡泡，然後傳送不含推理的最終答案。
 - 別名：`/reason`。
- 傳送沒有引數的 `/reasoning`（或 `/reasoning:`）可查看目前推理層級。
- 解析順序：行內指令，接著是工作階段覆寫，再來是每個代理程式預設值（`agents.list[].reasoningDefault`），最後是後援（`off`）。
+- 傳送不含引數的 `/reasoning`（或 `/reasoning:`）可查看目前推理層級。
+- 解析順序：內嵌指令，接著是工作階段覆寫，接著是每個 agent 的預設值（`agents.list[].reasoningDefault`），最後回退（`off`）。

-格式錯誤的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊會在一般回覆中保持隱藏，且已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開頭標籤中，且否則會傳送為空文字，OpenClaw 會移除格式錯誤的開頭標籤並傳送剩餘文字。
+格式錯誤的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊在一般回覆中維持隱藏，已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開啟標籤中，且否則會以空文字交付，OpenClaw 會移除格式錯誤的開啟標籤並交付剩餘文字。

 ## 相關

- 提權模式文件位於[提權模式](/zh-TW/tools/elevated)。
+- 提升模式文件位於[提升模式](/zh-TW/tools/elevated)。

 ## Heartbeat

- Heartbeat 探測本文是設定的 Heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的行內指令會照常套用（但避免從 Heartbeat 變更工作階段預設值）。
- Heartbeat 傳送預設只傳送最終酬載。若也要傳送分開的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或每個代理程式的 `agents.list[].heartbeat.includeReasoning: true`。
+- Heartbeat 探測本文是設定的 heartbeat 提示（預設：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 訊息中的內嵌指令會照常套用（但請避免從 heartbeat 變更工作階段預設值）。
+- Heartbeat 交付預設只傳送最終承載。若也要傳送分開的 `Reasoning:` 訊息（可用時），請設定 `agents.defaults.heartbeat.includeReasoning: true` 或每個 agent 的 `agents.list[].heartbeat.includeReasoning: true`。

-## 網頁聊天 UI
+## Web 聊天 UI

- 網頁聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定映照工作階段已儲存的層級。
- 選擇另一個層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，且不是一次性的 `thinkingOnce` 覆寫。
- 第一個選項一律為 `Default (<resolved level>)`，其中已解析的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 和 `session_status` 使用的相同後援邏輯。
- 選擇器使用 Gateway 工作階段資料列/預設值回傳的 `thinkingLevels`，並保留 `thinkingOptions` 作為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者 regex 清單；Plugin 擁有模型專屬層級集合。
- `/think:<level>` 仍可運作，並會更新相同儲存的工作階段層級，因此聊天指令與選擇器會保持同步。
+- Web 聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定鏡像工作階段儲存的層級。
+- 選取其他層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。
+- 第一個選項一律是 `Default (<resolved level>)`，其中解析出的預設值來自作用中工作階段模型的供應商思考設定檔，加上 `/status` 和 `session_status` 使用的相同回退邏輯。
+- 選擇器使用 Gateway 工作階段列/預設值回傳的 `thinkingLevels`，並將 `thinkingOptions` 保留為舊版標籤清單。瀏覽器 UI 不保留自己的供應商 regex 清單；Plugin 擁有模型專屬層級集合。
+- `/think:<level>` 仍可運作，並會更新同一個儲存的工作階段層級，因此聊天指令和選擇器會保持同步。

-## 提供者設定檔
+## 供應商設定檔

- 供應商 Plugin 可以公開 `resolveThinkingProfile(ctx)`，以定義模型支援的層級與預設值。
- 代理 Claude 模型的供應商 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。
- 每個設定檔層級都有儲存的正規 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），也可以包含顯示用 `label`。二元供應商使用 `{ id: "low", label: "on" }`。
- 需要驗證明確思考覆寫的工具 Plugin，應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加上 `api.runtime.agent.normalizeThinkingLevel(...)`；它們不應維護自己的供應商/模型層級清單。
- 能存取已設定自訂模型中繼資料的工具 Plugin，可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 的選擇加入反映在 Plugin 端驗證中。
- 已發布的舊版掛鉤（`supportsXHighThinking`、`isBinaryThinking` 與 `resolveDefaultThinkingLevel`）會保留作為相容性配接器，但新的自訂層級集應使用 `resolveThinkingProfile`。
- Gateway 列/預設值公開 `thinkingLevels`、`thinkingOptions` 與 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證相同的設定檔 ID 與標籤。
+- 提供者 Plugin 可以公開 `resolveThinkingProfile(ctx)`，以定義模型支援的層級與預設值。
+- 代理 Claude 模型的提供者 Plugin 應重用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，讓直接 Anthropic 與代理目錄保持一致。
+- 每個設定檔層級都有儲存的標準 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），也可以包含顯示用的 `label`。二元提供者使用 `{ id: "low", label: "on" }`。
+- 需要驗證明確思考覆寫的工具 Plugin，應使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 搭配 `api.runtime.agent.normalizeThinkingLevel(...)`；不應維護自己的提供者/模型層級清單。
+- 可存取已設定自訂模型中繼資料的工具 Plugin，可以將 `catalog` 傳入 `resolveThinkingPolicy`，讓 `compat.supportedReasoningEfforts` 選擇加入設定反映在 Plugin 端驗證中。
+- 已發布的舊版掛鉤（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍作為相容性配接器保留，但新的自訂層級集合應使用 `resolveThinkingProfile`。
+- Gateway 列與預設值會公開 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，讓 ACP/聊天用戶端呈現與執行階段驗證所用相同的設定檔 ID 與標籤。