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

chore(i18n): refresh zh-TW translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 02:48:38 +00:00
parent 24c647793e
commit c92ecc1fb3
21 changed files with 2679 additions and 2340 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

396
docs/zh-TW/concepts/qa-e2e-automation.md
View File

@ -1,80 +1,71 @@
---
read_when:
- 了解品質保證堆疊如何協同運作
- 了解 QA 堆疊如何協同運作
- 擴充 qa-lab、qa-channel 或傳輸配接器
- 新增由儲存庫支援的 QA 情境
- 圍繞 Gateway 儀表板建立更高擬真度的 QA 自動化
summary: QA 堆疊概覽：qa-lab、qa-channel、由 repo 支援的情境、即時傳輸通道、傳輸轉接器，以及報告。
title: QA 概觀
- 新增以儲存庫為後盾的 QA 情境
- 圍繞 Gateway 儀表板建構更高真實度的 QA 自動化
summary: QA 堆疊概觀：qa-lab、qa-channel、以儲存庫支援的情境、即時傳輸通道、傳輸配接器與報告。
title: 品質保證概觀
x-i18n:
generated_at: "2026-05-03T21:31:22Z"
generated_at: "2026-05-04T02:44:27Z"
model: gpt-5.5
provider: openai
source_hash: 6a1446fddb00855634d34662a0a47be1e5054a9e7bfed5bc9ae21185d87094d8
source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
私有 QA 堆疊旨在以比單一單元測試更接近真實、通道形態的方式演練 OpenClaw。
私有 QA 堆疊旨在以比單一單元測試更貼近真實情境、具通道形態的方式演練 OpenClaw。
目前組成：
- `extensions/qa-channel`：合成訊息通道，具備 DM、頻道、執行緒、
反應、編輯與刪除表面。
- `extensions/qa-lab`：偵錯器 UI 與 QA 匯流排，用於觀察逐字稿、
注入傳入訊息，以及匯出 Markdown 報告。
- `extensions/qa-matrix`、未來的 runner plugins：即時傳輸介面卡，
會在子 QA gateway 內驅動真實通道。
- `qa/`：由 repo 支援的啟動任務種子資產與基準 QA
情境。
- [Mantis](/zh-TW/concepts/mantis)：針對需要真實傳輸、瀏覽器截圖、VM 狀態與 PR 證據的錯誤，
進行修正前後的即時驗證。
- `extensions/qa-channel`：合成訊息通道，具備 DM、頻道、執行緒、反應、編輯與刪除介面。
- `extensions/qa-lab`：除錯器 UI 與 QA 匯流排，用於觀察逐字稿、注入傳入訊息，以及匯出 Markdown 報告。
- `extensions/qa-matrix`、未來的執行器 Plugin：即時傳輸配接器，會在子 QA gateway 內驅動真實通道。
- `qa/`：由 repo 支援的 kickoff 任務與基準 QA 情境種子資產。
- [Mantis](/zh-TW/concepts/mantis)：針對需要真實傳輸、瀏覽器螢幕截圖、VM 狀態與 PR 證據的錯誤，進行修正前後的即時驗證。
## 指令介面
## 命令介面
每個 QA 流程都在 `pnpm openclaw qa <subcommand>` 下執行。許多都有 `pnpm qa:*`
script 別名；兩種形式都受支援。
每個 QA 流程都在 `pnpm openclaw qa <subcommand>` 下執行。許多流程有 `pnpm qa:*` script 別名；兩種形式都支援。
| 指令 | 用途 |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | 綁定的 QA 自我檢查；寫入 Markdown 報告。 |
| `qa suite` | 對 QA gateway lane 執行由 repo 支援的情境。別名：`pnpm openclaw qa suite --runner multipass`，用於一次性 Linux VM。 |
| `qa coverage` | 印出 markdown 情境涵蓋率清單（`--json` 用於機器輸出）。 |
| `qa parity-report` | 比較兩個 `qa-suite-summary.json` 檔案並寫入代理式同等性報告。 |
| `qa character-eval` | 在多個即時模型上執行角色 QA 情境，並產生評審報告。請參閱[報告](#reporting)。 |
| `qa manual` | 對選取的 provider/model lane 執行一次性提示。 |
| `qa ui` | 啟動 QA 偵錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。 |
| `qa docker-build-image` | 建置預先烘焙的 QA Docker 映像。 |
| `qa docker-scaffold` | 寫入 QA dashboard + gateway lane 的 docker-compose scaffold。 |
| `qa up` | 建置 QA site、啟動 Docker 支援的 stack、印出 URL（別名：`pnpm qa:lab:up`；`:fast` 變體會加入 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。 |
| `qa aimock` | 只啟動 AIMock provider server。 |
| `qa mock-openai` | 只啟動具情境感知的 `mock-openai` provider server。 |
| `qa credentials doctor` / `add` / `list` / `remove` | 管理共用 Convex credential pool。 |
| `qa matrix` | 針對一次性 Tuwunel homeserver 的即時傳輸 lane。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。 |
| `qa telegram` | 針對真實私有 Telegram 群組的即時傳輸 lane。 |
| `qa discord` | 針對真實私有 Discord guild channel 的即時傳輸 lane。 |
| `qa mantis` | 用於即時傳輸錯誤修正前後驗證的 runner，包含第一個 Discord 狀態反應情境。請參閱 [Mantis](/zh-TW/concepts/mantis)。 |
| 命令 | 用途 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | 內建 QA 自我檢查；寫入 Markdown 報告。 |
| `qa suite` | 對 QA gateway lane 執行由 repo 支援的情境。別名：`pnpm openclaw qa suite --runner multipass`，用於一次性的 Linux VM。 |
| `qa coverage` | 列印 Markdown 情境覆蓋率清冊（`--json` 用於機器輸出）。 |
| `qa parity-report` | 比較兩個 `qa-suite-summary.json` 檔案，並寫入 agentic 對等報告。 |
| `qa character-eval` | 跨多個即時模型執行角色 QA 情境，並產生經評判的報告。請參閱[報告](#reporting)。 |
| `qa manual` | 對選取的 provider/model lane 執行一次性提示。 |
| `qa ui` | 啟動 QA 除錯器 UI 與本機 QA 匯流排（別名：`pnpm qa:lab:ui`）。 |
| `qa docker-build-image` | 建置預先烘焙的 QA Docker 映像。 |
| `qa docker-scaffold` | 寫入 QA 儀表板 + gateway lane 的 docker-compose 腳手架。 |
| `qa up` | 建置 QA 站台、啟動 Docker 支援的堆疊並列印 URL（別名：`pnpm qa:lab:up`；`:fast` 變體會加入 `--use-prebuilt-image --bind-ui-dist --skip-ui-build`）。 |
| `qa aimock` | 只啟動 AIMock provider 伺服器。 |
| `qa mock-openai` | 只啟動具情境感知能力的 `mock-openai` provider 伺服器。 |
| `qa credentials doctor` / `add` / `list` / `remove` | 管理共享的 Convex 憑證池。 |
| `qa matrix` | 針對一次性 Tuwunel homeserver 的即時傳輸 lane。請參閱 [Matrix QA](/zh-TW/concepts/qa-matrix)。 |
| `qa telegram` | 針對真實私人 Telegram 群組的即時傳輸 lane。 |
| `qa discord` | 針對真實私人 Discord guild 頻道的即時傳輸 lane。 |
| `qa slack` | 針對真實私人 Slack 頻道的即時傳輸 lane。 |
| `qa mantis` | 針對即時傳輸錯誤的修正前後驗證執行器，包含 Discord 狀態反應證據與 Crabbox 桌面/瀏覽器 smoke。請參閱 [Mantis](/zh-TW/concepts/mantis)。 |
## 操作者流程
## 操作員流程
目前的 QA 操作者流程是一個雙窗格 QA site：
目前的 QA 操作員流程是雙窗格 QA 站台：
- 左側：帶有代理程式的 Gateway dashboard（Control UI）。
- 左側：含 agent 的 Gateway 儀表板（控制 UI）。
- 右側：QA Lab，顯示類 Slack 的逐字稿與情境計畫。
使用以下指令執行：
執行方式：
```bash
pnpm qa:lab:up
```
這會建置 QA site、啟動 Docker 支援的 gateway lane，並公開
QA Lab 頁面，讓操作者或自動化迴圈可以給代理程式 QA
任務、觀察真實通道行為，並記錄哪些成功、失敗或
仍受阻。
這會建置 QA 站台、啟動 Docker 支援的 gateway lane，並公開 QA Lab 頁面，讓操作員或自動化迴圈可以給 agent 一個 QA 任務、觀察真實通道行為，並記錄哪些項目成功、失敗或仍遭阻塞。
若要更快反覆開發 QA Lab UI，而不必每次都重建 Docker 映像，
請使用 bind-mounted QA Lab bundle 啟動 stack：
若要更快速地迭代 QA Lab UI，而不必每次都重建 Docker 映像，請使用 bind-mounted QA Lab bundle 啟動堆疊：
```bash
pnpm openclaw qa docker-build-image
@ -83,10 +74,7 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` 會讓 Docker 服務使用預先建置的映像，並將
`extensions/qa-lab/web/dist` bind-mount 到 `qa-lab` container。`qa:lab:watch`
會在變更時重建該 bundle，而當 QA Lab
資產 hash 變更時，瀏覽器會自動重新載入。
`qa:lab:up:fast` 會讓 Docker 服務使用預先建置的映像，並將 `extensions/qa-lab/web/dist` bind-mount 到 `qa-lab` 容器中。`qa:lab:watch` 會在變更時重建該 bundle，而當 QA Lab 資產雜湊變更時，瀏覽器會自動重新載入。
若要進行本機 OpenTelemetry trace smoke，請執行：
@ -94,101 +82,82 @@ pnpm qa:lab:watch
pnpm qa:otel:smoke
```
該 script 會啟動本機 OTLP/HTTP trace receiver，在啟用
`diagnostics-otel` plugin 的情況下執行 `otel-trace-smoke` QA 情境，然後
解碼匯出的 protobuf spans，並斷言發布關鍵形狀：
`openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、
`openclaw.context.assembled` 與 `openclaw.message.delivery` 必須存在；
模型呼叫在成功回合中不得匯出 `StreamAbandoned`；原始診斷 ID 與
`openclaw.content.*` attributes 必須留在 trace 之外。它會在 QA suite artifacts 旁寫入
`otel-smoke-summary.json`。
該 script 會啟動本機 OTLP/HTTP trace 接收器，在啟用 `diagnostics-otel` Plugin 的情況下執行 `otel-trace-smoke` QA 情境，接著解碼匯出的 protobuf spans，並斷言 release-critical 形狀：必須存在 `openclaw.run`、`openclaw.harness.run`、`openclaw.model.call`、`openclaw.context.assembled` 與 `openclaw.message.delivery`；成功回合中的模型呼叫不得匯出 `StreamAbandoned`；原始診斷 ID 與 `openclaw.content.*` 屬性必須留在 trace 之外。它會在 QA suite artifact 旁寫入 `otel-smoke-summary.json`。
可觀測性 QA 僅限 source checkout。npm tarball 會刻意省略
QA Lab，因此 package Docker release lanes 不會執行 `qa` 指令。變更 diagnostics
instrumentation 時，請從已建置的 source checkout 使用
`pnpm qa:otel:smoke`。
Observability QA 僅適用於原始碼 checkout。npm tarball 會有意省略 QA Lab，因此套件 Docker release lane 不會執行 `qa` 命令。變更診斷 instrumentation 時，請從已建置的原始碼 checkout 執行 `pnpm qa:otel:smoke`。
若要執行 transport-real Matrix smoke lane，請執行：
若要執行傳輸真實的 Matrix smoke lane，請執行：
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
此 lane 的完整 CLI 參考、profile/scenario 目錄、env vars 與 artifact 版面配置位於 [Matrix QA](/zh-TW/concepts/qa-matrix)。概略來說：它會在 Docker 中佈建一次性 Tuwunel homeserver、註冊臨時 driver/SUT/observer 使用者、在範圍限定於該傳輸的子 QA gateway 內執行真實 Matrix plugin（沒有 `qa-channel`），然後在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下寫入 Markdown 報告、JSON 摘要、observed-events artifact 與合併輸出記錄。
此 lane 的完整 CLI 參考、profile/情境目錄、環境變數與 artifact 版面配置位於 [Matrix QA](/zh-TW/concepts/qa-matrix)。簡而言之：它會在 Docker 中佈建一次性的 Tuwunel homeserver、註冊臨時 driver/SUT/observer 使用者、在限定於該傳輸的子 QA gateway 內執行真實 Matrix Plugin（不使用 `qa-channel`），接著在 `.artifacts/qa-e2e/matrix-<timestamp>/` 下寫入 Markdown 報告、JSON 摘要、observed-events artifact 與合併輸出日誌。
針對 transport-real Telegram 與 Discord smoke lanes：
針對傳輸真實的 Telegram、Discord 與 Slack smoke lane：
```bash
pnpm openclaw qa telegram
pnpm openclaw qa discord
pnpm openclaw qa slack
```
兩者都以既有真實通道為目標，並使用兩個 bots（driver + SUT）。必要 env vars、情境清單、輸出 artifacts 與 Convex credential pool 記錄於下方的 [Telegram 與 Discord QA 參考](#telegram-and-discord-qa-reference)。
它們會以含兩個 bot（driver + SUT）的既有真實通道為目標。必要環境變數、情境清單、輸出 artifact 與 Convex 憑證池記錄於下方的 [Telegram、Discord 與 Slack QA 參考](#telegram-discord-and-slack-qa-reference)。
使用 pooled live credentials 前，請執行：
使用集區化即時憑證之前，請執行：
```bash
pnpm openclaw qa credentials doctor
```
doctor 會檢查 Convex broker env、驗證 endpoint 設定，並在 maintainer secret 存在時驗證 admin/list 可達性。它只會回報 secret 的已設定/缺漏狀態。
doctor 會檢查 Convex broker 環境、驗證 endpoint 設定，並在 maintainer secret 存在時驗證 admin/list 可達性。它只會回報 secret 的已設定/缺漏狀態。
## 即時傳輸涵蓋率
## 即時傳輸覆蓋率
即時傳輸 lanes 共用一份契約，而不是各自發明自己的情境清單形狀。`qa-channel` 是廣泛的合成產品行為 suite，不屬於即時傳輸涵蓋率矩陣。
即時傳輸 lane 共用一份合約，而不是各自發明自己的情境清單形狀。`qa-channel` 是廣泛的合成產品行為 suite，不屬於即時傳輸覆蓋率矩陣的一部分。
| Lane | Canary | Mention gating | Bot-to-bot | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration |
| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Lane | Canary | 提及閘控 | Bot 對 Bot | Allowlist 封鎖 | 頂層回覆 | 重新啟動續接 | 執行緒後續追蹤 | 執行緒隔離 | 反應觀察 | Help 命令 | 原生命令註冊 |
| -------- | ------ | -------- | ---------- | --------------- | -------- | ------------ | ---------------- | ------------ | -------- | --------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
這會讓 `qa-channel` 保持作為廣泛的產品行為 suite，同時 Matrix、
Telegram 與未來即時傳輸共用一份明確的傳輸契約
檢查清單。
這會讓 `qa-channel` 保持作為廣泛的產品行為 suite，同時讓 Matrix、Telegram 與未來的即時傳輸共用一份明確的傳輸合約檢查清單。
若要在不將 Docker 帶入 QA 路徑的情況下執行一次性 Linux VM lane，請執行：
若要在不把 Docker 帶入 QA 路徑的情況下執行一次性 Linux VM lane，請執行：
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
這會啟動全新的 Multipass guest、安裝 dependencies、在 guest 內建置 OpenClaw、
執行 `qa suite`，然後將正常 QA 報告與
摘要複製回 host 上的 `.artifacts/qa-e2e/...`。
這會啟動全新的 Multipass guest、安裝相依性、在 guest 內建置 OpenClaw、執行 `qa suite`，接著將一般 QA 報告與摘要複製回 host 上的 `.artifacts/qa-e2e/...`。
它會重用與 host 上 `qa suite` 相同的情境選取行為。
Host 與 Multipass suite runs 預設會使用隔離的 gateway workers 平行執行多個選取情境。
`qa-channel` 預設 concurrency 為
4，並受選取的情境數量限制。使用 `--concurrency <count>` 調整
worker 數量，或使用 `--concurrency 1` 進行序列執行。
當任何情境失敗時，指令會以非零碼結束。若你想要 artifacts 但不想要失敗的 exit code，
請使用 `--allow-failures`。
Live runs 會轉送對 guest 實用且受支援的 QA auth inputs：
env-based provider keys、QA live provider config path，以及
`CODEX_HOME`（若存在）。請將 `--output-dir` 保持在 repo root 下，讓 guest
可以透過掛載的 workspace 寫回。
Host 與 Multipass suite run 預設會以隔離的 gateway workers 平行執行多個選取的情境。`qa-channel` 預設 concurrency 為 4，並受選取的情境數量上限限制。使用 `--concurrency <count>` 調整 worker 數量，或使用 `--concurrency 1` 進行序列執行。
當任何情境失敗時，命令會以非零狀態結束。當你想要 artifact 而不要失敗的結束碼時，請使用 `--allow-failures`。
即時 run 會轉送對 guest 實用的受支援 QA auth 輸入：以環境為基礎的 provider key、QA live provider 設定路徑，以及存在時的 `CODEX_HOME`。請將 `--output-dir` 保持在 repo root 底下，讓 guest 能透過掛載的 workspace 寫回。
## Telegram 與 Discord QA 參考
## Telegram、Discord 與 Slack QA 參考
Matrix 有[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量與 Docker-backed homeserver 佈建較多。Telegram 與 Discord 較小型，每個只有少數情境、沒有 profile system，並針對既有真實通道，因此它們的參考放在這裡。
Matrix 有一個[專屬頁面](/zh-TW/concepts/qa-matrix)，因為其情境數量與 Docker 支援的 homeserver 佈建。Telegram、Discord 與 Slack 較小，每個只有少數情境、沒有 profile 系統，並針對既有真實通道，因此它們的參考位於此處。
### 共用 CLI flags
### 共享 CLI 旗標
兩個 lanes 都透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同 flags：
這些 lane 透過 `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` 註冊，並接受相同旗標：
| Flag | Default | Description |
| ------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | 只執行此情境。可重複指定。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord}-<timestamp>` | 寫入報告、摘要、觀察到的訊息與輸出記錄的位置。相對路徑會以 `--repo-root` 為基準解析。 |
| `--repo-root <path>` | `process.cwd()` | 從中立 cwd 呼叫時的儲存庫根目錄。 |
| `--sut-account <id>` | `sut` | QA Gateway 設定內的暫時帳號 ID。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可運作）。 |
| `--model <ref>` / `--alt-model <ref>` | 提供者預設值 | 主要/替代模型參照。 |
| `--fast` | 關閉 | 支援時使用提供者快速模式。 |
| `--credential-source <env\|convex>` | `env` | 請參閱 [Convex 憑證池](#convex-credential-pool)。 |
| `--credential-role <maintainer\|ci>` | CI 中為 `ci`，否則為 `maintainer` | 使用 `--credential-source convex` 時採用的角色。 |
| 旗標 | 預設值 | 說明 |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | 只執行此情境。可重複指定。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 寫入報告、摘要、觀察到的訊息和輸出記錄的位置。相對路徑會以 `--repo-root` 為基準解析。 |
| `--repo-root <path>` | `process.cwd()` | 從中立 cwd 呼叫時的儲存庫根目錄。 |
| `--sut-account <id>` | `sut` | QA Gateway 設定內的暫時帳號 id。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 或 `live-frontier`（舊版 `live-openai` 仍可使用）。 |
| `--model <ref>` / `--alt-model <ref>` | provider default | 主要／替代模型參照。 |
| `--fast` | off | 支援時啟用供應商快速模式。 |
| `--credential-source <env\|convex>` | `env` | 請參閱 [Convex 憑證池](#convex-credential-pool)。 |
| `--credential-role <maintainer\|ci>` | CI 中為 `ci`，否則為 `maintainer` | 使用 `--credential-source convex` 時使用的角色。 |
任何情境失敗時，兩者都會以非零狀態結束。`--allow-failures` 會寫入成品，但不會設定失敗的結束代碼。
任何情境失敗時，各通道都會以非零狀態結束。`--allow-failures` 會寫入成品，但不會設定失敗的退出碼。
### Telegram QA
@ -196,17 +165,17 @@ Matrix 有[專屬頁面](/zh-TW/concepts/qa-matrix)，因為它的情境數量
pnpm openclaw qa telegram
```
目標是一個真實的私人 Telegram 群組，並使用兩個不同的 Bot（driver + SUT）。SUT Bot 必須有 Telegram 使用者名稱；當兩個 Bot 都在 `@BotFather` 啟用 **Bot-to-Bot Communication Mode** 時，Bot 對 Bot 觀察的效果最佳。
目標是一個真實的私人 Telegram 群組，搭配兩個不同的 bot（driver + SUT）。SUT bot 必須有 Telegram 使用者名稱；當兩個 bot 都在 `@BotFather` 中啟用 **Bot-to-Bot Communication Mode** 時，bot 對 bot 觀察效果最佳。
使用 `--credential-source env` 時必要的 env：
使用 `--credential-source env` 時所需的 env：
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — 數字 chat id（字串）。
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — 數值聊天 id（字串）。
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
選用：
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在觀察到的訊息成品中保留訊息本文（預設會遮蔽）。
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文（預設會遮蔽）。
情境（`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`）：
@ -222,7 +191,7 @@ pnpm openclaw qa telegram
輸出成品：
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — 包含從 canary 開始的每則回覆 RTT（driver 傳送 → 觀察到 SUT 回覆）。
- `telegram-qa-summary.json` — 從 canary 開始，包含每則回覆的 RTT（driver 傳送 → 觀察到 SUT 回覆）。
- `telegram-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
### Discord QA
@ -231,28 +200,28 @@ pnpm openclaw qa telegram
pnpm openclaw qa discord
```
目標是一個真實的私人 Discord guild 頻道，並使用兩個 Bot：由測試框架控制的 driver Bot，以及由子 OpenClaw Gateway 透過內建 Discord Plugin 啟動的 SUT Bot。會驗證頻道提及處理、SUT Bot 已向 Discord 註冊原生 `/help` 指令，以及選擇啟用的 Mantis 證據情境。
目標是一個真實的私人 Discord guild 頻道，搭配兩個 bot：由測試框架控制的 driver bot，以及由子 OpenClaw Gateway 透過 bundled Discord plugin 啟動的 SUT bot。驗證頻道提及處理、SUT bot 已向 Discord 註冊原生 `/help` 命令，以及選擇啟用的 Mantis 證據情境。
使用 `--credential-source env` 時必要的 env：
使用 `--credential-source env` 時所需的 env：
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必須符合 Discord 回傳的 SUT Bot 使用者 ID（否則該通道會快速失敗）。
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — 必須符合 Discord 傳回的 SUT bot 使用者 id（否則該通道會快速失敗）。
選用：
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 會在觀察到的訊息成品中保留訊息本文。
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文。
情境（`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`）：
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — 選擇啟用的 Mantis 情境。因為它會將 SUT 切換為永遠開啟、僅工具的 guild 回覆，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST reaction 時間軸以及 HTML/PNG 視覺成品，所以會單獨執行。
- `discord-status-reactions-tool-only` — 選擇啟用的 Mantis 情境。因為它會將 SUT 切換為一律啟用、僅工具的 guild 回覆，並設定 `messages.statusReactions.enabled=true`，接著擷取 REST 反應時間軸以及 HTML/PNG 視覺成品，所以會單獨執行。
明確執行 Mantis status-reaction 情境：
明確執行 Mantis 狀態反應情境：
```bash
pnpm openclaw qa discord \
@ -268,118 +237,148 @@ pnpm openclaw qa discord \
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
- 執行 status-reaction 情境時，會產生 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
- 執行狀態反應情境時，會產生 `discord-qa-reaction-timelines.json` 和 `discord-status-reactions-tool-only-timeline.png`。
### Slack QA
```bash
pnpm openclaw qa slack
```
目標是一個真實的私人 Slack 頻道，搭配兩個不同的 bot：由測試框架控制的 driver bot，以及由子 OpenClaw Gateway 透過 bundled Slack plugin 啟動的 SUT bot。
使用 `--credential-source env` 時所需的 env：
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
選用：
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` 會在觀察訊息成品中保留訊息本文。
情境（`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`）：
- `slack-canary`
- `slack-mention-gating`
輸出成品：
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — 除非設定 `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`，否則本文會被遮蔽。
### Convex 憑證池
Telegram 和 Discord 通道都可以從共用的 Convex 池租用憑證，而不是讀取上方 env vars。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得獨佔租約、在執行期間對租約送出 Heartbeat，並在關閉時釋放租約。池種類為 `"telegram"` 和 `"discord"`。
Telegram、Discord 和 Slack 通道可以從共享的 Convex 池租用憑證，而不是讀取上述 env vars。傳入 `--credential-source convex`（或設定 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）；QA Lab 會取得一個獨佔租約，在執行期間傳送 Heartbeat，並在關閉時釋放租約。池種類為 `"telegram"`、`"discord"` 和 `"slack"`。
Broker 在 `admin/add` 驗證的 payload 形狀：
Broker 會在 `admin/add` 驗證的 payload 形狀：
- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必須是數字 chat-id 字串。
- Telegram（`kind: "telegram"`）：`{ groupId: string, driverToken: string, sutToken: string }` — `groupId` 必須是數值聊天 id 字串。
- Discord（`kind: "discord"`）：`{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`。
操作用 env vars 與 Convex broker 端點合約位於 [測試 → 透過 Convex 共用 Telegram 憑證](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（該區段名稱早於 Discord 支援；兩種種類的 broker 語義相同）。
操作用 env vars 和 Convex broker 端點合約位於 [測試 → 透過 Convex 共享 Telegram 憑證](/zh-TW/help/testing#shared-telegram-credentials-via-convex-v1)（該章節名稱早於 Discord 支援；兩種種類的 broker 語意相同）。
## Repo 支援的種子
## 儲存庫支援的種子
種子資產位於 `qa/`：
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
這些刻意放在 git 中，讓 QA 計畫對人類與代理都可見。
這些檔案刻意放在 git 中，讓 QA 計畫對人員與 agent 都可見。
`qa-lab` 應保持為通用 markdown 執行器。每個情境 markdown 檔案都是一次測試執行的事實來源，並應定義：
`qa-lab` 應保持為通用 markdown runner。每個情境 markdown 檔案都是一次測試執行的真實來源，且應定義：
- 情境中繼資料
- 選用的分類、能力、通道與風險中繼資料
- 選用的類別、能力、通道和風險中繼資料
- 文件與程式碼參照
- 選用的 Plugin 需求
- 選用的 Gateway 設定 patch
- 選用的 plugin 需求
- 選用的 Gateway 設定修補
- 可執行的 `qa-flow`
支援 `qa-flow` 的可重用 runtime 介面可以維持通用且跨領域。例如，markdown 情境可以結合傳輸端輔助工具與瀏覽器端輔助工具，透過 Gateway `browser.request` seam 驅動內嵌 Control UI，而不需要加入特殊案例執行器。
支援 `qa-flow` 的可重用執行階段介面可以保持通用且跨面向。例如，markdown 情境可以結合傳輸端 helper 與瀏覽器端 helper，透過 Gateway `browser.request` seam 驅動內嵌的 Control UI，而不需要加入特殊案例 runner。
情境檔案應依產品能力分組，而不是依原始碼樹資料夾分組。檔案移動時請保持情境 ID 穩定；使用 `docsRefs` 和 `codeRefs` 追蹤實作。
情境檔案應依產品能力分組，而不是依原始碼樹資料夾分組。檔案移動時請保持情境 ID 穩定；使用 `docsRefs` 和 `codeRefs` 進行實作可追溯性。
基準清單應保持足夠廣泛，以涵蓋：
- DM 與頻道聊天
- DM 和頻道聊天
- thread 行為
- 訊息動作生命週期
- cron callback
- cron callbacks
- 記憶回想
- 模型切換
- 子代理交接
- 儲存庫讀取與文件讀取
- subagent handoff
- 讀取儲存庫與讀取文件
- 一個小型建置任務，例如 Lobster Invaders
## 提供者模擬通道
## 供應商 mock 通道
`qa suite` 有兩個本機提供者模擬通道：
`qa suite` 有兩個本機供應商 mock 通道：
- `mock-openai` 是具備情境感知能力的 OpenClaw 模擬。它仍是 repo 支援 QA 與 parity gate 的預設決定性模擬通道。
- `aimock` 會啟動 AIMock 支援的提供者伺服器，用於實驗性協定、fixture、record/replay 與 chaos 覆蓋。它是加成項，不會取代 `mock-openai` 情境分派器。
- `mock-openai` 是具情境感知的 OpenClaw mock。它仍是儲存庫支援 QA 和 parity gates 的預設決定性 mock 通道。
- `aimock` 會啟動由 AIMock 支援的供應商伺服器，用於實驗性通訊協定、fixture、record/replay 和 chaos 覆蓋。它是加成性質，且不會取代 `mock-openai` 情境 dispatcher。
提供者通道實作位於 `extensions/qa-lab/src/providers/`。每個提供者都擁有自己的預設值、本機伺服器啟動、Gateway 模型設定、auth-profile 暫存需求，以及 live/mock 能力旗標。共用 suite 與 Gateway 程式碼應透過提供者登錄路由，而不是依提供者名稱分支。
供應商通道實作位於 `extensions/qa-lab/src/providers/` 之下。每個供應商都擁有自己的預設值、本機伺服器啟動、Gateway 模型設定、auth-profile staging 需求，以及 live/mock 能力旗標。共享 suite 和 Gateway 程式碼應透過供應商 registry 路由，而不是依供應商名稱分支。
## 傳輸配接器
`qa-lab` 擁有用於 markdown QA 情境的通用傳輸 seam。`qa-channel` 是該 seam 上的第一個配接器，但設計目標更廣：未來真實或合成頻道應接入同一個 suite 執行器，而不是新增傳輸專用 QA 執行器。
`qa-lab` 擁有一個供 markdown QA 情境使用的通用傳輸 seam。`qa-channel` 是該 seam 上的第一個配接器，但設計目標更廣：未來真實或合成頻道應接入相同的 suite runner，而不是加入傳輸專屬 QA runner。
在架構層級，分工如下：
- `qa-lab` 擁有通用情境執行、worker 並行、成品寫入與報告。
- 傳輸配接器擁有 Gateway 設定、就緒狀態、輸入與輸出觀察、傳輸動作，以及正規化傳輸狀態。
- `qa/scenarios/` 下的 markdown 情境檔案定義測試執行；`qa-lab` 提供執行它們的可重用 runtime 介面。
- 傳輸配接器擁有 Gateway 設定、就緒狀態、入站與出站觀察、傳輸動作，以及正規化傳輸狀態。
- `qa/scenarios/` 下的 markdown 情境檔案定義測試執行；`qa-lab` 提供執行它們的可重用執行階段介面。
### 新增頻道
將頻道加入 markdown QA 系統只需要兩件事：
將頻道加入 markdown QA 系統時，只需要兩件事：
1. 該頻道的傳輸配接器。
2. 測試該頻道合約的情境包。
2. 測試該頻道合約的情境套件。
當共用 `qa-lab` host 可以擁有流程時，請勿新增頂層 QA 指令根。
當共享的 `qa-lab` host 可以擁有流程時，不要新增新的頂層 QA 命令根。
`qa-lab` 擁有共用 host 機制：
`qa-lab` 擁有共享 host 機制：
- `openclaw qa` 指令根
- suite 啟動與拆卸
- `openclaw qa` 命令根
- suite 啟動與拆除
- worker 並行
- 成品寫入
- 報告產生
- 情境執行
- 舊版 `qa-channel` 情境的相容 alias
- 舊版 `qa-channel` 情境的相容別名
執行器 Plugin 擁有傳輸合約：
Runner plugins 擁有傳輸合約：
- `openclaw qa <runner>` 如何掛載在共用 `qa` 根底下
- 如何為該傳輸設定 Gateway
- `openclaw qa <runner>` 如何掛載在共享 `qa` 根之下
- Gateway 如何針對該傳輸進行設定
- 如何檢查就緒狀態
- 如何注入輸入事件
- 如何觀察輸出訊息
- 如何公開 transcript 與正規化傳輸狀態
- 如何注入入站事件
- 如何觀察出站訊息
- 如何公開 transcripts 和正規化傳輸狀態
- 如何執行傳輸支援的動作
- 如何處理傳輸專用 reset 或清理
- 如何處理傳輸專屬重設或清理
新頻道的最低採用門檻：
1. 讓 `qa-lab` 繼續作為共用 `qa` 根的擁有者。
2. 在共用 `qa-lab` host seam 上實作傳輸執行器。
3. 將傳輸專用機制保留在執行器 Plugin 或頻道測試框架內。
4. 將執行器掛載為 `openclaw qa <runner>`，而不是註冊競爭的根指令。執行器 Plugin 應在 `openclaw.plugin.json` 宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。保持 `runtime-api.ts` 輕量；lazy CLI 與執行器執行應留在個別進入點後方。
5. 在主題式 `qa/scenarios/` 目錄下撰寫或改寫 markdown 情境。
6. 為新情境使用通用情境輔助工具。
7. 除非儲存庫正在進行有意的遷移，否則保持既有相容 alias 可運作。
1. 保留 `qa-lab` 作為共用 `qa` 根的擁有者。
2. 在共用的 `qa-lab` 主機銜接層上實作傳輸執行器。
3. 將傳輸專屬機制保留在執行器 Plugin 或通道測試工具中。
4. 將執行器掛載為 `openclaw qa <runner>`，而不是註冊互相競爭的根命令。執行器 Plugin 應在 `openclaw.plugin.json` 中宣告 `qaRunners`，並從 `runtime-api.ts` 匯出相符的 `qaRunnerCliRegistrations` 陣列。讓 `runtime-api.ts` 保持輕量；延遲 CLI 和執行器執行應保留在獨立進入點後方。
5. 在主題式 `qa/scenarios/` 目錄下撰寫或調整 Markdown 情境。
6. 對新情境使用通用情境輔助工具。
7. 除非 repo 正在進行有意的遷移，否則保持現有相容性別名可用。
決策規則很嚴格：
- 如果行為可以在 `qa-lab` 中表達一次，就放在 `qa-lab`。
- 如果行為取決於單一頻道傳輸，就保留在該執行器 Plugin 或 Plugin 測試框架中。
- 如果某個情境需要多個頻道都能使用的新能力，請新增通用輔助工具，而不是在 `suite.ts` 中加入頻道專用分支。
- 如果某個行為只對單一傳輸有意義，請讓情境維持傳輸專用，並在情境合約中明確表示。
- 如果行為依賴單一通道傳輸，就將它保留在該執行器 Plugin 或 Plugin 測試工具中。
- 如果情境需要多個通道都能使用的新能力，請新增通用輔助工具，而不是在 `suite.ts` 中加入通道專屬分支。
- 如果某個行為只對單一傳輸有意義，請讓情境保持傳輸專屬，並在情境契約中明確說明。
### 情境輔助工具名稱
@ -398,22 +397,22 @@ Broker 在 `admin/add` 驗證的 payload 形狀：
- `formatTransportTranscript`
- `resetTransport`
相容性別名仍可用於現有情境 — `waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus` — 但新的情境撰寫應使用通用名稱。這些別名的存在是為了避免一次性遷移，而不是未來的模式。
相容性別名仍可供現有情境使用 — `waitForQaChannelReady`、`waitForOutboundMessage`、`waitForNoOutbound`、`formatConversationTranscript`、`resetBus` — 但撰寫新情境時應使用通用名稱。這些別名存在是為了避免一次性遷移，而不是未來的模型。
## 回報
`qa-lab` 會從觀察到的匯流排時間軸匯出 Markdown 協定報告。
報告應回答：
- 哪些項目正常運作
- 哪些項目失敗
- 哪些項目仍受阻
- 哪些正常運作
- 哪些失敗
- 哪些仍受阻
- 哪些後續情境值得加入
若要取得可用情境的清單 — 在評估後續工作規模或接入新傳輸時很有用 — 請執行 `pnpm openclaw qa coverage`（加入 `--json` 可取得機器可讀輸出）。
若要查看可用情境清單 — 在評估後續工作規模或接線新傳輸時很有用 — 請執行 `pnpm openclaw qa coverage`（加入 `--json` 取得機器可讀輸出）。
若要進行角色與風格檢查，請在多個即時模型
refs 上執行相同情境，並寫出經評審的 Markdown 報告：
若要進行角色與風格檢查，請跨多個即時模型
refs 執行相同情境，並撰寫經評審的 Markdown 報告：
```bash
pnpm openclaw qa character-eval \
@ -434,30 +433,31 @@ pnpm openclaw qa character-eval \
此命令會執行本機 QA Gateway 子程序，而不是 Docker。角色評估
情境應透過 `SOUL.md` 設定 persona，然後執行一般使用者回合，
例如聊天、工作區協助，以及小型檔案任務。不應告知候選模型
它正在被評估。此命令會保留每份完整
transcript，記錄基本執行統計資料，然後在支援時以快速模式搭配
`xhigh` reasoning 詢問評審模型，依自然度、氛圍和幽默感為執行結果排名。
比較不同提供者時請使用 `--blind-judge-models`：評審提示仍會取得
每份 transcript 和執行狀態，但候選 refs 會被替換為中性的
例如聊天、workspace 協助，以及小型檔案任務。不應告知候選模型
它正在接受評估。此命令會保留每份完整
transcript、記錄基本執行統計，然後請評審模型以快速模式搭配
支援時的 `xhigh` reasoning，依自然度、氛圍和幽默感對執行結果排名。
比較供應商時使用 `--blind-judge-models`：評審提示仍會取得
每份 transcript 與執行狀態，但候選 refs 會替換成中性
標籤，例如 `candidate-01`；報告會在解析後將排名對應回真實 refs。
候選執行預設使用 `high` thinking，GPT-5.5 使用 `medium`，較舊且支援的 OpenAI 評估 refs 使用 `xhigh`。可用
`--model provider/model,thinking=<level>` 內嵌覆寫特定候選。`--thinking <level>` 仍會設定
全域備援，而較舊的 `--model-thinking <provider/model=level>` 形式會
保留以維持相容性。
OpenAI 候選 refs 預設使用快速模式，因此在提供者支援時會使用
優先處理。當單一候選或評審需要覆寫時，請內嵌加入 `,fast`、`,no-fast` 或 `,fast=false`。只有在你想要
強制所有候選模型開啟快速模式時，才傳入 `--fast`。候選與評審的耗時會
記錄在報告中供基準分析使用，但評審提示會明確說明
候選執行預設使用 `high` thinking，GPT-5.5 使用 `medium`，而支援它的
較舊 OpenAI 評估 refs 使用 `xhigh`。用
`--model provider/model,thinking=<level>` 內聯覆寫特定候選。`--thinking <level>` 仍會設定
全域 fallback，且較舊的 `--model-thinking <provider/model=level>` 形式
會保留以維持相容性。
OpenAI 候選 refs 預設使用快速模式，因此在供應商支援時會使用
優先處理。當單一候選或評審需要覆寫時，請內聯加入 `,fast`、`,no-fast` 或 `,fast=false`。只有在想要
強制所有候選模型開啟快速模式時才傳入 `--fast`。候選和評審耗時會
記錄在報告中以供基準分析，但評審提示會明確要求
不要依速度排名。
候選與評審模型執行預設並行度皆為 16。當提供者限制或本機 Gateway
壓力使執行過於嘈雜時，請降低
候選與評審模型執行都預設使用並行度 16。當供應商限制或本機 Gateway
壓力讓執行過於嘈雜時，請降低
`--concurrency` 或 `--judge-concurrency`。
未傳入候選 `--model` 時，角色評估預設會使用
未傳入候選 `--model` 時，角色評估預設使用
`openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、
`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
`moonshot/kimi-k2.5`，以及
`google/gemini-3.1-pro-preview`。
未傳入 `--model` 時的 `google/gemini-3.1-pro-preview`。
未傳入 `--judge-model` 時，評審預設為
`openai/gpt-5.5,thinking=xhigh,fast` 和
`anthropic/claude-opus-4-6,thinking=high`。
@ -467,4 +467,4 @@ OpenAI 候選 refs 預設使用快速模式，因此在提供者支援時會使
- [矩陣 QA](/zh-TW/concepts/qa-matrix)
- [QA 通道](/zh-TW/channels/qa-channel)
- [測試](/zh-TW/help/testing)
- [儀表板](/zh-TW/web/dashboard)
- [Dashboard](/zh-TW/web/dashboard)

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

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

520
docs/zh-TW/gateway/config-agents.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 調整代理預設值（模型、思考、工作區、Heartbeat、媒體、Skills）
- 設定多代理路由與綁定
- 設定多代理路由與繫結
- 調整工作階段、訊息傳遞與對話模式行為
summary: 代理預設值、多代理路由、工作階段、訊息和對話設定
summary: 代理預設值、多代理路由、工作階段、訊息與對話設定
title: 設定 — 代理程式
x-i18n:
generated_at: "2026-05-03T21:32:01Z"
generated_at: "2026-05-04T02:44:27Z"
model: gpt-5.5
provider: openai
source_hash: b25371c34b9f8b0cacce021879e43e6a65b86d626dc87d5bfa05dcae80ac32e4
source_hash: 9d339b82b8b3b82e55820ca6568b3ed569fe64135e698515fa7f316c3afbbfd9
source_path: gateway/config-agents.md
workflow: 16
---
代理程式範圍的設定鍵位於 `agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 之下。關於通道、工具、Gateway 執行階段，以及其他
Agent 作用域的設定鍵位於 `agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 下。關於通道、工具、Gateway 執行階段，以及其他
頂層鍵，請參閱[設定參考](/zh-TW/gateway/configuration-reference)。
## 代理程式預設值
## Agent 預設值
### `agents.defaults.workspace`
@ -32,7 +32,7 @@ x-i18n:
### `agents.defaults.repoRoot`
選用的儲存庫根目錄，會顯示在系統提示詞的 Runtime 行中。若未設定，OpenClaw 會從工作區往上自動偵測。
選用的儲存庫根目錄，會顯示在系統提示的執行階段行中。如果未設定，OpenClaw 會從工作區往上自動偵測。
```json5
{
@ -42,8 +42,8 @@ x-i18n:
### `agents.defaults.skills`
選用的代理程式預設 Skills 允許清單，適用於未設定
`agents.list[].skills` 的代理程式。
選用的預設 Skills 允許清單，適用於未設定
`agents.list[].skills` 的 agent。
```json5
{
@ -58,15 +58,15 @@ x-i18n:
}
```
- 省略 `agents.defaults.skills` 時，預設不限制 Skills。
- 省略 `agents.list[].skills` 時，會繼承預設值。
- 將 `agents.list[].skills: []` 設為沒有 Skills。
- 非空的 `agents.list[].skills` 清單就是該代理程式的最終集合；它
- 省略 `agents.defaults.skills`，即可預設不限制 Skills。
- 省略 `agents.list[].skills`，即可繼承預設值。
- 設定 `agents.list[].skills: []`，即可不使用 Skills。
- 非空的 `agents.list[].skills` 清單就是該 agent 的最終集合；
不會與預設值合併。
### `agents.defaults.skipBootstrap`
停用自動建立工作區啟動程序檔案（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
停用自動建立工作區啟動檔案（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
```json5
{
@ -76,7 +76,7 @@ x-i18n:
### `agents.defaults.skipOptionalBootstrapFiles`
略過建立選定的選用工作區檔案，同時仍會寫入必要的啟動程序檔案。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。
在仍寫入必要啟動檔案的同時，略過建立選定的選用工作區檔案。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。
```json5
{
@ -90,10 +90,10 @@ x-i18n:
### `agents.defaults.contextInjection`
控制工作區啟動程序檔案何時注入系統提示詞。預設值：`"always"`。
控制工作區啟動檔案何時注入系統提示。預設值：`"always"`。
- `"continuation-skip"`：安全的延續回合（在已完成的助理回應之後）會略過重新注入工作區啟動程序，降低提示詞大小。Heartbeat 執行與 Compaction 後重試仍會重建脈絡。
- `"never"`：在每個回合停用工作區啟動程序與脈絡檔案注入。僅應用於完全自行管理提示詞生命週期的代理程式（自訂脈絡引擎、建置自身脈絡的原生執行階段，或不需要啟動程序的特殊工作流程）。Heartbeat 與 Compaction 復原回合也會略過注入。
- `"continuation-skip"`：安全的延續回合（在已完成的助理回應之後）會略過重新注入工作區啟動內容，以減少提示大小。Heartbeat 執行和 Compaction 後重試仍會重建上下文。
- `"never"`：在每個回合停用工作區啟動與上下文檔案注入。僅對完全自行掌控提示生命週期的 agent 使用此選項（自訂上下文引擎、建立自身上下文的原生執行階段，或不需要專用啟動流程的工作流程）。Heartbeat 和 Compaction 復原回合也會略過注入。
```json5
{
@ -103,7 +103,7 @@ x-i18n:
### `agents.defaults.bootstrapMaxChars`
每個工作區啟動程序檔案在截斷前的最大字元數。預設值：`12000`。
截斷前每個工作區啟動檔案的字元上限。預設值：`12000`。
```json5
{
@ -113,7 +113,7 @@ x-i18n:
### `agents.defaults.bootstrapTotalMaxChars`
所有工作區啟動程序檔案合計注入的最大總字元數。預設值：`60000`。
跨所有工作區啟動檔案注入的總字元上限。預設值：`60000`。
```json5
{
@ -123,12 +123,16 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
控制啟動程序脈絡遭截斷時，代理程式可見的警告文字。
控制啟動上下文被截斷時，agent 可見的系統提示通知。
預設值：`"once"`。
- `"off"`：永不將警告文字注入系統提示詞。
- `"once"`：每個唯一截斷簽章只注入一次警告（建議）。
- `"always"`：存在截斷時，每次執行都注入警告。
- `"off"`：永不將截斷通知文字注入系統提示。
- `"once"`：每個唯一截斷簽章只注入一次簡潔通知（建議）。
- `"always"`：只要存在截斷，每次執行都注入簡潔通知。
詳細的原始/注入計數與設定調校欄位會保留在診斷資料中，
例如上下文/狀態報告和記錄；例行 WebChat 使用者/執行階段上下文只會
取得簡潔的復原通知。
```json5
{
@ -136,35 +140,35 @@ x-i18n:
}
```
### 脈絡預算所有權對照表
### 上下文預算歸屬對照表
OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分離，
OpenClaw 有多個高容量提示/上下文預算，且刻意依子系統拆分，
而不是全部流經同一個通用旋鈕。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
一般工作區啟動程序注入。
一般工作區啟動注入。
- `agents.defaults.startupContext.*`：
一次性的重設／啟動模型執行前置內容，包含近期每日
`memory/*.md` 檔案。單純聊天 `/new` 與 `/reset` 命令會
確認重設，而不叫用模型。
一次性的重設/啟動模型執行前置內容，包括最近的每日
`memory/*.md` 檔案。單獨的聊天 `/new` 和 `/reset` 命令會
在不叫用模型的情況下確認重設。
- `skills.limits.*`：
注入系統提示詞的精簡 Skills 清單。
注入系統提示的精簡 Skills 清單。
- `agents.defaults.contextLimits.*`：
有界限的執行階段摘錄，以及注入的執行階段所擁有區塊。
有界的執行階段摘錄和注入的執行階段所屬區塊。
- `memory.qmd.limits.*`：
索引記憶體搜尋片段與注入大小設定。
已索引記憶體搜尋片段與注入大小。
只有在某個代理程式需要不同預算時，才使用對應的每代理程式覆寫：
只有在某個 agent 需要不同預算時，才使用相符的每 agent 覆寫：
- `agents.list[].skillsLimits.maxSkillsPromptChars`
- `agents.list[].contextLimits.*`
#### `agents.defaults.startupContext`
控制重設／啟動模型執行時，第一回合注入的啟動前置內容。
單純聊天 `/new` 與 `/reset` 命令會確認重設，而不叫用
模型，因此不會載入此前置內容。
控制在重設/啟動模型執行時注入的第一回合啟動前置內容。
單獨的聊天 `/new` 和 `/reset` 命令會在不叫用模型的情況下確認重設，
因此不會載入此前置內容。
```json5
{
@ -185,7 +189,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分
#### `agents.defaults.contextLimits`
有界限執行階段脈絡介面的共用預設值。
有界執行階段上下文表面的共用預設值。
```json5
{
@ -202,15 +206,17 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分
}
```
- `memoryGetMaxChars`：在加入截斷中繼資料與延續通知前，預設的 `memory_get` 摘錄上限。
- `memoryGetDefaultLines`：省略 `lines` 時，預設的 `memory_get` 行視窗。
- `toolResultMaxChars`：即時工具結果上限，用於持久化結果與溢位復原。
- `memoryGetMaxChars`：加入截斷中繼資料和延續通知前，
預設的 `memory_get` 摘錄上限。
- `memoryGetDefaultLines`：省略 `lines` 時，
預設的 `memory_get` 行視窗。
- `toolResultMaxChars`：用於持久化結果和溢位復原的即時工具結果上限。
- `postCompactionMaxChars`：Compaction 後重新整理注入期間使用的 AGENTS.md 摘錄上限。
#### `agents.list[].contextLimits`
共用 `contextLimits` 旋鈕的每代理程式覆寫。省略的欄位會繼承
自 `agents.defaults.contextLimits`。
共用 `contextLimits` 旋鈕的每 agent 覆寫。省略的欄位會繼承自
`agents.defaults.contextLimits`。
```json5
{
@ -236,7 +242,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分
#### `skills.limits.maxSkillsPromptChars`
注入系統提示詞的精簡 Skills 清單全域上限。這
注入系統提示的精簡 Skills 清單全域上限。這
不會影響依需求讀取 `SKILL.md` 檔案。
```json5
@ -251,7 +257,7 @@ OpenClaw 有多個高容量提示詞／脈絡預算，且刻意依子系統分
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
Skills 提示詞預算的每代理程式覆寫。
Skills 提示預算的每 agent 覆寫。
```json5
{
@ -270,11 +276,11 @@ Skills 提示詞預算的每代理程式覆寫。
### `agents.defaults.imageMaxDimensionPx`
在呼叫供應商前，逐字稿／工具圖片區塊中圖片最長邊的最大像素尺寸。
提供者呼叫前，逐字稿/工具影像區塊中最長影像邊的像素上限。
預設值：`1200`。
較低的值通常可降低大量截圖執行時的視覺權杖用量與請求承載大小。
較高的值可保留更多視覺細節。
較低的值通常會降低大量截圖執行的視覺權杖用量和請求酬載大小。
較高的值會保留更多視覺細節。
```json5
{
@ -284,7 +290,7 @@ Skills 提示詞預算的每代理程式覆寫。
### `agents.defaults.userTimezone`
系統提示詞脈絡的時區（不是訊息時間戳記）。會退回使用主機時區。
系統提示上下文的時區（不是訊息時間戳記）。會回退到主機時區。
```json5
{
@ -294,7 +300,7 @@ Skills 提示詞預算的每代理程式覆寫。
### `agents.defaults.timeFormat`
系統提示詞中的時間格式。預設值：`auto`（作業系統偏好）。
系統提示中的時間格式。預設值：`auto`（作業系統偏好設定）。
```json5
{
@ -340,6 +346,7 @@ Skills 提示詞預算的每代理程式覆寫。
pdfMaxPages: 20,
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
timeoutSeconds: 600,
@ -352,58 +359,59 @@ Skills 提示詞預算的每代理程式覆寫。
```
- `model`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 字串形式只會設定主要模型。
- 物件形式會設定主要模型加上有序容錯移轉模型。
- 字串形式只設定主要模型。
- 物件形式會設定主要模型加上有序的容錯移轉模型。
- `imageModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由 `image` 工具路徑作為其視覺模型設定使用。
- 也會在所選/預設模型無法接受影像輸入時，作為備援路由使用。
- 建議使用明確的 `provider/model` 參照。為了相容性，裸 ID 仍會被接受；如果裸 ID 唯一符合 `models.providers.*.models` 中已設定且具備影像能力的項目，OpenClaw 會將其限定到該供應商。已設定的符合項目若有歧義，則需要明確的供應商前綴。
- 由 `image` 工具路徑用作其視覺模型設定。
- 當選取的／預設模型無法接受影像輸入時，也用作備援路由。
- 建議使用明確的 `provider/model` 參照。為了相容性也接受裸 ID；如果裸 ID 唯一符合 `models.providers.*.models` 中已設定且支援影像的項目，OpenClaw 會將其限定到該供應商。已設定的符合項目若不明確，則需要明確的供應商前綴。
- `imageGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由共用影像生成能力，以及任何未來會生成影像的工具/Plugin 介面使用。
- 常見值：原生 Gemini 影像生成使用 `google/gemini-3.1-flash-image-preview`，fal 使用 `fal/fal-ai/flux/dev`，OpenAI Images 使用 `openai/gpt-image-2`，或透明背景 OpenAI PNG/WebP 輸出使用 `openai/gpt-image-1.5`。
- 如果你直接選取供應商/模型，也要設定相符的供應商驗證（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的影像生成供應商。
- 由共用的影像產生能力，以及任何未來會產生影像的工具／Plugin 表面使用。
- 常見值：原生 Gemini 影像產生使用 `google/gemini-3.1-flash-image-preview`，fal 使用 `fal/fal-ai/flux/dev`，OpenAI Images 使用 `openai/gpt-image-2`，或透明背景 OpenAI PNG/WebP 輸出使用 `openai/gpt-image-1.5`。
- 如果你直接選取供應商／模型，也要設定相符的供應商驗證（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的影像產生供應商。
- `musicGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由共用音樂生成能力和內建 `music_generate` 工具使用。
- 常見值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
- 如果省略，`music_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的音樂生成供應商。
- 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。
- 由共用的音樂產生能力與內建的 `music_generate` 工具使用。
- 常見值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview`，或 `minimax/music-2.6`。
- 如果省略，`music_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的音樂產生供應商。
- 如果你直接選取供應商／模型，也要設定相符的供應商驗證／API 金鑰。
- `videoGenerationModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由共用影片生成能力和內建 `video_generate` 工具使用。
- 常見值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
- 如果省略，`video_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，然後依供應商 ID 順序嘗試其餘已註冊的影片生成供應商。
- 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。
- 內建 Qwen 影片生成供應商最多支援 1 個輸出影片、1 張輸入影像、4 個輸入影片、10 秒長度，以及供應商層級的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 選項。
- 由共用的影片產生能力與內建的 `video_generate` 工具使用。
- 常見值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash`，或 `qwen/wan2.7-r2v`。
- 如果省略，`video_generate` 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著依供應商 ID 順序嘗試其餘已註冊的影片產生供應商。
- 如果你直接選取供應商／模型，也要設定相符的供應商驗證／API 金鑰。
- 隨附的 Qwen 影片產生供應商支援最多 1 個輸出影片、1 張輸入影像、4 個輸入影片、10 秒時長，以及供應商層級的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 選項。
- `pdfModel`：接受字串（`"provider/model"`）或物件（`{ primary, fallbacks }`）。
- 由 `pdf` 工具用於模型路由。
- 如果省略，PDF 工具會退回使用 `imageModel`，再退回使用已解析的工作階段/預設模型。
- `pdfMaxBytesMb`：當呼叫時未傳入 `maxBytesMb` 時，`pdf` 工具的預設 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中擷取備援模式會考量的預設最大頁數。
- 如果省略，PDF 工具會備援到 `imageModel`，再備援到解析後的工作階段／預設模型。
- `pdfMaxBytesMb`：在呼叫時未傳入 `maxBytesMb` 時，`pdf` 工具的預設 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中擷取備援模式會考慮的預設頁數上限。
- `verboseDefault`：代理程式的預設詳細程度。值：`"off"`、`"on"`、`"full"`。預設：`"off"`。
- `reasoningDefault`：代理程式的預設推理可見性。值：`"off"`、`"on"`、`"stream"`。每個代理程式的 `agents.list[].reasoningDefault` 會覆寫此預設值。已設定的推理預設值只會在沒有設定每則訊息或工作階段推理覆寫時，套用於擁有者、已授權寄件者，或 operator-admin gateway 情境。
- `toolProgressDetail`：`/verbose` 工具摘要與進度草稿工具列的詳細模式。值：`"explain"`（預設，精簡的人類可讀標籤）或 `"raw"`（可用時附加原始命令／詳細資訊）。每個代理程式的 `agents.list[].toolProgressDetail` 會覆寫此預設值。
- `reasoningDefault`：代理程式的預設推理可見性。值：`"off"`、`"on"`、`"stream"`。每個代理程式的 `agents.list[].reasoningDefault` 會覆寫此預設值。已設定的推理預設值只會在沒有設定每則訊息或工作階段推理覆寫時，套用於擁有者、授權傳送者，或操作者管理員 Gateway 情境。
- `elevatedDefault`：代理程式的預設提升輸出層級。值：`"off"`、`"on"`、`"ask"`、`"full"`。預設：`"on"`。
- `model.primary`：格式為 `provider/model`（例如 API 金鑰存取使用 `openai/gpt-5.5`，或 Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略供應商，OpenClaw 會先嘗試別名，再嘗試該確切模型 ID 的唯一已設定供應商符合項目，最後才退回已設定的預設供應商（已棄用的相容性行為，因此建議使用明確的 `provider/model`）。如果該供應商不再公開已設定的預設模型，OpenClaw 會退回使用第一個已設定的供應商/模型，而不是顯示過時且已移除供應商的預設值。
- `models`：已設定的模型目錄，以及 `/model` 的允許清單。每個項目可包含 `alias`（捷徑）和 `params`（供應商專屬，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
- 安全編輯：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 新增項目。除非你傳入 `--replace`，否則 `config set` 會拒絕移除既有允許清單項目的替換。
- 供應商範圍的設定/入門流程會將所選供應商模型合併到此對應表，並保留已設定的其他無關供應商。
- 對於直接的 OpenAI Responses 模型，會自動啟用伺服器端 Compaction。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆寫閾值。請參閱 [OpenAI 伺服器端 Compaction](/zh-TW/providers/openai#server-side-compaction-responses-api)。
- `params`：套用到所有模型的全域預設供應商參數。設定於 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合併優先順序（設定）：`agents.defaults.params`（全域基底）會被 `agents.defaults.models["provider/model"].params`（每模型）覆寫，然後 `agents.list[].params`（相符代理程式 ID）會依鍵覆寫。詳情請參閱 [Prompt Caching](/zh-TW/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：進階透傳 JSON，會合併到 OpenAI 相容代理的 `api: "openai-completions"` 請求主體。如果它與生成的請求鍵衝突，額外主體會勝出；非原生 completions 路由之後仍會移除僅限 OpenAI 的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 相容的聊天範本參數，會合併到頂層 `api: "openai-completions"` 請求主體。對於關閉 thinking 的 `vllm/nemotron-3-*`，內建 vLLM Plugin 會自動傳送 `enable_thinking: false` 和 `force_nonempty_content: true`；明確的 `chat_template_kwargs` 會覆寫生成的預設值，而 `extra_body.chat_template_kwargs` 仍具有最終優先權。對於 vLLM Qwen thinking 控制，請在該模型項目上將 `params.qwenThinkingFormat` 設為 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：每模型的 OpenAI 相容推理強度清單。對真正接受它的自訂端點加入 `"xhigh"`；OpenClaw 接著會在指令選單、Gateway 工作階段列、工作階段修補驗證、代理程式 CLI 驗證，以及該已設定供應商/模型的 `llm-task` 驗證中公開 `/think xhigh`。當後端需要規範層級的供應商專屬值時，請使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：僅限 Z.AI 的保留 thinking 選用功能。啟用且 thinking 開啟時，OpenClaw 會傳送 `thinking.clear_thinking: false` 並重播先前的 `reasoning_content`；請參閱 [Z.AI thinking 與保留 thinking](/zh-TW/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：預設低階代理程式執行階段政策。省略 id 時預設為 OpenClaw Pi。使用 `id: "pi"` 強制使用內建 PI harness，使用 `id: "auto"` 讓已註冊的 Plugin harness 宣告支援的模型，且在沒有符合項目時使用 PI，使用已註冊的 harness id（例如 `id: "codex"`）要求該 harness，或使用受支援的 CLI 後端別名（例如 `id: "claude-cli"`）。明確的 Plugin 執行階段會在 harness 不可用或失敗時關閉失敗。請將模型參照維持為規範的 `provider/model`；請透過執行階段設定選取 Codex、Claude CLI、Gemini CLI 和其他執行後端，而不是使用舊版執行階段供應商前綴。這與供應商/模型選取的差異，請參閱 [Agent runtimes](/zh-TW/concepts/agent-runtimes)。
- 會變更這些欄位的設定寫入器（例如 `/models set`、`/models set-image` 和備援新增/移除指令）會儲存規範物件形式，並盡可能保留既有備援清單。
- `maxConcurrent`：跨工作階段的最大平行代理程式執行數（每個工作階段仍會序列化）。預設：4。
- `model.primary`：格式為 `provider/model`（例如 API 金鑰存取使用 `openai/gpt-5.5`，Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略供應商，OpenClaw 會先嘗試別名，接著對該精確模型 ID 嘗試唯一的已設定供應商符合項，最後才備援到已設定的預設供應商（已淘汰的相容性行為，因此建議使用明確的 `provider/model`）。如果該供應商不再公開已設定的預設模型，OpenClaw 會備援到第一個已設定的供應商／模型，而不是顯示過時且已移除的供應商預設值。
- `models`：為 `/model` 設定的模型目錄與允許清單。每個項目可包含 `alias`（捷徑）和 `params`（供應商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
- 安全編輯：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 新增項目。除非你傳入 `--replace`，否則 `config set` 會拒絕移除現有允許清單項目的替換。
- 供應商範圍的設定／上線流程會將所選供應商模型合併到此對應表，並保留已設定的無關供應商。
- 對於直接的 OpenAI Responses 模型，伺服器端 Compaction 會自動啟用。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆寫閾值。請參閱 [OpenAI 伺服器端 Compaction](/zh-TW/providers/openai#server-side-compaction-responses-api)。
- `params`：套用至所有模型的全域預設供應商參數。設定於 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合併優先順序（設定）：`agents.defaults.params`（全域基底）會由 `agents.defaults.models["provider/model"].params`（每個模型）覆寫，接著 `agents.list[].params`（符合的代理程式 ID）會依鍵覆寫。詳情請參閱 [提示快取](/zh-TW/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：進階傳遞 JSON，會合併到 OpenAI 相容代理的 `api: "openai-completions"` 請求主體中。如果它與產生的請求鍵衝突，額外主體會優先；非原生 completions 路由之後仍會移除僅 OpenAI 使用的 `store`。
- `params.chat_template_kwargs`：vLLM/OpenAI 相容的聊天範本引數，會合併到頂層 `api: "openai-completions"` 請求主體。對於關閉思考的 `vllm/nemotron-3-*`，隨附的 vLLM Plugin 會自動傳送 `enable_thinking: false` 和 `force_nonempty_content: true`；明確的 `chat_template_kwargs` 會覆寫產生的預設值，而 `extra_body.chat_template_kwargs` 仍具有最終優先權。對於 vLLM Qwen 思考控制，請在該模型項目將 `params.qwenThinkingFormat` 設為 `"chat-template"` 或 `"top-level"`。
- `compat.supportedReasoningEfforts`：每個模型的 OpenAI 相容推理努力程度清單。對於真正接受 `"xhigh"` 的自訂端點，請包含 `"xhigh"`；OpenClaw 接著會在命令選單、Gateway 工作階段列、工作階段修補驗證、代理程式 CLI 驗證，以及該已設定供應商／模型的 `llm-task` 驗證中公開 `/think xhigh`。當後端需要某個標準層級的供應商特定值時，請使用 `compat.reasoningEffortMap`。
- `params.preserveThinking`：僅 Z.AI 適用的保留思考選擇加入。啟用且思考開啟時，OpenClaw 會傳送 `thinking.clear_thinking: false` 並重播先前的 `reasoning_content`；請參閱 [Z.AI 思考與保留思考](/zh-TW/providers/zai#thinking-and-preserved-thinking)。
- `agentRuntime`：預設低階代理程式執行階段政策。省略的 ID 預設為 OpenClaw Pi。使用 `id: "pi"` 強制使用內建 PI harness，使用 `id: "auto"` 讓已註冊的 Plugin harness 認領支援的模型，且在沒有符合項時使用 PI，使用已註冊的 harness ID（例如 `id: "codex"`）要求該 harness，或使用支援的 CLI 後端別名（例如 `id: "claude-cli"`）。明確的 Plugin 執行階段會在 harness 不可用或失敗時封閉失敗。模型參照請保持 `provider/model` 的標準形式；透過執行階段設定選取 Codex、Claude CLI、Gemini CLI 和其他執行後端，而不是使用舊版執行階段供應商前綴。關於這與供應商／模型選擇有何不同，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。
- 會改動這些欄位的設定寫入器（例如 `/models set`、`/models set-image`，以及備援新增／移除命令）會儲存標準物件形式，並在可能時保留既有備援清單。
- `maxConcurrent`：跨工作階段的最大並行代理程式執行數（每個工作階段仍會序列化）。預設：4。
### `agents.defaults.agentRuntime`
`agentRuntime` 控制哪個低階執行器執行代理程式回合。大多數
部署應保留預設的 OpenClaw Pi 執行階段。當受信任的
Plugin 提供原生 harness（例如內建 Codex app-server harness），
或你想使用受支援的 CLI 後端（例如 Claude CLI）時使用它。關於心智
模型，請參閱 [Agent runtimes](/zh-TW/concepts/agent-runtimes)。
`agentRuntime` 控制哪個低階執行器會執行代理程式回合。多數
部署應維持預設的 OpenClaw Pi 執行階段。當受信任的
Plugin 提供原生 harness（例如隨附的 Codex app-server harness），
或當你想使用支援的 CLI 後端（例如 Claude CLI）時使用它。關於心智
模型，請參閱 [代理程式執行階段](/zh-TW/concepts/agent-runtimes)。
```json5
{
@ -418,16 +426,16 @@ Plugin 提供原生 harness（例如內建 Codex app-server harness），
}
```
- `id`：`"auto"`、`"pi"`、已註冊的 Plugin harness id，或受支援的 CLI 後端別名。內建 Codex Plugin 會註冊 `codex`；內建 Anthropic Plugin 提供 `claude-cli` CLI 後端。
- `id: "auto"` 讓已註冊的 Plugin harness 宣告支援的回合，並在沒有符合 harness 時使用 PI。明確的 Plugin 執行階段（例如 `id: "codex"`）要求該 harness，且在它不可用或失敗時關閉失敗。
- `id`：`"auto"`、`"pi"`、已註冊的 Plugin harness ID，或支援的 CLI 後端別名。隨附的 Codex Plugin 會註冊 `codex`；隨附的 Anthropic Plugin 提供 `claude-cli` CLI 後端。
- `id: "auto"` 讓已註冊的 Plugin harness 認領支援的回合，且在沒有 harness 符合時使用 PI。明確的 Plugin 執行階段（例如 `id: "codex"`）要求該 harness，並在其不可用或失敗時封閉失敗。
- 環境覆寫：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 會覆寫該程序的 `id`。
- 對於僅使用 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。
- 對於 Claude CLI 部署，建議使用 `model: "anthropic/claude-opus-4-7"` 加上 `agentRuntime.id: "claude-cli"`。舊版 `claude-cli/claude-opus-4-7` 模型參照仍可為了相容性運作，但新設定應維持供應商/模型選取的規範形式，並將執行後端放在 `agentRuntime.id`。
- 對於僅 Codex 的部署，請設定 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。
- 對於 Claude CLI 部署，建議使用 `model: "anthropic/claude-opus-4-7"` 加上 `agentRuntime.id: "claude-cli"`。舊版 `claude-cli/claude-opus-4-7` 模型參照仍可為了相容性運作，但新設定應保持標準的供應商／模型選擇，並將執行後端放在 `agentRuntime.id`。
- 較舊的執行階段政策鍵會由 `openclaw doctor --fix` 重寫為 `agentRuntime`。
- Harness 選擇會在第一次嵌入式執行後，依工作階段 ID 固定。設定/env 變更會影響新的或已重設的工作階段，而不是既有 transcript。具有 transcript 歷史但沒有記錄固定值的舊版工作階段會被視為已固定為 PI。`/status` 會回報有效執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 這只控制文字代理程式回合執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍會使用其供應商/模型設定。
- Harness 選擇會在第一次嵌入式執行後，依工作階段 ID 固定。設定／環境變更會影響新的或重設的工作階段，不會影響既有 transcript。具有 transcript 歷史但沒有已記錄固定值的舊版工作階段會視為已固定到 PI。`/status` 會回報有效的執行階段，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 這只控制文字代理程式回合的執行。媒體產生、視覺、PDF、音樂、影片和 TTS 仍使用其供應商／模型設定。
**內建別名簡寫**（只在模型位於 `agents.defaults.models` 中時套用）：
**內建別名簡寫**（只有在模型位於 `agents.defaults.models` 時才適用）：
| 別名 | 模型 |
| ------------------- | ------------------------------------------ |
@ -442,13 +450,13 @@ Plugin 提供原生 harness（例如內建 Codex app-server harness），
你設定的別名一律優先於預設值。
Z.AI GLM-4.x 模型會自動啟用 thinking mode，除非你設定 `--thinking off`，或自行定義 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型預設會啟用 `tool_stream` 以進行 tool call streaming。將 `agents.defaults.models["zai/<model>"].params.tool_stream` 設為 `false` 即可停用。
Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用 `adaptive` thinking。
Z.AI GLM-4.x 模型會自動啟用思考模式，除非你設定 `--thinking off`，或自行定義 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型預設會啟用 `tool_stream` 以進行工具呼叫串流。將 `agents.defaults.models["zai/<model>"].params.tool_stream` 設為 `false` 即可停用。
Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 `adaptive` 思考。
### `agents.defaults.cliBackends`
用於純文字 fallback 執行的選用 CLI 後端（無工具呼叫）。當 API 提供者失敗時，可作為備援。
用於純文字後備執行的選用 CLI 後端（無工具呼叫）。在 API 提供者失敗時，可作為備援使用。
```json5
{
@ -479,11 +487,11 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
- CLI 後端以文字為優先；工具一律停用。
- 設定 `sessionArg` 時支援工作階段。
- 當 `imageArg` 接受檔案路徑時，支援影像透傳。
- 當 `imageArg` 接受檔案路徑時，支援影像傳遞。
### `agents.defaults.systemPromptOverride`
以固定字串取代 OpenClaw 組裝的整個系統提示。可在預設層級（`agents.defaults.systemPromptOverride`）或每個代理（`agents.list[].systemPromptOverride`）設定。每個代理的值優先；空值或僅包含空白字元的值會被忽略。適合受控提示實驗。
用固定字串取代整個由 OpenClaw 組裝的系統提示詞。可在預設層級（`agents.defaults.systemPromptOverride`）或個別代理（`agents.list[].systemPromptOverride`）設定。個別代理的值優先；空值或僅含空白的值會被忽略。適合用於受控的提示詞實驗。
```json5
{
@ -497,7 +505,7 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
### `agents.defaults.promptOverlays`
依模型家族套用、與提供者無關的提示覆疊。GPT-5 家族模型 ID 會跨提供者接收共享行為合約；`personality` 只控制友善互動風格層。
依模型家族套用、與提供者無關的提示詞覆蓋層。GPT-5 家族模型 ID 會在各提供者間接收共用的行為契約；`personality` 只控制友善互動風格層。
```json5
{
@ -514,8 +522,8 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
```
- `"friendly"`（預設）和 `"on"` 會啟用友善互動風格層。
- `"off"` 只會停用友善層；已標記的 GPT-5 行為合約仍會啟用。
- 未設定此共享設定時，仍會讀取舊版 `plugins.entries.openai.config.personality`。
- `"off"` 只會停用友善層；已標記的 GPT-5 行為契約仍會保持啟用。
- 未設定這個共用設定時，仍會讀取舊版 `plugins.entries.openai.config.personality`。
### `agents.defaults.heartbeat`
@ -547,15 +555,15 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
}
```
- `every`：持續時間字串（ms/s/m/h）。預設：`30m`（API 金鑰驗證）或 `1h`（OAuth 驗證）。設為 `0m` 可停用。
- `includeSystemPromptSection`：為 false 時，會從系統提示省略 Heartbeat 區段，並略過將 `HEARTBEAT.md` 注入啟動環境脈絡。預設：`true`。
- `suppressToolErrorWarnings`：為 true 時，會在 Heartbeat 執行期間抑制工具錯誤警告 payload。
- `every`：期間字串（ms/s/m/h）。預設：`30m`（API 金鑰驗證）或 `1h`（OAuth 驗證）。設為 `0m` 即可停用。
- `includeSystemPromptSection`：為 false 時，會從系統提示詞省略 Heartbeat 區段，並略過將 `HEARTBEAT.md` 注入啟動內容。預設：`true`。
- `suppressToolErrorWarnings`：為 true 時，會在 Heartbeat 執行期間抑制工具錯誤警告酬載。
- `timeoutSeconds`：Heartbeat 代理回合在中止前允許的最長秒數。未設定時會使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直接/DM 傳送政策。`allow`（預設）允許傳送至直接目標。`block` 會抑制傳送至直接目標，並發出 `reason=dm-blocked`。
- `lightContext`：為 true 時，Heartbeat 執行會使用輕量啟動環境脈絡，且只保留工作區啟動環境檔案中的 `HEARTBEAT.md`。
- `isolatedSession`：為 true 時，每次 Heartbeat 都會在沒有先前對話歷史的新工作階段中執行。模式與 cron `sessionTarget: "isolated"` 相同。可將每次 Heartbeat 的 token 成本從約 100K 降至約 2-5K token。
- `skipWhenBusy`：為 true 時，Heartbeat 執行會在額外忙碌的 lane 上延後：子代理或巢狀命令工作。Cron lane 一律會延後 Heartbeat，即使沒有此旗標也一樣。
- 每個代理：設定 `agents.list[].heartbeat`。當任一代理定義 `heartbeat` 時，**只有那些代理**會執行 Heartbeat。
- `directPolicy`：直接/DM 傳遞政策。`allow`（預設）允許傳遞至直接目標。`block` 會抑制直接目標傳遞，並發出 `reason=dm-blocked`。
- `lightContext`：為 true 時，Heartbeat 執行會使用輕量啟動內容，並且只保留工作區啟動檔案中的 `HEARTBEAT.md`。
- `isolatedSession`：為 true 時，每次 Heartbeat 都會在全新工作階段中執行，沒有先前對話歷史。與 Cron `sessionTarget: "isolated"` 相同的隔離模式。將每次 Heartbeat 的 token 成本從約 100K 降至約 2-5K token。
- `skipWhenBusy`：為 true 時，Heartbeat 執行會因額外忙碌通道而延後：子代理或巢狀命令工作。即使沒有此旗標，Cron 通道也一律會延後 Heartbeat。
- 個別代理：設定 `agents.list[].heartbeat`。當任何代理定義了 `heartbeat`，**只有那些代理**會執行 Heartbeat。
- Heartbeat 會執行完整代理回合，較短的間隔會消耗更多 token。
### `agents.defaults.compaction`
@ -593,22 +601,22 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
```
- `mode`：`default` 或 `safeguard`（針對長歷史的分塊摘要）。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `provider`：已註冊 Compaction provider Plugin 的 ID。設定後，會呼叫該 provider 的 `summarize()`，而不是內建 LLM 摘要。失敗時會 fallback 至內建摘要。設定 provider 會強制 `mode: "safeguard"`。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `provider`：已註冊 Compaction 提供者 Plugin 的 ID。設定後，會呼叫提供者的 `summarize()`，而不是內建 LLM 摘要。失敗時會退回內建摘要。設定提供者會強制 `mode: "safeguard"`。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `timeoutSeconds`：單次 Compaction 作業在 OpenClaw 中止前允許的最長秒數。預設：`900`。
- `keepRecentTokens`：Pi 切點預算，用於逐字保留最新的逐字稿尾端。手動 `/compact` 只有在明確設定時才會遵守此值；否則手動 Compaction 會是一個硬 checkpoint。
- `identifierPolicy`：`strict`（預設）、`off` 或 `custom`。`strict` 會在 Compaction 摘要期間前置內建的不透明識別碼保留指引。
- `keepRecentTokens`：Pi 切點預算，用於逐字保留最近的逐字稿尾端。手動 `/compact` 在明確設定時會遵循此值；否則手動 Compaction 會是硬檢查點。
- `identifierPolicy`：`strict`（預設）、`off` 或 `custom`。`strict` 會在 Compaction 摘要期間加上內建的不透明識別碼保留指引前綴。
- `identifierInstructions`：當 `identifierPolicy=custom` 時使用的選用自訂識別碼保留文字。
- `qualityGuard`：針對 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設為 `enabled: false` 可略過稽核。
- `midTurnPrecheck`：選用的 Pi tool-loop 壓力檢查。當 `enabled: true` 時，OpenClaw 會在工具結果附加後、下一次模型呼叫前檢查脈絡壓力。如果脈絡已無法容納，它會在提交提示前中止目前嘗試，並重用既有的預檢復原路徑來截斷工具結果，或進行 Compaction 後重試。可搭配 `default` 和 `safeguard` Compaction 模式使用。預設：停用。
- `postCompactionSections`：選用的 AGENTS.md H2/H3 區段名稱，用於在 Compaction 後重新注入。預設為 `["Session Startup", "Red Lines"]`；設為 `[]` 可停用重新注入。未設定或明確設為該預設配對時，也會接受較舊的 `Every Session`/`Safety` 標題作為舊版 fallback。
- `model`：僅用於 Compaction 摘要的選用 `provider/model-id` 覆寫。當主要工作階段應保留一個模型，但 Compaction 摘要應在另一個模型上執行時使用；未設定時，Compaction 會使用工作階段的主要模型。
- `maxActiveTranscriptBytes`：選用的位元組門檻（`number` 或類似 `"20mb"` 的字串），當作用中 JSONL 超過門檻時，會在執行前觸發一般本機 Compaction。需要 `truncateAfterCompaction`，成功的 Compaction 才能輪替至較小的後續逐字稿。未設定或為 `0` 時停用。
- `notifyUser`：為 `true` 時，會在 Compaction 開始和完成時傳送簡短通知給使用者（例如「正在壓縮脈絡...」和「Compaction 完成」）。預設停用，以維持 Compaction 靜默。
- `memoryFlush`：自動 Compaction 前的靜默代理回合，用於儲存持久記憶。當這個 housekeeping 回合應留在本機模型上時，將 `model` 設為精確的 provider/model，例如 `ollama/qwen3:8b`；此覆寫不會繼承作用中工作階段的 fallback 鏈。工作區為唯讀時會略過。
- `qualityGuard`：針對 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設定 `enabled: false` 可略過稽核。
- `midTurnPrecheck`：選用的 Pi 工具迴圈壓力檢查。當 `enabled: true` 時，OpenClaw 會在附加工具結果後、下一次模型呼叫前檢查內容壓力。若內容已無法容納，它會在提交提示詞前中止目前嘗試，並重用既有的預檢復原路徑來截斷工具結果，或執行 Compaction 後重試。可與 `default` 和 `safeguard` 兩種 Compaction 模式搭配使用。預設：停用。
- `postCompactionSections`：Compaction 後要重新注入的選用 AGENTS.md H2/H3 區段名稱。預設為 `["Session Startup", "Red Lines"]`；設為 `[]` 可停用重新注入。未設定或明確設為該預設組合時，也會接受舊版 `Every Session`/`Safety` 標題作為相容後備。
- `model`：僅用於 Compaction 摘要的選用 `provider/model-id` 覆蓋。當主要工作階段應保留一個模型，但 Compaction 摘要應在另一個模型上執行時使用；未設定時，Compaction 會使用工作階段的主要模型。
- `maxActiveTranscriptBytes`：選用位元組閾值（`number` 或像 `"20mb"` 的字串），當作用中 JSONL 超過閾值時，會在執行前觸發一般本機 Compaction。需要 `truncateAfterCompaction`，讓成功的 Compaction 能輪替到較小的後續逐字稿。未設定或為 `0` 時停用。
- `notifyUser`：為 `true` 時，會在 Compaction 開始與完成時向使用者傳送簡短通知（例如「正在壓縮內容...」和「Compaction 完成」）。預設停用，以保持 Compaction 靜默。
- `memoryFlush`：自動 Compaction 前的靜默代理式回合，用於儲存持久記憶。當此維護回合應保留在本機模型上時，將 `model` 設為精確的提供者/模型，例如 `ollama/qwen3:8b`；此覆蓋不會繼承作用中工作階段的後備鏈。工作區為唯讀時會略過。
### `agents.defaults.contextPruning`
在傳送給 LLM 前，從記憶體脈絡中修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。
在傳送給 LLM 前，從記憶體內容修剪**舊工具結果**。**不會**修改磁碟上的工作階段歷史。
```json5
{
@ -630,25 +638,25 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
}
```
<Accordion title="cache-ttl mode behavior">
<Accordion title="cache-ttl 模式行為">
- `mode: "cache-ttl"` 會啟用修剪 pass。
- `ttl` 控制修剪多久後可以再次執行（自上次 cache touch 後）。
- 修剪會先 soft-trim 過大的工具結果，接著在需要時 hard-clear 較舊的工具結果。
- `mode: "cache-ttl"` 會啟用修剪階段。
- `ttl` 控制修剪多久後才能再次執行（從上次快取觸碰後開始算）。
- 修剪會先軟修剪過大的工具結果，接著在需要時硬清除較舊的工具結果。
**Soft-trim** 會保留開頭 + 結尾，並在中間插入 `...`。
**軟修剪**會保留開頭 + 結尾，並在中間插入 `...`。
**Hard-clear** 會以 placeholder 取代整個工具結果。
**硬清除**會用佔位符取代整個工具結果。
注意事項：
- 影像區塊絕不會被修剪/清除。
- 比率以字元為基準（近似值），不是精確的 token 計數。
- 如果助理訊息少於 `keepLastAssistants`，會略過修剪。
- 影像區塊永遠不會被修剪/清除。
- 比率以字元為基準（近似值），不是精確的 token 數。
- 如果助理訊息少於 `keepLastAssistants` 則會略過修剪。
</Accordion>
行為細節請參閱 [工作階段修剪](/zh-TW/concepts/session-pruning)。
請參閱 [工作階段修剪](/zh-TW/concepts/session-pruning) 了解行為細節。
### 區塊串流
@ -667,10 +675,10 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
```
- 非 Telegram 頻道需要明確設定 `*.blockStreaming: true` 才能啟用區塊回覆。
- 頻道覆寫：`channels.<channel>.blockStreamingCoalesce`（以及每個帳號的變體）。Signal/Slack/Discord/Google Chat 預設為 `minChars: 1500`。
- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800-2500ms。每個代理覆寫：`agents.list[].humanDelay`。
- 頻道覆蓋：`channels.<channel>.blockStreamingCoalesce`（以及個別帳號變體）。Signal/Slack/Discord/Google Chat 預設為 `minChars: 1500`。
- `humanDelay`：區塊回覆之間的隨機暫停。`natural` = 800–2500ms。個別代理覆蓋：`agents.list[].humanDelay`。
行為與分塊細節請參閱 [串流](/zh-TW/concepts/streaming)。
請參閱 [串流](/zh-TW/concepts/streaming) 了解行為 + 分塊細節。
### 輸入指示器
@ -686,15 +694,15 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
```
- 預設值：直接聊天/提及使用 `instant`，未提及的群組聊天使用 `message`。
- 每個工作階段覆寫：`session.typingMode`、`session.typingIntervalSeconds`。
- 每工作階段覆寫：`session.typingMode`、`session.typingIntervalSeconds`。
請參閱[輸入指示器](/zh-TW/concepts/typing-indicators)。
請參閱 [輸入指示器](/zh-TW/concepts/typing-indicators)。
<a id="agentsdefaultssandbox"></a>
### `agents.defaults.sandbox`
嵌入式代理的選用沙箱化設定。完整指南請參閱[沙箱化](/zh-TW/gateway/sandboxing)。
嵌入式代理的選用沙箱化。完整指南請參閱 [沙箱化](/zh-TW/gateway/sandboxing)。
```json5
{
@ -802,39 +810,39 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
**SSH 後端設定：**
- `target`：`user@host[:port]` 格式的 SSH 目標
- `target`：`user@host[:port]` 形式的 SSH 目標
- `command`：SSH 用戶端命令（預設：`ssh`）
- `workspaceRoot`：用於各範圍工作區的遠端絕對根目錄
- `workspaceRoot`：用於各範圍工作區的絕對遠端根目錄
- `identityFile` / `certificateFile` / `knownHostsFile`：傳遞給 OpenSSH 的現有本機檔案
- `identityData` / `certificateData` / `knownHostsData`：內嵌內容或 SecretRefs，OpenClaw 會在執行階段將其實體化為暫存檔
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主機金鑰原則旋鈕
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在執行階段具體化為暫存檔案的內嵌內容或 SecretRef
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主機金鑰政策控制項
**SSH 驗證優先順序：**
- `identityData` 優先於 `identityFile`
- `certificateData` 優先於 `certificateFile`
- `knownHostsData` 優先於 `knownHostsFile`
- 由 SecretRef 支援的 `*Data` 值會在沙箱工作階段啟動前，從作用中的祕密執行階段快照解析
- 由 SecretRef 支援的 `*Data` 值會在沙箱工作階段開始前，從作用中的密鑰執行階段快照解析
**SSH 後端行為：**
- 建立或重新建立後，會將遠端工作區植入一次
- 接著保持遠端 SSH 工作區為權威來源
- 透過 SSH 路由 `exec`、檔案工具與媒體路徑
- 建立或重新建立後，會為遠端工作區植入一次
- 然後保持遠端 SSH 工作區為標準來源
- 透過 SSH 路由 `exec`、檔案工具和媒體路徑
- 不會自動將遠端變更同步回主機
- 不支援沙箱瀏覽器容器
**工作區存取：**
- `none`：位於 `~/.openclaw/sandboxes` 底下的各範圍沙箱工作區
- `none`：位於 `~/.openclaw/sandboxes` 下的各範圍沙箱工作區
- `ro`：沙箱工作區位於 `/workspace`，代理工作區以唯讀方式掛載於 `/agent`
- `rw`：代理工作區以讀寫方式掛載於 `/workspace`
**範圍：**
- `session`：每個工作階段一個容器與工作區
- `agent`：每個代理一個容器與工作區（預設）
- `shared`：共用容器與工作區（沒有跨工作階段隔離）
- `session`：每個工作階段各自的容器 + 工作區
- `agent`：每個代理一個容器 + 工作區（預設）
- `shared`：共用容器和工作區（無跨工作階段隔離）
**OpenShell Plugin 設定：**
@ -864,29 +872,29 @@ Anthropic Claude 4.6 模型在未設定明確 thinking level 時，預設使用
**OpenShell 模式：**
- `mirror`：執行前從本機植入遠端，執行後同步回來；本機工作區保持為權威來源
- `remote`：建立沙箱時將遠端植入一次，接著保持遠端工作區為權威來源
- `mirror`：執行前從本機植入遠端，執行後同步回來；本機工作區維持為標準來源
- `remote`：建立沙箱時植入遠端一次，之後保持遠端工作區為標準來源
在 `remote` 模式中，於 OpenClaw 外部所做的主機本機編輯，在植入步驟後不會自動同步進沙箱。
傳輸是透過 SSH 進入 OpenShell 沙箱，但 Plugin 擁有沙箱生命週期與選用的鏡像同步。
在 `remote` 模式中，於 OpenClaw 外部進行的主機本機編輯，在植入步驟後不會自動同步至沙箱。
傳輸是透過 SSH 進入 OpenShell 沙箱，但 Plugin 負責沙箱生命週期和選用的鏡像同步。
**`setupCommand`** 會在容器建立後執行一次（透過 `sh -lc`）。需要網路輸出、可寫入的根目錄、root 使用者。
**`setupCommand`** 會在容器建立後執行一次（透過 `sh -lc`）。需要網路出口、可寫入根目錄、root 使用者。
**容器預設為 `network: "none"`** —— 如果代理需要對外存取，請設為 `"bridge"`（或自訂橋接網路）。
`"host"` 會被封鎖。`"container:<id>"` 預設會被封鎖，除非你明確設定
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急例外）。
**容器預設為 `network: "none"`** — 若代理需要對外存取，請設為 `"bridge"`（或自訂橋接網路）。
`"host"` 會被封鎖。除非你明確設定
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（緊急例外），否則預設會封鎖 `"container:<id>"`。
**傳入附件** 會暫存到作用中工作區的 `media/inbound/*`。
**傳入附件** 會暫存至作用中工作區的 `media/inbound/*`。
**`docker.binds`** 會掛載額外的主機目錄；全域與每個代理的繫結會合併。
**`docker.binds`** 會掛載額外的主機目錄；全域和各代理繫結會合併。
**沙箱化瀏覽器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 會注入系統提示。不需要在 `openclaw.json` 中設定 `browser.enabled`。
noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短期有效的權杖 URL（而不是在共用 URL 中暴露密碼）。
noVNC 觀察者存取預設使用 VNC 驗證，且 OpenClaw 會發出短期有效的權杖 URL（而不是在共用 URL 中暴露密碼）。
- `allowHostControl: false`（預設）會阻止沙箱化工作階段指定主機瀏覽器。
- `allowHostControl: false`（預設）會阻止沙箱化工作階段鎖定主機瀏覽器。
- `network` 預設為 `openclaw-sandbox-browser`（專用橋接網路）。只有在你明確想要全域橋接連線時，才設為 `bridge`。
- `cdpSourceRange` 可選擇性地將容器邊緣的 CDP 輸入限制為 CIDR 範圍（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只會將額外的主機目錄掛載到沙箱瀏覽器容器中。設定後（包含 `[]`），它會取代瀏覽器容器的 `docker.binds`。
- `cdpSourceRange` 可選擇性地將容器邊界的 CDP 入口限制在 CIDR 範圍內（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 只會將額外的主機目錄掛載到沙箱瀏覽器容器中。設定時（包括 `[]`），它會取代瀏覽器容器的 `docker.binds`。
- 啟動預設值定義於 `scripts/sandbox-browser-entrypoint.sh`，並針對容器主機調校：
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
@ -906,14 +914,14 @@ noVNC 觀察者存取預設使用 VNC 驗證，OpenClaw 會發出短期有效的
- `--metrics-recording-only`
- `--disable-extensions`（預設啟用）
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
預設啟用；如果 WebGL/3D 使用情境需要，可透過
預設啟用；若 WebGL/3D 使用情境需要，可透過
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 停用。
- 如果你的工作流程依賴擴充功能，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 會重新啟用擴充功能。
- 若你的工作流程依賴擴充功能，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 會重新啟用擴充功能。
- `--renderer-process-limit=2` 可透過
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 變更；設為 `0` 以使用 Chromium 的
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 變更；設為 `0` 可使用 Chromium 的
預設程序限制。
- 啟用 `noSandbox` 時，另加 `--no-sandbox`。
- 預設值是容器映像基準；若要變更容器預設值，請使用具自訂
- 預設值是容器映像基準；若要變更容器預設值，請使用具有自訂
進入點的自訂瀏覽器映像。
</Accordion>
@ -927,16 +935,16 @@ scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
若 npm 安裝沒有原始碼 checkout，請參閱[沙箱化 § 映像與設定](/zh-TW/gateway/sandboxing#images-and-setup)，取得內嵌的 `docker build` 命令。
若是沒有原始碼 checkout 的 npm 安裝，內嵌 `docker build` 命令請參閱 [沙箱化 § 映像與設定](/zh-TW/gateway/sandboxing#images-and-setup)。
### `agents.list`（每個代理覆寫）
### `agents.list`（各代理覆寫）
使用 `agents.list[].tts` 為代理指定自己的 TTS 供應商、語音、模型、
風格或自動 TTS 模式。代理區塊會深度合併到全域
`messages.tts` 之上，因此共用憑證可以保留在同一處，而個別
代理只覆寫其需要的語音或供應商欄位。作用中代理的
使用 `agents.list[].tts` 可為代理指定自己的 TTS 提供者、語音、模型、
樣式或自動 TTS 模式。代理區塊會深度合併到全域
`messages.tts` 之上，因此共用憑證可以保留在同一處，而各個
代理只覆寫它們需要的語音或提供者欄位。作用中代理的
覆寫會套用到自動語音回覆、`/tts audio`、`/tts status` 和
`tts` 代理工具。供應商範例與優先順序請參閱[文字轉語音](/zh-TW/tools/tts#per-agent-voice-overrides)。
`tts` 代理工具。提供者範例和優先順序請參閱 [文字轉語音](/zh-TW/tools/tts#per-agent-voice-overrides)。
```json5
{
@ -990,28 +998,28 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `id`：穩定的代理程式 ID（必填）。
- `default`：設定多個時，第一個生效（會記錄警告）。如果都未設定，清單中的第一個項目就是預設值。
- `model`：字串形式會設定嚴格的每代理程式主要模型，且沒有模型後援；物件形式 `{ primary }` 也同樣嚴格，除非你加入 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 讓該代理程式選擇啟用後援，或使用 `{ primary, fallbacks: [] }` 明確指定嚴格行為。只覆寫 `primary` 的 Cron 工作仍會繼承預設後援，除非你設定 `fallbacks: []`。
- `params`：每代理程式串流參數，會合併覆寫 `agents.defaults.models` 中選取的模型項目。可用於代理程式特定覆寫，例如 `cacheRetention`、`temperature` 或 `maxTokens`，不必複製整個模型目錄。
- `tts`：選用的每代理程式文字轉語音覆寫。此區塊會深度合併覆寫 `messages.tts`，因此請將共用提供者憑證與後援政策保留在 `messages.tts`，並只在此設定角色特定值，例如提供者、語音、模型、風格或自動模式。
- `skills`：選用的每代理程式 Skills 允許清單。如果省略，代理程式會在已設定時繼承 `agents.defaults.skills`；明確清單會取代預設值而非合併，且 `[]` 表示沒有 Skills。
- `thinkingDefault`：選用的每代理程式預設思考等級（`off | minimal | low | medium | high | xhigh | adaptive | max`）。當未設定每訊息或工作階段覆寫時，會覆寫此代理程式的 `agents.defaults.thinkingDefault`。所選提供者/模型設定檔會控制哪些值有效；對於 Google Gemini，`adaptive` 會保留提供者擁有的動態思考（Gemini 3/3.1 省略 `thinkingLevel`，Gemini 2.5 使用 `thinkingBudget: -1`）。
- `reasoningDefault`：選用的每代理程式預設推理可見性（`on | off | stream`）。當未設定每訊息或工作階段推理覆寫時，會覆寫此代理程式的 `agents.defaults.reasoningDefault`。
- `fastModeDefault`：選用的每代理程式快速模式預設值（`true | false`）。當未設定每訊息或工作階段快速模式覆寫時套用。
- `agentRuntime`：選用的每代理程式低階執行階段政策覆寫。使用 `{ id: "codex" }` 可讓某個代理程式僅使用 Codex，而其他代理程式在 `auto` 模式中保留預設 PI 後援。
- `runtime`：選用的每代理程式執行階段描述元。當代理程式應預設為 ACP harness 工作階段時，搭配 `runtime.acp` 預設值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。
- `identity.avatar`：工作區相對路徑、`http(s)` URL 或 `data:` URI。
- `identity` 會推導預設值：從 `emoji` 推導 `ackReaction`，從 `name`/`emoji` 推導 `mentionPatterns`。
- `subagents.allowAgents`：明確 `sessions_spawn.agentId` 目標的代理程式 ID 允許清單（`["*"]` = 任意；預設：僅相同代理程式）。當應允許自我目標的 `agentId` 呼叫時，請包含請求者 ID。
- 沙箱繼承防護：如果請求者工作階段受沙箱限制，`sessions_spawn` 會拒絕將在非沙箱環境中執行的目標。
- `subagents.requireAgentId`：為 true 時，封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔；預設：false）。
- `id`：穩定的代理 id（必填）。
- `default`：設定多個時，第一個生效（會記錄警告）。如果未設定任何一個，清單第一項就是預設值。
- `model`：字串形式會設定嚴格的每代理主要模型，不使用模型備援；物件形式 `{ primary }` 也同樣嚴格，除非你加入 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 讓該代理選擇啟用備援，或使用 `{ primary, fallbacks: [] }` 明確指定嚴格行為。只覆寫 `primary` 的 Cron 工作仍會繼承預設備援，除非你設定 `fallbacks: []`。
- `params`：每代理串流參數，會合併覆蓋 `agents.defaults.models` 中選取的模型項目。若要為代理指定 `cacheRetention`、`temperature` 或 `maxTokens` 等專屬覆寫，而不複製整個模型目錄，請使用此設定。
- `tts`：選用的每代理文字轉語音覆寫。此區塊會深度合併覆蓋 `messages.tts`，因此請將共用提供者憑證與備援政策保留在 `messages.tts`，並只在此設定角色專屬值，例如提供者、語音、模型、風格或自動模式。
- `skills`：選用的每代理 Skills 允許清單。若省略，代理會在已設定時繼承 `agents.defaults.skills`；明確清單會取代預設值而非合併，且 `[]` 表示不使用 Skills。
- `thinkingDefault`：選用的每代理預設思考層級（`off | minimal | low | medium | high | xhigh | adaptive | max`）。當未設定每則訊息或工作階段覆寫時，會為此代理覆寫 `agents.defaults.thinkingDefault`。選取的提供者/模型設定檔會控制哪些值有效；對 Google Gemini 而言，`adaptive` 會保留提供者擁有的動態思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：選用的每代理預設推理可見性（`on | off | stream`）。當未設定每則訊息或工作階段推理覆寫時，會為此代理覆寫 `agents.defaults.reasoningDefault`。
- `fastModeDefault`：選用的每代理快速模式預設值（`true | false`）。當未設定每則訊息或工作階段快速模式覆寫時套用。
- `agentRuntime`：選用的每代理低階執行階段政策覆寫。使用 `{ id: "codex" }` 可讓某個代理僅使用 Codex，而其他代理在 `auto` 模式下維持預設 PI 備援。
- `runtime`：選用的每代理執行階段描述元。當代理應預設使用 ACP harness 工作階段時，請搭配 `runtime.acp` 預設值（`agent`、`backend`、`mode`、`cwd`）使用 `type: "acp"`。
- `identity.avatar`：相對於工作區的路徑、`http(s)` URL，或 `data:` URI。
- `identity` 會衍生預設值：`ackReaction` 來自 `emoji`，`mentionPatterns` 來自 `name`/`emoji`。
- `subagents.allowAgents`：明確 `sessions_spawn.agentId` 目標的代理 id 允許清單（`["*"]` = 任意；預設：僅相同代理）。當應允許自我目標的 `agentId` 呼叫時，請包含請求端 id。
- 沙箱繼承防護：如果請求端工作階段已沙箱化，`sessions_spawn` 會拒絕會以非沙箱方式執行的目標。
- `subagents.requireAgentId`：為 true 時，封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選取設定檔；預設：false）。
---
## 多代理程式路由
## 多代理路由
在一個 Gateway 內執行多個隔離的代理程式。請參閱 [Multi-Agent](/zh-TW/concepts/multi-agent)。
在一個 Gateway 內執行多個隔離的代理。請參閱[多代理](/zh-TW/concepts/multi-agent)。
```json5
{
@ -1028,13 +1036,13 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
### 綁定比對欄位
### 繫結比對欄位
- `type`（選用）：`route` 用於一般路由（缺少 type 時預設為 route），`acp` 用於持久 ACP 對話綁定。
- `type`（選用）：一般路由使用 `route`（缺少 type 時預設為 route），持久 ACP 對話繫結使用 `acp`。
- `match.channel`（必填）
- `match.accountId`（選用；`*` = 任意帳號；省略 = 預設帳號）
- `match.peer`（選用；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（選用；通道特定）
- `match.guildId` / `match.teamId`（選用；頻道專屬）
- `acp`（選用；僅適用於 `type: "acp"`）：`{ mode, label, cwd, backend }`
**確定性比對順序：**
@ -1043,16 +1051,16 @@ scripts/sandbox-browser-setup.sh # optional browser image
2. `match.guildId`
3. `match.teamId`
4. `match.accountId`（精確，無 peer/guild/team）
5. `match.accountId: "*"`（整個通道）
6. 預設代理程式
5. `match.accountId: "*"`（全頻道）
6. 預設代理
在每一層中，第一個相符的 `bindings` 項目會生效。
對於 `type: "acp"` 項目，OpenClaw 會依精確對話身分（`match.channel` + 帳號 + `match.peer.id`）解析，且不使用上方的路由綁定層級順序。
對於 `type: "acp"` 項目，OpenClaw 會依精確的對話身分（`match.channel` + 帳號 + `match.peer.id`）解析，且不使用上述路由繫結層級順序。
### 每代理程式存取設定檔
### 每代理存取設定檔
<Accordion title="完整存取權（無沙箱）">
<Accordion title="Full access (no sandbox)">
```json5
{
@ -1070,7 +1078,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
<Accordion title="唯讀工具 + 工作區">
<Accordion title="Read-only tools + workspace">
```json5
{
@ -1099,7 +1107,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
<Accordion title="無檔案系統存取權限（僅限訊息）">
<Accordion title="無檔案系統存取權（僅限訊息）">
```json5
{
@ -1145,7 +1153,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
</Accordion>
如需優先順序詳細資訊，請參閱[多代理沙箱與工具](/zh-TW/tools/multi-agent-sandbox-tools)。
如需優先順序詳細資訊，請參閱 [Multi-Agent Sandbox & Tools](/zh-TW/tools/multi-agent-sandbox-tools)。
---
@ -1197,33 +1205,33 @@ scripts/sandbox-browser-setup.sh # optional browser image
<Accordion title="工作階段欄位詳細資訊">
- **`scope`**：群組聊天情境的基礎工作階段分組策略。
- `per-sender`（預設）：每個傳送者在某個頻道情境中取得獨立工作階段。
- `global`：某個頻道情境中的所有參與者共用單一工作階段（僅在需要共用情境時使用）。
- `per-sender`（預設）：每位傳送者在一個頻道情境中都有隔離的工作階段。
- `global`：一個頻道情境中的所有參與者共用單一工作階段（僅在需要共用情境時使用）。
- **`dmScope`**：DM 的分組方式。
- `main`：所有 DM 共用主要工作階段。
- `per-peer`：跨頻道依傳送者 ID 隔離。
- `per-channel-peer`：依頻道 + 傳送者隔離（建議用於多使用者收件匣）。
- `per-account-channel-peer`：依帳戶 + 頻道 + 傳送者隔離（建議用於多帳戶）。
- **`identityLinks`**：將標準 ID 對應到帶有供應商前綴的對等方，以便跨頻道共用工作階段。諸如 `/dock_discord` 的 Dock 命令會使用相同對應，將作用中工作階段的回覆路由切換到另一個已連結的頻道對等方；請參閱[頻道 docking](/zh-TW/concepts/channel-docking)。
- **`reset`**：主要重設政策。`daily` 會在本機時間 `atHour` 重設；`idle` 會在 `idleMinutes` 後重設。同時設定時，先到期者生效。每日重設的新鮮度使用工作階段列的 `sessionStartedAt`；閒置重設的新鮮度使用 `lastInteractionAt`。背景/系統事件寫入（例如 Heartbeat、Cron 喚醒、exec 通知和 Gateway 簿記）可以更新 `updatedAt`，但不會讓每日/閒置工作階段保持新鮮。
- `per-account-channel-peer`：依帳號 + 頻道 + 傳送者隔離（建議用於多帳號）。
- **`identityLinks`**：將標準 ID 對應到具有提供者前綴的對等端，以便跨頻道共用工作階段。Dock 指令（例如 `/dock_discord`）使用相同對應，將作用中工作階段的回覆路由切換到另一個已連結的頻道對等端；請參閱[頻道停駐](/zh-TW/concepts/channel-docking)。
- **`reset`**：主要重設原則。`daily` 會在本機時間 `atHour` 重設；`idle` 會在 `idleMinutes` 後重設。兩者都設定時，先到期者生效。每日重設的新鮮度使用工作階段列的 `sessionStartedAt`；閒置重設的新鮮度使用 `lastInteractionAt`。背景/系統事件寫入（例如 Heartbeat、Cron 喚醒、exec 通知和 Gateway 簿記）可以更新 `updatedAt`，但不會讓每日/閒置工作階段保持新鮮。
- **`resetByType`**：依類型覆寫（`direct`、`group`、`thread`）。舊版 `dm` 可作為 `direct` 的別名。
- **`mainKey`**：舊版欄位。執行階段一律使用 `"main"` 作為主要直接聊天儲存桶。
- **`agentToAgent.maxPingPongTurns`**：代理對代理交換期間，代理之間回覆往返的最大回合數（整數，範圍：`0`–`5`）。`0` 會停用 ping-pong 串接。
- **`sendPolicy`**：依 `channel`、`chatType`（`direct|group|channel`，含舊版 `dm` 別名）、`keyPrefix` 或 `rawKeyPrefix` 比對。第一個拒絕規則生效。
- **`mainKey`**：舊版欄位。Runtime 一律使用 `"main"` 作為主要直接聊天桶。
- **`agentToAgent.maxPingPongTurns`**：在代理程式對代理程式交換期間，代理程式之間的最大來回回覆輪數（整數，範圍：`0`–`5`）。`0` 會停用來回串接。
- **`sendPolicy`**：依 `channel`、`chatType`（`direct|group|channel`，含舊版 `dm` 別名）、`keyPrefix` 或 `rawKeyPrefix` 比對。第一個拒絕規則優先。
- **`maintenance`**：工作階段儲存清理 + 保留控制。
- `mode`：`warn` 只發出警告；`enforce` 會套用清理。
- `pruneAfter`：過期項目的年齡截斷點（預設 `30d`）。
- `maxEntries`：`sessions.json` 中的項目數量上限（預設 `500`）。執行階段會使用小型高水位緩衝區批次寫入清理，以支援生產規模上限；`openclaw sessions cleanup --enforce` 會立即套用上限。
- `rotateBytes`：已淘汰且會被忽略；`openclaw doctor --fix` 會將它從較舊設定中移除。
- `resetArchiveRetention`：`*.reset.<timestamp>` 轉錄封存的保留期。預設為 `pruneAfter`；設為 `false` 可停用。
- `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式會記錄警告；在 `enforce` 模式會先移除最舊的成品/工作階段。
- `pruneAfter`：過時項目的年齡截止值（預設 `30d`）。
- `maxEntries`：`sessions.json` 中的項目數上限（預設 `500`）。Runtime 會以適合正式環境大小上限的小型高水位緩衝區批次寫入清理；`openclaw sessions cleanup --enforce` 會立即套用上限。
- `rotateBytes`：已淘汰且會被忽略；`openclaw doctor --fix` 會從較舊的設定中移除它。
- `resetArchiveRetention`：`*.reset.<timestamp>` 對話逐字稿封存的保留期。預設為 `pruneAfter`；設為 `false` 可停用。
- `maxDiskBytes`：選用的工作階段目錄磁碟預算。在 `warn` 模式中會記錄警告；在 `enforce` 模式中會先移除最舊的成品/工作階段。
- `highWaterBytes`：預算清理後的選用目標。預設為 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：執行緒綁定工作階段功能的全域預設值。
- `enabled`：主要預設開關（供應商可覆寫；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：預設非活動自動取消聚焦時間（小時）（`0` 會停用；供應商可覆寫）
- `maxAgeHours`：預設硬性最大年齡（小時）（`0` 會停用；供應商可覆寫）
- `spawnSessions`：從 `sessions_spawn` 和 ACP 執行緒生成建立執行緒綁定工作階段的預設閘門。啟用執行緒綁定時預設為 `true`；供應商/帳戶可覆寫。
- `defaultSpawnContext`：執行緒綁定生成的預設原生子代理情境（`"fork"` 或 `"isolated"`）。預設為 `"fork"`。
- `enabled`：主要預設開關（提供者可以覆寫；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：預設閒置自動取消聚焦時數（`0` 會停用；提供者可以覆寫）
- `maxAgeHours`：預設硬性最大時數（`0` 會停用；提供者可以覆寫）
- `spawnSessions`：從 `sessions_spawn` 和 ACP 執行緒產生建立執行緒綁定工作階段的預設閘門。啟用執行緒綁定時預設為 `true`；提供者/帳號可以覆寫。
- `defaultSpawnContext`：執行緒綁定產生的預設原生子代理程式情境（`"fork"` 或 `"isolated"`）。預設為 `"fork"`。
</Accordion>
@ -1263,34 +1271,34 @@ scripts/sandbox-browser-setup.sh # optional browser image
每個頻道/帳號覆寫：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
解析方式（最具體者優先）：帳號 → 頻道 → 全域。`""` 會停用並停止串接。`"auto"` 會衍生 `[{identity.name}]`。
解析順序（最具體者優先）：帳號 → 頻道 → 全域。`""` 會停用並停止串接。`"auto"` 會衍生為 `[{identity.name}]`。
**範本變數：**
| 變數 | 說明 | 範例 |
| ----------------- | ---------------------- | --------------------------- |
| `{model}` | 簡短模型名稱 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型識別碼 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供者名稱 | `anthropic` |
| `{thinkingLevel}` | 目前思考層級 | `high`, `low`, `off` |
| `{identity.name}` | Agent 身分名稱 | （與 `"auto"` 相同） |
| 變數 | 說明 | 範例 |
| ----------------- | -------------------- | --------------------------- |
| `{model}` | 簡短模型名稱 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型識別碼 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供者名稱 | `anthropic` |
| `{thinkingLevel}` | 目前思考層級 | `high`, `low`, `off` |
| `{identity.name}` | 代理身分名稱 | （與 `"auto"` 相同） |
變數不區分大小寫。`{think}` 是 `{thinkingLevel}` 的別名。
### 確認反應
- 預設為作用中 agent 的 `identity.emoji`，否則為 `"👀"`。設為 `""` 可停用。
- 預設為作用中代理的 `identity.emoji`，否則為 `"👀"`。設為 `""` 可停用。
- 每個頻道覆寫：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析順序：帳號 → 頻道 → `messages.ackReaction` → 身分備援。
- 解析順序：帳號 → 頻道 → `messages.ackReaction` → 身分後援。
- 範圍：`group-mentions`（預設）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在支援反應的頻道（例如 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles）上，回覆後移除確認反應。
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支援反應的頻道上，回覆後移除確認反應。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上啟用生命週期狀態反應。
在 Slack 和 Discord 上，未設定時，只要確認反應為作用中，狀態反應就會保持啟用。
在 Telegram 上，請明確設為 `true` 以啟用生命週期狀態反應。
在 Slack 和 Discord 上，未設定時，如果確認反應為作用中，狀態反應會保持啟用。
在 Telegram 上，需明確將其設為 `true` 才會啟用生命週期狀態反應。
### 傳入防抖
將同一寄件者快速送出的純文字訊息批次合併為單一 agent 回合。媒體/附件會立即刷新。控制命令會略過防抖。
將同一傳送者快速送出的純文字訊息合併成單一代理回合。媒體/附件會立即送出。控制命令會略過防抖。
### TTS（文字轉語音）
@ -1340,19 +1348,19 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
- `auto` 控制預設自動 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆寫本機偏好設定，`/tts status` 會顯示實際生效狀態。
- `summaryModel` 會覆寫自動摘要的 `agents.defaults.model.primary`。
- `auto` 控制預設自動 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆寫本機偏好設定，`/tts status` 會顯示有效狀態。
- `summaryModel` 會覆寫自動摘要所用的 `agents.defaults.model.primary`。
- `modelOverrides` 預設啟用；`modelOverrides.allowProvider` 預設為 `false`（選擇加入）。
- API 金鑰會回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 內建語音提供者由 Plugin 擁有。如果已設定 `plugins.allow`，請加入每個你想使用的 TTS 提供者 Plugin，例如 Edge TTS 的 `microsoft`。舊版 `edge` 提供者 id 會作為 `microsoft` 的別名接受。
- `providers.openai.baseUrl` 會覆寫 OpenAI TTS 端點。解析順序為設定，接著是 `OPENAI_TTS_BASE_URL`，最後是 `https://api.openai.com/v1`。
- 當 `providers.openai.baseUrl` 指向非 OpenAI 端點時，OpenClaw 會將它視為 OpenAI 相容的 TTS 伺服器，並放寬模型/語音驗證。
- API 金鑰會後援至 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 內建語音提供者由 Plugin 擁有。如果已設定 `plugins.allow`，請納入你想使用的每個 TTS 提供者 Plugin，例如 Edge TTS 的 `microsoft`。舊版 `edge` 提供者 ID 會被接受為 `microsoft` 的別名。
- `providers.openai.baseUrl` 會覆寫 OpenAI TTS 端點。解析順序為設定，接著是 `OPENAI_TTS_BASE_URL`，再接著是 `https://api.openai.com/v1`。
- 當 `providers.openai.baseUrl` 指向非 OpenAI 端點時，OpenClaw 會將其視為 OpenAI 相容的 TTS 伺服器，並放寬模型/語音驗證。
---
## Talk
Talk 模式的預設值（macOS/iOS/Android）。
Talk 模式（macOS/iOS/Android）的預設值。
```json5
{
@ -1382,20 +1390,20 @@ Talk 模式的預設值（macOS/iOS/Android）。
```
- 設定多個 Talk 提供者時，`talk.provider` 必須符合 `talk.providers` 中的某個鍵。
- 舊版扁平 Talk 鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容使用，並會自動遷移到 `talk.providers.<provider>`。
- 語音 ID 會回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- 舊版扁平 Talk 鍵（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）僅供相容性使用，並會自動遷移至 `talk.providers.<provider>`。
- 語音 ID 會後援至 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受純文字字串或 SecretRef 物件。
- `ELEVENLABS_API_KEY` 備援只會在未設定 Talk API 金鑰時套用。
- `providers.*.voiceAliases` 讓 Talk 指令可以使用易懂的名稱。
- `ELEVENLABS_API_KEY` 後援僅在未設定 Talk API 金鑰時套用。
- `providers.*.voiceAliases` 讓 Talk 指令能使用易懂名稱。
- `providers.mlx.modelId` 會選取 macOS 本機 MLX 輔助程式使用的 Hugging Face 儲存庫。如省略，macOS 會使用 `mlx-community/Soprano-80M-bf16`。
- macOS MLX 播放會在存在時透過內建的 `openclaw-mlx-tts` 輔助程式執行，或使用 `PATH` 上的可執行檔；`OPENCLAW_MLX_TTS_BIN` 會覆寫開發用的輔助程式路徑。
- `speechLocale` 會設定 iOS/macOS Talk 語音辨識使用的 BCP 47 地區設定 id。保留未設定即可使用裝置預設值。
- `silenceTimeoutMs` 控制 Talk 模式在使用者靜默後等待多久才傳送逐字稿。未設定時會保留平台預設暫停時間窗（`macOS 和 Android 為 700 ms，iOS 為 900 ms`）。
- macOS MLX 播放會在存在時透過內建的 `openclaw-mlx-tts` 輔助程式執行，否則使用 `PATH` 上的可執行檔；`OPENCLAW_MLX_TTS_BIN` 會覆寫開發用的輔助程式路徑。
- `speechLocale` 設定 iOS/macOS Talk 語音辨識使用的 BCP 47 語言環境 ID。保持未設定即可使用裝置預設值。
- `silenceTimeoutMs` 控制 Talk 模式在使用者靜默後等待多久才送出逐字稿。未設定時會保留平台預設暫停時間窗（`macOS 和 Android 為 700 ms，iOS 為 900 ms`）。
---
## 相關
- [設定參考](/zh-TW/gateway/configuration-reference) — 所有其他設定鍵
- [設定](/zh-TW/gateway/configuration) — 常見工作和快速設定
- [設定](/zh-TW/gateway/configuration) — 常見工作與快速設定
- [設定範例](/zh-TW/gateway/configuration-examples)

369
docs/zh-TW/gateway/config-channels.md
View File

@ -1,54 +1,54 @@
---
read_when:
- 設定頻道 Plugin（驗證、存取控制、多帳號）
- 各頻道設定鍵的疑難排解
- 設定頻道 Plugin（身分驗證、存取控制、多帳號）
- 疑難排解各通道設定鍵
- 稽核私訊政策、群組政策或提及閘控
summary: 通道設定：Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等通道的存取控制、配對與每通道金鑰
summary: 通道設定：涵蓋 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 等的存取控制、配對與每個通道的金鑰
title: 設定 — 頻道
x-i18n:
generated_at: "2026-05-03T21:32:03Z"
generated_at: "2026-05-04T02:44:23Z"
model: gpt-5.5
provider: openai
source_hash: 366bcee632c649219bbf6cf44d64cc13d966ec813abc74d54088d89de640b47c
source_hash: 57dcc0b5148324ea6fdee51b7b6e97ec7bd7dc3ca89518ab0816fe4172feefbc
source_path: gateway/config-channels.md
workflow: 16
---
每個通道的設定鍵位於 `channels.*` 底下。涵蓋 DM 和群組存取、多帳號設定、提及門檻，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建通道 Plugin 的個別通道鍵。
每個通道的設定鍵位於 `channels.*` 底下。涵蓋 DM 與群組存取、多帳號設定、提及閘控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建通道 Plugin 的每通道鍵。
如需 agents、工具、Gateway 執行階段和其他頂層鍵，請參閱
若要設定代理、工具、Gateway 執行階段與其他頂層鍵，請參閱
[設定參考](/zh-TW/gateway/configuration-reference)。
## 通道
每個通道會在其設定區段存在時自動啟動（除非 `enabled: false`）。
每個通道都會在其設定區段存在時自動啟動（除非 `enabled: false`）。
### DM 和群組存取
### DM 與群組存取
所有通道都支援 DM 政策和群組政策：
所有通道都支援 DM 政策與群組政策：
| DM 政策 | 行為 |
| DM 政策 | 行為 |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (default) | 未知傳送者會取得一次性配對碼；擁有者必須核准 |
| `allowlist` | 只允許 `allowFrom`（或已配對允許儲存區）中的傳送者 |
| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有傳入 DM |
| `pairing`（預設） | 未知寄件者會取得一次性配對碼；擁有者必須核准 |
| `allowlist` | 僅允許 `allowFrom`（或已配對允許儲存區）中的寄件者 |
| `open` | 允許所有傳入 DM（需要 `allowFrom: ["*"]`） |
| `disabled` | 忽略所有傳入 DM |
| 群組政策 | 行為 |
| --------------------- | -------------------------------------------------------- |
| `allowlist` (default) | 只允許符合已設定允許清單的群組 |
| `open` | 略過群組允許清單（提及門檻仍然適用） |
| 群組政策 | 行為 |
| --------------------- | ------------------------------------------------------ |
| `allowlist`（預設） | 僅允許符合已設定允許清單的群組 |
| `open` | 略過群組允許清單（提及閘控仍會套用） |
| `disabled` | 封鎖所有群組/聊天室訊息 |
<Note>
`channels.defaults.groupPolicy` 會在供應商的 `groupPolicy` 未設定時設定預設值。
`channels.defaults.groupPolicy` 會在提供者的 `groupPolicy` 未設定時指定預設值。
配對碼會在 1 小時後過期。待處理的 DM 配對請求上限為**每個通道 3 個**。
如果供應商區塊完全缺失（沒有 `channels.<provider>`），執行階段群組政策會退回到 `allowlist`（失敗時關閉），並顯示啟動警告。
如果提供者區塊完全缺失（沒有 `channels.<provider>`），執行階段群組政策會回退到 `allowlist`（失敗關閉），並在啟動時發出警告。
</Note>
### 通道模型覆寫
使用 `channels.modelByChannel` 將特定通道 ID 固定到某個模型。值可接受 `provider/model` 或已設定的模型別名。當工作階段尚未有模型覆寫時（例如透過 `/model` 設定），通道對應會套用。
使用 `channels.modelByChannel` 將特定通道 ID 固定到某個模型。值可接受 `provider/model` 或已設定的模型別名。當工作階段尚未有模型覆寫時（例如透過 `/model` 設定），會套用通道對應。
```json5
{
@ -69,9 +69,9 @@ x-i18n:
}
```
### 通道預設值和 Heartbeat
### 通道預設值與 Heartbeat
使用 `channels.defaults` 在各供應商之間共享群組政策和 Heartbeat 行為：
使用 `channels.defaults` 設定跨提供者共用的群組政策與 Heartbeat 行為：
```json5
{
@ -89,15 +89,15 @@ x-i18n:
}
```
- `channels.defaults.groupPolicy`：供應商層級的 `groupPolicy` 未設定時的後備群組政策。
- `channels.defaults.contextVisibility`：所有通道的預設補充脈絡可見性模式。值：`all`（預設，包含所有引用/執行緒/歷史脈絡）、`allowlist`（只包含來自允許清單傳送者的脈絡）、`allowlist_quote`（與 allowlist 相同，但保留明確的引用/回覆脈絡）。個別通道覆寫：`channels.<channel>.contextVisibility`。
- `channels.defaults.groupPolicy`：提供者層級的 `groupPolicy` 未設定時的後援群組政策。
- `channels.defaults.contextVisibility`：所有通道的預設補充上下文可見性模式。值：`all`（預設，包含所有引用/討論串/歷史上下文）、`allowlist`（僅包含允許清單寄件者的上下文）、`allowlist_quote`（與 allowlist 相同，但保留明確的引用/回覆上下文）。每通道覆寫：`channels.<channel>.contextVisibility`。
- `channels.defaults.heartbeat.showOk`：在 Heartbeat 輸出中包含健康的通道狀態。
- `channels.defaults.heartbeat.showAlerts`：在 Heartbeat 輸出中包含降級/錯誤狀態。
- `channels.defaults.heartbeat.useIndicator`：呈現精簡指示器樣式的 Heartbeat 輸出。
### WhatsApp
WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的工作階段存在時，它會自動啟動。
WhatsApp 透過 Gateway 的 Web 通道（Baileys Web）執行。當已連結的工作階段存在時會自動啟動。
```json5
{
@ -135,7 +135,7 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
<Accordion title="Multi-account WhatsApp">
<Accordion title="多帳號 WhatsApp">
```json5
{
@ -153,10 +153,10 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
- 外送命令預設使用 `default` 帳號（如果存在）；否則使用第一個已設定的帳號 ID（排序後）。
- 選用的 `channels.whatsapp.defaultAccount` 會在符合已設定帳號 ID 時覆寫該後備預設帳號選擇。
- 舊版單帳號 Baileys auth 目錄會由 `openclaw doctor` 遷移到 `whatsapp/default`。
- 個別帳號覆寫：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
- 若存在 `default`，傳出命令預設使用帳號 `default`；否則使用第一個已設定的帳號 ID（排序後）。
- 選用的 `channels.whatsapp.defaultAccount` 會在符合已設定帳號 ID 時覆寫該後援預設帳號選擇。
- 舊版單帳號 Baileys 驗證目錄會由 `openclaw doctor` 遷移到 `whatsapp/default`。
- 每帳號覆寫：`channels.whatsapp.accounts.<id>.sendReadReceipts`、`channels.whatsapp.accounts.<id>.dmPolicy`、`channels.whatsapp.accounts.<id>.allowFrom`。
</Accordion>
@ -215,13 +215,13 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
- Bot 權杖：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅一般檔案；拒絕符號連結），預設帳號則以 `TELEGRAM_BOT_TOKEN` 作為後備。
- `apiRoot` 只是 Telegram Bot API 根路徑。使用 `https://api.telegram.org` 或你的自架/代理根路徑，不要使用 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 會移除意外尾隨的 `/bot<TOKEN>` 後綴。
- Bot 權杖：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（僅限一般檔案；拒絕符號連結），預設帳號會以 `TELEGRAM_BOT_TOKEN` 作為後援。
- `apiRoot` 僅是 Telegram Bot API 根目錄。請使用 `https://api.telegram.org` 或你的自架/Proxy 根目錄，不要使用 `https://api.telegram.org/bot<TOKEN>`；`openclaw doctor --fix` 會移除意外加上的尾端 `/bot<TOKEN>` 後綴。
- 選用的 `channels.telegram.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
- 在多帳號設定（2 個以上帳號 ID）中，請設定明確預設值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免後備路由；缺失或無效時，`openclaw doctor` 會發出警告。
- 在多帳號設定（2 個以上帳號 ID）中，請設定明確預設值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免後援路由；缺失或無效時，`openclaw doctor` 會發出警告。
- `configWrites: false` 會封鎖由 Telegram 發起的設定寫入（超級群組 ID 遷移、`/config set|unset`）。
- 含有 `type: "acp"` 的頂層 `bindings[]` 項目會為論壇主題設定持久 ACP 繫結（在 `match.peer.id` 使用標準 `chatId:topic:topicId`）。欄位語意在 [ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。
- Telegram 串流預覽使用 `sendMessage` + `editMessageText`（可在直接和群組聊天中運作）。
- 帶有 `type: "acp"` 的頂層 `bindings[]` 項目會為論壇主題設定持久 ACP 繫結（在 `match.peer.id` 中使用標準 `chatId:topic:topicId`）。欄位語意在 [ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。
- Telegram 串流預覽使用 `sendMessage` + `editMessageText`（可在直接聊天與群組聊天中運作）。
- 重試政策：請參閱[重試政策](/zh-TW/concepts/retry)。
### Discord
@ -327,38 +327,38 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
- 權杖：`channels.discord.token`，預設帳號會以 `DISCORD_BOT_TOKEN` 作為備援。
- 提供明確 Discord `token` 的直接對外呼叫會使用該權杖進行呼叫；帳號重試/政策設定仍來自作用中執行階段快照中選取的帳號。
- 可選的 `channels.discord.defaultAccount` 在符合已設定帳號 ID 時，會覆寫預設帳號選擇。
- 使用 `user:<id>`（DM）或 `channel:<id>`（公會頻道）作為傳送目標；裸數字 ID 會被拒絕。
- 公會 slug 會轉為小寫並將空格替換為 `-`；頻道鍵使用已 slug 化的名稱（不含 `#`）。建議優先使用公會 ID。
- 預設會忽略由機器人撰寫的訊息。`allowBots: true` 會啟用這些訊息；使用 `allowBots: "mentions"` 則只接受提及該機器人的機器人訊息（自己的訊息仍會被篩除）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及頻道覆寫）會丟棄提及其他使用者或角色、但未提及該機器人的訊息（不含 @everyone/@here）。
- `channels.discord.mentionAliases` 會在傳送前將穩定的對外 `@handle` 文字對應到 Discord 使用者 ID，因此即使暫時目錄快取為空，也能以確定方式提及已知隊友。個別帳號覆寫位於 `channels.discord.accounts.<accountId>.mentionAliases`。
- `maxLinesPerMessage`（預設 17）即使在 2000 字元以內，也會拆分過高的訊息。
- Token：`channels.discord.token`，預設帳戶可使用 `DISCORD_BOT_TOKEN` 作為備援。
- 提供明確 Discord `token` 的直接對外呼叫會使用該 Token 進行呼叫；帳戶重試/政策設定仍來自作用中執行階段快照中的所選帳戶。
- 選用的 `channels.discord.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。
- 使用 `user:<id>`（DM）或 `channel:<id>`（伺服器頻道）作為傳送目標；不接受裸數字 ID。
- 伺服器 slug 為小寫，空格會替換為 `-`；頻道鍵使用 slug 化名稱（不含 `#`）。建議使用伺服器 ID。
- 預設會忽略機器人作者的訊息。`allowBots: true` 會啟用它們；使用 `allowBots: "mentions"` 則只接受提及該機器人的機器人訊息（自己的訊息仍會被過濾）。
- `channels.discord.guilds.<id>.ignoreOtherMentions`（以及頻道覆寫）會捨棄提及其他使用者或角色、但未提及該機器人的訊息（排除 @everyone/@here）。
- `channels.discord.mentionAliases` 會在傳送前將穩定的對外 `@handle` 文字對應到 Discord 使用者 ID，因此即使暫時性目錄快取為空，也能確定性地提及已知隊友。每個帳戶的覆寫位於 `channels.discord.accounts.<accountId>.mentionAliases` 下。
- `maxLinesPerMessage`（預設 17）即使在低於 2000 字元時也會拆分較高的訊息。
- `channels.discord.threadBindings` 控制 Discord 執行緒綁定路由：
- `enabled`：Discord 對執行緒綁定工作階段功能的覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及綁定傳送/路由）
- `idleHours`：Discord 對閒置自動取消聚焦時數的覆寫（`0` 會停用）
- `maxAgeHours`：Discord 對硬性最大時數的覆寫（`0` 會停用）
- `spawnSessions`：`sessions_spawn({ thread: true })` 和 ACP 執行緒產生自動建立/綁定執行緒的開關（預設：`true`）
- `defaultSpawnContext`：執行緒綁定產生的原生子代理程式情境（預設為 `"fork"`）
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目會為頻道和執行緒設定持久 ACP 綁定（在 `match.peer.id` 中使用頻道/執行緒 ID）。欄位語意共用於 [ACP 代理程式](/zh-TW/tools/acp-agents#persistent-channel-bindings)。
- `channels.discord.ui.components.accentColor` 設定 Discord components v2 容器的強調色。
- `channels.discord.voice` 啟用 Discord 語音頻道對話，以及可選的自動加入 + LLM + TTS 覆寫。純文字 Discord 設定預設會關閉語音；設定 `channels.discord.voice.enabled=true` 以選擇啟用。
- `channels.discord.voice.model` 可選擇覆寫 Discord 語音頻道回覆所使用的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞至 `@discordjs/voice` DAVE 選項（預設為 `true` 和 `24`）。
- `enabled`：針對執行緒綁定工作階段功能的 Discord 覆寫（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及綁定的傳送/路由）
- `idleHours`：以小時計算的閒置自動取消聚焦 Discord 覆寫（`0` 會停用）
- `maxAgeHours`：以小時計算的硬性最長存續時間 Discord 覆寫（`0` 會停用）
- `spawnSessions`：`sessions_spawn({ thread: true })` 與 ACP 執行緒衍生自動建立/綁定執行緒的開關（預設：`true`）
- `defaultSpawnContext`：執行緒綁定衍生的原生子代理程式情境（預設為 `"fork"`）
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目會為頻道和執行緒設定持久 ACP 綁定（在 `match.peer.id` 中使用頻道/執行緒 ID）。欄位語意在 [ACP 代理程式](/zh-TW/tools/acp-agents#persistent-channel-bindings) 中共用。
- `channels.discord.ui.components.accentColor` 設定 Discord 元件 v2 容器的強調色。
- `channels.discord.voice` 啟用 Discord 語音頻道對話，以及選用的自動加入 + LLM + TTS 覆寫。純文字 Discord 設定預設會關閉語音；設定 `channels.discord.voice.enabled=true` 即可選擇啟用。
- `channels.discord.voice.model` 可選擇性覆寫用於 Discord 語音頻道回應的 LLM 模型。
- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 會傳遞至 `@discordjs/voice` DAVE 選項（預設分別為 `true` 和 `24`）。
- `channels.discord.voice.connectTimeoutMs` 控制 `/vc join` 和自動加入嘗試的初始 `@discordjs/voice` Ready 等待時間（預設為 `30000`）。
- `channels.discord.voice.reconnectGraceMs` 控制已中斷連線的語音工作階段可在 OpenClaw 銷毀前花多久時間進入重新連線訊號狀態（預設為 `15000`）。
- OpenClaw 另外會在重複解密失敗後，透過離開/重新加入語音工作階段來嘗試語音接收復原。
- `channels.discord.streaming` 是標準串流模式鍵。舊版 `streamMode` 和布林值 `streaming` 會自動遷移。
- `channels.discord.autoPresence` 會將執行階段可用性對應到機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許可選的狀態文字覆寫。
- `channels.discord.voice.reconnectGraceMs` 控制已中斷連線的語音工作階段在 OpenClaw 銷毀它之前，可花多久時間進入重新連線訊號狀態（預設為 `15000`）。
- OpenClaw 也會在重複解密失敗後，透過離開/重新加入語音工作階段來嘗試語音接收復原。
- `channels.discord.streaming` 是正式的串流模式鍵。舊版 `streamMode` 和布林值 `streaming` 會自動遷移。
- `channels.discord.autoPresence` 會將執行階段可用性對應至機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許選用的狀態文字覆寫。
- `channels.discord.dangerouslyAllowNameMatching` 會重新啟用可變名稱/標籤比對（緊急相容模式）。
- `channels.discord.execApprovals`：Discord 原生 exec 核准傳送和核准者授權。
- `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當可從 `approvers` 或 `commands.ownerAllowFrom` 解析核准者時，exec 核准會啟用。
- `approvers`：允許核准 exec 要求的 Discord 使用者 ID。省略時會退回使用 `commands.ownerAllowFrom`。
- `agentFilter`：可選的代理程式 ID 允許清單。省略時會轉送所有代理程式的核准。
- `sessionFilter`：可選的工作階段鍵模式（子字串或 regex）。
- `target`：傳送核准提示的位置。`"dm"`（預設）傳送至核准者 DM，`"channel"` 傳送至來源頻道，`"both"` 兩者都傳送。當 target 包含 `"channel"` 時，按鈕只能由已解析的核准者使用。
- `channels.discord.execApprovals`：Discord 原生 exec 核准傳送與核准者授權。
- `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當核准者可從 `approvers` 或 `commands.ownerAllowFrom` 解析時，exec 核准就會啟用。
- `approvers`：允許核准 exec 請求的 Discord 使用者 ID。省略時會退回使用 `commands.ownerAllowFrom`。
- `agentFilter`：選用的代理程式 ID 允許清單。省略即可轉送所有代理程式的核准。
- `sessionFilter`：選用的工作階段鍵模式（子字串或正規表示式）。
- `target`：核准提示的傳送位置。`"dm"`（預設）會傳送給核准者 DM，`"channel"` 會傳送到來源頻道，`"both"` 會兩者都傳送。當目標包含 `"channel"` 時，按鈕僅可由已解析的核准者使用。
- `cleanupAfterResolve`：為 `true` 時，會在核准、拒絕或逾時後刪除核准 DM。
**反應通知模式：** `off`（無）、`own`（機器人的訊息，預設）、`all`（所有訊息）、`allowlist`（來自所有訊息上的 `guilds.<id>.users`）。
@ -392,9 +392,9 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
- 服務帳號 JSON：行內（`serviceAccount`）或檔案式（`serviceAccountFile`）。
- 也支援服務帳號 SecretRef（`serviceAccountRef`）。
- 環境備援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 服務帳戶 JSON：行內（`serviceAccount`）或檔案型（`serviceAccountFile`）。
- 也支援服務帳戶 SecretRef（`serviceAccountRef`）。
- 環境變數備援：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。
- 使用 `spaces/<spaceId>` 或 `users/<userId>` 作為傳送目標。
- `channels.googlechat.dangerouslyAllowNameMatching` 會重新啟用可變電子郵件主體比對（緊急相容模式）。
@ -468,43 +468,44 @@ WhatsApp 透過 Gateway 的網頁通道（Baileys Web）執行。當已連結的
}
```
- **Socket mode** 需要同時有 `botToken` 和 `appToken`（預設帳號環境備援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（在根層或個別帳號中）。
- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞至公開 Bolt receiver API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用。
- **Socket mode** 需要同時有 `botToken` 和 `appToken`（預設帳戶環境變數備援為 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。
- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（位於根層級或每個帳戶）。
- `socketMode` 會將 Slack SDK Socket Mode 傳輸調校傳遞給公開 Bolt 接收器 API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用它。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受純文字
字串或 SecretRef 物件。
- Slack 帳號快照會公開個別憑證來源/狀態欄位，例如
`botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 中的
`signingSecretStatus`。`configured_unavailable` 表示該帳號已透過 SecretRef
設定，但目前的命令/執行階段路徑無法解析祕密值。
- `configWrites: false` 會阻止由 Slack 發起的設定寫入。
- 可選的 `channels.slack.defaultAccount` 在符合已設定帳號 ID 時，會覆寫預設帳號選擇。
- `channels.slack.streaming.mode` 是標準 Slack 串流模式鍵。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生串流傳輸。舊版 `streamMode`、布林值 `streaming` 和 `nativeStreaming` 會自動遷移。
- Slack 帳戶快照會公開每個憑證的來源/狀態欄位，例如
`botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式中的
`signingSecretStatus`。`configured_unavailable` 表示帳戶是
透過 SecretRef 設定，但目前的命令/執行階段路徑無法
解析密鑰值。
- `configWrites: false` 會封鎖由 Slack 發起的設定寫入。
- 選用的 `channels.slack.defaultAccount` 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。
- `channels.slack.streaming.mode` 是正式的 Slack 串流模式鍵。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生串流傳輸。舊版 `streamMode`、布林值 `streaming` 和 `nativeStreaming` 會自動遷移。
- 使用 `user:<id>`（DM）或 `channel:<id>` 作為傳送目標。
**反應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
**執行緒工作階段隔離：** `thread.historyScope` 為個別執行緒（預設）或跨頻道共用。`thread.inheritParent` 會將父頻道逐字稿複製到新執行緒。
**執行緒工作階段隔離：** `thread.historyScope` 為每個執行緒（預設）或跨頻道共用。`thread.inheritParent` 會將父頻道轉錄複製到新執行緒。
- Slack 原生串流加上 Slack 助理風格的「is typing...」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持在執行緒外，因此仍可透過 Slack 草稿張貼並編輯預覽來串流，而不是顯示執行緒風格的原生串流/狀態預覽。
- `typingReaction` 會在回覆執行期間，向傳入的 Slack 訊息加入暫時反應，並在完成時移除。請使用 Slack emoji shortcode，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 核准傳送和核准者授權。與 Discord 相同的 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 使用者 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
- Slack 原生串流加上 Slack 助理風格的「is typing...」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持非執行緒，因此它們仍可透過 Slack 草稿發文並編輯預覽進行串流，而不是顯示執行緒風格的原生串流/狀態預覽。
- `typingReaction` 會在回覆執行期間，將暫時性反應新增到傳入的 Slack 訊息，然後在完成時移除。請使用 Slack emoji 短代碼，例如 `"hourglass_flowing_sand"`。
- `channels.slack.execApprovals`：Slack 原生 exec 核准傳送與核准者授權。結構描述與 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 使用者 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。
| 動作群組 | 預設 | 備註 |
| 動作群組 | 預設 | 備註 |
| ------------ | ------- | ---------------------- |
| reactions | enabled | 反應 + 列出反應 |
| messages | enabled | 讀取/傳送/編輯/刪除 |
| pins | enabled | 釘選/取消釘選/列出 |
| memberInfo | enabled | 成員資訊 |
| emojiList | enabled | 自訂 emoji 清單 |
| reactions | 已啟用 | 反應 + 列出反應 |
| messages | 已啟用 | 讀取/傳送/編輯/刪除 |
| pins | 已啟用 | 釘選/取消釘選/列出 |
| memberInfo | 已啟用 | 成員資訊 |
| emojiList | 已啟用 | 自訂 emoji 清單 |
### Mattermost
Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或
Mattermost 在目前的 OpenClaw 版本中以 bundled Plugin 形式提供。較舊或
自訂建置可以使用
`openclaw plugins install @openclaw/mattermost` 安裝目前的 npm package。固定版本前，請查看
`openclaw plugins install @openclaw/mattermost` 安裝目前的 npm 套件。固定版本前，請先查看
[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost)
取得目前的 dist-tags。
以確認目前的 dist-tags。
```json5
{
@ -534,18 +535,18 @@ Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或
}
```
聊天模式：`oncall`（在 @ 提及時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。
聊天模式：`oncall`（在 @-提及時回應，預設）、`onmessage`（每則訊息）、`onchar`（以觸發前綴開頭的訊息）。
啟用 Mattermost 原生命令時：
- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），不是完整 URL。
- `commands.callbackUrl` 必須解析到 OpenClaw gateway 端點，且 Mattermost 伺服器必須可連線。
- 原生斜線命令回呼會使用 Mattermost 在斜線命令註冊期間傳回的每個命令 token 進行驗證。如果註冊失敗或沒有啟用任何命令，OpenClaw 會以 `Unauthorized: invalid command token.` 拒絕回呼。
- 對於私有/tailnet/內部回呼主機，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回呼主機/網域。請使用主機/網域值，不要使用完整 URL。
- `channels.mattermost.configWrites`：允許或拒絕 Mattermost 發起的設定寫入。
- `channels.mattermost.requireMention`：在頻道中回覆前要求 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：每個頻道的提及門控覆寫（`"*"` 表示預設）。
- 可選的 `channels.mattermost.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。
- `commands.callbackPath` 必須是路徑（例如 `/api/channels/mattermost/command`），而不是完整 URL。
- `commands.callbackUrl` 必須解析到 OpenClaw gateway 端點，且可由 Mattermost 伺服器存取。
- 原生斜線命令回呼會使用 Mattermost 在註冊斜線命令時傳回的逐命令權杖進行驗證。如果註冊失敗或沒有啟用任何命令，OpenClaw 會以 `Unauthorized: invalid command token.` 拒絕回呼。
- 對於私有、tailnet 或內部回呼主機，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含該回呼主機/網域。請使用主機/網域值，而不是完整 URL。
- `channels.mattermost.configWrites`：允許或拒絕由 Mattermost 發起的設定寫入。
- `channels.mattermost.requireMention`：要求在頻道中回覆前必須有 `@mention`。
- `channels.mattermost.groups.<channelId>.requireMention`：逐頻道的提及門檻覆寫（`"*"` 表示預設）。
- 選用的 `channels.mattermost.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
### Signal
@ -566,15 +567,15 @@ Mattermost 在目前 OpenClaw 版本中作為 bundled Plugin 隨附。較舊或
}
```
**回應通知模式：** `off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
**反應通知模式：**`off`、`own`（預設）、`all`、`allowlist`（來自 `reactionAllowlist`）。
- `channels.signal.account`：將頻道啟動固定到特定的 Signal 帳號身分。
- `channels.signal.configWrites`：允許或拒絕 Signal 發起的設定寫入。
- 可選的 `channels.signal.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。
- `channels.signal.account`：將頻道啟動固定到特定 Signal 帳號身分。
- `channels.signal.configWrites`：允許或拒絕由 Signal 發起的設定寫入。
- 選用的 `channels.signal.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
### BlueBubbles
BlueBubbles 是建議的 iMessage 路徑（由 plugin 支援，設定於 `channels.bluebubbles` 之下）。
BlueBubbles 是建議的 iMessage 路徑（由 Plugin 支援，設定於 `channels.bluebubbles` 下）。
```json5
{
@ -589,9 +590,9 @@ BlueBubbles 是建議的 iMessage 路徑（由 plugin 支援，設定於 `channe
}
```
- 這裡涵蓋的核心 key path：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 可選的 `channels.bluebubbles.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。
- 頂層 `bindings[]` 項目搭配 `type: "acp"` 可將 BlueBubbles 對話繫結到持續性 ACP 工作階段。在 `match.peer.id` 中使用 BlueBubbles handle 或目標字串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings)。
- 此處涵蓋的核心鍵路徑：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。
- 選用的 `channels.bluebubbles.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 BlueBubbles 對話繫結到持久 ACP 工作階段。請在 `match.peer.id` 中使用 BlueBubbles handle 或目標字串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings)。
- 完整的 BlueBubbles 頻道設定記錄於 [BlueBubbles](/zh-TW/channels/bluebubbles)。
### iMessage
@ -620,17 +621,17 @@ OpenClaw 會產生 `imsg rpc`（透過 stdio 的 JSON-RPC）。不需要 daemon
}
```
- 可選的 `channels.imessage.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。
- 選用的 `channels.imessage.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
- 需要 Messages DB 的完整磁碟存取權。
- 建議使用 `chat_id:<id>` 目標。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH wrapper；設定 `remoteHost`（`host` 或 `user@host`）以擷取 SCP 附件。
- 需要對 Messages DB 授予完整磁碟存取權。
- 優先使用 `chat_id:<id>` 目標。使用 `imsg chats --limit 20` 列出聊天。
- `cliPath` 可以指向 SSH 包裝器；設定 `remoteHost`（`host` 或 `user@host`）以擷取 SCP 附件。
- `attachmentRoots` 和 `remoteAttachmentRoots` 會限制傳入附件路徑（預設：`/Users/*/Library/Messages/Attachments`）。
- SCP 使用嚴格的 host-key 檢查，因此請確認轉送主機金鑰已存在於 `~/.ssh/known_hosts`。
- `channels.imessage.configWrites`：允許或拒絕 iMessage 發起的設定寫入。
- 頂層 `bindings[]` 項目搭配 `type: "acp"` 可將 iMessage 對話繫結到持續性 ACP 工作階段。在 `match.peer.id` 中使用正規化 handle 或明確聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP Agents](/zh-TW/tools/acp-agents#persistent-channel-bindings)。
- SCP 使用嚴格主機金鑰檢查，因此請確保轉送主機金鑰已存在於 `~/.ssh/known_hosts`。
- `channels.imessage.configWrites`：允許或拒絕由 iMessage 發起的設定寫入。
- 具有 `type: "acp"` 的頂層 `bindings[]` 項目可將 iMessage 對話繫結到持久 ACP 工作階段。請在 `match.peer.id` 中使用正規化 handle 或明確的聊天目標（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共用欄位語意：[ACP 代理](/zh-TW/tools/acp-agents#persistent-channel-bindings)。
<Accordion title="iMessage SSH wrapper 範例">
<Accordion title="iMessage SSH 包裝器範例">
```bash
#!/usr/bin/env bash
@ -641,7 +642,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix 由 plugin 支援，並設定於 `channels.matrix` 之下。
Matrix 由 Plugin 支援，並設定於 `channels.matrix` 下。
```json5
{
@ -671,25 +672,25 @@ Matrix 由 plugin 支援，並設定於 `channels.matrix` 之下。
}
```
- Token 驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。
- 權杖驗證使用 `accessToken`；密碼驗證使用 `userId` + `password`。
- `channels.matrix.proxy` 會透過明確的 HTTP(S) proxy 路由 Matrix HTTP 流量。具名帳號可使用 `channels.matrix.accounts.<id>.proxy` 覆寫。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私有/內部 homeserver。`proxy` 和這個網路 opt-in 是獨立控制項。
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允許私有/內部 homeserver。`proxy` 與此網路選擇加入是獨立控制項。
- `channels.matrix.defaultAccount` 會在多帳號設定中選取偏好的帳號。
- `channels.matrix.autoJoin` 預設為 `off`，因此受邀房間和新的 DM 樣式邀請會被忽略，直到你設定 `autoJoin: "allowlist"` 搭配 `autoJoinAllowlist`，或設定 `autoJoin: "always"`。
- `channels.matrix.autoJoin` 預設為 `off`，因此受邀房間與新的 DM 樣式邀請都會被忽略，直到你設定 `autoJoin: "allowlist"` 搭配 `autoJoinAllowlist`，或設定 `autoJoin: "always"`。
- `channels.matrix.execApprovals`：Matrix 原生 exec 核准傳遞與核准者授權。
- `enabled`：`true`、`false` 或 `"auto"`（預設）。在自動模式中，當可從 `approvers` 或 `commands.ownerAllowFrom` 解析核准者時，exec 核准會啟用。
- `approvers`：允許核准 exec 要求的 Matrix 使用者 ID（例如 `@owner:example.org`）。
- `agentFilter`：可選的代理程式 ID allowlist。省略時會轉送所有代理程式的核准。
- `sessionFilter`：可選的工作階段 key 模式（substring 或 regex）。
- `target`：核准提示的傳送位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。
- 每帳號覆寫：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix DM 如何分組為工作階段：`per-user`（預設）會依路由後的 peer 共用，而 `per-room` 會隔離每個 DM 房間。
- Matrix 狀態探測和即時目錄查詢會使用與執行階段流量相同的 proxy 原則。
- 完整的 Matrix 設定、目標規則和設定範例記錄於 [Matrix](/zh-TW/channels/matrix)。
- `approvers`：允許核准 exec 請求的 Matrix 使用者 ID（例如 `@owner:example.org`）。
- `agentFilter`：選用代理 ID allowlist。省略時會轉送所有代理的核准。
- `sessionFilter`：選用工作階段鍵模式（子字串或 regex）。
- `target`：傳送核准提示的位置。`"dm"`（預設）、`"channel"`（來源房間）或 `"both"`。
- 逐帳號覆寫：`channels.matrix.accounts.<id>.execApprovals`。
- `channels.matrix.dm.sessionScope` 控制 Matrix DM 如何分組成工作階段：`per-user`（預設）依路由對等端共用，而 `per-room` 會隔離每個 DM 房間。
- Matrix 狀態探測與即時目錄查詢使用與執行階段流量相同的 proxy 原則。
- 完整的 Matrix 設定、目標規則與設定範例記錄於 [Matrix](/zh-TW/channels/matrix)。
### Microsoft Teams
Microsoft Teams 由 plugin 支援，並設定於 `channels.msteams` 之下。
Microsoft Teams 由 Plugin 支援，並設定於 `channels.msteams` 下。
```json5
{
@ -704,12 +705,12 @@ Microsoft Teams 由 plugin 支援，並設定於 `channels.msteams` 之下。
}
```
- 這裡涵蓋的核心 key path：`channels.msteams`、`channels.msteams.configWrites`。
- 完整的 Teams 設定（認證、webhook、DM/群組原則、每個 team/每個頻道覆寫）記錄於 [Microsoft Teams](/zh-TW/channels/msteams)。
- 此處涵蓋的核心鍵路徑：`channels.msteams`、`channels.msteams.configWrites`。
- 完整的 Teams 設定（認證、Webhook、DM/群組原則、逐團隊/逐頻道覆寫）記錄於 [Microsoft Teams](/zh-TW/channels/msteams)。
### IRC
IRC 由 plugin 支援，並設定於 `channels.irc` 之下。
IRC 由 Plugin 支援，並設定於 `channels.irc` 下。
```json5
{
@ -730,9 +731,9 @@ IRC 由 plugin 支援，並設定於 `channels.irc` 之下。
}
```
- 這裡涵蓋的核心 key path：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 可選的 `channels.irc.defaultAccount` 會在符合已設定的帳號 id 時覆寫預設帳號選擇。
- 完整的 IRC 頻道設定（host/port/TLS/頻道/allowlist/提及門控）記錄於 [IRC](/zh-TW/channels/irc)。
- 此處涵蓋的核心鍵路徑：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。
- 選用的 `channels.irc.defaultAccount` 會在符合已設定帳號 ID 時覆寫預設帳號選擇。
- 完整的 IRC 頻道設定（主機/連接埠/TLS/頻道/allowlist/提及門檻）記錄於 [IRC](/zh-TW/channels/irc)。
### 多帳號（所有頻道）
@ -758,33 +759,35 @@ IRC 由 plugin 支援，並設定於 `channels.irc` 之下。
```
- 省略 `accountId` 時會使用 `default`（CLI + 路由）。
- Env token 只套用到 **default** 帳號。
- 基礎頻道設定會套用到所有帳號，除非每個帳號另有覆寫。
- 使用 `bindings[].match.accountId` 將每個帳號路由到不同代理程式。
- 如果你透過 `openclaw channels add`（或頻道 onboarding）新增非預設帳號，而目前仍使用單帳號頂層頻道設定，OpenClaw 會先將帳號作用域的頂層單帳號值提升到頻道帳號 map，讓原始帳號繼續運作。多數頻道會將它們移入 `channels.<channel>.accounts.default`；Matrix 則可保留現有相符的具名/預設目標。
- 現有的僅頻道繫結（沒有 `accountId`）會繼續符合預設帳號；帳號作用域繫結仍為可選。
- `openclaw doctor --fix` 也會修復混合形狀，方法是將帳號作用域的頂層單帳號值移入該頻道所選的提升帳號。多數頻道使用 `accounts.default`；Matrix 則可保留現有相符的具名/預設目標。
- Env 權杖只會套用到**預設**帳號。
- 基礎頻道設定會套用到所有帳號，除非逐帳號覆寫。
- 使用 `bindings[].match.accountId` 將每個帳號路由到不同代理。
- 如果你透過 `openclaw channels add`（或頻道 onboarding）新增非預設帳號，同時仍使用單帳號頂層頻道設定，OpenClaw 會先將帳號範圍的頂層單帳號值提升到頻道帳號對應表，使原始帳號繼續運作。大多數頻道會將它們移入 `channels.<channel>.accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。
- 現有僅限頻道的繫結（沒有 `accountId`）會繼續符合預設帳號；帳號範圍的繫結仍為選用。
- `openclaw doctor --fix` 也會透過將帳號範圍的頂層單帳號值移入該頻道所選的已提升帳號，來修復混合形狀。大多數頻道使用 `accounts.default`；Matrix 則可改為保留現有相符的具名/預設目標。
### 其他 plugin 頻道
### 其他 Plugin 頻道
許多 plugin 頻道設定為 `channels.<id>`，並記錄於各自的專用頻道頁面（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
許多 Plugin 頻道會設定為 `channels.<id>`，並記錄於其專用頻道頁面（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。
請參閱完整頻道索引：[頻道](/zh-TW/channels)。
### 群組聊天提及門控
### 群組聊天提及門檻
群組訊息預設為 **要求提及**（metadata 提及或安全 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。
群組訊息預設為**要求提及**（中繼資料提及或安全的 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。
可見回覆會另行控制。群組/頻道房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪次，但一般最終回覆會保持私密，可見房間輸出需要 `message(action=send)`。只有在你想要舊版行為，也就是一般回覆會貼回房間時，才設定 `"automatic"`。若要將相同的僅工具可見回覆行為也套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`；Codex harness 也會將該僅工具行為作為未設定的直接聊天預設。
可見回覆由另一組設定控制。群組/頻道房間預設為 `messages.groupChat.visibleReplies: "message_tool"`：OpenClaw 仍會處理該輪對話，但一般最終回覆會保持私密，可見的房間輸出需要 `message(action=send)`。只有在你想要舊有行為，也就是一般回覆會張貼回房間時，才設定 `"automatic"`。若也要將相同的僅工具可見回覆行為套用到直接聊天，請設定 `messages.visibleReplies: "message_tool"`；Codex harness 也會將該僅工具行為作為其未設定的直接聊天預設。
如果訊息工具在作用中的工具原則下不可用，OpenClaw 會退回自動可見回覆，而不是靜默抑制回應。`openclaw doctor` 會警告此不相符狀態。
僅工具可見回覆需要能可靠呼叫工具的模型/執行階段。如果工作階段記錄顯示 assistant 文字帶有 `didSendViaMessagingTool: false`，表示模型產生了私密最終答案，而不是呼叫 message 工具。請改用該頻道的更強工具呼叫模型，或設定 `messages.groupChat.visibleReplies: "automatic"` 以還原舊有可見最終回覆。
Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署中停用檔案監看或設定重新載入時才需要重新啟動。
如果 message 工具在作用中的工具原則下不可用，OpenClaw 會退回到自動可見回覆，而不是靜默抑制回應。`openclaw doctor` 會針對此不相符狀況發出警告。
gateway 會在檔案儲存後熱重載 `messages` 設定。只有在部署中停用檔案監看或設定重載時，才需要重新啟動。
**提及類型：**
- **Metadata 提及**：原生平台 @-mentions。在 WhatsApp 自我聊天模式中會忽略。
- **中繼資料提及**：原生平台 @-提及。在 WhatsApp 自我聊天模式中會被忽略。
- **文字模式**：`agents.list[].groupChat.mentionPatterns` 中的安全 regex 模式。無效模式和不安全的巢狀重複會被忽略。
- 只有在可偵測時（原生提及或至少一個模式），才會強制執行提及門控。
- 只有在可偵測時才會強制執行提及閘控（原生提及或至少一個模式）。
```json5
{
@ -801,11 +804,11 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署
}
```
`messages.groupChat.historyLimit` 會設定全域預設值。頻道可使用 `channels.<channel>.historyLimit`（或依帳號）覆寫。設為 `0` 可停用。
`messages.groupChat.historyLimit` 會設定全域預設值。頻道可以用 `channels.<channel>.historyLimit`（或依帳號）覆寫。設為 `0` 可停用。
`messages.visibleReplies` 是全域來源回合預設值；`messages.groupChat.visibleReplies` 會針對群組/頻道來源回合覆寫它。當 `messages.visibleReplies` 未設定時，harness 可以提供自己的直接/來源預設值；Codex harness 預設為 `message_tool`。頻道允許清單與提及閘控仍會決定是否處理某個回合。
`messages.visibleReplies` 是全域來源回合預設值；`messages.groupChat.visibleReplies` 會針對群組/頻道來源回合覆寫它。當 `messages.visibleReplies` 未設定時，harness 可以提供自己的直接/來源預設值；Codex harness 預設為 `message_tool`。頻道允許清單和提及閘控仍會決定是否處理某個回合。
#### 私訊歷史記錄限制
#### DM 歷史限制
```json5
{
@ -820,13 +823,13 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署
}
```
解析順序：依私訊覆寫 → provider 預設值 → 無限制（全部保留）。
解析順序：依 DM 覆寫 → 提供者預設值 → 無限制（全部保留）。
支援：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。
#### 自我聊天模式
在 `allowFrom` 中包含你自己的號碼，即可啟用自我聊天模式（忽略原生 @-提及，只回應文字模式）：
在 `allowFrom` 中加入你自己的號碼以啟用自我聊天模式（忽略原生 @-提及，只回應文字模式）：
```json5
{
@ -847,7 +850,7 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署
}
```
### 指令（聊天指令處理）
### 命令（聊天命令處理）
```json5
{
@ -874,34 +877,34 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署
}
```
<Accordion title="指令詳細資訊">
<Accordion title="命令詳細資料">
- 此區塊會設定指令介面。若要查看目前內建 + 隨附的指令目錄，請參閱[斜線指令](/zh-TW/tools/slash-commands)。
- 此頁是**設定鍵參考**，不是完整指令目錄。頻道/Plugin 擁有的指令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、裝置配對 `/pair`、記憶體 `/dreaming`、電話控制 `/phone`，以及 Talk `/voice`，會在其頻道/Plugin 頁面與[斜線指令](/zh-TW/tools/slash-commands)中記錄。
- 文字指令必須是帶有前導 `/` 的**獨立**訊息。
- `native: "auto"` 會為 Discord/Telegram 開啟原生指令，並讓 Slack 維持關閉。
- `nativeSkills: "auto"` 會為 Discord/Telegram 開啟原生 Skills 指令，並讓 Slack 維持關閉。
- 依頻道覆寫：`channels.discord.commands.native`（bool 或 `"auto"`）。對 Discord 而言，`false` 會在啟動期間略過原生指令註冊與清理。
- 使用 `channels.<provider>.commands.nativeSkills` 依頻道覆寫原生 Skills 註冊。
- `channels.telegram.customCommands` 會加入額外 Telegram 機器人選單項目。
- 這個區塊會設定命令介面。若要查看目前內建 + 隨附的命令目錄，請參閱 [斜線命令](/zh-TW/tools/slash-commands)。
- 本頁是**設定鍵參考**，不是完整命令目錄。頻道/Plugin 擁有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、裝置配對 `/pair`、記憶 `/dreaming`、電話控制 `/phone` 和 Talk `/voice`，會記錄在其頻道/Plugin 頁面以及 [斜線命令](/zh-TW/tools/slash-commands)。
- 文字命令必須是以 `/` 開頭的**獨立**訊息。
- `native: "auto"` 會為 Discord/Telegram 開啟原生命令，並讓 Slack 維持關閉。
- `nativeSkills: "auto"` 會為 Discord/Telegram 開啟原生 skill 命令，並讓 Slack 維持關閉。
- 依頻道覆寫：`channels.discord.commands.native`（布林值或 `"auto"`）。對於 Discord，`false` 會在啟動期間略過原生命令註冊與清理。
- 使用 `channels.<provider>.commands.nativeSkills` 依頻道覆寫原生 skill 註冊。
- `channels.telegram.customCommands` 會加入額外的 Telegram Bot 選單項目。
- `bash: true` 會為主機 shell 啟用 `! <cmd>`。需要 `tools.elevated.enabled`，且傳送者必須在 `tools.elevated.allowFrom.<channel>` 中。
- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 Gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入還需要 `operator.admin`；唯讀 `/config show` 仍可供一般寫入範圍的 operator 用戶端使用。
- `mcp: true` 會為 `mcp.servers` 底下的 OpenClaw 代管 MCP 伺服器設定啟用 `/mcp`。
- `plugins: true` 會為 Plugin 探索、安裝與啟用/停用控制啟用 `/plugins`。
- `channels.<provider>.configWrites` 會依頻道管控設定變更（預設值：true）。
- 對於多帳號頻道，`channels.<provider>.accounts.<id>.configWrites` 也會管控以該帳號為目標的寫入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 會停用 `/restart` 與 Gateway 重新啟動工具動作。預設值：`true`。
- `ownerAllowFrom` 是僅限擁有者指令/工具的明確擁有者允許清單。它與 `allowFrom` 分開。
- `config: true` 會啟用 `/config`（讀取/寫入 `openclaw.json`）。對於 gateway `chat.send` 用戶端，持久性 `/config set|unset` 寫入也需要 `operator.admin`；唯讀 `/config show` 仍可供一般寫入範圍的 operator 用戶端使用。
- `mcp: true` 會為 `mcp.servers` 下由 OpenClaw 管理的 MCP 伺服器設定啟用 `/mcp`。
- `plugins: true` 會為 Plugin 探索、安裝，以及啟用/停用控制項啟用 `/plugins`。
- `channels.<provider>.configWrites` 會依頻道閘控設定變更（預設：true）。
- 對於多帳號頻道，`channels.<provider>.accounts.<id>.configWrites` 也會閘控以該帳號為目標的寫入（例如 `/allowlist --config --account <id>` 或 `/config set channels.<provider>.accounts.<id>...`）。
- `restart: false` 會停用 `/restart` 和 Gateway 重新啟動工具動作。預設：`true`。
- `ownerAllowFrom` 是 owner-only 命令/工具的明確擁有者允許清單。它與 `allowFrom` 分開。
- `ownerDisplay: "hash"` 會在系統提示中雜湊擁有者 ID。設定 `ownerDisplaySecret` 可控制雜湊。
- `allowFrom` 是依 provider 設定。設定後，它會是**唯一**授權來源（頻道允許清單/配對與 `useAccessGroups` 會被忽略）。
- `useAccessGroups: false` 允許指令在未設定 `allowFrom` 時略過存取群組政策。
- 指令文件對照：
- 內建 + 隨附目錄：[斜線指令](/zh-TW/tools/slash-commands)
- 頻道專屬指令介面：[頻道](/zh-TW/channels)
- QQ Bot 指令：[QQ Bot](/zh-TW/channels/qqbot)
- 配對指令：[配對](/zh-TW/channels/pairing)
- LINE 卡片指令：[LINE](/zh-TW/channels/line)
- 記憶體 Dreaming：[Dreaming](/zh-TW/concepts/dreaming)
- `allowFrom` 是依提供者設定。設定後，它就是**唯一**授權來源（頻道允許清單/配對和 `useAccessGroups` 都會被忽略）。
- 當未設定 `allowFrom` 時，`useAccessGroups: false` 允許命令繞過存取群組政策。
- 命令文件對照：
- 內建 + 隨附目錄：[斜線命令](/zh-TW/tools/slash-commands)
- 頻道特定命令介面：[頻道](/zh-TW/channels)
- QQ Bot 命令：[QQ Bot](/zh-TW/channels/qqbot)
- 配對命令：[配對](/zh-TW/channels/pairing)
- LINE 卡片命令：[LINE](/zh-TW/channels/line)
- 記憶 Dreaming：[Dreaming](/zh-TW/concepts/dreaming)
</Accordion>
@ -911,4 +914,4 @@ Gateway 會在檔案儲存後熱重新載入 `messages` 設定。只有在部署
- [設定參考](/zh-TW/gateway/configuration-reference) — 頂層鍵
- [設定 — agents](/zh-TW/gateway/config-agents)
- [頻道概覽](/zh-TW/channels)
- [頻道概觀](/zh-TW/channels)

45
docs/zh-TW/gateway/configuration-examples.md
View File

@ -3,18 +3,18 @@ read_when:
- 了解如何設定 OpenClaw
- 正在尋找設定範例
- 首次設定 OpenClaw
summary: 符合結構描述的常見 OpenClaw 設定範例
summary: 常見 OpenClaw 設定的符合結構描述的設定範例
title: 設定範例
x-i18n:
generated_at: "2026-04-30T03:05:00Z"
generated_at: "2026-05-04T02:44:16Z"
model: gpt-5.5
provider: openai
source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba
source_hash: 60c8c2d731f8dce93c4d14657041d72043bc36e3d71ab6cb13c02993ba90dbe3
source_path: gateway/configuration-examples.md
workflow: 16
---
以下範例與目前的設定結構描述一致。完整參考與各欄位備註，請參閱 [設定](/zh-TW/gateway/configuration)。
範例如下，與目前的設定結構描述一致。如需完整參考與各欄位註記，請參閱[設定](/zh-TW/gateway/configuration)。
## 快速開始
@ -27,7 +27,7 @@ x-i18n:
}
```
儲存到 `~/.openclaw/openclaw.json`，你就能從該號碼私訊 bot。
儲存到 `~/.openclaw/openclaw.json` 後，你就可以從該號碼私訊機器人。
### 建議的起始設定
@ -59,7 +59,7 @@ x-i18n:
## 展開範例（主要選項）
> JSON5 允許你使用註解與尾隨逗號。一般 JSON 也可以使用。
> JSON5 可讓你使用註解和尾隨逗號。一般 JSON 也可以使用。
```json5
{
@ -256,6 +256,7 @@ x-i18n:
skills: ["github", "weather"], // inherited by agents that omit list[].skills
thinkingDefault: "low",
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
blockStreamingDefault: "off",
@ -472,7 +473,7 @@ x-i18n:
## 常見模式
### 具有一項覆寫的共用 skill 基準
### 共用技能基準搭配一個覆寫
```json5
{
@ -490,8 +491,8 @@ x-i18n:
```
- `agents.defaults.skills` 是共用基準。
- `agents.list[].skills` 會替換單一代理程式的該基準。
- 當代理程式不應看到任何 Skills 時，請使用 `skills: []`。
- `agents.list[].skills` 會為單一代理取代該基準。
- 當代理不應看到任何 Skills 時，請使用 `skills: []`。
### 多平台設定
@ -514,9 +515,9 @@ x-i18n:
}
```
### 受信任 Node 網路自動核准
### 受信任的 Node 網路自動核准
除非你能控制網路路徑，否則請維持手動裝置配對。若是專用實驗室或 tailnet 子網路，你可以選擇使用精確的 CIDR 或 IP，啟用首次 Node 裝置自動核准：
除非你控制網路路徑，否則請保持裝置配對為手動。對於專用實驗室或 tailnet 子網路，你可以選擇使用精確的 CIDR 或 IP 啟用首次 Node 裝置自動核准：
```json5
{
@ -530,11 +531,11 @@ x-i18n:
}
```
未設定時，這會保持關閉。它只適用於沒有要求範圍的新 `role: node` 配對。Operator/瀏覽器用戶端，以及角色、範圍、中繼資料或公開金鑰升級，仍然需要手動核准。
未設定時，此功能會保持關閉。它只適用於沒有要求任何範圍的全新 `role: node` 配對。操作者/瀏覽器用戶端，以及角色、範圍、中繼資料或公開金鑰升級，仍需要手動核准。
### 安全 DM 模式（共用收件匣 / 多使用者 DM）
如果有超過一個人可以傳 DM 給你的機器人（`allowFrom` 中有多個項目、多人的配對核准，或 `dmPolicy: "open"`），請啟用**安全 DM 模式**，讓不同寄件者的 DM 預設不會共用同一個上下文：
如果有超過一個人可以 DM 你的 bot（`allowFrom` 中有多個項目、核准多人的配對，或 `dmPolicy: "open"`），請啟用 **安全 DM 模式**，讓不同寄件者的 DM 預設不會共用同一個上下文：
```json5
{
@ -558,10 +559,10 @@ x-i18n:
}
```
對於 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，寄件者授權預設優先使用 ID。
只有在你明確接受該風險時，才可使用各頻道的 `dangerouslyAllowNameMatching: true` 啟用直接可變名稱/電子郵件/nick 比對。
對於 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，寄件者授權預設以 ID 優先。
只有在你明確接受該風險時，才為各頻道啟用透過 `dangerouslyAllowNameMatching: true` 進行直接可變的名稱/email/nick 比對。
### Anthropic API 金鑰 + MiniMax 備援
### Anthropic API 金鑰 + MiniMax 後備
```json5
{
@ -595,7 +596,7 @@ x-i18n:
}
```
### 工作機器人（受限存取）
### 工作 bot（受限制存取）
```json5
{
@ -620,7 +621,7 @@ x-i18n:
}
```
### 僅限本機模型
### 僅使用本機模型
```json5
{
@ -655,11 +656,11 @@ x-i18n:
## 提示
- 如果你設定 `dmPolicy: "open"`，對應的 `allowFrom` 清單必須包含 `"*"`。
- 供應商 ID 各不相同（電話號碼、使用者 ID、頻道 ID）。請使用供應商文件確認格式。
- 提供者 ID 會有所不同（電話號碼、使用者 ID、頻道 ID）。請使用提供者文件確認格式。
- 稍後可新增的選用區段：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
- 如需更深入的設定說明，請參閱[供應商](/zh-TW/providers)和[疑難排解](/zh-TW/gateway/troubleshooting)。
- 請參閱[提供者](/zh-TW/providers)與[疑難排解](/zh-TW/gateway/troubleshooting)，了解更深入的設定說明。
## 相關
- [設定參考](/zh-TW/gateway/configuration-reference)
- [設定](/zh-TW/gateway/configuration)
- [組態參考](/zh-TW/gateway/configuration-reference)
- [組態](/zh-TW/gateway/configuration)

228
docs/zh-TW/gateway/opentelemetry.md
View File

@ -1,36 +1,33 @@
---
read_when:
- 您想將 OpenClaw 模型使用量、訊息流程或工作階段指標傳送到 OpenTelemetry 收集器
- 您想要將 OpenClaw 模型使用情況、訊息流程或工作階段指標傳送至 OpenTelemetry 收集器
- 你正在將追蹤、指標或日誌接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 後端
- 若要建立儀表板或警示，你需要確切的指標名稱、追蹤區段名稱或屬性結構
summary: 透過 diagnostics-otel Plugin (OTLP/HTTP)，將 OpenClaw 診斷資料匯出至任何 OpenTelemetry 收集器
- 您需要確切的指標名稱、span 名稱或屬性結構，才能建立儀表板或警示
summary: 透過 diagnostics-otel Plugin（OTLP/HTTP）將 OpenClaw 診斷資料匯出到任何 OpenTelemetry 收集器
title: OpenTelemetry 匯出
x-i18n:
generated_at: "2026-05-03T21:33:55Z"
generated_at: "2026-05-04T02:44:21Z"
model: gpt-5.5
provider: openai
source_hash: c8091aa633a3e10593681f94913a858587a5dc69d9947e0c0d4132f6e897b00b
source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f
source_path: gateway/opentelemetry.md
workflow: 16
---
OpenClaw 透過官方 `diagnostics-otel` Plugin 匯出診斷資料
使用 **OTLP/HTTP (protobuf)**。任何接受 OTLP/HTTP 的 collector 或後端
都可不需變更程式碼直接運作。若要了解本機檔案記錄以及如何閱讀，請參閱
OpenClaw 透過官方 `diagnostics-otel` Plugin
使用 **OTLP/HTTP (protobuf)** 匯出診斷資料。任何接受 OTLP/HTTP
的收集器或後端都能在不修改程式碼的情況下運作。如需本機檔案記錄及其讀取方式，請參閱
[記錄](/zh-TW/logging)。
## 運作方式
## 整體如何搭配運作
- **診斷事件** 是由
Gateway 和隨附 Plugin 針對模型執行、訊息流程、工作階段、佇列
和 exec 發出的結構化處理程序內記錄。
- **`diagnostics-otel` Plugin** 會訂閱這些事件，並透過 OTLP/HTTP 將其匯出為
- **診斷事件** 是由 Gateway 和內建 Plugin 在程序內發出的結構化記錄，
用於模型執行、訊息流程、工作階段、佇列和 exec。
- **`diagnostics-otel` Plugin** 會訂閱這些事件，並透過 OTLP/HTTP 將它們匯出為
OpenTelemetry **指標**、**追蹤** 和 **記錄**。
- **提供者呼叫** 會在提供者傳輸接受自訂標頭時，從 OpenClaw 的
受信任模型呼叫 span 內容接收 W3C `traceparent` 標頭。
Plugin 發出的追蹤內容不會被傳播。
- 只有在診斷介面和 Plugin
都啟用時，匯出器才會附加，因此預設的處理程序內成本接近於零。
- 當提供者傳輸接受自訂標頭時，**提供者呼叫** 會從 OpenClaw
受信任的模型呼叫 span 情境收到 W3C `traceparent` 標頭。Plugin 發出的追蹤情境不會被傳播。
- 匯出器只會在診斷介面與 Plugin 都啟用時附加，因此程序內成本預設會維持接近零。
## 快速開始
@ -72,18 +69,19 @@ openclaw plugins enable diagnostics-otel
```
<Note>
`protocol` 目前僅支援 `http/protobuf`。`grpc` 會被忽略。
`protocol` 目前只支援 `http/protobuf`。`grpc` 會被忽略。
</Note>
## 匯出的訊號
| 訊號 | 內容 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **指標** | 權杖使用量、成本、執行時間、訊息流程、佇列通道、工作階段狀態、exec 和記憶體壓力的計數器與直方圖。 |
| **追蹤** | 模型使用量、模型呼叫、harness 生命週期、工具執行、exec、Webhook/訊息處理、內容組裝和工具迴圈的 span。 |
| **指標** | token 用量、成本、執行期間、訊息流程、佇列通道、工作階段狀態、exec 和記憶體壓力的計數器與直方圖。 |
| **追蹤** | 模型用量、模型呼叫、harness 生命週期、工具執行、exec、webhook/訊息處理、情境組裝，以及工具迴圈的 span。 |
| **記錄** | 啟用 `diagnostics.otel.logs` 時，透過 OTLP 匯出的結構化 `logging.file` 記錄。 |
可獨立切換 `traces`、`metrics` 和 `logs`。當 `diagnostics.otel.enabled` 為 true 時，三者預設全部開啟。
可分別切換 `traces`、`metrics` 和 `logs`。當
`diagnostics.otel.enabled` 為 true 時，三者預設都會開啟。
## 設定參考
@ -120,118 +118,118 @@ openclaw plugins enable diagnostics-otel
### 環境變數
| 變數 | 用途 |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆寫 `diagnostics.otel.endpoint`。如果值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，則會照原樣使用。 |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 當相符的 `diagnostics.otel.*Endpoint` 設定鍵未設定時使用的訊號專屬端點覆寫。訊號專屬設定優先於訊號專屬 env，而訊號專屬 env 又優先於共用端點。 |
| `OTEL_SERVICE_NAME` | 覆寫 `diagnostics.otel.serviceName`。 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆寫線路通訊協定（目前僅採用 `http/protobuf`）。 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 設為 `gen_ai_latest_experimental`，即可發出最新實驗性 GenAI span 屬性 (`gen_ai.provider.name`)，而不是舊版 `gen_ai.system`。GenAI 指標一律使用有界、低基數的語意屬性。 |
| `OPENCLAW_OTEL_PRELOADED` | 當另一個 preload 或主機處理程序已註冊全域 OpenTelemetry SDK 時設為 `1`。Plugin 接著會略過自己的 NodeSDK 生命週期，但仍會連接診斷監聽器並遵循 `traces`/`metrics`/`logs`。 |
| 變數 | 用途 |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆寫 `diagnostics.otel.endpoint`。如果值已經包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，會依原樣使用。 |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 在對應的 `diagnostics.otel.*Endpoint` 設定鍵未設定時使用的特定訊號端點覆寫。特定訊號設定優先於特定訊號環境變數，而特定訊號環境變數優先於共用端點。 |
| `OTEL_SERVICE_NAME` | 覆寫 `diagnostics.otel.serviceName`。 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆寫線路協定（目前只採用 `http/protobuf`）。 |
| `OTEL_SEMCONV_STABILITY_OPT_IN` | 設為 `gen_ai_latest_experimental`，即可發出最新的實驗性 GenAI span 屬性 (`gen_ai.provider.name`)，而不是舊版 `gen_ai.system`。無論如何，GenAI 指標一律使用有界且低基數的語意屬性。 |
| `OPENCLAW_OTEL_PRELOADED` | 當另一個 preload 或主機程序已註冊全域 OpenTelemetry SDK 時設為 `1`。Plugin 接著會略過自己的 NodeSDK 生命週期，但仍會接線診斷監聽器，並遵守 `traces`/`metrics`/`logs`。 |
## 隱私與內容擷取
原始模型/工具內容預設**不會**匯出。Span 只攜帶有界的
識別符（channel、provider、model、error category、僅雜湊的 request ids），
原始模型/工具內容預設**不會**匯出。Span 只攜帶有界識別符
（通道、提供者、模型、錯誤類別、僅雜湊的請求 ID），
且絕不包含提示文字、回應文字、工具輸入、工具輸出或
工作階段金鑰。
傳出的模型請求可能包含 W3C `traceparent` 標頭。該標頭只會
從 OpenClaw 擁有的診斷追蹤內容針對作用中的模型
呼叫產生。既有由呼叫端提供的 `traceparent` 標頭會被取代，因此 Plugin 或
從作用中模型呼叫的 OpenClaw 所有診斷追蹤情境產生。
既有由呼叫端提供的 `traceparent` 標頭會被取代，因此 Plugin 或
自訂提供者選項無法偽造跨服務追蹤祖先關係。
只有當你的 collector 和
保留政策已核准可處理提示、回應、工具或系統提示
文字時，才將 `diagnostics.otel.captureContent.*` 設為 `true`。每個子鍵都可獨立選擇啟用：
只有在你的收集器與保留政策已核准可存放提示、回應、工具或系統提示
文字時，才將 `diagnostics.otel.captureContent.*` 設為 `true`。
每個子鍵都可獨立選擇啟用：
- `inputMessages` — 使用者提示內容。
- `outputMessages` — 模型回應內容。
- `toolInputs` — 工具引數酬載。
- `toolOutputs` — 工具結果酬載。
- `toolInputs` — 工具引數承載。
- `toolOutputs` — 工具結果承載。
- `systemPrompt` — 組裝後的系統/開發者提示。
當任何子鍵啟用時，模型和工具 span 只會針對該類別取得有界、已遮蔽的
啟用任何子鍵時，模型與工具 span 只會針對該類別取得有界且經過遮蔽的
`openclaw.content.*` 屬性。
## 取樣與清除
## 取樣與排清
- **追蹤：** `diagnostics.otel.sampleRate`（僅 root-span，`0.0` 丟棄全部，
- **追蹤：** `diagnostics.otel.sampleRate`（僅 root span，`0.0` 丟棄全部，
`1.0` 保留全部）。
- **指標：** `diagnostics.otel.flushIntervalMs`（最低 `1000`）。
- **記錄：** OTLP 記錄會遵循 `logging.level`（檔案記錄層級）。它們使用
診斷記錄項目的遮蔽路徑，而非主控台格式化。高流量
安裝應優先使用 OTLP collector 取樣/篩選，而不是本機取樣。
- **檔案記錄關聯：** 當記錄呼叫攜帶有效的
診斷追蹤內容時，JSONL 檔案記錄會包含頂層 `traceId`、
`spanId`、`parentSpanId` 和 `traceFlags`，讓記錄處理器能將本機記錄行與
匯出的 span 關聯。
- **請求關聯：** Gateway HTTP 請求和 WebSocket 訊框會建立
內部請求追蹤範圍。該範圍內的記錄和診斷事件
預設會繼承請求追蹤，而代理程式執行和模型呼叫 span 會
建立為子項，因此提供者 `traceparent` 標頭會留在同一個追蹤上。
診斷記錄資料的遮蔽路徑，而不是主控台格式化。高流量
安裝應優先使用 OTLP 收集器取樣/篩選，而不是本機取樣。
- **檔案記錄關聯：** 當記錄呼叫帶有有效的診斷追蹤情境時，JSONL 檔案記錄會包含頂層
`traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，讓記錄處理器能將本機記錄行與
匯出的 span 串接。
- **請求關聯：** Gateway HTTP 請求與 WebSocket frame 會建立
內部請求追蹤範圍。該範圍內的記錄與診斷事件
預設會繼承請求追蹤，而代理執行與模型呼叫 span 則會
作為子項建立，因此提供者 `traceparent` 標頭會留在同一條追蹤上。
## 匯出的指標
### 模型使用量
### 模型用量
- `openclaw.tokens`（計數器，attrs：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`）
- `openclaw.cost.usd`（計數器，attrs：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `openclaw.run.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `openclaw.context.tokens`（直方圖，attrs：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `gen_ai.client.token.usage`（直方圖，GenAI 語意慣例指標，attrs：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`）
- `gen_ai.client.operation.duration`（直方圖，秒，GenAI 語意慣例指標，attrs：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`、選用 `error.type`）
- `openclaw.model_call.duration_ms`（直方圖，attrs：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分類錯誤上的 `openclaw.errorCategory` 和 `openclaw.failureKind`）
- `openclaw.model_call.request_bytes`（直方圖，最終模型請求酬載的 UTF-8 位元組大小；不含原始酬載內容）
- `openclaw.tokens`（計數器，屬性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`、`openclaw.agent`）
- `openclaw.cost.usd`（計數器，屬性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `openclaw.run.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `openclaw.context.tokens`（直方圖，屬性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`）
- `gen_ai.client.token.usage`（直方圖，GenAI 語意慣例指標，屬性：`gen_ai.token.type` = `input`/`output`、`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`）
- `gen_ai.client.operation.duration`（直方圖，秒，GenAI 語意慣例指標，屬性：`gen_ai.provider.name`、`gen_ai.operation.name`、`gen_ai.request.model`，選用 `error.type`）
- `openclaw.model_call.duration_ms`（直方圖，屬性：`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`，以及分類錯誤上的 `openclaw.errorCategory` 和 `openclaw.failureKind`）
- `openclaw.model_call.request_bytes`（直方圖，最終模型請求承載的 UTF-8 位元組大小；不含原始承載內容）
- `openclaw.model_call.response_bytes`（直方圖，串流模型回應事件的 UTF-8 位元組大小；不含原始回應內容）
- `openclaw.model_call.time_to_first_byte_ms`（直方圖，第一個串流回應事件前的經過時間）
- `openclaw.model_call.time_to_first_byte_ms`（直方圖，第一個串流回應事件前經過的時間）
### 訊息流程
- `openclaw.webhook.received`（計數器，attrs：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.webhook.error`（計數器，attrs：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.webhook.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.message.queued`（計數器，attrs：`openclaw.channel`、`openclaw.source`）
- `openclaw.message.processed`（計數器，attrs：`openclaw.channel`、`openclaw.outcome`）
- `openclaw.message.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.outcome`）
- `openclaw.message.delivery.started`（計數器，attrs：`openclaw.channel`、`openclaw.delivery.kind`）
- `openclaw.message.delivery.duration_ms`（直方圖，attrs：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`）
- `openclaw.webhook.received`（計數器，屬性：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.webhook.error`（計數器，屬性：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.webhook.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.webhook`）
- `openclaw.message.queued`（計數器，屬性：`openclaw.channel`、`openclaw.source`）
- `openclaw.message.processed`（計數器，屬性：`openclaw.channel`、`openclaw.outcome`）
- `openclaw.message.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.outcome`）
- `openclaw.message.delivery.started`（計數器，屬性：`openclaw.channel`、`openclaw.delivery.kind`）
- `openclaw.message.delivery.duration_ms`（直方圖，屬性：`openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`）
### 佇列與工作階段
- `openclaw.queue.lane.enqueue`（計數器，attrs：`openclaw.lane`）
- `openclaw.queue.lane.dequeue`（計數器，attrs：`openclaw.lane`）
- `openclaw.queue.depth`（直方圖，attrs：`openclaw.lane` 或 `openclaw.channel=heartbeat`）
- `openclaw.queue.wait_ms`（直方圖，attrs：`openclaw.lane`）
- `openclaw.session.state`（計數器，attrs：`openclaw.state`、`openclaw.reason`）
- `openclaw.session.stuck`（計數器，attrs：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出）
- `openclaw.session.stuck_age_ms`（直方圖，attrs：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出）
- `openclaw.run.attempt`（計數器，attrs：`openclaw.attempt`）
- `openclaw.queue.lane.enqueue`（計數器，屬性：`openclaw.lane`）
- `openclaw.queue.lane.dequeue`（計數器，屬性：`openclaw.lane`）
- `openclaw.queue.depth`（直方圖，屬性：`openclaw.lane` 或 `openclaw.channel=heartbeat`）
- `openclaw.queue.wait_ms`（直方圖，屬性：`openclaw.lane`）
- `openclaw.session.state`（計數器，屬性：`openclaw.state`、`openclaw.reason`）
- `openclaw.session.stuck`（計數器，屬性：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出）
- `openclaw.session.stuck_age_ms`（直方圖，屬性：`openclaw.state`；僅針對沒有作用中工作的過期工作階段簿記發出）
- `openclaw.run.attempt`（計數器，屬性：`openclaw.attempt`）
### 工作階段活性遙測
### 工作階段存活遙測
`diagnostics.stuckSessionWarnMs` 是工作階段
活性診斷的無進度時間閾值。當 OpenClaw 觀察到回覆、工具、狀態、區塊或 ACP 執行階段進度時，`processing` 工作階段不會朝此閾值累積時間。
Typing keepalive 不會計為進度，因此仍可偵測
靜默的模型或 harness。
`diagnostics.stuckSessionWarnMs` 是工作階段存活診斷的無進度時間閾值。
當 OpenClaw 觀察到回覆、工具、狀態、區塊或 ACP runtime 進度時，
`processing` 工作階段不會朝此閾值累積時間。
輸入狀態 keepalive 不會算作進度，因此靜默的模型或 harness
仍可被偵測到。
OpenClaw 會依其仍可觀察到的工作來分類工作階段：
OpenClaw 會依它仍可觀察到的工作分類工作階段：
- `session.long_running`：作用中的嵌入式工作、模型呼叫或工具呼叫仍在推進。
- `session.stalled`：存在作用中工作，但作用中的執行尚未回報近期進度。停滯的嵌入式執行一開始維持僅觀察，然後在至少 10 分鐘且達到 5 倍 `diagnostics.stuckSessionWarnMs` 仍無進度後進入中止並清空，讓該通道後方排隊的回合可以繼續。
- `session.stuck`：沒有作用中工作的過時工作階段簿記。這會立即釋放受影響的工作階段通道。
- `session.long_running`：作用中的嵌入式工作、模型呼叫或工具呼叫仍在進行。
- `session.stalled`：存在作用中的工作，但作用中的執行最近未回報進度。停滯的嵌入式執行一開始會維持僅觀察，接著在至少 10 分鐘且達到 5 倍 `diagnostics.stuckSessionWarnMs` 仍無進度後中止並清空，讓該通道後方排隊的回合可以恢復。
- `session.stuck`：沒有作用中工作的過期工作階段記帳。這會立即釋放受影響的工作階段通道。
只有 `session.stuck` 會發出 `openclaw.session.stuck` 計數器、`openclaw.session.stuck_age_ms` 直方圖，以及 `openclaw.session.stuck` span。重複的 `session.stuck` 診斷會在工作階段維持不變時退避，因此儀表板應針對持續增加發出警示，而不是對每個 Heartbeat tick 發出警示。關於設定旋鈕與預設值，請參閱[設定參考](/zh-TW/gateway/configuration-reference#diagnostics)。
只有 `session.stuck` 會發出 `openclaw.session.stuck` 計數器、`openclaw.session.stuck_age_ms` 直方圖，以及 `openclaw.session.stuck` span。重複的 `session.stuck` 診斷會在工作階段保持不變時退避，因此儀表板應針對持續增加發出警示，而不是每個 Heartbeat tick 都警示。如需設定旋鈕與預設值，請參閱[設定參考](/zh-TW/gateway/configuration-reference#diagnostics)。
### Harness 生命週期
- `openclaw.harness.duration_ms`（直方圖，屬性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、錯誤時的 `openclaw.harness.phase`）
- `openclaw.harness.duration_ms`（直方圖，屬性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，發生錯誤時包含 `openclaw.harness.phase`）
### Exec
### 執行
- `openclaw.exec.duration_ms`（直方圖，屬性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`）
### 診斷內部（記憶體與工具迴圈）
### 診斷內部機制（記憶體與工具迴圈）
- `openclaw.memory.heap_used_bytes`（直方圖，屬性：`openclaw.memory.kind`）
- `openclaw.memory.rss_bytes`（直方圖）
@ -243,7 +241,7 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段：
- `openclaw.model.usage`
- `openclaw.channel`、`openclaw.provider`、`openclaw.model`
- `openclaw.tokens.*`（input/output/cache_read/cache_write/total）
- `openclaw.tokens.*`（輸入/輸出/快取讀取/快取寫入/總計）
- 預設為 `gen_ai.system`，或在選用最新 GenAI 語意慣例時使用 `gen_ai.provider.name`
- `gen_ai.request.model`、`gen_ai.operation.name`、`gen_ai.usage.*`
- `openclaw.run`
@ -251,43 +249,43 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段：
- `openclaw.model.call`
- 預設為 `gen_ai.system`，或在選用最新 GenAI 語意慣例時使用 `gen_ai.provider.name`
- `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport`
- 錯誤時的 `openclaw.errorCategory` 與選用的 `openclaw.failureKind`
- 發生錯誤時包含 `openclaw.errorCategory` 與選用的 `openclaw.failureKind`
- `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms`
- `openclaw.provider.request_id_hash`（上游提供者請求 ID 的有界 SHA 型雜湊；不會匯出原始 ID）
- `openclaw.harness.run`
- `openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`、`openclaw.provider`、`openclaw.model`、`openclaw.channel`
- 完成時：`openclaw.harness.result_classification`、`openclaw.harness.yield_detected`、`openclaw.harness.items.started`、`openclaw.harness.items.completed`、`openclaw.harness.items.active`
- 錯誤時：`openclaw.harness.phase`、`openclaw.errorCategory`、選用的 `openclaw.harness.cleanup_failed`
- 發生錯誤時：`openclaw.harness.phase`、`openclaw.errorCategory`、選用的 `openclaw.harness.cleanup_failed`
- `openclaw.tool.execution`
- `gen_ai.tool.name`、`openclaw.toolName`、`openclaw.errorCategory`、`openclaw.tool.params.*`
- `openclaw.exec`
- `openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`、`openclaw.exec.command_length`、`openclaw.exec.exit_code`、`openclaw.exec.timed_out`
- `openclaw.webhook.processed`
- `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`
- `openclaw.channel`、`openclaw.webhook`
- `openclaw.webhook.error`
- `openclaw.channel`、`openclaw.webhook`、`openclaw.chatId`、`openclaw.error`
- `openclaw.channel`、`openclaw.webhook`、`openclaw.error`
- `openclaw.message.processed`
- `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、`openclaw.messageId`、`openclaw.reason`
- `openclaw.channel`、`openclaw.outcome`、`openclaw.reason`
- `openclaw.message.delivery`
- `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、`openclaw.errorCategory`、`openclaw.delivery.result_count`
- `openclaw.session.stuck`
- `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth`
- `openclaw.context.assembled`
- `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（沒有提示、歷史、回應或工作階段金鑰內容）
- `openclaw.prompt.size`、`openclaw.history.size`、`openclaw.context.tokens`、`openclaw.errorCategory`（不包含提示、歷史、回應或工作階段金鑰內容）
- `openclaw.tool.loop`
- `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（沒有迴圈訊息、參數或工具輸出）
- `openclaw.toolName`、`openclaw.outcome`、`openclaw.iterations`、`openclaw.errorCategory`（不包含迴圈訊息、參數或工具輸出）
- `openclaw.memory.pressure`
- `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes`
明確啟用內容擷取時，模型與工具 span 也可以包含你已選用之特定內容類別的有界、已遮蔽 `openclaw.content.*` 屬性。
明確啟用內容擷取時，模型與工具 span 也可以包含你選用的特定內容類別之有界且已遮蔽的 `openclaw.content.*` 屬性。
## 診斷事件目錄
下列事件支援上述指標與 span。Plugin 也可以直接訂閱這些事件，而不需 OTLP 匯出。
下列事件支援上述指標與 span。Plugin 也可以直接訂閱這些事件，而不需要 OTLP 匯出。
**模型使用量**
**模型用量**
- `model.usage` — token、成本、持續時間、context、提供者/模型/通道、工作階段 ID。`usage` 是提供者/回合的成本與遙測統計；`context.used` 是目前的提示/context 快照，在涉及快取輸入或工具迴圈呼叫時，可能低於提供者的 `usage.total`。
- `model.usage` — token、成本、持續時間、內容、提供者/模型/頻道、工作階段 ID。`usage` 是用於成本與遙測的提供者/回合計帳；`context.used` 是目前的提示/內容快照，當涉及快取輸入或工具迴圈呼叫時，可能低於提供者的 `usage.total`。
**訊息流程**
@ -304,15 +302,15 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段：
**Harness 生命週期**
- `harness.run.started` / `harness.run.completed` / `harness.run.error` — agent harness 的每次執行生命週期。包含 `harnessId`、選用的 `pluginId`、提供者/模型/通道，以及執行 ID。完成時加入 `durationMs`、`outcome`、選用的 `resultClassification`、`yieldDetected`，以及 `itemLifecycle` 計數。錯誤時加入 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory`，以及選用的 `cleanupFailed`。
- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 代理 harness 的每次執行生命週期。包含 `harnessId`、選用的 `pluginId`、提供者/模型/頻道，以及執行 ID。完成時會新增 `durationMs`、`outcome`、選用的 `resultClassification`、`yieldDetected`，以及 `itemLifecycle` 計數。錯誤會新增 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory`，以及選用的 `cleanupFailed`。
**Exec**
**執行**
- `exec.process.completed` — 終端結果、持續時間、目標、模式、結束碼與失敗種類。不包含命令文字與工作目錄。
## 沒有匯出器時
## 不使用匯出器
你可以讓診斷事件保持可供 Plugin 或自訂 sink 使用，而不執行 `diagnostics-otel`：
你可以不執行 `diagnostics-otel`，仍讓診斷事件可供 Plugin 或自訂接收端使用：
```json5
{
@ -320,7 +318,7 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段：
}
```
若要在不提高 `logging.level` 的情況下取得目標式偵錯輸出，請使用診斷旗標。旗標不區分大小寫，並支援萬用字元（例如 `telegram.*` 或 `*`）：
如需在不提高 `logging.level` 的情況下取得目標式除錯輸出，請使用診斷旗標。旗標不區分大小寫，並支援萬用字元（例如 `telegram.*` 或 `*`）：
```json5
{
@ -328,13 +326,13 @@ OpenClaw 會依其仍可觀察到的工作來分類工作階段：
}
```
或作為一次性的環境變數覆寫：
或作為一次性的環境覆寫：
```bash
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
```
旗標輸出會寫入標準記錄檔（`logging.file`），且仍會由 `logging.redactSensitive` 進行遮蔽。完整指南：[診斷旗標](/zh-TW/diagnostics/flags)。
旗標輸出會寫入標準記錄檔（`logging.file`），且仍會由 `logging.redactSensitive` 遮蔽。完整指南：[診斷旗標](/zh-TW/diagnostics/flags)。
## 停用
@ -344,12 +342,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
}
```
你也可以將 `diagnostics-otel` 從 `plugins.allow` 中移除，或執行 `openclaw plugins disable diagnostics-otel`。
你也可以將 `diagnostics-otel` 排除於 `plugins.allow` 之外，或執行 `openclaw plugins disable diagnostics-otel`。
## 相關
- [記錄](/zh-TW/logging) — 檔案記錄、主控台輸出、CLI tailing，以及 Control UI 記錄分頁
- [Gateway 記錄內部](/zh-TW/gateway/logging) — WS 記錄樣式、子系統前綴與主控台擷取
- [診斷旗標](/zh-TW/diagnostics/flags) — 目標式偵錯記錄旗標
- [診斷匯出](/zh-TW/gateway/diagnostics) — 操作者支援組合工具（與 OTEL 匯出分開）
- [記錄](/zh-TW/logging) — 檔案記錄、主控台輸出、CLI tail，以及 Control UI 記錄分頁
- [Gateway 記錄內部機制](/zh-TW/gateway/logging) — WS 記錄樣式、子系統前綴與主控台擷取
- [診斷旗標](/zh-TW/diagnostics/flags) — 目標式除錯記錄旗標
- [診斷匯出](/zh-TW/gateway/diagnostics) — 操作者支援套件工具（與 OTEL 匯出分開）
- [設定參考](/zh-TW/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 欄位參考

107
docs/zh-TW/gateway/operator-scopes.md
View File

@ -1,25 +1,25 @@
---
read_when:
- 偵錯缺少操作者範圍的錯誤
- 除錯缺少操作員範圍的錯誤
- 檢視裝置或 Node 配對核准
- 新增或分類 Gateway RPC 方法
summary: Gateway 用戶端的操作者角色、範圍與批准時檢查
summary: Gateway 用戶端的操作者角色、範圍與核准時檢查
title: 操作員範圍
x-i18n:
generated_at: "2026-05-03T02:44:26Z"
generated_at: "2026-05-04T02:44:21Z"
model: gpt-5.5
provider: openai
source_hash: 48f59f96b41333af9124ad4083ac5442eedb2d6cebdfff74e3ba256f06d36add
source_hash: f05d6bdbf9bdad2aef1c9664bb7ebb4b6241334b8aefac7993104e9977e40450
source_path: gateway/operator-scopes.md
workflow: 16
---
Operator 範圍定義 Gateway 用戶端在完成驗證後可以執行的操作。
它們是在單一可信任 Gateway 操作者網域內的控制平面防護機制，
不是敵對多租戶隔離。如果你需要在人員、團隊或機器之間建立強隔離，
請在不同 OS 使用者或主機下執行獨立的 Gateways。
Operator 範圍定義 Gateway 用戶端在驗證後可以執行的操作。
它們是一個受信任 Gateway operator 網域內的控制平面防護機制，
不是敵意多租戶隔離。如果你需要在人員、團隊或機器之間建立強隔離，
請在不同的 OS 使用者或主機下執行獨立的 Gateway。
相關：[安全性](/zh-TW/gateway/security)、[Gateway 通訊協定](/zh-TW/gateway/protocol)、
相關：[安全性](/zh-TW/gateway/security)、[Gateway 協定](/zh-TW/gateway/protocol)、
[Gateway 配對](/zh-TW/gateway/pairing)、[裝置 CLI](/zh-TW/cli/devices)。
## 角色
@ -27,73 +27,70 @@ Operator 範圍定義 Gateway 用戶端在完成驗證後可以執行的操作
Gateway WebSocket 用戶端會以一種角色連線：
- `operator`：控制平面用戶端，例如 CLI、Control UI、自動化，以及
可信任的輔助程序。
- `node`：能力主機，例如 macOS、iOS、Android，或透過 `node.invoke`
暴露命令的無頭節點。
受信任的輔助程序。
- `node`：功能主機，例如 macOS、iOS、Android，或透過 `node.invoke`
公開命令的 headless 節點。
Operator RPC 方法需要 `operator` 角色。Node 發起的方法
需要 `node` 角色。
Operator RPC 方法需要 `operator` 角色。源自 Node 的方法需要
`node` 角色。
## 範圍層級
| 範圍 | 意義 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator.read` | 唯讀狀態、清單、目錄、記錄、工作階段讀取，以及其他不會變更狀態的控制平面呼叫。 |
| `operator.write` | 一般會變更狀態的操作者動作，例如傳送訊息、呼叫工具、更新 talk/voice 設定，以及 Node 命令轉送。也滿足 `operator.read`。 |
| `operator.admin` | 管理性的控制平面存取。滿足每個 `operator.*` 範圍。設定變更、更新、原生 hooks、敏感保留命名空間，以及高風險核准都需要此範圍。 |
| `operator.pairing` | 裝置和 Node 配對管理，包括列出、核准、拒絕、移除、輪替與撤銷配對記錄或裝置權杖。 |
| `operator.approvals` | Exec 和 Plugin 核准 API。 |
| `operator.talk.secrets` | 讀取包含密鑰的 Talk 設定。 |
| 範圍 | 含義 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operator.read` | 唯讀狀態、清單、目錄、記錄、工作階段讀取，以及其他不會變更狀態的控制平面呼叫。 |
| `operator.write` | 一般會變更狀態的 operator 動作，例如傳送訊息、叫用工具、更新對話/語音設定，以及 Node 命令轉送。也滿足 `operator.read`。 |
| `operator.admin` | 管理性控制平面存取。滿足每個 `operator.*` 範圍。設定變更、更新、原生 hook、敏感保留命名空間，以及高風險核准都需要此範圍。 |
| `operator.pairing` | 裝置與 Node 配對管理，包括列出、核准、拒絕、移除、輪替，以及撤銷配對記錄或裝置權杖。 |
| `operator.approvals` | Exec 與 Plugin 核准 API。 |
| `operator.talk.secrets` | 讀取包含密鑰的 Talk 設定。 |
未知的未來 `operator.*` 範圍需要完全相符，除非呼叫者具有
未知的未來 `operator.*` 範圍需要精確符合，除非呼叫端具有
`operator.admin`。
## 方法範圍只是第一道關卡
## 方法範圍只是第一道門檻
每個 Gateway RPC 都有最小權限的方法範圍。該方法範圍會決定
請求是否可以到達處理常式。某些處理常式接著會根據實際要核准或變更的具體項目，
每個 Gateway RPC 都有一個最低權限的方法範圍。該方法範圍會決定
請求是否可以到達處理常式。部分處理常式接著會根據實際被核准或變更的項目，
套用更嚴格的核准時檢查。
範例：
- `device.pair.approve` 可透過 `operator.pairing` 存取，但核准
操作者裝置只能發行或保留呼叫者已持有的範圍。
- `node.pair.approve` 可透過 `operator.pairing` 存取，然後會從待處理的
Node 命令清單推導額外核准範圍。
- `device.pair.approve` 可透過 `operator.pairing` 到達，但核准
operator 裝置時，只能鑄造或保留呼叫端已持有的範圍。
- `node.pair.approve` 可透過 `operator.pairing` 到達，接著會從待處理的
Node 命令清單衍生額外的核准範圍。
- `chat.send` 通常是寫入範圍的方法，但持久性的 `/config set`
和 `/config unset` 需要命令層級的 `operator.admin`。
與 `/config unset` 在命令層級需要 `operator.admin`。
這讓較低範圍的操作者可以執行低風險配對動作，而不必讓
所有配對核准都僅限管理員。
這讓較低範圍的 operator 可以執行低風險配對動作，而不必讓所有配對核准都僅限 admin。
## 裝置配對核准
裝置配對記錄是已核准角色與範圍的持久來源。
已配對的裝置不會悄悄取得更廣的存取權：重新連線時若要求
更廣的角色或更廣的範圍，會建立新的待處理升級請求。
已配對的裝置不會默默取得更廣的存取權：如果重新連線時要求更廣的角色或更廣的範圍，
就會建立新的待處理升級請求。
核准裝置請求時：
- 沒有操作者角色的請求不需要操作者權杖範圍核准。
- 對 `operator.read`、`operator.write`、`operator.approvals`、
`operator.pairing` 或 `operator.talk.secrets` 的請求，需要呼叫者持有
- 沒有 operator 角色的請求不需要 operator 權杖範圍核准。
- 要求 `operator.read`、`operator.write`、`operator.approvals`、
`operator.pairing` 或 `operator.talk.secrets` 的請求，需要呼叫端持有
這些範圍或 `operator.admin`。
- 對 `operator.admin` 的請求需要 `operator.admin`。
- 沒有明確範圍的修復請求可以繼承現有的操作者權杖範圍。
如果該現有權杖是管理員範圍，核准仍需要 `operator.admin`。
- 要求 `operator.admin` 的請求需要 `operator.admin`。
- 沒有明確範圍的修復請求可以繼承現有 operator 權杖範圍。如果該現有權杖具有 admin 範圍，
核准仍然需要 `operator.admin`。
對於已配對裝置權杖工作階段，管理預設限於自身範圍，除非呼叫者
也具有 `operator.admin`：非管理員呼叫者只能輪替、撤銷或移除
自己的裝置項目。
對於已配對裝置的權杖工作階段，管理是自我範圍限定的，除非呼叫端也具有
`operator.admin`：非 admin 呼叫端只會看到自己的配對項目，只能核准或拒絕自己的待處理請求，
且只能輪替、撤銷或移除自己的裝置項目。
## Node 配對核准
舊版 `node.pair.*` 使用另一個由 Gateway 擁有的 Node 配對儲存區。WS Node
會使用具有 `role: node` 的裝置配對，但相同的核准層級詞彙
仍然適用。
舊版 `node.pair.*` 使用由 Gateway 擁有的獨立 Node 配對儲存區。WS Node
使用帶有 `role: node` 的裝置配對，但同一組核准層級詞彙仍然適用。
`node.pair.approve` 會使用待處理請求的命令清單推導額外的
必要範圍：
`node.pair.approve` 會使用待處理請求的命令清單來衍生額外的必要範圍：
- 無命令請求：`operator.pairing`
- 非 exec Node 命令：`operator.pairing` + `operator.write`
@ -103,11 +100,11 @@ Operator RPC 方法需要 `operator` 角色。Node 發起的方法
Node 配對會建立身分與信任。它不會取代 Node 自身的
`system.run` exec 核准政策。
## 共用密鑰驗證
## 共享密鑰驗證
共用 Gateway 權杖/密碼驗證會被視為該 Gateway 的可信任操作者存取。
OpenAI 相容的 HTTP 介面和 `/tools/invoke` 會為共用密鑰 bearer 驗證
還原一般完整操作者預設範圍集，即使呼叫者送出較窄的宣告範圍也是如此。
共享 Gateway 權杖/密碼驗證會被視為該 Gateway 的受信任 operator 存取。
OpenAI 相容 HTTP 介面與 `/tools/invoke` 會為共享密鑰 bearer 驗證還原一般完整的
operator 預設範圍集合，即使呼叫端傳送較窄的已宣告範圍也是如此。
帶有身分的模式，例如可信任 Proxy 驗證或私有入口 `none`，
仍可遵循明確宣告的範圍。請使用獨立的 Gateways 來進行真正的信任邊界隔離。
帶有身分的模式，例如受信任 Proxy 驗證或私有入口 `none`，
仍可遵守明確宣告的範圍。請使用獨立的 Gateway 來實現真正的信任邊界隔離。

212
docs/zh-TW/plugins/building-plugins.md
View File

@ -1,35 +1,39 @@
---
read_when:
- 您想建立新的 OpenClaw Plugin
- 您需要一份 Plugin 開發快速入門指南
- 你正在為 OpenClaw 新增通道、提供者、工具或其他功能
- 你想要建立新的 OpenClaw Plugin
- 您需要 Plugin 開發的快速入門指南
- 你正在為 OpenClaw 新增頻道、提供者、工具或其他功能
sidebarTitle: Getting Started
summary: 在幾分鐘內建立你的第一個 OpenClaw Plugin
title: 建構 Plugin
title: 建置 Plugin
x-i18n:
generated_at: "2026-05-02T20:51:43Z"
generated_at: "2026-05-04T02:44:25Z"
model: gpt-5.5
provider: openai
source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1
source_hash: 3e6c55c551629da54b3f150ce6299694186fe4434cfd7978a2d43d175d33a5d9
source_path: plugins/building-plugins.md
workflow: 16
---
Plugin 以新功能擴充 OpenClaw：頻道、模型提供者、語音、即時轉錄、即時語音、媒體理解、圖像生成、影片生成、網頁擷取、網頁搜尋、代理工具，或任意組合。
Plugin 透過新增能力來擴充 OpenClaw：通道、模型提供者、
語音、即時轉錄、即時語音、媒體理解、影像
生成、影片生成、網頁擷取、網頁搜尋、代理工具，或任何
組合。
你不需要將你的 Plugin 加入 OpenClaw 儲存庫。發布到
[ClawHub](/zh-TW/tools/clawhub)，使用者即可透過
`openclaw plugins install clawhub:<package-name>` 安裝。裸套件規格在啟動切換期間仍會從 npm 安裝。
[ClawHub](/zh-TW/tools/clawhub)，使用者可透過
`openclaw plugins install clawhub:<package-name>` 安裝。純套件規格在
啟動切換期間仍會從 npm 安裝。
## 先決條件
- Node >= 22 和套件管理器（npm 或 pnpm）
- Node >= 22 與套件管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 對於儲存庫內 Plugin：已複製儲存庫並完成 `pnpm install`。原始碼
checkout 的 Plugin 開發僅支援 pnpm，因為 OpenClaw 會從 `extensions/*` 工作區套件載入內建
Plugin。
checkout Plugin 開發僅支援 pnpm，因為 OpenClaw 會從 `extensions/*` workspace 套件載入
內建 Plugin。
## 哪一種 Plugin？
## 哪種 Plugin？
<CardGroup cols={3}>
<Card title="Channel plugin" icon="messages-square" href="/zh-TW/plugins/sdk-channel-plugins">
@ -39,21 +43,22 @@ Plugin 以新功能擴充 OpenClaw：頻道、模型提供者、語音、即時
新增模型提供者（LLM、代理或自訂端點）
</Card>
<Card title="Tool / hook plugin" icon="wrench" href="/zh-TW/plugins/hooks">
註冊代理工具、事件 hook 或服務 — 請繼續閱讀下方內容
註冊代理工具、事件掛鉤或服務 — 繼續閱讀下方內容
</Card>
</CardGroup>
對於無法保證在 onboarding/setup 執行時已安裝的頻道 Plugin，請使用
對於在 onboarding/setup 執行時不保證已安裝的通道 Plugin，請使用
`openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。
它會產生一組設定配接器與精靈，宣告安裝需求，並在 Plugin 尚未安裝前，對實際設定寫入採取失敗關閉策略。
它會產生一組 setup adapter + wizard pair，用來宣告安裝需求，並在 Plugin 安裝之前
對實際設定寫入採取封閉式失敗。
## 快速開始：工具 Plugin
本逐步說明會建立一個最小 Plugin，用來註冊代理工具。頻道與提供者
Plugin 有上方連結的專屬指南。
本逐步指南會建立一個最小 Plugin，用來註冊代理工具。通道
與提供者 Plugin 有上方連結的專屬指南。
<Steps>
<Step title="Create the package and manifest">
<Step title="建立套件與 manifest">
<CodeGroup>
```json package.json
{
@ -94,15 +99,15 @@ Plugin 有上方連結的專屬指南。
</CodeGroup>
每個 Plugin 都需要 manifest，即使沒有設定也一樣。執行階段註冊的工具
必須列在 `contracts.tools` 中，讓 OpenClaw 不必載入每個 Plugin 執行階段也能發現擁有它的
必須列在 `contracts.tools` 中，讓 OpenClaw 不必載入每個 Plugin runtime 也能探索擁有它的
Plugin。Plugin 也應有意識地宣告
`activation.onStartup`。這個範例將它設為 `true`。完整 schema 請參閱
`activation.onStartup`。此範例將其設為 `true`。完整 schema 請參閱
[Manifest](/zh-TW/plugins/manifest)。標準 ClawHub
發布片段位於 `docs/snippets/plugin-publish/`。
</Step>
<Step title="Write the entry point">
<Step title="撰寫進入點">
```typescript
// index.ts
@ -126,13 +131,13 @@ Plugin 有上方連結的專屬指南。
});
```
`definePluginEntry` 適用於非頻道 Plugin。對於頻道，請使用
`definePluginEntry` 用於非通道 Plugin。對於通道，請使用
`defineChannelPluginEntry` — 請參閱 [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins)。
完整進入點選項請參閱 [Entry Points](/zh-TW/plugins/sdk-entrypoints)。
完整的進入點選項請參閱 [Entry Points](/zh-TW/plugins/sdk-entrypoints)。
</Step>
<Step title="Test and publish">
<Step title="測試並發布">
**外部 Plugin：** 使用 ClawHub 驗證並發布，然後安裝：
@ -142,10 +147,10 @@ Plugin 有上方連結的專屬指南。
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
像 `@myorg/openclaw-my-plugin` 這樣的裸套件規格會在啟動切換期間從 npm 安裝。
想使用 ClawHub 解析時，請使用 `clawhub:`。
像 `@myorg/openclaw-my-plugin` 這樣的純套件規格會在
啟動切換期間從 npm 安裝。需要 ClawHub 解析時請使用 `clawhub:`。
**儲存庫內 Plugin：** 放在內建 Plugin 工作區樹狀結構下 — 會自動被發現。
**儲存庫內 Plugin：** 放在內建 Plugin workspace 樹下 — 會自動被探索。
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -154,20 +159,20 @@ Plugin 有上方連結的專屬指南。
</Step>
</Steps>
## Plugin 功能
## Plugin 能力
單一 Plugin 可以透過 `api` 物件註冊任意數量的功能：
單一 Plugin 可以透過 `api` 物件註冊任意數量的能力：
| 功能 | 註冊方法 | 詳細指南 |
| 能力 | 註冊方法 | 詳細指南 |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文字推論（LLM） | `api.registerProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) |
| CLI 推論後端 | `api.registerCliBackend(...)` | [CLI Backends](/zh-TW/gateway/cli-backends) |
| 頻道 / 訊息 | `api.registerChannel(...)` | [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) |
| 通道 / 訊息 | `api.registerChannel(...)` | [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) |
| 語音（TTS/STT） | `api.registerSpeechProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 即時轉錄 | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 即時語音 | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒體理解 | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 圖像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 影像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音樂生成 | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 影片生成 | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 網頁擷取 | `api.registerWebFetchProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
@ -175,47 +180,49 @@ Plugin 有上方連結的專屬指南。
| 工具結果 middleware | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api) |
| 代理工具 | `api.registerTool(...)` | 下方 |
| 自訂命令 | `api.registerCommand(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) |
| Plugin hook | `api.on(...)` | [Plugin hooks](/zh-TW/plugins/hooks) |
| 內部事件 hook | `api.registerHook(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) |
| Plugin hooks | `api.on(...)` | [Plugin hooks](/zh-TW/plugins/hooks) |
| 內部事件掛鉤 | `api.registerHook(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) |
| HTTP 路由 | `api.registerHttpRoute(...)` | [Internals](/zh-TW/plugins/architecture-internals#gateway-http-routes) |
| CLI 子命令 | `api.registerCli(...)` | [Entry Points](/zh-TW/plugins/sdk-entrypoints) |
完整註冊 API 請參閱 [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api)。
內建 Plugin 在需要於模型看到輸出前進行非同步工具結果重寫時，可以使用 `api.registerAgentToolResultMiddleware(...)`。
請在 `contracts.agentToolResultMiddleware` 中宣告目標執行階段，例如
`["pi", "codex"]`。這是受信任的內建 Plugin seam；外部
Plugin 應優先使用一般 OpenClaw Plugin hook，除非 OpenClaw 為此功能增加明確的信任政策。
內建 Plugin 在需要於模型看到輸出之前進行非同步工具結果重寫時，
可以使用 `api.registerAgentToolResultMiddleware(...)`。請在
`contracts.agentToolResultMiddleware` 中宣告目標 runtime，例如
`["pi", "codex"]`。這是一個受信任的內建 Plugin seam；外部
Plugin 應優先使用一般 OpenClaw Plugin hooks，除非 OpenClaw 為此能力新增
明確的信任政策。
如果你的 Plugin 註冊自訂 Gateway RPC 方法，請將它們保留在
如果你的 Plugin 註冊自訂 Gateway RPC 方法，請將它們放在
Plugin 專屬前綴下。核心管理命名空間（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）會保持保留，且一律解析為
`operator.admin`，即使 Plugin 要求較窄的 scope 也是如此。
`exec.approvals.*`、`wizard.*`、`update.*`）會保留，且永遠解析為
`operator.admin`，即使 Plugin 要求較窄的 scope 也一樣。
需要記住的 hook guard 語意：
請記住以下 hook guard 語意：
- `before_tool_call`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `before_tool_call`：`{ block: true }` 是終止結果，會停止較低優先序的 handler。
- `before_tool_call`：`{ block: false }` 會被視為沒有決策。
- `before_tool_call`：`{ requireApproval: true }` 會暫停代理執行，並透過 exec 核准覆蓋層、Telegram 按鈕、Discord 互動，或任何頻道上的 `/approve` 命令提示使用者核准。
- `before_install`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `before_tool_call`：`{ requireApproval: true }` 會暫停代理執行，並透過 exec approval overlay、Telegram 按鈕、Discord 互動，或任何通道上的 `/approve` 命令提示使用者核准。
- `before_install`：`{ block: true }` 是終止結果，會停止較低優先序的 handler。
- `before_install`：`{ block: false }` 會被視為沒有決策。
- `message_sending`：`{ cancel: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `message_sending`：`{ cancel: true }` 是終止結果，會停止較低優先序的 handler。
- `message_sending`：`{ cancel: false }` 會被視為沒有決策。
- `message_received`：需要傳入 thread/topic 路由時，請優先使用型別化的 `threadId` 欄位。將 `metadata` 保留給頻道專屬的額外資訊。
- `message_sending`：請優先使用型別化的 `replyToId` / `threadId` 路由欄位，而不是頻道專屬的 metadata key。
- `message_received`：需要傳入 thread/topic routing 時，請優先使用型別化的 `threadId` 欄位。將 `metadata` 保留給通道特定的額外資訊。
- `message_sending`：請優先使用型別化的 `replyToId` / `threadId` routing 欄位，而不是通道特定的 metadata key。
`/approve` 命令會以有界 fallback 處理 exec 與 Plugin 核准：找不到 exec 核准 id 時，OpenClaw 會以相同 id 重試 Plugin 核准。Plugin 核准轉送可透過設定中的 `approvals.plugin` 獨立設定。
`/approve` 命令會以有界 fallback 處理 exec 與 Plugin approval：找不到 exec approval id 時，OpenClaw 會用相同 id 透過 Plugin approval 重試。Plugin approval forwarding 可以透過設定中的 `approvals.plugin` 獨立設定。
如果自訂核准接線需要偵測相同的有界 fallback 情況，
請優先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，
而不是手動比對核准到期字串。
如果自訂 approval plumbing 需要偵測同一個有界 fallback 情況，
請優先使用 `openclaw/plugin-sdk/error-runtime` 的 `isApprovalNotFoundError`，
而不是手動比對 approval 到期字串。
範例與 hook 參考請參閱 [Plugin hooks](/zh-TW/plugins/hooks)。
範例與 hook reference 請參閱 [Plugin hooks](/zh-TW/plugins/hooks)。
## 註冊代理工具
工具是 LLM 可以呼叫的型別化函式。它們可以是必要的（永遠
可用）或選用的（使用者選擇加入）：
工具是 LLM 可以呼叫的型別化函式。它們可以是必要（永遠
可用）或選用（使用者 opt-in）：
```typescript
register(api) {
@ -244,23 +251,31 @@ register(api) {
}
```
每個透過 `api.registerTool(...)` 註冊的工具，也必須在
所有透過 `api.registerTool(...)` 註冊的工具，也必須在
Plugin manifest 中宣告：
```json
{
"contracts": {
"tools": ["my_tool", "workflow_tool"]
},
"toolMetadata": {
"workflow_tool": {
"optional": true
}
}
}
```
OpenClaw 會擷取並快取已註冊工具的已驗證描述子，
因此 Plugin 不需要在 manifest 中重複 `description` 或 schema 資料。
manifest contract 只宣告擁有權與發現；執行仍會呼叫
即時註冊的工具實作。
OpenClaw 會擷取並快取已註冊工具中通過驗證的描述元，
因此 plugins 不需要在 manifest 中重複 `description` 或 schema 資料。這個
manifest 合約只宣告擁有權與探索；執行時仍會呼叫
即時註冊工具的實作。
對於使用 `api.registerTool(..., { optional: true })` 註冊的工具，請設定
`toolMetadata.<tool>.optional: true`，讓 OpenClaw 可以避免載入該
plugin runtime，直到此工具被明確加入允許清單。
使用者可在設定中啟用選用工具：
使用者可在設定中啟用 optional tools：
```json5
{
@ -268,14 +283,16 @@ manifest contract 只宣告擁有權與發現；執行仍會呼叫
}
```
- 工具名稱不得與核心工具衝突（衝突項目會被略過）
- 註冊物件格式錯誤的工具（包括缺少 `parameters`）會被略過，並改在 Plugin 診斷中回報，而不是中斷代理程式執行
- 對於具有副作用或需要額外二進位檔的工具，請使用 `optional: true`
- 使用者可以將 Plugin ID 加到 `tools.allow`，以啟用某個 Plugin 的所有工具
- 工具名稱不得與 core tools 衝突（衝突項目會被略過）
- 含有格式錯誤註冊物件的工具，包括缺少 `parameters`，會被略過並在 plugin diagnostics 中回報，而不是中斷 agent 執行
- 對具有副作用或額外 binary 需求的工具使用 `optional: true`
- 使用者可以將 plugin id 加入 `tools.allow`，以啟用某個 plugin 的所有工具
## 註冊 CLI 指令
Plugin 可以透過 `api.registerCli` 新增根層級 `openclaw` 指令群組。請為每個頂層指令根提供 `descriptors`，讓 OpenClaw 不必急切載入每個 Plugin 執行階段，就能顯示並路由該指令。
Plugins 可以使用 `api.registerCli` 新增 root `openclaw` command groups。請為
每個頂層命令 root 提供 `descriptors`，讓 OpenClaw 可以顯示並路由
該命令，而不必急切載入每個 plugin runtime。
```typescript
register(api) {
@ -305,7 +322,7 @@ register(api) {
}
```
安裝後，驗證執行階段註冊並執行指令：
安裝後，請驗證 runtime 註冊並執行指令：
```bash
openclaw plugins inspect demo-plugin --runtime --json
@ -324,53 +341,58 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { ... } from "openclaw/plugin-sdk";
```
完整子路徑參考請見 [SDK 概覽](/zh-TW/plugins/sdk-overview)。
完整的 subpath 參考請見 [SDK 概覽](/zh-TW/plugins/sdk-overview)。
在你的 Plugin 內，請使用本機 barrel 檔案（`api.ts`、`runtime-api.ts`）進行內部匯入，絕對不要透過其 SDK 路徑匯入自己的 Plugin。
在你的 plugin 中，請使用本機 barrel files（`api.ts`、`runtime-api.ts`）進行
內部匯入，不要透過 SDK 路徑匯入自己的 plugin。
對於提供者 Plugin，請將提供者特定的輔助工具保留在那些套件根層級 barrel 中，除非該接縫確實是通用的。目前的內建範例：
對於 provider plugins，請將 provider-specific helpers 保留在那些 package-root
barrels 中，除非該 seam 確實是通用的。目前 bundled examples：
- Anthropic：Claude 串流包裝器與 `service_tier` / beta 輔助工具
- OpenAI：提供者建構器、預設模型輔助工具、即時提供者
- OpenRouter：提供者建構器加上 onboarding/設定輔助工具
- Anthropic：Claude stream wrappers 與 `service_tier` / beta helpers
- OpenAI：provider builders、default-model helpers、realtime providers
- OpenRouter：provider builder 加上 onboarding/config helpers
如果某個輔助工具只在單一內建提供者套件內有用，請將它保留在該套件根層級接縫上，而不是提升到 `openclaw/plugin-sdk/*`。
如果某個 helper 只在單一 bundled provider package 內有用，請將它保留在該
package-root seam，而不是提升到 `openclaw/plugin-sdk/*`。
部分產生的 `openclaw/plugin-sdk/<bundled-id>` 輔助接縫仍存在，用於有追蹤擁有者使用情況的內建 Plugin 維護。請將這些視為保留介面，而不是新第三方 Plugin 的預設模式。
部分產生的 `openclaw/plugin-sdk/<bundled-id>` helper seams 仍存在，
用於有追蹤擁有者使用情境的 bundled-plugin 維護。請將這些視為
保留介面，而不是新 third-party plugins 的預設模式。
## 提交前檢查清單
<Check>**package.json** 具有正確的 `openclaw` 中繼資料</Check>
<Check>**package.json** 具有正確的 `openclaw` metadata</Check>
<Check>**openclaw.plugin.json** manifest 存在且有效</Check>
<Check>進入點使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
<Check>所有匯入都使用聚焦的 `plugin-sdk/<subpath>` 路徑</Check>
<Check>內部匯入使用本機模組，而非 SDK 自我匯入</Check>
<Check>內部匯入使用本機模組，而不是 SDK self-imports</Check>
<Check>測試通過（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
<Check>`pnpm check` 通過（儲存庫內 Plugin）</Check>
<Check>`pnpm check` 通過（repo 內 plugins）</Check>
## Beta 發布測試
## Beta 版本測試
1. 留意 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 發布標籤，並透過 `Watch` > `Releases` 訂閱。Beta 標籤看起來像 `v2026.3.N-beta.1`。你也可以開啟官方 OpenClaw X 帳號 [@openclaw](https://x.com/openclaw) 的通知，以接收發布公告。
2. Beta 標籤一出現，就立即針對它測試你的 Plugin。穩定版發布前的時間窗口通常只有幾個小時。
3. 測試後，請在 `plugin-forum` Discord 頻道中你的 Plugin 討論串張貼 `all good` 或說明壞掉的內容。如果你還沒有討論串，請建立一個。
4. 如果有東西壞掉，請開啟或更新標題為 `Beta blocker: <plugin-name> - <summary>` 的 issue，並套用 `beta-blocker` 標籤。將 issue 連結放到你的討論串中。
5. 開啟一個指向 `main`、標題為 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，並在 PR 和你的 Discord 討論串中連結該 issue。貢獻者無法替 PR 加標籤，因此標題是給維護者與自動化使用的 PR 端訊號。有 PR 的阻擋問題會被合併；沒有 PR 的阻擋問題仍可能照常發布。維護者會在 beta 測試期間關注這些討論串。
6. 沉默代表綠燈。如果你錯過時間窗口，你的修正很可能會在下一個週期落地。
1. 追蹤 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub release tags，並透過 `Watch` > `Releases` 訂閱。Beta tags 形式像 `v2026.3.N-beta.1`。你也可以開啟官方 OpenClaw X 帳號 [@openclaw](https://x.com/openclaw) 的通知，以接收 release 公告。
2. Beta tag 一出現，請盡快用它測試你的 plugin。進入 stable 前的時間窗口通常只有幾個小時。
3. 測試後，在 `plugin-forum` Discord channel 中你的 plugin thread 發文，內容可為 `all good` 或說明哪裡壞了。如果你還沒有 thread，請建立一個。
4. 如果發生問題，請開啟或更新標題為 `Beta blocker: <plugin-name> - <summary>` 的 issue，並套用 `beta-blocker` label。將 issue link 放到你的 thread 中。
5. 開啟一個指向 `main` 的 PR，標題為 `fix(<plugin-id>): beta blocker - <summary>`，並在 PR 和你的 Discord thread 中連結該 issue。Contributors 無法為 PR 加 label，因此標題是給 maintainers 與 automation 的 PR 端訊號。有 PR 的 blockers 會被合併；沒有 PR 的 blockers 可能仍會照常發布。Maintainers 會在 beta testing 期間關注這些 threads。
6. 沉默表示綠燈。如果你錯過窗口，你的修正很可能會進入下一個 cycle。
## 下一步
<CardGroup cols={2}>
<Card title="Channel Plugins" icon="messages-square" href="/zh-TW/plugins/sdk-channel-plugins">
建置訊息通道 Plugin
<Card title="通道 Plugins" icon="messages-square" href="/zh-TW/plugins/sdk-channel-plugins">
建置 messaging channel plugin
</Card>
<Card title="Provider Plugins" icon="cpu" href="/zh-TW/plugins/sdk-provider-plugins">
建置模型提供者 Plugin
建置 model provider plugin
</Card>
<Card title="SDK 概覽" icon="book-open" href="/zh-TW/plugins/sdk-overview">
匯入對應與註冊 API 參考
Import map 與 registration API 參考
</Card>
<Card title="執行階段輔助工具" icon="settings" href="/zh-TW/plugins/sdk-runtime">
TTS、搜尋、透過 api.runtime 使用 subagent
<Card title="Runtime Helpers" icon="settings" href="/zh-TW/plugins/sdk-runtime">
透過 api.runtime 使用 TTS、search、subagent
</Card>
<Card title="測試" icon="test-tubes" href="/zh-TW/plugins/sdk-testing">
測試工具與模式
@ -384,6 +406,6 @@ import { ... } from "openclaw/plugin-sdk";
- [Plugin 架構](/zh-TW/plugins/architecture) — 內部架構深入解析
- [SDK 概覽](/zh-TW/plugins/sdk-overview) — Plugin SDK 參考
- [Manifest](/zh-TW/plugins/manifest) — Plugin manifest 格式
- [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) — 建置通道 Plugin
- [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) — 建置提供者 Plugin
- [Manifest](/zh-TW/plugins/manifest) — plugin manifest 格式
- [通道 Plugins](/zh-TW/plugins/sdk-channel-plugins) — 建置 channel plugins
- [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) — 建置 provider plugins

762
docs/zh-TW/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

214
docs/zh-TW/plugins/memory-wiki.md
View File

@ -1,103 +1,104 @@
---
read_when:
- 你想要的不只是普通的 MEMORY.md 筆記，而是持久知識
- 你需要超越單純 MEMORY.md 筆記的持久知識
- 你正在設定隨附的 memory-wiki Plugin
- 你想了解 wiki_search、wiki_get 或橋接模式
summary: memory-wiki：含出處、聲明、儀表板和橋接模式的已編譯知識庫
summary: memory-wiki：已編譯的知識庫，包含來源依據、主張、儀表板與橋接模式
title: 記憶維基
x-i18n:
generated_at: "2026-04-30T03:24:21Z"
generated_at: "2026-05-04T02:45:28Z"
model: gpt-5.5
provider: openai
source_hash: 744d569f8b0c9b668ea54dc057f808544359eaae87d5557de2e6acd1b31acd89
source_hash: b070177b7c1217e9102bc57680b4009265e3584ede7ad6dc3ba7b6393260fefe
source_path: plugins/memory-wiki.md
workflow: 16
---
`memory-wiki` 是一個內建 Plugin，會將持久記憶轉換成編譯後的知識庫。
`memory-wiki` 是一個內建 Plugin，會將持久記憶轉換為已編譯的知識庫。
它**不會**取代 Active Memory Plugin。Active Memory Plugin 仍然負責召回、提升、索引與 Dreaming。`memory-wiki` 與它並列運作，並將持久知識編譯成可瀏覽的 wiki，包含確定性頁面、結構化主張、來源、儀表板與機器可讀摘要。
它**不會**取代 Active Memory Plugin。Active Memory Plugin 仍然負責回想、提升、索引與 Dreaming。`memory-wiki` 位於它旁邊，並將持久知識編譯成可導覽的 wiki，包含確定性頁面、結構化主張、來源、儀表板，以及機器可讀的摘要。
當你希望記憶更像是維護良好的知識層，而不是一堆 Markdown 檔案時，就使用它。
當你希望記憶的行為更像維護良好的知識層，而不是一堆 Markdown 檔案時，請使用它。
## 它新增了什麼
- 具有確定性頁面版面的專用 wiki 知識庫
- 結構化主張與證據中繼資料，而不只是散文
- 頁面層級的來源、信心度、矛盾與待解問題
- 供代理程式與執行階段使用者使用的編譯摘要
- wiki 原生搜尋、取得、套用與 lint 工具
- 具備確定性頁面配置的專用 wiki vault
- 結構化的主張與證據中繼資料，而不只是文字敘述
- 頁面層級的來源、信心度、矛盾與開放問題
- 供 agent/runtime 消費者使用的已編譯摘要
- wiki 原生的搜尋/取得/套用/lint 工具
- 可選的橋接模式，可從 Active Memory Plugin 匯入公開成品
- 可選的 Obsidian 友善轉譯模式與 CLI 整合
- 可選的 Obsidian 友善算繪模式與 CLI 整合
## 它如何與記憶配合
## 它如何配合記憶
可以把分工想成這樣：
可以這樣理解分工：
| 層級 | 負責 |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Active Memory Plugin（`memory-core`、QMD、Honcho 等） | 召回、語意搜尋、提升、Dreaming、記憶執行階段 |
| `memory-wiki` | 編譯後的 wiki 頁面、富含來源的綜合內容、儀表板、wiki 專用搜尋、取得與套用 |
| Active Memory Plugin (`memory-core`, QMD, Honcho 等) | 回想、語意搜尋、提升、Dreaming、記憶 runtime |
| `memory-wiki` | 已編譯 wiki 頁面、富含來源的綜合內容、儀表板、wiki 專用搜尋/取得/套用 |
如果 Active Memory Plugin 暴露共享召回成品，OpenClaw 可以使用 `memory_search corpus=all` 在一次流程中搜尋兩個層級。
如果 Active Memory Plugin 暴露共享回想成品，OpenClaw 可以透過 `memory_search corpus=all` 在一次流程中搜尋兩個層級。
當你需要 wiki 專用排序、來源，或直接頁面存取時，請改用 wiki 原生工具。
當你需要 wiki 專用的排序、來源或直接頁面存取時，請改用 wiki 原生工具。
## 建議的混合模式
對於本機優先設定，一個穩健的預設值是：
對 local-first 設定來說，一個穩健的預設是：
- 使用 QMD 作為 Active Memory 後端，用於召回與廣泛語意搜尋
- 以 `bridge` 模式使用 `memory-wiki`，產生持久的綜合知識頁面
- 使用 QMD 作為 Active Memory 後端，用於回想與廣泛語意搜尋
- 使用 `memory-wiki` 的 `bridge` 模式建立持久的綜合知識頁面
這種分工很有效，因為每個層級都能保持專注：
這樣的分工效果很好，因為每個層級都能保持專注：
- QMD 讓原始筆記、工作階段匯出與額外集合保持可搜尋
- `memory-wiki` 編譯穩定實體、主張、儀表板與來源頁面
實用規則：
實務規則：
- 當你想要跨記憶進行一次廣泛召回時，使用 `memory_search`
- 當你想要具備來源感知的 wiki 結果時，使用 `wiki_search` 與 `wiki_get`
- 當你希望共享搜尋涵蓋兩個層級時，使用 `memory_search corpus=all`
- 當你想跨記憶做一次廣泛回想時，使用 `memory_search`
- 當你想取得具備來源感知的 wiki 結果時，使用 `wiki_search` 和 `wiki_get`
- 當你想讓共享搜尋橫跨兩個層級時，使用 `memory_search corpus=all`
如果橋接模式回報匯出的成品為零，表示 Active Memory Plugin 目前尚未暴露公開橋接輸入。請先執行 `openclaw wiki doctor`，然後確認 Active Memory Plugin 支援公開成品。
如果橋接模式回報匯出的成品為零，表示 Active Memory Plugin 目前尚未暴露公開橋接輸入。先執行 `openclaw wiki doctor`，再確認 Active Memory Plugin 支援公開成品。
當橋接模式啟用且 `bridge.readMemoryArtifacts` 已啟用時，`openclaw wiki status`、`openclaw wiki doctor` 與 `openclaw wiki bridge import` 會透過正在執行的 Gateway 讀取。這會讓 CLI 橋接檢查與執行階段記憶 Plugin 情境保持一致。如果橋接停用或成品讀取已關閉，這些命令會維持其本機與離線行為。
當橋接模式啟用且 `bridge.readMemoryArtifacts` 已啟用時，`openclaw wiki status`、`openclaw wiki doctor` 與 `openclaw wiki bridge
import` 會透過執行中的 Gateway 讀取。這會讓 CLI 橋接檢查與 runtime 記憶 Plugin 上下文保持一致。如果橋接已停用或成品讀取已關閉，這些命令會保留其本機/離線行為。
## 知識庫模式
## Vault 模式
`memory-wiki` 支援三種知識庫模式：
`memory-wiki` 支援三種 vault 模式：
### `isolated`
自有知識庫、自有來源，不依賴 `memory-core`。
自己的 vault、自己的來源，不依賴 `memory-core`。
當你希望 wiki 成為自己的策展知識儲存庫時，使用此模式。
當你希望 wiki 成為獨立策展的知識儲存庫時，請使用此模式。
### `bridge`
透過公開 Plugin SDK 接縫，從 Active Memory Plugin 讀取公開記憶成品與記憶事件。
透過公開 Plugin SDK seam，從 Active Memory Plugin 讀取公開記憶成品與記憶事件。
當你希望 wiki 編譯並整理記憶 Plugin 的匯出成品，而不深入私有 Plugin 內部實作時，使用此模式。
當你希望 wiki 編譯並整理記憶 Plugin 匯出的成品，而不深入私有 Plugin 內部實作時，請使用此模式。
橋接模式可以索引：
- 匯出的記憶成品
- 夢境報告
- 每日筆記
- 記憶根目錄檔案
- 記憶根檔案
- 記憶事件記錄
### `unsafe-local`
明確的同機器逃生出口，用於本機私有路徑。
明確的同機器逃生口，用於本機私有路徑。
此模式刻意設計為實驗性且不可攜。只有在你了解信任邊界，且特別需要橋接模式無法提供的本機檔案系統存取時才使用。
此模式刻意設計為實驗性且不可攜。僅在你理解信任邊界，且明確需要橋接模式無法提供的本機檔案系統存取時使用。
## 知識庫版面
## Vault 配置
此 Plugin 會初始化如下的知識庫：
Plugin 會像這樣初始化 vault：
```text
<vault>/
@ -120,14 +121,14 @@ x-i18n:
主要頁面群組為：
- `sources/` 用於匯入的原始材料與橋接支援頁面
- `entities/` 用於持久的事物、人物、系統、專案與物件
- `entities/` 用於持久事物、人物、系統、專案與物件
- `concepts/` 用於想法、抽象概念、模式與政策
- `syntheses/` 用於編譯後摘要與維護中的彙整
- `syntheses/` 用於已編譯摘要與維護中的彙總
- `reports/` 用於產生的儀表板
## 結構化主張與證據
頁面可以攜帶結構化 `claims` frontmatter，而不只是自由格式文字。
頁面可以攜帶結構化的 `claims` frontmatter，而不只是自由格式文字。
每個主張可以包含：
@ -150,24 +151,24 @@ x-i18n:
- `note`
- `updatedAt`
這正是讓 wiki 更像信念層，而不是被動筆記堆的原因。主張可以被追蹤、評分、質疑，並回溯到來源加以解析。
這讓 wiki 更像信念層，而不是被動的筆記傾倒處。主張可以被追蹤、評分、質疑，並解析回來源。
## 面向代理程式的實體中繼資料
## 面向 Agent 的實體中繼資料
實體頁面也可以攜帶供代理程式使用的路由中繼資料。這是通用 frontmatter，因此適用於人物、團隊、系統、專案或任何其他實體類型。
實體頁面也可以攜帶供 agent 使用的路由中繼資料。這是通用 frontmatter，因此適用於人物、團隊、系統、專案或任何其他實體類型。
常見欄位包括：
- `entityType`：例如 `person`、`team`、`system` 或 `project`
- `canonicalId`：跨別名與匯入使用的穩定身分鍵
- `aliases`：應解析到同一頁面的名稱、帳號或標籤
- `aliases`：應解析到同一頁面的名稱、handle 或標籤
- `privacyTier`：`public`、`local-private`、`sensitive` 或 `confirm-before-use`
- `bestUsedFor` / `notEnoughFor`：精簡路由提示
- `lastRefreshedAt`：與頁面編輯時間分開的來源重新整理時間戳
- `personCard`：可選的人物專用路由卡，包含帳號、社群、電子郵件、時區、路線、適合詢問、避免詢問、信心度與隱私
- `personCard`：可選的人物專用路由卡，包含 handle、社群、電子郵件、時區、lane、ask-for、avoid-asking-for、信心度與隱私
- `relationships`：指向相關頁面的型別化邊，包含目標、種類、權重、信心度、證據種類、隱私層級與備註
對於人物 wiki，代理程式通常應先從 `reports/person-agent-directory.md` 開始，接著在使用聯絡資訊或推論事實之前，用 `wiki_get` 開啟人物頁面。
對人物 wiki 來說，agent 通常應先從 `reports/person-agent-directory.md` 開始，接著用 `wiki_get` 開啟人物頁面，再使用聯絡資訊或推論出的事實。
範例：
@ -219,19 +220,19 @@ claims:
## 編譯管線
編譯步驟會讀取 wiki 頁面、正規化摘要，並在以下位置輸出穩定的機器面向成品：
編譯步驟會讀取 wiki 頁面、正規化摘要，並在下列位置輸出穩定的機器面向成品：
- `.openclaw-wiki/cache/agent-digest.json`
- `.openclaw-wiki/cache/claims.jsonl`
這些摘要的存在，是為了讓代理程式與執行階段程式碼不必抓取 Markdown 頁面。
這些摘要存在的目的，是讓 agent 與 runtime 程式碼不必爬取 Markdown 頁面。
編譯後輸出也會支援：
已編譯輸出也會支援：
- 搜尋與取得流程的一階 wiki 索引
- 從主張 ID 查回擁有該主張的頁面
- 精簡提示補充內容
- 報告與儀表板產生
- 搜尋/取得流程的第一階 wiki 索引
- claim-id 查詢回擁有頁面
- 精簡提示補充
- 報告/儀表板產生
## 儀表板與健康報告
@ -249,27 +250,27 @@ claims:
- `reports/provenance-coverage.md`
- `reports/privacy-review.md`
這些報告會追蹤如下項目：
這些報告會追蹤下列事項：
- 矛盾備註叢集
- 競爭主張叢集
- 競爭性主張叢集
- 缺少結構化證據的主張
- 低信心度頁面與主張
- 過期或未知的新鮮度
- 有未解問題的頁面
- 人物與實體路由卡
- 過時或未知的新鮮度
- 含有未解問題的頁面
- 人物/實體路由卡
- 結構化關係邊
- 證據類別覆蓋率
- 使用前需要審查的非公開隱私層級
## 搜尋與擷取
`memory-wiki` 支援兩種搜尋後端：
`memory-wiki` 支援兩個搜尋後端：
- `shared`：可用時使用共享記憶搜尋流程
- `local`：在本機搜尋 wiki
它也支援三種語料庫：
它也支援三個語料庫：
- `wiki`
- `memory`
@ -277,30 +278,30 @@ claims:
重要行為：
- `wiki_search` 與 `wiki_get` 會在可能時使用編譯摘要作為第一階段
- 主張 ID 可以解析回擁有該主張的頁面
- 受爭議、過期與新鮮主張會影響排序
- `wiki_search` 與 `wiki_get` 會在可能時使用已編譯摘要作為第一階段
- claim id 可以解析回擁有頁面
- 受質疑/過時/新鮮主張會影響排序
- 來源標籤可以保留到結果中
- 搜尋模式可以偏向人物查找、問題路由、來源證據或原始主張的排序
實用規則：
實務規則：
- 使用 `memory_search corpus=all` 進行一次廣泛召回
- 當你在意 wiki 專用排序、來源或頁面層級信念結構時，使用 `wiki_search` + `wiki_get`
- 使用 `memory_search corpus=all` 進行一次廣泛回想
- 當你重視 wiki 專用排序、來源或頁面層級信念結構時，使用 `wiki_search` + `wiki_get`
搜尋模式：
- `auto`：平衡的預設值
- `find-person`：提高類人物實體、別名、帳號、社群與 canonical ID 的權重
- `route-question`：提高代理程式卡、適合詢問提示、最適用提示與關係情境的權重
- `source-evidence`：提高來源頁面與結構化證據中繼資料的權重
- `raw-claim`：提高相符結構化主張的權重，並在結果中傳回主張與證據中繼資料
- `find-person`：加權人物類實體、別名、handle、社群與 canonical ID
- `route-question`：加權 agent 卡、ask-for 提示、best-used-for 提示與關係上下文
- `source-evidence`：加權來源頁面與結構化證據中繼資料
- `raw-claim`：加權相符的結構化主張，並在結果中回傳主張/證據中繼資料
當結果符合結構化主張時，`wiki_search` 可以在其詳細資料 payload 中傳回 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 與 `evidenceSourceIds`。文字輸出也會在可用時包含精簡的 `Claim:` 與 `Evidence:` 行。
當結果符合結構化主張時，`wiki_search` 可以在其詳細資料 payload 中回傳 `matchedClaimId`、`matchedClaimStatus`、`matchedClaimConfidence`、`evidenceKinds` 與 `evidenceSourceIds`。可用時，文字輸出也會包含精簡的 `Claim:` 與 `Evidence:` 行。
## 代理程式工具
## Agent 工具
此 Plugin 會註冊這些工具：
Plugin 會註冊這些工具：
- `wiki_status`
- `wiki_search`
@ -310,27 +311,27 @@ claims:
它們的用途：
- `wiki_status`：目前的知識庫模式、健康狀態、Obsidian CLI 可用性
- `wiki_search`：搜尋 wiki 頁面，以及在設定時搜尋共享記憶語料庫；接受 `mode` 以進行人物查找、問題路由、來源證據或原始主張深入查詢
- `wiki_get`：依 ID 或路徑讀取 wiki 頁面，或回退到共享記憶語料庫
- `wiki_apply`：進行狹窄的綜合與中繼資料變更，不做自由格式頁面手術
- `wiki_lint`：結構檢查、來源缺口、矛盾、待解問題
- `wiki_status`：目前 vault 模式、健康狀態、Obsidian CLI 可用性
- `wiki_search`：搜尋 wiki 頁面，以及在設定時搜尋共享記憶語料庫；接受 `mode` 進行人物查找、問題路由、來源證據或原始主張下鑽
- `wiki_get`：依 id/path 讀取 wiki 頁面，或退回共享記憶語料庫
- `wiki_apply`：狹窄的綜合/中繼資料變更，不進行自由格式頁面手術
- `wiki_lint`：結構檢查、來源缺口、矛盾、開放問題
此 Plugin 也會註冊非獨佔的記憶語料庫補充，因此當 Active Memory Plugin 支援語料庫選擇時，共享的 `memory_search` 與 `memory_get` 可以連到 wiki。
Plugin 也會註冊非獨占的記憶語料庫補充，因此當 Active Memory Plugin 支援語料庫選擇時，共享的 `memory_search` 與 `memory_get` 可以觸及 wiki。
## 提示與情境行為
## 提示與上下文行為
當 `context.includeCompiledDigestPrompt` 啟用時，記憶提示區段會附加來自 `agent-digest.json` 的精簡編譯快照。
當 `context.includeCompiledDigestPrompt` 啟用時，記憶提示區段會附加來自 `agent-digest.json` 的精簡已編譯快照。
該快照刻意保持小而高訊號：
該快照刻意保持小巧且高訊號：
- 僅限最重要頁面
- 僅限最重要主張
- 僅頂層頁面
- 僅頂層主張
- 矛盾數量
- 問題數量
- 信心度與新鮮度限定詞
- 信心度/新鮮度限定詞
這是選擇性啟用，因為它會改變提示形狀，且主要適用於明確使用記憶補充內容的情境引擎或舊版提示組裝。
這是選擇加入，因為它會改變提示形狀，且主要適用於明確消費記憶補充的上下文引擎或舊式提示組裝。
## 設定
@ -386,11 +387,11 @@ claims:
}
```
主要切換選項：
主要切換項：
- `vaultMode`：`isolated`、`bridge`、`unsafe-local`
- `vault.renderMode`：`native` 或 `obsidian`
- `bridge.readMemoryArtifacts`：匯入 Active Memory Plugin 公開成品
- `bridge.readMemoryArtifacts`：匯入 Active Memory Plugin 的公開成品
- `bridge.followMemoryEvents`：在橋接模式中包含事件記錄
- `search.backend`：`shared` 或 `local`
- `search.corpus`：`wiki`、`memory` 或 `all`
@ -400,12 +401,15 @@ claims:
### 範例：QMD + 橋接模式
當你想用 QMD 進行回想，並用 `memory-wiki` 維護知識層時，請使用這個設定：
當你想使用 QMD 進行回憶，並使用 `memory-wiki` 作為維護式知識層時，請使用此設定：
```json5
{
memory: {
backend: "qmd",
},
plugins: {
entries: {
"memory-wiki": {
enabled: true,
config: {
@ -432,11 +436,11 @@ claims:
}
```
這會保持：
這會維持：
- 由 QMD 負責 Active Memory 回想
- QMD 負責 Active Memory 回憶
- `memory-wiki` 專注於已編譯頁面與儀表板
- 提示形狀維持不變，直到你有意啟用已編譯摘要提示為止
- 提示形狀保持不變，直到你有意啟用已編譯摘要提示
## CLI
@ -456,11 +460,11 @@ openclaw wiki bridge import
openclaw wiki obsidian status
```
完整命令參考請見 [CLI：wiki](/zh-TW/cli/wiki)。
完整命令參考請參閱 [CLI：wiki](/zh-TW/cli/wiki)。
## Obsidian 支援
當 `vault.renderMode` 是 `obsidian` 時，Plugin 會寫入適合 Obsidian 的 Markdown，並可選擇使用官方 `obsidian` CLI。
當 `vault.renderMode` 為 `obsidian` 時，Plugin 會寫入 Obsidian 友善的 Markdown，並可選擇使用官方 `obsidian` CLI。
支援的工作流程包括：
@ -468,23 +472,23 @@ openclaw wiki obsidian status
- vault 搜尋
- 開啟頁面
- 呼叫 Obsidian 命令
- 跳到每日筆記
- 跳至每日筆記
這是選用功能。即使沒有 Obsidian，wiki 仍可在原生模式中運作。
這是可選的。即使沒有 Obsidian，wiki 仍可在原生模式下運作。
## 建議工作流程
1. 保留你的 Active Memory Plugin 來進行回想、提升與 Dreaming。
1. 保留你的 Active Memory Plugin 以進行回憶、提升與 Dreaming。
2. 啟用 `memory-wiki`。
3. 除非你明確想要橋接模式，否則先從 `isolated` 模式開始。
4. 當來源可追溯性很重要時，使用 `wiki_search` / `wiki_get`。
5. 使用 `wiki_apply` 進行範圍精準的整合或中繼資料更新。
3. 除非你明確想使用橋接模式，否則請從 `isolated` 模式開始。
4. 當來源脈絡很重要時，使用 `wiki_search` / `wiki_get`。
5. 使用 `wiki_apply` 進行小範圍綜合或中繼資料更新。
6. 在有意義的變更後執行 `wiki_lint`。
7. 如果你想看見過時/矛盾內容，請開啟儀表板。
7. 如果你想要 stale/contradiction 可見性，請開啟儀表板。
## 相關文件
- [記憶概觀](/zh-TW/concepts/memory)
- [Memory 概觀](/zh-TW/concepts/memory)
- [CLI：memory](/zh-TW/cli/memory)
- [CLI：wiki](/zh-TW/cli/wiki)
- [Plugin SDK 概觀](/zh-TW/plugins/sdk-overview)

110
docs/zh-TW/providers/openrouter.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你想要一個用於多種 LLM 的單一 API 金鑰
- 您想透過 OpenRouter 在 OpenClaw 中執行模型
- 你想要使用 OpenRouter 進行圖片生成
- 您想使用 OpenRouter 進行影片生成
summary: 使用 OpenRouter 的統一 API 在 OpenClaw 中存取多種模型
- 你想要一組可用於多種 LLM 的 API 金鑰
- 你想透過 OpenRouter 在 OpenClaw 中執行模型
- 你想使用 OpenRouter 進行影像生成
- 你想使用 OpenRouter 進行影片生成
summary: 使用 OpenRouter 的統一 API，在 OpenClaw 中存取多種模型
title: OpenRouter
x-i18n:
generated_at: "2026-05-02T21:02:53Z"
generated_at: "2026-05-04T02:45:38Z"
model: gpt-5.5
provider: openai
source_hash: e98b8b540265b6d11681390c02cb68312f33625bf223823a2dbca17e877c0422
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_path: providers/openrouter.md
workflow: 16
---
OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求路由到許多模型。它與 OpenAI 相容，因此大多數 OpenAI SDK 只要切換基底 URL 即可使用。
OpenRouter 提供**統一 API**，可透過單一端點和 API 金鑰將請求路由到多種模型。它與 OpenAI 相容，因此大多數 OpenAI SDK 只要切換基底 URL 即可運作。
## 開始使用
@ -23,13 +23,13 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求
<Step title="取得你的 API 金鑰">
在 [openrouter.ai/keys](https://openrouter.ai/keys) 建立 API 金鑰。
</Step>
<Step title="執行上線設定">
<Step title="執行 onboarding">
```bash
openclaw onboard --auth-choice openrouter-api-key
```
</Step>
<Step title="（可選）切換到特定模型">
上線設定預設為 `openrouter/auto`。之後可選擇具體模型：
<Step title="（選用）切換到特定模型">
Onboarding 預設使用 `openrouter/auto`。之後可選擇具體模型：
```bash
openclaw models set openrouter/<provider>/<model>
@ -54,7 +54,7 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求
## 模型參照
<Note>
模型參照遵循 `openrouter/<provider>/<model>` 模式。如需可用供應商與模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。
模型參照遵循 `openrouter/<provider>/<model>` 模式。如需可用提供者和模型的完整清單，請參閱 [/concepts/model-providers](/zh-TW/concepts/model-providers)。
</Note>
內建備援範例：
@ -64,9 +64,9 @@ OpenRouter 提供 **統一 API**，可透過單一端點和 API 金鑰將請求
| `openrouter/auto` | OpenRouter 自動路由 |
| `openrouter/moonshotai/kimi-k2.6` | 透過 MoonshotAI 使用 Kimi K2.6 |
## 圖像生成
## 圖片產生
OpenRouter 也可以支援 `image_generate` 工具。請在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 圖像模型：
OpenRouter 也可以支援 `image_generate` 工具。在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 圖片模型：
```json5
{
@ -82,11 +82,11 @@ OpenRouter 也可以支援 `image_generate` 工具。請在 `agents.defaults.ima
}
```
OpenClaw 會使用 `modalities: ["image", "text"]` 將圖像請求傳送到 OpenRouter 的聊天補全圖像 API。Gemini 圖像模型會透過 OpenRouter 的 `image_config` 接收支援的 `aspectRatio` 和 `resolution` 提示。對於較慢的 OpenRouter 圖像模型，請使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次呼叫的 `timeoutMs` 參數仍會優先套用。
OpenClaw 會使用 `modalities: ["image", "text"]` 將圖片請求傳送到 OpenRouter 的聊天補全圖片 API。Gemini 圖片模型會透過 OpenRouter 的 `image_config` 接收支援的 `aspectRatio` 和 `resolution` 提示。對於速度較慢的 OpenRouter 圖片模型，請使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次呼叫的 `timeoutMs` 參數仍會優先。
## 影片生成
## 影片產生
OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工具。請在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 影片模型：
OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工具。在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 影片模型：
```json5
{
@ -101,11 +101,11 @@ OpenRouter 也可以透過其非同步 `/videos` API 支援 `video_generate` 工
}
```
OpenClaw 會向 OpenRouter 提交文字轉影片與圖像轉影片工作，輪詢回傳的 `polling_url`，並從 OpenRouter 的 `unsigned_urls` 或文件化的工作內容端點下載完成的影片。參考圖像預設會以第一格／最後一格圖像傳送；標記為 `reference_image` 的圖像會作為 OpenRouter 輸入參照傳送。內建的 `google/veo-3.1-fast` 預設值宣告目前支援 4/6/8 秒時長、`720P`/`1080P` 解析度，以及 `16:9`/`9:16` 長寬比。OpenRouter 未註冊影片轉影片，因為上游影片生成 API 目前接受文字和圖像參照。
OpenClaw 會將文字轉影片和圖片轉影片作業提交給 OpenRouter，輪詢傳回的 `polling_url`，並從 OpenRouter 的 `unsigned_urls` 或文件化的作業內容端點下載完成的影片。參考圖片預設會作為第一/最後影格圖片傳送；標記為 `reference_image` 的圖片會作為 OpenRouter 輸入參考傳送。內建的 `google/veo-3.1-fast` 預設值宣告目前支援 4/6/8 秒時長、`720P`/`1080P` 解析度，以及 `16:9`/`9:16` 長寬比。OpenRouter 未註冊影片轉影片，因為上游影片產生 API 目前接受文字和圖片參考。
## 文字轉語音
OpenRouter 也可透過其與 OpenAI 相容的 `/audio/speech` 端點作為 TTS 供應商使用。
OpenRouter 也可以透過其與 OpenAI 相容的 `/audio/speech` 端點作為 TTS 提供者使用。
```json5
{
@ -125,63 +125,89 @@ OpenRouter 也可透過其與 OpenAI 相容的 `/audio/speech` 端點作為 TTS
}
```
如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 會重複使用 `models.providers.openrouter.apiKey`，接著使用 `OPENROUTER_API_KEY`。
如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 會重用 `models.providers.openrouter.apiKey`，然後才使用 `OPENROUTER_API_KEY`。
## 驗證與標頭
OpenRouter 底層會使用帶有你 API 金鑰的 Bearer 權杖。
OpenRouter 底層會使用帶有你的 API 金鑰的 Bearer 權杖。
在實際 OpenRouter 請求（`https://openrouter.ai/api/v1`）中，OpenClaw 也會加入 OpenRouter 文件化的應用程式歸因標頭：
| 標頭 | 值 |
| ------------------------- | --------------------- |
| `HTTP-Referer` | `https://openclaw.ai` |
| `X-OpenRouter-Title` | `OpenClaw` |
| `X-OpenRouter-Categories` | `cli-agent` |
| 標頭 | 值 |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `HTTP-Referer` | `https://openclaw.ai` |
| `X-OpenRouter-Title` | `OpenClaw` |
| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
<Warning>
如果你將 OpenRouter 供應商重新指向其他 Proxy 或基底 URL，OpenClaw **不會** 注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。
如果你將 OpenRouter 提供者重新指向其他 proxy 或基底 URL，OpenClaw **不會**注入這些 OpenRouter 專用標頭或 Anthropic 快取標記。
</Warning>
## 進階設定
<AccordionGroup>
<Accordion title="回應快取">
OpenRouter 回應快取需要選擇啟用。可使用模型參數為每個 OpenRouter 模型啟用：
```json5
{
agents: {
defaults: {
models: {
"openrouter/auto": {
params: {
responseCache: true,
responseCacheTtlSeconds: 300,
},
},
},
},
},
}
```
OpenClaw 會傳送 `X-OpenRouter-Cache: true`，並在設定時傳送 `X-OpenRouter-Cache-TTL`。`responseCacheClear: true` 會強制重新整理目前請求，並儲存替換回應。也接受 snake_case 別名（`response_cache`、`response_cache_ttl_seconds` 和 `response_cache_clear`）。
這與提供者提示快取以及 OpenRouter 的 Anthropic `cache_control` 標記不同。它只會套用在已驗證的 `openrouter.ai` 路由上，不會套用在自訂 proxy 基底 URL。
</Accordion>
<Accordion title="Anthropic 快取標記">
在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會用這些標記在系統／開發者提示區塊上更好地重複使用提示快取。
在已驗證的 OpenRouter 路由上，Anthropic 模型參照會保留 OpenRouter 專用的 Anthropic `cache_control` 標記，OpenClaw 會使用這些標記在系統/開發者提示區塊上提升提示快取重用率。
</Accordion>
<Accordion title="Anthropic reasoning 預填">
在已驗證的 OpenRouter 路由上，啟用 reasoning 的 Anthropic 模型參照會在請求送達 OpenRouter 前移除尾端 assistant 預填回合，以符合 Anthropic 要求 reasoning 對話必須以 user 回合結尾的規定。
<Accordion title="Anthropic 推理預填">
在已驗證的 OpenRouter 路由上，啟用推理的 Anthropic 模型參照會在請求到達 OpenRouter 前移除結尾的助理預填輪次，以符合 Anthropic 對推理對話必須以使用者輪次結尾的要求。
</Accordion>
<Accordion title="思考／reasoning 注入">
在支援的非 `auto` 路由上，OpenClaw 會將選取的思考層級對應到 OpenRouter Proxy reasoning 酬載。不支援的模型提示和 `openrouter/auto` 會略過該 reasoning 注入。Hunter Alpha 也會針對過時的已設定模型參照略過 Proxy reasoning，因為 OpenRouter 可能會針對該已退役路由在 reasoning 欄位中回傳最終答案文字。
<Accordion title="思考 / 推理注入">
在支援的非 `auto` 路由上，OpenClaw 會將選定的思考層級對應到 OpenRouter proxy 推理 payload。不支援的模型提示和 `openrouter/auto` 會略過該推理注入。Hunter Alpha 也會對過期設定的模型參照略過 proxy 推理，因為 OpenRouter 可能會針對該已淘汰路由在推理欄位中傳回最終答案文字。
</Accordion>
<Accordion title="DeepSeek V4 reasoning 重播">
在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的 assistant 回合補上缺少的 `reasoning_content`，讓思考／工具對話維持 DeepSeek V4 要求的後續形狀。
<Accordion title="DeepSeek V4 推理重播">
在已驗證的 OpenRouter 路由上，`openrouter/deepseek/deepseek-v4-flash` 和 `openrouter/deepseek/deepseek-v4-pro` 會在重播的助理輪次中補上缺失的 `reasoning_content`，讓思考/工具對話保留 DeepSeek V4 所需的後續形狀。
</Accordion>
<Accordion title="僅限 OpenAI 的請求塑形">
OpenRouter 仍會透過 Proxy 風格、與 OpenAI 相容的路徑執行，因此不會轉送原生僅限 OpenAI 的請求塑形，例如 `serviceTier`、Responses `store`、OpenAI reasoning 相容酬載，以及提示快取提示。
<Accordion title="僅 OpenAI 的請求形塑">
OpenRouter 仍會透過 proxy 風格的 OpenAI 相容路徑執行，因此不會轉送原生僅 OpenAI 的請求形塑，例如 `serviceTier`、Responses `store`、OpenAI 推理相容 payload，以及提示快取提示。
</Accordion>
<Accordion title="Gemini 支援的路由">
Gemini 支援的 OpenRouter 參照會停留在 Proxy-Gemini 路徑：OpenClaw 會在該處保留 Gemini 思考簽章清理，但不會啟用原生 Gemini 重播驗證或啟動重寫。
Gemini 支援的 OpenRouter 參照會留在 proxy-Gemini 路徑上：OpenClaw 會在該處保留 Gemini thought-signature 清理，但不會啟用原生 Gemini 重播驗證或 bootstrap 重寫。
</Accordion>
<Accordion title="供應商路由中繼資料">
如果你在模型參數下傳入 OpenRouter 供應商路由，OpenClaw 會先將其轉送為 OpenRouter 路由中繼資料，然後再執行共用串流包裝器。
<Accordion title="提供者路由中繼資料">
如果你在模型參數下傳入 OpenRouter 提供者路由，OpenClaw 會在共用串流包裝器執行前，將其作為 OpenRouter 路由中繼資料轉送。
</Accordion>
</AccordionGroup>
## 相關內容
## 相關
<CardGroup cols={2}>
<Card title="模型選擇" href="/zh-TW/concepts/model-providers" icon="layers">
選擇供應商、模型參照與容錯移轉行為。
選擇提供者、模型參照和容錯移轉行為。
</Card>
<Card title="設定參考" href="/zh-TW/gateway/configuration-reference" icon="gear">
agents、models 與 providers 的完整設定參考。
agents、模型和提供者的完整設定參考。
</Card>
</CardGroup>

129
docs/zh-TW/security/network-proxy.md
View File

@ -1,36 +1,36 @@
---
read_when:
- 你希望針對 SSRF 與 DNS 重新綁定攻擊採取縱深防禦
- 為 OpenClaw 執行階段流量設定外部正向代理
summary: 如何透過由操作人員管理的篩選代理路由 OpenClaw 執行階段 HTTP 和 WebSocket 流量
- 你想要針對 SSRF 與 DNS 重新綁定攻擊採取縱深防禦
- 設定 OpenClaw 執行階段流量的外部正向代理
summary: 如何透過操作員管理的篩選代理路由 OpenClaw 執行階段 HTTP 與 WebSocket 流量
title: 網路代理
x-i18n:
generated_at: "2026-05-02T02:59:32Z"
generated_at: "2026-05-04T02:45:35Z"
model: gpt-5.5
provider: openai
source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3
source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9
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 檢查與實際輸出連線之間的落差。
- 集中政策：維護單一輸出政策，而不是仰賴每個應用程式 HTTP 呼叫點都正確套用網路規則。
- 連線時檢查：在 DNS 解析後、代理開啟上游連線前立即評估目的地。
- DNS 重綁防禦：縮小應用程式層級 DNS 檢查與實際輸出連線之間的落差。
- 更廣泛的 JavaScript 覆蓋範圍：透過同一路徑路由一般 `fetch`、`node:http`、`node:https`、WebSocket、axios、got、node-fetch，以及類似用戶端。
- 可稽核性：在出口邊界記錄允許與拒絕的目的地。
- 營運控制：在不重新建置 OpenClaw 的情況下強制執行目的地規則、網路分段、速率限制或輸出允許清單。
- 可稽核性：在輸出邊界記錄允許和拒絕的目的地。
- 營運控制：不需重建 OpenClaw，就能強制執行目的地規則、網路分段、速率限制或輸出允許清單。
代理路由是一般 HTTP 和 WebSocket 輸出的程序層級防護欄。它讓操作員能以失敗即關閉的路徑，將受支援的 JavaScript HTTP 用戶端透過自己的過濾代理路由，但它不是作業系統層級的網路沙箱，也不代表 OpenClaw 會認證代理的目的地政策。
代理路由是一般 HTTP 和 WebSocket 輸出的程序層級護欄。它可讓操作員透過自己的過濾代理，為受支援的 JavaScript HTTP 用戶端提供失敗即封閉的路由路徑，但它不是作業系統層級的網路沙箱，也不表示 OpenClaw 會認證代理的目的地政策。
## OpenClaw 如何路由流量
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
公開合約是路由行為，而不是用來實作它的內部 Node hook。OpenClaw Gateway 控制平面 WebSocket 用戶端在 Gateway URL 使用 `localhost` 或字面 loopback IP，例如 `127.0.0.1` 或 `[::1]` 時，會對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理封鎖 loopback 目的地，該控制平面路徑也必須能夠連到 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理。
公開合約是路由行為，而不是用來實作它的內部 Node 掛鉤。當 Gateway URL 使用 `localhost`，或使用像 `127.0.0.1` 或 `[::1]` 這類明確 loopback IP 時，OpenClaw Gateway 控制平面 WebSocket 用戶端會針對 local loopback Gateway RPC 流量使用狹窄的直接路徑。即使操作員代理阻擋 loopback 目的地，該控制平面路徑也必須能連到 loopback Gateway。一般執行階段 HTTP 和 WebSocket 請求仍會使用設定的代理。
在內部，OpenClaw 會為此功能使用兩個程序層級路由 hook：
在內部，OpenClaw 針對此功能使用兩個程序層級的路由掛鉤：
- Undici dispatcher 路由涵蓋 `fetch`、以 undici 為基礎的用戶端，以及提供自身 undici dispatcher 的傳輸。
- `global-agent` 路由涵蓋 Node 核心 `node:http` 和 `node:https` 呼叫端，包括許多建構在 `http.request`、`https.request`、`http.get` 和 `https.get` 之上的函式庫。受管理的代理模式會強制使用該全域 agent，因此明確的 Node HTTP agent 不會意外繞過操作員代理。
- `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://`。透過代理使用 HTTP `CONNECT` 時，仍支援 HTTPS 目的地；這只表示 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 會還原先前的代理環境，並重設快取的程序路由狀態。
## 相關代理術語
- `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)。
- 通道或提供者專屬代理設定：特定傳輸的擁有者專屬覆寫。當目標是在整個執行階段集中控制出口時，請優先使用受管理的網路代理。
- `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)。
- 通道或供應商專屬代理設定：特定傳輸的擁有者專屬覆寫。若目標是在整個執行階段集中控制輸出，請優先使用受管理的網路代理。
## 設定
@ -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 或排程工作以該值啟動 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 程序、主機、容器或服務帳號可以使用它。
- 自行解析目的地，並在 DNS 解析後封鎖目的地 IP。
- 對純 HTTP 請求和 HTTPS `CONNECT` 通道，在連線時套用政策。
- 拒絕對 loopback、私有、link-local、metadata、多播、保留或文件範圍的目的地型繞過。
- 僅繫結至 loopback 或私有受信任介面。
- 限制存取權，讓只有 OpenClaw 程序、主機、容器或服務帳戶可以使用它。
- 自行解析目的地，並在 DNS 解析後阻擋目的地 IP。
- 對純 HTTP 請求與 HTTPS `CONNECT` 通道，在連線時套用政策。
- 拒絕對 loopback、私有、link-local、中繼資料、多播、保留或文件範圍的目的地型繞過。
- 除非你完全信任 DNS 解析路徑，否則避免使用主機名稱允許清單。
- 記錄目的地、決策、狀態和原因，但不記錄請求本文、授權標頭、Cookie 或其他秘密。
- 記錄目的地、決策、狀態和原因，但不要記錄請求本文、授權標頭、Cookie 或其他秘密。
- 將代理政策納入版本控制，並像審查安全敏感設定一樣審查變更。
## 建議封鎖的目的地
## 建議阻擋的目的地
將此拒絕清單作為任何正向代理、防火牆或出口政策的起點。
將此拒絕清單作為任何正向代理、防火牆或輸出政策的起點。
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-mapped 形式的嵌入式 IPv4 哨兵處理。維護外部代理政策時，這些檔案是有用參考，但 OpenClaw 不會自動匯出或在你的代理中強制執行那些規則。
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-mapped 形式的內嵌 IPv4 哨兵處理。維護外部代理政策時，這些檔案是實用參考，但 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` | Link-local 位址與常見雲端 metadata 路徑 |
| `169.254.169.254`, `metadata.google.internal` | 雲端 metadata 服務 |
| `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 丟棄與 ORCHIDv2 範圍 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | 帶有嵌入式 IPv4 的 NAT64 前綴 |
| `2002::/16`, `2001::/32` | 帶有嵌入式 IPv4 的 6to4 和 Teredo |
| `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` | Link-local 位址與常見雲端中繼資料路徑 |
| `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-compatible 與 IPv4-mapped IPv6 |
如果你的雲端提供者或網路平台記錄了其他 metadata 主機或保留範圍，也請加入它們。
如果你的雲端供應商或網路平台記載了其他中繼資料主機或保留範圍，也請一併加入。
## 驗證
從執行 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` 測試部署專屬預期。自訂拒絕目的地採用失敗即封閉：任何 HTTP 回應都表示可透過代理連到該目的地，而任何傳輸錯誤都會回報為無法判定，因為 OpenClaw 無法證明代理阻擋了可連線的來源。驗證失敗時，命令會以代碼 1 結束。
使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及每個目的地檢查。代理 URL 認證資料會在文字和 JSON 輸出中遮蔽：
使用 `--json` 進行自動化。JSON 輸出包含整體結果、有效代理設定來源、任何設定錯誤，以及各目的地檢查。代理 URL 認證會在文字與 JSON 輸出中遮蔽：
```json
{
@ -178,9 +178,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/
```
公開請求應該會成功。回送與中繼資料請求應該會被代理封鎖。對於 `openclaw proxy validate`，內建的回送金絲雀可以區分代理拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀，因此除非你的代理公開了可另行驗證的部署專屬拒絕訊號，否則請將 HTTP 回應與不明確的傳輸失敗都視為驗證失敗。
對公網的請求應該成功。回環與中繼資料請求應該會被代理伺服器封鎖。對於 `openclaw proxy validate`，內建的回環金絲雀可以區分代理伺服器拒絕與可連線的來源。自訂 `--denied-url` 檢查沒有該金絲雀，因此除非你的代理伺服器公開了可另行驗證的部署專屬拒絕訊號，否則請將 HTTP 回應與含糊的傳輸失敗都視為驗證失敗。
接著啟用 OpenClaw 代理路由：
然後啟用 OpenClaw 代理伺服器路由：
```bash
openclaw config set proxy.enabled true
@ -198,9 +198,10 @@ proxy:
## 限制
- 代理會改善程序本機 JavaScript HTTP 和 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
- 原始 `net`、`tls` 和 `http2` socket、原生附加元件與子程序，除非繼承並遵守代理環境變數，否則可能繞過 Node 層級的代理路由。
- 使用者的本機 WebUI 和本機模型伺服器應在需要時加入操作者代理政策的允許清單；OpenClaw 不會為它們公開一般的本機網路繞過機制。
- Gateway 控制平面代理繞過刻意限制為 `localhost` 與明確的回送 IP URL。對於本機直接 Gateway 控制平面連線，請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主機名稱會像一般主機名稱型流量一樣路由。
- OpenClaw 不會檢查、測試或認證你的代理政策。
- 請將代理政策變更視為具安全敏感性的營運變更。
- 代理伺服器可提升對程序本機 JavaScript HTTP 與 WebSocket 用戶端的涵蓋範圍，但它不是作業系統層級的網路沙箱。
- 原始 `net`、`tls` 和 `http2` 通訊端、原生附加元件與子程序，除非繼承並遵守代理伺服器環境變數，否則可能會繞過 Node 層級的代理伺服器路由。
- IRC 是位於操作員管理的正向代理伺服器路由之外的原始 TCP/TLS 通道。在要求所有輸出流量都必須經過該正向代理伺服器的部署中，除非已明確核准直接 IRC 輸出流量，否則請設定 `channels.irc.enabled=false`。
- 需要時，使用者本機 WebUI 與本機模型伺服器應在操作員代理伺服器政策中列入允許清單；OpenClaw 不會為它們公開一般性的本機網路繞過機制。
- Gateway 控制平面代理伺服器繞過刻意限制於 `localhost` 與字面回環 IP URL。針對本機直接 Gateway 控制平面連線，請使用 `ws://127.0.0.1:18789`、`ws://[::1]:18789` 或 `ws://localhost:18789`；其他主機名稱會像一般以主機名稱為基礎的流量一樣路由。
- OpenClaw 不會檢查、測試或認證你的代理伺服器政策。
- 請將代理伺服器政策變更視為安全性敏感的營運變更。

43
docs/zh-TW/tools/llm-task.md
View File

@ -1,19 +1,19 @@
---
read_when:
- 你希望在工作流程中加入僅輸出 JSON 的 LLM 步驟
- 你需要經結構描述驗證的 LLM 輸出來進行自動化
summary: 用於工作流程的 JSON-only LLM 任務（選用 Plugin 工具）
- 您想在工作流程中使用僅限 JSON 的 LLM 步驟
- 你需要經結構描述驗證、可用於自動化的大型語言模型輸出
summary: 工作流程的僅限 JSON 的 LLM 任務（選用 Plugin 工具）
title: 大型語言模型任務
x-i18n:
generated_at: "2026-04-30T03:45:55Z"
generated_at: "2026-05-04T02:45:51Z"
model: gpt-5.5
provider: openai
source_hash: 613aefd1bac5b9675821a118c11130c8bfaefb1673d0266f14ff4e91b47fed8b
source_hash: 9cdc5d4feef17fb6d6d90d819d4c92d26a4ec43e4f5364c6acbaad1934a89269
source_path: tools/llm-task.md
workflow: 16
---
`llm-task` 是一個**選用的 Plugin 工具**，會執行僅 JSON 的 LLM 工作，並傳回結構化輸出（可選擇依 JSON Schema 驗證）。
`llm-task` 是一個**選用 Plugin 工具**，會執行僅輸出 JSON 的 LLM 任務，並傳回結構化輸出（可選擇使用 JSON Schema 驗證）。
這很適合 Lobster 這類工作流程引擎：你可以加入單一 LLM 步驟，而不必為每個工作流程撰寫自訂 OpenClaw 程式碼。
@ -31,21 +31,18 @@ x-i18n:
}
```
2. 將工具加入允許清單（它是以 `optional: true` 註冊）：
2. 允許選用工具：
```json
{
"agents": {
"list": [
{
"id": "main",
"tools": { "allow": ["llm-task"] }
}
]
"tools": {
"alsoAllow": ["llm-task"]
}
}
```
只有在你想使用限制性允許清單模式時，才使用 `tools.allow`。
## 設定（選用）
```json
@ -68,7 +65,7 @@ x-i18n:
}
```
`allowedModels` 是 `provider/model` 字串的允許清單。如果已設定，清單以外的任何請求都會被拒絕。
`allowedModels` 是 `provider/model` 字串的允許清單。如果有設定，清單外的任何請求都會被拒絕。
## 工具參數
@ -83,11 +80,11 @@ x-i18n:
- `maxTokens`（數字，選用）
- `timeoutMs`（數字，選用）
`thinking` 接受標準的 OpenClaw 推理預設值，例如 `low` 或 `medium`。
`thinking` 接受標準 OpenClaw 推理預設值，例如 `low` 或 `medium`。
## 輸出
傳回包含已解析 JSON 的 `details.json`（並在提供 `schema` 時依其驗證）。
傳回包含已剖析 JSON 的 `details.json`（提供 `schema` 時也會據此驗證）。
## 範例：Lobster 工作流程步驟
@ -113,13 +110,13 @@ openclaw.invoke --tool llm-task --action json --args-json '{
## 安全注意事項
- 此工具是**僅 JSON**，並會指示模型只輸出 JSON（不含程式碼圍欄、沒有說明文字）。
- 這次執行不會向模型暴露任何工具。
- 除非你使用 `schema` 驗證，否則應將輸出視為不可信。
- 在任何有副作用的步驟（send、post、exec）之前放置核准流程。
- 此工具**僅輸出 JSON**，並指示模型只輸出 JSON（不得包含程式碼區塊或評論）。
- 此次執行不會向模型公開任何工具。
- 除非你使用 `schema` 驗證，否則應將輸出視為不受信任。
- 在任何會產生副作用的步驟（send、post、exec）之前放置核准流程。
## 相關內容
## 相關
- [思考層級](/zh-TW/tools/thinking)
- [推理層級](/zh-TW/tools/thinking)
- [Sub-agents](/zh-TW/tools/subagents)
- [斜線命令](/zh-TW/tools/slash-commands)

122
docs/zh-TW/tools/lobster.md
View File

@ -1,52 +1,52 @@
---
read_when:
- 你需要具備明確核准機制的確定性多步驟工作流程
- 您需要繼續某個工作流程，而不重新執行先前的步驟
summary: 適用於 OpenClaw 的型別化工作流程執行階段，具備可恢復的核准閘門。
- 您需要具備明確核准機制的確定性多步驟工作流程
- 你需要在不重新執行先前步驟的情況下恢復工作流程
summary: 具備可恢復核准閘門的 OpenClaw 型別化工作流程執行階段。
title: 龍蝦
x-i18n:
generated_at: "2026-04-30T03:45:53Z"
generated_at: "2026-05-04T02:46:07Z"
model: gpt-5.5
provider: openai
source_hash: 1700bcfdbcf4558cb908935834e9059221d0d26ad78ed6f9e2158f7e0b83edbd
source_hash: 67f5145b11f2d6e07e9d78a44a389ae5f236c85ec8c287ab0f217a18b622ece0
source_path: tools/lobster.md
workflow: 16
---
Lobster 是一個工作流程 shell，讓 OpenClaw 能將多步驟工具序列作為單一、確定性的操作執行，並具備明確的核准檢查點。
Lobster 是一個工作流程 shell，讓 OpenClaw 能將多步驟工具序列作為單一、確定性的操作執行，並具有明確的核准檢查點。
Lobster 是位於卸離背景工作之上的一層編寫層。若要了解個別任務之上的流程協調，請參閱 [Task Flow](/zh-TW/automation/taskflow)（`openclaw tasks flow`）。若要了解任務活動帳本，請參閱 [`openclaw tasks`](/zh-TW/automation/tasks)。
Lobster 是高於 detached background work 的一層編寫層。若要了解個別任務之上的流程編排，請參閱 [TaskFlow](/zh-TW/automation/taskflow)（`openclaw tasks flow`）。若要了解任務活動帳本，請參閱 [`openclaw tasks`](/zh-TW/automation/tasks)。
## Hook
你的助理可以建置管理自身的工具。提出一個工作流程需求，30 分鐘後你就會有一個 CLI 加上一組能以一次呼叫執行的管線。Lobster 就是缺少的那一塊：確定性的管線、明確核准，以及可恢復的狀態。
你的助理可以建構管理自身的工具。要求一個工作流程，30 分鐘後你就會有一個 CLI 加上可作為一次呼叫執行的管線。Lobster 是缺少的那一塊：確定性管線、明確核准，以及可恢復的狀態。
## 為什麼
如今，複雜工作流程需要多次來回工具呼叫。每次呼叫都會消耗 token，而 LLM 必須協調每個步驟。Lobster 將這種協調移入具型別的執行階段：
如今，複雜工作流程需要許多來回工具呼叫。每次呼叫都會耗費 tokens，而 LLM 必須編排每個步驟。Lobster 將該編排移入具型別的執行階段：
- **一次呼叫取代多次呼叫**：OpenClaw 執行一次 Lobster 工具呼叫並取得結構化結果。
- **內建核准**：副作用（傳送電子郵件、發布留言）會暫停工作流程，直到明確核准為止。
- **可恢復**：暫停的工作流程會回傳 token；核准後可恢復，而不必重新執行所有內容。
- **一次呼叫取代多次呼叫**：OpenClaw 執行一次 Lobster 工具呼叫，並取得結構化結果。
- **內建核准**：副作用（寄送電子郵件、發布留言）會暫停工作流程，直到明確核准。
- **可恢復**：暫停的工作流程會回傳 token；核准後即可恢復，而不必重新執行所有內容。
## 為什麼使用 DSL 而不是普通程式？
## 為什麼使用 DSL 而不是一般程式？
Lobster 刻意保持小巧。目標不是「一種新語言」，而是一種可預測、AI 友善的管線規格，並將核准與恢復 token 作為一等功能。
Lobster 刻意保持小而精。目標不是「一種新語言」，而是一個可預測、AI 友善的管線規格，並具備一等公民的核准與恢復 tokens。
- **內建核准/恢復**：一般程式可以提示人類，但若沒有你自己發明該執行階段，它無法透過持久 token _暫停並恢復_。
- **確定性 + 可稽核性**：管線是資料，因此很容易記錄、比較差異、重播與審查。
- **為 AI 限縮的介面**：微小文法 + JSON 管線可減少「創意」程式路徑，並讓驗證變得務實可行。
- **內建安全政策**：逾時、輸出上限、沙箱檢查與 allowlist 由執行階段強制執行，而不是由每個指令碼各自處理。
- **仍可程式化**：每個步驟都能呼叫任何 CLI 或指令碼。若你想使用 JS/TS，可從程式碼產生 `.lobster` 檔案。
- **內建核准/恢復**：一般程式可以提示人類，但無法在沒有自行發明執行階段的情況下，使用持久 token _暫停並恢復_。
- **確定性 + 可稽核性**：管線是資料，因此容易記錄、比較差異、重播與審查。
- **為 AI 限縮表面**：極小文法 + JSON 管道可減少「創意」程式碼路徑，並讓驗證變得實際可行。
- **內建安全政策**：逾時、輸出上限、沙盒檢查與 allowlists 由執行階段強制執行，而不是由每個腳本各自處理。
- **仍可程式化**：每個步驟都可以呼叫任何 CLI 或腳本。如果你想使用 JS/TS，可以從程式碼產生 `.lobster` 檔案。
## 運作方式
OpenClaw 使用內嵌 runner **於行程內**執行 Lobster 工作流程。不會產生外部 CLI 子行程；工作流程引擎在 Gateway 行程內執行，並直接回傳 JSON envelope。
OpenClaw 使用嵌入式 runner **在程序內**執行 Lobster 工作流程。不會產生外部 CLI 子程序；工作流程引擎會在 gateway 程序內執行，並直接回傳 JSON envelope。
如果管線因核准而暫停，工具會回傳 `resumeToken`，讓你稍後繼續。
## 模式：小型 CLI + JSON 管線 + 核准
## 模式：小型 CLI + JSON 管道 + 核准
建置會輸出 JSON 的小型命令，然後將它們串接成單一 Lobster 呼叫。（以下範例命令名稱請替換成你自己的。）
建構會說 JSON 的小型命令，然後將它們串接成單一 Lobster 呼叫。（以下範例命令名稱僅供參考，請替換成你自己的命令。）
```bash
inbox list --json
@ -62,7 +62,7 @@ inbox apply --json
}
```
如果管線要求核准，使用 token 恢復：
如果管線要求核准，請使用 token 恢復：
```json
{
@ -74,7 +74,7 @@ inbox apply --json
AI 觸發工作流程；Lobster 執行步驟。核准閘門讓副作用保持明確且可稽核。
範例：將輸入項目映射成工具呼叫：
範例：將輸入項目映射為工具呼叫：
```bash
gog.gmail.search --query 'newer_than:1d' \
@ -83,9 +83,9 @@ gog.gmail.search --query 'newer_than:1d' \
## 僅 JSON 的 LLM 步驟（llm-task）
對於需要**結構化 LLM 步驟**的工作流程，啟用選用的
`llm-task` plugin 工具，並從 Lobster 呼叫它。這能讓工作流程
保持確定性，同時仍可用模型進行分類、摘要與草擬。
對於需要**結構化 LLM 步驟**的工作流程，請啟用選用的
`llm-task` Plugin 工具，並從 Lobster 呼叫它。這能讓工作流程保持
確定性，同時仍能使用模型進行分類/摘要/草擬。
啟用工具：
@ -100,7 +100,7 @@ gog.gmail.search --query 'newer_than:1d' \
"list": [
{
"id": "main",
"tools": { "allow": ["llm-task"] }
"tools": { "alsoAllow": ["llm-task"] }
}
]
}
@ -130,7 +130,7 @@ openclaw.invoke --tool llm-task --action json --args-json '{
## 工作流程檔案（.lobster）
Lobster 可以執行包含 `name`、`args`、`steps`、`env`、`condition` 與 `approval` 欄位的 YAML/JSON 工作流程檔案。在 OpenClaw 工具呼叫中，將 `pipeline` 設為檔案路徑。
Lobster 可以執行具有 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 欄位的 YAML/JSON 工作流程檔案。在 OpenClaw 工具呼叫中，將 `pipeline` 設為檔案路徑。
```yaml
name: inbox-triage
@ -153,22 +153,22 @@ steps:
condition: $approve.approved
```
注意：
注意事項：
- `stdin: $step.stdout` 和 `stdin: $step.json` 會傳遞前一個步驟的輸出。
- `condition`（或 `when`）可依據 `$step.approved` 控制步驟是否執行。
- `stdin: $step.stdout` 和 `stdin: $step.json` 會傳遞先前步驟的輸出。
- `condition`（或 `when`）可以根據 `$step.approved` 為步驟設閘。
## 安裝 Lobster
內建的 Lobster 工作流程會於行程內執行；不需要個別的 `lobster` 二進位檔。內嵌 runner 隨 Lobster plugin 一起提供。
隨附的 Lobster 工作流程會在程序內執行；不需要單獨的 `lobster` 二進位檔。嵌入式 runner 會隨 Lobster Plugin 一起提供。
如果你需要獨立的 Lobster CLI 來開發或執行外部管線，請從 [Lobster repo](https://github.com/openclaw/lobster) 安裝，並確保 `lobster` 位於 `PATH`。
如果你需要獨立的 Lobster CLI 進行開發或外部管線，請從 [Lobster repo](https://github.com/openclaw/lobster) 安裝，並確保 `lobster` 位於 `PATH`。
## 啟用工具
Lobster 是**選用**的 plugin 工具（預設未啟用）。
Lobster 是**選用**的 Plugin 工具（預設未啟用）。
建議做法（累加且安全）：
建議方式（加法式、安全）：
```json
{
@ -178,7 +178,7 @@ Lobster 是**選用**的 plugin 工具（預設未啟用）。
}
```
或依 agent 設定：
或按代理程式設定：
```json
{
@ -195,13 +195,13 @@ Lobster 是**選用**的 plugin 工具（預設未啟用）。
}
```
除非你打算以限制性 allowlist 模式執行，否則請避免使用 `tools.allow: ["lobster"]`。
除非你打算在限制性 allowlist 模式中執行，否則請避免使用 `tools.allow: ["lobster"]`。
<Note>
allowlist 對選用 plugin 採用選擇啟用。如果你的 allowlist 只列出 plugin 工具（例如 `lobster`），OpenClaw 會保持核心工具啟用。若要限制核心工具，也請將你想要的核心工具或群組納入 allowlist。
選用 Plugins 的 allowlists 是選擇加入。`alsoAllow` 只會啟用具名的選用 Plugin 工具，同時保留一般核心工具集。若要限制核心工具，請將 `tools.allow` 與你想要的核心工具或群組搭配使用。
</Note>
## 範例：電子郵件分類處理
## 範例：電子郵件分診
沒有 Lobster：
@ -216,7 +216,7 @@ User: "Check my email and draft replies"
(repeat daily, no memory of what was triaged)
```
有 Lobster：
使用 Lobster：
```json
{
@ -270,7 +270,7 @@ User: "Check my email and draft replies"
}
```
使用引數執行工作流程檔案：
使用 args 執行工作流程檔案：
```json
{
@ -282,7 +282,7 @@ User: "Check my email and draft replies"
### `resume`
在核准後繼續暫停的工作流程。
在核准後繼續已暫停的工作流程。
```json
{
@ -294,20 +294,20 @@ User: "Check my email and draft replies"
### 選用輸入
- `cwd`：管線的相對工作目錄（必須保持在 Gateway 工作目錄內）。
- `timeoutMs`：如果工作流程超過此持續時間則中止（預設：20000）。
- `maxStdoutBytes`：如果輸出超過此大小則中止工作流程（預設：512000）。
- `cwd`：管線的相對工作目錄（必須保持在 gateway 工作目錄內）。
- `timeoutMs`：如果工作流程超過此時長，則中止（預設：20000）。
- `maxStdoutBytes`：如果輸出超過此大小，則中止（預設：512000）。
- `argsJson`：傳遞給 `lobster run --args-json` 的 JSON 字串（僅限工作流程檔案）。
## 輸出 envelope
Lobster 會回傳 JSON envelope，其狀態為以下三者之一：
Lobster 會回傳具有三種狀態之一的 JSON envelope：
- `ok` → 已成功完成
- `needs_approval` → 已暫停；需要 `requiresApproval.resumeToken` 才能恢復
- `cancelled` → 已明確拒絕或取消
工具會同時在 `content`（格式化 JSON）與 `details`（原始物件）中公開 envelope。
此工具會同時在 `content`（美化 JSON）和 `details`（原始物件）中公開 envelope。
## 核准
@ -316,40 +316,40 @@ Lobster 會回傳 JSON envelope，其狀態為以下三者之一：
- `approve: true` → 恢復並繼續副作用
- `approve: false` → 取消並完成工作流程
使用 `approve --preview-from-stdin --limit N` 可將 JSON 預覽附加到核准要求，而不需要自訂 jq/heredoc 黏合邏輯。恢復 token 現在很精簡：Lobster 會將工作流程恢復狀態儲存在其狀態目錄下，並回傳一個小型 token key。
使用 `approve --preview-from-stdin --limit N`，即可將 JSON 預覽附加到核准要求，而不需要自訂 jq/heredoc 黏合程式碼。恢復 tokens 現在很精簡：Lobster 會將工作流程恢復狀態儲存在其狀態目錄下，並回傳一個小型 token key。
## OpenProse
OpenProse 與 Lobster 搭配良好：使用 `/prose` 協調多 agent 準備工作，然後執行 Lobster 管線以取得確定性核准。如果 Prose 程式需要 Lobster，請透過 `tools.subagents.tools` 允許子 agent 使用 `lobster` 工具。請參閱 [OpenProse](/zh-TW/prose)。
OpenProse 與 Lobster 搭配得很好：使用 `/prose` 編排多代理程式準備工作，然後執行 Lobster 管線以取得確定性的核准。如果 Prose 程式需要 Lobster，請透過 `tools.subagents.tools` 為子代理程式允許 `lobster` 工具。請參閱 [OpenProse](/zh-TW/prose)。
## 安全性
- **僅限本機行程內** — 工作流程在 Gateway 行程內執行；plugin 本身不會進行網路呼叫。
- **不處理密鑰** — Lobster 不管理 OAuth；它會呼叫負責這些工作的 OpenClaw 工具。
- **沙箱感知** — 當工具內容在沙箱中時會停用。
- **已強化** — 逾時與輸出上限由內嵌 runner 強制執行。
- **僅限本機程序內** — 工作流程在 gateway 程序內執行；Plugin 本身不會發出網路呼叫。
- **無秘密** — Lobster 不管理 OAuth；它會呼叫負責處理的 OpenClaw 工具。
- **沙盒感知** — 當工具情境處於沙盒中時會停用。
- **已強化** — 逾時與輸出上限由嵌入式 runner 強制執行。
## 疑難排解
- **`lobster timed out`** → 增加 `timeoutMs`，或拆分長管線。
- **`lobster timed out`** → 增加 `timeoutMs`，或拆分較長的管線。
- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或減少輸出大小。
- **`lobster returned invalid JSON`** → 確保管線以工具模式執行，且只列印 JSON。
- **`lobster failed`** → 查看 Gateway 記錄，以取得內嵌 runner 錯誤詳細資料。
- **`lobster failed`** → 檢查 gateway 記錄以取得嵌入式 runner 錯誤詳細資訊。
## 了解更多
## 深入了解
- [Plugins](/zh-TW/tools/plugin)
- [Plugin 工具編寫](/zh-TW/plugins/building-plugins#registering-agent-tools)
## 案例研究：社群工作流程
一個公開範例：「第二大腦」CLI + Lobster 管線，用於管理三個 Markdown vault（個人、伴侶、共享）。CLI 會為統計資料、收件匣列表與過期掃描輸出 JSON；Lobster 則將這些命令串接成 `weekly-review`、`inbox-triage`、`memory-consolidation` 與 `shared-task-sync` 等工作流程，每個都具備核准閘門。可用時，AI 會處理判斷（分類）；不可用時，則退回確定性規則。
一個公開範例：一個「第二大腦」CLI + Lobster 管線，用來管理三個 Markdown vault（個人、夥伴、共享）。該 CLI 會為統計資料、收件匣清單與過期掃描輸出 JSON；Lobster 會將這些命令串接成 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync` 等工作流程，每個都有核准閘門。AI 會在可用時處理判斷（分類），不可用時則回退到確定性規則。
- 討論串：[https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
- Repo：[https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
## 相關
- [自動化與任務](/zh-TW/automation) — 排程 Lobster 工作流程
- [自動化概覽](/zh-TW/automation) — 所有自動化機制
- [工具概覽](/zh-TW/tools) — 所有可用的 agent 工具
- [工具概覽](/zh-TW/tools) — 所有可用的代理程式工具

308
docs/zh-TW/tools/slash-commands.md
View File

@ -3,40 +3,40 @@ read_when:
- 使用或設定聊天指令
- 偵錯命令路由或權限
sidebarTitle: Slash commands
summary: 斜線命令：文字與原生、設定和支援的命令
summary: 斜線命令：文字與原生模式、設定與支援的命令
title: 斜線指令
x-i18n:
generated_at: "2026-05-03T21:44:24Z"
generated_at: "2026-05-04T02:46:28Z"
model: gpt-5.5
provider: openai
source_hash: 9fbdd76ccd43159cabfbc3f15f7bddd2a7ada07fcd6eea2e169d2d88df18f28c
source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84
source_path: tools/slash-commands.md
workflow: 16
---
Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，並以 `/` 開頭。僅限主機的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 為別名）。
Commands 由 Gateway 處理。大多數指令都必須作為以 `/` 開頭的**獨立**訊息傳送。僅限主機的 bash 聊天指令使用 `! <cmd>`（`/bash <cmd>` 為別名）。
當對話或對話串繫結至 ACP 工作階段時，一般後續文字會路由到該 ACP harness。Gateway 管理命令仍會保留在本機：`/acp ...` 一律會送達 OpenClaw ACP 命令處理器，而只要該介面啟用了命令處理，`/status` 與 `/unfocus` 就會保留在本機。
當對話或討論串繫結到 ACP 工作階段時，一般後續文字會路由到該 ACP harness。Gateway 管理指令仍保持本機處理：`/acp ...` 一律會送達 OpenClaw ACP 指令處理器，而只要該介面啟用了指令處理，`/status` 與 `/unfocus` 就會保持本機處理。
有兩個相關系統：
<AccordionGroup>
<Accordion title="命令">
<Accordion title="指令">
獨立的 `/...` 訊息。
</Accordion>
<Accordion title="指令">
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`。
<Accordion title="指示詞">
`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 指令會在模型看到訊息前從訊息中移除。
- 在一般聊天訊息中（不是僅含指令），它們會被視為「行內提示」，而且**不會**保留工作階段設定。
- 在僅含指令的訊息中（訊息只包含指令），它們會保留到工作階段，並回覆確認訊息。
- 指令只會套用於**已授權的傳送者**。如果已設定 `commands.allowFrom`，它就是唯一使用的允許清單；否則授權會來自通道允許清單／配對加上 `commands.useAccessGroups`。未授權的傳送者會看到指令被視為純文字。
- 指示詞會先從訊息中移除，模型才會看到。
- 在一般聊天訊息中（非純指示詞），它們會被視為「行內提示」，且**不會**持續保存工作階段設定。
- 在純指示詞訊息中（訊息只包含指示詞），它們會持續保存到工作階段，並以確認訊息回覆。
- 指示詞只會套用於**已授權的傳送者**。如果設定了 `commands.allowFrom`，它就是唯一使用的允許清單；否則授權來自頻道允許清單/配對加上 `commands.useAccessGroups`。未授權的傳送者會看到指示詞被當作純文字處理。
</Accordion>
<Accordion title="行內捷徑">
僅限允許清單／已授權的傳送者：`/help`, `/commands`, `/status`, `/whoami` (`/id`)。
僅限允許清單/已授權的傳送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它們會立即執行，在模型看到訊息前被移除，而剩餘文字會繼續通過一般流程。
它們會立即執行，在模型看到訊息前被移除，而剩餘文字會繼續走一般流程。
</Accordion>
</AccordionGroup>
@ -69,136 +69,137 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
```
<ParamField path="commands.text" type="boolean" default="true">
啟用在聊天訊息中解析 `/...`。在沒有原生命令的介面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你將此項設為 `false`，文字命令仍可運作。
啟用聊天訊息中的 `/...` 解析。在沒有原生指令的介面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你將此項設為 `false`，文字指令仍可運作。
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
註冊原生命令。自動：Discord/Telegram 開啟；Slack 關閉（直到你新增斜線命令）；對不支援原生命令的供應商會被忽略。設定 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native`，即可依供應商覆寫（布林值或 `"auto"`）。在 Discord 上，`false` 會在啟動期間略過斜線命令註冊與清理；先前註冊的命令可能會持續可見，直到你從 Discord 應用程式移除它們。Slack 命令是在 Slack 應用程式中管理，且不會自動移除。
註冊原生指令。自動：Discord/Telegram 啟用；Slack 停用（直到你加入斜線指令）；沒有原生支援的提供者會忽略。設定 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native`，可依提供者覆寫（布林值或 `"auto"`）。在 Discord 上，`false` 會在啟動期間略過斜線指令註冊與清理；先前註冊的指令可能仍會可見，直到你從 Discord 應用程式中移除。Slack 指令在 Slack 應用程式中管理，且不會自動移除。
</ParamField>
在 Discord 上，原生命令規格可包含 `descriptionLocalizations`，OpenClaw 會將其發布為 Discord `description_localizations`，並納入調和比較。
在 Discord 上，原生指令規格可包含 `descriptionLocalizations`，OpenClaw 會將其發布為 Discord `description_localizations`，並納入協調比較。
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
在支援時以原生方式註冊 **skill** 命令。自動：Discord/Telegram 開啟；Slack 關閉（Slack 需要為每個 skill 建立一個斜線命令）。設定 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills`，即可依供應商覆寫（布林值或 `"auto"`）。
在支援時以原生方式註冊**技能**指令。自動：Discord/Telegram 啟用；Slack 停用（Slack 需要為每個技能建立一個斜線指令）。設定 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills`，可依提供者覆寫（布林值或 `"auto"`）。
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
啟用 `! <cmd>` 以執行主機 shell 命令（`/bash <cmd>` 是別名；需要 `tools.elevated` 允許清單）。
啟用 `! <cmd>` 以執行主機 shell 指令（`/bash <cmd>` 是別名；需要 `tools.elevated` 允許清單）。
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
控制 bash 在切換到背景模式前等待多久（`0` 會立即轉入背景）。
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
啟用 `/config`（讀取／寫入 `openclaw.json`）。
啟用 `/config`（讀取/寫入 `openclaw.json`）。
</ParamField>
<ParamField path="commands.mcp" type="boolean" default="false">
啟用 `/mcp`（讀取／寫入 `mcp.servers` 下由 OpenClaw 管理的 MCP 設定）。
啟用 `/mcp`（讀取/寫入 OpenClaw 管理、位於 `mcp.servers` 下的 MCP 設定）。
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
啟用 `/plugins`（Plugin 探索／狀態，以及安裝與啟用／停用控制）。
啟用 `/plugins`（Plugin 探索/狀態，以及安裝與啟用/停用控制）。
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
啟用 `/debug`（僅限執行階段覆寫）。
啟用 `/debug`（僅限執行階段的覆寫）。
</ParamField>
<ParamField path="commands.restart" type="boolean" default="true">
啟用 `/restart` 加上 Gateway 重新啟動工具動作。
啟用 `/restart` 以及 Gateway 重新啟動工具動作。
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
設定僅限擁有者命令／工具介面的明確擁有者允許清單。這是可以核准危險動作並執行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人類操作員帳號。它與 `commands.allowFrom` 以及 DM 配對存取是分開的。
為僅限擁有者的指令/工具介面設定明確的擁有者允許清單。這是可核准危險動作並執行 `/diagnostics`、`/export-trajectory` 和 `/config` 等指令的人類操作者帳號。它與 `commands.allowFrom` 以及 DM 配對存取是分開的。
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
依通道設定：讓僅限擁有者命令必須具備**擁有者身分**才能在該介面上執行。當為 `true` 時，傳送者必須符合已解析的擁有者候選項（例如 `commands.ownerAllowFrom` 中的項目，或供應商原生擁有者中繼資料），或在內部訊息通道上持有內部 `operator.admin` 範圍。通道 `allowFrom` 中的萬用字元項目，或空白／未解析的擁有者候選清單，**不足以**通過條件；僅限擁有者命令會在該通道上預設拒絕。如果你希望僅限擁有者命令只由 `ownerAllowFrom` 與標準命令允許清單把關，請保持此項關閉。
依頻道設定：讓僅限擁有者的指令在該介面上執行時必須具備**擁有者身分**。當為 `true` 時，傳送者必須符合已解析的擁有者候選項目（例如 `commands.ownerAllowFrom` 中的項目或提供者原生的擁有者中繼資料），或在內部訊息頻道上持有內部 `operator.admin` 範圍。頻道 `allowFrom` 中的萬用字元項目，或空的/未解析的擁有者候選清單，**不足以**通過；僅限擁有者的指令會在該頻道上預設拒絕。若你希望僅限擁有者的指令只由 `ownerAllowFrom` 和標準指令允許清單把關，請關閉此項。
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
控制擁有者 ID 在系統提示中如何顯示。
</ParamField>
<ParamField path="commands.ownerDisplaySecret" type="string">
可選擇性設定 `commands.ownerDisplay="hash"` 時使用的 HMAC secret。
可選擇設定在 `commands.ownerDisplay="hash"` 時使用的 HMAC 密鑰。
</ParamField>
<ParamField path="commands.allowFrom" type="object">
依供應商設定的命令授權允許清單。設定後，它會成為命令與指令的唯一授權來源（通道允許清單／配對與 `commands.useAccessGroups` 會被忽略）。使用 `"*"` 作為全域預設；供應商專屬鍵會覆寫它。
依提供者設定指令授權允許清單。設定後，它會是指令與指示詞唯一的授權來源（頻道允許清單/配對以及 `commands.useAccessGroups` 會被忽略）。使用 `"*"` 作為全域預設；提供者專屬鍵會覆寫它。
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
在未設定 `commands.allowFrom` 時，對命令強制套用允許清單／政策。
當未設定 `commands.allowFrom` 時，對指令強制套用允許清單/政策。
</ParamField>
## 命令清單
## 指令清單
目前的真實來源：
- 核心內建項目來自 `src/auto-reply/commands-registry.shared.ts`
- 產生的 dock 命令來自 `src/auto-reply/commands-registry.data.ts`
- Plugin 命令來自 Plugin `registerCommand()` 呼叫
- 你的 Gateway 上的實際可用性仍取決於設定旗標、通道介面，以及已安裝／啟用的 Plugin
- 產生的 dock 指令來自 `src/auto-reply/commands-registry.data.ts`
- Plugin 指令來自 Plugin `registerCommand()` 呼叫
- 在你的 Gateway 上的實際可用性仍取決於設定旗標、頻道介面，以及已安裝/啟用的 Plugins
### 核心內建命令
### 核心內建指令
<AccordionGroup>
<Accordion title="工作階段與執行">
- `/new [model]` 會啟動新工作階段；`/reset` 是重設別名。
- `/new [model]` 會啟動新的工作階段；`/reset` 是重設別名。
- Control UI 會攔截輸入的 `/new`，以建立並切換到新的儀表板工作階段；輸入的 `/reset` 仍會執行 Gateway 的就地重設。
- `/reset soft [message]` 會保留目前轉錄稿、丟棄重用的 CLI 後端工作階段 ID，並就地重新執行啟動／系統提示載入。
- `/compact [instructions]` 會壓縮工作階段脈絡。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `/stop` 會中止目前執行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理對話串繫結到期時間。
- `/reset soft [message]` 會保留目前逐字稿、捨棄重用的 CLI 後端工作階段 ID，並就地重新執行啟動/系統提示載入。
- `/compact [instructions]` 會壓縮工作階段內容。請參閱 [Compaction](/zh-TW/concepts/compaction)。
- `/stop` 會中止目前的執行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理討論串繫結到期時間。
- `/export-session [path]` 會將目前工作階段匯出為 HTML。別名：`/export`。
- `/export-trajectory [path]` 會要求 exec 核准，然後為目前工作階段匯出 JSONL [trajectory bundle](/zh-TW/tools/trajectory)。當你需要某個 OpenClaw 工作階段的提示、工具與轉錄稿時間軸時使用它。在群組聊天中，核准提示與匯出結果會私下傳給擁有者。別名：`/trajectory`。
- `/export-trajectory [path]` 會要求 exec 核准，然後為目前工作階段匯出 JSONL [軌跡組合包](/zh-TW/tools/trajectory)。當你需要某個 OpenClaw 工作階段的提示、工具與逐字稿時間軸時使用它。在群組聊天中，核准提示與匯出結果會私下傳送給擁有者。別名：`/trajectory`。
</Accordion>
<Accordion title="模型與執行控制">
- `/think <level>` 設定 thinking 層級。選項來自作用中模型的供應商 profile；常見層級為 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自訂層級僅在支援處可用。別名：`/thinking`, `/t`。
- `/think <level>` 設定思考層級。選項來自使用中模型的提供者設定檔；常見層級為 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自訂層級只在支援處可用。別名：`/thinking`、`/t`。
- `/verbose on|off|full` 切換詳細輸出。別名：`/v`。
- `/trace on|off` 切換目前工作階段的 Plugin trace 輸出。
- `/trace on|off` 切換目前工作階段的 Plugin 追蹤輸出。
- `/fast [status|on|off]` 顯示或設定快速模式。
- `/reasoning [on|off|stream]` 切換 reasoning 可見性。別名：`/reason`。
- `/elevated [on|off|ask|full]` 切換 elevated 模式。別名：`/elev`。
- `/reasoning [on|off|stream]` 切換推理可見性。別名：`/reason`。
- `/elevated [on|off|ask|full]` 切換提升模式。別名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 顯示或設定 exec 預設值。
- `/model [name|#|status]` 顯示或設定模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已設定／可用授權的供應商，或某個供應商的模型；加入 `all` 可瀏覽該供應商的完整目錄。
- `/queue <mode>` 管理佇列行為（`steer`、舊版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等選項；`/queue default` 或 `/queue reset` 會清除工作階段覆寫。請參閱 [命令佇列](/zh-TW/concepts/queue) 與 [Steering 佇列](/zh-TW/concepts/queue-steering)。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已設定/可用授權的提供者，或某個提供者的模型；加入 `all` 可瀏覽該提供者的完整目錄。
- `/queue <mode>` 管理佇列行為（`steer`、舊版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等選項；`/queue default` 或 `/queue reset` 會清除工作階段覆寫。請參閱 [指令佇列](/zh-TW/concepts/queue) 和 [Steering 佇列](/zh-TW/concepts/queue-steering)。
- `/steer <message>` 會將指引注入目前工作階段的執行中，不受 `/queue` 模式影響。當工作階段閒置時，它不會啟動新的執行。別名：`/tell`。請參閱 [Steer](/zh-TW/tools/steer)。
</Accordion>
<Accordion title="探索與狀態">
- `/help` 顯示簡短說明摘要。
- `/commands` 顯示產生的命令目錄。
- `/tools [compact|verbose]` 顯示目前 agent 現在可以使用的項目。
- `/status` 顯示執行／執行階段狀態，包括 `Execution`／`Runtime` 標籤，以及可用時的供應商用量／配額。
- `/diagnostics [note]` 是僅限擁有者的支援報告流程，用於 Gateway 錯誤與 Codex harness 執行。它每次都會在執行 `openclaw gateway diagnostics export --json` 前要求明確 exec 核准；請勿使用 allow-all 規則核准診斷。核准後，它會傳送可貼上的報告，包含本機 bundle 路徑、manifest 摘要、隱私權注意事項與相關工作階段 ID。在群組聊天中，核准提示與報告會私下傳給擁有者。當作用中工作階段使用 OpenAI Codex harness 時，同一項核准也會將相關 Codex 回饋傳送到 OpenAI 伺服器，且完成的回覆會列出 OpenClaw 工作階段 ID、Codex 對話串 ID，以及 `codex resume <thread-id>` 命令。請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。
- `/crestodian <request>` 會從擁有者 DM 執行 Crestodian 設定與修復輔助工具。
- `/tasks` 列出目前工作階段的作用中／近期背景工作。
- `/context [list|detail|json]` 說明脈絡是如何組合的。
- `/commands` 顯示產生的指令目錄。
- `/tools [compact|verbose]` 顯示目前代理現在可以使用的工具。
- `/status` 顯示執行/執行階段狀態，包括 `Execution`/`Runtime` 標籤，以及可用時的提供者使用量/配額。
- `/diagnostics [note]` 是僅限擁有者使用的支援報告流程，用於 Gateway 錯誤與 Codex harness 執行。每次執行 `openclaw gateway diagnostics export --json` 前都會要求明確的 exec 核准；請勿使用全允許規則核准診斷。核准後，它會傳送可貼上的報告，包含本機組合包路徑、manifest 摘要、隱私注意事項與相關工作階段 ID。在群組聊天中，核准提示與報告會私下傳送給擁有者。當使用中的工作階段使用 OpenAI Codex harness 時，同一個核准也會將相關 Codex 回饋傳送到 OpenAI 伺服器，且完成的回覆會列出 OpenClaw 工作階段 ID、Codex 討論串 ID，以及 `codex resume <thread-id>` 指令。請參閱 [診斷匯出](/zh-TW/gateway/diagnostics)。
- `/crestodian <request>` 從擁有者 DM 執行 Crestodian 設定與修復輔助工具。
- `/tasks` 列出目前工作階段的使用中/近期背景工作。
- `/context [list|detail|json]` 說明內容如何組合。
- `/whoami` 顯示你的傳送者 ID。別名：`/id`。
- `/usage off|tokens|full|cost` 控制每則回應的用量頁尾，或列印本機費用摘要。
- `/usage off|tokens|full|cost` 控制每個回覆的使用量頁尾，或列印本機成本摘要。
</Accordion>
<Accordion title="Skills、允許清單、核准">
- `/skill <name> [input]` 依名稱執行 skill。
- `/skill <name> [input]` 依名稱執行技能。
- `/allowlist [list|add|remove] ...` 管理允許清單項目。僅限文字。
- `/approve <id> <decision>` 解析 exec 核准提示。
- `/btw <question>` 提出附帶問題，而不變更未來工作階段脈絡。別名：`/side`。請參閱 [BTW](/zh-TW/tools/btw)。
- `/approve <id> <decision>` 解決 exec 核准提示。
- `/btw <question>` 詢問旁支問題，而不變更未來工作階段內容。別名：`/side`。請參閱 [BTW](/zh-TW/tools/btw)。
</Accordion>
<Accordion title="子代理與 ACP">
<Accordion title="子代理和 ACP">
- `/subagents list|kill|log|info|send|steer|spawn` 管理目前工作階段的子代理執行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 工作階段與執行階段選項。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 工作階段和執行階段選項。
- `/focus <target>` 將目前的 Discord 討論串或 Telegram 主題/對話繫結到工作階段目標。
- `/unfocus` 移除目前的繫結。
- `/agents` 列出目前工作階段中繫結到討論串的代理。
- `/kill <id|#|all>` 中止一個或所有正在執行的子代理。
- `/steer <id|#> <message>` 將引導訊息傳送給正在執行的子代理。別名：`/tell`。
- `/kill <id|#|all>` 中止一個或所有執行中的子代理。
- `/subagents steer <id|#> <message>` 向執行中的子代理傳送導引。請參閱 [導引](/zh-TW/tools/steer)。
</Accordion>
<Accordion title="僅擁有者寫入與管理">
<Accordion title="僅擁有者可寫入與管理">
- `/config show|get|set|unset` 讀取或寫入 `openclaw.json`。僅限擁有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 讀取或寫入 `mcp.servers` 下由 OpenClaw 管理的 MCP 伺服器設定。僅限擁有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 檢查或變更 Plugin 狀態。`/plugin` 是別名。寫入僅限擁有者。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理僅限執行階段的設定覆寫。僅限擁有者。需要 `commands.debug: true`。
- `/restart` 在啟用時重新啟動 OpenClaw。預設：啟用；設定 `commands.restart: false` 可將其停用。
- `/send on|off|inherit` 設定傳送政策。僅限擁有者。
- `/restart` 在啟用時重新啟動 OpenClaw。預設：已啟用；設定 `commands.restart: false` 可停用。
- `/send on|off|inherit` 設定傳送策略。僅限擁有者。
</Accordion>
<Accordion title="語音、TTS、頻道控制">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。請參閱 [TTS](/zh-TW/tools/tts)。
- `/activation mention|always` 設定群組啟用模式。
- `/bash <command>` 執行主機 Shell 命令。僅限文字。別名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` 允許清單。
- `!poll [sessionId]` 檢查背景 bash 作業。
- `!stop [sessionId]` 停止背景 bash 作業。
- `/bash <command>` 執行主機 shell 命令。僅文字。別名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` 允許清單。
- `!poll [sessionId]` 檢查背景 bash 工作。
- `!stop [sessionId]` 停止背景 bash 工作。
</Accordion>
</AccordionGroup>
@ -206,31 +207,32 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
### 產生的停靠命令
停靠命令會將目前工作階段的回覆路由切換到另一個已連結的
頻道。設定、範例與疑難排解請參閱[頻道停靠](/zh-TW/concepts/channel-docking)。
頻道。請參閱 [頻道停靠](/zh-TW/concepts/channel-docking) 以取得設定、
範例和疑難排解。
停靠命令由支援原生命令的頻道 Plugin 產生。目前內建集合：
停靠命令是從支援原生命令的頻道 Plugin 產生。目前內建集合：
- `/dock-discord`（別名：`/dock_discord`）
- `/dock-mattermost`（別名：`/dock_mattermost`）
- `/dock-slack`（別名：`/dock_slack`）
- `/dock-telegram`（別名：`/dock_telegram`）
從直接聊天使用停靠命令，可將目前工作階段的回覆路由切換到另一個已連結的頻道。代理會保留相同的工作階段內容，但該工作階段之後的回覆會傳送到選取的頻道對等端。
從直接聊天使用停靠命令，可將目前工作階段的回覆路由切換到另一個已連結的頻道。代理會保留相同的工作階段上下文，但該工作階段未來的回覆會傳送到所選的頻道對等端。
停靠命令需要 `session.identityLinks`。來源傳送者與目標對等端必須位於相同身分群組中，例如 `["telegram:123", "discord:456"]`。如果 id 為 `123` 的 Telegram 使用者傳送 `/dock_discord`，OpenClaw 會在作用中的工作階段上儲存 `lastChannel: "discord"` 與 `lastTo: "456"`。如果傳送者未連結到 Discord 對等端，命令會回覆設定提示，而不是落入一般聊天流程。
停靠命令需要 `session.identityLinks`。來源傳送者和目標對等端必須位於同一個身分群組中，例如 `["telegram:123", "discord:456"]`。如果 id 為 `123` 的 Telegram 使用者傳送 `/dock_discord`，OpenClaw 會在作用中的工作階段上儲存 `lastChannel: "discord"` 和 `lastTo: "456"`。如果傳送者未連結到 Discord 對等端，命令會回覆設定提示，而不是落入一般聊天流程。
停靠只會變更作用中工作階段路由。它不會建立頻道帳號、授予存取權、繞過頻道允許清單，或將逐字稿歷史移到另一個工作階段。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一個產生的停靠命令來再次切換路由。
停靠只會變更作用中工作階段的路由。它不會建立頻道帳號、授予存取權、略過頻道允許清單，或將逐字稿歷史移到另一個工作階段。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他產生的停靠命令再次切換路由。
### 內建 Plugin 命令
內建 Plugin 可以新增更多斜線命令。此 repo 中目前的內建命令：
內建 Plugin 可以新增更多斜線命令。此 repo 目前的內建命令：
- `/dreaming [on|off|status|help]` 切換記憶體 Dreaming。請參閱 [Dreaming](/zh-TW/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理裝置配對/設定流程。請參閱[配對](/zh-TW/channels/pairing)。
- `/dreaming [on|off|status|help]` 切換記憶 Dreaming。請參閱 [Dreaming](/zh-TW/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理裝置配對/設定流程。請參閱 [配對](/zh-TW/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 暫時啟用高風險手機 Node 命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 語音設定。在 Discord 上，原生命令名稱是 `/talkvoice`。
- `/card ...` 傳送 LINE 豐富卡片預設。請參閱 [LINE](/zh-TW/channels/line)。
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 檢查並控制內建 Codex 應用程式伺服器控管架構。請參閱 [Codex 控管架構](/zh-TW/plugins/codex-harness)。
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 檢查並控制內建 Codex app-server harness。請參閱 [Codex harness](/zh-TW/plugins/codex-harness)。
- 僅限 QQBot 的命令：
- `/bot-ping`
- `/bot-version`
@ -238,94 +240,94 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
- `/bot-upgrade`
- `/bot-logs`
### 動態 Skill 命令
### 動態 skill 命令
使用者可呼叫的 Skills 也會公開為斜線命令：
- `/skill <name> [input]` 一律可作為通用進入點使用。
- 當 Skill/Plugin 註冊時，Skills 也可能顯示為像 `/prose` 這樣的直接命令。
- 原生 Skill 命令註冊由 `commands.nativeSkills` 與 `channels.<provider>.commands.nativeSkills` 控制。
- 命令規格可以為支援在地化描述的原生介面提供 `descriptionLocalizations`，包括 Discord。
- `/skill <name> [input]` 永遠可作為通用進入點使用。
- 當 skill/Plugin 註冊時，skills 也可能以 `/prose` 這類直接命令出現。
- 原生 skill 命令註冊由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
- 命令規格可以為支援本地化描述的原生介面提供 `descriptionLocalizations`，包含 Discord。
<AccordionGroup>
<Accordion title="引數與剖析器注意事項">
- 命令接受命令與引數之間的選用 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型別名、`provider/model` 或供應商名稱（模糊比對）；如果沒有符合項目，文字會被視為訊息本文。
- 如需完整供應商用量細分，請使用 `openclaw status --usage`。
<Accordion title="引數和剖析器注意事項">
- 命令可在命令與引數之間接受選用的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型別名、`provider/model`，或提供者名稱（模糊比對）；若沒有相符項，文字會被視為訊息本文。
- 如需完整的提供者用量細分，請使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，並遵循頻道 `configWrites`。
- 在多帳號頻道中，以設定為目標的 `/allowlist --account <id>` 與 `/config set channels.<provider>.accounts.<id>...` 也會遵循目標帳號的 `configWrites`。
- 在多帳號頻道中，針對設定的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也會遵循目標帳號的 `configWrites`。
- `/usage` 控制每次回覆的用量頁尾；`/usage cost` 會從 OpenClaw 工作階段記錄列印本機成本摘要。
- `/restart` 預設為啟用；設定 `commands.restart: false` 可將其停用。
- `/plugins install <spec>` 接受與 `openclaw plugins install` 相同的 Plugin 規格：本機路徑/封存檔、npm 套件、`git:<repo>` 或 `clawhub:<pkg>`，然後因為 Plugin 原始碼模組已變更而要求 Gateway 重新啟動。
- `/plugins enable|disable` 更新 Plugin 設定，並為新的代理回合觸發 Gateway Plugin 重新載入。
- `/restart` 預設啟用；設定 `commands.restart: false` 可停用。
- `/plugins install <spec>` 接受與 `openclaw plugins install` 相同的 Plugin 規格：本機路徑/封存檔、npm 套件、`git:<repo>` 或 `clawhub:<pkg>`，然後因為 Plugin 來源模組已變更而要求重新啟動 Gateway。
- `/plugins enable|disable` 會更新 Plugin 設定，並為新的代理回合觸發 Gateway Plugin 重新載入。
</Accordion>
<Accordion title="頻道特定行為">
- 僅限 Discord 的原生命令：`/vc join|leave|status` 控制語音頻道（無法作為文字使用）。`join` 需要 guild 與選取的語音/stage 頻道。需要 `channels.discord.voice` 與原生命令。
- Discord 討論串繫結命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要有效啟用討論串繫結（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- 僅限 Discord 的原生命令：`/vc join|leave|status` 控制語音頻道（無法作為文字使用）。`join` 需要伺服器以及選取的語音/舞台頻道。需要 `channels.discord.voice` 和原生命令。
- Discord 討論串繫結命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要啟用有效的討論串繫結（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令參考與執行階段行為：[ACP 代理](/zh-TW/tools/acp-agents)。
</Accordion>
<Accordion title="詳細 / 追蹤 / 快速 / 推理安全">
- `/verbose` 用於偵錯與提供額外可見性；一般使用時請保持**關閉**。
- `/trace` 比 `/verbose` 範圍更窄：它只會顯示 Plugin 擁有的追蹤/偵錯行，並保持一般詳細工具雜訊關閉。
<Accordion title="詳細 / 追蹤 / 快速 / 推理安全性">
- `/verbose` 用於偵錯和提供額外可見性；一般使用時請保持**關閉**。
- `/trace` 比 `/verbose` 範圍更窄：它只會揭露 Plugin 擁有的追蹤/偵錯行，並保持一般詳細工具訊息關閉。
- `/fast on|off` 會保存工作階段覆寫。使用 Sessions UI 的 `inherit` 選項可清除它並退回設定預設值。
- `/fast` 依供應商而異：OpenAI/OpenAI Codex 會在原生 Responses 端點將它對應到 `service_tier=priority`，而直接公開 Anthropic 請求，包括傳送到 `api.anthropic.com` 的 OAuth 驗證流量，會將它對應到 `service_tier=auto` 或 `standard_only`。請參閱 [OpenAI](/zh-TW/providers/openai) 與 [Anthropic](/zh-TW/providers/anthropic)。
- 相關時仍會顯示工具失敗摘要，但只有在 `/verbose` 為 `on` 或 `full` 時才會包含詳細失敗文字。
- `/reasoning`、`/verbose` 與 `/trace` 在群組環境中有風險：它們可能揭露你不打算公開的內部推理、工具輸出或 Plugin 診斷。建議保持關閉，尤其是在群組聊天中。
- `/fast` 依提供者而異：OpenAI/OpenAI Codex 會在原生 Responses 端點上將其對應到 `service_tier=priority`，而直接公開的 Anthropic 請求，包含傳送到 `api.anthropic.com` 的 OAuth 驗證流量，會將其對應到 `service_tier=auto` 或 `standard_only`。請參閱 [OpenAI](/zh-TW/providers/openai) 和 [Anthropic](/zh-TW/providers/anthropic)。
- 工具失敗摘要在相關時仍會顯示，但詳細失敗文字只會在 `/verbose` 為 `on` 或 `full` 時包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群組環境中有風險：它們可能揭露你不打算公開的內部推理、工具輸出或 Plugin 診斷。建議保持關閉，尤其是在群組聊天中。
</Accordion>
<Accordion title="模型切換">
- `/model` 會立即保存新的工作階段模型。
- 如果代理處於閒置狀態，下一次執行會立即使用它。
- 如果已有執行處於作用中，OpenClaw 會將即時切換標記為待處理，並只會在乾淨的重試點重新啟動到新模型。
- 如果工具活動或回覆輸出已經開始，待處理切換可能會維持佇列狀態，直到稍後的重試機會或下一個使用者回合。
- 在本機 TUI 中，`/crestodian [request]` 會從一般代理 TUI 返回 Crestodian。這與訊息頻道救援模式分開，且不會授予遠端設定權限。
- 如果代理閒置，下一次執行會立刻使用它。
- 如果已有執行正在進行中，OpenClaw 會將即時切換標記為待處理，並只在乾淨的重試點重新啟動到新模型。
- 如果工具活動或回覆輸出已經開始，待處理切換可能會保持佇列狀態，直到稍後的重試機會或下一個使用者回合。
- 在本機 TUI 中，`/crestodian [request]` 會從一般代理 TUI 返回 Crestodian。這與訊息頻道救援模式分開，且不授予遠端設定權限。
</Accordion>
<Accordion title="快速路徑與行內捷徑">
- **快速路徑：** 來自允許清單傳送者的僅命令訊息會立即處理（繞過佇列 + 模型）。
- **群組提及閘控：** 來自允許清單傳送者的僅命令訊息會繞過提及需求。
- **行內捷徑（僅限允許清單傳送者）：** 某些命令嵌入一般訊息時也能運作，並會在模型看到剩餘文字之前被移除。
<Accordion title="快速路徑和行內捷徑">
- **快速路徑：** 來自允許清單傳送者且僅含命令的訊息會立即處理（略過佇列 + 模型）。
- **群組提及門檻：** 來自允許清單傳送者且僅含命令的訊息會略過提及需求。
- **行內捷徑（僅限允許清單傳送者）：** 某些命令嵌入一般訊息時也能運作，並且會在模型看到剩餘文字前被移除。
- 範例：`hey /status` 會觸發狀態回覆，剩餘文字則繼續走一般流程。
- 目前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授權的僅命令訊息會被靜默忽略，行內 `/...` 權杖會被視為純文字。
- 未授權的僅命令訊息會被靜默忽略，而行內 `/...` 權杖會被視為純文字。
</Accordion>
<Accordion title="Skill 命令與原生引數">
- **Skill 命令：** `user-invocable` Skills 會公開為斜線命令。名稱會清理為 `a-z0-9_`（最多 32 個字元）；衝突會取得數字尾碼（例如 `_2`）。
- `/skill <name> [input]` 依名稱執行 Skill（在原生命令限制阻止每個 Skill 一個命令時很有用）。
- 預設情況下，Skill 命令會作為一般請求轉送給模型。
- Skills 可選擇宣告 `command-dispatch: tool`，將命令直接路由到工具（確定性，無模型）。
<Accordion title="Skill 命令和原生引數">
- **Skill 命令：** `user-invocable` skills 會公開為斜線命令。名稱會清理為 `a-z0-9_`（最多 32 個字元）；衝突時會加上數字後綴（例如 `_2`）。
- `/skill <name> [input]` 依名稱執行 skill（當原生命令限制無法支援每個 skill 各自的命令時很有用）。
- 預設情況下，skill 命令會作為一般請求轉送給模型。
- Skills 可以選擇宣告 `command-dispatch: tool`，將命令直接路由到工具（確定性，無模型）。
- 範例：`/prose`（OpenProse Plugin）— 請參閱 [OpenProse](/zh-TW/prose)。
- **原生命令引數：** Discord 對動態選項使用自動完成（以及在你省略必要引數時使用按鈕選單）。當命令支援選項且你省略引數時，Telegram 與 Slack 會顯示按鈕選單。動態選項會依目標工作階段模型解析，因此像 `/think` 層級這類模型特定選項會遵循該工作階段的 `/model` 覆寫。
- **原生命令引數：** Discord 對動態選項使用自動完成（而當你省略必要引數時使用按鈕選單）。Telegram 和 Slack 會在命令支援選項且你省略引數時顯示按鈕選單。動態選項會依目標工作階段模型解析，因此 `/think` 層級等模型特定選項會遵循該工作階段的 `/model` 覆寫。
</Accordion>
</AccordionGroup>
## `/tools`
`/tools` 回答的是執行階段問題，而不是設定問題：**這個代理現在在這段對話中可以使用什麼**。
`/tools` 回答的是執行階段問題，而不是設定問題：**此代理現在在這段對話中可以使用什麼**。
- 預設 `/tools` 精簡且最佳化以便快速掃描。
- 預設 `/tools` 精簡，並針對快速瀏覽最佳化。
- `/tools verbose` 會加入簡短描述。
- 支援引數的原生命令介面會公開相同的模式切換為 `compact|verbose`。
- 結果以工作階段為範圍，因此變更代理、頻道、討論串、傳送者授權或模型都可能改變輸出。
- `/tools` 包含執行階段實際可存取的工具，包括核心工具、已連線的 Plugin 工具，以及頻道擁有的工具。
- 支援引數的原生命令介面會公開相同的模式切換 `compact|verbose`。
- 結果以工作階段為範圍，因此變更代理、頻道、討論串、傳送者授權或模型，都可能改變輸出。
- `/tools` 包含執行階段實際可達的工具，包含核心工具、已連接的 Plugin 工具和頻道擁有的工具。
若要編輯設定檔與覆寫，請使用 Control UI Tools 面板或設定/目錄介面，而不是將 `/tools` 視為靜態目錄。
若要編輯設定檔和覆寫，請使用 Control UI Tools 面板或設定/目錄介面，而不是將 `/tools` 視為靜態目錄。
## 用量介面（顯示位置）
## 使用介面（顯示位置）
- **提供者用量/配額**（範例：「Claude 剩餘 80%」）會在啟用用量追蹤時，針對目前的模型提供者顯示在 `/status` 中。OpenClaw 會將提供者的視窗標準化為「剩餘 %」；對於 MiniMax，僅剩餘百分比欄位會在顯示前反轉，而 `model_remains` 回應會優先使用聊天模型項目加上帶有模型標籤的方案標籤。
- **Token/快取行** 在 `/status` 中，當即時工作階段快照內容稀疏時，可以回退到最新的轉錄用量項目。既有的非零即時值仍然優先，而轉錄回退也可以在已儲存總數缺失或較小時，復原目前作用中的執行階段模型標籤，以及較大的提示導向總數。
- **執行與執行階段：** `/status` 會以 `Execution` 回報有效的沙盒路徑，並以 `Runtime` 回報實際執行工作階段的是誰：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 後端，或 ACP 後端。
- **每次回應的 token/成本** 由 `/usage off|tokens|full` 控制（附加到一般回覆）。
- `/model status` 是關於**模型/驗證/端點**，不是用量。
- **供應商用量/配額**（範例：「Claude 剩餘 80%」）會在啟用用量追蹤時，針對目前的模型供應商顯示於 `/status`。OpenClaw 會將供應商視窗正規化為「剩餘 %」；對於 MiniMax，只提供剩餘百分比的欄位會在顯示前反轉，而 `model_remains` 回應會優先使用聊天模型項目加上帶有模型標籤的方案標籤。
- **權杖/快取行** 在 `/status` 中，當即時工作階段快照資料稀疏時，可以退回使用最新的逐字稿用量項目。現有的非零即時值仍會優先採用，而逐字稿退回也能在已儲存總量缺失或較小時，恢復作用中的執行階段模型標籤，以及較大的、偏向提示的總量。
- **執行與執行階段：** `/status` 會針對有效的沙箱路徑回報 `Execution`，並針對實際執行工作階段的對象回報 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 後端，或 ACP 後端。
- **每次回應的權杖/成本** 由 `/usage off|tokens|full` 控制（附加到一般回覆）。
- `/model status` 關注的是 **模型/驗證/端點**，不是用量。
## 模型選擇（`/model`）
`/model` 實作為指令。
`/model` 是以指示實作。
範例：
@ -340,14 +342,14 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
注意事項：
- `/model` 和 `/model list` 會顯示精簡的編號選擇器（模型家族 + 可用提供者）。
- 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，包含提供者與模型下拉選單，以及送出步驟。
- `/model <#>` 會從該選擇器中選取（並在可能時優先使用目前提供者）。
- `/model status` 會顯示詳細檢視，包含已設定的提供者端點（`baseUrl`）與 API 模式（`api`）（如果可用）。
- `/model` 和 `/model list` 會顯示精簡的編號選擇器（模型系列 + 可用供應商）。
- 在 Discord 上，`/model` 和 `/models` 會開啟互動式選擇器，包含供應商與模型下拉選單，以及「提交」步驟。
- `/model <#>` 會從該選擇器中選取（並在可能時偏好目前供應商）。
- `/model status` 會顯示詳細檢視，包含已設定的供應商端點（`baseUrl`）和 API 模式（`api`，若可用）。
## 除錯覆寫
## 偵錯覆寫
`/debug` 可讓你設定**僅限執行階段**的設定覆寫（記憶體中，不寫入磁碟）。僅限擁有者。預設停用；使用 `commands.debug: true` 啟用。
`/debug` 可讓你設定 **僅限執行階段** 的設定覆寫（記憶體中，而非磁碟）。僅限擁有者。預設停用；使用 `commands.debug: true` 啟用。
範例：
@ -365,7 +367,7 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
## Plugin 追蹤輸出
`/trace` 可讓你切換**工作階段範圍的 Plugin 追蹤/除錯行**，而不需開啟完整詳細模式。
`/trace` 可讓你切換 **工作階段範圍的 Plugin 追蹤/偵錯行**，而不必開啟完整詳細模式。
範例：
@ -377,11 +379,11 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
注意事項：
- 不帶引數的 `/trace` 會顯示目前工作階段的追蹤狀態。
- 不帶引數的 `/trace` 會顯示目前的工作階段追蹤狀態。
- `/trace on` 會為目前工作階段啟用 Plugin 追蹤行。
- `/trace off` 會再次停用它們。
- Plugin 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。
- `/trace` 不會取代 `/debug`；`/debug` 仍然管理僅限執行階段的設定覆寫。
- `/trace` 不會取代 `/debug`；`/debug` 仍負責管理僅限執行階段的設定覆寫。
- `/trace` 不會取代 `/verbose`；一般詳細工具/狀態輸出仍屬於 `/verbose`。
## 設定更新
@ -416,12 +418,12 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
```
<Note>
`/mcp` 會將設定儲存在 OpenClaw 設定中，而不是 Pi 擁有的專案設定。執行階段配接器會決定哪些傳輸實際上可執行。
`/mcp` 會將設定儲存在 OpenClaw 設定中，而不是 Pi 擁有的專案設定。執行階段配接器會決定實際可執行哪些傳輸。
</Note>
## Plugin 更新
`/plugins` 可讓操作員檢視已探索到的 Plugins，並在設定中切換啟用狀態。唯讀流程可以使用 `/plugin` 作為別名。預設停用；使用 `commands.plugins: true` 啟用。
`/plugins` 可讓操作員檢查已發現的 Plugins，並在設定中切換啟用狀態。唯讀流程可使用 `/plugin` 作為別名。預設停用；使用 `commands.plugins: true` 啟用。
範例：
@ -434,46 +436,46 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
```
<Note>
- `/plugins list` 和 `/plugins show` 會針對目前工作區加上磁碟設定，使用真實的 Plugin 探索。
- `/plugins list` 和 `/plugins show` 會使用目前工作區加上磁碟設定，執行真正的 Plugin 探索。
- `/plugins install` 會從 ClawHub、npm、git、本機目錄和封存檔安裝。
- `/plugins enable|disable` 只會更新 Plugin 設定；它不會安裝或解除安裝 Plugins。
- 啟用與停用變更會熱重新載入 Gateway Plugin 執行階段介面，供新的代理回合使用；安裝會要求重新啟動 Gateway，因為 Plugin 原始模組已變更。
- 啟用與停用變更會為新的 agent 回合熱重新載入 Gateway Plugin 執行階段表面；安裝會要求重新啟動 Gateway，因為 Plugin 來源模組已變更。
</Note>
## 介面注意事項
## 表面注意事項
<AccordionGroup>
<Accordion title="每個介面的工作階段">
- **文字指令**會在一般聊天工作階段中執行（DM 共用 `main`，群組有自己的工作階段）。
- **原生命令**使用隔離工作階段：
<Accordion title="各表面的工作階段">
- **文字指令** 會在一般聊天工作階段中執行（私訊共用 `main`，群組有自己的工作階段）。
- **原生指令** 使用隔離工作階段：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前置字可透過 `channels.slack.slashCommand.sessionPrefix` 設定）
- Slack：`agent:<agentId>:slack:slash:<userId>`（前綴可透過 `channels.slack.slashCommand.sessionPrefix` 設定）
- Telegram：`telegram:slash:<userId>`（透過 `CommandTargetSessionKey` 指向聊天工作階段）
- **`/stop`** 會指向作用中的聊天工作階段，以便中止目前執行。
</Accordion>
<Accordion title="Slack 特定事項">
`channels.slack.slashCommand` 仍支援單一 `/openclaw` 風格命令。如果你啟用 `commands.native`，必須為每個內建命令建立一個 Slack 斜線命令（名稱與 `/help` 相同）。Slack 的命令引數選單會以暫時性 Block Kit 按鈕傳送。
`channels.slack.slashCommand` 仍支援單一 `/openclaw` 樣式指令。如果你啟用 `commands.native`，就必須為每個內建指令建立一個 Slack slash command（名稱與 `/help` 相同）。Slack 的指令引數選單會以臨時 Block Kit 按鈕傳送。
Slack 原生例外：註冊 `/agentstatus`（不是 `/status`），因為 Slack 保留了 `/status`。文字 `/status` 在 Slack 訊息中仍可運作。
Slack 原生例外：註冊 `/agentstatus`（不是 `/status`），因為 Slack 保留 `/status`。文字 `/status` 仍可在 Slack 訊息中運作。
</Accordion>
</AccordionGroup>
## BTW 旁支問題
## BTW 附帶問題
`/btw` 是關於目前工作階段的快速**旁支問題**。`/side` 是別名。
`/btw` 是針對目前工作階段的快速 **附帶問題**。`/side` 是別名。
不同於一般聊天：
- 它會使用目前工作階段作為背景脈絡，
- 它會作為獨立的**無工具**一次性呼叫執行，
- 它使用目前工作階段作為背景脈絡，
- 它會作為獨立的 **無工具** 一次性呼叫執行，
- 它不會改變未來的工作階段脈絡，
- 它不會寫入轉錄歷史，
- 它會作為即時旁支結果傳送，而不是一般助理訊息。
- 它不會寫入逐字稿歷史，
- 它會作為即時附帶結果傳送，而不是一般助理訊息。
這讓 `/btw` 在你想要臨時釐清，同時讓主要工作繼續進行時很有用。
這讓 `/btw` 適合在主要任務持續進行時，取得暫時性的釐清。
範例：
@ -482,7 +484,7 @@ Commands 由 Gateway 處理。大多數命令必須以**獨立**訊息傳送，
/side what changed while the main run continued?
```
完整行為與用戶端 UX 詳情，請參閱 [BTW 旁支問題](/zh-TW/tools/btw)。
完整行為與用戶端 UX 詳細資訊，請參閱 [BTW 附帶問題](/zh-TW/tools/btw)。
## 相關

74
docs/zh-TW/tools/steer.md Normal file
View File

@ -0,0 +1,74 @@
---
read_when:
- 在代理程式已在執行時使用 /steer 或 /tell
- 比較 /steer 與 /queue steer
- 判斷要引導目前的執行、子代理，還是 ACP 工作階段
sidebarTitle: Steer
summary: 在不變更佇列模式的情況下引導進行中的執行
title: 引導
x-i18n:
generated_at: "2026-05-04T02:46:33Z"
model: gpt-5.5
provider: openai
source_hash: 71e1c80c0eea86d5c3c29513d3ed0675c04779fc9c6ee3b8a76c4bedaa264d22
source_path: tools/steer.md
workflow: 16
---
`/steer` 會將指引傳送給已在作用中的執行。它用於「在這次執行仍在工作時調整它」的情境，而不是用來開始新的回合。
## 目前工作階段
使用頂層 `/steer` 來指定目前工作階段的作用中執行：
```text
/steer prefer the smaller patch and keep the tests focused
/tell summarize before making the next tool call
```
行為：
- 只指定目前工作階段的作用中執行。
- 獨立於工作階段的 `/queue` 模式運作。
- 當工作階段閒置時，不會開始新的執行。
- 當沒有可引導的作用中執行時，會回覆警告。
- 使用作用中 runtime 的引導路徑，因此模型會在下一個支援的 runtime 邊界看到該指引。
## 引導與佇列
`/queue steer` 會變更一般傳入訊息在執行作用中時到達的行為。`/steer <message>` 是明確命令，會嘗試在下一個支援的 runtime 邊界，將該命令的訊息注入作用中執行，不受已儲存的 `/queue` 設定影響。
使用：
- 當你想立即引導作用中執行時，使用 `/steer <message>`。
- 當你想讓未來的一般訊息預設引導作用中執行時，使用 `/queue steer`。
- 當新訊息應等待稍後回合，而不是引導作用中執行時，使用 `/queue collect` 或 `/queue followup`。
如需佇列模式與備援行為，請參閱[命令佇列](/zh-TW/concepts/queue)和[引導佇列](/zh-TW/concepts/queue-steering)。
## 子代理
當目標是子執行時，使用 `/subagents steer`：
```text
/subagents steer 2 focus only on the API surface
```
頂層 `/steer` 不會依 id 或清單索引選取子代理。它一律指定目前工作階段的作用中執行。請參閱[子代理](/zh-TW/tools/subagents)，了解子代理 id、標籤與控制命令。
## ACP 工作階段
當目標是 ACP harness 工作階段時，使用 `/acp steer`：
```text
/acp steer --session agent:main:acp:codex tighten the repro
```
請參閱 [ACP 代理](/zh-TW/tools/acp-agents)，了解 ACP 工作階段選取與 runtime 行為。
## 相關
- [斜線命令](/zh-TW/tools/slash-commands)
- [命令佇列](/zh-TW/concepts/queue)
- [引導佇列](/zh-TW/concepts/queue-steering)
- [子代理](/zh-TW/tools/subagents)

457
docs/zh-TW/tools/subagents.md
View File

@ -1,37 +1,41 @@
---
read_when:
- 您想透過代理程式進行背景或平行工作
- 你想透過代理程式進行背景或平行工作
- 你正在變更 sessions_spawn 或子代理工具政策
- 你正在實作或疑難排解綁定執行緒的子代理工作階段
- 您正在實作或疑難排解綁定執行緒的子代理工作階段
sidebarTitle: Sub-agents
summary: 啟動隔離的背景代理執行工作，並將結果回報至發出請求的聊天
summary: 啟動隔離的背景代理執行，並將結果回報至請求者的聊天對話
title: 子代理
x-i18n:
generated_at: "2026-05-02T21:06:23Z"
generated_at: "2026-05-04T02:46:41Z"
model: gpt-5.5
provider: openai
source_hash: 0e964df543bd19435daf94f2c85a34b9d32e07662405d2eac7635935f1e7bf64
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
source_path: tools/subagents.md
workflow: 16
---
子代理是從現有代理執行中產生的背景代理執行。
它們會在自己的工作階段中執行（`agent:<agentId>:subagent:<uuid>`），並在完成時將結果**公告**回請求者聊天頻道。每個子代理執行都會被追蹤為一個[背景工作](/zh-TW/automation/tasks)。
子代理是在既有代理執行中生成的背景代理執行。
它們會在自己的工作階段（`agent:<agentId>:subagent:<uuid>`）中執行，
並在完成後將結果**公告**回請求者聊天
頻道。每次子代理執行都會作為
[背景任務](/zh-TW/automation/tasks)追蹤。
主要目標：
- 平行處理「研究 / 長時間工作 / 慢速工具」工作，而不阻塞主要執行。
- 預設保持子代理隔離（工作階段分離 + 選用沙盒）。
- 讓工具介面難以誤用：子代理預設**不會**取得工作階段工具。
- 支援可設定的巢狀深度，以用於協調器模式。
- 平行處理「研究／長任務／慢速工具」工作，而不阻塞主要執行。
- 預設讓子代理保持隔離（工作階段分離 + 選用沙箱）。
- 讓工具介面難以被誤用：子代理預設**不會**取得工作階段工具。
- 支援可設定的巢狀深度，以配合協調器模式。
<Note>
**成本注意事項：**每個子代理預設都有自己的脈絡與權杖使用量。對於繁重或重複性的工作，請為子代理設定較便宜的模型，並讓主要代理使用較高品質的模型。可透過 `agents.defaults.subagents.model` 或個別代理覆寫進行設定。當子代理確實需要請求者目前的逐字稿時，代理可以在該次產生時要求 `context: "fork"`。繫結執行緒的子代理工作階段預設為 `context: "fork"`，因為它們會將目前對話分支到後續執行緒。
**成本注意事項：**每個子代理預設都有自己的上下文與權杖用量。對於繁重或重複性任務，請為子代理設定較便宜的模型，並讓主要代理使用較高品質的模型。可透過 `agents.defaults.subagents.model` 或個別代理覆寫設定。當子執行確實需要請求者目前的對話紀錄時，代理可以在該次生成時要求 `context: "fork"`。執行緒綁定的子代理工作階段預設為 `context: "fork"`，因為它們會把目前對話分支到後續執行緒。
</Note>
## 斜線命令
使用 `/subagents` 檢查或控制**目前工作階段**的子代理執行：
使用 `/subagents` 檢查或控制**目前
工作階段**的子代理執行：
```text
/subagents list
@ -43,11 +47,14 @@ x-i18n:
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
```
`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 id、逐字稿路徑、清理）。使用 `sessions_history` 取得有界且經安全篩選的回想檢視；需要原始完整逐字稿時，請檢查磁碟上的逐字稿路徑。
使用頂層 [`/steer <message>`](/zh-TW/tools/steer) 來引導目前請求者工作階段的作用中執行。當目標是子執行時，請使用 `/subagents steer <id|#> <message>`。
### 執行緒繫結控制
`/subagents info` 會顯示執行中繼資料（狀態、時間戳記、工作階段 ID、
對話紀錄路徑、清理）。使用 `sessions_history` 取得有界且經安全篩選的回想檢視；當你需要原始完整對話紀錄時，請檢查磁碟上的對話紀錄路徑。
這些命令適用於支援持久執行緒繫結的頻道。
### 執行緒綁定控制
這些命令可用於支援持久執行緒綁定的頻道。
請參閱下方的[支援執行緒的頻道](#thread-supporting-channels)。
```text
@ -58,141 +65,162 @@ x-i18n:
/session max-age <duration|off>
```
### 產生行為
### 生成行為
`/subagents spawn` 會以使用者命令啟動背景子代理（不是內部轉送），並在執行完成時將一則最終完成更新傳回請求者聊天。
`/subagents spawn` 會以使用者命令（而非內部轉送）啟動一個背景子代理，並在執行完成時將一則最終完成更新送回
請求者聊天。
<AccordionGroup>
<Accordion title="Non-blocking, push-based completion">
- 產生命令是非阻塞的；它會立即傳回執行 id。
- 完成時，子代理會向請求者聊天頻道公告摘要/結果訊息。
- 完成採用推送式。產生後，請**不要**為了等待完成而迴圈輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；只有在除錯或介入時才按需檢查狀態。
- 完成時，在公告清理流程繼續之前，OpenClaw 會盡力關閉該子代理工作階段開啟並追蹤的瀏覽器分頁/程序。
<Accordion title="非阻塞、推送式完成">
- 生成命令是非阻塞的；它會立即傳回執行 ID。
- 完成時，子代理會將摘要／結果訊息公告回請求者聊天頻道。
- 完成是推送式的。一旦生成後，請**不要**為了等待它完成而循環輪詢 `/subagents list`、`sessions_list` 或 `sessions_history`；只在除錯或介入時按需檢查狀態。
- 完成時，OpenClaw 會盡最大努力在公告清理流程繼續前，關閉該子代理工作階段開啟且已追蹤的瀏覽器分頁／程序。
</Accordion>
<Accordion title="Manual-spawn delivery resilience">
- OpenClaw 會先嘗試使用穩定的冪等性金鑰直接 `agent` 傳遞。
- 如果直接傳遞失敗，會退回佇列路由。
<Accordion title="手動生成交付韌性">
- OpenClaw 會先嘗試使用穩定的冪等性鍵進行直接 `agent` 交付。
- 如果直接交付失敗，會退回佇列路由。
- 如果佇列路由仍不可用，公告會以短暫的指數退避重試，然後才最終放棄。
- 完成傳遞會保留已解析的請求者路由：可用時，繫結執行緒或繫結對話的完成路由優先；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補上缺少的目標/帳號，讓直接傳遞仍可運作。
- 完成交付會保留已解析的請求者路由：可用時，執行緒綁定或對話綁定的完成路由優先；如果完成來源只提供頻道，OpenClaw 會從請求者工作階段已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）補齊遺失的目標／帳戶，讓直接交付仍可運作。
</Accordion>
<Accordion title="Completion handoff metadata">
交還給請求者工作階段的完成交接內容，是執行階段產生的內部脈絡（不是使用者撰寫的文字），並包含：
<Accordion title="完成交接中繼資料">
給請求者工作階段的完成交接是執行階段產生的內部上下文（不是使用者撰寫文字），並包含：
- `Result` — 最新可見的 `assistant` 回覆文字，否則為已清理的最新工具/toolResult 文字。終止失敗的執行不會重用擷取到的回覆文字。
- `Result` — 最新可見的 `assistant` 回覆文字；否則為經清理的最新工具／toolResult 文字。終止且失敗的執行不會重用已擷取的回覆文字。
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。
- 精簡的執行階段/權杖統計。
- 一項傳遞指示，要求請求者代理以一般助理語氣改寫（而不是轉送原始內部中繼資料）。
- 精簡的執行階段／權杖統計。
- 一則交付指示，要求請求者代理以一般助理語氣重寫（不要轉發原始內部中繼資料）。
</Accordion>
<Accordion title="Modes and ACP runtime">
<Accordion title="模式與 ACP 執行階段">
- `--model` 和 `--thinking` 會覆寫該特定執行的預設值。
- 使用 `info`/`log` 在完成後檢查詳細資料與輸出。
- `/subagents spawn` 是一次性模式（`mode: "run"`）。若要使用持久的繫結執行緒工作階段，請使用 `sessions_spawn` 搭配 `thread: true` 和 `mode: "session"`。
- 對於 ACP 控制程式工作階段（Claude Code、Gemini CLI、OpenCode，或明確的 Codex ACP/acpx），當工具宣告該執行階段時，請使用 `sessions_spawn` 搭配 `runtime: "acp"`。除錯完成或代理對代理迴圈時，請參閱 [ACP 傳遞模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` Plugin 時，Codex 聊天/執行緒控制應優先使用 `/codex ...`，而不是 ACP，除非使用者明確要求 ACP/acpx。
- OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙盒化，且已載入如 `acpx` 這類後端 Plugin。`runtime: "acp"` 需要外部 ACP 控制程式 id，或 `runtime.type="acp"` 的 `agents.list[]` 項目；對於來自 `agents_list` 的一般 OpenClaw 設定代理，請使用預設子代理執行階段。
- `/subagents spawn` 是一次性模式（`mode: "run"`）。若要使用持久執行緒綁定工作階段，請搭配 `thread: true` 和 `mode: "session"` 使用 `sessions_spawn`。
- 對於 ACP 控制器工作階段（Claude Code、Gemini CLI、OpenCode，或明確的 Codex ACP/acpx），當工具宣告該執行階段時，請搭配 `runtime: "acp"` 使用 `sessions_spawn`。除錯完成或代理對代理迴圈時，請參閱 [ACP 交付模型](/zh-TW/tools/acp-agents#delivery-model)。啟用 `codex` Plugin 時，除非使用者明確要求 ACP/acpx，否則 Codex 聊天／執行緒控制應偏好 `/codex ...` 而非 ACP。
- OpenClaw 會隱藏 `runtime: "acp"`，直到 ACP 已啟用、請求者未被沙箱化，且已載入例如 `acpx` 的後端 Plugin。`runtime: "acp"` 預期使用外部 ACP 控制器 ID，或具有 `runtime.type="acp"` 的 `agents.list[]` 項目；一般 OpenClaw 設定代理從 `agents_list` 使用預設子代理執行階段。
</Accordion>
</AccordionGroup>
## 脈絡模式
## 上下文模式
原生子代理會以隔離狀態啟動，除非呼叫端明確要求分支目前逐字稿。
原生子代理會以隔離方式啟動，除非呼叫端明確要求分支目前的對話紀錄。
| 模式 | 使用時機 | 行為 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在工作文字中簡要說明的事項 | 建立乾淨的子逐字稿。這是預設值，並能降低權杖使用量。 |
| `fork` | 依賴目前對話、先前工具結果，或請求者逐字稿中既有細緻指示的工作 | 在子代理開始前，將請求者逐字稿分支到子工作階段。 |
| `isolated` | 全新研究、獨立實作、慢速工具工作，或任何可在任務文字中簡報的事項 | 建立乾淨的子對話紀錄。這是預設值，並可降低權杖使用量。 |
| `fork` | 依賴目前對話、先前工具結果，或請求者對話紀錄中已存在的細緻指示的工作 | 在子執行開始前，將請求者對話紀錄分支到子工作階段。 |
請謹慎使用 `fork`。它用於對脈絡敏感的委派，而不是取代清楚撰寫工作提示。
請節制使用 `fork`。它是為了上下文敏感的委派，不是撰寫清楚任務提示的替代品。
## 工具：`sessions_spawn`
在全域 `subagent` 通道上以 `deliver: false` 啟動子代理執行，然後執行公告步驟，並將公告回覆發布到請求者聊天頻道。
在全域 `subagent` 通道上以 `deliver: false` 啟動子代理執行，
然後執行公告步驟，並將公告回覆發布到請求者
聊天頻道。
可用性取決於呼叫端的有效工具政策。`coding` 和 `full` 設定檔預設公開 `sessions_spawn`。`messaging` 設定檔不會；若應委派工作的代理需要，請加入 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` 或使用 `tools.profile: "coding"`。頻道/群組、提供者、沙盒，以及個別代理的允許/拒絕政策，仍可在設定檔階段後移除此工具。從相同工作階段使用 `/tools` 確認有效工具清單。
可用性取決於呼叫端的有效工具政策。`coding` 和
`full` 設定檔預設會公開 `sessions_spawn`。`messaging` 設定檔
不會；請加入 `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]`，或對應該委派工作的代理使用 `tools.profile: "coding"`。
頻道／群組、提供者、沙箱，以及個別代理的允許／拒絕政策，
仍可在設定檔階段後移除該工具。請在相同工作階段使用 `/tools`
確認有效工具清單。
**預設值：**
- **模型：**繼承呼叫端，除非你設定 `agents.defaults.subagents.model`（或個別代理的 `agents.list[].subagents.model`）；明確的 `sessions_spawn.model` 仍會優先。
- **思考：**繼承呼叫端，除非你設定 `agents.defaults.subagents.thinking`（或個別代理的 `agents.list[].subagents.thinking`）；明確的 `sessions_spawn.thinking` 仍會優先。
- **模型：**除非你設定 `agents.defaults.subagents.model`（或個別代理的 `agents.list[].subagents.model`），否則會繼承呼叫端；明確的 `sessions_spawn.model` 仍會優先。
- **Thinking：**除非你設定 `agents.defaults.subagents.thinking`（或個別代理的 `agents.list[].subagents.thinking`），否則會繼承呼叫端；明確的 `sessions_spawn.thinking` 仍會優先。
- **執行逾時：**如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 會在已設定時使用 `agents.defaults.subagents.runTimeoutSeconds`；否則退回 `0`（無逾時）。
### 工具參數
<ParamField path="task" type="string" required>
子代理的工作說明。
子代理的任務描述。
</ParamField>
<ParamField path="label" type="string">
選用的人類可讀標籤。
</ParamField>
<ParamField path="agentId" type="string">
在 `subagents.allowAgents` 允許時，於另一個代理 id 底下產生。
在 `subagents.allowAgents` 允許時，於另一個代理 ID 之下生成。
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` 僅適用於外部 ACP 控制程式（`claude`、`droid`、`gemini`、`opencode`，或明確要求的 Codex ACP/acpx），以及 `runtime.type` 為 `acp` 的 `agents.list[]` 項目。
`acp` 僅用於外部 ACP 控制器（`claude`、`droid`、`gemini`、`opencode`，或明確要求的 Codex ACP/acpx），以及其 `runtime.type` 為 `acp` 的 `agents.list[]` 項目。
</ParamField>
<ParamField path="resumeSessionId" type="string">
僅限 ACP。當 `runtime: "acp"` 時恢復現有 ACP 控制程式工作階段；原生子代理產生會忽略此項。
僅限 ACP。當 `runtime: "acp"` 時，繼續既有 ACP 控制器工作階段；原生子代理生成會忽略此參數。
</ParamField>
<ParamField path="streamTo" type='"parent"'>
僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理產生請省略。
僅限 ACP。當 `runtime: "acp"` 時，將 ACP 執行輸出串流到父工作階段；原生子代理生成請省略。
</ParamField>
<ParamField path="model" type="string">
覆寫子代理模型。無效值會被略過，子代理會在預設模型上執行，並在工具結果中附上警告。
覆寫子代理模型。無效值會被略過，子代理會在預設模型上執行，並在工具結果中顯示警告。
</ParamField>
<ParamField path="thinking" type="string">
覆寫子代理執行的思考層級。
覆寫子代理執行的 thinking 等級。
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
已設定時預設為 `agents.defaults.subagents.runTimeoutSeconds`，否則為 `0`。設定後，子代理執行會在 N 秒後中止。
</ParamField>
<ParamField path="thread" type="boolean" default="false">
當為 `true` 時，會為此子代理工作階段要求頻道執行緒繫結。
當為 `true` 時，會為此子代理工作階段要求頻道執行緒綁定。
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
如果 `thread: true` 且省略 `mode`，預設會變成 `session`。`mode: "session"` 需要 `thread: true`。
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
`"delete"` 會在公告後立即封存（仍會透過重新命名保留逐字稿）。
`"delete"` 會在公告後立即封存（仍會透過重新命名保留對話紀錄）。
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
`require` 會拒絕產生，除非目標子執行階段已沙盒化。
`require` 會拒絕生成，除非目標子執行階段已沙箱化。
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` 會將請求者目前逐字稿分支到子工作階段。僅限原生子代理。繫結執行緒的產生預設為 `fork`；非執行緒產生預設為 `isolated`。
`fork` 會將請求者目前的對話紀錄分支到子工作階段。僅限原生子代理。執行緒綁定生成預設為 `fork`；非執行緒生成預設為 `isolated`。
</ParamField>
<Warning>
`sessions_spawn` **不**接受頻道傳遞參數（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需傳遞，請從已產生的執行使用 `message`/`sessions_send`。
`sessions_spawn` **不**接受頻道交付參數（`target`、
`channel`、`to`、`threadId`、`replyTo`、`transport`）。若要交付，請從生成的執行使用
`message`/`sessions_send`。
</Warning>
## 繫結執行緒的工作階段
## 執行緒綁定工作階段
當頻道啟用執行緒繫結時，子代理可以保持繫結到某個執行緒，讓該執行緒中的後續使用者訊息持續路由到相同的子代理工作階段。
當頻道啟用執行緒綁定時，子代理可以保持綁定到
某個執行緒，讓該執行緒中的後續使用者訊息持續路由到
同一個子代理工作階段。
### 支援執行緒的頻道
**Discord** 目前是唯一支援的頻道。它支援持久的繫結執行緒子代理工作階段（`sessions_spawn` 搭配 `thread: true`）、手動執行緒控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及配接器金鑰 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSessions`。
**Discord** 目前是唯一支援的頻道。它支援
持久執行緒綁定的子代理工作階段（搭配
`thread: true` 的 `sessions_spawn`）、手動執行緒控制（`/focus`、`/unfocus`、`/agents`、
`/session idle`、`/session max-age`），以及配接器鍵
`channels.discord.threadBindings.enabled`、
`channels.discord.threadBindings.idleHours`、
`channels.discord.threadBindings.maxAgeHours` 和
`channels.discord.threadBindings.spawnSessions`。
### 快速流程
<Steps>
<Step title="Spawn">
`sessions_spawn` 搭配 `thread: true`（並可選擇搭配 `mode: "session"`）。
<Step title="生成">
搭配 `thread: true`（並可選擇搭配 `mode: "session"`）使用 `sessions_spawn`。
</Step>
<Step title="Bind">
OpenClaw 會在作用中的頻道中建立執行緒，或將執行緒繫結到該工作階段目標。
<Step title="綁定">
OpenClaw 會在作用中頻道中建立或綁定一個執行緒到該工作階段目標。
</Step>
<Step title="Route follow-ups">
該執行緒中的回覆與後續訊息會路由到已繫結的工作階段。
<Step title="路由後續訊息">
該執行緒中的回覆與後續訊息會路由到已綁定的工作階段。
</Step>
<Step title="Inspect timeouts">
使用 `/session idle` 檢查/更新因閒置而自動取消聚焦的設定，並使用 `/session max-age` 控制硬性上限。
<Step title="檢查逾時">
使用 `/session idle` 檢查／更新非作用狀態自動取消聚焦，並使用
`/session max-age` 控制硬性上限。
</Step>
<Step title="Detach">
使用 `/unfocus` 手動分離。
<Step title="解除附加">
使用 `/unfocus` 手動解除附加。
</Step>
</Steps>
@ -200,58 +228,57 @@ x-i18n:
| 指令 | 效果 |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | 將目前執行緒（或建立一個）綁定到子代理/session 目標 |
| `/unfocus` | 移除目前已綁定執行緒的綁定 |
| `/agents` | 列出作用中的執行與綁定狀態（`thread:<id>` 或 `unbound`） |
| `/session idle` | 檢查/更新閒置自動解除焦點（僅限已聚焦的綁定執行緒） |
| `/session max-age` | 檢查/更新硬性上限（僅限已聚焦的綁定執行緒） |
| `/focus <target>` | 將目前執行緒（或建立一個）繫結至子代理/工作階段目標 |
| `/unfocus` | 移除目前已繫結執行緒的繫結 |
| `/agents` | 列出作用中的執行與繫結狀態（`thread:<id>` 或 `unbound`） |
| `/session idle` | 檢查/更新閒置自動解除聚焦（僅限已聚焦的已繫結執行緒） |
| `/session max-age` | 檢查/更新硬性上限（僅限已聚焦的已繫結執行緒） |
### 設定開關
- **全域預設值：** `session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。
- **頻道覆寫與生成自動綁定鍵** 視配接器而定。請參閱上方的[支援執行緒的頻道](#thread-supporting-channels)。
- **頻道覆寫與產生時自動繫結鍵** 視配接器而定。請參閱上方的[支援執行緒的頻道](#thread-supporting-channels)。
請參閱[設定參考](/zh-TW/gateway/configuration-reference)與
[斜線指令](/zh-TW/tools/slash-commands)，了解目前的配接器詳細資訊。
請參閱[設定參考](/zh-TW/gateway/configuration-reference)和
[斜線指令](/zh-TW/tools/slash-commands)，以取得目前的配接器詳細資料。
### 允許清單
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
可透過明確 `agentId` 指定為目標的 agent ID 清單（`["*"]` 允許任何項目）。預設值：僅限請求者 agent。如果你設定了清單，且仍希望請求者能以 `agentId` 生成自身，請在清單中包含請求者 ID。
可透過明確 `agentId` 指定為目標的代理 ID 清單（`["*"]` 允許任何代理）。預設值：僅限請求端代理。如果你設定清單，且仍希望請求端能使用 `agentId` 產生自身，請在清單中加入請求端 ID。
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
當請求者 agent 未設定自己的 `subagents.allowAgents` 時使用的預設目標 agent 允許清單。
當請求端代理未設定自己的 `subagents.allowAgents` 時使用的預設目標代理允許清單。
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。每個 agent 的覆寫：`agents.list[].subagents.requireAgentId`。
封鎖省略 `agentId` 的 `sessions_spawn` 呼叫（強制明確選擇設定檔）。單一代理覆寫：`agents.list[].subagents.requireAgentId`。
</ParamField>
如果請求者 session 受沙箱限制，`sessions_spawn` 會拒絕
可能以非沙箱方式執行的目標。
如果請求端工作階段在沙箱中執行，`sessions_spawn` 會拒絕
將在非沙箱中執行的目標。
### 探索
使用 `agents_list` 查看哪些 agent ID 目前允許用於
`sessions_spawn`。回應會包含每個列出 agent 的有效
模型與嵌入式執行階段中繼資料，讓呼叫者能區分 Pi、Codex
app-server 與其他已設定的原生執行階段。
使用 `agents_list` 查看目前允許 `sessions_spawn` 的代理 ID。
回應會包含每個列出代理的有效模型與嵌入式執行階段中繼資料，
讓呼叫端能區分 Pi、Codex 應用程式伺服器，以及其他已設定的原生執行階段。
### 自動封存
- 子代理 session 會在 `agents.defaults.subagents.archiveAfterMinutes` 之後自動封存（預設 `60`）。
- 封存會使用 `sessions.delete`，並將逐字稿重新命名為 `*.deleted.<timestamp>`（同一資料夾）。
- `cleanup: "delete"` 會在 announce 後立即封存（仍會透過重新命名保留逐字稿）。
- 自動封存是盡力而為；如果 Gateway 重新啟動，待處理的計時器會遺失。
- `runTimeoutSeconds` **不會** 自動封存；它只會停止執行。session 會保留到自動封存為止。
- 自動封存同樣適用於深度 1 與深度 2 的 session。
- 瀏覽器清理與封存清理是分開的：追蹤的瀏覽器分頁/程序會在執行完成時盡力關閉，即使逐字稿/session 記錄仍被保留。
- 子代理工作階段會在 `agents.defaults.subagents.archiveAfterMinutes` 後自動封存（預設為 `60`）。
- 封存會使用 `sessions.delete`，並將記錄重新命名為 `*.deleted.<timestamp>`（同一資料夾）。
- `cleanup: "delete"` 會在回報後立即封存（仍會透過重新命名保留記錄）。
- 自動封存是盡力而為；如果 gateway 重新啟動，待處理的計時器會遺失。
- `runTimeoutSeconds` **不會**自動封存；它只會停止執行。工作階段會保留到自動封存為止。
- 自動封存同樣適用於深度 1 和深度 2 工作階段。
- 瀏覽器清理與封存清理是分開的：追蹤中的瀏覽器分頁/程序會在執行完成時盡力關閉，即使記錄/工作階段紀錄被保留也一樣。
## 巢狀子代理
預設情況下，子代理不能生成自己的子代理
（`maxSpawnDepth: 1`）。設定 `maxSpawnDepth: 2` 可啟用一層
巢狀結構，也就是**協調器模式**：主要 → 協調器子代理 →
工作子子代理。
預設情況下，子代理無法產生自己的子代理
（`maxSpawnDepth: 1`）。設定 `maxSpawnDepth: 2` 可啟用一層巢狀
結構，即**協調器模式**：主代理 → 協調器子代理 →
工作子代理的子代理。
```json5
{
@ -270,153 +297,149 @@ app-server 與其他已設定的原生執行階段。
### 深度層級
| 深度 | Session 鍵形狀 | 角色 | 可以生成？ |
| 深度 | 工作階段鍵形狀 | 角色 | 可以產生嗎？ |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | 主要 agent | 一律可以 |
| 0 | `agent:<id>:main` | 主代理 | 一律可以 |
| 1 | `agent:<id>:subagent:<uuid>` | 子代理（允許深度 2 時為協調器） | 僅當 `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子子代理（葉節點工作者） | 永不 |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子代理的子代理（葉節點工作代理） | 永不 |
### Announce 鏈
### 回報鏈
結果會沿著鏈往上回傳：
結果會沿著鏈向上流動：
1. 深度 2 工作者完成 → announce 給其父層（深度 1 協調器）。
2. 深度 1 協調器收到 announce、彙整結果並完成 → announce 給主要項目。
3. 主要 agent 收到 announce，並交付給使用者。
1. 深度 2 工作代理完成 → 回報給其父層（深度 1 協調器）。
2. 深度 1 協調器收到回報、整合結果、完成 → 回報給主代理。
3. 主代理收到回報並傳遞給使用者。
每一層只會看到其直接子層的 announce。
每一層只會看到來自其直接子層的回報。
<Note>
**操作指引：** 啟動子工作一次，然後等待完成
事件，而不是圍繞 `sessions_list`、
`sessions_history`、`/subagents list` 或 `exec` sleep 指令建立輪詢迴圈。
`sessions_list` 與 `/subagents list` 會讓子 session 關係
聚焦在即時工作上：即時子項會保持附加，已結束子項會在短暫的近期視窗中保持
可見，而過期的僅儲存子連結會在其新鮮度視窗後被
忽略。這可防止舊的 `spawnedBy` /
`parentSessionKey` 中繼資料在
重新啟動後重新喚回幽靈子項。如果子項完成事件在你已送出
最終答案後才抵達，正確的後續動作是精確的靜默 token
**操作指南：**啟動子層工作一次，然後等待完成事件，
而不是圍繞 `sessions_list`、`sessions_history`、`/subagents list`
或 `exec` 睡眠指令建立輪詢迴圈。
`sessions_list` 和 `/subagents list` 會讓子工作階段關係
聚焦於即時工作：即時子工作階段會保持附加，已結束的子工作階段會在短暫的近期視窗中保持可見，
而過時的僅儲存子連結會在其新鮮度視窗後被忽略。這能避免舊的 `spawnedBy` /
`parentSessionKey` 中繼資料在重新啟動後復活幽靈子層。
如果子層完成事件在你已送出最終答案後才抵達，正確的後續回應是完全靜默權杖
`NO_REPLY` / `no_reply`。
</Note>
### 依深度區分的工具政策
### 依深度的工具政策
- 角色與控制範圍會在生成時寫入 session 中繼資料。這可避免扁平或還原的 session 鍵意外重新取得協調器權限。
- **深度 1（協調器，當 `maxSpawnDepth >= 2`）：** 取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子項。其他 session/系統工具仍會被拒絕。
- **深度 1（葉節點，當 `maxSpawnDepth == 1`）：** 沒有 session 工具（目前的預設行為）。
- **深度 2（葉節點工作者）：** 沒有 session 工具，`sessions_spawn` 在深度 2 一律會被拒絕。無法再生成更多子項。
- 角色與控制範圍會在產生時寫入工作階段中繼資料。這可避免扁平或已還原的工作階段鍵意外重新取得協調器權限。
- **深度 1（協調器，當 `maxSpawnDepth >= 2` 時）：**取得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，因此可以管理其子層。其他工作階段/系統工具仍會被拒絕。
- **深度 1（葉節點，當 `maxSpawnDepth == 1` 時）：**沒有工作階段工具（目前預設行為）。
- **深度 2（葉節點工作代理）：**沒有工作階段工具，`sessions_spawn` 在深度 2 一律被拒絕。不能再產生更多子層。
### 每個 agent 的生成限制
### 單一代理產生限制
每個 agent session（任何深度）一次最多可以有 `maxChildrenPerAgent`
個作用中子項（預設 `5`）。這可防止單一協調器造成失控扇出。
每個代理工作階段（任何深度）同一時間最多可有 `maxChildrenPerAgent`
（預設 `5`）個作用中子層。這可避免單一協調器造成失控的扇出。
### 級聯停止
### 串聯停止
停止深度 1 協調器會自動停止其所有深度 2
子項：
子層：
- 主要聊天中的 `/stop` 會停止所有深度 1 agent，並級聯到其深度 2 子項。
- `/subagents kill <id>` 會停止特定子代理，並級聯到其子項。
- `/subagents kill all` 會停止請求者的所有子代理並級聯。
- 主聊天中的 `/stop` 會停止所有深度 1 代理，並串聯停止其深度 2 子層。
- `/subagents kill <id>` 會停止特定子代理，並串聯停止其子層。
- `/subagents kill all` 會停止請求端的所有子代理並串聯停止。
## 驗證
子代理驗證是依 **agent ID** 解析，而不是依 session 類型：
子代理驗證會依**代理 ID**解析，而不是依工作階段類型：
- 子代理 session 鍵為 `agent:<agentId>:subagent:<uuid>`。
- 驗證儲存會從該 agent 的 `agentDir` 載入。
- 主要 agent 的驗證設定檔會合併為**備援**；發生衝突時，agent 設定檔會覆寫主要設定檔。
- 子代理工作階段鍵為 `agent:<agentId>:subagent:<uuid>`。
- 驗證儲存會從該代理的 `agentDir` 載入。
- 主代理的驗證設定檔會作為**備援**合併；發生衝突時，代理設定檔會覆寫主設定檔。
合併是加成式的，因此主要設定檔一律可作為
備援使用。尚不支援每個 agent 完全隔離的驗證。
合併是加成式的，因此主設定檔永遠可作為備援使用。
尚未支援每個代理完全隔離的驗證。
## Announce
## 回報
子代理會透過 announce 步驟回報：
子代理會透過回報步驟回傳：
- announce 步驟在子代理 session 內執行（不是請求者 session）。
- 如果子代理精確回覆 `ANNOUNCE_SKIP`，則不會張貼任何內容。
- 如果最新的 assistant 文字是精確的靜默 token `NO_REPLY` / `no_reply`，即使先前存在可見進度，也會抑制 announce 輸出。
- 回報步驟在子代理工作階段內執行（不是請求端工作階段）。
- 如果子代理精確回覆 `ANNOUNCE_SKIP`，就不會發布任何內容。
- 如果最新的助理文字是完全靜默權杖 `NO_REPLY` / `no_reply`，即使先前已有可見進度，回報輸出也會被抑制。
交付取決於請求者深度：
傳遞方式取決於請求端深度：
- 頂層請求者 session 會使用帶有外部交付的後續 `agent` 呼叫（`deliver=true`）。
- 巢狀請求者 subagent session 會收到內部後續注入（`deliver=false`），讓協調器能在 session 內彙整子項結果。
- 如果巢狀請求者 subagent session 已不存在，OpenClaw 會在可用時退回到該 session 的請求者。
- 最上層請求端工作階段會使用帶外部傳遞的後續 `agent` 呼叫（`deliver=true`）。
- 巢狀請求端子代理工作階段會收到內部後續注入（`deliver=false`），讓協調器能在工作階段內整合子層結果。
- 如果巢狀請求端子代理工作階段已不存在，OpenClaw 會在可用時退回使用該工作階段的請求端。
對於頂層請求者 session，完成模式的直接交付會先
解析任何已綁定的對話/執行緒路由與 hook 覆寫，然後從
請求者 session 儲存的路由填入缺少的頻道目標欄位。
這可確保完成結果留在正確的聊天/主題中，即使完成
來源只識別了頻道。
對最上層請求端工作階段而言，完成模式的直接傳遞會先
解析任何已繫結的對話/執行緒路由和 hook 覆寫，然後從
請求端工作階段儲存的路由補齊缺少的頻道目標欄位。
這能讓完成訊息停留在正確的聊天/主題中，即使完成來源
只識別頻道也是如此。
建立巢狀完成發現項目時，子項完成彙總會限定在目前請求者執行範圍內，
防止過去執行的過期子項
輸出洩漏到目前 announce。當頻道配接器可用時，announce 回覆會保留
執行緒/主題路由。
建立巢狀完成發現時，子層完成彙總會限定於目前請求端執行，
避免過時的先前執行子層輸出洩漏到目前回報中。當頻道配接器
提供執行緒/主題路由時，回報回覆會保留該路由。
### Announce 內容脈絡
### 回報內容
Announce 內容脈絡會正規化為穩定的內部事件區塊：
回報內容會正規化為穩定的內部事件區塊：
| 欄位 | 來源 |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| 來源 | `subagent` 或 `cron` |
| Session ID | 子 session 鍵/ID |
| 類型 | Announce 類型 + 任務標籤 |
| 狀態 | 從執行階段結果衍生（`success`、`error`、`timeout` 或 `unknown`）— **不是** 從模型文字推斷 |
| 結果內容 | 最新可見的 assistant 文字，否則為已清理的最新 tool/toolResult 文字 |
| 後續動作 | 描述何時回覆與何時保持靜默的指示 |
| 欄位 | 來源 |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| 來源 | `subagent` 或 `cron` |
| 工作階段 ID | 子工作階段鍵/ID |
| 類型 | 回報類型 + 工作標籤 |
| 狀態 | 從執行階段結果衍生（`success`、`error`、`timeout` 或 `unknown`），**不是**從模型文字推斷 |
| 結果內容 | 最新可見助理文字，否則為經清理的最新工具/toolResult 文字 |
| 後續 | 描述何時回覆與何時保持靜默的指示 |
終端失敗執行會回報失敗狀態，而不重播擷取到的
回覆文字。逾時時，如果子項只完成了工具呼叫，announce
可以將該歷史壓縮成簡短的部分進度摘要，而不是
回覆文字。逾時時，如果子層只完成工具呼叫，回報
可以將該歷史折疊成簡短的部分進度摘要，而不是
重播原始工具輸出。
### 統計列
### 統計行
Announce 承載內容會在結尾包含統計列（即使被包裝時也是如此）：
回報承載會在結尾包含統計行（即使被包裝也一樣）：
- 執行階段（例如 `runtime 5m12s`）。
- Token 使用量（輸入/輸出/總計）。
- 設定模型定價時的估計成本（`models.providers.*.models[].cost`）。
- `sessionKey`、`sessionId` 與逐字稿路徑，讓主要 agent 能透過 `sessions_history` 擷取歷史，或檢查磁碟上的檔案。
- 權杖使用量（輸入/輸出/總計）。
- 當已設定模型定價時的估算成本（`models.providers.*.models[].cost`）。
- `sessionKey`、`sessionId` 和記錄路徑，讓主代理可透過 `sessions_history` 擷取歷史，或檢查磁碟上的檔案。
內部中繼資料僅用於協調；面向使用者的回覆
應以一般 assistant 語氣重寫。
內部中繼資料僅供協調使用；面向使用者的回覆
應以一般助理語氣重寫。
### 為何偏好 `sessions_history`
`sessions_history` 是較安全的協調路徑：
- Assistant 回憶會先正規化：移除 thinking 標籤；移除 `<relevant-memories>` / `<relevant_memories>` 腳手架；移除純文字工具呼叫 XML 承載區塊（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`），包括從未乾淨關閉的截斷承載；移除降級的工具呼叫/結果腳手架與歷史脈絡標記；移除洩漏的模型控制 token（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。
- 類似憑證/token 的文字會被遮蔽。
- 長區塊可以被截斷。
- 非常大的歷史可以丟棄較舊的列，或用 `[sessions_history omitted: message too large]` 取代過大的列。
- 當你需要完整逐位元組一致的逐字稿時，原始磁碟逐字稿檢查是備援方式。
- 助理回憶會先正規化：移除 thinking 標籤；移除 `<relevant-memories>` / `<relevant_memories>` 鷹架；移除純文字工具呼叫 XML 承載區塊（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`），包含永遠未乾淨閉合的截斷承載；移除降級的工具呼叫/結果鷹架和歷史內容標記；移除洩漏的模型控制權杖（`<|assistant|>`、其他 ASCII `<|...|>`、全形 `<｜...｜>`）；移除格式錯誤的 MiniMax 工具呼叫 XML。
- 憑證/類似權杖的文字會被遮蔽。
- 長區塊可被截斷。
- 非常大的歷史可捨棄較舊列，或用 `[sessions_history omitted: message too large]` 取代過大的列。
- 當你需要完整逐位元組一致的記錄時，原始磁碟記錄檢查是備援方式。
## 工具政策
子代理會先使用與父層或目標 agent 相同的設定檔與工具政策
管線。之後，OpenClaw 會套用子代理限制
層。
子代理會先使用與父代理或目標代理相同的設定檔和工具政策
管線。之後，OpenClaw 會套用子代理限制層。
在沒有具限制性的 `tools.profile` 時，子代理會取得**除了
session 工具**與系統工具以外的**所有工具**：
若沒有具限制性的 `tools.profile`，子代理會取得**除了
工作階段工具**和系統工具之外的所有工具：
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
`sessions_history` 在這裡也仍是有界且已清理的回憶視圖，
不是原始逐字稿傾印。
`sessions_history` 在此仍是有界且經清理的回憶檢視，並
不是原始記錄傾印。
當 `maxSpawnDepth >= 2` 時，深度 1 協調器子代理會額外
收到 `sessions_spawn`、`subagents`、`sessions_list` 與
`sessions_history`，以便管理其子項。
收到 `sessions_spawn`、`subagents`、`sessions_list` 和
`sessions_history`，因此可以管理其子層。
### 透過設定覆寫
@ -443,10 +466,10 @@ session 工具**與系統工具以外的**所有工具**：
```
`tools.subagents.tools.allow` 是最終的僅允許篩選器。它可以縮小
已解析的工具集，但無法**加回**已被 `tools.profile` 移除的工具。
已解析的工具集，但無法**加回**已由 `tools.profile` 移除的工具。
例如，`tools.profile: "coding"` 包含 `web_search`/`web_fetch`，
但不包含 `browser` 工具。若要讓 coding-profile 子代理使用瀏覽器自動化，
請在設定檔階段加入 browser：
請在 profile 階段加入 browser：
```json5
{
@ -457,53 +480,55 @@ session 工具**與系統工具以外的**所有工具**：
}
```
當只有一個代理應取得瀏覽器自動化能力時，請使用每代理的 `agents.list[].tools.alsoAllow: ["browser"]`。
當只有單一代理應取得瀏覽器自動化時，請使用每個代理的 `agents.list[].tools.alsoAllow: ["browser"]`。
## 並行
子代理使用專用的進程內佇列通道：
子代理使用專用的程序內佇列通道：
- **通道名稱：** `subagent`
- **並行數：** `agents.defaults.subagents.maxConcurrent`（預設為 `8`）
- **並行數：** `agents.defaults.subagents.maxConcurrent`（預設 `8`）
## 活性與復原
## 存活性與復原
OpenClaw 不會將缺少 `endedAt` 視為子代理仍然存活的永久證明。
早於過時執行時間窗的未結束執行，不再於 `/subagents list`、狀態摘要、
後代完成閘控，以及每工作階段並行檢查中計為作用中/待處理。
OpenClaw 不會把缺少 `endedAt` 視為子代理仍然存活的永久證明。
早於過期執行時間窗且未結束的執行，會停止在 `/subagents list`、狀態摘要、
子代完成門檻，以及每個工作階段的並行檢查中計為作用中/待處理。
Gateway 重新啟動後，過時且未結束的已還原執行會被修剪，除非其子工作階段
標記為 `abortedLastRun: true`。這些因重新啟動而中止的子工作階段仍可透過
子代理孤立復原流程恢復；該流程會先傳送合成的恢復訊息，再清除中止標記。
Gateway 重新啟動後，除非其子工作階段標記為 `abortedLastRun: true`，
否則過期且未結束的已還原執行會被剪除。這些因重新啟動而中止的子工作階段，
仍可透過子代理孤兒復原流程復原；該流程會先傳送合成的恢復訊息，
再清除中止標記。
自動重新啟動復原會按每個子工作階段設限。若同一個子代理子項在快速重新卡住
時間窗內反覆被接受進行孤立復原，OpenClaw 會在該工作階段上持久化復原墓碑，
自動重新啟動復原會以每個子工作階段為界限。如果同一個子代理子項在快速重卡住時間窗內
反覆被接受進行孤兒復原，OpenClaw 會在該工作階段上保留復原墓碑，
並在後續重新啟動時停止自動恢復它。執行 `openclaw tasks maintenance --apply`
以協調任務記錄，或執行 `openclaw doctor --fix` 以清除墓碑工作階段上過時的
中止復原旗標。
以協調任務記錄，或執行 `openclaw doctor --fix` 以清除已設墓碑工作階段上的
過期中止復原旗標。
<Note>
如果子代理生成因 Gateway `PAIRING_REQUIRED` / `scope-upgrade` 而失敗，
請先檢查 RPC 呼叫端，再編輯配對狀態。內部 `sessions_spawn` 協調應以
`client.id: "gateway-client"` 搭配 `client.mode: "backend"`，透過直接
loopback 共享 token/密碼驗證進行連線；該路徑不依賴 CLI 的已配對裝置範圍基準。
遠端呼叫端、明確的 `deviceIdentity`、明確的裝置 token 路徑，以及瀏覽器/node
用戶端仍需一般裝置核准才能進行範圍升級。
如果子代理產生失敗並出現 Gateway `PAIRING_REQUIRED` /
`scope-upgrade`，請先檢查 RPC 呼叫端，再編輯配對狀態。
內部 `sessions_spawn` 協調應透過直接 loopback 共享權杖/密碼驗證，
以 `client.id: "gateway-client"` 和 `client.mode: "backend"` 連線；
該路徑不依賴 CLI 的已配對裝置範圍基準。遠端呼叫端、明確的
`deviceIdentity`、明確的裝置權杖路徑，以及瀏覽器/node 用戶端，
仍需要一般裝置核准才能進行範圍升級。
</Note>
## 停止
- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止由其生成的任何作用中子代理執行，連鎖套用至巢狀子項。
- `/subagents kill <id>` 會停止指定的子代理，並連鎖停止其子項。
- 在請求者聊天中傳送 `/stop` 會中止請求者工作階段，並停止從中產生的任何作用中子代理執行，連鎖套用至巢狀子項。
- `/subagents kill <id>` 會停止特定子代理，並連鎖停止其子項。
## 限制
- 子代理公告是**盡力而為**。如果 gateway 重新啟動，待處理的「公告回傳」工作會遺失。
- 子代理仍共用相同的 gateway 行程資源；請將 `maxConcurrent` 視為安全閥。
- `sessions_spawn` 一律為非阻塞：它會立即回傳 `{ status: "accepted", runId, childSessionKey }`。
- 子代理內容脈絡只注入 `AGENTS.md` + `TOOLS.md`（沒有 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。
- 子代理公告是**盡力而為**。如果 gateway 重新啟動，待處理的「回報公告」工作會遺失。
- 子代理仍共用相同的 gateway 程序資源；請將 `maxConcurrent` 視為安全閥。
- `sessions_spawn` 一律為非阻塞：它會立即傳回 `{ status: "accepted", runId, childSessionKey }`。
- 子代理內容只注入 `AGENTS.md` + `TOOLS.md`（沒有 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。
- 最大巢狀深度為 5（`maxSpawnDepth` 範圍：1–5）。大多數使用案例建議使用深度 2。
- `maxChildrenPerAgent` 限制每個工作階段的作用中子項數量（預設 `5`，範圍 `1–20`）。
- `maxChildrenPerAgent` 會限制每個工作階段的作用中子項數量（預設 `5`，範圍 `1–20`）。
## 相關

163
docs/zh-TW/tools/thinking.md
View File

@ -1,140 +1,143 @@
---
read_when:
- 調整思考、快速模式或詳細指令的解析或預設值
summary: 用於 /think、/fast、/verbose、/trace 與推理可見性的指令語法
- 調整思考、快速模式或詳細指令的剖析或預設值
summary: /think、/fast、/verbose、/trace 的指令語法與推理可見性
title: 思考層級
x-i18n:
generated_at: "2026-04-30T16:30:54Z"
generated_at: "2026-05-04T02:46:38Z"
model: gpt-5.5
provider: openai
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
source_path: tools/thinking.md
workflow: 16
---
## 功能說明
## 功能
- 任何傳入本文中的行內指令：`/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 動態思考）
- 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`。
- `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`。
- 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 會省略停用推理的 payload，而不是傳送不支援的值。
- 自訂 OpenAI 相容目錄項目可以透過設定 `models.providers.<provider>.models[].compat.supportedReasoningEfforts` 包含 `"xhigh"`，選擇加入 `/think xhigh`。這會使用相同的 compat 中繼資料來對應傳出的 OpenAI 推理 effort payload，因此選單、工作階段驗證、代理 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` delta。
- 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`。
- Moonshot（`moonshot/*`）會將 `/think off` 對應到 `thinking: { type: "disabled" }`，並將任何非 `off` 層級對應到 `thinking: { type: "enabled" }`。啟用思考時，Moonshot 只接受 `tool_choice` `auto|none`；OpenClaw 會將不相容的值正規化為 `auto`。
## 解析順序
1. 訊息上的行內指令（只套用於該訊息）。
2. 工作階段覆寫（透過傳送僅含指令的訊息設定）。
3. 個別代理預設值（設定中的 `agents.list[].thinkingDefault`）。
2. 工作階段覆寫（透過傳送只有指令的訊息設定）。
3. 每個代理程式預設值（設定中的 `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:medium` 或 `/t high`。
- 該設定會在目前工作階段中持續有效（預設依傳送者區分）；可由 `/think:off` 或工作階段閒置重設清除。
- 會傳送確認回覆（`Thinking level set to high.` / `Thinking disabled.`）。如果層級無效（例如 `/thinking big`），指令會以提示拒絕，且工作階段狀態保持不變。
- 傳送沒有引數的 `/think`（或 `/think:`）可查看目前思考層級。
## 依代理套用
## 依代理程式套用
- **嵌入式 Pi**：解析後的層級會傳遞給處理程序內的 Pi 代理執行階段。
- **嵌入式 Pi**：已解析的層級會傳遞給處理程序內 Pi 代理程式執行階段。
## 快速模式（/fast）
- 層級：`on|off`。
- 僅含指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。
- 傳送不帶模式的 `/fast`（或 `/fast status`）即可查看目前有效的快速模式狀態。
- 只有指令的訊息會切換工作階段快速模式覆寫，並回覆 `Fast mode enabled.` / `Fast mode disabled.`。
- 傳送沒有模式的 `/fast`（或 `/fast status`）可查看目前有效的快速模式狀態。
- OpenClaw 會依此順序解析快速模式：
1. 行內/僅指令 `/fast on|off`
1. 行內/只有指令的 `/fast on|off`
2. 工作階段覆寫
3. 個別代理預設值（`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` 切換。
3. 每個代理程式預設值（`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`。
- 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 重寫為 `MiniMax-M2.7-highspeed`。
- 同時設定時，明確的 Anthropic `serviceTier` / `service_tier` 模型參數會覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理 base URL 略過 Anthropic 服務層級注入。
- `/status` 只有在啟用快速模式時才會顯示 `Fast`。
- 對於 Anthropic 相容路徑上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）會將 `MiniMax-M2.7` 改寫為 `MiniMax-M2.7-highspeed`。
- 明確的 Anthropic `serviceTier` / `service_tier` 模型參數會在兩者都設定時覆寫快速模式預設值。OpenClaw 仍會對非 Anthropic 代理基底 URL 略過 Anthropic 服務層級注入。
- `/status` 只會在啟用快速模式時顯示 `Fast`。
## 詳細指令（/verbose 或 /v）
- 層級：`on`（最小）| `full` | `off`（預設）。
- 僅含指令的訊息會切換工作階段詳細模式，並回覆 `Verbose logging enabled.` / `Verbose logging disabled.`；無效層級會回傳提示且不變更狀態。
- `/verbose off` 會儲存明確的工作階段覆寫；可在 Sessions UI 中選擇 `inherit` 來清除。
- 行內指令只影響該訊息；否則會套用工作階段/全域預設值。
- 傳送不帶引數的 `/verbose`（或 `/verbose:`）即可查看目前詳細層級。
- 啟用詳細模式時，會發出結構化工具結果的代理（Pi、其他 JSON 代理）會將每次工具呼叫作為自己的僅中繼資料訊息傳回，可用時前綴為 `<emoji> <tool-name>: <arg>`（路徑/指令）。這些工具摘要會在每個工具開始時立即傳送（分開的氣泡），而不是作為串流 delta。
- 工具失敗摘要在一般模式中仍會顯示，但原始錯誤詳細資料後綴會隱藏，除非詳細模式為 `on` 或 `full`。
- 當詳細模式為 `full` 時，工具輸出也會在完成後轉送（分開的氣泡，截斷到安全長度）。如果你在執行期間切換 `/verbose 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`
## Plugin 追蹤指令（/trace）
- 層級：`on` | `off`（預設）。
- 僅含指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 行內指令只影響該訊息；否則會套用工作階段/全域預設值。
- 傳送不帶引數的 `/trace`（或 `/trace:`）即可查看目前追蹤層級。
- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 擁有的追蹤/偵錯行，例如 Active Memory 偵錯摘要。
- 追蹤行可能出現在 `/status` 中，也可能在一般助理回覆後作為後續診斷訊息出現。
- 只有指令的訊息會切換工作階段 Plugin 追蹤輸出，並回覆 `Plugin trace enabled.` / `Plugin trace disabled.`。
- 行內指令只影響該訊息；否則套用工作階段/全域預設值。
- 傳送沒有引數的 `/trace`（或 `/trace:`）可查看目前追蹤層級。
- `/trace` 比 `/verbose` 範圍更窄：它只公開 Plugin 所屬的追蹤/偵錯行，例如 Active Memory 偵錯摘要。
- 追蹤行可以出現在 `/status` 中，也可以作為一般助理回覆後的後續診斷訊息。
## 推理可見性（/reasoning）
- 層級：`on|off|stream`。
- 僅含指令的訊息會切換是否在回覆中顯示思考區塊。
- 啟用時，推理會作為**獨立訊息**傳送，並以前綴 `Reasoning:` 開頭。
- `stream`（僅 Telegram）：在產生回覆時將推理串流到 Telegram 草稿氣泡，然後傳送不含推理的最終答案。
- 只有指令的訊息會切換是否在回覆中顯示思考區塊。
- 啟用時，推理會作為**分開的訊息**傳送，前置 `Reasoning:`。
- `stream`（僅 Telegram）：在產生回覆時將推理串流到 Telegram 草稿訊息泡泡，然後傳送不含推理的最終答案。
- 別名：`/reason`。
- 傳送不帶引數的 `/reasoning`（或 `/reasoning:`）即可查看目前推理層級。
- 解析順序：行內指令，接著工作階段覆寫，接著個別代理預設值（`agents.list[].reasoningDefault`），最後回退（`off`）。
- 傳送沒有引數的 `/reasoning`（或 `/reasoning:`）可查看目前推理層級。
- 解析順序：行內指令，接著是工作階段覆寫，再來是每個代理程式預設值（`agents.list[].reasoningDefault`），最後是後援（`off`）。
格式不正確的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊會在一般回覆中維持隱藏，已可見文字後未封閉的推理也會隱藏。如果回覆完整包在單一未封閉開啟標籤中，且原本會作為空文字傳送，OpenClaw 會移除格式不正確的開啟標籤並傳送剩餘文字。
格式錯誤的本機模型推理標籤會保守處理。封閉的 `<think>...</think>` 區塊會在一般回覆中保持隱藏，且已可見文字之後未封閉的推理也會隱藏。如果回覆完全包在單一未封閉的開頭標籤中，且否則會傳送為空文字，OpenClaw 會移除格式錯誤的開頭標籤並傳送剩餘文字。
## 相關內容
## 相關
- Elevated mode 文件位於 [Elevated mode](/zh-TW/tools/elevated)。
- 提權模式文件位於[提權模式](/zh-TW/tools/elevated)。
## Heartbeats
## 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 傳遞預設只傳送最終 payload。若也要傳送獨立的 `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` 或每個代理程式的 `agents.list[].heartbeat.includeReasoning: true`。
## 網頁聊天 UI
- 網頁聊天思考選擇器會在頁面載入時，從傳入工作階段儲存區/設定映照工作階段已儲存的層級。
- 選擇另一個層級會立即透過 `sessions.patch` 寫入工作階段覆寫；它不會等待下一次傳送，也不是一次性的 `thinkingOnce` 覆寫。
- 第一個選項一律是 `Default (<resolved level>)`，其中解析後的預設值來自作用中工作階段模型的提供者思考設定檔，加上 `/status` 與 `session_status` 使用的相同回退邏輯。
- 選擇器使用 Gateway 工作階段列/預設值回傳的 `thinkingLevels`，並將 `thinkingOptions` 保留為舊版標籤清單。瀏覽器 UI 不會保留自己的提供者 regex 清單；模型特定層級集合由 Plugin 擁有。
- `/think:<level>` 仍可運作並更新相同的已儲存工作階段層級，因此聊天指令與選擇器會保持同步。
- 選擇另一個層級會立即透過 `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 端驗證中。
- 已發布的舊版 hook（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）會保留作為相容性配接器，但新的自訂層級集合應使用 `resolveThinkingProfile`。
- Gateway 列/defaults 會公開 `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 與標籤。

108
docs/zh-TW/tools/web-fetch.md
View File

@ -1,29 +1,29 @@
---
read_when:
- 你想擷取 URL 並提取可讀內容
- 你需要設定 web_fetch 或其 Firecrawl 備援
- 你想了解 web_fetch 的限制與快取
- 你想取得一個 URL 並擷取可讀內容
- 你需要設定 web_fetch 或其 Firecrawl 後備方案
- 你想了解 web_fetch 的限制和快取
sidebarTitle: Web Fetch
summary: web_fetch 工具 -- 具備可讀內容擷取的 HTTP 擷取
summary: web_fetch 工具 -- 具備可讀內容擷取功能的 HTTP 擷取
title: 網頁擷取
x-i18n:
generated_at: "2026-05-02T21:06:48Z"
generated_at: "2026-05-04T02:46:49Z"
model: gpt-5.5
provider: openai
source_hash: f455da77c20049f0ed0246fa53e9f49d3cf2004e65bd64a0bf871861c6e93229
source_hash: c8c3efbf4a640b2fd69cc9532dcb06a873a6830a2e8a85ab7510ab38207c8670
source_path: tools/web-fetch.md
workflow: 16
---
`web_fetch` 工具會執行一般 HTTP GET，並擷取可讀內容
（HTML 轉為 markdown 或文字）。它**不會**執行 JavaScript。
（將 HTML 轉為 Markdown 或文字）。它**不會**執行 JavaScript。
對於高度依賴 JS 的網站或受登入保護的頁面，請改用
對於大量依賴 JS 的網站或受登入保護的頁面，請改用
[網頁瀏覽器](/zh-TW/tools/browser)。
## 快速開始
`web_fetch` **預設啟用** -- 不需要設定。代理可以立即呼叫它：
`web_fetch` **預設已啟用** -- 不需要設定。代理可以立即呼叫它：
```javascript
await web_fetch({ url: "https://example.com/article" });
@ -32,15 +32,15 @@ await web_fetch({ url: "https://example.com/article" });
## 工具參數
<ParamField path="url" type="string" required>
要擷取的 URL。僅支援 `http(s)`。
要擷取的 URL。僅限 `http(s)`。
</ParamField>
<ParamField path="extractMode" type="'markdown' | 'text'" default="markdown">
主要內容擷取後的輸出格式。
主內容擷取後的輸出格式。
</ParamField>
<ParamField path="maxChars" type="number">
將輸出截斷至這個字元數。
將輸出截斷為此字元數。
</ParamField>
## 運作方式
@ -48,17 +48,18 @@ await web_fetch({ url: "https://example.com/article" });
<Steps>
<Step title="擷取">
使用類似 Chrome 的 User-Agent 和 `Accept-Language`
標頭傳送 HTTP GET。封鎖私人／內部主機名稱，並重新檢查重新導向。
標頭傳送 HTTP GET。封鎖私有/內部主機名稱，並重新檢查重新導向。
</Step>
<Step title="萃取">
在 HTML 回應上執行 Readability（主要內容擷取）。
<Step title="提取">
在 HTML 回應上執行 Readability（主內容擷取）。
</Step>
<Step title="備援（選用）">
如果 Readability 失敗且已設定 Firecrawl，會透過
Firecrawl API 以規避機器人限制模式重試。
<Step title="後援（選用）">
如果 Readability 失敗且已設定 Firecrawl，則透過
Firecrawl API 以規避機器人偵測模式重試。
</Step>
<Step title="快取">
結果會快取 15 分鐘（可設定），以減少對同一 URL 的重複擷取。
結果會快取 15 分鐘（可設定），以減少對相同 URL 的重複
擷取。
</Step>
</Steps>
@ -77,6 +78,7 @@ await web_fetch({ url: "https://example.com/article" });
timeoutSeconds: 30,
cacheTtlMinutes: 15,
maxRedirects: 3,
useTrustedEnvProxy: false, // let a trusted HTTP(S) env proxy resolve DNS
readability: true, // use Readability extraction
userAgent: "Mozilla/5.0 ...", // override User-Agent
ssrfPolicy: {
@ -89,10 +91,10 @@ await web_fetch({ url: "https://example.com/article" });
}
```
## Firecrawl 備援
## Firecrawl 後援
如果 Readability 擷取失敗，`web_fetch` 可以退回使用
[Firecrawl](/zh-TW/tools/firecrawl)，以規避機器人限制並取得更好的擷取結果：
如果 Readability 擷取失敗，`web_fetch` 可以後援到
[Firecrawl](/zh-TW/tools/firecrawl)，用於規避機器人偵測並提供更好的擷取：
```json5
{
@ -126,37 +128,57 @@ await web_fetch({ url: "https://example.com/article" });
舊版 `tools.web.fetch.firecrawl.*` 設定會由 `openclaw doctor --fix` 自動遷移。
<Note>
如果 Firecrawl 已啟用，但其 SecretRef 無法解析，且沒有
`FIRECRAWL_API_KEY` 環境變數備援，Gateway 啟動會快速失敗。
如果 Firecrawl 已啟用，且其 SecretRef 未解析且沒有
`FIRECRAWL_API_KEY` 環境後援，Gateway 啟動會快速失敗。
</Note>
<Note>
Firecrawl `baseUrl` 覆寫受到嚴格限制：託管流量使用
`https://api.firecrawl.dev`；自託管覆寫必須指向私人或
內部端點，而 `http://` 只會被這類私人目標接受。
Firecrawl `baseUrl` 覆寫受到限制：託管流量使用
`https://api.firecrawl.dev`；自架覆寫必須指向私有或
內部端點，且 `http://` 只接受用於這些私有目標。
</Note>
目前的執行階段行為：
- `tools.web.fetch.provider` 會明確選取擷取備援提供者。
- 如果省略 `provider`，OpenClaw 會從可用憑證中自動偵測第一個就緒的 web-fetch
提供者。非沙盒化的 `web_fetch` 可以使用已安裝、宣告 `contracts.webFetchProviders` 並在
執行階段註冊相符提供者的 plugins。目前內建提供者是 Firecrawl。
- 沙盒化的 `web_fetch` 呼叫仍限制為只能使用內建提供者。
- 如果停用 Readability，`web_fetch` 會直接跳到所選的
提供者備援。如果沒有可用提供者，則會封閉式失敗。
- `tools.web.fetch.provider` 會明確選擇擷取後援提供者。
- 如果省略 `provider`，OpenClaw 會從可用憑證中自動偵測第一個就緒的網頁擷取
提供者。非沙盒化的 `web_fetch` 可以使用已安裝且宣告
`contracts.webFetchProviders`，並在執行階段註冊相符提供者的 plugins。
目前內建提供者是 Firecrawl。
- 沙盒化的 `web_fetch` 呼叫仍限制為內建提供者。
- 如果 Readability 已停用，`web_fetch` 會直接跳到所選的
提供者後援。如果沒有可用提供者，則會封閉失敗。
## 受信任的環境代理
如果你的部署需要讓 `web_fetch` 透過受信任的出站
HTTP(S) 代理，請設定 `tools.web.fetch.useTrustedEnvProxy: true`。
在此模式下，OpenClaw 仍會在傳送請求前套用基於主機名稱的 SSRF 檢查，
但會讓代理解析 DNS，而不是執行本機 DNS
釘選。只有在代理由操作者控制，並且會在 DNS 解析後強制執行
出站政策時，才啟用此選項。
<Note>
如果未設定 HTTP(S) 代理環境變數，或目標主機被
`NO_PROXY` 排除，`web_fetch` 會回退到使用本機 DNS
釘選的一般嚴格路徑。
</Note>
## 限制與安全性
- `maxChars` 會被限制在 `tools.web.fetch.maxCharsCap`
- 回應主體會在解析前限制為 `maxResponseBytes`；過大的
回應會被截斷並附上警告
- 私人／內部主機名稱會被封鎖
- `maxChars` 會限制在 `tools.web.fetch.maxCharsCap`
- 回應本文在解析前會限制為 `maxResponseBytes`；過大的
回應會被截斷並附帶警告
- 私有/內部主機名稱會被封鎖
- `tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange` 和
`tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是針對受信任假 IP 代理堆疊的狹義選擇加入；
除非你的代理擁有這些合成範圍並執行自己的目的地政策，否則請保留未設定
`tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange` 是針對受信任假 IP 代理堆疊的狹義選用項；
除非你的代理擁有這些合成範圍並強制執行自己的目的地政策，
否則請不要設定
- 重新導向會被檢查，並受 `maxRedirects` 限制
- `web_fetch` 是盡力而為 -- 有些網站需要使用[網頁瀏覽器](/zh-TW/tools/browser)
- `useTrustedEnvProxy` 是明確的選用項，且只應為
操作者控制、仍會在 DNS 解析後強制執行出站政策的代理啟用
- `web_fetch` 是盡力而為 -- 有些網站需要[網頁瀏覽器](/zh-TW/tools/browser)
## 工具設定檔
@ -174,5 +196,5 @@ await web_fetch({ url: "https://example.com/article" });
## 相關
- [網頁搜尋](/zh-TW/tools/web) -- 使用多個提供者搜尋網頁
- [網頁瀏覽器](/zh-TW/tools/browser) -- 用於高度依賴 JS 網站的完整瀏覽器自動化
- [Firecrawl](/zh-TW/tools/firecrawl) -- Firecrawl 搜尋與爬取工具
- [網頁瀏覽器](/zh-TW/tools/browser) -- 適用於大量依賴 JS 網站的完整瀏覽器自動化
- [Firecrawl](/zh-TW/tools/firecrawl) -- Firecrawl 搜尋與擷取工具

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

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

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

@ -1,71 +1,83 @@
---
read_when:
- 偵錯或設定 WebChat 存取權
summary: Loopback WebChat 靜態主機與聊天 UI 的 Gateway WS 使用方式
- 偵錯或設定 WebChat 存取
summary: 聊天 UI 的迴路網頁聊天靜態託管與 Gateway WS 使用方式
title: 網頁聊天
x-i18n:
generated_at: "2026-05-03T21:44:33Z"
generated_at: "2026-05-04T02:47:05Z"
model: gpt-5.5
provider: openai
source_hash: 48024e58259901c6feb67168c5c1ce32f46b8ad9b6f4511e56d2000478a3ed60
source_hash: bf435585a13a1cde5885714837017109eeeb61ffa5e33a400017706f676f57ea
source_path: web/webchat.md
workflow: 16
---
狀態：macOS/iOS SwiftUI 聊天 UI 會直接與 Gateway WebSocket 通訊。
## 它是什麼
## 這是什麼
- Gateway 的原生聊天 UI（沒有嵌入式瀏覽器，也沒有本機靜態伺服器）。
- 適用於 Gateway 的原生聊天 UI（沒有嵌入式瀏覽器，也沒有本機靜態伺服器）。
- 使用與其他通道相同的工作階段與路由規則。
- 決定性路由：回覆一律回到 WebChat。
- 決定性路由：回覆一律傳回 WebChat。
## 快速開始
1. 啟動 Gateway。
2. 開啟 WebChat UI（macOS/iOS 應用程式）或 Control UI 聊天分頁。
3. 確認已設定有效的 Gateway 驗證路徑（預設為共享密鑰，
2. 開啟 WebChat UI（macOS/iOS app）或 Control UI 聊天分頁。
3. 確認已設定有效的 Gateway 驗證路徑（預設為 shared-secret，
即使在 loopback 上也是如此）。
## 運作方式（行為）
- UI 會連線至 Gateway WebSocket，並使用 `chat.history`、`chat.send` 和 `chat.inject`。
- `chat.history` 為了穩定性而有界限：Gateway 可能會截斷很長的文字欄位、省略大型中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。
- `chat.history` 會針對現代僅附加工作階段檔案遵循作用中的逐字稿分支，因此已放棄的重寫分支和已被取代的提示副本不會在 WebChat 中呈現。
- Compaction 項目會呈現為明確的已壓縮歷史分隔線。該分隔線會說明較早的回合已保留在檢查點中，並連結到工作階段檢查點控制項，操作員可在權限允許時從那裡分支或還原 Compaction 前的檢視。
- Control UI 會記住 `chat.history` 傳回的後端 Gateway `sessionId`，並在後續 `chat.send` 呼叫中包含它，因此重新連線和頁面重新整理會繼續相同的已儲存對話，除非使用者啟動或重設工作階段。
- Control UI 會在產生新的 `chat.send` 執行 ID 前，合併同一工作階段、訊息和附件的重複進行中提交；Gateway 仍會對重複使用相同冪等性金鑰的重複請求進行去重。
- `chat.history` 也會進行顯示正規化：僅限執行階段的 OpenClaw 上下文、
傳入封套包裝、內嵌傳遞指令標籤
- UI 連線到 Gateway WebSocket，並使用 `chat.history`、`chat.send` 和 `chat.inject`。
- `chat.history` 會受到限制以維持穩定性：Gateway 可能會截斷過長的文字欄位、省略龐大的中繼資料，並以 `[chat.history omitted: message too large]` 取代過大的項目。
- 對於現代的僅附加工作階段檔案，`chat.history` 會遵循作用中的逐字稿分支，因此已放棄的重寫分支和被取代的提示副本不會在 WebChat 中呈現。
- Compaction 項目會呈現為明確的已壓縮歷史分隔線。分隔線會說明較早的回合已保存在檢查點中，並連結到 Sessions 檢查點控制項；在權限允許時，操作人員可以在那裡建立分支或還原 Compaction 前的檢視。
- Control UI 會記住 `chat.history` 傳回的後端 Gateway `sessionId`，並在後續的 `chat.send` 呼叫中包含它，因此重新連線與頁面重新整理會繼續同一個已儲存的對話，除非使用者開始或重設工作階段。
- Control UI 會在產生新的 `chat.send` 執行 ID 前，合併同一個工作階段、訊息與附件的重複進行中提交；Gateway 仍會對重複使用相同冪等鍵的重複請求進行去重。
- 工作區啟動檔案與待處理的 `BOOTSTRAP.md` 指示會透過代理系統提示的 Project Context 提供，而不是複製到 WebChat 使用者訊息中。Bootstrap 截斷只會加入簡潔的系統提示復原通知；詳細計數與設定旋鈕會保留在診斷介面上。
- `chat.history` 也會進行顯示正規化：僅執行期的 OpenClaw 內容、
傳入信封包裝、內嵌傳遞指令標籤
例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`、純文字工具呼叫 XML
酬載（包括 `<tool_call>...</tool_call>`、
承載（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>`，以及截斷的工具呼叫區塊），以及
外洩的 ASCII/全形模型控制權杖，都會從可見文字中移除，
而整段可見文字僅為精確靜默
權杖 `NO_REPLY` / `no_reply` 的助理項目會被省略。
- 帶有推理標記的回覆酬載（`isReasoning: true`）會從 WebChat 助理內容、逐字稿重播文字和音訊內容區塊中排除，因此僅供思考的酬載不會顯示為可見的助理訊息或可播放音訊。
- `chat.inject` 會將助理備註直接附加到逐字稿，並廣播到 UI（不執行代理）。
- 已中止的執行可讓部分助理輸出持續顯示在 UI 中。
- 當存在已緩衝輸出時，Gateway 會將已中止的部分助理文字持久化到逐字稿歷史中，並以中止中繼資料標記這些項目。
洩漏的 ASCII/全形模型控制權杖，都會從可見文字中移除，
而整個可見文字僅為精確靜默
權杖 `NO_REPLY` / `no_reply` 的 assistant 項目會被省略。
- 標記為推理的回覆承載（`isReasoning: true`）會從 WebChat assistant 內容、逐字稿重播文字與音訊內容區塊中排除，因此僅思考用的承載不會顯示為可見的 assistant 訊息或可播放音訊。
- `chat.inject` 會將 assistant 備註直接附加到逐字稿，並廣播給 UI（不執行代理）。
- 中止的執行可以讓部分 assistant 輸出持續顯示在 UI 中。
- 當存在已緩衝輸出時，Gateway 會將中止的部分 assistant 文字持久化到逐字稿歷史中，並以中止中繼資料標記這些項目。
- 歷史一律從 Gateway 擷取（不監看本機檔案）。
- 如果無法連線到 Gateway，WebChat 會是唯讀。
- 如果無法連上 Gateway，WebChat 會是唯讀狀態。
### 逐字稿與傳遞模型
WebChat 有兩條獨立的資料路徑：
- 工作階段 JSONL 檔案是持久化的模型/執行期逐字稿。對於一般代理執行，Pi 會透過其工作階段管理器持久化模型可見的 `user`、`assistant` 和 `toolResult` 訊息。WebChat 不會將任意傳遞、狀態或輔助文字寫入該逐字稿。
- Gateway `ReplyPayload` 事件是即時傳遞投影。它們可以針對 WebChat/通道顯示、區塊串流、指令標籤、媒體嵌入、TTS/音訊旗標與 UI 備援行為進行正規化。它們本身並不是權威的工作階段記錄。
- WebChat 只會在 Gateway 擁有一般 Pi assistant 回合之外顯示的訊息時，注入 assistant 逐字稿項目：`chat.inject`、非代理命令回覆、中止的部分輸出，以及 WebChat 管理的媒體逐字稿補充內容。
- `chat.history` 會讀取已儲存的工作階段逐字稿，並套用 WebChat 顯示投影。如果即時 assistant 文字在執行期間出現，但在重新載入歷史後消失，請先檢查原始 JSONL 是否包含該 assistant 文字，接著檢查 `chat.history` 投影是否將其移除，再檢查 Control UI 樂觀尾端合併是否以持久化快照取代了本機傳遞狀態。
一般代理執行的最終答案應該是持久化的，因為 Pi 會寫入 assistant `message_end`。任何將已傳遞最終承載鏡像到逐字稿中的備援，都必須先避免重複建立 Pi 已經寫入的 assistant 回合。
## Control UI 代理工具面板
- Control UI `/agents` 工具面板有兩個獨立檢視：
- **目前可用** 使用 `tools.effective(sessionKey=...)`，並顯示目前
工作階段在執行階段實際可使用的內容，包括核心、Plugin 和通道擁有的工具。
- **工具設定** 使用 `tools.catalog`，並持續專注於設定檔、覆寫和
工作階段在執行期實際可用的內容，包括核心、Plugin 與通道擁有的工具。
- **工具設定** 使用 `tools.catalog`，並聚焦於設定檔、覆寫與
目錄語意。
- 執行階段可用性以工作階段為範圍。在同一代理上切換工作階段可能會變更
- 執行期可用性以工作階段為範圍。在同一個代理上切換工作階段，可能會變更
**目前可用** 清單。
- 設定編輯器不代表執行階段可用性；有效存取仍遵循政策
優先順序（`allow`/`deny`、每代理與供應商/通道覆寫）。
- 設定編輯器不代表執行期可用；有效存取仍會遵循原則
優先順序（`allow`/`deny`、每代理與提供者/通道覆寫）。
## 遠端使用
- 遠端模式會透過 SSH/Tailscale 對 Gateway WebSocket 建立隧道。
- 遠端模式會透過 SSH/Tailscale 建立 Gateway WebSocket 通道。
- 你不需要執行獨立的 WebChat 伺服器。
## 設定參考（WebChat）
@ -74,20 +86,20 @@ x-i18n:
WebChat 選項：
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷很長的文字欄位，並可能以預留位置取代過大的訊息。用戶端也可以傳送每次請求的 `maxChars`，針對單一 `chat.history` 呼叫覆寫此預設值。
- `gateway.webchat.chatHistoryMaxChars`：`chat.history` 回應中文字欄位的最大字元數。當逐字稿項目超過此限制時，Gateway 會截斷過長的文字欄位，並可能以預留位置取代過大的訊息。用戶端也可以傳送單次請求的 `maxChars`，以覆寫單次 `chat.history` 呼叫的此預設值。
相關全域選項：
- `gateway.port`、`gateway.bind`：WebSocket 主機/連接埠。
- `gateway.auth.mode`、`gateway.auth.token`、`gateway.auth.password`：
共享密鑰 WebSocket 驗證。
shared-secret WebSocket 驗證。
- `gateway.auth.allowTailscale`：啟用時，瀏覽器 Control UI 聊天分頁可以使用 Tailscale
Serve 身分標頭。
- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的**非 loopback** Proxy 來源後方之瀏覽器用戶端使用的反向 Proxy 驗證（請參閱 [可信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)）。
- `gateway.auth.mode: "trusted-proxy"`：供位於具身分感知能力的**非 loopback** 代理來源後方的瀏覽器用戶端使用的反向代理驗證（請參閱 [Trusted Proxy Auth](/zh-TW/gateway/trusted-proxy-auth)）。
- `gateway.remote.url`、`gateway.remote.token`、`gateway.remote.password`：遠端 Gateway 目標。
- `session.*`：工作階段儲存與主要金鑰預設值。
## 相關
- [Control UI](/zh-TW/web/control-ui)
- [儀表板](/zh-TW/web/dashboard)
- [Dashboard](/zh-TW/web/dashboard)