chore(i18n): refresh zh-TW translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
71f964b1a8
commit
5dc93359e9
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- 設定私訊存取控制
|
||||
- 配對新的 iOS/Android Node
|
||||
- 配對新的 iOS/Android 節點
|
||||
- 檢視 OpenClaw 的安全態勢
|
||||
summary: 配對概覽：核准誰可以私訊你 + 哪些節點可以加入
|
||||
summary: 配對總覽：核准誰可以私訊你 + 哪些節點可以加入
|
||||
title: 配對
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:21:42Z"
|
||||
generated_at: "2026-05-04T09:37:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874
|
||||
source_hash: f2bce4cfba7708b0003f2ffeacada8bc1849cc301f28178b499a9a67bddcf36d
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,27 +17,27 @@ x-i18n:
|
||||
「配對」是 OpenClaw 明確的存取核准步驟。
|
||||
它用於兩個地方：
|
||||
|
||||
1. **DM 配對**（誰可以與機器人交談）
|
||||
1. **DM 配對**（誰可以和機器人對話）
|
||||
2. **Node 配對**（哪些裝置/Node 可以加入 Gateway 網路）
|
||||
|
||||
安全性背景：[安全性](/zh-TW/gateway/security)
|
||||
安全性脈絡：[安全性](/zh-TW/gateway/security)
|
||||
|
||||
## 1) DM 配對（傳入聊天存取）
|
||||
|
||||
當通道設定為 DM 政策 `pairing` 時，未知寄件者會取得一組短代碼，且在你核准之前，他們的訊息**不會被處理**。
|
||||
當某個通道設定了 DM 政策 `pairing`，未知寄件者會收到一組短代碼，而且其訊息在你核准之前**不會被處理**。
|
||||
|
||||
預設 DM 政策記載於：[安全性](/zh-TW/gateway/security)
|
||||
|
||||
只有在有效的 DM 允許清單包含 `"*"` 時，`dmPolicy: "open"` 才是公開的。
|
||||
設定與驗證會要求公開開放設定具備這個萬用字元。如果現有
|
||||
狀態包含 `open` 並搭配具體的 `allowFrom` 項目，執行階段仍只會允許
|
||||
那些寄件者，且配對儲存區的核准不會擴大 `open` 存取權。
|
||||
`dmPolicy: "open"` 只有在有效 DM 允許清單包含 `"*"` 時才是公開的。
|
||||
公開開放設定的設定與驗證需要該萬用字元。如果既有狀態包含 `open`
|
||||
且有具體的 `allowFrom` 項目，執行階段仍只允許那些寄件者，
|
||||
而配對儲存核准不會擴大 `open` 存取權。
|
||||
|
||||
配對代碼：
|
||||
|
||||
- 8 個字元、大寫、不含容易混淆的字元（`0O1I`）。
|
||||
- 8 個字元、大寫、沒有易混淆字元（`0O1I`）。
|
||||
- **1 小時後過期**。機器人只會在建立新請求時傳送配對訊息（大約每位寄件者每小時一次）。
|
||||
- 待處理的 DM 配對請求預設每個通道上限為 **3 個**；額外請求會被忽略，直到其中一個過期或被核准。
|
||||
- 待處理的 DM 配對請求預設每個通道上限為 **3 個**；額外請求會被忽略，直到有一個過期或被核准。
|
||||
|
||||
### 核准寄件者
|
||||
|
||||
@ -48,15 +48,16 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
如果尚未設定命令擁有者，核准 DM 配對代碼也會將
|
||||
`commands.ownerAllowFrom` 啟動設定為已核准的寄件者，例如 `telegram:123456789`。
|
||||
這會讓初次設定擁有一個明確的擁有者，用於特權命令與 exec
|
||||
核准提示。擁有者存在後，後續配對核准只會授予 DM
|
||||
存取權；不會新增更多擁有者。
|
||||
這會讓首次設定明確擁有可執行特權命令與執行核准提示的擁有者。
|
||||
擁有者存在之後，後續配對核准只會授予 DM 存取權；
|
||||
不會新增更多擁有者。
|
||||
|
||||
支援的通道：`bluebubbles`、`discord`、`feishu`、`googlechat`、`imessage`、`irc`、`line`、`matrix`、`mattermost`、`msteams`、`nextcloud-talk`、`nostr`、`openclaw-weixin`、`signal`、`slack`、`synology-chat`、`telegram`、`twitch`、`whatsapp`、`zalo`、`zalouser`。
|
||||
|
||||
### 可重複使用的寄件者群組
|
||||
|
||||
當同一組受信任寄件者應套用到多個訊息通道，或同時套用到 DM 與群組允許清單時，請使用最上層的 `accessGroups`。
|
||||
當同一組受信任寄件者應套用到多個訊息通道，或同時套用到 DM 與群組允許清單時，
|
||||
請使用頂層的 `accessGroups`。
|
||||
|
||||
靜態群組使用 `type: "message.senders"`，並從通道允許清單以
|
||||
`accessGroup:<name>` 參照：
|
||||
@ -80,65 +81,72 @@ openclaw pairing approve telegram <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
存取群組的詳細文件在此：[存取群組](/zh-TW/channels/access-groups)
|
||||
存取群組的詳細說明在這裡：[存取群組](/zh-TW/channels/access-groups)
|
||||
|
||||
### 狀態儲存位置
|
||||
|
||||
儲存在 `~/.openclaw/credentials/` 底下：
|
||||
儲存在 `~/.openclaw/credentials/` 之下：
|
||||
|
||||
- 待處理請求：`<channel>-pairing.json`
|
||||
- 已核准允許清單儲存區：
|
||||
- 已核准允許清單儲存：
|
||||
- 預設帳號：`<channel>-allowFrom.json`
|
||||
- 非預設帳號：`<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
帳號範圍行為：
|
||||
|
||||
- 非預設帳號只會讀寫其範圍限定的允許清單檔案。
|
||||
- 預設帳號使用通道範圍、未範圍限定的允許清單檔案。
|
||||
- 非預設帳號只讀寫其範圍限定的允許清單檔案。
|
||||
- 預設帳號使用通道範圍、未限定範圍的允許清單檔案。
|
||||
|
||||
請將這些視為敏感資料（它們會控管你的助理存取權）。
|
||||
請將這些視為敏感資料（它們會管控對你助理的存取）。
|
||||
|
||||
<Note>
|
||||
配對允許清單儲存區用於 DM 存取。群組授權是分開的。
|
||||
核准 DM 配對代碼不會自動允許該寄件者執行群組
|
||||
命令或在群組中控制機器人。第一位擁有者啟動是位於
|
||||
`commands.ownerAllowFrom` 的獨立設定狀態，而群組聊天傳遞仍遵循
|
||||
配對允許清單儲存用於 DM 存取。群組授權是分開的。
|
||||
核准 DM 配對代碼不會自動允許該寄件者執行群組命令，
|
||||
或在群組中控制機器人。首次擁有者啟動設定是
|
||||
`commands.ownerAllowFrom` 中獨立的設定狀態，而群組聊天遞送仍遵循
|
||||
通道的群組允許清單（例如 `groupAllowFrom`、`groups`，或依通道而定的每群組
|
||||
或每主題覆寫）。
|
||||
</Note>
|
||||
|
||||
## 2) Node 裝置配對（iOS/Android/macOS/無頭 Node）
|
||||
|
||||
Node 以具備 `role: node` 的**裝置**身分連線到 Gateway。Gateway
|
||||
Node 會以 `role: node` 的**裝置**身分連線到 Gateway。Gateway
|
||||
會建立必須核准的裝置配對請求。
|
||||
|
||||
### 透過 Telegram 配對（建議用於 iOS）
|
||||
|
||||
如果你使用 `device-pair` Plugin，可以完全透過 Telegram 進行初次裝置配對：
|
||||
如果你使用 `device-pair` Plugin，可以完全從 Telegram 完成首次裝置配對：
|
||||
|
||||
1. 在 Telegram 中傳訊息給你的機器人：`/pair`
|
||||
2. 機器人會回覆兩則訊息：一則指示訊息，以及另一則獨立的**設定代碼**訊息（便於在 Telegram 中複製/貼上）。
|
||||
3. 在手機上開啟 OpenClaw iOS 應用程式 → 設定 → Gateway。
|
||||
4. 貼上設定代碼並連線。
|
||||
5. 回到 Telegram：`/pair pending`（檢閱請求 ID、角色與範圍），然後核准。
|
||||
2. 機器人會回覆兩則訊息：一則指示訊息，以及一則獨立的**設定代碼**訊息（在 Telegram 中易於複製/貼上）。
|
||||
3. 在手機上開啟 OpenClaw iOS app → Settings → Gateway。
|
||||
4. 掃描 QR code 或貼上設定代碼並連線。
|
||||
5. 回到 Telegram：`/pair pending`（檢視請求 ID、角色與範圍），然後核准。
|
||||
|
||||
設定代碼是 base64 編碼的 JSON 承載，其中包含：
|
||||
設定代碼是 base64 編碼的 JSON 承載內容，包含：
|
||||
|
||||
- `url`：Gateway WebSocket URL（`ws://...` 或 `wss://...`）
|
||||
- `bootstrapToken`：用於初始配對握手的短效單一裝置啟動權杖
|
||||
- `bootstrapToken`：用於初始配對交握的短效單裝置啟動 token
|
||||
|
||||
該啟動權杖帶有內建配對啟動設定檔：
|
||||
該啟動 token 帶有內建的配對啟動設定檔：
|
||||
|
||||
- 主要交接的 `node` 權杖維持 `scopes: []`
|
||||
- 任何交接的 `operator` 權杖都會限制在啟動允許清單內：
|
||||
- 主要交接的 `node` token 保持 `scopes: []`
|
||||
- 任何交接的 `operator` token 都限制於啟動允許清單：
|
||||
`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write`
|
||||
- 啟動範圍檢查會以角色作為前綴，而不是單一扁平範圍池：
|
||||
operator 範圍項目只會滿足 operator 請求，非 operator 角色
|
||||
仍必須在自己的角色前綴底下請求範圍
|
||||
- 後續權杖輪替/撤銷仍同時受裝置已核准的
|
||||
角色合約與呼叫端工作階段的 operator 範圍限制
|
||||
- 啟動範圍檢查以角色為前綴，而不是單一扁平範圍池：
|
||||
operator 範圍項目只滿足 operator 請求，而非 operator 角色
|
||||
仍必須在自己的角色前綴下請求範圍
|
||||
- 後續 token 輪替/撤銷仍受裝置已核准的
|
||||
角色合約與呼叫者工作階段的 operator 範圍共同限制
|
||||
|
||||
在設定代碼有效期間，請將它視為密碼。
|
||||
設定代碼有效時，請像密碼一樣對待它。
|
||||
|
||||
對於 Tailscale、公開或其他非 local loopback 的行動裝置配對，請使用 Tailscale
|
||||
Serve/Funnel 或其他 `wss://` Gateway URL。直接非 local loopback 的 `ws://` 設定
|
||||
URL 會在發出 QR/設定代碼之前被拒絕。明文 `ws://` 設定代碼
|
||||
僅限於 loopback URL；私人網路 `ws://` 用戶端仍需要遠端
|
||||
Gateway 指南中所述的明確
|
||||
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 破窗設定。
|
||||
|
||||
### 核准 Node 裝置
|
||||
|
||||
@ -148,25 +156,25 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
當明確核准因核准用配對裝置工作階段
|
||||
只以配對專用範圍開啟而遭拒時，CLI 會使用
|
||||
`operator.admin` 重試同一個請求。這讓現有具備管理能力的配對裝置可以復原新的
|
||||
Control UI/瀏覽器配對，而無需手動編輯 `devices/paired.json`。
|
||||
Gateway 仍會驗證重試的連線；無法以
|
||||
`operator.admin` 驗證的權杖仍會被阻擋。
|
||||
當明確核准被拒絕，原因是執行核准的已配對裝置工作階段
|
||||
以僅配對範圍開啟時，CLI 會使用 `operator.admin` 重試同一個請求。
|
||||
這讓既有具備管理能力的已配對裝置，可以在不手動編輯
|
||||
`devices/paired.json` 的情況下復原新的 Control UI/瀏覽器配對。Gateway
|
||||
仍會驗證重試的連線；無法以 `operator.admin` 驗證的 token
|
||||
仍會被封鎖。
|
||||
|
||||
如果同一台裝置以不同驗證詳細資訊重試（例如不同的
|
||||
如果同一裝置使用不同驗證詳細資料重試（例如不同
|
||||
角色/範圍/公開金鑰），先前的待處理請求會被取代，並建立新的
|
||||
`requestId`。
|
||||
|
||||
<Note>
|
||||
已配對的裝置不會在無聲情況下取得更廣泛的存取權。如果它重新連線並要求更多範圍或更廣泛的角色，OpenClaw 會保留現有核准不變，並建立新的待處理升級請求。在核准之前，請使用 `openclaw devices list` 比較目前已核准的存取權與新請求的存取權。
|
||||
已配對的裝置不會悄悄取得更廣的存取權。如果它重新連線並要求更多範圍或更廣角色，OpenClaw 會保持既有核准不變，並建立新的待處理升級請求。核准前，請使用 `openclaw devices list` 比較目前已核准的存取權與新請求的存取權。
|
||||
</Note>
|
||||
|
||||
### 選用的受信任 CIDR Node 自動核准
|
||||
|
||||
裝置配對預設仍為手動。對於嚴格控管的 Node 網路，
|
||||
你可以透過明確 CIDR 或精確 IP 選擇加入初次 Node 自動核准：
|
||||
你可以選擇以明確 CIDR 或精確 IP 啟用首次 Node 自動核准：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -180,24 +188,24 @@ Gateway 仍會驗證重試的連線；無法以
|
||||
}
|
||||
```
|
||||
|
||||
這只會套用於不請求任何範圍的全新 `role: node` 配對請求。
|
||||
Operator、瀏覽器、Control UI 與 WebChat 用戶端仍需要手動
|
||||
這只適用於全新的 `role: node` 配對請求，且不得要求任何
|
||||
範圍。Operator、瀏覽器、Control UI 與 WebChat 用戶端仍需要手動
|
||||
核准。角色、範圍、中繼資料與公開金鑰變更仍需要手動
|
||||
核准。
|
||||
|
||||
### Node 配對狀態儲存
|
||||
|
||||
儲存在 `~/.openclaw/devices/` 底下：
|
||||
儲存在 `~/.openclaw/devices/` 之下：
|
||||
|
||||
- `pending.json`（短效；待處理請求會過期）
|
||||
- `paired.json`（已配對裝置 + 權杖）
|
||||
- `paired.json`（已配對裝置 + token）
|
||||
|
||||
### 注意事項
|
||||
### 備註
|
||||
|
||||
- 舊版 `node.pair.*` API（CLI：`openclaw nodes pending|approve|reject|remove|rename`）是
|
||||
獨立的 Gateway 擁有配對儲存區。WS Node 仍需要裝置配對。
|
||||
- 配對記錄是已核准角色的持久真實來源。作用中
|
||||
裝置權杖仍受該已核准角色集合限制；已核准角色之外的零散權杖項目
|
||||
獨立的 Gateway 擁有配對儲存。WS Node 仍需要裝置配對。
|
||||
- 配對記錄是已核准角色的持久真實來源。作用中的
|
||||
裝置 token 仍受限於該已核准角色集合；位於已核准角色之外的零散 token 項目
|
||||
不會建立新的存取權。
|
||||
|
||||
## 相關文件
|
||||
|
||||
@ -4,33 +4,33 @@ read_when:
|
||||
summary: Telegram 機器人支援狀態、功能與設定
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:02:46Z"
|
||||
generated_at: "2026-05-04T09:36:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
可用於透過 grammY 在 bot 私訊與群組中進行正式環境部署。長輪詢是預設模式；Webhook 模式為選用。
|
||||
適用於 bot 私訊與群組的生產就緒設定，透過 grammY 運作。長輪詢是預設模式；webhook 模式為選用。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="配對" icon="link" href="/zh-TW/channels/pairing">
|
||||
Telegram 的預設私訊政策是配對。
|
||||
</Card>
|
||||
<Card title="通道疑難排解" icon="wrench" href="/zh-TW/channels/troubleshooting">
|
||||
跨通道診斷與修復手冊。
|
||||
<Card title="頻道疑難排解" icon="wrench" href="/zh-TW/channels/troubleshooting">
|
||||
跨頻道診斷與修復作業手冊。
|
||||
</Card>
|
||||
<Card title="Gateway 配置" icon="settings" href="/zh-TW/gateway/configuration">
|
||||
完整通道設定模式與範例。
|
||||
<Card title="Gateway 設定" icon="settings" href="/zh-TW/gateway/configuration">
|
||||
完整頻道設定模式與範例。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 快速設定
|
||||
|
||||
<Steps>
|
||||
<Step title="在 BotFather 建立 bot token">
|
||||
開啟 Telegram 並與 **@BotFather** 聊天（確認帳號完全是 `@BotFather`）。
|
||||
<Step title="在 BotFather 中建立 bot token">
|
||||
開啟 Telegram 並與 **@BotFather** 聊天（確認帳號名稱正好是 `@BotFather`）。
|
||||
|
||||
執行 `/newbot`、依照提示操作，並儲存 token。
|
||||
|
||||
@ -51,8 +51,8 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
環境變數備援：`TELEGRAM_BOT_TOKEN=...`（僅限預設帳號）。
|
||||
Telegram **不**使用 `openclaw channels login telegram`；請在設定/env 中設定 token，然後啟動 gateway。
|
||||
環境變數備援：`TELEGRAM_BOT_TOKEN=...`（僅限預設帳戶）。
|
||||
Telegram **不** 使用 `openclaw channels login telegram`；請在設定/env 中設定 token，然後啟動 gateway。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -64,31 +64,31 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
配對碼會在 1 小時後過期。
|
||||
配對碼會在 1 小時後到期。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="將 bot 加入群組">
|
||||
將 bot 加入你的群組，然後設定 `channels.telegram.groups` 與 `groupPolicy` 以符合你的存取模型。
|
||||
將 bot 加入你的群組，然後設定 `channels.telegram.groups` 與 `groupPolicy`，使其符合你的存取模型。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Token 解析順序會感知帳號。實務上，設定值優先於環境變數備援，而 `TELEGRAM_BOT_TOKEN` 只套用於預設帳號。
|
||||
Token 解析順序會感知帳戶。實務上，設定值優先於環境變數備援，而 `TELEGRAM_BOT_TOKEN` 只套用於預設帳戶。
|
||||
</Note>
|
||||
|
||||
## Telegram 端設定
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="隱私模式與群組可見性">
|
||||
Telegram bot 預設使用 **Privacy Mode**，這會限制它們可接收的群組訊息。
|
||||
Telegram bot 預設啟用**隱私模式**，這會限制它們接收的群組訊息。
|
||||
|
||||
如果 bot 必須看到所有群組訊息，請擇一：
|
||||
如果 bot 必須看到所有群組訊息，請執行以下任一操作：
|
||||
|
||||
- 透過 `/setprivacy` 停用隱私模式，或
|
||||
- 將 bot 設為群組管理員。
|
||||
|
||||
切換隱私模式時，請在每個群組中移除並重新加入 bot，讓 Telegram 套用變更。
|
||||
切換隱私模式時，請在每個群組中移除再重新加入 bot，讓 Telegram 套用變更。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -99,7 +99,7 @@ Token 解析順序會感知帳號。實務上，設定值優先於環境變數
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="實用的 BotFather 切換項">
|
||||
<Accordion title="實用的 BotFather 開關">
|
||||
|
||||
- `/setjoingroups` 用於允許/拒絕加入群組
|
||||
- `/setprivacy` 用於群組可見性行為
|
||||
@ -114,25 +114,25 @@ Token 解析順序會感知帳號。實務上，設定值優先於環境變數
|
||||
`channels.telegram.dmPolicy` 控制直接訊息存取：
|
||||
|
||||
- `pairing`（預設）
|
||||
- `allowlist`（需要 `allowFrom` 中至少有一個寄件者 ID）
|
||||
- `open`（需要 `allowFrom` 包含 `"*"`）
|
||||
- `allowlist`（要求 `allowFrom` 中至少有一個傳送者 ID）
|
||||
- `open`（要求 `allowFrom` 包含 `"*"`）
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 會讓任何找到或猜到 bot 使用者名稱的 Telegram 帳號都能指揮該 bot。請只將它用於刻意公開、且工具受到嚴格限制的 bot；單一擁有者 bot 應使用 `allowlist` 搭配數字使用者 ID。
|
||||
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 會讓任何找到或猜到 bot 使用者名稱的 Telegram 帳戶都能指揮 bot。只應用於刻意公開且工具受到嚴格限制的 bot；單一擁有者 bot 應使用 `allowlist` 搭配數字使用者 ID。
|
||||
|
||||
`channels.telegram.allowFrom` 接受數字 Telegram 使用者 ID。`telegram:` / `tg:` 前綴會被接受並正規化。
|
||||
在多帳號設定中，限制性的頂層 `channels.telegram.allowFrom` 會被視為安全邊界：帳號層級的 `allowFrom: ["*"]` 項目不會讓該帳號公開，除非合併後的有效帳號允許清單仍包含明確的萬用字元。
|
||||
`dmPolicy: "allowlist"` 搭配空的 `allowFrom` 會封鎖所有私訊，並會被設定驗證拒絕。
|
||||
在多帳戶設定中，限制性的頂層 `channels.telegram.allowFrom` 會被視為安全邊界：帳戶層級的 `allowFrom: ["*"]` 項目不會讓該帳戶公開，除非合併後的有效帳戶允許清單仍包含明確萬用字元。
|
||||
`dmPolicy: "allowlist"` 搭配空的 `allowFrom` 會封鎖所有私訊，且會被設定驗證拒絕。
|
||||
設定流程只會要求數字使用者 ID。
|
||||
如果你已升級且設定包含 `@username` 允許清單項目，請執行 `openclaw doctor --fix` 來解析它們（盡力而為；需要 Telegram bot token）。
|
||||
如果你先前依賴配對儲存的允許清單檔案，`openclaw doctor --fix` 可在允許清單流程中將項目復原到 `channels.telegram.allowFrom`（例如 `dmPolicy: "allowlist"` 尚未有明確 ID 時）。
|
||||
|
||||
對於單一擁有者 bot，建議使用 `dmPolicy: "allowlist"` 搭配明確的數字 `allowFrom` ID，讓存取政策在設定中持久保存（而不是依賴先前的配對核准）。
|
||||
|
||||
常見混淆：私訊配對核准並不代表「此寄件者在任何地方都已獲授權」。
|
||||
配對授予私訊存取權。如果尚未存在命令擁有者，第一個核准的配對也會設定 `commands.ownerAllowFrom`，讓僅限擁有者的命令與 exec 核准擁有明確的操作者帳號。
|
||||
群組寄件者授權仍來自明確設定的允許清單。
|
||||
如果你想要「我授權一次後，私訊與群組命令都能運作」，請將你的數字 Telegram 使用者 ID 放入 `channels.telegram.allowFrom`；若是僅限擁有者的命令，請確認 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
常見混淆：私訊配對核准不代表「此傳送者在所有地方都已授權」。
|
||||
配對授予私訊存取權。如果尚未存在命令擁有者，第一個核准的配對也會設定 `commands.ownerAllowFrom`，讓僅限擁有者的命令與 exec 核准具有明確的操作者帳戶。
|
||||
群組傳送者授權仍來自明確的設定允許清單。
|
||||
如果你想要「我授權一次後，私訊與群組命令都能運作」，請將你的數字 Telegram 使用者 ID 放入 `channels.telegram.allowFrom`；對於僅限擁有者的命令，請確認 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
|
||||
|
||||
### 尋找你的 Telegram 使用者 ID
|
||||
|
||||
@ -148,12 +148,12 @@ Token 解析順序會感知帳號。實務上，設定值優先於環境變數
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
第三方方法（隱私性較低）：`@userinfobot` 或 `@getidsbot`。
|
||||
第三方方法（較不私密）：`@userinfobot` 或 `@getidsbot`。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="群組政策與允許清單">
|
||||
兩個控制項會一起套用：
|
||||
兩項控制會共同套用：
|
||||
|
||||
1. **允許哪些群組**（`channels.telegram.groups`）
|
||||
- 沒有 `groups` 設定：
|
||||
@ -161,22 +161,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- 搭配 `groupPolicy: "allowlist"`（預設）：群組會被封鎖，直到你新增 `groups` 項目（或 `"*"`）
|
||||
- 已設定 `groups`：作為允許清單（明確 ID 或 `"*"`）
|
||||
|
||||
2. **群組中允許哪些寄件者**（`channels.telegram.groupPolicy`）
|
||||
2. **群組中允許哪些傳送者**（`channels.telegram.groupPolicy`）
|
||||
- `open`
|
||||
- `allowlist`（預設）
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` 用於群組寄件者篩選。若未設定，Telegram 會退回使用 `allowFrom`。
|
||||
`groupAllowFrom` 用於群組傳送者篩選。如果未設定，Telegram 會退回使用 `allowFrom`。
|
||||
`groupAllowFrom` 項目應為數字 Telegram 使用者 ID（`telegram:` / `tg:` 前綴會被正規化）。
|
||||
不要將 Telegram 群組或超級群組聊天 ID 放入 `groupAllowFrom`。負數聊天 ID 屬於 `channels.telegram.groups`。
|
||||
非數字項目會在寄件者授權中被忽略。
|
||||
安全邊界（`2026.2.25+`）：群組寄件者驗證**不會**繼承私訊配對儲存的核准。
|
||||
配對維持僅限私訊。對於群組，請設定 `groupAllowFrom` 或每個群組/每個主題的 `allowFrom`。
|
||||
不要將 Telegram 群組或超級群組聊天 ID 放入 `groupAllowFrom`。負數聊天 ID 應放在 `channels.telegram.groups` 下。
|
||||
非數字項目會在傳送者授權中被忽略。
|
||||
安全邊界（`2026.2.25+`）：群組傳送者驗證**不會**繼承私訊配對儲存核准。
|
||||
配對仍僅限私訊。對於群組，請設定 `groupAllowFrom` 或每個群組/每個主題的 `allowFrom`。
|
||||
如果未設定 `groupAllowFrom`，Telegram 會退回使用設定中的 `allowFrom`，而不是配對儲存。
|
||||
單一擁有者 bot 的實用模式：在 `channels.telegram.allowFrom` 中設定你的使用者 ID，讓 `groupAllowFrom` 保持未設定，並在 `channels.telegram.groups` 下允許目標群組。
|
||||
執行階段注意事項：如果完全缺少 `channels.telegram`，除非明確設定 `channels.defaults.groupPolicy`，執行階段預設會採用 fail-closed 的 `groupPolicy="allowlist"`。
|
||||
執行階段注意事項：如果完全缺少 `channels.telegram`，除非明確設定了 `channels.defaults.groupPolicy`，否則執行階段會預設為故障關閉的 `groupPolicy="allowlist"`。
|
||||
|
||||
範例：允許一個特定群組中的任何成員：
|
||||
範例：允許特定一個群組中的任何成員：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
範例：只允許一個特定群組內的特定使用者：
|
||||
範例：只允許特定一個群組中的特定使用者：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -214,8 +214,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
常見錯誤：`groupAllowFrom` 不是 Telegram 群組允許清單。
|
||||
|
||||
- 將像 `-1001234567890` 這類負數 Telegram 群組或超級群組聊天 ID 放在 `channels.telegram.groups` 下。
|
||||
- 當你想限制允許群組中哪些人可以觸發 bot 時，將像 `8734062810` 這類 Telegram 使用者 ID 放在 `groupAllowFrom` 下。
|
||||
- 只有在你希望允許群組中的任何成員都能與 bot 交談時，才使用 `groupAllowFrom: ["*"]`。
|
||||
- 當你想限制允許群組內哪些人可以觸發 bot 時，將像 `8734062810` 這類 Telegram 使用者 ID 放在 `groupAllowFrom` 下。
|
||||
- 只有在你希望允許群組中的任何成員都能與 bot 對話時，才使用 `groupAllowFrom: ["*"]`。
|
||||
|
||||
</Warning>
|
||||
|
||||
@ -224,14 +224,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Tab title="提及行為">
|
||||
群組回覆預設需要提及。
|
||||
|
||||
提及可來自：
|
||||
提及可以來自：
|
||||
|
||||
- 原生 `@botusername` 提及，或
|
||||
- 下列項目中的提及模式：
|
||||
- 下列位置中的提及模式：
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
工作階段層級命令切換：
|
||||
工作階段層級命令開關：
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
@ -264,33 +264,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
## 執行階段行為
|
||||
|
||||
- Telegram 由 gateway 程序擁有。
|
||||
- 路由是確定性的：Telegram 傳入訊息會回覆到 Telegram（模型不會選擇通道）。
|
||||
- 傳入訊息會正規化為共用通道信封，並包含回覆中繼資料與媒體 placeholder。
|
||||
- 群組工作階段依群組 ID 隔離。論壇主題會附加 `:topic:<threadId>` 以保持主題隔離。
|
||||
- 私訊訊息可攜帶 `message_thread_id`；OpenClaw 會保留 thread ID 供回覆使用，但預設會讓私訊維持在扁平工作階段。當你刻意想要私訊主題工作階段隔離時，請設定 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或相符的主題設定。
|
||||
- 長輪詢使用 grammY runner，並採用每個聊天/每個 thread 的排序。整體 runner sink 並行度使用 `agents.defaults.maxConcurrent`。
|
||||
- 長輪詢會在每個 gateway 程序內受到保護，因此同一時間只有一個作用中的 poller 可以使用 bot token。如果你仍看到 `getUpdates` 409 衝突，可能有另一個 OpenClaw gateway、script 或外部 poller 正在使用同一個 token。
|
||||
- 長輪詢 watchdog restart 預設會在 120 秒內沒有完成的 `getUpdates` liveness 時觸發。只有在你的部署於長時間執行工作期間仍看到誤判的 polling-stall restart 時，才提高 `channels.telegram.pollingStallThresholdMs`。此值以毫秒為單位，允許範圍是 `30000` 到 `600000`；支援每個帳號覆寫。
|
||||
- Telegram Bot API 不支援讀取回條（`sendReadReceipts` 不適用）。
|
||||
- 路由是確定性的：Telegram 傳入會回覆到 Telegram（模型不會選擇頻道）。
|
||||
- 傳入訊息會正規化為共享頻道信封，並包含回覆中繼資料與媒體預留位置。
|
||||
- 群組工作階段依群組 ID 隔離。論壇主題會附加 `:topic:<threadId>` 以維持主題隔離。
|
||||
- 私訊訊息可攜帶 `message_thread_id`；OpenClaw 會保留 thread ID 用於回覆，但預設將私訊保留在扁平工作階段。當你刻意需要私訊主題工作階段隔離時，請設定 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或相符的主題設定。
|
||||
- 長輪詢使用 grammY runner，並採用每聊天/每 thread 排序。整體 runner sink 並行度使用 `agents.defaults.maxConcurrent`。
|
||||
- 長輪詢在每個 gateway 程序內受到保護，因此同一時間只有一個作用中的 poller 可使用 bot token。如果你仍看到 `getUpdates` 409 衝突，可能是另一個 OpenClaw gateway、script 或外部 poller 正在使用相同 token。
|
||||
- 長輪詢 watchdog 重啟預設會在 120 秒沒有完成 `getUpdates` 存活性後觸發。只有在部署期間執行長時間工作時仍看到錯誤的 polling-stall 重啟，才增加 `channels.telegram.pollingStallThresholdMs`。該值以毫秒為單位，允許範圍為 `30000` 到 `600000`；支援每帳戶覆寫。
|
||||
- Telegram Bot API 不支援讀取回執（`sendReadReceipts` 不適用）。
|
||||
|
||||
## 功能參考
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="即時串流預覽（訊息編輯）">
|
||||
OpenClaw 可即時串流部分回覆：
|
||||
OpenClaw 可以即時串流部分回覆：
|
||||
|
||||
- 直接聊天：預覽訊息 + `editMessageText`
|
||||
- 群組/主題：預覽訊息 + `editMessageText`
|
||||
|
||||
要求：
|
||||
|
||||
- `channels.telegram.streaming` 是 `off | partial | block | progress`（預設：`partial`）
|
||||
- `progress` 會保留一個可編輯的狀態草稿，並以工具進度更新它直到最終交付
|
||||
- `streaming.preview.toolProgress` 控制工具/進度更新是否重用同一則已編輯的預覽訊息（預設：預覽串流作用中時為 `true`）
|
||||
- `channels.telegram.streaming` 為 `off | partial | block | progress`（預設：`partial`）
|
||||
- `progress` 會保留一個可編輯的狀態草稿，並以工具進度更新它，直到最終傳送
|
||||
- `streaming.preview.toolProgress` 控制工具/進度更新是否重用同一則經編輯的預覽訊息（預設：預覽串流啟用時為 `true`）
|
||||
- `streaming.preview.commandText` 控制這些工具進度列中的命令/exec 詳細資訊：`raw`（預設，保留已發布行為）或 `status`（僅工具標籤）
|
||||
- 舊版 `channels.telegram.streamMode` 與布林值 `streaming` 會被偵測；請執行 `openclaw doctor --fix` 將它們遷移到 `channels.telegram.streaming.mode`
|
||||
- 會偵測舊版 `channels.telegram.streamMode` 與布林值 `streaming`；請執行 `openclaw doctor --fix` 將它們遷移到 `channels.telegram.streaming.mode`
|
||||
|
||||
工具進度預覽更新是在工具執行時顯示的短狀態列，例如命令執行、檔案讀取、規劃更新或 patch 摘要。Telegram 預設會啟用這些更新，以符合 `v2026.4.22` 及後續版本的 OpenClaw 已發布行為。若要保留答案文字的已編輯預覽，但隱藏工具進度列，請設定：
|
||||
工具進度預覽更新是在工具執行時顯示的簡短狀態列，例如命令執行、檔案讀取、規劃更新或 patch 摘要。Telegram 預設會啟用這些項目，以符合 `v2026.4.22` 及後續版本已發布的 OpenClaw 行為。若要保留答案文字的編輯預覽，但隱藏工具進度列，請設定：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -307,7 +307,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
若要保留工具進度可見但隱藏命令/exec 文字，請設定：
|
||||
若要讓工具進度保持可見，但隱藏命令/exec 文字，請設定：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -324,7 +324,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
對於進度草稿模式，請將相同的命令文字政策放在 `streaming.progress` 下：
|
||||
若要使用進度草稿模式，請將相同的命令文字政策放在 `streaming.progress` 底下：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -342,43 +342,43 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
只有在你想要僅傳遞最終結果時，才使用 `streaming.mode: "off"`：Telegram 預覽編輯會停用，且一般工具/進度閒聊會被抑制，而不是作為獨立狀態訊息傳送。核准提示、媒體承載內容和錯誤仍會透過一般最終傳遞路徑送出。當你只想保留答案預覽編輯，同時隱藏工具進度狀態列時，請使用 `streaming.preview.toolProgress: false`。
|
||||
只有在你想要僅最終送達時，才使用 `streaming.mode: "off"`：Telegram 預覽編輯會停用，一般工具/進度閒聊會被抑制，而不是作為獨立狀態訊息傳送。核准提示、媒體酬載和錯誤仍會透過一般最終送達路徑傳送。當你只想保留答案預覽編輯，同時隱藏工具進度狀態列時，請使用 `streaming.preview.toolProgress: false`。
|
||||
|
||||
<Note>
|
||||
Telegram 已選取引用回覆是例外。當 `replyToMode` 是 `"first"`、`"all"` 或 `"batched"`，且傳入訊息包含已選取的引用文字時，OpenClaw 會透過 Telegram 原生引用回覆路徑傳送最終答案，而不是編輯答案預覽，因此 `streaming.preview.toolProgress` 無法在該回合顯示簡短狀態列。沒有已選取引用文字的目前訊息回覆仍會保留預覽串流。當工具進度可見性比原生引用回覆更重要時，請設定 `replyToMode: "off"`，或設定 `streaming.preview.toolProgress: false` 以承認此取捨。
|
||||
Telegram 選取引文回覆是例外。當 `replyToMode` 為 `"first"`、`"all"` 或 `"batched"`，且傳入訊息包含選取的引文文字時，OpenClaw 會透過 Telegram 原生引文回覆路徑傳送最終答案，而不是編輯答案預覽，因此 `streaming.preview.toolProgress` 無法顯示該回合的短狀態列。沒有選取引文文字的目前訊息回覆仍會保留預覽串流。當工具進度可見性比原生引文回覆更重要時，請設定 `replyToMode: "off"`；或設定 `streaming.preview.toolProgress: false` 以承認這項取捨。
|
||||
</Note>
|
||||
|
||||
對於純文字回覆：
|
||||
|
||||
- 簡短的私訊/群組/主題預覽：OpenClaw 會保留同一則預覽訊息並就地執行最終編輯，除非預覽出現後已傳送可見的非預覽訊息
|
||||
- 預覽後接著可見的非預覽輸出：OpenClaw 會將完成的回覆作為新的最終訊息傳送，並清理較舊的預覽，因此最終答案會出現在中間輸出之後
|
||||
- 超過約一分鐘的預覽：OpenClaw 會將完成的回覆作為新的最終訊息傳送，然後清理預覽，因此 Telegram 可見的時間戳會反映完成時間，而不是預覽建立時間
|
||||
- 短的私訊/群組/主題預覽：OpenClaw 會保留同一則預覽訊息，並就地執行最終編輯，除非預覽出現後已傳送可見的非預覽訊息
|
||||
- 預覽後接著可見的非預覽輸出：OpenClaw 會將完成的回覆作為新的最終訊息傳送，並清理較舊的預覽，讓最終答案出現在中間輸出之後
|
||||
- 超過約一分鐘的預覽：OpenClaw 會將完成的回覆作為新的最終訊息傳送，然後清理預覽，讓 Telegram 可見的時間戳反映完成時間，而不是預覽建立時間
|
||||
|
||||
對於複雜回覆（例如媒體承載內容），OpenClaw 會退回一般最終傳遞，然後清理預覽訊息。
|
||||
對於複雜回覆（例如媒體酬載），OpenClaw 會退回一般最終送達，然後清理預覽訊息。
|
||||
|
||||
預覽串流與區塊串流是分開的。當 Telegram 明確啟用區塊串流時，OpenClaw 會略過預覽串流，以避免雙重串流。
|
||||
|
||||
僅限 Telegram 的推理串流：
|
||||
|
||||
- `/reasoning stream` 會在產生期間將推理傳送到即時預覽
|
||||
- 推理預覽會在最終傳遞後刪除；當推理應保持可見時，請使用 `/reasoning on`
|
||||
- 最終答案會在不含推理文字的情況下傳送
|
||||
- `/reasoning stream` 會在生成時將推理傳送到即時預覽
|
||||
- 推理預覽會在最終送達後刪除；當推理應保持可見時，請使用 `/reasoning on`
|
||||
- 最終答案傳送時不含推理文字
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="格式化與 HTML 後備">
|
||||
<Accordion title="Formatting and HTML fallback">
|
||||
傳出文字使用 Telegram `parse_mode: "HTML"`。
|
||||
|
||||
- 類似 Markdown 的文字會轉譯為 Telegram 安全的 HTML。
|
||||
- 原始模型 HTML 會被逸出，以減少 Telegram 剖析失敗。
|
||||
- 如果 Telegram 拒絕剖析後的 HTML，OpenClaw 會以純文字重試。
|
||||
- 類 Markdown 文字會轉譯為 Telegram 安全 HTML。
|
||||
- 原始模型 HTML 會被逸出，以減少 Telegram 解析失敗。
|
||||
- 如果 Telegram 拒絕解析後的 HTML，OpenClaw 會以純文字重試。
|
||||
|
||||
連結預覽預設啟用，可使用 `channels.telegram.linkPreview: false` 停用。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生命令與自訂命令">
|
||||
Telegram 命令選單註冊會在啟動時使用 `setMyCommands` 處理。
|
||||
<Accordion title="Native commands and custom commands">
|
||||
Telegram 命令選單註冊會在啟動時透過 `setMyCommands` 處理。
|
||||
|
||||
原生命令預設值：
|
||||
|
||||
@ -401,7 +401,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
規則：
|
||||
|
||||
- 名稱會正規化（移除開頭的 `/`、轉為小寫）
|
||||
- 名稱會正規化（移除前導 `/`、轉為小寫）
|
||||
- 有效模式：`a-z`、`0-9`、`_`，長度 `1..32`
|
||||
- 自訂命令不能覆寫原生命令
|
||||
- 衝突/重複項目會被略過並記錄
|
||||
@ -409,39 +409,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
注意事項：
|
||||
|
||||
- 自訂命令只是選單項目；它們不會自動實作行為
|
||||
- 即使未顯示在 Telegram 選單中，Plugin/技能命令在輸入時仍可運作
|
||||
- Plugin/Skill 命令即使未顯示在 Telegram 選單中，輸入時仍可運作
|
||||
|
||||
如果停用原生命令，內建項目會被移除。自訂/Plugin 命令若已設定，仍可註冊。
|
||||
|
||||
常見設定失敗：
|
||||
|
||||
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 選單在修剪後仍然溢出；請減少 Plugin/技能/自訂命令，或停用 `channels.telegram.commands.native`。
|
||||
- `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失敗並顯示 `404: Not Found`，但直接 Bot API curl 命令可運作，可能表示 `channels.telegram.apiRoot` 被設定為完整的 `/bot<TOKEN>` 端點。`apiRoot` 必須只是 Bot API 根路徑，而 `openclaw doctor --fix` 會移除意外尾隨的 `/bot<TOKEN>`。
|
||||
- `getMe returned 401` 表示 Telegram 拒絕已設定的機器人權杖。請使用目前的 BotFather 權杖更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
|
||||
- `setMyCommands failed` 搭配網路/fetch 錯誤，通常表示連往 `api.telegram.org` 的傳出 DNS/HTTPS 被封鎖。
|
||||
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 選單在修剪後仍然溢出；請減少 Plugin/Skill/自訂命令，或停用 `channels.telegram.commands.native`。
|
||||
- 當直接 Bot API curl 命令可運作，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 以 `404: Not Found` 失敗時，可能表示 `channels.telegram.apiRoot` 被設定為完整的 `/bot<TOKEN>` 端點。`apiRoot` 必須只是 Bot API 根目錄，且 `openclaw doctor --fix` 會移除意外尾隨的 `/bot<TOKEN>`。
|
||||
- `getMe returned 401` 表示 Telegram 拒絕設定的 bot token。請使用目前的 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
|
||||
- `setMyCommands failed` 搭配網路/擷取錯誤通常表示到 `api.telegram.org` 的傳出 DNS/HTTPS 被封鎖。
|
||||
|
||||
### 裝置配對命令（`device-pair` Plugin）
|
||||
|
||||
安裝 `device-pair` Plugin 後：
|
||||
安裝 `device-pair` Plugin 時：
|
||||
|
||||
1. `/pair` 會產生設定碼
|
||||
2. 將程式碼貼到 iOS app
|
||||
3. `/pair pending` 會列出待處理要求（包括角色/範圍）
|
||||
4. 核准要求：
|
||||
2. 在 iOS app 中貼上代碼
|
||||
3. `/pair pending` 會列出待處理請求（包含角色/範圍）
|
||||
4. 核准請求：
|
||||
- `/pair approve <requestId>` 用於明確核准
|
||||
- 只有一個待處理要求時使用 `/pair approve`
|
||||
- `/pair approve latest` 用於最新項目
|
||||
- `/pair approve` 用於只有一個待處理請求時
|
||||
- `/pair approve latest` 用於最新請求
|
||||
|
||||
設定碼會攜帶短效啟動權杖。內建啟動交接會將主要節點權杖維持在 `scopes: []`；任何已交接的操作者權杖仍限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。啟動範圍檢查會加上角色前綴，因此該操作者允許清單只滿足操作者要求；非操作者角色仍需要其自身角色前綴下的範圍。
|
||||
設定碼帶有短效啟動權杖。內建啟動交接會將主要節點權杖維持在 `scopes: []`；任何被交接的操作者權杖都仍會限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。啟動範圍檢查帶有角色前綴，因此該操作者允許清單只會滿足操作者請求；非操作者角色仍需要其自身角色前綴下的範圍。
|
||||
|
||||
如果裝置以變更後的驗證詳細資料重試（例如角色/範圍/公開金鑰），先前的待處理要求會被取代，且新要求會使用不同的 `requestId`。核准前請重新執行 `/pair pending`。
|
||||
如果裝置使用已變更的驗證詳細資料重試（例如角色/範圍/公開金鑰），先前的待處理請求會被取代，且新請求會使用不同的 `requestId`。核准前請重新執行 `/pair pending`。
|
||||
|
||||
更多詳細資料：[配對](/zh-TW/channels/pairing#pair-via-telegram-recommended-for-ios)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="行內按鈕">
|
||||
設定行內鍵盤範圍：
|
||||
<Accordion title="Inline buttons">
|
||||
設定內嵌鍵盤範圍：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -455,7 +455,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
個別帳戶覆寫：
|
||||
每個帳號覆寫：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -501,19 +501,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
回呼點擊會以文字傳遞給代理：
|
||||
回呼點擊會以文字傳給 agent：
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="代理與自動化的 Telegram 訊息動作">
|
||||
Telegram 工具動作包括：
|
||||
<Accordion title="Telegram message actions for agents and automation">
|
||||
Telegram 工具動作包含：
|
||||
|
||||
- `sendMessage`（`to`、`content`、選用 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `sendMessage`（`to`、`content`、選用的 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `react`（`chatId`、`messageId`、`emoji`）
|
||||
- `deleteMessage`（`chatId`、`messageId`）
|
||||
- `editMessage`（`chatId`、`messageId`、`content`）
|
||||
- `createForumTopic`（`chatId`、`name`、選用 `iconColor`、`iconCustomEmojiId`）
|
||||
- `createForumTopic`（`chatId`、`name`、選用的 `iconColor`、`iconCustomEmojiId`）
|
||||
|
||||
頻道訊息動作提供符合人體工學的別名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
|
||||
|
||||
@ -524,15 +524,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker`（預設：停用）
|
||||
|
||||
注意：`edit` 和 `topic-create` 目前預設啟用，且沒有個別的 `channels.telegram.actions.*` 切換。
|
||||
執行階段傳送會使用作用中的設定/密鑰快照（啟動/重新載入），因此動作路徑不會在每次傳送時執行臨時 SecretRef 重新解析。
|
||||
注意：`edit` 和 `topic-create` 目前預設啟用，且沒有獨立的 `channels.telegram.actions.*` 切換。
|
||||
執行階段傳送會使用作用中的設定/秘密快照（啟動/重新載入），因此動作路徑不會在每次傳送時執行臨時 SecretRef 重新解析。
|
||||
|
||||
反應移除語意：[/tools/reactions](/zh-TW/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="回覆執行緒標籤">
|
||||
Telegram 支援在產生的輸出中使用明確回覆執行緒標籤：
|
||||
<Accordion title="Reply threading tags">
|
||||
Telegram 支援生成輸出中的明確回覆串接標籤：
|
||||
|
||||
- `[[reply_to_current]]` 會回覆觸發訊息
|
||||
- `[[reply_to:<id>]]` 會回覆特定 Telegram 訊息 ID
|
||||
@ -543,29 +543,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
當回覆執行緒已啟用，且原始 Telegram 文字或標題可用時，OpenClaw 會自動包含原生 Telegram 引用摘錄。Telegram 會將原生引用文字限制為 1024 個 UTF-16 code units，因此較長訊息會從開頭引用，且如果 Telegram 拒絕引用，會退回純回覆。
|
||||
當啟用回覆串接，且原始 Telegram 文字或說明文字可用時，OpenClaw 會自動包含原生 Telegram 引文摘錄。Telegram 將原生引文文字限制在 1024 個 UTF-16 code unit，因此較長的訊息會從開頭引用，並在 Telegram 拒絕引文時退回純回覆。
|
||||
|
||||
注意：`off` 會停用隱含回覆執行緒。明確的 `[[reply_to_*]]` 標籤仍會被遵循。
|
||||
注意：`off` 會停用隱含回覆串接。明確的 `[[reply_to_*]]` 標籤仍會被遵循。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="論壇主題與執行緒行為">
|
||||
<Accordion title="Forum topics and thread behavior">
|
||||
論壇超級群組：
|
||||
|
||||
- 主題工作階段鍵會附加 `:topic:<threadId>`
|
||||
- 回覆和輸入動作會以主題執行緒為目標
|
||||
- 回覆與輸入狀態會以主題討論串為目標
|
||||
- 主題設定路徑：
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
一般主題（`threadId=1`）特殊情況：
|
||||
|
||||
- 訊息傳送會省略 `message_thread_id`（Telegram 會拒絕 `sendMessage(...thread_id=1)`）
|
||||
- 輸入動作仍會包含 `message_thread_id`
|
||||
- 輸入狀態動作仍會包含 `message_thread_id`
|
||||
|
||||
主題繼承：主題項目會繼承群組設定，除非被覆寫（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
|
||||
`agentId` 僅限主題，且不會從群組預設值繼承。
|
||||
|
||||
**個別主題代理路由**：每個主題都可透過在主題設定中設定 `agentId` 路由到不同代理。這讓每個主題都有自己的隔離工作區、記憶體和工作階段。範例：
|
||||
**每主題 agent 路由**：每個主題都可以透過在主題設定中設定 `agentId`，路由到不同 agent。這會讓每個主題擁有自己的隔離工作區、記憶和工作階段。範例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -587,24 +587,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
接著每個主題都有自己的工作階段鍵：`agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**持久 ACP 主題繫結**：論壇主題可以透過頂層具型別 ACP 繫結（`bindings[]` 搭配 `type: "acp"` 和 `match.channel: "telegram"`、`peer.kind: "group"`，以及像 `-1001234567890:topic:42` 的主題限定 ID）釘選 ACP harness 工作階段。目前範圍限於群組/超級群組中的論壇主題。請參閱 [ACP 代理](/zh-TW/tools/acp-agents)。
|
||||
**持久 ACP 主題繫結**：論壇主題可以透過頂層型別化 ACP 繫結（`bindings[]`，其中 `type: "acp"` 且 `match.channel: "telegram"`、`peer.kind: "group"`，以及像 `-1001234567890:topic:42` 這樣的主題限定 id）釘選 ACP harness 工作階段。目前範圍限於群組/超級群組中的論壇主題。請參閱 [ACP Agents](/zh-TW/tools/acp-agents)。
|
||||
|
||||
**從聊天產生執行緒繫結 ACP**：`/acp spawn <agent> --thread here|auto` 會將目前主題繫結到新的 ACP 工作階段；後續回覆會直接路由至該處。OpenClaw 會在主題內釘選產生確認。需要 `channels.telegram.threadBindings.spawnSessions` 保持啟用（預設：`true`）。
|
||||
**從聊天產生綁定討論串的 ACP**：`/acp spawn <agent> --thread here|auto` 會將目前主題繫結到新的 ACP 工作階段；後續訊息會直接路由到該處。OpenClaw 會在主題內釘選產生確認。需要保持啟用 `channels.telegram.threadBindings.spawnSessions`（預設：`true`）。
|
||||
|
||||
範本脈絡會公開 `MessageThreadId` 和 `IsForum`。含有 `message_thread_id` 的 DM 聊天預設會在扁平工作階段上保留 DM 路由和回覆中繼資料；只有在設定了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`，或符合的主題設定時，才會使用具備執行緒感知的工作階段鍵。使用頂層 `channels.telegram.dm.threadReplies` 作為帳號預設值，或使用 `direct.<chatId>.threadReplies` 針對單一 DM 設定。
|
||||
樣板內容會公開 `MessageThreadId` 和 `IsForum`。帶有 `message_thread_id` 的私訊聊天，預設會在扁平工作階段上保留私訊路由與回覆中繼資料；只有在設定 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`，或符合相符主題設定時，才會使用支援討論串的工作階段鍵。使用頂層 `channels.telegram.dm.threadReplies` 作為帳號預設值，或使用 `direct.<chatId>.threadReplies` 設定單一私訊。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="音訊、影片和貼圖">
|
||||
<Accordion title="音訊、影片與貼圖">
|
||||
### 音訊訊息
|
||||
|
||||
Telegram 會區分語音記事和音訊檔案。
|
||||
Telegram 會區分語音訊息與音訊檔案。
|
||||
|
||||
- 預設：音訊檔案行為
|
||||
- 在代理回覆中加入標籤 `[[audio_as_voice]]` 可強制以語音記事傳送
|
||||
- 傳入的語音記事轉錄會在代理脈絡中被框定為機器產生、
|
||||
不可信任的文字；提及偵測仍會使用原始
|
||||
轉錄，因此受提及閘控的語音訊息會繼續運作。
|
||||
- 在代理回覆中加入標籤 `[[audio_as_voice]]` 可強制傳送語音訊息
|
||||
- 傳入的語音訊息轉錄會在代理內容中標記為機器產生、
|
||||
不受信任的文字；提及偵測仍會使用原始
|
||||
轉錄，因此受提及控管的語音訊息會繼續運作。
|
||||
|
||||
訊息動作範例：
|
||||
|
||||
@ -620,7 +620,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### 影片訊息
|
||||
|
||||
Telegram 會區分影片檔案和影片記事。
|
||||
Telegram 會區分影片檔案與影片訊息。
|
||||
|
||||
訊息動作範例：
|
||||
|
||||
@ -634,17 +634,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
影片記事不支援說明文字；提供的訊息文字會另外傳送。
|
||||
影片訊息不支援說明文字；提供的訊息文字會另外傳送。
|
||||
|
||||
### 貼圖
|
||||
|
||||
傳入貼圖處理：
|
||||
傳入貼圖處理方式：
|
||||
|
||||
- 靜態 WEBP：下載並處理（預留位置 `<media:sticker>`）
|
||||
- 靜態 WEBP：下載並處理（佔位符 `<media:sticker>`）
|
||||
- 動畫 TGS：略過
|
||||
- 影片 WEBM：略過
|
||||
|
||||
貼圖脈絡欄位：
|
||||
貼圖內容欄位：
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -656,7 +656,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
貼圖會在可行時描述一次，並快取以減少重複的視覺呼叫。
|
||||
貼圖會描述一次（可行時）並快取，以減少重複的視覺呼叫。
|
||||
|
||||
啟用貼圖動作：
|
||||
|
||||
@ -683,7 +683,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
搜尋已快取貼圖：
|
||||
搜尋已快取的貼圖：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -697,24 +697,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="反應通知">
|
||||
Telegram 反應會以 `message_reaction` 更新抵達（與訊息酬載分開）。
|
||||
Telegram 反應會以 `message_reaction` 更新抵達（與訊息承載內容分開）。
|
||||
|
||||
啟用時，OpenClaw 會將系統事件加入佇列，例如：
|
||||
啟用後，OpenClaw 會將系統事件加入佇列，例如：
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
設定：
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all`（預設：`own`）
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（預設：`minimal`）
|
||||
- `channels.telegram.reactionNotifications`：`off | own | all`（預設：`own`）
|
||||
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（預設：`minimal`）
|
||||
|
||||
注意事項：
|
||||
|
||||
- `own` 表示僅限使用者對 bot 傳送訊息的反應（透過已傳送訊息快取盡力判定）。
|
||||
- 反應事件仍遵守 Telegram 存取控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授權的傳送者會被丟棄。
|
||||
- Telegram 不會在反應更新中提供執行緒 ID。
|
||||
- 非論壇群組會路由至群組聊天工作階段
|
||||
- 論壇群組會路由至群組一般主題工作階段（`:topic:1`），而不是確切的來源主題
|
||||
- `own` 表示僅限使用者對機器人所傳送訊息的反應（透過已傳送訊息快取盡力判定）。
|
||||
- 反應事件仍會遵守 Telegram 存取控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授權的傳送者會被捨棄。
|
||||
- Telegram 不會在反應更新中提供討論串 ID。
|
||||
- 非論壇群組會路由到群組聊天工作階段
|
||||
- 論壇群組會路由到群組的一般主題工作階段（`:topic:1`），而不是精確的原始主題
|
||||
|
||||
輪詢/Webhook 的 `allowed_updates` 會自動包含 `message_reaction`。
|
||||
|
||||
@ -728,22 +728,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- 代理身分表情符號後援（`agents.list[].identity.emoji`，否則為 "👀"）
|
||||
- 代理身分表情符號備援（`agents.list[].identity.emoji`，否則為 "👀"）
|
||||
|
||||
注意事項：
|
||||
|
||||
- Telegram 預期使用 unicode 表情符號（例如 "👀"）。
|
||||
- 使用 `""` 可停用頻道或帳號的反應。
|
||||
- 使用 `""` 可停用某個頻道或帳號的反應。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="來自 Telegram 事件和命令的設定寫入">
|
||||
<Accordion title="來自 Telegram 事件與指令的設定寫入">
|
||||
頻道設定寫入預設啟用（`configWrites !== false`）。
|
||||
|
||||
Telegram 觸發的寫入包括：
|
||||
由 Telegram 觸發的寫入包括：
|
||||
|
||||
- 群組遷移事件（`migrate_to_chat_id`），用於更新 `channels.telegram.groups`
|
||||
- `/config set` 和 `/config unset`（需要啟用命令）
|
||||
- `/config set` 和 `/config unset`（需要啟用指令）
|
||||
|
||||
停用：
|
||||
|
||||
@ -760,35 +760,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="長輪詢與 Webhook">
|
||||
預設為長輪詢。若要使用 Webhook 模式，請設定 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；選用 `webhookPath`、`webhookHost`、`webhookPort`（預設為 `/telegram-webhook`、`127.0.0.1`、`8787`）。
|
||||
預設為長輪詢。若要使用 Webhook 模式，請設定 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可選用 `webhookPath`、`webhookHost`、`webhookPort`（預設為 `/telegram-webhook`、`127.0.0.1`、`8787`）。
|
||||
|
||||
本機監聽器會繫結至 `127.0.0.1:8787`。若要公開入口，請在本機連接埠前方放置反向 Proxy，或有意地設定 `webhookHost: "0.0.0.0"`。
|
||||
本機監聽器會繫結到 `127.0.0.1:8787`。若要公開入口，請在本機連接埠前放置反向 Proxy，或刻意設定 `webhookHost: "0.0.0.0"`。
|
||||
|
||||
Webhook 模式會先驗證請求防護、Telegram 秘密權杖和 JSON 主體，然後才向 Telegram 回傳 `200`。
|
||||
OpenClaw 接著會透過與長輪詢相同的每聊天/每主題 bot 通道非同步處理更新，因此較慢的代理回合不會佔住 Telegram 的傳遞 ACK。
|
||||
Webhook 模式會先驗證請求防護、Telegram secret token 與 JSON 主體，才會向 Telegram 回傳 `200`。
|
||||
接著 OpenClaw 會透過長輪詢使用的相同逐聊天/逐主題機器人通道非同步處理更新，因此較慢的代理回合不會占住 Telegram 的傳遞 ACK。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="限制、重試和 CLI 目標">
|
||||
<Accordion title="限制、重試與 CLI 目標">
|
||||
- `channels.telegram.textChunkLimit` 預設為 4000。
|
||||
- `channels.telegram.chunkMode="newline"` 會在依長度分割前優先使用段落邊界（空白行）。
|
||||
- `channels.telegram.mediaMaxMb`（預設 100）會限制傳入和傳出的 Telegram 媒體大小。
|
||||
- `channels.telegram.mediaGroupFlushMs`（預設 500）控制 Telegram 相簿/媒體群組在 OpenClaw 將其作為單一傳入訊息分派前的緩衝時間。若相簿部分延遲抵達，請增加此值；若要降低相簿回覆延遲，請減少此值。
|
||||
- `channels.telegram.timeoutSeconds` 會覆寫 Telegram API 用戶端逾時（若未設定，則套用 grammY 預設值）。Bot 用戶端會將低於 60 秒傳出文字/輸入請求防護的設定值限制住，讓 grammY 不會在 OpenClaw 的傳輸防護和後援執行前中止可見回覆傳遞。長輪詢仍使用 45 秒的 `getUpdates` 請求防護，因此閒置輪詢不會無限期擱置。
|
||||
- `channels.telegram.pollingStallThresholdMs` 預設為 `120000`；僅在發生誤判的輪詢停滯重新啟動時，才調整於 `30000` 到 `600000` 之間。
|
||||
- 群組脈絡歷史會使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（預設 50）；`0` 會停用。
|
||||
- 回覆/引用/轉寄的補充脈絡目前會依收到的內容傳遞。
|
||||
- Telegram 允許清單主要控管誰能觸發代理，而不是完整的補充脈絡遮蔽邊界。
|
||||
- DM 歷史控制：
|
||||
- `channels.telegram.mediaMaxMb`（預設 100）會限制傳入與傳出的 Telegram 媒體大小。
|
||||
- `channels.telegram.mediaGroupFlushMs`（預設 500）控制 Telegram 相簿/媒體群組在 OpenClaw 將其作為一則傳入訊息派送前要緩衝多久。如果相簿部分較晚抵達，請增加此值；若要降低相簿回覆延遲，請降低此值。
|
||||
- `channels.telegram.timeoutSeconds` 會覆寫 Telegram API 用戶端逾時（若未設定，則套用 grammY 預設值）。機器人用戶端會將低於 60 秒傳出文字/輸入中請求防護的設定值限制在防護以下，讓 grammY 不會在 OpenClaw 的傳輸防護與備援可執行前中止可見回覆傳遞。長輪詢仍會使用 45 秒的 `getUpdates` 請求防護，因此閒置輪詢不會被無限期放棄。
|
||||
- `channels.telegram.pollingStallThresholdMs` 預設為 `120000`；只有在發生誤判的輪詢停滯重新啟動時，才在 `30000` 到 `600000` 之間調整。
|
||||
- 群組內容歷史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（預設 50）；`0` 會停用。
|
||||
- 回覆/引用/轉寄的補充內容目前會依收到時的樣子傳遞。
|
||||
- Telegram 允許清單主要控管誰可以觸發代理，而不是完整的補充內容遮蔽邊界。
|
||||
- 私訊歷史控制：
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- `channels.telegram.retry` 設定會套用至 Telegram 傳送輔助工具（CLI/tools/actions），用於可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有限的安全傳送重試，但不會重試可能導致可見訊息重複的模糊傳送後網路封包。
|
||||
- `channels.telegram.retry` 設定適用於 Telegram 傳送輔助工具（CLI/工具/動作）處理可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有界限的安全傳送重試，但不會重試可能重複產生可見訊息的模稜兩可送出後網路封套。
|
||||
|
||||
CLI 傳送目標可以是數字聊天 ID 或使用者名稱：
|
||||
CLI 與訊息工具傳送目標可以是數字聊天 ID、使用者名稱，或論壇主題目標：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
|
||||
```
|
||||
|
||||
Telegram 輪詢使用 `openclaw message poll`，並支援論壇主題：
|
||||
@ -801,57 +802,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
僅限 Telegram 的輪詢旗標：
|
||||
僅限 Telegram 的投票旗標：
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` 用於論壇主題（或使用 `:topic:` 目標）
|
||||
- 用於論壇主題的 `--thread-id`（或使用 `:topic:` 目標）
|
||||
|
||||
Telegram 傳送也支援：
|
||||
|
||||
- 當 `channels.telegram.capabilities.inlineButtons` 允許時，使用含有 `buttons` 區塊的 `--presentation` 來建立行內鍵盤
|
||||
- 使用 `--pin` 或 `--delivery '{"pin":true}'`，在 bot 可於該聊天釘選時要求釘選傳遞
|
||||
- 使用 `--force-document`，將傳出圖片和 GIF 作為文件傳送，而不是壓縮相片或動畫媒體上傳
|
||||
- 當 `channels.telegram.capabilities.inlineButtons` 允許時，使用含有 `buttons` 區塊的 `--presentation` 來提供行內鍵盤
|
||||
- 使用 `--pin` 或 `--delivery '{"pin":true}'`，在機器人可在該聊天中釘選時要求釘選傳遞
|
||||
- 使用 `--force-document`，將傳出圖片與 GIF 作為文件傳送，而非壓縮相片或動畫媒體上傳
|
||||
|
||||
動作閘控：
|
||||
動作控管：
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` 會停用傳出 Telegram 訊息，包括輪詢
|
||||
- `channels.telegram.actions.poll=false` 會停用 Telegram 輪詢建立，同時保留一般傳送啟用
|
||||
- `channels.telegram.actions.sendMessage=false` 會停用傳出 Telegram 訊息，包括投票
|
||||
- `channels.telegram.actions.poll=false` 會停用 Telegram 投票建立，同時保留一般傳送啟用
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram 中的 exec 核准">
|
||||
Telegram 支援在核准者 DM 中進行 exec 核准，並可選擇在來源聊天或主題中張貼提示。核准者必須是數字 Telegram 使用者 ID。
|
||||
<Accordion title="Telegram 中的執行核准">
|
||||
Telegram 支援在核准者私訊中進行執行核准，也可選擇在原始聊天或主題中張貼提示。核准者必須是數字 Telegram 使用者 ID。
|
||||
|
||||
設定路徑：
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`（當至少一位核准者可解析時自動啟用）
|
||||
- `channels.telegram.execApprovals.approvers`（後援為來自 `commands.ownerAllowFrom` 的數字擁有者 ID）
|
||||
- `channels.telegram.execApprovals.target`: `dm`（預設）| `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
- `channels.telegram.execApprovals.enabled`（至少有一位可解析核准者時會自動啟用）
|
||||
- `channels.telegram.execApprovals.approvers`（退回使用 `commands.ownerAllowFrom` 中的數字擁有者 ID）
|
||||
- `channels.telegram.execApprovals.target`：`dm`（預設）| `channel` | `both`
|
||||
- `agentFilter`、`sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制誰可以與 bot 對話，以及它會在哪裡傳送一般回覆。它們不會讓某人成為 exec 核准者。當尚未存在命令擁有者時，第一次核准的 DM 配對會啟動 `commands.ownerAllowFrom`，因此單一擁有者設定仍可運作，而不需要在 `execApprovals.approvers` 底下重複 ID。
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制誰可以和機器人交談，以及機器人會在哪裡傳送一般回覆。它們不會讓某人成為執行核准者。當尚未存在指令擁有者時，第一個已核准的私訊配對會啟動 `commands.ownerAllowFrom`，因此單一擁有者設定仍可運作，而不需要在 `execApprovals.approvers` 下重複 ID。
|
||||
|
||||
頻道傳遞會在聊天中顯示命令文字；僅在受信任的群組/主題中啟用 `channel` 或 `both`。當提示落在論壇主題中時，OpenClaw 會保留該主題供核准提示和後續訊息使用。Exec 核准預設會在 30 分鐘後過期。
|
||||
頻道傳遞會在聊天中顯示指令文字；只在受信任的群組/主題中啟用 `channel` 或 `both`。當提示落在論壇主題中時，OpenClaw 會為核准提示與後續訊息保留該主題。執行核准預設會在 30 分鐘後過期。
|
||||
|
||||
行內核准按鈕也需要 `channels.telegram.capabilities.inlineButtons` 允許目標介面（`dm`、`group` 或 `all`）。以 `plugin:` 為前綴的核准 ID 會透過 Plugin 核准解析；其他 ID 會先透過 exec 核准解析。
|
||||
行內核准按鈕也需要 `channels.telegram.capabilities.inlineButtons` 允許目標表面（`dm`、`group` 或 `all`）。以 `plugin:` 為前綴的核准 ID 會透過 plugin 核准解析；其他會先透過執行核准解析。
|
||||
|
||||
請參閱 [Exec 核准](/zh-TW/tools/exec-approvals)。
|
||||
請參閱[執行核准](/zh-TW/tools/exec-approvals)。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 錯誤回覆控制
|
||||
|
||||
當代理遇到傳遞或 Provider 錯誤時，Telegram 可以回覆錯誤文字或加以抑制。兩個設定鍵會控制此行為：
|
||||
當代理遇到傳遞或提供者錯誤時，Telegram 可以回覆錯誤文字或加以抑制。此行為由兩個設定鍵控制：
|
||||
|
||||
| 鍵 | 值 | 預設 | 說明 |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| 鍵 | 值 | 預設 | 說明 |
|
||||
| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 會向聊天傳送友善的錯誤訊息。`silent` 會完全抑制錯誤回覆。 |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 對同一聊天傳送錯誤回覆之間的最短時間。防止中斷期間出現錯誤垃圾訊息。 |
|
||||
| `channels.telegram.errorCooldownMs` | 數字 (ms) | `60000` | 對同一聊天回覆錯誤之間的最短時間。可避免服務中斷期間發生錯誤訊息洗版。 |
|
||||
|
||||
支援每帳號、每群組和每主題覆寫（繼承方式與其他 Telegram 設定鍵相同）。
|
||||
支援逐帳號、逐群組與逐主題覆寫（繼承方式與其他 Telegram 設定鍵相同）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -872,56 +873,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## 疑難排解
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bot 未回應非提及的群組訊息">
|
||||
<Accordion title="機器人不回應未提及的群組訊息">
|
||||
|
||||
- 如果 `requireMention=false`，Telegram 隱私模式必須允許完整可見性。
|
||||
- BotFather：`/setprivacy` -> Disable
|
||||
- 然後將 bot 從群組移除並重新加入
|
||||
- 當設定預期未提及的群組訊息時，`openclaw channels status` 會發出警告。
|
||||
- `openclaw channels status --probe` 可以檢查明確的數字群組 ID；萬用字元 `"*"` 無法進行成員資格探測。
|
||||
- BotFather：`/setprivacy` -> 停用
|
||||
- 然後將機器人從群組移除並重新加入
|
||||
- 當設定預期接收未提及的群組訊息時，`openclaw channels status` 會發出警告。
|
||||
- `openclaw channels status --probe` 可以檢查明確的數字群組 ID；萬用字元 `"*"` 無法探測成員資格。
|
||||
- 快速工作階段測試：`/activation always`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot 完全看不到群組訊息">
|
||||
<Accordion title="機器人完全看不到群組訊息">
|
||||
|
||||
- 當 `channels.telegram.groups` 存在時，群組必須列出（或包含 `"*"`）
|
||||
- 驗證機器人在群組中的成員身分
|
||||
- 檢閱記錄：`openclaw logs --follow` 以查看略過原因
|
||||
- 當 `channels.telegram.groups` 存在時，群組必須列在其中（或包含 `"*"`）
|
||||
- 驗證機器人在群組中的成員資格
|
||||
- 檢閱記錄：使用 `openclaw logs --follow` 查看略過原因
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="指令部分可用或完全無法使用">
|
||||
|
||||
- 授權你的傳送者身分（配對和/或數字 `allowFrom`）
|
||||
- 即使群組政策為 `open`，指令授權仍然適用
|
||||
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示原生選單有太多項目；請減少 plugin/skill/自訂指令，或停用原生選單
|
||||
- `deleteMyCommands` / `setMyCommands` 啟動呼叫和 `sendChatAction` 輸入狀態呼叫都有界限，並會在請求逾時時透過 Telegram 的傳輸備援重試一次。持續的網路/fetch 錯誤通常表示到 `api.telegram.org` 的 DNS/HTTPS 可達性問題
|
||||
- 即使群組政策是 `open`，指令授權仍然適用
|
||||
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示原生選單項目太多；減少 Plugin/Skill/自訂指令，或停用原生選單
|
||||
- `deleteMyCommands` / `setMyCommands` 啟動呼叫與 `sendChatAction` 輸入中呼叫都有界限，並會在請求逾時時透過 Telegram 的傳輸備援重試一次。持續的網路/擷取錯誤通常表示到 `api.telegram.org` 的 DNS/HTTPS 連線可達性問題
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="啟動回報未授權的 token">
|
||||
<Accordion title="啟動回報未授權的權杖">
|
||||
|
||||
- `getMe returned 401` 是 Telegram 對已設定機器人 token 的驗證失敗。
|
||||
- 在 BotFather 重新複製或重新產生機器人 token，然後更新預設帳號的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
|
||||
- 啟動期間的 `deleteWebhook 401 Unauthorized` 也是驗證失敗；若把它視為「沒有 webhook 存在」，只會把相同的錯誤 token 失敗延後到後續 API 呼叫。
|
||||
- `getMe returned 401` 是針對已設定機器人權杖的 Telegram 驗證失敗。
|
||||
- 在 BotFather 中重新複製或重新產生機器人權杖，然後更新預設帳號的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
|
||||
- 啟動期間的 `deleteWebhook 401 Unauthorized` 也是驗證失敗；把它視為「不存在 Webhook」只會把同一個錯誤權杖失敗延後到之後的 API 呼叫。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polling 或網路不穩定">
|
||||
<Accordion title="輪詢或網路不穩定">
|
||||
|
||||
- Node 22+ 加上自訂 fetch/proxy 時，如果 AbortSignal 類型不相符，可能觸發立即中止行為。
|
||||
- 某些主機會先將 `api.telegram.org` 解析為 IPv6；故障的 IPv6 輸出可能導致間歇性 Telegram API 失敗。
|
||||
- 有些主機會先將 `api.telegram.org` 解析為 IPv6；損壞的 IPv6 輸出可能造成 Telegram API 間歇性失敗。
|
||||
- 如果記錄包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 現在會將這些視為可復原的網路錯誤並重試。
|
||||
- 在 polling 啟動期間，OpenClaw 會將成功的啟動 `getMe` 探測重用於 grammY，因此 runner 不需要在第一次 `getUpdates` 之前再做第二次 `getMe`。
|
||||
- 如果 `deleteWebhook` 在 polling 啟動期間因暫時性網路錯誤失敗，OpenClaw 會繼續進入長 polling，而不是再發出一次 pre-poll 控制平面呼叫。仍處於作用中的 webhook 會呈現為 `getUpdates` 衝突；OpenClaw 接著會重建 Telegram 傳輸並重試 webhook 清理。
|
||||
- 如果 Telegram socket 以很短的固定週期回收，請檢查是否有偏低的 `channels.telegram.timeoutSeconds`；機器人用戶端會將設定值箝制在輸出與 `getUpdates` 請求保護值以上，但較舊版本在此值低於那些保護值時，可能會在每次 poll 或回覆時中止。
|
||||
- 如果記錄包含 `Polling stall detected`，OpenClaw 預設會在 120 秒沒有完成長 poll 存活性後重新啟動 polling 並重建 Telegram 傳輸。
|
||||
- `openclaw channels status --probe` 和 `openclaw doctor` 會在執行中的 polling 帳號於啟動寬限期後尚未完成 `getUpdates`、執行中的 webhook 帳號於啟動寬限期後尚未完成 `setWebhook`，或最後一次成功的 polling 傳輸活動已過期時提出警告。
|
||||
- 只有在長時間執行的 `getUpdates` 呼叫是健康的，但你的主機仍回報誤判的 polling 停滯重啟時，才提高 `channels.telegram.pollingStallThresholdMs`。持續停滯通常指向主機與 `api.telegram.org` 之間的 proxy、DNS、IPv6 或 TLS 輸出問題。
|
||||
- Telegram 也會遵循行程 proxy env 進行 Bot API 傳輸，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小寫變體。`NO_PROXY` / `no_proxy` 仍可繞過 `api.telegram.org`。
|
||||
- 如果 OpenClaw 受管理 proxy 在服務環境中透過 `OPENCLAW_PROXY_URL` 設定，且沒有標準 proxy env，Telegram 也會使用該 URL 進行 Bot API 傳輸。
|
||||
- 在直接輸出/TLS 不穩定的 VPS 主機上，請透過 `channels.telegram.proxy` 路由 Telegram API 呼叫：
|
||||
- 在輪詢啟動期間，OpenClaw 會為 grammY 重用成功的啟動 `getMe` 探測，因此執行器不需要在第一次 `getUpdates` 前再做第二次 `getMe`。
|
||||
- 如果 `deleteWebhook` 在輪詢啟動期間因暫時性網路錯誤失敗，OpenClaw 會繼續進入長輪詢，而不是再進行另一次輪詢前控制平面呼叫。仍在作用中的 Webhook 會顯示為 `getUpdates` 衝突；接著 OpenClaw 會重建 Telegram 傳輸並重試 Webhook 清理。
|
||||
- 如果 Telegram socket 以短而固定的節奏回收，請檢查是否有過低的 `channels.telegram.timeoutSeconds`；機器人用戶端會將設定值鉗制在輸出與 `getUpdates` 請求保護值之下，但較舊版本在該值低於這些保護值時，可能會中止每次輪詢或回覆。
|
||||
- 如果記錄包含 `Polling stall detected`，OpenClaw 預設會在 120 秒內沒有完成長輪詢存活訊號後，重新啟動輪詢並重建 Telegram 傳輸。
|
||||
- `openclaw channels status --probe` 和 `openclaw doctor` 會在下列情況發出警告：執行中的輪詢帳號在啟動寬限期後尚未完成 `getUpdates`、執行中的 Webhook 帳號在啟動寬限期後尚未完成 `setWebhook`，或最後一次成功的輪詢傳輸活動已過期。
|
||||
- 只有在長時間執行的 `getUpdates` 呼叫健康，但你的主機仍回報誤判的輪詢停滯重新啟動時，才提高 `channels.telegram.pollingStallThresholdMs`。持續停滯通常指向主機與 `api.telegram.org` 之間的 proxy、DNS、IPv6 或 TLS 輸出問題。
|
||||
- Telegram 也會遵循 Bot API 傳輸的程序 proxy 環境變數，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 以及它們的小寫變體。`NO_PROXY` / `no_proxy` 仍可略過 `api.telegram.org`。
|
||||
- 如果 OpenClaw 受管理 proxy 在服務環境中透過 `OPENCLAW_PROXY_URL` 設定，且沒有標準 proxy 環境變數，Telegram 也會將該 URL 用於 Bot API 傳輸。
|
||||
- 在直接輸出/TLS 不穩定的 VPS 主機上，透過 `channels.telegram.proxy` 路由 Telegram API 呼叫：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -929,8 +930,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ 預設為 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 結果順序會依序遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，再到行程預設值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不適用，Node 22+ 會退回 `ipv4first`。
|
||||
- 如果你的主機是 WSL2，或明確在僅 IPv4 行為下運作較佳，請強制 family selection：
|
||||
- Node 22+ 預設為 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 結果順序會依序遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，再到程序預設值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不適用，Node 22+ 會退回到 `ipv4first`。
|
||||
- 如果你的主機是 WSL2，或明確使用僅 IPv4 行為更好，請強制 family 選擇：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -939,7 +940,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Telegram 媒體下載預設已允許 RFC 2544 基準測試範圍的回應（`198.18.0.0/15`）。如果受信任的 fake-IP 或透明 proxy 在媒體下載期間將 `api.telegram.org` 改寫為其他私人/內部/特殊用途位址，你可以選擇啟用僅限 Telegram 的繞過：
|
||||
- RFC 2544 基準範圍回應（`198.18.0.0/15`）預設已允許用於 Telegram 媒體下載。如果受信任的 fake-IP 或透明 proxy 在媒體下載期間將 `api.telegram.org` 重寫為其他私人/內部/特殊用途位址，你可以選擇啟用僅限 Telegram 的繞過：
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -948,18 +949,17 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- 相同的選擇啟用也可針對每個帳號設定於
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
|
||||
- 同樣的選擇啟用也可按帳號在
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork` 使用。
|
||||
- 如果你的 proxy 將 Telegram 媒體主機解析為 `198.18.x.x`，請先關閉
|
||||
dangerous 旗標。Telegram 媒體預設已允許 RFC 2544
|
||||
基準測試範圍。
|
||||
危險旗標。Telegram 媒體預設已允許 RFC 2544
|
||||
基準範圍。
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 會削弱 Telegram
|
||||
媒體 SSRF 保護。僅在受信任、由操作員控制的 proxy
|
||||
環境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它們
|
||||
合成 RFC 2544 基準測試範圍以外的私人或特殊用途回應時。
|
||||
一般公網 Telegram 存取請保持關閉。
|
||||
環境中使用，例如 Clash、Mihomo 或 Surge fake-IP 路由，且它們會在 RFC 2544 基準
|
||||
範圍之外合成私人或特殊用途回應。一般公開網際網路 Telegram 存取請保持關閉。
|
||||
</Warning>
|
||||
|
||||
- 環境覆寫（暫時）：
|
||||
@ -986,23 +986,23 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
- 啟動/驗證：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必須指向一般檔案；符號連結會被拒絕）
|
||||
- 存取控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、頂層 `bindings[]`（`type: "acp"`）
|
||||
- exec 核准：`execApprovals`、`accounts.*.execApprovals`
|
||||
- 執行核准：`execApprovals`、`accounts.*.execApprovals`
|
||||
- 指令/選單：`commands.native`、`commands.nativeSkills`、`customCommands`
|
||||
- 執行緒/回覆：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies`
|
||||
- 串接/回覆：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies`
|
||||
- 串流：`streaming`（預覽）、`streaming.preview.toolProgress`、`blockStreaming`
|
||||
- 格式/傳送：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 格式/傳遞：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
|
||||
- 媒體/網路：`mediaMaxMb`、`mediaGroupFlushMs`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
|
||||
- 自訂 API 根目錄：`apiRoot`（僅 Bot API 根目錄；請勿包含 `/bot<TOKEN>`）
|
||||
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
|
||||
- 自訂 API 根目錄：`apiRoot`（僅 Bot API 根目錄；不要包含 `/bot<TOKEN>`）
|
||||
- Webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
|
||||
- 動作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- 回應：`reactionNotifications`、`reactionLevel`
|
||||
- 回應表情：`reactionNotifications`、`reactionLevel`
|
||||
- 錯誤：`errorPolicy`、`errorCooldownMs`
|
||||
- 寫入/歷史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
- 寫入/歷史記錄：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
多帳號優先順序：設定兩個或更多帳號 ID 時，請設定 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），使預設路由明確。否則 OpenClaw 會退回第一個正規化帳號 ID，且 `openclaw doctor` 會發出警告。具名帳號會繼承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不會繼承 `accounts.default.*` 值。
|
||||
多帳號優先順序：設定兩個或更多帳號 ID 時，請設定 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以明確指定預設路由。否則 OpenClaw 會退回到第一個正規化帳號 ID，且 `openclaw doctor` 會發出警告。具名帳號會繼承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不會繼承 `accounts.default.*` 值。
|
||||
</Note>
|
||||
|
||||
## 相關
|
||||
@ -1015,13 +1015,13 @@ dig +short api.telegram.org AAAA
|
||||
群組和主題允許清單行為。
|
||||
</Card>
|
||||
<Card title="Channel 路由" icon="route" href="/zh-TW/channels/channel-routing">
|
||||
將傳入訊息路由至代理。
|
||||
將傳入訊息路由到代理。
|
||||
</Card>
|
||||
<Card title="安全性" icon="shield" href="/zh-TW/gateway/security">
|
||||
威脅模型與強化。
|
||||
</Card>
|
||||
<Card title="多代理路由" icon="sitemap" href="/zh-TW/concepts/multi-agent">
|
||||
將群組和主題對應至代理。
|
||||
將群組和主題對應到代理。
|
||||
</Card>
|
||||
<Card title="疑難排解" icon="wrench" href="/zh-TW/channels/troubleshooting">
|
||||
跨 Channel 診斷。
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 新增或修改訊息 CLI 動作
|
||||
- 變更傳出通道行為
|
||||
- 變更出站通道行為
|
||||
summary: '`openclaw message` 的 CLI 參考（傳送 + 頻道動作）'
|
||||
title: 訊息
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:48Z"
|
||||
generated_at: "2026-05-04T09:36:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55
|
||||
source_hash: 9ef57d33c93206a61a6d044667de4faf6340f7d8cc324300f235e838ee3b7ff1
|
||||
source_path: cli/message.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -16,7 +16,7 @@ x-i18n:
|
||||
# `openclaw message`
|
||||
|
||||
用於傳送訊息與頻道動作的單一外送命令
|
||||
(Discord/Google Chat/iMessage/Matrix/Mattermost (Plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp)。
|
||||
（Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。
|
||||
|
||||
## 用法
|
||||
|
||||
@ -26,79 +26,79 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
頻道選擇：
|
||||
|
||||
- 如果設定了多個頻道，則必須提供 `--channel`。
|
||||
- 如果剛好只設定一個頻道，該頻道會成為預設值。
|
||||
- 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost 需要 Plugin)
|
||||
- 當存在 `--channel` 或帶有頻道前綴的目標時，`openclaw message` 會將所選頻道解析為其所屬的 Plugin；否則會載入已設定的頻道 Plugin 以推斷預設頻道。
|
||||
- 如果設定了多個頻道，則需要 `--channel`。
|
||||
- 如果只設定了一個頻道，該頻道會成為預設值。
|
||||
- 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要 plugin）
|
||||
- 當存在 `--channel` 或帶有頻道前綴的目標時，`openclaw message` 會將選取的頻道解析到其所屬 Plugin；否則會載入已設定的頻道 Plugin，以推斷預設頻道。
|
||||
|
||||
目標格式 (`--target`)：
|
||||
目標格式（`--target`）：
|
||||
|
||||
- WhatsApp：E.164、群組 JID，或 WhatsApp Channel/Newsletter JID (`...@newsletter`)
|
||||
- Telegram：聊天 ID 或 `@username`
|
||||
- Discord：`channel:<id>` 或 `user:<id>` (或 `<@id>` 提及；原始數字 ID 會被視為頻道)
|
||||
- WhatsApp：E.164、群組 JID，或 WhatsApp Channel/Newsletter JID（`...@newsletter`）
|
||||
- Telegram：聊天 ID、`@username`，或論壇主題目標（`-1001234567890:topic:42`，或 `--thread-id 42`）
|
||||
- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始數字 ID 會視為頻道）
|
||||
- Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
|
||||
- Slack：`channel:<id>` 或 `user:<id>` (接受原始頻道 ID)
|
||||
- Mattermost (Plugin)：`channel:<id>`、`user:<id>` 或 `@username` (裸 ID 會被視為頻道)
|
||||
- Slack：`channel:<id>` 或 `user:<id>`（接受原始頻道 ID）
|
||||
- Mattermost (plugin)：`channel:<id>`、`user:<id>`，或 `@username`（裸 ID 會視為頻道）
|
||||
- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>`，或 `username:<name>`/`u:<name>`
|
||||
- iMessage：處理代號、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
|
||||
- Matrix：`@user:server`、`!room:server` 或 `#alias:server`
|
||||
- Microsoft Teams：對話 ID (`19:...@thread.tacv2`) 或 `conversation:<id>` 或 `user:<aad-object-id>`
|
||||
- iMessage：handle、`chat_id:<id>`、`chat_guid:<guid>`，或 `chat_identifier:<id>`
|
||||
- Matrix：`@user:server`、`!room:server`，或 `#alias:server`
|
||||
- Microsoft Teams：對話 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
|
||||
|
||||
名稱查詢：
|
||||
名稱查找：
|
||||
|
||||
- 對於支援的提供者 (Discord/Slack/等)，像 `Help` 或 `#help` 這樣的頻道名稱會透過目錄快取解析。
|
||||
- 快取未命中時，如果提供者支援，OpenClaw 會嘗試即時目錄查詢。
|
||||
- 對於支援的提供者（Discord/Slack 等），像 `Help` 或 `#help` 這類頻道名稱會透過目錄快取解析。
|
||||
- 快取未命中時，若提供者支援，OpenClaw 會嘗試即時目錄查找。
|
||||
|
||||
## 常用旗標
|
||||
## 常用 flags
|
||||
|
||||
- `--channel <name>`
|
||||
- `--account <id>`
|
||||
- `--target <dest>` (send/poll/read/等的目標頻道或使用者)
|
||||
- `--targets <name>` (可重複；僅限廣播)
|
||||
- `--target <dest>`（用於傳送/輪詢/讀取等的目標頻道或使用者）
|
||||
- `--targets <name>`（可重複；僅限廣播）
|
||||
- `--json`
|
||||
- `--dry-run`
|
||||
- `--verbose`
|
||||
|
||||
## SecretRef 行為
|
||||
|
||||
- `openclaw message` 會在執行所選動作前解析支援頻道的 SecretRefs。
|
||||
- 解析會在可能時限定於作用中的動作目標：
|
||||
- 設定 `--channel` 時以頻道為範圍 (或從像 `discord:...` 這樣的前綴目標推斷)
|
||||
- 設定 `--account` 時以帳戶為範圍 (頻道全域 + 所選帳戶表面)
|
||||
- 省略 `--account` 時，OpenClaw 不會強制使用 `default` 帳戶 SecretRef 範圍
|
||||
- 無關頻道上未解析的 SecretRefs 不會阻擋目標式訊息動作。
|
||||
- 如果所選頻道/帳戶 SecretRef 未解析，該命令會對該動作以失敗關閉。
|
||||
- `openclaw message` 會在執行選取的動作前解析支援的頻道 SecretRefs。
|
||||
- 解析會在可行時限定於作用中動作目標範圍：
|
||||
- 設定 `--channel` 時為頻道範圍（或從像 `discord:...` 這類帶前綴的目標推斷）
|
||||
- 設定 `--account` 時為帳號範圍（頻道全域 + 選取的帳號表面）
|
||||
- 省略 `--account` 時，OpenClaw 不會強制使用 `default` 帳號 SecretRef 範圍
|
||||
- 不相關頻道上未解析的 SecretRefs 不會阻擋目標訊息動作。
|
||||
- 如果選取的頻道/帳號 SecretRef 未解析，該動作的命令會關閉失敗。
|
||||
|
||||
## 動作
|
||||
|
||||
### 核心
|
||||
|
||||
- `send`
|
||||
- 頻道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- 頻道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- 必要：`--target`，以及 `--message`、`--media` 或 `--presentation`
|
||||
- 選用：`--media`、`--presentation`、`--delivery`、`--pin`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent`
|
||||
- 共用簡報承載：`--presentation` 會傳送語意區塊 (`text`、`context`、`divider`、`buttons`、`select`)，核心會透過所選頻道宣告的能力轉譯。請參閱 [訊息簡報](/zh-TW/plugins/message-presentation)。
|
||||
- 通用遞送偏好：`--delivery` 接受像 `{ "pin": true }` 這樣的遞送提示；當頻道支援時，`--pin` 是釘選遞送的簡寫。
|
||||
- 僅限 Telegram：`--force-document` (將圖片與 GIF 作為文件傳送，以避免 Telegram 壓縮)
|
||||
- 僅限 Telegram：`--thread-id` (論壇主題 ID)
|
||||
- 僅限 Slack：`--thread-id` (討論串時間戳記；`--reply-to` 使用相同欄位)
|
||||
- 共用 presentation payload：`--presentation` 會傳送語意區塊（`text`、`context`、`divider`、`buttons`、`select`），核心會透過選取頻道宣告的能力來轉譯。請參閱 [訊息呈現](/zh-TW/plugins/message-presentation)。
|
||||
- 通用 delivery 偏好設定：`--delivery` 接受例如 `{ "pin": true }` 的 delivery 提示；當頻道支援時，`--pin` 是 pinned delivery 的簡寫。
|
||||
- 僅限 Telegram：`--force-document`（將圖片和 GIF 作為文件傳送，以避免 Telegram 壓縮）
|
||||
- 僅限 Telegram：`--thread-id`（論壇主題 ID）
|
||||
- 僅限 Slack：`--thread-id`（thread timestamp；`--reply-to` 使用相同欄位）
|
||||
- Telegram + Discord：`--silent`
|
||||
- 僅限 WhatsApp：`--gif-playback`；WhatsApp Channels/Newsletters 使用其原生 `@newsletter` JID 定址。
|
||||
- 僅限 WhatsApp：`--gif-playback`；WhatsApp Channels/Newsletters 以其原生 `@newsletter` JID 定址。
|
||||
|
||||
- `poll`
|
||||
- 頻道：WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
|
||||
- 必要：`--target`、`--poll-question`、`--poll-option` (可重複)
|
||||
- 必要：`--target`、`--poll-question`、`--poll-option`（可重複）
|
||||
- 選用：`--poll-multi`
|
||||
- 僅限 Discord：`--poll-duration-hours`、`--silent`、`--message`
|
||||
- 僅限 Telegram：`--poll-duration-seconds` (5-600)、`--silent`、`--poll-anonymous` / `--poll-public`、`--thread-id`
|
||||
- 僅限 Telegram：`--poll-duration-seconds`（5-600）、`--silent`、`--poll-anonymous` / `--poll-public`、`--thread-id`
|
||||
|
||||
- `react`
|
||||
- 頻道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
|
||||
- 必要：`--message-id`、`--target`
|
||||
- 選用：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
|
||||
- 注意：`--remove` 需要 `--emoji` (省略 `--emoji` 可在支援處清除自己的反應；請參閱 /tools/reactions)
|
||||
- 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支援處清除自己的 reactions；請參閱 /tools/reactions）
|
||||
- 僅限 WhatsApp：`--participant`、`--from-me`
|
||||
- Signal 群組反應：必須提供 `--target-author` 或 `--target-author-uuid`
|
||||
- Signal 群組 reactions：需要 `--target-author` 或 `--target-author-uuid`
|
||||
|
||||
- `reactions`
|
||||
- 頻道：Discord/Google Chat/Slack/Matrix
|
||||
@ -109,7 +109,7 @@ openclaw message <subcommand> [flags]
|
||||
- 頻道：Discord/Slack/Matrix
|
||||
- 必要：`--target`
|
||||
- 選用：`--limit`、`--message-id`、`--before`、`--after`
|
||||
- 僅限 Slack：`--message-id` 會讀取特定 Slack 訊息時間戳記；搭配 `--thread-id` 可讀取精確的討論串回覆。
|
||||
- 僅限 Slack：`--message-id` 會讀取特定 Slack 訊息 timestamp；搭配 `--thread-id` 可讀取精確的 thread 回覆。
|
||||
- 僅限 Discord：`--around`
|
||||
|
||||
- `edit`
|
||||
@ -124,25 +124,25 @@ openclaw message <subcommand> [flags]
|
||||
- 頻道：Discord/Slack/Matrix
|
||||
- 必要：`--message-id`、`--target`
|
||||
|
||||
- `pins` (列出)
|
||||
- `pins`（列出）
|
||||
- 頻道：Discord/Slack/Matrix
|
||||
- 必要：`--target`
|
||||
|
||||
- `permissions`
|
||||
- 頻道：Discord/Matrix
|
||||
- 必要：`--target`
|
||||
- 僅限 Matrix：在啟用 Matrix 加密且允許驗證動作時可用
|
||||
- 僅限 Matrix：當 Matrix 加密已啟用且允許驗證動作時可用
|
||||
|
||||
- `search`
|
||||
- 頻道：Discord
|
||||
- 必要：`--guild-id`、`--query`
|
||||
- 選用：`--channel-id`、`--channel-ids` (可重複)、`--author-id`、`--author-ids` (可重複)、`--limit`
|
||||
- 選用：`--channel-id`、`--channel-ids`（可重複）、`--author-id`、`--author-ids`（可重複）、`--limit`
|
||||
|
||||
### 討論串
|
||||
### Threads
|
||||
|
||||
- `thread create`
|
||||
- 頻道：Discord
|
||||
- 必要：`--thread-name`、`--target` (頻道 ID)
|
||||
- 必要：`--thread-name`、`--target`（頻道 ID）
|
||||
- 選用：`--message-id`、`--message`、`--auto-archive-min`
|
||||
|
||||
- `thread list`
|
||||
@ -152,25 +152,25 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
- `thread reply`
|
||||
- 頻道：Discord
|
||||
- 必要：`--target` (討論串 ID)、`--message`
|
||||
- 必要：`--target`（thread ID）、`--message`
|
||||
- 選用：`--media`、`--reply-to`
|
||||
|
||||
### 表情符號
|
||||
|
||||
- `emoji list`
|
||||
- Discord：`--guild-id`
|
||||
- Slack：沒有額外旗標
|
||||
- Slack：沒有額外 flags
|
||||
|
||||
- `emoji upload`
|
||||
- 頻道：Discord
|
||||
- 必要：`--guild-id`、`--emoji-name`、`--media`
|
||||
- 選用：`--role-ids` (可重複)
|
||||
- 選用：`--role-ids`（可重複）
|
||||
|
||||
### 貼圖
|
||||
|
||||
- `sticker send`
|
||||
- 頻道：Discord
|
||||
- 必要：`--target`、`--sticker-id` (可重複)
|
||||
- 必要：`--target`、`--sticker-id`（可重複）
|
||||
- 選用：`--message`
|
||||
|
||||
- `sticker upload`
|
||||
@ -179,30 +179,30 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
### 角色 / 頻道 / 成員 / 語音
|
||||
|
||||
- `role info` (Discord)：`--guild-id`
|
||||
- `role add` / `role remove` (Discord)：`--guild-id`、`--user-id`、`--role-id`
|
||||
- `channel info` (Discord)：`--target`
|
||||
- `channel list` (Discord)：`--guild-id`
|
||||
- `member info` (Discord/Slack)：`--user-id` (Discord 另需 `--guild-id`)
|
||||
- `voice status` (Discord)：`--guild-id`、`--user-id`
|
||||
- `role info`（Discord）：`--guild-id`
|
||||
- `role add` / `role remove`（Discord）：`--guild-id`、`--user-id`、`--role-id`
|
||||
- `channel info`（Discord）：`--target`
|
||||
- `channel list`（Discord）：`--guild-id`
|
||||
- `member info`（Discord/Slack）：`--user-id`（Discord 另需 `--guild-id`）
|
||||
- `voice status`（Discord）：`--guild-id`、`--user-id`
|
||||
|
||||
### 事件
|
||||
|
||||
- `event list` (Discord)：`--guild-id`
|
||||
- `event create` (Discord)：`--guild-id`、`--event-name`、`--start-time`
|
||||
- `event list`（Discord）：`--guild-id`
|
||||
- `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
|
||||
- 選用：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
|
||||
|
||||
### 管理 (Discord)
|
||||
### 管理（Discord）
|
||||
|
||||
- `timeout`：`--guild-id`、`--user-id` (選用 `--duration-min` 或 `--until`；兩者皆省略可清除逾時)
|
||||
- `kick`：`--guild-id`、`--user-id` (+ `--reason`)
|
||||
- `ban`：`--guild-id`、`--user-id` (+ `--delete-days`、`--reason`)
|
||||
- `timeout`：`--guild-id`、`--user-id`（選用 `--duration-min` 或 `--until`；兩者都省略則清除 timeout）
|
||||
- `kick`：`--guild-id`、`--user-id`（+ `--reason`）
|
||||
- `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
|
||||
- `timeout` 也支援 `--reason`
|
||||
|
||||
### 廣播
|
||||
|
||||
- `broadcast`
|
||||
- 頻道：任何已設定的頻道；使用 `--channel all` 以目標設定所有提供者
|
||||
- 頻道：任何已設定的頻道；使用 `--channel all` 以目標所有提供者
|
||||
- 必要：`--targets <target...>`
|
||||
- 選用：`--message`、`--media`、`--dry-run`
|
||||
|
||||
@ -215,7 +215,7 @@ openclaw message send --channel discord \
|
||||
--target channel:123 --message "hi" --reply-to 456
|
||||
```
|
||||
|
||||
傳送含語意按鈕的訊息：
|
||||
傳送帶有語意按鈕的訊息：
|
||||
|
||||
```
|
||||
openclaw message send --channel discord \
|
||||
@ -223,9 +223,9 @@ openclaw message send --channel discord \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
|
||||
```
|
||||
|
||||
核心會根據頻道能力，將相同的 `presentation` 承載轉譯為 Discord 元件、Slack 區塊、Telegram 行內按鈕、Mattermost props，或 Teams/Feishu 卡片。完整合約與備援規則請參閱 [訊息簡報](/zh-TW/plugins/message-presentation)。
|
||||
核心會依據頻道能力，將相同的 `presentation` payload 轉譯成 Discord components、Slack blocks、Telegram inline buttons、Mattermost props，或 Teams/Feishu cards。完整合約與 fallback 規則請參閱 [訊息呈現](/zh-TW/plugins/message-presentation)。
|
||||
|
||||
傳送更豐富的簡報承載：
|
||||
傳送更豐富的 presentation payload：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel googlechat --target spaces/AAA... \
|
||||
@ -233,7 +233,7 @@ openclaw message send --channel googlechat --target spaces/AAA... \
|
||||
--presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}'
|
||||
```
|
||||
|
||||
建立 Discord 投票：
|
||||
建立 Discord poll：
|
||||
|
||||
```
|
||||
openclaw message poll --channel discord \
|
||||
@ -243,7 +243,7 @@ openclaw message poll --channel discord \
|
||||
--poll-multi --poll-duration-hours 48
|
||||
```
|
||||
|
||||
建立 Telegram 投票 (2 分鐘後自動關閉)：
|
||||
建立 Telegram poll（2 分鐘後自動關閉）：
|
||||
|
||||
```
|
||||
openclaw message poll --channel telegram \
|
||||
@ -253,14 +253,14 @@ openclaw message poll --channel telegram \
|
||||
--poll-duration-seconds 120 --silent
|
||||
```
|
||||
|
||||
傳送 Teams 主動訊息：
|
||||
傳送 Teams proactive 訊息：
|
||||
|
||||
```
|
||||
openclaw message send --channel msteams \
|
||||
--target conversation:19:abc@thread.tacv2 --message "hi"
|
||||
```
|
||||
|
||||
建立 Teams 投票：
|
||||
建立 Teams poll：
|
||||
|
||||
```
|
||||
openclaw message poll --channel msteams \
|
||||
@ -269,14 +269,14 @@ openclaw message poll --channel msteams \
|
||||
--poll-option Pizza --poll-option Sushi
|
||||
```
|
||||
|
||||
在 Slack 中反應：
|
||||
在 Slack 加上 reaction：
|
||||
|
||||
```
|
||||
openclaw message react --channel slack \
|
||||
--target C123 --message-id 456 --emoji "✅"
|
||||
```
|
||||
|
||||
在 Signal 群組中反應：
|
||||
在 Signal 群組加上 reaction：
|
||||
|
||||
```
|
||||
openclaw message react --channel signal \
|
||||
@ -284,14 +284,14 @@ openclaw message react --channel signal \
|
||||
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
|
||||
```
|
||||
|
||||
透過通用簡報傳送 Telegram 行內按鈕：
|
||||
透過通用 presentation 傳送 Telegram inline buttons：
|
||||
|
||||
```
|
||||
openclaw message send --channel telegram --target @mychat --message "Choose:" \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
|
||||
```
|
||||
|
||||
透過通用簡報傳送 Teams 卡片：
|
||||
透過通用 presentation 傳送 Teams card：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel msteams \
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- 您想要安裝或管理 Gateway Plugin 或相容套件包
|
||||
- 您想要偵錯 Plugin 載入失敗
|
||||
- 你想安裝或管理 Gateway Plugin 或相容套件組合
|
||||
- 你想要偵錯 Plugin 載入失敗問題
|
||||
sidebarTitle: Plugins
|
||||
summary: '`openclaw plugins` 的 CLI 參考（list、install、marketplace、uninstall、enable/disable、doctor）'
|
||||
summary: '`openclaw plugins` 的 CLI 參考（列出、安裝、市集、解除安裝、啟用/停用、診斷）'
|
||||
title: Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:03:02Z"
|
||||
generated_at: "2026-05-04T09:37:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
|
||||
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
管理 Gateway Plugin、hook 套件包和相容套組。
|
||||
管理 Gateway Plugin、hook 套件包與相容套件組。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugin 系統" href="/zh-TW/tools/plugin">
|
||||
安裝、啟用和疑難排解 Plugin 的終端使用者指南。
|
||||
<Card title="Plugin system" href="/zh-TW/tools/plugin">
|
||||
安裝、啟用與疑難排解 Plugin 的終端使用者指南。
|
||||
</Card>
|
||||
<Card title="管理 Plugin" href="/zh-TW/plugins/manage-plugins">
|
||||
安裝、列出、更新、解除安裝和發布的快速範例。
|
||||
<Card title="Manage plugins" href="/zh-TW/plugins/manage-plugins">
|
||||
安裝、列出、更新、解除安裝與發布的快速範例。
|
||||
</Card>
|
||||
<Card title="Plugin 套組" href="/zh-TW/plugins/bundles">
|
||||
套組相容性模型。
|
||||
<Card title="Plugin bundles" href="/zh-TW/plugins/bundles">
|
||||
套件組相容性模型。
|
||||
</Card>
|
||||
<Card title="Plugin manifest" href="/zh-TW/plugins/manifest">
|
||||
Manifest 欄位和設定結構描述。
|
||||
資訊清單欄位與設定結構描述。
|
||||
</Card>
|
||||
<Card title="安全性" href="/zh-TW/gateway/security">
|
||||
Plugin 安裝的安全性強化。
|
||||
<Card title="Security" href="/zh-TW/gateway/security">
|
||||
Plugin 安裝的安全強化。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -62,14 +62,14 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
若要調查緩慢的安裝、檢查、解除安裝或 registry 重新整理，請以 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行命令。追蹤會將階段計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。
|
||||
若要調查緩慢的安裝、檢查、解除安裝或登錄重新整理，請搭配 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` 執行命令。追蹤會將階段計時寫入 stderr，並讓 JSON 輸出保持可解析。請參閱[偵錯](/zh-TW/help/debugging#plugin-lifecycle-trace)。
|
||||
|
||||
<Note>
|
||||
隨附 Plugin 會與 OpenClaw 一起提供。有些預設啟用（例如隨附模型提供者、隨附語音提供者，以及隨附瀏覽器 Plugin）；其他則需要 `plugins enable`。
|
||||
隨附的 Plugin 會與 OpenClaw 一起提供。有些預設啟用（例如隨附的模型提供者、隨附的語音提供者，以及隨附的瀏覽器 Plugin）；其他則需要執行 `plugins enable`。
|
||||
|
||||
原生 OpenClaw Plugin 必須隨附 `openclaw.plugin.json`，並包含內嵌 JSON Schema（`configSchema`，即使為空也一樣）。相容套組則改用自己的套組 manifest。
|
||||
原生 OpenClaw Plugin 必須提供 `openclaw.plugin.json`，並包含內嵌 JSON Schema（`configSchema`，即使是空的也一樣）。相容套件組則改用自己的套件組資訊清單。
|
||||
|
||||
`plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。詳細清單/資訊輸出也會顯示套組子類型（`codex`、`claude` 或 `cursor`）以及偵測到的套組功能。
|
||||
`plugins list` 會顯示 `Format: openclaw` 或 `Format: bundle`。詳細列出/資訊輸出也會顯示套件組子類型（`codex`、`claude` 或 `cursor`）以及偵測到的套件組功能。
|
||||
</Note>
|
||||
|
||||
### 安裝
|
||||
@ -91,75 +91,75 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
在啟動切換期間，裸套件名稱預設會從 npm 安裝。若要使用 ClawHub，請使用 `clawhub:<package>`。請將安裝 Plugin 視為執行程式碼。建議使用釘選版本。
|
||||
在啟動切換期間，裸套件名稱預設會從 npm 安裝。ClawHub 請使用 `clawhub:<package>`。請將 Plugin 安裝視同執行程式碼。建議使用釘選版本。
|
||||
</Warning>
|
||||
|
||||
`plugins search` 會查詢 ClawHub 中可安裝的 Plugin 套件，並列印可直接安裝的套件名稱。它會搜尋 code-plugin 和 bundle-plugin 套件，而不是 Skills。若要搜尋 ClawHub Skills，請使用 `openclaw skills search`。
|
||||
`plugins search` 會查詢 ClawHub 中可安裝的 Plugin 套件，並印出可直接安裝的套件名稱。它會搜尋 code-plugin 與 bundle-plugin 套件，而不是 Skills。若要搜尋 ClawHub Skills，請使用 `openclaw skills search`。
|
||||
|
||||
<Note>
|
||||
ClawHub 是大多數 Plugin 的主要散布與探索介面。Npm 仍是受支援的備援與直接安裝路徑。OpenClaw 擁有的 `@openclaw/*` Plugin 套件已再次發布到 npm；請在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [Plugin 清單](/zh-TW/plugins/plugin-inventory)查看目前清單。穩定安裝使用 `latest`。Beta 頻道安裝與更新會在 npm `beta` dist-tag 可用時優先使用該標籤，然後才退回 `latest`。
|
||||
ClawHub 是大多數 Plugin 的主要發佈與探索介面。npm 仍是受支援的備援與直接安裝路徑。OpenClaw 擁有的 `@openclaw/*` Plugin 套件已重新發布到 npm；請在 [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) 或 [Plugin 清單](/zh-TW/plugins/plugin-inventory)查看目前清單。穩定版安裝使用 `latest`。Beta 通道安裝與更新會在 npm `beta` dist-tag 可用時優先使用該標籤，然後才回退到 `latest`。
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="設定 include 與無效設定修復">
|
||||
如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該 include 檔案，並讓 `openclaw.json` 保持不變。根 include、include 陣列，以及含有同層覆寫的 include 都會封閉失敗，而不是攤平成一般設定。請參閱[設定 include](/zh-TW/gateway/configuration) 了解支援的形狀。
|
||||
<Accordion title="Config includes and invalid-config repair">
|
||||
如果你的 `plugins` 區段由單一檔案 `$include` 支援，`plugins install/update/enable/disable/uninstall` 會寫入該被包含的檔案，並保持 `openclaw.json` 不變。根層包含、包含陣列，以及帶有同層覆寫的包含都會封閉失敗，而不是攤平成單一內容。支援的形狀請參閱[設定包含](/zh-TW/gateway/configuration)。
|
||||
|
||||
如果安裝期間設定無效，`plugins install` 通常會封閉失敗，並告訴你先執行 `openclaw doctor --fix`。在 Gateway 啟動與熱重新載入期間，無效的 Plugin 設定會像其他無效設定一樣封閉失敗；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一有文件記載的安裝時例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin 所提供的狹窄隨附 Plugin 復原路徑。
|
||||
如果安裝期間設定無效，`plugins install` 通常會封閉失敗，並告訴你先執行 `openclaw doctor --fix`。在 Gateway 啟動與熱重新載入期間，無效的 Plugin 設定會像任何其他無效設定一樣封閉失敗；`openclaw doctor --fix` 可以隔離無效的 Plugin 項目。唯一記載的安裝時例外，是針對明確選擇加入 `openclaw.install.allowInvalidConfigRecovery` 的 Plugin 所提供的狹窄隨附 Plugin 復原路徑。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force、重新安裝與更新">
|
||||
`--force` 會重用既有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件包。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm 成品重新安裝相同 id 時使用它。若要例行升級已追蹤的 npm Plugin，請優先使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
<Accordion title="--force and reinstall vs update">
|
||||
`--force` 會重用現有安裝目標，並就地覆寫已安裝的 Plugin 或 hook 套件包。當你有意從新的本機路徑、封存檔、ClawHub 套件或 npm 成品重新安裝相同 id 時使用。對於已追蹤的 npm Plugin 的例行升級，建議使用 `openclaw plugins update <id-or-npm-spec>`。
|
||||
|
||||
如果你針對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止，並指引你使用 `plugins update <id-or-npm-spec>` 進行一般升級；如果你確實想從不同來源覆寫目前安裝，則使用 `plugins install <package> --force`。
|
||||
如果你對已安裝的 Plugin id 執行 `plugins install`，OpenClaw 會停止並指引你使用 `plugins update <id-or-npm-spec>` 進行一般升級，或在你確實想從不同來源覆寫目前安裝時，使用 `plugins install <package> --force`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--pin 範圍">
|
||||
`--pin` 只適用於 npm 安裝。不支援搭配 `git:` 安裝；當你想釘選來源時，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它不支援搭配 `--marketplace`，因為 marketplace 安裝會保存 marketplace 來源中繼資料，而不是 npm spec。
|
||||
<Accordion title="--pin scope">
|
||||
`--pin` 只適用於 npm 安裝。不支援搭配 `git:` 安裝；若你想要釘選來源，請使用明確的 git ref，例如 `git:github.com/acme/plugin@v1.2.3`。它也不支援搭配 `--marketplace`，因為 marketplace 安裝會保留 marketplace 來源中繼資料，而不是 npm 規格。
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` 是針對內建危險程式碼掃描器誤報的緊急選項。即使內建掃描器回報 `critical` 發現，它也允許安裝繼續，但它**不會**繞過 Plugin `before_install` hook 政策封鎖，也**不會**繞過掃描失敗。
|
||||
`--dangerously-force-unsafe-install` 是針對內建危險程式碼掃描器誤判的緊急選項。即使內建掃描器回報 `critical` 發現，它也允許安裝繼續，但它**不會**略過 Plugin `before_install` hook 政策阻擋，也**不會**略過掃描失敗。
|
||||
|
||||
此 CLI 旗標適用於 Plugin 安裝/更新流程。Gateway 支援的 skill 相依性安裝使用對應的 `dangerouslyForceUnsafeInstall` 請求覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
|
||||
此 CLI 旗標適用於 Plugin 安裝/更新流程。由 Gateway 支援的 skill 相依性安裝會使用對應的 `dangerouslyForceUnsafeInstall` 請求覆寫，而 `openclaw skills install` 仍是獨立的 ClawHub skill 下載/安裝流程。
|
||||
|
||||
如果你發布在 ClawHub 上的 Plugin 被 registry 掃描封鎖，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的發布者步驟。
|
||||
如果你發布在 ClawHub 的 Plugin 被登錄掃描阻擋，請使用 [ClawHub](/zh-TW/tools/clawhub) 中的發布者步驟。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hook 套件包和 npm spec">
|
||||
`plugins install` 也是安裝在 `package.json` 中公開 `openclaw.hooks` 的 hook 套件包的介面。請使用 `openclaw hooks` 取得經篩選的 hook 可見性與逐 hook 啟用，而不是用於套件安裝。
|
||||
<Accordion title="Hook packs and npm specs">
|
||||
`plugins install` 也是安裝 hook 套件包的介面，這些套件包會在 `package.json` 中公開 `openclaw.hooks`。請使用 `openclaw hooks` 取得篩選後的 hook 可見性與個別 hook 啟用狀態，而不是用於套件安裝。
|
||||
|
||||
Npm spec **僅限 registry**（套件名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file spec 和 semver 範圍會被拒絕。即使你的 shell 有全域 npm 安裝設定，相依性安裝也會以專案本機方式搭配 `--ignore-scripts` 執行以確保安全。
|
||||
npm 規格是**僅限登錄**（套件名稱 + 選用的**精確版本**或 **dist-tag**）。Git/URL/file 規格與 semver 範圍會被拒絕。為了安全，即使你的 shell 有全域 npm 安裝設定，相依性安裝也會以專案本機方式搭配 `--ignore-scripts` 執行。
|
||||
|
||||
當你想明確使用 npm 解析時，請使用 `npm:<package>`。在啟動切換期間，裸套件 spec 也會直接從 npm 安裝。
|
||||
當你想明確使用 npm 解析時，請使用 `npm:<package>`。在啟動切換期間，裸套件規格也會直接從 npm 安裝。
|
||||
|
||||
裸 spec 和 `@latest` 會留在穩定軌道。OpenClaw 日期戳記修正版本，例如 `2026.5.3-1`，在此檢查中屬於穩定發布。如果 npm 將其中任一解析為 prerelease，OpenClaw 會停止並要求你以 prerelease 標籤（例如 `@beta`/`@rc`）或精確 prerelease 版本（例如 `@1.2.3-beta.4`）明確選擇加入。
|
||||
裸規格與 `@latest` 會保持在穩定軌道。OpenClaw 日期戳記修正版（例如 `2026.5.3-1`）在此檢查中屬於穩定版本。如果 npm 將其中任一解析為預發行版本，OpenClaw 會停止並要求你以預發行標籤（例如 `@beta`/`@rc`）或精確預發行版本（例如 `@1.2.3-beta.4`）明確選擇加入。
|
||||
|
||||
如果裸安裝 spec 符合官方 Plugin id（例如 `diffs`），OpenClaw 會直接安裝 catalog 項目。若要安裝同名 npm 套件，請使用明確的 scoped spec（例如 `@scope/diffs`）。
|
||||
如果裸安裝規格符合官方 Plugin id（例如 `diffs`），OpenClaw 會直接安裝目錄項目。若要安裝同名 npm 套件，請使用明確的 scoped 規格（例如 `@scope/diffs`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Git 儲存庫">
|
||||
使用 `git:<repo>` 可直接從 git 儲存庫安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。加入 `@<ref>` 或 `#<ref>` 可在安裝前 checkout 分支、標籤或 commit。
|
||||
<Accordion title="Git repositories">
|
||||
使用 `git:<repo>` 可直接從 git 儲存庫安裝。支援的形式包括 `git:github.com/owner/repo`、`git:owner/repo`、完整的 `https://`、`ssh://`、`git://`、`file://`，以及 `git@host:owner/repo.git` clone URL。加入 `@<ref>` 或 `#<ref>` 可在安裝前取出分支、標籤或 commit。
|
||||
|
||||
Git 安裝會 clone 到暫存目錄，在 ref 存在時 checkout 要求的 ref，然後使用一般 Plugin 目錄安裝器。這表示 manifest 驗證、危險程式碼掃描、套件管理器安裝工作，以及安裝記錄的行為都會像 npm 安裝一樣。記錄下來的 git 安裝包含來源 URL/ref 以及解析後的 commit，因此 `openclaw plugins update` 之後可以重新解析來源。
|
||||
Git 安裝會 clone 到暫存目錄，在有要求的 ref 時將其取出，然後使用一般 Plugin 目錄安裝器。這表示資訊清單驗證、危險程式碼掃描、套件管理器安裝工作與安裝記錄的行為會像 npm 安裝一樣。已記錄的 git 安裝會包含來源 URL/ref 以及已解析的 commit，讓 `openclaw plugins update` 之後可以重新解析來源。
|
||||
|
||||
從 git 安裝後，請使用 `openclaw plugins inspect <id> --runtime --json` 驗證執行階段註冊，例如 gateway 方法和 CLI 命令。如果 Plugin 透過 `api.registerCli` 註冊了 CLI 根命令，請直接透過 OpenClaw 根 CLI 執行該命令，例如 `openclaw demo-plugin ping`。
|
||||
從 git 安裝後，請使用 `openclaw plugins inspect <id> --runtime --json` 驗證執行階段註冊，例如 gateway 方法與 CLI 命令。如果 Plugin 使用 `api.registerCli` 註冊了 CLI 根命令，請透過 OpenClaw 根 CLI 直接執行該命令，例如 `openclaw demo-plugin ping`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="封存檔">
|
||||
支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解開後的 Plugin 根目錄包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。
|
||||
<Accordion title="Archives">
|
||||
支援的封存檔：`.zip`、`.tgz`、`.tar.gz`、`.tar`。原生 OpenClaw Plugin 封存檔必須在解壓後的 Plugin 根目錄包含有效的 `openclaw.plugin.json`；只包含 `package.json` 的封存檔會在 OpenClaw 寫入安裝記錄前被拒絕。
|
||||
|
||||
也支援 Claude marketplace 安裝。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
ClawHub 安裝使用明確的 `clawhub:<package>` locator：
|
||||
ClawHub 安裝會使用明確的 `clawhub:<package>` 定位器：
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
在啟動切換期間，裸 npm 安全 Plugin spec 預設會從 npm 安裝：
|
||||
在啟動切換期間，裸 npm 安全 Plugin 規格預設會從 npm 安裝：
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
@ -172,12 +172,12 @@ openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw 會在安裝前檢查宣告的 Plugin API / 最低 gateway 相容性。當所選 ClawHub 版本發布 ClawPack 成品時，OpenClaw 會下載版本化的 npm-pack `.tgz`，驗證 ClawHub digest header 和成品 digest，然後透過一般封存檔路徑安裝。沒有 ClawPack 中繼資料的舊版 ClawHub 版本，仍會透過舊版套件封存檔驗證路徑安裝。記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm integrity、npm shasum、tarball 名稱，以及 ClawPack digest 事實，以供日後更新使用。
|
||||
未指定版本的 ClawHub 安裝會保留未指定版本的記錄 spec，因此 `openclaw plugins update` 可以跟隨較新的 ClawHub 發布；明確版本或標籤選擇器，例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`，則會維持釘選到該選擇器。
|
||||
OpenClaw 會在安裝前檢查公告的 Plugin API / 最低 gateway 相容性。當選取的 ClawHub 版本發布 ClawPack 成品時，OpenClaw 會下載版本化 npm-pack `.tgz`，驗證 ClawHub digest 標頭與成品 digest，然後透過一般封存路徑安裝。沒有 ClawPack 中繼資料的較舊 ClawHub 版本仍會透過舊版套件封存驗證路徑安裝。已記錄的安裝會保留其 ClawHub 來源中繼資料、成品種類、npm integrity、npm shasum、tarball 名稱，以及 ClawPack digest 事實，以供之後更新。
|
||||
未指定版本的 ClawHub 安裝會保留未指定版本的記錄規格，讓 `openclaw plugins update` 可以跟隨較新的 ClawHub 發行；明確版本或標籤選擇器（例如 `clawhub:pkg@1.2.3` 和 `clawhub:pkg@beta`）則會保持釘選到該選擇器。
|
||||
|
||||
#### Marketplace 簡寫
|
||||
|
||||
當 marketplace 名稱存在於 Claude 位於 `~/.claude/plugins/known_marketplaces.json` 的本機 registry 快取中時，請使用 `plugin@marketplace` 簡寫：
|
||||
當 marketplace 名稱存在於 Claude 位於 `~/.claude/plugins/known_marketplaces.json` 的本機登錄快取中時，請使用 `plugin@marketplace` 簡寫：
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
@ -195,27 +195,27 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Marketplace sources">
|
||||
- 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 Marketplace 名稱
|
||||
- 本機 Marketplace 根目錄或 `marketplace.json` 路徑
|
||||
- 來自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名稱
|
||||
- 本機 marketplace 根目錄或 `marketplace.json` 路徑
|
||||
- GitHub repo 簡寫，例如 `owner/repo`
|
||||
- GitHub repo URL，例如 `https://github.com/owner/repo`
|
||||
- git URL
|
||||
|
||||
</Tab>
|
||||
<Tab title="Remote marketplace rules">
|
||||
對於從 GitHub 或 git 載入的遠端 Marketplace，Plugin 項目必須保留在複製下來的 Marketplace repo 內。OpenClaw 接受來自該 repo 的相對路徑來源，並拒絕遠端 manifest 中的 HTTP(S)、絕對路徑、git、GitHub，以及其他非路徑 Plugin 來源。
|
||||
對於從 GitHub 或 git 載入的遠端 marketplace，Plugin 項目必須保留在複製下來的 marketplace repo 內。OpenClaw 會接受來自該 repo 的相對路徑來源，並拒絕遠端 manifest 中的 HTTP(S)、絕對路徑、git、GitHub，以及其他非路徑 Plugin 來源。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
對於本機路徑與封存檔，OpenClaw 會自動偵測：
|
||||
|
||||
- 原生 OpenClaw Plugin（`openclaw.plugin.json`）
|
||||
- Codex 相容 bundle（`.codex-plugin/plugin.json`）
|
||||
- Claude 相容 bundle（`.claude-plugin/plugin.json` 或預設 Claude 元件版面配置）
|
||||
- Cursor 相容 bundle（`.cursor-plugin/plugin.json`）
|
||||
- 原生 OpenClaw plugins（`openclaw.plugin.json`）
|
||||
- Codex 相容套件組合（`.codex-plugin/plugin.json`）
|
||||
- Claude 相容套件組合（`.claude-plugin/plugin.json` 或預設 Claude 元件版面配置）
|
||||
- Cursor 相容套件組合（`.cursor-plugin/plugin.json`）
|
||||
|
||||
<Note>
|
||||
相容 bundle 會安裝到一般 Plugin 根目錄，並參與相同的 list/info/enable/disable 流程。目前支援 bundle skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` / manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的 bundle 能力會顯示在診斷/info 中，但尚未接入執行階段執行。
|
||||
相容套件組合會安裝到一般 Plugin 根目錄，並參與相同的列出/資訊/啟用/停用流程。目前支援套件組合 Skills、Claude command-skills、Claude `settings.json` 預設值、Claude `.lsp.json` / manifest 宣告的 `lspServers` 預設值、Cursor command-skills，以及相容的 Codex hook 目錄；其他偵測到的套件組合功能會顯示在診斷/資訊中，但尚未接入 runtime 執行。
|
||||
</Note>
|
||||
|
||||
### 列出
|
||||
@ -231,41 +231,41 @@ openclaw plugins search <query> --json
|
||||
```
|
||||
|
||||
<ParamField path="--enabled" type="boolean">
|
||||
只顯示已啟用的 Plugin。
|
||||
只顯示已啟用的 plugins。
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
從表格檢視切換為每個 Plugin 的詳細列，包含來源/起源/版本/啟用中繼資料。
|
||||
從表格檢視切換為每個 Plugin 的詳細行，包含來源/起源/版本/啟用中繼資料。
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
機器可讀的清單，加上 registry 診斷與套件相依安裝狀態。
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` 會先讀取持久化的本機 Plugin registry；當 registry 遺失或無效時，會退回使用僅由 manifest 衍生的備援。它適合用來檢查 Plugin 是否已安裝、已啟用，且對冷啟動規劃可見，但它不是對已執行 Gateway 程序的即時執行階段探測。變更 Plugin 程式碼、啟用狀態、hook 政策或 `plugins.load.paths` 後，請重新啟動服務該通道的 Gateway，再期待新的 `register(api)` 程式碼或 hook 執行。對於遠端/容器部署，請確認你重新啟動的是實際的 `openclaw gateway run` 子程序，而不只是包裝程序。
|
||||
`plugins list` 會先讀取持久化的本機 Plugin registry；當 registry 缺失或無效時，會使用僅由 manifest 推導出的 fallback。它可用來檢查某個 Plugin 是否已安裝、已啟用，並且對冷啟動規劃可見，但它不是對已在執行中的 Gateway 程序進行即時 runtime 探測。變更 Plugin 程式碼、啟用狀態、hook 政策或 `plugins.load.paths` 之後，請重新啟動服務該通道的 Gateway，再期待新的 `register(api)` 程式碼或 hooks 執行。對於遠端/容器部署，請確認你重新啟動的是實際的 `openclaw gateway run` 子程序，而不只是包裝程序。
|
||||
|
||||
`plugins list --json` 會包含每個 Plugin 來自 `package.json`
|
||||
`dependencies` 和 `optionalDependencies` 的 `dependencyStatus`。OpenClaw 會檢查這些套件
|
||||
名稱是否存在於 Plugin 一般 Node `node_modules` 查找路徑中；它
|
||||
不會匯入 Plugin 執行階段程式碼、執行套件管理器，或修復遺失的
|
||||
相依項。
|
||||
名稱是否存在於該 Plugin 一般 Node `node_modules` 查找路徑上；它
|
||||
不會匯入 Plugin runtime 程式碼、執行套件管理器，或修復缺失的
|
||||
相依套件。
|
||||
</Note>
|
||||
|
||||
`plugins search` 是遠端 ClawHub 目錄查找。它不會檢查本機
|
||||
狀態、變更設定、安裝套件，或載入 Plugin 執行階段程式碼。搜尋
|
||||
結果包含 ClawHub 套件名稱、系列、通道、版本、摘要，以及
|
||||
`plugins search` 是遠端 ClawHub 目錄查詢。它不會檢查本機
|
||||
狀態、變更 config、安裝套件，或載入 Plugin runtime 程式碼。搜尋
|
||||
結果包含 ClawHub 套件名稱、family、channel、版本、摘要，以及
|
||||
安裝提示，例如 `openclaw plugins install clawhub:<package>`。
|
||||
|
||||
若要在封裝好的 Docker 映像檔中處理隨附 Plugin，請將 Plugin
|
||||
原始碼目錄 bind-mount 到相符的封裝原始碼路徑上，例如
|
||||
`/app/extensions/synology-chat`。OpenClaw 會先於 `/app/dist/extensions/synology-chat` 探索該掛載的原始碼
|
||||
覆蓋層；單純複製的原始碼
|
||||
目錄仍不會生效，因此一般封裝安裝仍會使用編譯後的 dist。
|
||||
若要在封裝的 Docker 映像中處理內建 Plugin，請將 Plugin
|
||||
來源目錄 bind-mount 到相符的封裝來源路徑上，例如
|
||||
`/app/extensions/synology-chat`。OpenClaw 會先於
|
||||
`/app/dist/extensions/synology-chat` 發現該掛載的來源
|
||||
覆寫；單純複製的來源目錄會保持無作用，因此一般封裝安裝仍會使用已編譯的 dist。
|
||||
|
||||
針對執行階段 hook 偵錯：
|
||||
若要偵錯 runtime hook：
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` 會顯示來自模組載入檢查流程的已註冊 hook 與診斷。執行階段檢查永遠不會安裝相依項；請使用 `openclaw doctor --fix` 清理舊版相依狀態，或安裝遺失的已設定可下載 Plugin。
|
||||
- `openclaw gateway status --deep --require-rpc` 會確認可連線的 Gateway、服務/程序提示、設定路徑，以及 RPC 健康狀態。
|
||||
- 非隨附的對話 hook（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
- `openclaw plugins inspect <id> --runtime --json` 會顯示來自模組載入檢查流程的已註冊 hooks 與診斷。Runtime 檢查永遠不會安裝相依套件；請使用 `openclaw doctor --fix` 清理舊版相依狀態，或安裝缺失且已設定的可下載 plugins。
|
||||
- `openclaw gateway status --deep --require-rpc` 會確認可連線的 Gateway、服務/程序提示、config 路徑，以及 RPC 健康狀態。
|
||||
- 非內建的對話 hooks（`llm_input`、`llm_output`、`before_agent_finalize`、`agent_end`）需要 `plugins.entries.<id>.hooks.allowConversationAccess=true`。
|
||||
|
||||
使用 `--link` 可避免複製本機目錄（會加入 `plugins.load.paths`）：
|
||||
|
||||
@ -274,16 +274,16 @@ openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` 不支援搭配 `--link`，因為連結式安裝會重用來源路徑，而不是覆寫受管理的安裝目標。
|
||||
`--force` 不支援與 `--link` 搭配使用，因為連結式安裝會重用來源路徑，而不是覆寫受管理的安裝目標。
|
||||
|
||||
在 npm 安裝上使用 `--pin`，可將解析出的精確規格（`name@version`）儲存在受管理的 Plugin 索引中，同時保留預設的未釘選行為。
|
||||
在 npm 安裝上使用 `--pin`，可將解析出的精確 spec（`name@version`）儲存在受管理的 Plugin 索引中，同時保留預設的未釘選行為。
|
||||
</Note>
|
||||
|
||||
### Plugin 索引
|
||||
|
||||
Plugin 安裝中繼資料是機器管理的狀態，不是使用者設定。安裝與更新會將它寫入作用中 OpenClaw 狀態目錄下的 `plugins/installs.json`。其頂層 `installRecords` 映射是安裝中繼資料的持久來源，包含損壞或遺失 Plugin manifest 的記錄。`plugins` 陣列是由 manifest 衍生的冷 registry 快取。該檔案包含請勿編輯警告，並由 `openclaw plugins update`、解除安裝、診斷，以及冷 Plugin registry 使用。
|
||||
Plugin 安裝中繼資料是由機器管理的狀態，不是使用者 config。安裝與更新會將它寫入作用中 OpenClaw 狀態目錄底下的 `plugins/installs.json`。其頂層 `installRecords` map 是安裝中繼資料的持久來源，其中包含毀損或缺失 Plugin manifest 的記錄。`plugins` 陣列是由 manifest 推導出的冷 registry 快取。該檔案包含請勿編輯警告，並由 `openclaw plugins update`、解除安裝、診斷，以及冷 Plugin registry 使用。
|
||||
|
||||
當 OpenClaw 在設定中看到已發布的舊版 `plugins.installs` 記錄時，會將它們移入 Plugin 索引並移除設定鍵；如果任一寫入失敗，設定記錄會保留，以免安裝中繼資料遺失。
|
||||
當 OpenClaw 在 config 中看到已出貨的舊版 `plugins.installs` 記錄時，會將它們移到 Plugin 索引並移除該 config key；如果任一寫入失敗，config 記錄會被保留，確保安裝中繼資料不會遺失。
|
||||
|
||||
### 解除安裝
|
||||
|
||||
@ -293,7 +293,7 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` 會從 `plugins.entries`、持久化的 Plugin 索引、Plugin allow/deny 清單項目，以及適用時的連結式 `plugins.load.paths` 項目移除 Plugin 記錄。除非設定 `--keep-files`，否則解除安裝也會移除已追蹤的受管理安裝目錄，前提是該目錄位於 OpenClaw 的 Plugin 擴充根目錄內。對於 Active Memory Plugin，記憶體插槽會重設為 `memory-core`。
|
||||
`uninstall` 會從 `plugins.entries`、持久化 Plugin 索引、Plugin 允許/拒絕清單項目，以及適用時已連結的 `plugins.load.paths` 項目中移除 Plugin 記錄。除非設定 `--keep-files`，解除安裝也會在追蹤的受管理安裝目錄位於 OpenClaw 的 Plugin extensions 根目錄內時移除該目錄。對於 Active Memory plugins，memory slot 會重設為 `memory-core`。
|
||||
|
||||
<Note>
|
||||
`--keep-config` 支援作為 `--keep-files` 的已棄用別名。
|
||||
@ -313,25 +313,25 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
當你傳入 Plugin id 時，OpenClaw 會重用該 Plugin 記錄的安裝規格。這表示先前儲存的 dist-tag（例如 `@beta`）與精確釘選版本，會在後續 `update <id>` 執行中繼續使用。
|
||||
當你傳入 Plugin id 時，OpenClaw 會重用該 Plugin 記錄的安裝 spec。這表示先前儲存的 dist-tags（例如 `@beta`）與精確釘選版本，會在之後的 `update <id>` 執行中繼續使用。
|
||||
|
||||
對於 npm 安裝，你也可以傳入包含 dist-tag 或精確版本的明確 npm 套件規格。OpenClaw 會將該套件名稱解析回已追蹤的 Plugin 記錄，更新該已安裝 Plugin，並記錄新的 npm 規格供未來依 id 更新時使用。
|
||||
對於 npm 安裝，你也可以傳入含有 dist-tag 或精確版本的明確 npm 套件 spec。OpenClaw 會將該套件名稱解析回已追蹤的 Plugin 記錄、更新該已安裝 Plugin，並記錄新的 npm spec，供未來以 id 為基礎的更新使用。
|
||||
|
||||
傳入不含版本或標籤的 npm 套件名稱，也會解析回已追蹤的 Plugin 記錄。當某個 Plugin 已釘選到精確版本，而你想將它移回 registry 的預設發布線時，請使用此方式。
|
||||
傳入不含版本或 tag 的 npm 套件名稱，也會解析回已追蹤的 Plugin 記錄。當某個 Plugin 先前已釘選到精確版本，而你想將它移回 registry 的預設發行線時，請使用這個方式。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Beta channel updates">
|
||||
`openclaw plugins update` 會重用已追蹤的 Plugin 規格，除非你傳入新的規格。`openclaw update` 另外知道作用中的 OpenClaw 更新通道：在 beta 通道上，預設線 npm 與 ClawHub Plugin 記錄會先嘗試 `@beta`，若沒有 Plugin beta 發布版本，則退回記錄的預設/latest 規格。精確版本與明確標籤會維持釘選在該選擇器上。
|
||||
`openclaw plugins update` 會重用已追蹤的 Plugin spec，除非你傳入新的 spec。`openclaw update` 另外知道作用中的 OpenClaw 更新 channel：在 beta channel 上，預設線 npm 與 ClawHub Plugin 記錄會先嘗試 `@beta`，如果沒有 Plugin beta 發行版，才 fallback 到記錄的預設/latest spec。精確版本與明確 tags 會持續釘選到該 selector。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
在即時 npm 更新前，OpenClaw 會根據 npm registry 中繼資料檢查已安裝套件版本。如果已安裝版本與記錄的成品身分已經符合解析出的目標，更新會略過，不會下載、重新安裝或重寫 `openclaw.json`。
|
||||
在即時 npm 更新之前，OpenClaw 會根據 npm registry 中繼資料檢查已安裝套件版本。如果已安裝版本與記錄的成品身分已符合解析出的目標，更新會被略過，不會下載、重新安裝或重寫 `openclaw.json`。
|
||||
|
||||
當已儲存完整性雜湊且擷取到的成品雜湊改變時，OpenClaw 會將其視為 npm 成品漂移。互動式 `openclaw plugins update` 命令會列印預期與實際雜湊，並在繼續前要求確認。非互動式更新輔助工具會採取失敗關閉，除非呼叫者提供明確的繼續政策。
|
||||
當已儲存 integrity hash，且抓取到的成品 hash 發生變化時，OpenClaw 會將其視為 npm 成品漂移。互動式 `openclaw plugins update` 命令會列印預期與實際 hash，並在繼續前要求確認。非互動式更新輔助程式會 fail closed，除非呼叫端提供明確的繼續政策。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` 也可用於 `plugins update`，作為 Plugin 更新期間內建危險程式碼掃描誤判的緊急覆寫。它仍不會繞過 Plugin `before_install` 政策封鎖或掃描失敗封鎖，且只適用於 Plugin 更新，不適用於 hook-pack 更新。
|
||||
`--dangerously-force-unsafe-install` 也可在 `plugins update` 上使用，作為 Plugin 更新期間內建 dangerous-code 掃描誤判的 break-glass 覆寫。它仍不會繞過 Plugin `before_install` 政策封鎖或掃描失敗封鎖，而且只適用於 Plugin 更新，不適用於 hook-pack 更新。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -343,21 +343,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
檢查會顯示身分、載入狀態、來源、manifest 能力、政策旗標、診斷、安裝中繼資料、bundle 能力，以及任何偵測到的 MCP 或 LSP server 支援，預設不會匯入 Plugin 執行階段。加入 `--runtime` 可載入 Plugin 模組，並包含已註冊的 hook、工具、命令、服務、Gateway 方法與 HTTP 路由。執行階段檢查會直接回報遺失的 Plugin 相依項；安裝與修復仍位於 `openclaw plugins install`、`openclaw plugins update` 和 `openclaw doctor --fix`。
|
||||
Inspect 預設不會匯入 Plugin runtime，會顯示身分、載入狀態、來源、manifest 功能、政策旗標、診斷、安裝中繼資料、套件組合功能，以及任何偵測到的 MCP 或 LSP server 支援。加入 `--runtime` 可載入 Plugin 模組，並包含已註冊 hooks、tools、commands、services、gateway methods，以及 HTTP routes。Runtime 檢查會直接回報缺失的 Plugin 相依套件；安裝與修復仍留在 `openclaw plugins install`、`openclaw plugins update`，以及 `openclaw doctor --fix` 中進行。
|
||||
|
||||
Plugin 擁有的 CLI 命令會安裝為根層級 `openclaw` 命令群組。當 `inspect --runtime` 在 `cliCommands` 下顯示命令後，請以 `openclaw <command> ...` 執行它；例如，註冊 `demo-git` 的 Plugin 可用 `openclaw demo-git ping` 驗證。
|
||||
Plugin 擁有的 CLI commands 會安裝為根層級 `openclaw` command groups。當 `inspect --runtime` 在 `cliCommands` 下顯示某個 command 後，請以 `openclaw <command> ...` 執行它；例如，註冊 `demo-git` 的 Plugin 可用 `openclaw demo-git ping` 驗證。
|
||||
|
||||
每個 Plugin 都會依其在執行階段實際註冊的內容分類：
|
||||
每個 Plugin 會依照它在 runtime 實際註冊的內容分類：
|
||||
|
||||
- **plain-capability** — 一種能力類型（例如僅提供者 Plugin）
|
||||
- **hybrid-capability** — 多種能力類型（例如文字 + 語音 + 圖像）
|
||||
- **hook-only** — 只有 hook，沒有能力或介面
|
||||
- **non-capability** — 有工具/命令/服務，但沒有能力
|
||||
- **plain-capability** — 一種 capability 類型（例如僅 provider 的 Plugin）
|
||||
- **hybrid-capability** — 多種 capability 類型（例如文字 + 語音 + 圖像）
|
||||
- **hook-only** — 只有 hooks，沒有 capabilities 或 surfaces
|
||||
- **non-capability** — tools/commands/services，但沒有 capabilities
|
||||
|
||||
請參閱 [Plugin 形態](/zh-TW/plugins/architecture#plugin-shapes)，了解更多能力模型資訊。
|
||||
如需 capability model 的更多資訊，請參閱 [Plugin shapes](/zh-TW/plugins/architecture#plugin-shapes)。
|
||||
|
||||
<Note>
|
||||
`--json` 旗標會輸出適合腳本與稽核的機器可讀報告。`inspect --all` 會呈現全體表格，包含形態、能力種類、相容性通知、bundle 能力，以及 hook 摘要欄位。`info` 是 `inspect` 的別名。
|
||||
`--json` 旗標會輸出適合 scripting 與 auditing 的機器可讀報告。`inspect --all` 會呈現全體範圍的表格，包含 shape、capability kinds、compatibility notices、bundle capabilities，以及 hook summary 欄位。`info` 是 `inspect` 的別名。
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -366,11 +366,11 @@ Plugin 擁有的 CLI 命令會安裝為根層級 `openclaw` 命令群組。當 `
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` 會回報 Plugin 載入錯誤、manifest/探索診斷，以及相容性通知。當一切正常時，它會列印 `No plugin issues detected.`
|
||||
`doctor` 會回報 Plugin 載入錯誤、manifest/discovery 診斷，以及相容性 notices。當一切正常時，它會印出 `No plugin issues detected.`
|
||||
|
||||
如果已設定的 Plugin 存在於磁碟上，但被 loader 的路徑安全檢查封鎖，設定驗證會保留該 Plugin 項目，並將其回報為 `present but blocked`。請修復前面的已封鎖 Plugin 診斷，例如路徑擁有權或 world-writable 權限，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` 設定。
|
||||
如果已設定的 Plugin 存在於磁碟上，但被 loader 的路徑安全檢查封鎖，config 驗證會保留該 Plugin 項目，並將它回報為 `present but blocked`。請修正前面的 blocked-plugin 診斷，例如路徑 ownership 或 world-writable permissions，而不是移除 `plugins.entries.<id>` 或 `plugins.allow` config。
|
||||
|
||||
對於缺少 `register`/`activate` 匯出等模組形態失敗，請使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在診斷輸出中包含精簡的匯出形態摘要。
|
||||
對於缺少 `register`/`activate` exports 這類 module-shape 失敗，請使用 `OPENCLAW_PLUGIN_LOAD_DEBUG=1` 重新執行，以在診斷輸出中包含精簡的 export-shape 摘要。
|
||||
|
||||
### Registry
|
||||
|
||||
@ -380,12 +380,14 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
本機 Plugin registry 是 OpenClaw 對已安裝 Plugin 身分、啟用狀態、來源中繼資料與貢獻擁有權的持久化冷讀模型。一般啟動、提供者擁有者查找、通道設定分類，以及 Plugin 清單，都可以讀取它，而不需匯入 Plugin 執行階段模組。
|
||||
本機 Plugin registry 是 OpenClaw 為已安裝 Plugin 身分、啟用狀態、來源中繼資料，以及貢獻 ownership 所持久化的冷讀取模型。一般啟動、provider owner 查找、channel setup 分類，以及 Plugin 清單都可以在不匯入 Plugin runtime 模組的情況下讀取它。
|
||||
|
||||
使用 `plugins registry` 檢查持久化註冊表是否存在、最新或過期。使用 `--refresh` 從持久化 Plugin 索引、設定政策，以及 manifest/package 中繼資料重建它。這是修復路徑，不是執行階段啟用路徑。
|
||||
使用 `plugins registry` 檢查持久化 registry 是否存在、為最新或已過期。使用 `--refresh` 從持久化 Plugin 索引、設定政策，以及資訊清單/套件中繼資料重建它。這是修復路徑，不是執行階段啟用路徑。
|
||||
|
||||
`openclaw doctor --fix` 也會修復與 registry 相鄰的受管理 npm 漂移：如果受管理 Plugin npm 根目錄下有孤立或復原的 `@openclaw/*` 套件遮蔽了隨附 Plugin，doctor 會移除該過期套件並重建 registry，讓啟動流程能依據隨附資訊清單進行驗證。
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已棄用的應急相容性開關，用於註冊表讀取失敗。請優先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；env 後援僅供遷移推出期間的緊急啟動復原使用。
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` 是已棄用的緊急相容性開關，用於 registry 讀取失敗。請優先使用 `plugins registry --refresh` 或 `openclaw doctor --fix`；此 env 後援僅供遷移推出期間的緊急啟動復原使用。
|
||||
</Warning>
|
||||
|
||||
### 市集
|
||||
@ -395,7 +397,7 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
市集清單接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。`--json` 會列印解析後的來源標籤，以及剖析後的市集 manifest 和 Plugin 項目。
|
||||
市集清單接受本機市集路徑、`marketplace.json` 路徑、像 `owner/repo` 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。`--json` 會印出解析後的來源標籤，以及剖析後的市集資訊清單與 Plugin 項目。
|
||||
|
||||
## 相關
|
||||
|
||||
|
||||
@ -3,13 +3,13 @@ read_when:
|
||||
- 新增或修改 doctor 遷移
|
||||
- 引入破壞性設定變更
|
||||
sidebarTitle: Doctor
|
||||
summary: Doctor 指令：健康檢查、設定遷移與修復步驟
|
||||
summary: Doctor 命令：健康檢查、設定遷移與修復步驟
|
||||
title: 診斷工具
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:33:06Z"
|
||||
generated_at: "2026-05-04T09:36:55Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 20b2cb3c3cd88e01050cb285a08a020603642439bd35668b7414360801fc03ff
|
||||
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
不提示而接受預設值（包含適用時的重啟/服務/sandbox 修復步驟）。
|
||||
不提示就接受預設值（包含適用時的重新啟動/服務/沙盒修復步驟）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
不提示而套用建議修復（安全時包含修復與重啟）。
|
||||
不提示就套用建議的修復（安全時包含修復與重新啟動）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
也套用積極修復（會覆寫自訂 supervisor 設定）。
|
||||
也套用更積極的修復（會覆寫自訂 supervisor 設定）。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
不顯示提示並且只套用安全遷移（設定正規化與磁碟上的狀態搬移）。略過需要人工確認的重啟/服務/sandbox 動作。偵測到舊版狀態遷移時會自動執行。
|
||||
在不提示的情況下執行，且只套用安全遷移（設定正規化 + 磁碟狀態搬移）。略過需要人工確認的重新啟動/服務/沙盒動作。偵測到舊版狀態遷移時會自動執行。
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,12 +62,12 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
掃描系統服務以尋找額外的 gateway 安裝（launchd/systemd/schtasks）。
|
||||
掃描系統服務以找出額外的 gateway 安裝（launchd/systemd/schtasks）。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
如果你想在寫入前檢閱變更，請先開啟設定檔：
|
||||
如果你想在寫入前檢視變更，請先開啟設定檔：
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
@ -77,123 +77,123 @@ cat ~/.openclaw/openclaw.json
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="健康狀態、UI 與更新">
|
||||
- git 安裝可選的預先更新（僅互動模式）。
|
||||
- UI 協定新鮮度檢查（當協定 schema 較新時重建 Control UI）。
|
||||
- 健康檢查與重啟提示。
|
||||
- Skills 狀態摘要（符合資格/缺少/受阻）與 Plugin 狀態。
|
||||
- git 安裝的選用前置更新（僅限互動模式）。
|
||||
- UI 通訊協定新鮮度檢查（當通訊協定 schema 較新時重建 Control UI）。
|
||||
- 健康狀態檢查 + 重新啟動提示。
|
||||
- Skills 狀態摘要（符合資格/缺少/已封鎖）與 plugin 狀態。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="設定與遷移">
|
||||
- 舊版值的設定正規化。
|
||||
- 將舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.<provider>` 的 Talk 設定遷移。
|
||||
- 舊版 Chrome extension 設定與 Chrome MCP 就緒狀態的瀏覽器遷移檢查。
|
||||
- OpenCode provider override 警告（`models.providers.opencode` / `models.providers.opencode-go`）。
|
||||
- Codex OAuth shadowing 警告（`models.providers.openai-codex`）。
|
||||
- OpenAI Codex OAuth profiles 的 OAuth TLS 先決條件檢查。
|
||||
- 當 `plugins.allow` 具有限制但工具政策仍要求萬用字元或 Plugin 擁有的工具時，顯示 Plugin/tool allowlist 警告。
|
||||
- Talk 設定從舊版扁平 `talk.*` 欄位遷移到 `talk.provider` + `talk.providers.<provider>`。
|
||||
- 舊版 Chrome 擴充功能設定與 Chrome MCP 就緒狀態的瀏覽器遷移檢查。
|
||||
- OpenCode provider 覆寫警告（`models.providers.opencode` / `models.providers.opencode-go`）。
|
||||
- Codex OAuth 遮蔽警告（`models.providers.openai-codex`）。
|
||||
- OpenAI Codex OAuth 設定檔的 OAuth TLS 先決條件檢查。
|
||||
- 當 `plugins.allow` 具限制性，但工具政策仍要求萬用字元或 plugin 擁有的工具時，發出 Plugin/工具允許清單警告。
|
||||
- 舊版磁碟狀態遷移（sessions/agent dir/WhatsApp auth）。
|
||||
- 舊版 Plugin manifest contract key 遷移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。
|
||||
- 舊版 Cron store 遷移（`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs）。
|
||||
- 舊版 plugin manifest contract key 遷移（`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`）。
|
||||
- 舊版 cron store 遷移（`jobId`, `schedule.cron`, 頂層 delivery/payload 欄位、payload `provider`、簡單 `notify: true` webhook 後援 jobs）。
|
||||
- 舊版 agent runtime-policy 遷移到 `agents.defaults.agentRuntime` 與 `agents.list[].agentRuntime`。
|
||||
- 啟用 plugins 時清理過時的 Plugin 設定；當 `plugins.enabled=false` 時，過時的 Plugin 參照會被視為惰性 containment config 並保留。
|
||||
- 啟用 plugins 時清理過時 plugin 設定；當 `plugins.enabled=false` 時，過時 plugin 參照會被視為惰性的隔離設定並保留。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="狀態與完整性">
|
||||
- Session lock file 檢查與過時 lock 清理。
|
||||
- 修復受影響 2026.4.24 build 所建立之重複 prompt-rewrite 分支的 session transcript。
|
||||
- 偵測卡住的 subagent restart-recovery tombstone，並支援使用 `--fix` 清除過時的 aborted recovery flags，讓啟動時不會持續將 child 視為 restart-aborted。
|
||||
- 狀態完整性與權限檢查（sessions, transcripts, state dir）。
|
||||
- 修復受影響的 2026.4.24 建置建立的重複 prompt-rewrite 分支 session transcript。
|
||||
- 卡住的 subagent 重新啟動復原 tombstone 偵測，支援用 `--fix` 清除過時的 aborted recovery flags，讓啟動不會持續把 child 視為 restart-aborted。
|
||||
- 狀態完整性與權限檢查（sessions、transcripts、state dir）。
|
||||
- 本機執行時的設定檔權限檢查（chmod 600）。
|
||||
- Model auth 健康狀態：檢查 OAuth 過期、可重新整理即將過期的 token，並回報 auth-profile cooldown/disabled 狀態。
|
||||
- Model auth 健康狀態：檢查 OAuth 到期、可重新整理即將到期的 tokens，並回報 auth-profile cooldown/disabled 狀態。
|
||||
- 額外 workspace dir 偵測（`~/openclaw`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway、服務與 supervisor">
|
||||
- 啟用 sandboxing 時修復 sandbox image。
|
||||
<Accordion title="Gateway、服務與 supervisors">
|
||||
- 啟用 sandboxing 時的 sandbox image 修復。
|
||||
- 舊版服務遷移與額外 gateway 偵測。
|
||||
- Matrix channel 舊版狀態遷移（於 `--fix` / `--repair` 模式）。
|
||||
- Matrix channel 舊版狀態遷移（在 `--fix` / `--repair` 模式中）。
|
||||
- Gateway runtime 檢查（服務已安裝但未執行；快取的 launchd label）。
|
||||
- Channel 狀態警告（從執行中的 gateway 探測）。
|
||||
- Supervisor 設定稽核（launchd/systemd/schtasks）與選用修復。
|
||||
- 清理由 gateway 服務在安裝或更新期間捕捉到的 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值所造成的嵌入式 proxy 環境。
|
||||
- Gateway runtime 最佳實務檢查（Node vs Bun、version-manager paths）。
|
||||
- Gateway port collision 診斷（預設 `18789`）。
|
||||
- Supervisor 設定稽核（launchd/systemd/schtasks），並可選擇修復。
|
||||
- 清理 Gateway 服務的嵌入式 proxy 環境，這些服務在安裝或更新期間擷取了 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 值。
|
||||
- Gateway runtime 最佳實務檢查（Node vs Bun、version-manager 路徑）。
|
||||
- Gateway port 衝突診斷（預設 `18789`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Auth、安全性與配對">
|
||||
- 開放 DM policies 的安全性警告。
|
||||
- local token mode 的 Gateway auth 檢查（沒有 token source 時提供 token 產生；不會覆寫 token SecretRef configs）。
|
||||
- 裝置配對問題偵測（pending first-time pair requests、pending role/scope upgrades、stale local device-token cache drift，以及 paired-record auth drift）。
|
||||
<Accordion title="Auth、安全性與 pairing">
|
||||
- 開放 DM 政策的安全性警告。
|
||||
- 本機 token 模式的 Gateway auth 檢查（沒有 token source 時提供 token 產生；不會覆寫 token SecretRef 設定）。
|
||||
- 裝置 pairing 問題偵測（待處理的首次 pair 請求、待處理的 role/scope 升級、過時的本機 device-token cache drift，以及 paired-record auth drift）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Workspace 與 shell">
|
||||
- Linux 上的 systemd linger 檢查。
|
||||
- Workspace bootstrap file size 檢查（context files 的截斷/接近限制警告）。
|
||||
- 預設 agent 的 Skills 就緒狀態檢查；回報缺少 bins、env、config 或 OS requirements 的 allowed skills，且 `--fix` 可以停用 `skills.entries` 中無法使用的 skills。
|
||||
- Workspace bootstrap file 大小檢查（context files 的截斷/接近上限警告）。
|
||||
- 預設 agent 的 Skills 就緒狀態檢查；回報允許但缺少 bins、env、config 或 OS 需求的 skills，且 `--fix` 可在 `skills.entries` 中停用不可用的 skills。
|
||||
- Shell completion 狀態檢查與自動安裝/升級。
|
||||
- Memory search embedding provider 就緒狀態檢查（local model、remote API key 或 QMD binary）。
|
||||
- Source install 檢查（pnpm workspace mismatch、missing UI assets、missing tsx binary）。
|
||||
- 寫入更新後的設定與 wizard metadata。
|
||||
- Memory search embedding provider 就緒狀態檢查（本機 model、遠端 API key 或 QMD binary）。
|
||||
- Source install 檢查（pnpm workspace 不相符、缺少 UI assets、缺少 tsx binary）。
|
||||
- 寫入更新後的設定 + wizard metadata。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Dreams UI 回填與重設
|
||||
## Dreams UI backfill 與 reset
|
||||
|
||||
Control UI Dreams 場景包含 **Backfill**、**Reset** 與 **Clear Grounded** 動作，用於 grounded dreaming workflow。這些動作會使用 gateway doctor 風格的 RPC 方法，但它們**不是** `openclaw doctor` CLI 修復/遷移的一部分。
|
||||
Control UI Dreams 場景包含 grounded dreaming workflow 的 **Backfill**、**Reset** 與 **Clear Grounded** 動作。這些動作使用 gateway doctor-style RPC 方法，但它們**不是** `openclaw doctor` CLI 修復/遷移的一部分。
|
||||
|
||||
它們會做的事：
|
||||
|
||||
- **Backfill** 會掃描 active workspace 中歷史的 `memory/YYYY-MM-DD.md` 檔案，執行 grounded REM diary pass，並將可還原的 backfill entries 寫入 `DREAMS.md`。
|
||||
- **Reset** 只會從 `DREAMS.md` 移除那些有標記的 backfill diary entries。
|
||||
- **Clear Grounded** 只會移除由 historical replay 產生、且尚未累積 live recall 或 daily support 的 staged grounded-only short-term entries。
|
||||
- **Backfill** 會掃描 active workspace 中歷史的 `memory/YYYY-MM-DD.md` 檔案、執行 grounded REM diary pass，並將可逆的 backfill entries 寫入 `DREAMS.md`。
|
||||
- **Reset** 只會從 `DREAMS.md` 移除那些已標記的 backfill diary entries。
|
||||
- **Clear Grounded** 只會移除來自歷史 replay、且尚未累積 live recall 或 daily support 的 staged grounded-only short-term entries。
|
||||
|
||||
它們本身**不會**做的事：
|
||||
|
||||
- 它們不會編輯 `MEMORY.md`
|
||||
- 它們不會執行完整 doctor 遷移
|
||||
- 它們不會執行完整 doctor migrations
|
||||
- 除非你先明確執行 staged CLI path，否則它們不會自動將 grounded candidates stage 到 live short-term promotion store
|
||||
|
||||
如果你想讓 grounded historical replay 影響一般 deep promotion lane，請改用 CLI 流程：
|
||||
如果你想讓 grounded historical replay 影響一般的 deep promotion lane，請改用 CLI flow：
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
這會將 grounded durable candidates stage 到 short-term dreaming store，同時保留 `DREAMS.md` 作為 review surface。
|
||||
這會將 grounded durable candidates stage 到 short-term dreaming store，同時讓 `DREAMS.md` 保持作為 review surface。
|
||||
|
||||
## 詳細行為與原因
|
||||
## 詳細行為與理由
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. 選用更新（git 安裝）">
|
||||
如果這是 git checkout，且 doctor 以互動模式執行，它會在執行 doctor 前提供更新（fetch/rebase/build）。
|
||||
如果這是 git checkout 且 doctor 正以互動方式執行，它會在執行 doctor 前提供更新（fetch/rebase/build）。
|
||||
</Accordion>
|
||||
<Accordion title="1. 設定正規化">
|
||||
如果設定包含舊版值形狀（例如沒有 channel-specific override 的 `messages.ackReaction`），doctor 會將它們正規化為目前的 schema。
|
||||
|
||||
這包含舊版 Talk 扁平欄位。目前公開的 Talk 設定是 `talk.provider` + `talk.providers.<provider>`。Doctor 會將舊的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形狀改寫到 provider map。
|
||||
這包含舊版 Talk 扁平欄位。目前公開 Talk 設定是 `talk.provider` + `talk.providers.<provider>`。Doctor 會把舊的 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 形狀重寫到 provider map。
|
||||
|
||||
當 `plugins.allow` 非空且工具政策使用萬用字元或 Plugin 擁有的工具項目時，Doctor 也會警告。`tools.allow: ["*"]` 只會比對實際載入之 Plugin 的工具；它不會繞過專屬 Plugin allowlist。
|
||||
當 `plugins.allow` 非空且工具政策使用萬用字元或 plugin-owned tool entries 時，Doctor 也會警告。`tools.allow: ["*"]` 只會符合實際載入的 plugins 中的工具；它不會繞過專屬 plugin 允許清單。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. 舊版設定 key 遷移">
|
||||
當設定包含已棄用的 key 時，其他命令會拒絕執行並要求你執行 `openclaw doctor`。
|
||||
當設定包含已棄用的 keys 時，其他 commands 會拒絕執行，並要求你執行 `openclaw doctor`。
|
||||
|
||||
Doctor 會：
|
||||
|
||||
- 說明找到哪些舊版 key。
|
||||
- 說明找到哪些舊版 keys。
|
||||
- 顯示它套用的遷移。
|
||||
- 使用更新後的 schema 改寫 `~/.openclaw/openclaw.json`。
|
||||
- 使用更新後的 schema 重寫 `~/.openclaw/openclaw.json`。
|
||||
|
||||
Gateway 也會在啟動時偵測到舊版設定格式時自動執行 doctor 遷移，因此過時設定會在無需手動介入的情況下被修復。Cron job store 遷移由 `openclaw doctor --fix` 處理。
|
||||
Gateway 在啟動時偵測到舊版設定格式，也會自動執行 doctor migrations，因此過時設定不需人工介入就會被修復。Cron job store migrations 由 `openclaw doctor --fix` 處理。
|
||||
|
||||
目前的遷移：
|
||||
目前遷移：
|
||||
|
||||
- `routing.allowFrom` → `channels.whatsapp.allowFrom`
|
||||
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- 已設定頻道的設定缺少可見回覆政策 → `messages.groupChat.visibleReplies: "message_tool"`
|
||||
- 已設定的頻道設定缺少可見回覆政策 → `messages.groupChat.visibleReplies: "message_tool"`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → 頂層 `bindings`
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
@ -211,282 +211,282 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- 對於有具名 `accounts` 但仍殘留單一帳號頂層頻道值的頻道，將那些帳號範圍的值移入為該頻道升級選定的帳號（大多數頻道為 `accounts.default`；Matrix 可保留現有相符的具名/預設目標）
|
||||
- 對於具有具名 `accounts` 但仍殘留單一帳號頂層頻道值的頻道，將這些帳號範圍值移入為該頻道選定的已提升帳號（多數頻道為 `accounts.default`；Matrix 可以保留既有相符的具名/預設目標）
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*`（tools/elevated/exec/sandbox/subagents）
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- 移除 `agents.defaults.llm`；慢速提供者/模型逾時請使用 `models.providers.<id>.timeoutSeconds`
|
||||
- 移除 `agents.defaults.llm`；針對較慢的供應商/模型逾時，請使用 `models.providers.<id>.timeoutSeconds`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- 移除 `browser.relayBindHost`（舊版 extension relay 設定）
|
||||
- 舊版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 啟動時也會略過 `api` 設為未來或未知列舉值的提供者，而不是封閉式失敗）
|
||||
- 移除 `browser.relayBindHost`（舊版擴充功能轉送設定）
|
||||
- 舊版 `models.providers.*.api: "openai"` → `"openai-completions"`（Gateway 啟動時也會略過 `api` 設為未來或未知列舉值的供應商，而不是以關閉失敗）
|
||||
|
||||
Doctor 警告也包含多帳號頻道的帳號預設指引：
|
||||
Doctor 警告也包含多帳號頻道的帳號預設值指引：
|
||||
|
||||
- 如果設定了兩個以上 `channels.<channel>.accounts` 項目，但沒有 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 會警告備援路由可能選到非預期的帳號。
|
||||
- 如果 `channels.<channel>.defaultAccount` 設為未知帳號 ID，doctor 會發出警告並列出已設定的帳號 ID。
|
||||
- 如果設定了兩個或更多 `channels.<channel>.accounts` 項目，但未設定 `channels.<channel>.defaultAccount` 或 `accounts.default`，doctor 會警告後援路由可能選到非預期的帳號。
|
||||
- 如果 `channels.<channel>.defaultAccount` 設為未知的帳號 ID，doctor 會警告並列出已設定的帳號 ID。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. OpenCode 提供者覆寫">
|
||||
如果你手動加入了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它會覆寫來自 `@mariozechner/pi-ai` 的內建 OpenCode 型錄。這可能強制模型使用錯誤的 API，或將成本歸零。Doctor 會警告，讓你移除覆寫並還原逐模型 API 路由 + 成本。
|
||||
<Accordion title="2b. OpenCode 供應商覆寫">
|
||||
如果你手動新增了 `models.providers.opencode`、`opencode-zen` 或 `opencode-go`，它會覆寫來自 `@mariozechner/pi-ai` 的內建 OpenCode 目錄。這可能會強制模型使用錯誤的 API，或將成本歸零。Doctor 會警告，讓你可以移除覆寫並恢復每個模型的 API 路由與成本。
|
||||
</Accordion>
|
||||
<Accordion title="2c. 瀏覽器遷移與 Chrome MCP 就緒狀態">
|
||||
如果你的瀏覽器設定仍指向已移除的 Chrome extension 路徑，doctor 會將它正規化為目前主機本機的 Chrome MCP attach 模型：
|
||||
如果你的瀏覽器設定仍指向已移除的 Chrome 擴充功能路徑，doctor 會將其正規化為目前的主機本機 Chrome MCP 附加模型：
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` 變成 `"existing-session"`
|
||||
- `browser.profiles.*.driver: "extension"` 會變成 `"existing-session"`
|
||||
- `browser.relayBindHost` 會被移除
|
||||
|
||||
當你使用 `defaultProfile: "user"` 或已設定的 `existing-session` 設定檔時，Doctor 也會稽核主機本機 Chrome MCP 路徑：
|
||||
|
||||
- 檢查同一台主機上是否已安裝 Google Chrome，以供預設自動連線設定檔使用
|
||||
- 檢查偵測到的 Chrome 版本，並在低於 Chrome 144 時發出警告
|
||||
- 提醒你在瀏覽器檢查頁面啟用遠端偵錯（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
|
||||
- 檢查 Google Chrome 是否安裝在同一台主機上，以供預設自動連線設定檔使用
|
||||
- 檢查偵測到的 Chrome 版本，並在低於 Chrome 144 時警告
|
||||
- 提醒你在瀏覽器檢查頁面中啟用遠端偵錯（例如 `chrome://inspect/#remote-debugging`、`brave://inspect/#remote-debugging` 或 `edge://inspect/#remote-debugging`）
|
||||
|
||||
Doctor 無法代你啟用 Chrome 端設定。主機本機 Chrome MCP 仍需要：
|
||||
Doctor 無法替你啟用 Chrome 端設定。主機本機 Chrome MCP 仍需要：
|
||||
|
||||
- Gateway/Node 主機上有 Chromium-based 瀏覽器 144+
|
||||
- Gateway/Node 主機上的 Chromium 型瀏覽器 144+
|
||||
- 瀏覽器在本機執行
|
||||
- 該瀏覽器已啟用遠端偵錯
|
||||
- 在瀏覽器中核准第一次 attach 同意提示
|
||||
- 在瀏覽器中核准第一次附加同意提示
|
||||
|
||||
這裡的就緒狀態只關於本機 attach 前置條件。Existing-session 會保留目前的 Chrome MCP 路由限制；像 `responsebody`、PDF 匯出、下載攔截和批次動作等進階路由仍需要受管理的瀏覽器或原始 CDP 設定檔。
|
||||
這裡的就緒狀態只關於本機附加先決條件。Existing-session 會保留目前的 Chrome MCP 路由限制；像 `responsebody`、PDF 匯出、下載攔截和批次動作等進階路由仍需要受管理瀏覽器或原始 CDP 設定檔。
|
||||
|
||||
這項檢查**不**適用於 Docker、sandbox、remote-browser 或其他 headless 流程。那些流程會繼續使用原始 CDP。
|
||||
此檢查**不**適用於 Docker、sandbox、remote-browser 或其他 headless 流程。這些流程會繼續使用原始 CDP。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. OAuth TLS 前置條件">
|
||||
設定 OpenAI Codex OAuth 設定檔時，doctor 會探測 OpenAI 授權端點，以驗證本機 Node/OpenSSL TLS 堆疊是否能驗證憑證鏈。如果探測因憑證錯誤失敗（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、過期憑證或自簽憑證），doctor 會列印平台特定修復指引。在 macOS 搭配 Homebrew Node 時，修復方式通常是 `brew postinstall ca-certificates`。使用 `--deep` 時，即使 Gateway 健康，探測仍會執行。
|
||||
<Accordion title="2d. OAuth TLS 先決條件">
|
||||
設定 OpenAI Codex OAuth 設定檔時，doctor 會探測 OpenAI 授權端點，以驗證本機 Node/OpenSSL TLS 堆疊能否驗證憑證鏈。如果探測因憑證錯誤而失敗（例如 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、過期憑證或自簽憑證），doctor 會列印平台特定的修復指引。在使用 Homebrew Node 的 macOS 上，修復通常是 `brew postinstall ca-certificates`。使用 `--deep` 時，即使 Gateway 健康，探測也會執行。
|
||||
</Accordion>
|
||||
<Accordion title="2e. Codex OAuth 提供者覆寫">
|
||||
如果你先前在 `models.providers.openai-codex` 下加入舊版 OpenAI 傳輸設定，它們可能遮蔽新版發行版會自動使用的內建 Codex OAuth 提供者路徑。Doctor 在看到那些舊傳輸設定與 Codex OAuth 並存時會發出警告，讓你移除或改寫過時的傳輸覆寫，並取回內建路由/備援行為。自訂代理和僅標頭覆寫仍受支援，而且不會觸發此警告。
|
||||
<Accordion title="2e. Codex OAuth 供應商覆寫">
|
||||
如果你先前在 `models.providers.openai-codex` 下新增了舊版 OpenAI 傳輸設定，它們可能會遮蔽較新版本自動使用的內建 Codex OAuth 供應商路徑。Doctor 看到這些舊傳輸設定與 Codex OAuth 並存時會警告，讓你可以移除或改寫過時的傳輸覆寫，取回內建的路由/後援行為。自訂代理和僅標頭覆寫仍受支援，且不會觸發此警告。
|
||||
</Accordion>
|
||||
<Accordion title="2f. Codex Plugin 路由警告">
|
||||
啟用內建 Codex Plugin 時，doctor 也會檢查 `openai-codex/*` 主要模型參照是否仍透過預設 PI runner 解析。當你想透過 PI 使用 Codex OAuth/訂閱驗證時，這個組合是有效的，但它很容易與原生 Codex app-server harness 混淆。Doctor 會發出警告，並指向明確的 app-server 形狀：`openai/*` 加上 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
|
||||
啟用隨附的 Codex Plugin 時，doctor 也會檢查 `openai-codex/*` 主要模型參照是否仍透過預設 PI 執行器解析。當你想透過 PI 使用 Codex OAuth/訂閱驗證時，這個組合是有效的，但很容易與原生 Codex app-server harness 混淆。Doctor 會警告並指向明確的 app-server 形狀：`openai/*` 加上 `agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
|
||||
|
||||
Doctor 不會自動修復此項，因為兩條路由都有效：
|
||||
Doctor 不會自動修復此項，因為兩種路由都有效：
|
||||
|
||||
- `openai-codex/*` + PI 表示「透過一般 OpenClaw runner 使用 Codex OAuth/訂閱驗證。」
|
||||
- `openai/*` + `agentRuntime.id: "codex"` 表示「透過原生 Codex app-server 執行嵌入式 turn。」
|
||||
- `openai-codex/*` + PI 表示「透過一般 OpenClaw 執行器使用 Codex OAuth/訂閱驗證。」
|
||||
- `openai/*` + `agentRuntime.id: "codex"` 表示「透過原生 Codex app-server 執行嵌入式回合。」
|
||||
- `/codex ...` 表示「從聊天控制或綁定原生 Codex 對話。」
|
||||
- `/acp ...` 或 `runtime: "acp"` 表示「使用外部 ACP/acpx adapter。」
|
||||
- `/acp ...` 或 `runtime: "acp"` 表示「使用外部 ACP/acpx 轉接器。」
|
||||
|
||||
如果出現警告，請選擇你原本想要的路由並手動編輯設定。當 PI Codex OAuth 是有意設定時，請保持警告原樣。
|
||||
如果出現警告，請選擇你原本想要的路由並手動編輯設定。當 PI Codex OAuth 是刻意設定時，請保留警告不變。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. 舊版狀態遷移（磁碟配置）">
|
||||
Doctor 可將較舊的磁碟布局遷移到目前結構：
|
||||
<Accordion title="3. 舊版狀態遷移（磁碟布局）">
|
||||
Doctor 可以將較舊的磁碟布局遷移到目前結構：
|
||||
|
||||
- Sessions 儲存 + transcripts：
|
||||
- 工作階段儲存區 + 轉錄：
|
||||
- 從 `~/.openclaw/sessions/` 到 `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Agent 目錄：
|
||||
- 從 `~/.openclaw/agent/` 到 `~/.openclaw/agents/<agentId>/agent/`
|
||||
- WhatsApp 驗證狀態（Baileys）：
|
||||
- 從舊版 `~/.openclaw/credentials/*.json`（`oauth.json` 除外）
|
||||
- 從舊版 `~/.openclaw/credentials/*.json`（除了 `oauth.json`）
|
||||
- 到 `~/.openclaw/credentials/whatsapp/<accountId>/...`（預設帳號 ID：`default`）
|
||||
|
||||
這些遷移是盡力而為且冪等的；當 doctor 將任何舊資料夾留下作為備份時，會發出警告。Gateway/CLI 也會在啟動時自動遷移舊版 sessions + agent 目錄，讓歷史記錄/驗證/模型落在逐 agent 路徑中，不需要手動執行 doctor。WhatsApp 驗證刻意只透過 `openclaw doctor` 遷移。Talk 提供者/provider-map 正規化現在會依結構相等性比較，因此僅金鑰順序不同的差異不再觸發重複的無作用 `doctor --fix` 變更。
|
||||
這些遷移會盡力執行且具冪等性；當 doctor 留下任何舊版資料夾作為備份時，會發出警告。Gateway/CLI 在啟動時也會自動遷移舊版工作階段 + agent 目錄，讓歷史記錄/驗證/模型落在每個 agent 的路徑中，而不需要手動執行 doctor。WhatsApp 驗證刻意只透過 `openclaw doctor` 遷移。Talk 供應商/供應商對應正規化現在會以結構相等比較，因此只有鍵順序不同的差異不再觸發重複的無操作 `doctor --fix` 變更。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. 舊版 Plugin manifest 遷移">
|
||||
Doctor 會掃描所有已安裝 Plugin manifest，尋找已棄用的頂層 capability key（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到時，它會提供將它們移入 `contracts` 物件，並就地改寫 manifest 檔案。此遷移是冪等的；如果 `contracts` key 已有相同值，舊版 key 會被移除，而不會重複資料。
|
||||
Doctor 會掃描所有已安裝 Plugin manifest，尋找已棄用的頂層功能鍵（`speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders`、`webSearchProviders`）。找到時，它會提出將這些鍵移入 `contracts` 物件，並就地改寫 manifest 檔案。此遷移具冪等性；如果 `contracts` 鍵已經有相同值，舊版鍵會被移除而不重複資料。
|
||||
</Accordion>
|
||||
<Accordion title="3b. 舊版 Cron 儲存遷移">
|
||||
Doctor 也會檢查 cron job 儲存（預設為 `~/.openclaw/cron/jobs.json`，或覆寫時為 `cron.store`），尋找排程器仍為相容性接受的舊 job 形狀。
|
||||
<Accordion title="3b. 舊版 Cron 儲存區遷移">
|
||||
Doctor 也會檢查 Cron 工作儲存區（預設為 `~/.openclaw/cron/jobs.json`，或覆寫時的 `cron.store`），尋找排程器仍為相容性而接受的舊工作形狀。
|
||||
|
||||
目前 Cron 清理包含：
|
||||
目前的 Cron 清理包含：
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- 頂層 payload 欄位（`message`、`model`、`thinking`、...）→ `payload`
|
||||
- 頂層 delivery 欄位（`deliver`、`channel`、`to`、`provider`、...）→ `delivery`
|
||||
- payload `provider` delivery aliases → 明確的 `delivery.channel`
|
||||
- 簡單舊版 `notify: true` webhook 備援 jobs → 明確的 `delivery.mode="webhook"` 搭配 `delivery.to=cron.webhook`
|
||||
- payload `provider` delivery 別名 → 明確的 `delivery.channel`
|
||||
- 簡單舊版 `notify: true` Webhook 後援工作 → 明確的 `delivery.mode="webhook"` 搭配 `delivery.to=cron.webhook`
|
||||
|
||||
Doctor 只會在不改變行為的情況下自動遷移 `notify: true` jobs。如果某個 job 將舊版 notify 備援與現有非 webhook delivery mode 組合使用，doctor 會發出警告並將該 job 留待手動審查。
|
||||
Doctor 只會在不改變行為時自動遷移 `notify: true` 工作。如果某個工作結合了舊版通知後援與既有的非 Webhook delivery 模式，doctor 會警告並保留該工作供手動審查。
|
||||
|
||||
在 Linux 上，當使用者的 crontab 仍叫用舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時，doctor 也會發出警告。該主機本機 script 不再由目前的 OpenClaw 維護，而且當 cron 無法連到 systemd user bus 時，可能會將錯誤的 `Gateway inactive` 訊息寫入 `~/.openclaw/logs/whatsapp-health.log`。請使用 `crontab -e` 移除過時的 crontab 項目；目前的健康檢查請使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
|
||||
在 Linux 上，當使用者的 crontab 仍叫用舊版 `~/.openclaw/bin/ensure-whatsapp.sh` 時，doctor 也會警告。該主機本機腳本不由目前的 OpenClaw 維護，且當 cron 無法連到 systemd 使用者匯流排時，可能會將錯誤的 `Gateway inactive` 訊息寫入 `~/.openclaw/logs/whatsapp-health.log`。請使用 `crontab -e` 移除過時的 crontab 項目；目前的健康檢查請使用 `openclaw channels status --probe`、`openclaw doctor` 和 `openclaw gateway status`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. 工作階段鎖定清理">
|
||||
Doctor 會掃描每個代理程式工作階段目錄，尋找過時的寫入鎖定檔案，也就是工作階段異常結束時遺留下來的檔案。對於找到的每個鎖定檔案，它會回報：路徑、PID、PID 是否仍在執行、鎖定存在時間，以及是否被視為過時（PID 已死亡或超過 30 分鐘）。在 `--fix` / `--repair` 模式下，它會自動移除過時的鎖定檔案；否則會列印提示，並指示你使用 `--fix` 重新執行。
|
||||
doctor 會掃描每個代理程式工作階段目錄中的過時寫入鎖定檔，也就是工作階段異常結束後遺留下來的檔案。對於找到的每個鎖定檔，它會回報：路徑、PID、該 PID 是否仍在執行、鎖定存在時間，以及是否被視為過時（PID 已死或超過 30 分鐘）。在 `--fix` / `--repair` 模式中，它會自動移除過時的鎖定檔；否則會列印一則提示，指示你使用 `--fix` 重新執行。
|
||||
</Accordion>
|
||||
<Accordion title="3d. 工作階段逐字稿分支修復">
|
||||
Doctor 會掃描代理程式工作階段 JSONL 檔案，尋找由 2026.4.24 提示逐字稿重寫錯誤所建立的重複分支形狀：一個包含 OpenClaw 內部執行階段內容的已放棄使用者回合，以及一個包含相同可見使用者提示的作用中同層分支。在 `--fix` / `--repair` 模式下，doctor 會在原始檔案旁備份每個受影響的檔案，並將逐字稿重寫到作用中分支，讓 Gateway 歷史記錄和記憶讀取器不再看到重複回合。
|
||||
<Accordion title="3d. 工作階段轉錄分支修復">
|
||||
doctor 會掃描代理程式工作階段 JSONL 檔案，尋找由 2026.4.24 提示轉錄重寫錯誤所建立的重複分支形狀：一個被棄用的使用者回合包含 OpenClaw 內部執行階段內容，旁邊還有一個作用中的同層分支，含有相同的可見使用者提示。在 `--fix` / `--repair` 模式中，doctor 會在原始檔旁備份每個受影響的檔案，並將轉錄重寫為作用中的分支，使 gateway 歷程與記憶讀取器不再看到重複回合。
|
||||
</Accordion>
|
||||
<Accordion title="4. 狀態完整性檢查（工作階段持久化、路由與安全性）">
|
||||
狀態目錄是作業上的腦幹。如果它消失，你會失去工作階段、憑證、記錄和設定（除非你在其他地方有備份）。
|
||||
狀態目錄是作業上的腦幹。如果它消失，你會失去工作階段、憑證、日誌與設定（除非你在其他地方有備份）。
|
||||
|
||||
Doctor 會檢查：
|
||||
doctor 會檢查：
|
||||
|
||||
- **狀態目錄遺失**：警告災難性的狀態遺失，提示重新建立目錄，並提醒你它無法復原遺失的資料。
|
||||
- **狀態目錄權限**：驗證可寫入性；提供修復權限的選項（偵測到擁有者/群組不符時會發出 `chown` 提示）。
|
||||
- **macOS 雲端同步狀態目錄**：當狀態解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 底下時發出警告，因為同步支援的路徑可能造成較慢的 I/O 和鎖定/同步競爭。
|
||||
- **Linux SD 或 eMMC 狀態目錄**：當狀態解析到 `mmcblk*` 掛載來源時發出警告，因為由 SD 或 eMMC 支援的隨機 I/O 在工作階段和憑證寫入期間可能較慢且磨耗更快。
|
||||
- **工作階段目錄遺失**：`sessions/` 和工作階段儲存目錄是持久保存歷史記錄並避免 `ENOENT` 當機所必需的。
|
||||
- **逐字稿不符**：當近期工作階段項目缺少逐字稿檔案時發出警告。
|
||||
- **主要工作階段「1 行 JSONL」**：當主要逐字稿只有一行時標記（歷史記錄沒有累積）。
|
||||
- **多個狀態目錄**：當多個主目錄中存在多個 `~/.openclaw` 資料夾，或 `OPENCLAW_STATE_DIR` 指向其他位置時發出警告（歷史記錄可能在安裝之間分裂）。
|
||||
- **狀態目錄權限**：驗證可寫入性；提供修復權限的選項（偵測到擁有者/群組不相符時，會發出 `chown` 提示）。
|
||||
- **macOS 雲端同步的狀態目錄**：當狀態解析到 iCloud Drive（`~/Library/Mobile Documents/com~apple~CloudDocs/...`）或 `~/Library/CloudStorage/...` 底下時發出警告，因為同步支援的路徑可能導致較慢的 I/O 以及鎖定/同步競爭。
|
||||
- **Linux SD 或 eMMC 狀態目錄**：當狀態解析到 `mmcblk*` 掛載來源時發出警告，因為 SD 或 eMMC 支援的隨機 I/O 可能較慢，且在工作階段與憑證寫入下磨耗更快。
|
||||
- **工作階段目錄遺失**：需要 `sessions/` 與工作階段儲存目錄，才能持久保存歷程並避免 `ENOENT` 當機。
|
||||
- **轉錄不相符**：當近期工作階段項目缺少轉錄檔時發出警告。
|
||||
- **主要工作階段「1 行 JSONL」**：當主要轉錄只有一行時標記（表示歷程沒有累積）。
|
||||
- **多個狀態目錄**：當多個 home 目錄中存在多個 `~/.openclaw` 資料夾，或 `OPENCLAW_STATE_DIR` 指向其他位置時發出警告（歷程可能在不同安裝之間分裂）。
|
||||
- **遠端模式提醒**：如果 `gateway.mode=remote`，doctor 會提醒你在遠端主機上執行（狀態位於那裡）。
|
||||
- **設定檔權限**：如果 `~/.openclaw/openclaw.json` 可被群組/所有人讀取，則發出警告並提供收緊為 `600` 的選項。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. 模型驗證健康狀態（OAuth 到期）">
|
||||
Doctor 會檢查驗證儲存中的 OAuth 設定檔，在權杖即將到期/已到期時發出警告，並可在安全時重新整理它們。如果 Anthropic OAuth/權杖設定檔已過時，它會建議使用 Anthropic API 金鑰或 Anthropic 設定權杖路徑。重新整理提示只會在互動式執行（TTY）時出現；`--non-interactive` 會略過重新整理嘗試。
|
||||
doctor 會檢查驗證儲存區中的 OAuth profile，在 token 即將到期/已到期時發出警告，並可在安全時重新整理它們。如果 Anthropic OAuth/token profile 已過時，它會建議使用 Anthropic API key 或 Anthropic setup-token 路徑。重新整理提示只會在互動式執行（TTY）時出現；`--non-interactive` 會略過重新整理嘗試。
|
||||
|
||||
當 OAuth 重新整理永久失敗時（例如 `refresh_token_reused`、`invalid_grant`，或供應商要求你重新登入），doctor 會回報需要重新驗證，並列印要執行的精確 `openclaw models auth login --provider ...` 命令。
|
||||
當 OAuth 重新整理永久失敗時（例如 `refresh_token_reused`、`invalid_grant`，或提供者要求你重新登入），doctor 會回報需要重新驗證，並列印要執行的精確 `openclaw models auth login --provider ...` 指令。
|
||||
|
||||
Doctor 也會回報因以下原因而暫時無法使用的驗證設定檔：
|
||||
doctor 也會回報因下列原因而暫時無法使用的 auth profile：
|
||||
|
||||
- 短暫冷卻時間（速率限制/逾時/驗證失敗）
|
||||
- 較長停用時間（帳單/額度失敗）
|
||||
- 較長時間的停用（帳單/點數失敗）
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Hooks 模型驗證">
|
||||
如果設定了 `hooks.gmail.model`，doctor 會根據目錄和允許清單驗證模型參照，並在它無法解析或不被允許時發出警告。
|
||||
<Accordion title="6. hooks 模型驗證">
|
||||
如果已設定 `hooks.gmail.model`，doctor 會根據 catalog 與 allowlist 驗證模型參照，並在無法解析或不允許時發出警告。
|
||||
</Accordion>
|
||||
<Accordion title="7. 沙箱映像修復">
|
||||
啟用沙箱時，doctor 會檢查 Docker 映像，並在目前映像遺失時提供建置或切換到舊版名稱的選項。
|
||||
</Accordion>
|
||||
<Accordion title="7b. Plugin 安裝清理">
|
||||
Doctor 會在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式下移除舊版 OpenClaw 產生的 Plugin 依賴項暫存狀態。這涵蓋過時的已產生依賴項根目錄、舊的安裝階段目錄，以及先前內建 Plugin 依賴項修復程式碼留下的套件本機殘留物。
|
||||
doctor 會在 `openclaw doctor --fix` / `openclaw doctor --repair` 模式中移除舊版 OpenClaw 產生的 Plugin 依賴 staging 狀態。這涵蓋過時的已產生依賴根目錄、舊的 install-stage 目錄、早期 bundled-plugin 依賴修復程式碼留下的 package-local 雜物，以及可能遮蔽目前 bundled manifest 的孤立或已復原的託管 bundled `@openclaw/*` plugins npm 副本。
|
||||
|
||||
當設定參照可下載 Plugin 但本機 Plugin 登錄找不到它們時，doctor 也可以重新安裝已設定的可下載 Plugin。針對 2026.5.2 內建 Plugin 外部化，doctor 會自動安裝現有設定已使用的可下載 Plugin，然後依賴 `meta.lastTouchedVersion` 讓該發行版本通行只執行一次。Gateway 啟動和設定重新載入不會執行套件管理器；Plugin 安裝仍然是明確的 doctor/install/update 工作。
|
||||
當 config 參照已設定的可下載 plugins，但本機 plugin registry 找不到它們時，doctor 也可以重新安裝這些 plugins。對於 2026.5.2 bundled-plugin externalization，doctor 會自動安裝既有 config 已使用的可下載 plugins，然後依賴 `meta.lastTouchedVersion` 確保該發行版本處理只執行一次。Gateway 啟動與 config 重新載入不會執行 package manager；plugin 安裝仍是明確的 doctor/install/update 工作。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Gateway 服務遷移與清理提示">
|
||||
Doctor 會偵測舊版 Gateway 服務（launchd/systemd/schtasks），並提供移除它們以及使用目前 Gateway 連接埠安裝 OpenClaw 服務的選項。它也可以掃描額外的類 Gateway 服務並列印清理提示。以設定檔命名的 OpenClaw Gateway 服務被視為一級項目，不會被標記為「額外」。
|
||||
doctor 會偵測舊版 gateway 服務（launchd/systemd/schtasks），並提供移除它們以及使用目前 gateway 連接埠安裝 OpenClaw 服務的選項。它也可以掃描額外的 gateway 類服務並列印清理提示。以 profile 命名的 OpenClaw gateway 服務會被視為一級項目，不會被標記為「額外」。
|
||||
|
||||
在 Linux 上，如果使用者層級 Gateway 服務遺失但系統層級 OpenClaw Gateway 服務存在，doctor 不會自動安裝第二個使用者層級服務。使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 檢查，然後移除重複項，或在系統監督器擁有 Gateway 生命週期時設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
在 Linux 上，如果使用者層級 gateway 服務遺失但系統層級 OpenClaw gateway 服務存在，doctor 不會自動安裝第二個使用者層級服務。請使用 `openclaw gateway status --deep` 或 `openclaw doctor --deep` 檢查，然後移除重複項，或在系統 supervisor 擁有 gateway 生命週期時設定 `OPENCLAW_SERVICE_REPAIR_POLICY=external`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. 啟動 Matrix 遷移">
|
||||
當 Matrix 頻道帳號有待處理或可執行的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式下）會建立遷移前快照，然後執行盡力而為的遷移步驟：舊版 Matrix 狀態遷移和舊版加密狀態準備。兩個步驟都不是致命的；錯誤會被記錄，啟動會繼續。在唯讀模式（不帶 `--fix` 的 `openclaw doctor`）下，此檢查會完全略過。
|
||||
當 Matrix 頻道帳戶有待處理或可執行的舊版狀態遷移時，doctor（在 `--fix` / `--repair` 模式中）會建立遷移前快照，然後執行 best-effort 遷移步驟：舊版 Matrix 狀態遷移與舊版加密狀態準備。這兩個步驟都不是致命錯誤；錯誤會被記錄，啟動會繼續。在唯讀模式（不帶 `--fix` 的 `openclaw doctor`）中，這項檢查會完全略過。
|
||||
</Accordion>
|
||||
<Accordion title="8c. 裝置配對與驗證漂移">
|
||||
Doctor 現在會將裝置配對狀態作為正常健康狀態通行的一部分進行檢查。
|
||||
doctor 現在會在一般健康檢查中檢查裝置配對狀態。
|
||||
|
||||
它會回報：
|
||||
|
||||
- 待處理的首次配對請求
|
||||
- 已配對裝置的待處理角色升級
|
||||
- 已配對裝置的待處理範圍升級
|
||||
- 裝置 id 仍相符，但裝置身分已不再符合已核准記錄的公開金鑰不相符修復
|
||||
- 已核准角色缺少有效 token 的已配對記錄
|
||||
- 範圍偏離已核准配對基準的已配對 token
|
||||
- 目前機器上的本機快取裝置 token 項目，其時間早於 Gateway 端 token 輪替，或帶有過期的範圍中繼資料
|
||||
- 已配對裝置待處理的角色升級
|
||||
- 已配對裝置待處理的範圍升級
|
||||
- 裝置 id 仍相符但裝置身分已不再符合已核准記錄的公開金鑰不相符修復
|
||||
- 缺少已核准角色作用中 token 的已配對記錄
|
||||
- 範圍漂移到已核准配對基準之外的已配對 token
|
||||
- 目前機器上的本機快取裝置 token 項目，其早於 gateway 端 token 輪替，或帶有過時的範圍中繼資料
|
||||
|
||||
Doctor 不會自動核准配對請求，也不會自動輪替裝置 token。它會改為印出精確的下一步：
|
||||
doctor 不會自動核准配對請求，也不會自動輪替裝置 token。它會改為列印精確的後續步驟：
|
||||
|
||||
- 使用 `openclaw devices list` 檢查待處理請求
|
||||
- 使用 `openclaw devices approve <requestId>` 核准精確的請求
|
||||
- 使用 `openclaw devices approve <requestId>` 核准精確請求
|
||||
- 使用 `openclaw devices rotate --device <deviceId> --role <role>` 輪替新的 token
|
||||
- 使用 `openclaw devices remove <deviceId>` 移除並重新核准過期記錄
|
||||
- 使用 `openclaw devices remove <deviceId>` 移除並重新核准過時記錄
|
||||
|
||||
這會補上常見的「已配對但仍收到需要配對」缺口：doctor 現在會區分首次配對、待處理的角色/範圍升級，以及過期 token/裝置身分漂移。
|
||||
這會補上常見的「已配對但仍然收到需要配對」缺口：doctor 現在會區分首次配對、待處理角色/範圍升級，以及過時 token/裝置身分漂移。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. 安全性警告">
|
||||
當某個提供者在沒有允許清單的情況下對私訊開放，或某個政策以危險方式設定時，Doctor 會發出警告。
|
||||
當 provider 對 DM 開放但沒有 allowlist，或 policy 以危險方式設定時，doctor 會發出警告。
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 gateway 在登出後仍保持運作。
|
||||
<Accordion title="10. systemd linger（Linux）">
|
||||
如果以 systemd 使用者服務執行，doctor 會確保已啟用 lingering，讓 gateway 在登出後仍保持執行。
|
||||
</Accordion>
|
||||
<Accordion title="11. 工作區狀態（Skills、plugins 和舊版目錄）">
|
||||
Doctor 會印出預設代理程式的工作區狀態摘要：
|
||||
<Accordion title="11. 工作區狀態（skills、plugins 與舊版目錄）">
|
||||
doctor 會列印預設代理程式的工作區狀態摘要：
|
||||
|
||||
- **Skills 狀態**：計算符合資格、缺少需求，以及被允許清單封鎖的 skills 數量。
|
||||
- **Skills 狀態**：計算 eligible、missing-requirements 與 allowlist-blocked skills 的數量。
|
||||
- **舊版工作區目錄**：當 `~/openclaw` 或其他舊版工作區目錄與目前工作區並存時發出警告。
|
||||
- **Plugin 狀態**：計算已啟用/已停用/發生錯誤的 plugins；列出任何錯誤的 plugin ID；回報套件 plugin 能力。
|
||||
- **Plugin 相容性警告**：標記與目前執行階段有相容性問題的 plugins。
|
||||
- **Plugin 診斷**：顯示 plugin 登錄檔在載入期間發出的任何警告或錯誤。
|
||||
- **Plugin 狀態**：計算已啟用/已停用/錯誤 plugins；列出任何錯誤的 plugin ID；回報 bundle plugin capabilities。
|
||||
- **Plugin 相容性警告**：標記與目前 runtime 有相容性問題的 plugins。
|
||||
- **Plugin 診斷**：顯示 plugin registry 在載入期間發出的任何警告或錯誤。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. 啟動檔案大小">
|
||||
Doctor 會檢查工作區啟動檔案（例如 `AGENTS.md`、`CLAUDE.md`，或其他注入的脈絡檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元占總預算的比例。當檔案被截斷或接近限制時，doctor 會印出調整 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 的提示。
|
||||
<Accordion title="11b. Bootstrap 檔案大小">
|
||||
doctor 會檢查工作區 bootstrap 檔案（例如 `AGENTS.md`、`CLAUDE.md` 或其他注入的內容檔案）是否接近或超過設定的字元預算。它會回報每個檔案的原始與注入字元數、截斷百分比、截斷原因（`max/file` 或 `max/total`），以及總注入字元數佔總預算的比例。當檔案被截斷或接近限制時，doctor 會列印調整 `agents.defaults.bootstrapMaxChars` 與 `agents.defaults.bootstrapTotalMaxChars` 的提示。
|
||||
</Accordion>
|
||||
<Accordion title="11d. 過期通道 plugin 清理">
|
||||
當 `openclaw doctor --fix` 移除缺失的通道 plugin 時，也會移除參照該 plugin 的懸空通道範圍設定：`channels.<id>` 項目、指名該通道的 heartbeat 目標，以及 `agents.*.models["<channel>/*"]` 覆寫。這可避免通道執行階段已消失，但設定仍要求 Gateway 綁定到它而造成 Gateway 啟動迴圈。
|
||||
<Accordion title="11d. 過時頻道 Plugin 清理">
|
||||
當 `openclaw doctor --fix` 移除遺失的頻道 Plugin 時，它也會移除參照該 Plugin 的懸空頻道範圍 config：`channels.<id>` 項目、命名該頻道的 Heartbeat targets，以及 `agents.*.models["<channel>/*"]` overrides。這能避免頻道 runtime 已消失但 config 仍要求 gateway 綁定到它所造成的 Gateway 啟動迴圈。
|
||||
</Accordion>
|
||||
<Accordion title="11c. Shell 自動完成">
|
||||
Doctor 會檢查目前 shell（zsh、bash、fish 或 PowerShell）是否已安裝 Tab 自動完成：
|
||||
<Accordion title="11c. Shell 補全">
|
||||
doctor 會檢查目前 shell（zsh、bash、fish 或 PowerShell）是否已安裝 tab 補全：
|
||||
|
||||
- 如果 shell 設定檔使用緩慢的動態完成模式（`source <(openclaw completion ...)`），doctor 會將其升級為較快的快取檔案變體。
|
||||
- 如果完成已在設定檔中設定，但快取檔案遺失，doctor 會自動重新產生快取。
|
||||
- 如果完全沒有設定完成，doctor 會提示安裝（僅互動模式；使用 `--non-interactive` 時略過）。
|
||||
- 如果 shell profile 使用較慢的動態補全模式（`source <(openclaw completion ...)`），doctor 會將其升級為較快的快取檔案變體。
|
||||
- 如果 profile 中已設定補全但快取檔案遺失，doctor 會自動重新產生快取。
|
||||
- 如果完全沒有設定補全，doctor 會提示安裝（僅互動模式；使用 `--non-interactive` 時略過）。
|
||||
|
||||
執行 `openclaw completion --write-state` 可手動重新產生快取。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Gateway 驗證檢查（本機 token）">
|
||||
Doctor 會檢查本機 gateway token 驗證是否就緒。
|
||||
doctor 會檢查本機 gateway token 驗證就緒狀態。
|
||||
|
||||
- 如果 token 模式需要 token 且不存在 token 來源，doctor 會提供產生 token 的選項。
|
||||
- 如果 `gateway.auth.token` 由 SecretRef 管理但無法使用，doctor 會發出警告，且不會用純文字覆寫它。
|
||||
- `openclaw doctor --generate-gateway-token` 只有在未設定 token SecretRef 時才會強制產生。
|
||||
- 如果 token 模式需要 token 但不存在 token 來源，doctor 會提供產生一個的選項。
|
||||
- 如果 `gateway.auth.token` 由 SecretRef 管理但無法使用，doctor 會發出警告，且不會以純文字覆寫它。
|
||||
- `openclaw doctor --generate-gateway-token` 只會在未設定 token SecretRef 時強制產生。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. SecretRef 感知的唯讀修復">
|
||||
某些修復流程需要檢查已設定的憑證，同時不削弱執行階段的快速失敗行為。
|
||||
<Accordion title="12b. 可感知 SecretRef 的唯讀修復">
|
||||
某些修復流程需要檢查已設定的憑證，同時不削弱 runtime fail-fast 行為。
|
||||
|
||||
- `openclaw doctor --fix` 現在會使用與狀態系列命令相同的唯讀 SecretRef 摘要模型，來進行目標式設定修復。
|
||||
- `openclaw doctor --fix` 現在會使用與 status-family commands 相同的唯讀 SecretRef 摘要模型，來進行目標 config 修復。
|
||||
- 範例：Telegram `allowFrom` / `groupAllowFrom` `@username` 修復會在可用時嘗試使用已設定的 bot 憑證。
|
||||
- 如果 Telegram bot token 是透過 SecretRef 設定，但在目前命令路徑中無法使用，doctor 會回報該憑證已設定但不可用，並略過自動解析，而不是當機或誤報 token 遺失。
|
||||
- 如果 Telegram bot token 是透過 SecretRef 設定，但在目前指令路徑中無法使用，doctor 會回報憑證為已設定但無法使用，並略過自動解析，而不是當機或誤報 token 遺失。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Gateway 健康檢查 + 重新啟動">
|
||||
診斷工具會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動。
|
||||
Doctor 會執行健康檢查，並在 Gateway 看起來不健康時提議重新啟動 Gateway。
|
||||
</Accordion>
|
||||
<Accordion title="13b. 記憶體搜尋就緒狀態">
|
||||
診斷工具會檢查設定的記憶體搜尋嵌入提供者是否已為預設代理程式就緒。行為取決於設定的後端與提供者：
|
||||
Doctor 會檢查已設定的記憶體搜尋嵌入提供者是否已為預設代理程式就緒。行為取決於已設定的後端與提供者：
|
||||
|
||||
- **QMD 後端**：探測 `qmd` 二進位檔是否可用且可啟動。若不可用，會列印修復指引，包括 npm 套件與手動二進位檔路徑選項。
|
||||
- **明確的本機提供者**：檢查本機模型檔案，或可辨識的遠端/可下載模型 URL。若缺少，建議切換到遠端提供者。
|
||||
- **明確的遠端提供者**（`openai`、`voyage` 等）：驗證環境或驗證儲存區中是否存在 API 金鑰。若缺少，會列印可操作的修復提示。
|
||||
- **明確本機提供者**：檢查本機模型檔案或可辨識的遠端/可下載模型 URL。若缺少，建議切換到遠端提供者。
|
||||
- **明確遠端提供者**（`openai`、`voyage` 等）：驗證環境或驗證儲存區中是否存在 API 金鑰。若缺少，會列印可操作的修復提示。
|
||||
- **自動提供者**：先檢查本機模型可用性，接著依自動選擇順序嘗試每個遠端提供者。
|
||||
|
||||
當可用快取的 Gateway 探測結果時（檢查當下 Gateway 為健康狀態），診斷工具會將其結果與 CLI 可見的設定交叉比對，並註記任何差異。診斷工具不會在預設路徑上啟動新的嵌入 ping；當你需要即時提供者檢查時，請使用深度記憶體狀態指令。
|
||||
當快取的 Gateway 探測結果可用時（Gateway 在檢查當下是健康的），doctor 會將其結果與 CLI 可見的設定交叉比對，並註記任何差異。Doctor 不會在預設路徑上啟動新的嵌入 ping；若要即時提供者檢查，請使用深度記憶體狀態命令。
|
||||
|
||||
使用 `openclaw memory status --deep` 以驗證執行時的嵌入就緒狀態。
|
||||
使用 `openclaw memory status --deep` 在執行時驗證嵌入就緒狀態。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. 頻道狀態警告">
|
||||
如果 Gateway 健康，診斷工具會執行頻道狀態探測，並回報警告與建議修復方式。
|
||||
<Accordion title="14. 通道狀態警告">
|
||||
如果 Gateway 健康，doctor 會執行通道狀態探測，並回報警告與建議修復方式。
|
||||
</Accordion>
|
||||
<Accordion title="15. 監督程式設定稽核 + 修復">
|
||||
診斷工具會檢查已安裝的監督程式設定（launchd/systemd/schtasks）是否缺少預設值或使用過時預設值（例如 systemd network-online 相依性與重新啟動延遲）。當找到不相符項目時，它會建議更新，並可將服務檔案/工作重寫為目前預設值。
|
||||
<Accordion title="15. Supervisor 設定稽核 + 修復">
|
||||
Doctor 會檢查已安裝的 supervisor 設定（launchd/systemd/schtasks）是否缺少預設值或預設值過時（例如 systemd network-online 相依性與重新啟動延遲）。當發現不一致時，會建議更新，並可將服務檔案/工作重寫為目前預設值。
|
||||
|
||||
注意：
|
||||
|
||||
- `openclaw doctor` 會在重寫監督程式設定前提示。
|
||||
- `openclaw doctor` 會在重寫 supervisor 設定前提示。
|
||||
- `openclaw doctor --yes` 會接受預設修復提示。
|
||||
- `openclaw doctor --repair` 會在不提示的情況下套用建議修復。
|
||||
- `openclaw doctor --repair --force` 會覆寫自訂監督程式設定。
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 會讓診斷工具對 Gateway 服務生命週期保持唯讀。它仍會回報服務健康狀態並執行非服務修復，但會略過服務安裝/啟動/重新啟動/啟動程序、監督程式設定重寫，以及舊版服務清理，因為該生命週期由外部監督程式擁有。
|
||||
- 在 Linux 上，當相符的 systemd Gateway 單元處於啟用狀態時，診斷工具不會重寫指令/進入點中繼資料。它也會在重複服務掃描期間忽略非作用中且非舊版的額外類 Gateway 單元，避免伴隨服務檔案造成清理雜訊。
|
||||
- 如果權杖驗證需要權杖，且 `gateway.auth.token` 由 SecretRef 管理，診斷工具服務安裝/修復會驗證 SecretRef，但不會將已解析的純文字權杖值持久化到監督程式服務環境中繼資料中。
|
||||
- 診斷工具會偵測較舊的 LaunchAgent、systemd 或 Windows 排定工作安裝中內嵌行內的受管理 `.env`/SecretRef 後援服務環境值，並重寫服務中繼資料，讓這些值從執行時來源載入，而不是從監督程式定義載入。
|
||||
- 診斷工具會偵測服務指令是否在 `gateway.port` 變更後仍固定使用舊的 `--port`，並將服務中繼資料重寫為目前連接埠。
|
||||
- 如果權杖驗證需要權杖，且設定的權杖 SecretRef 無法解析，診斷工具會封鎖安裝/修復路徑並提供可操作的指引。
|
||||
- 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且未設定 `gateway.auth.mode`，診斷工具會封鎖安裝/修復，直到明確設定模式。
|
||||
- 對於 Linux 使用者 systemd 單元，診斷工具權杖漂移檢查現在會在比較服務驗證中繼資料時，同時包含 `Environment=` 與 `EnvironmentFile=` 來源。
|
||||
- 當設定最後由較新版本寫入時，診斷工具服務修復會拒絕重寫、停止或重新啟動來自較舊 OpenClaw 二進位檔的 Gateway 服務。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
|
||||
- 你永遠可以透過 `openclaw gateway install --force` 強制完整重寫。
|
||||
- `openclaw doctor --repair --force` 會覆寫自訂 supervisor 設定。
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 會讓 doctor 在 Gateway 服務生命週期中保持唯讀。它仍會回報服務健康狀態並執行非服務修復，但會略過服務安裝/啟動/重新啟動/bootstrap、supervisor 設定重寫，以及舊版服務清理，因為該生命週期由外部 supervisor 擁有。
|
||||
- 在 Linux 上，當相符的 systemd Gateway unit 為作用中時，doctor 不會重寫命令/進入點中繼資料。它也會在重複服務掃描期間忽略非作用中的非舊版額外類 Gateway unit，因此輔助服務檔案不會產生清理雜訊。
|
||||
- 如果 token 驗證需要 token，且 `gateway.auth.token` 由 SecretRef 管理，doctor 服務安裝/修復會驗證 SecretRef，但不會將解析後的純文字 token 值持久化到 supervisor 服務環境中繼資料中。
|
||||
- Doctor 會偵測舊版 LaunchAgent、systemd 或 Windows 排程工作安裝中內嵌行內的受管理 `.env`/SecretRef 支援服務環境值，並重寫服務中繼資料，讓這些值從執行時來源載入，而非從 supervisor 定義載入。
|
||||
- Doctor 會偵測服務命令在 `gateway.port` 變更後是否仍固定舊的 `--port`，並將服務中繼資料重寫為目前連接埠。
|
||||
- 如果 token 驗證需要 token，且已設定的 token SecretRef 無法解析，doctor 會封鎖安裝/修復路徑並提供可操作的指引。
|
||||
- 如果同時設定了 `gateway.auth.token` 與 `gateway.auth.password`，且 `gateway.auth.mode` 未設定，doctor 會封鎖安裝/修復，直到明確設定模式為止。
|
||||
- 對於 Linux 使用者 systemd unit，doctor token 漂移檢查現在會在比較服務驗證中繼資料時包含 `Environment=` 與 `EnvironmentFile=` 來源。
|
||||
- 當設定最後由較新版本寫入時，Doctor 服務修復會拒絕重寫、停止或重新啟動來自較舊 OpenClaw 二進位檔的 Gateway 服務。請參閱 [Gateway 疑難排解](/zh-TW/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)。
|
||||
- 你一律可以透過 `openclaw gateway install --force` 強制完整重寫。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Gateway 執行時 + 連接埠診斷">
|
||||
診斷工具會檢查服務執行時（PID、上次結束狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH 通道）。
|
||||
Doctor 會檢查服務執行時（PID、上次結束狀態），並在服務已安裝但實際上未執行時發出警告。它也會檢查 Gateway 連接埠（預設 `18789`）上的連接埠衝突，並回報可能原因（Gateway 已在執行、SSH tunnel）。
|
||||
</Accordion>
|
||||
<Accordion title="17. Gateway 執行時最佳實務">
|
||||
當 Gateway 服務在 Bun 或版本管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）上執行時，診斷工具會發出警告。WhatsApp + Telegram 頻道需要 Node，而版本管理器路徑可能在升級後中斷，因為服務不會載入你的 shell 初始化設定。當系統 Node 安裝可用時（Homebrew/apt/choco），診斷工具會提議遷移到該安裝。
|
||||
當 Gateway 服務在 Bun 或版本管理的 Node 路徑（`nvm`、`fnm`、`volta`、`asdf` 等）上執行時，Doctor 會發出警告。WhatsApp + Telegram 通道需要 Node，而版本管理器路徑在升級後可能失效，因為服務不會載入你的 shell init。Doctor 會在可用時提議遷移到系統 Node 安裝（Homebrew/apt/choco）。
|
||||
|
||||
新安裝或修復的 macOS LaunchAgent 會使用標準系統 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是複製互動式 shell PATH，因此 Volta、asdf、fnm、pnpm 與其他版本管理器目錄不會改變 Node 子程序的解析結果。Linux 服務仍會保留明確的環境根目錄（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）與穩定的使用者二進位目錄，但推測的版本管理器備援目錄只有在這些目錄實際存在於磁碟上時，才會寫入服務 PATH。
|
||||
新安裝或修復的 macOS LaunchAgent 會使用標準系統 PATH（`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`），而不是複製互動式 shell PATH，因此 Volta、asdf、fnm、pnpm 與其他版本管理器目錄不會改變 Node 子程序解析的位置。Linux 服務仍會保留明確的環境根目錄（`NVM_DIR`、`FNM_DIR`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`BUN_INSTALL`、`PNPM_HOME`）與穩定的使用者 bin 目錄，但推測的版本管理器後援目錄只會在那些目錄存在於磁碟上時寫入服務 PATH。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. 設定寫入 + 精靈中繼資料">
|
||||
診斷工具會持久化任何設定變更，並加蓋精靈中繼資料以記錄診斷工具執行。
|
||||
Doctor 會持久化任何設定變更，並標記精靈中繼資料以記錄 doctor 執行。
|
||||
</Accordion>
|
||||
<Accordion title="19. 工作區提示（備份 + 記憶體系統）">
|
||||
當工作區缺少記憶體系統時，診斷工具會提出建議；如果工作區尚未置於 git 下，則會列印備份提示。
|
||||
Doctor 會在缺少時建議工作區記憶體系統，並在工作區尚未納入 git 時列印備份提示。
|
||||
|
||||
請參閱 [/concepts/agent-workspace](/zh-TW/concepts/agent-workspace)，取得工作區結構與 git 備份的完整指南（建議使用私有 GitHub 或 GitLab）。
|
||||
|
||||
@ -495,5 +495,5 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
|
||||
## 相關
|
||||
|
||||
- [Gateway 執行手冊](/zh-TW/gateway)
|
||||
- [Gateway runbook](/zh-TW/gateway)
|
||||
- [Gateway 疑難排解](/zh-TW/gateway/troubleshooting)
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在決定某個 Plugin 是隨核心 npm 套件一併發佈，還是單獨安裝
|
||||
- 你正在更新隨附 Plugin 套件中繼資料或發布自動化
|
||||
- 你需要標準的內部與外部 Plugin 清單
|
||||
summary: OpenClaw 核心隨附、對外發布或僅保留原始碼的 Plugin 產生清單
|
||||
- 你正在決定某個 Plugin 是要隨核心 npm 套件一併提供，還是要另外安裝
|
||||
- 您正在更新內建 Plugin 套件中繼資料或發布自動化
|
||||
- 你需要內部與外部 Plugin 的標準清單
|
||||
summary: OpenClaw Plugin 的產生清單，包含隨核心提供、對外發布或僅保留原始碼的項目
|
||||
title: Plugin 清單
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:38:44Z"
|
||||
generated_at: "2026-05-04T09:37:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2099d8a67847f54040db332287708a1f79aa6c08e6e33125425389fe962865cb
|
||||
source_hash: 64f3d27ae65faacf89deeaad1b456318fa72993fdcf16262f30fb3f48b898024
|
||||
source_path: plugins/plugin-inventory.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Plugin 清冊
|
||||
# Plugin 清單
|
||||
|
||||
此頁面是由 `extensions/*/package.json`、`openclaw.plugin.json`
|
||||
以及根 npm 套件的 `files` 排除項目產生。使用以下命令重新產生：
|
||||
此頁面由 `extensions/*/package.json`、`openclaw.plugin.json`
|
||||
以及根 npm 套件的 `files` 排除項目產生。使用以下指令重新產生：
|
||||
|
||||
```bash
|
||||
pnpm plugins:inventory:gen
|
||||
@ -25,140 +25,160 @@ pnpm plugins:inventory:gen
|
||||
|
||||
## 定義
|
||||
|
||||
- **核心 npm 套件：** 內建於 `openclaw` npm 套件中，無需另外安裝 Plugin 即可使用。
|
||||
- **官方外部套件：** 由 OpenClaw 維護、但從核心 npm 套件中省略的 Plugin；保留在此官方清冊中，並可透過 ClawHub 和/或 npm 依需求安裝。
|
||||
- **僅限原始碼 checkout：** 僅限 repo 本機的 Plugin，會從已發布的 npm 成品中省略，且不會宣傳為可安裝套件。
|
||||
- **核心 npm 套件：** 內建於 `openclaw` npm 套件中，無需另行安裝 Plugin 即可使用。
|
||||
- **官方外部套件：** 由 OpenClaw 維護的 Plugin，未包含於核心 npm 套件中，保留在此官方清單內，並可透過 ClawHub 和／或 npm 按需安裝。
|
||||
- **僅限原始碼簽出：** 僅存在於 repo 本機的 Plugin，未包含於已發佈的 npm 成品中，也不會宣傳為可安裝套件。
|
||||
|
||||
原始碼 checkout 與 npm 安裝不同：執行 `pnpm install` 後， bundled
|
||||
Plugin 會從 `extensions/<id>` 載入，因此可使用本機編輯內容與套件本機 workspace
|
||||
依賴項目。
|
||||
原始碼簽出與 npm 安裝不同：執行 `pnpm install` 後，隨附的
|
||||
Plugin 會從 `extensions/<id>` 載入，因此本機編輯與套件本地的工作區
|
||||
相依性都可使用。
|
||||
|
||||
## 安裝 Plugin
|
||||
|
||||
使用 **發佈形式** 欄來判斷是否需要安裝。標示為
|
||||
`included in OpenClaw` 的 Plugin 已存在於核心套件中。官方外部套件
|
||||
需要安裝一次，然後重新啟動 Gateway。
|
||||
|
||||
例如，Discord 是官方外部套件：
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/discord
|
||||
openclaw gateway restart
|
||||
openclaw plugins inspect discord --runtime --json
|
||||
```
|
||||
|
||||
裸套件規格會先嘗試 ClawHub，然後再 fallback 到 npm。若要強制指定來源，請使用
|
||||
`clawhub:@openclaw/discord` 或 `npm:@openclaw/discord`。安裝後，請依照
|
||||
該 Plugin 的設定文件，例如 [Discord](/zh-TW/channels/discord)，新增憑證
|
||||
與頻道設定。請參閱[管理 Plugin](/zh-TW/plugins/manage-plugins)，了解更新、
|
||||
解除安裝與發佈指令。
|
||||
|
||||
## 核心 npm 套件
|
||||
|
||||
| Plugin | 說明 | 發佈方式 | 介面 |
|
||||
| Plugin | 描述 | 發佈方式 | 介面 |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [alibaba](/zh-TW/plugins/reference/alibaba) | 新增影片生成供應商支援。 | `@openclaw/alibaba-provider`<br />隨 OpenClaw 內附 | contracts: videoGenerationProviders |
|
||||
| [amazon-bedrock](/zh-TW/plugins/reference/amazon-bedrock) | 為 OpenClaw 新增 Amazon Bedrock 模型供應商支援。 | `@openclaw/amazon-bedrock-provider`<br />隨 OpenClaw 內附 | providers: amazon-bedrock; contracts: memoryEmbeddingProviders |
|
||||
| [amazon-bedrock-mantle](/zh-TW/plugins/reference/amazon-bedrock-mantle) | 為 OpenClaw 新增 Amazon Bedrock Mantle 模型供應商支援。 | `@openclaw/amazon-bedrock-mantle-provider`<br />隨 OpenClaw 內附 | providers: amazon-bedrock-mantle |
|
||||
| [anthropic](/zh-TW/plugins/reference/anthropic) | 為 OpenClaw 新增 Anthropic 模型供應商支援。 | `@openclaw/anthropic-provider`<br />隨 OpenClaw 內附 | providers: anthropic; contracts: mediaUnderstandingProviders |
|
||||
| [anthropic-vertex](/zh-TW/plugins/reference/anthropic-vertex) | 為 OpenClaw 新增 Anthropic Vertex 模型供應商支援。 | `@openclaw/anthropic-vertex-provider`<br />隨 OpenClaw 內附 | providers: anthropic-vertex |
|
||||
| [arcee](/zh-TW/plugins/reference/arcee) | 為 OpenClaw 新增 Arcee 模型供應商支援。 | `@openclaw/arcee-provider`<br />隨 OpenClaw 內附 | providers: arcee |
|
||||
| [azure-speech](/zh-TW/plugins/reference/azure-speech) | Azure AI Speech 文字轉語音（MP3、原生 Ogg/Opus 語音訊息、PCM 電話語音）。 | `@openclaw/azure-speech`<br />隨 OpenClaw 內附 | contracts: speechProviders |
|
||||
| [bonjour](/zh-TW/plugins/reference/bonjour) | 透過 Bonjour/mDNS 宣告本機 OpenClaw gateway。 | `@openclaw/bonjour`<br />隨 OpenClaw 內附 | plugin |
|
||||
| [browser](/zh-TW/plugins/reference/browser) | 新增可由代理呼叫的工具。 | `@openclaw/browser-plugin`<br />隨 OpenClaw 內附 | contracts: tools; skills |
|
||||
| [byteplus](/zh-TW/plugins/reference/byteplus) | 為 OpenClaw 新增 BytePlus、BytePlus Plan 模型供應商支援。 | `@openclaw/byteplus-provider`<br />隨 OpenClaw 內附 | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders |
|
||||
| [cerebras](/zh-TW/plugins/reference/cerebras) | 為 OpenClaw 新增 Cerebras 模型供應商支援。 | `@openclaw/cerebras-provider`<br />隨 OpenClaw 內附 | providers: cerebras |
|
||||
| [chutes](/zh-TW/plugins/reference/chutes) | 為 OpenClaw 新增 Chutes 模型供應商支援。 | `@openclaw/chutes-provider`<br />隨 OpenClaw 內附 | providers: chutes |
|
||||
| [cloudflare-ai-gateway](/zh-TW/plugins/reference/cloudflare-ai-gateway) | 為 OpenClaw 新增 Cloudflare AI Gateway 模型供應商支援。 | `@openclaw/cloudflare-ai-gateway-provider`<br />隨 OpenClaw 內附 | providers: cloudflare-ai-gateway |
|
||||
| [comfy](/zh-TW/plugins/reference/comfy) | 為 OpenClaw 新增 ComfyUI 模型供應商支援。 | `@openclaw/comfy-provider`<br />隨 OpenClaw 內附 | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders |
|
||||
| [copilot-proxy](/zh-TW/plugins/reference/copilot-proxy) | 為 OpenClaw 新增 Copilot Proxy 模型供應商支援。 | `@openclaw/copilot-proxy`<br />隨 OpenClaw 內附 | providers: copilot-proxy |
|
||||
| [deepgram](/zh-TW/plugins/reference/deepgram) | 新增媒體理解供應商支援。新增即時轉錄供應商支援。 | `@openclaw/deepgram-provider`<br />隨 OpenClaw 內附 | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders |
|
||||
| [deepinfra](/zh-TW/plugins/reference/deepinfra) | 為 OpenClaw 新增 DeepInfra 模型供應商支援。 | `@openclaw/deepinfra-provider`<br />隨 OpenClaw 內附 | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders |
|
||||
| [deepseek](/zh-TW/plugins/reference/deepseek) | 為 OpenClaw 新增 DeepSeek 模型供應商支援。 | `@openclaw/deepseek-provider`<br />隨 OpenClaw 內附 | providers: deepseek |
|
||||
| [document-extract](/zh-TW/plugins/reference/document-extract) | 從本機文件附件擷取文字和備用頁面影像。 | `@openclaw/document-extract-plugin`<br />隨 OpenClaw 內附 | contracts: documentExtractors |
|
||||
| [duckduckgo](/zh-TW/plugins/reference/duckduckgo) | 新增網頁搜尋提供者支援。 | `@openclaw/duckduckgo-plugin`<br />包含於 OpenClaw | 合約: webSearchProviders |
|
||||
| [elevenlabs](/zh-TW/plugins/reference/elevenlabs) | 新增媒體理解提供者支援。新增即時轉錄提供者支援。新增文字轉語音提供者支援。 | `@openclaw/elevenlabs-speech`<br />包含於 OpenClaw | 合約: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders |
|
||||
| [exa](/zh-TW/plugins/reference/exa) | 新增網頁搜尋提供者支援。 | `@openclaw/exa-plugin`<br />包含於 OpenClaw | 合約: webSearchProviders |
|
||||
| [fal](/zh-TW/plugins/reference/fal) | 新增 fal 模型提供者支援至 OpenClaw。 | `@openclaw/fal-provider`<br />包含於 OpenClaw | 提供者: fal; 合約: imageGenerationProviders, videoGenerationProviders |
|
||||
| [file-transfer](/zh-TW/plugins/reference/file-transfer) | 透過專用節點命令，在已配對的節點上擷取、列出及寫入檔案。透過對最大 16 MB 的二進位檔使用 base64 over node.invoke，繞過 bash stdout 截斷。 | `@openclaw/file-transfer`<br />包含於 OpenClaw | 合約: tools |
|
||||
| [firecrawl](/zh-TW/plugins/reference/firecrawl) | 新增代理可呼叫的工具。新增網頁擷取提供者支援。新增網頁搜尋提供者支援。 | `@openclaw/firecrawl-plugin`<br />包含於 OpenClaw | 合約: tools, webFetchProviders, webSearchProviders |
|
||||
| [fireworks](/zh-TW/plugins/reference/fireworks) | 新增 Fireworks 模型提供者支援至 OpenClaw。 | `@openclaw/fireworks-provider`<br />包含於 OpenClaw | 提供者: fireworks |
|
||||
| [github-copilot](/zh-TW/plugins/reference/github-copilot) | 新增 GitHub Copilot 模型提供者支援至 OpenClaw。 | `@openclaw/github-copilot-provider`<br />包含於 OpenClaw | 提供者: github-copilot; 合約: memoryEmbeddingProviders |
|
||||
| [google](/zh-TW/plugins/reference/google) | 新增 Google、Google Gemini CLI、Google Vertex 模型提供者支援至 OpenClaw。 | `@openclaw/google-plugin`<br />包含於 OpenClaw | 提供者: google, google-gemini-cli, google-vertex; 合約: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [gradium](/zh-TW/plugins/reference/gradium) | 新增文字轉語音提供者支援。 | `@openclaw/gradium-speech`<br />包含於 OpenClaw | 合約: speechProviders |
|
||||
| [groq](/zh-TW/plugins/reference/groq) | 新增 Groq 模型提供者支援至 OpenClaw。 | `@openclaw/groq-provider`<br />包含於 OpenClaw | 提供者: groq; 合約: mediaUnderstandingProviders |
|
||||
| [huggingface](/zh-TW/plugins/reference/huggingface) | 新增 Hugging Face 模型提供者支援至 OpenClaw。 | `@openclaw/huggingface-provider`<br />包含於 OpenClaw | 提供者: huggingface |
|
||||
| [imessage](/zh-TW/plugins/reference/imessage) | 新增 iMessage 頻道介面，用於傳送及接收 OpenClaw 訊息。 | `@openclaw/imessage`<br />包含於 OpenClaw | 頻道: imessage |
|
||||
| [inworld](/zh-TW/plugins/reference/inworld) | Inworld 串流文字轉語音（MP3、OGG_OPUS、PCM 電話語音）。 | `@openclaw/inworld-speech`<br />包含於 OpenClaw | 合約: speechProviders |
|
||||
| [irc](/zh-TW/plugins/reference/irc) | 新增 IRC 頻道介面，用於傳送及接收 OpenClaw 訊息。 | `@openclaw/irc`<br />包含於 OpenClaw | 頻道: irc |
|
||||
| [kilocode](/zh-TW/plugins/reference/kilocode) | 新增 Kilocode 模型提供者支援至 OpenClaw。 | `@openclaw/kilocode-provider`<br />包含於 OpenClaw | 提供者: kilocode |
|
||||
| [kimi](/zh-TW/plugins/reference/kimi) | 新增 Kimi、Kimi Coding 模型提供者支援至 OpenClaw。 | `@openclaw/kimi-provider`<br />包含於 OpenClaw | 提供者: kimi, kimi-coding |
|
||||
| [litellm](/zh-TW/plugins/reference/litellm) | 新增 LiteLLM 模型提供者支援至 OpenClaw。 | `@openclaw/litellm-provider`<br />包含於 OpenClaw | 提供者: litellm; 合約: imageGenerationProviders |
|
||||
| [llm-task](/zh-TW/plugins/reference/llm-task) | 可由工作流程呼叫、用於結構化任務的通用 JSON-only LLM 工具。 | `@openclaw/llm-task`<br />包含於 OpenClaw | 合約: tools |
|
||||
| [lmstudio](/zh-TW/plugins/reference/lmstudio) | 新增 LM Studio 模型提供者支援至 OpenClaw。 | `@openclaw/lmstudio-provider`<br />包含於 OpenClaw | 提供者: lmstudio; 合約: memoryEmbeddingProviders |
|
||||
| [matrix](/zh-TW/plugins/reference/matrix) | 新增 Matrix 頻道介面，用於傳送及接收 OpenClaw 訊息。 | `@openclaw/matrix`<br />包含於 OpenClaw | 頻道: matrix |
|
||||
| [mattermost](/zh-TW/plugins/reference/mattermost) | 新增 Mattermost 頻道介面，用於傳送及接收 OpenClaw 訊息。 | `@openclaw/mattermost`<br />包含在 OpenClaw 中 | channels: mattermost |
|
||||
| [memory-core](/zh-TW/plugins/reference/memory-core) | 新增記憶嵌入提供者支援。新增可由代理呼叫的工具。 | `@openclaw/memory-core`<br />包含在 OpenClaw 中 | contracts: memoryEmbeddingProviders, tools |
|
||||
| [memory-wiki](/zh-TW/plugins/reference/memory-wiki) | OpenClaw 的持久化 wiki 編譯器，以及適合 Obsidian 使用的知識庫。 | `@openclaw/memory-wiki`<br />包含在 OpenClaw 中 | contracts: tools; skills |
|
||||
| [alibaba](/zh-TW/plugins/reference/alibaba) | 新增影片生成提供者支援。 | `@openclaw/alibaba-provider`<br />包含於 OpenClaw | contracts: videoGenerationProviders |
|
||||
| [amazon-bedrock](/zh-TW/plugins/reference/amazon-bedrock) | 為 OpenClaw 新增 Amazon Bedrock 模型提供者支援。 | `@openclaw/amazon-bedrock-provider`<br />包含於 OpenClaw | providers: amazon-bedrock; contracts: memoryEmbeddingProviders |
|
||||
| [amazon-bedrock-mantle](/zh-TW/plugins/reference/amazon-bedrock-mantle) | 為 OpenClaw 新增 Amazon Bedrock Mantle 模型提供者支援。 | `@openclaw/amazon-bedrock-mantle-provider`<br />包含於 OpenClaw | providers: amazon-bedrock-mantle |
|
||||
| [anthropic](/zh-TW/plugins/reference/anthropic) | 為 OpenClaw 新增 Anthropic 模型提供者支援。 | `@openclaw/anthropic-provider`<br />包含於 OpenClaw | providers: anthropic; contracts: mediaUnderstandingProviders |
|
||||
| [anthropic-vertex](/zh-TW/plugins/reference/anthropic-vertex) | 為 OpenClaw 新增 Anthropic Vertex 模型提供者支援。 | `@openclaw/anthropic-vertex-provider`<br />包含於 OpenClaw | providers: anthropic-vertex |
|
||||
| [arcee](/zh-TW/plugins/reference/arcee) | 為 OpenClaw 新增 Arcee 模型提供者支援。 | `@openclaw/arcee-provider`<br />包含於 OpenClaw | providers: arcee |
|
||||
| [azure-speech](/zh-TW/plugins/reference/azure-speech) | Azure AI Speech 文字轉語音（MP3、原生 Ogg/Opus 語音訊息、PCM 電話語音）。 | `@openclaw/azure-speech`<br />包含於 OpenClaw | contracts: speechProviders |
|
||||
| [bonjour](/zh-TW/plugins/reference/bonjour) | 透過 Bonjour/mDNS 宣告本機 OpenClaw gateway。 | `@openclaw/bonjour`<br />包含於 OpenClaw | plugin |
|
||||
| [browser](/zh-TW/plugins/reference/browser) | 新增可由代理呼叫的工具。 | `@openclaw/browser-plugin`<br />包含於 OpenClaw | contracts: tools; skills |
|
||||
| [byteplus](/zh-TW/plugins/reference/byteplus) | 為 OpenClaw 新增 BytePlus、BytePlus Plan 模型提供者支援。 | `@openclaw/byteplus-provider`<br />包含於 OpenClaw | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders |
|
||||
| [cerebras](/zh-TW/plugins/reference/cerebras) | 為 OpenClaw 新增 Cerebras 模型提供者支援。 | `@openclaw/cerebras-provider`<br />包含於 OpenClaw | providers: cerebras |
|
||||
| [chutes](/zh-TW/plugins/reference/chutes) | 為 OpenClaw 新增 Chutes 模型提供者支援。 | `@openclaw/chutes-provider`<br />包含於 OpenClaw | providers: chutes |
|
||||
| [cloudflare-ai-gateway](/zh-TW/plugins/reference/cloudflare-ai-gateway) | 為 OpenClaw 新增 Cloudflare AI Gateway 模型提供者支援。 | `@openclaw/cloudflare-ai-gateway-provider`<br />包含於 OpenClaw | providers: cloudflare-ai-gateway |
|
||||
| [comfy](/zh-TW/plugins/reference/comfy) | 為 OpenClaw 新增 ComfyUI 模型提供者支援。 | `@openclaw/comfy-provider`<br />包含於 OpenClaw | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders |
|
||||
| [copilot-proxy](/zh-TW/plugins/reference/copilot-proxy) | 為 OpenClaw 新增 Copilot Proxy 模型提供者支援。 | `@openclaw/copilot-proxy`<br />包含於 OpenClaw | providers: copilot-proxy |
|
||||
| [deepgram](/zh-TW/plugins/reference/deepgram) | 新增媒體理解提供者支援。新增即時轉錄提供者支援。 | `@openclaw/deepgram-provider`<br />包含於 OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders |
|
||||
| [deepinfra](/zh-TW/plugins/reference/deepinfra) | 為 OpenClaw 新增 DeepInfra 模型提供者支援。 | `@openclaw/deepinfra-provider`<br />包含於 OpenClaw | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders |
|
||||
| [deepseek](/zh-TW/plugins/reference/deepseek) | 為 OpenClaw 新增 DeepSeek 模型提供者支援。 | `@openclaw/deepseek-provider`<br />包含於 OpenClaw | providers: deepseek |
|
||||
| [document-extract](/zh-TW/plugins/reference/document-extract) | 從本機文件附件擷取文字與備援頁面影像。 | `@openclaw/document-extract-plugin`<br />包含於 OpenClaw | contracts: documentExtractors |
|
||||
| [duckduckgo](/zh-TW/plugins/reference/duckduckgo) | 新增網頁搜尋提供者支援。 | `@openclaw/duckduckgo-plugin`<br />包含於 OpenClaw | contracts: webSearchProviders |
|
||||
| [elevenlabs](/zh-TW/plugins/reference/elevenlabs) | 新增媒體理解提供者支援。新增即時轉錄提供者支援。新增文字轉語音提供者支援。 | `@openclaw/elevenlabs-speech`<br />包含於 OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders |
|
||||
| [exa](/zh-TW/plugins/reference/exa) | 新增網頁搜尋提供者支援。 | `@openclaw/exa-plugin`<br />包含於 OpenClaw | contracts: webSearchProviders |
|
||||
| [fal](/zh-TW/plugins/reference/fal) | 將 fal 模型提供者支援新增至 OpenClaw。 | `@openclaw/fal-provider`<br />包含於 OpenClaw | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders |
|
||||
| [file-transfer](/zh-TW/plugins/reference/file-transfer) | 透過專用 Node 命令在配對的 Node 上擷取、列出及寫入檔案。對於最高 16 MB 的二進位檔，透過 `node.invoke` 使用 base64，繞過 `bash` `stdout` 截斷。 | `@openclaw/file-transfer`<br />包含於 OpenClaw | contracts: tools |
|
||||
| [firecrawl](/zh-TW/plugins/reference/firecrawl) | 新增代理程式可呼叫的工具。新增網頁擷取提供者支援。新增網頁搜尋提供者支援。 | `@openclaw/firecrawl-plugin`<br />包含於 OpenClaw | contracts: tools, webFetchProviders, webSearchProviders |
|
||||
| [fireworks](/zh-TW/plugins/reference/fireworks) | 將 Fireworks 模型提供者支援新增至 OpenClaw。 | `@openclaw/fireworks-provider`<br />包含於 OpenClaw | providers: fireworks |
|
||||
| [github-copilot](/zh-TW/plugins/reference/github-copilot) | 將 GitHub Copilot 模型提供者支援新增至 OpenClaw。 | `@openclaw/github-copilot-provider`<br />包含於 OpenClaw | providers: github-copilot; contracts: memoryEmbeddingProviders |
|
||||
| [google](/zh-TW/plugins/reference/google) | 將 Google、Google Gemini CLI、Google Vertex 模型提供者支援新增至 OpenClaw。 | `@openclaw/google-plugin`<br />包含於 OpenClaw | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [gradium](/zh-TW/plugins/reference/gradium) | 新增文字轉語音提供者支援。 | `@openclaw/gradium-speech`<br />包含於 OpenClaw | contracts: speechProviders |
|
||||
| [groq](/zh-TW/plugins/reference/groq) | 將 Groq 模型提供者支援新增至 OpenClaw。 | `@openclaw/groq-provider`<br />包含於 OpenClaw | providers: groq; contracts: mediaUnderstandingProviders |
|
||||
| [huggingface](/zh-TW/plugins/reference/huggingface) | 將 Hugging Face 模型提供者支援新增至 OpenClaw。 | `@openclaw/huggingface-provider`<br />包含於 OpenClaw | providers: huggingface |
|
||||
| [imessage](/zh-TW/plugins/reference/imessage) | 新增 iMessage channel 介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/imessage`<br />包含於 OpenClaw | channels: imessage |
|
||||
| [inworld](/zh-TW/plugins/reference/inworld) | Inworld 串流文字轉語音（MP3、OGG_OPUS、PCM 電話語音）。 | `@openclaw/inworld-speech`<br />包含於 OpenClaw | contracts: speechProviders |
|
||||
| [irc](/zh-TW/plugins/reference/irc) | 新增 IRC channel 介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/irc`<br />包含於 OpenClaw | channels: irc |
|
||||
| [kilocode](/zh-TW/plugins/reference/kilocode) | 將 Kilocode 模型提供者支援新增至 OpenClaw。 | `@openclaw/kilocode-provider`<br />包含於 OpenClaw | providers: kilocode |
|
||||
| [kimi](/zh-TW/plugins/reference/kimi) | 將 Kimi、Kimi Coding 模型提供者支援新增至 OpenClaw。 | `@openclaw/kimi-provider`<br />包含於 OpenClaw | providers: kimi, kimi-coding |
|
||||
| [litellm](/zh-TW/plugins/reference/litellm) | 將 LiteLLM 模型提供者支援新增至 OpenClaw。 | `@openclaw/litellm-provider`<br />包含於 OpenClaw | providers: litellm; contracts: imageGenerationProviders |
|
||||
| [llm-task](/zh-TW/plugins/reference/llm-task) | 可從工作流程呼叫、適用於結構化工作的通用 JSON-only LLM 工具。 | `@openclaw/llm-task`<br />包含於 OpenClaw | contracts: tools |
|
||||
| [lmstudio](/zh-TW/plugins/reference/lmstudio) | 將 LM Studio 模型提供者支援新增至 OpenClaw。 | `@openclaw/lmstudio-provider`<br />包含於 OpenClaw | providers: lmstudio; contracts: memoryEmbeddingProviders |
|
||||
| [matrix](/zh-TW/plugins/reference/matrix) | 新增 Matrix channel 介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/matrix`<br />包含於 OpenClaw | channels: matrix |
|
||||
| [mattermost](/zh-TW/plugins/reference/mattermost) | 新增 Mattermost channel 介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/mattermost`<br />包含在 OpenClaw 中 | channels: mattermost |
|
||||
| [memory-core](/zh-TW/plugins/reference/memory-core) | 新增記憶體嵌入提供者支援。新增代理可呼叫的工具。 | `@openclaw/memory-core`<br />包含在 OpenClaw 中 | contracts: memoryEmbeddingProviders, tools |
|
||||
| [memory-wiki](/zh-TW/plugins/reference/memory-wiki) | 適用於 OpenClaw 的持久化 wiki 編譯器與 Obsidian 友善知識庫。 | `@openclaw/memory-wiki`<br />包含在 OpenClaw 中 | contracts: tools; skills |
|
||||
| [microsoft](/zh-TW/plugins/reference/microsoft) | 新增文字轉語音提供者支援。 | `@openclaw/microsoft-speech`<br />包含在 OpenClaw 中 | contracts: speechProviders |
|
||||
| [microsoft-foundry](/zh-TW/plugins/reference/microsoft-foundry) | 為 OpenClaw 新增 Microsoft Foundry 模型提供者支援。 | `@openclaw/microsoft-foundry`<br />包含在 OpenClaw 中 | providers: microsoft-foundry |
|
||||
| [migrate-claude](/zh-TW/plugins/reference/migrate-claude) | 將 Claude Code 和 Claude Desktop 指示、MCP 伺服器、Skills，以及安全設定匯入 OpenClaw。 | `@openclaw/migrate-claude`<br />包含在 OpenClaw 中 | contracts: migrationProviders |
|
||||
| [migrate-hermes](/zh-TW/plugins/reference/migrate-hermes) | 將 Hermes 設定、記憶、Skills，以及支援的憑證匯入 OpenClaw。 | `@openclaw/migrate-hermes`<br />包含在 OpenClaw 中 | contracts: migrationProviders |
|
||||
| [migrate-claude](/zh-TW/plugins/reference/migrate-claude) | 將 Claude Code 和 Claude Desktop 指示、MCP 伺服器、skills，以及安全設定匯入 OpenClaw。 | `@openclaw/migrate-claude`<br />包含在 OpenClaw 中 | contracts: migrationProviders |
|
||||
| [migrate-hermes](/zh-TW/plugins/reference/migrate-hermes) | 將 Hermes 設定、記憶、skills，以及支援的憑證匯入 OpenClaw。 | `@openclaw/migrate-hermes`<br />包含在 OpenClaw 中 | contracts: migrationProviders |
|
||||
| [minimax](/zh-TW/plugins/reference/minimax) | 為 OpenClaw 新增 MiniMax、MiniMax Portal 模型提供者支援。 | `@openclaw/minimax-provider`<br />包含在 OpenClaw 中 | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [mistral](/zh-TW/plugins/reference/mistral) | 為 OpenClaw 新增 Mistral 模型提供者支援。 | `@openclaw/mistral-provider`<br />包含在 OpenClaw 中 | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders |
|
||||
| [moonshot](/zh-TW/plugins/reference/moonshot) | 為 OpenClaw 新增 Moonshot 模型提供者支援。 | `@openclaw/moonshot-provider`<br />包含在 OpenClaw 中 | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders |
|
||||
| [nvidia](/zh-TW/plugins/reference/nvidia) | 為 OpenClaw 新增 NVIDIA 模型提供者支援。 | `@openclaw/nvidia-provider`<br />包含在 OpenClaw 中 | providers: nvidia |
|
||||
| [ollama](/zh-TW/plugins/reference/ollama) | 為 OpenClaw 新增 Ollama 模型提供者支援。 | `@openclaw/ollama-provider`<br />包含在 OpenClaw 中 | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders |
|
||||
| [open-prose](/zh-TW/plugins/reference/open-prose) | OpenProse VM Skills 包，包含 /prose 斜線命令。 | `@openclaw/open-prose`<br />包含在 OpenClaw 中 | skills |
|
||||
| [open-prose](/zh-TW/plugins/reference/open-prose) | OpenProse VM skill pack，包含 /prose 斜線命令。 | `@openclaw/open-prose`<br />包含在 OpenClaw 中 | skills |
|
||||
| [openai](/zh-TW/plugins/reference/openai) | 為 OpenClaw 新增 OpenAI、OpenAI Codex 模型提供者支援。 | `@openclaw/openai-provider`<br />包含在 OpenClaw 中 | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders |
|
||||
| [opencode](/zh-TW/plugins/reference/opencode) | 為 OpenClaw 新增 OpenCode 模型提供者支援。 | `@openclaw/opencode-provider`<br />包含在 OpenClaw 中 | providers: opencode; contracts: mediaUnderstandingProviders |
|
||||
| [opencode-go](/zh-TW/plugins/reference/opencode-go) | 為 OpenClaw 新增 OpenCode Go 模型提供者支援。 | `@openclaw/opencode-go-provider`<br />包含在 OpenClaw 中 | providers: opencode-go; contracts: mediaUnderstandingProviders |
|
||||
| [openrouter](/zh-TW/plugins/reference/openrouter) | 為 OpenClaw 新增 OpenRouter 模型提供者支援。 | `@openclaw/openrouter-provider`<br />包含在 OpenClaw 中 | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders |
|
||||
| [openshell](/zh-TW/plugins/reference/openshell) | 由 OpenShell 驅動的沙箱後端，具備鏡像本機工作區與以 SSH 為基礎的命令執行功能。 | `@openclaw/openshell-sandbox`<br />包含在 OpenClaw 中 | plugin |
|
||||
| [openshell](/zh-TW/plugins/reference/openshell) | 由 OpenShell 驅動的沙箱後端，具備鏡像 local 工作區與 SSH 型命令執行。 | `@openclaw/openshell-sandbox`<br />包含在 OpenClaw 中 | plugin |
|
||||
| [perplexity](/zh-TW/plugins/reference/perplexity) | 新增網頁搜尋提供者支援。 | `@openclaw/perplexity-plugin`<br />包含在 OpenClaw 中 | contracts: webSearchProviders |
|
||||
| [qianfan](/zh-TW/plugins/reference/qianfan) | 為 OpenClaw 新增 Qianfan 模型提供者支援。 | `@openclaw/qianfan-provider`<br />包含在 OpenClaw 中 | providers: qianfan |
|
||||
| [qwen](/zh-TW/plugins/reference/qwen) | 為 OpenClaw 新增 Qwen、Qwen Cloud、Model Studio、DashScope 模型提供者支援。 | `@openclaw/qwen-provider`<br />包含在 OpenClaw 中 | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders |
|
||||
| [runway](/zh-TW/plugins/reference/runway) | 新增影片生成供應商支援。 | `@openclaw/runway-provider`<br />包含於 OpenClaw | contracts: videoGenerationProviders |
|
||||
| [searxng](/zh-TW/plugins/reference/searxng) | 新增網頁搜尋供應商支援。 | `@openclaw/searxng-plugin`<br />包含於 OpenClaw | contracts: webSearchProviders |
|
||||
| [senseaudio](/zh-TW/plugins/reference/senseaudio) | 新增媒體理解供應商支援。 | `@openclaw/senseaudio-provider`<br />包含於 OpenClaw | contracts: mediaUnderstandingProviders |
|
||||
| [sglang](/zh-TW/plugins/reference/sglang) | 為 OpenClaw 新增 SGLang 模型供應商支援。 | `@openclaw/sglang-provider`<br />包含於 OpenClaw | providers: sglang |
|
||||
| [runway](/zh-TW/plugins/reference/runway) | 新增影片生成供應器支援。 | `@openclaw/runway-provider`<br />包含於 OpenClaw | contracts: videoGenerationProviders |
|
||||
| [searxng](/zh-TW/plugins/reference/searxng) | 新增網頁搜尋供應器支援。 | `@openclaw/searxng-plugin`<br />包含於 OpenClaw | contracts: webSearchProviders |
|
||||
| [senseaudio](/zh-TW/plugins/reference/senseaudio) | 新增媒體理解供應器支援。 | `@openclaw/senseaudio-provider`<br />包含於 OpenClaw | contracts: mediaUnderstandingProviders |
|
||||
| [sglang](/zh-TW/plugins/reference/sglang) | 為 OpenClaw 新增 SGLang 模型供應器支援。 | `@openclaw/sglang-provider`<br />包含於 OpenClaw | providers: sglang |
|
||||
| [signal](/zh-TW/plugins/reference/signal) | 新增 Signal 通道介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/signal`<br />包含於 OpenClaw | channels: signal |
|
||||
| [skill-workshop](/zh-TW/plugins/reference/skill-workshop) | 將可重複的工作流程擷取為工作區 Skills，包含待審核、安全寫入和技能提示重新整理。 | `@openclaw/skill-workshop`<br />包含於 OpenClaw | contracts: tools |
|
||||
| [skill-workshop](/zh-TW/plugins/reference/skill-workshop) | 將可重複的工作流程擷取為工作區 Skills，具備待審核、安全寫入與 Skill 提示重新整理。 | `@openclaw/skill-workshop`<br />包含於 OpenClaw | contracts: tools |
|
||||
| [slack](/zh-TW/plugins/reference/slack) | 新增 Slack 通道介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/slack`<br />包含於 OpenClaw | channels: slack |
|
||||
| [stepfun](/zh-TW/plugins/reference/stepfun) | 為 OpenClaw 新增 StepFun、StepFun Plan 模型供應商支援。 | `@openclaw/stepfun-provider`<br />包含於 OpenClaw | providers: stepfun, stepfun-plan |
|
||||
| [synthetic](/zh-TW/plugins/reference/synthetic) | 為 OpenClaw 新增 Synthetic 模型供應商支援。 | `@openclaw/synthetic-provider`<br />包含於 OpenClaw | providers: synthetic |
|
||||
| [tavily](/zh-TW/plugins/reference/tavily) | 新增代理可呼叫的工具。新增網頁搜尋供應商支援。 | `@openclaw/tavily-plugin`<br />包含於 OpenClaw | contracts: tools, webSearchProviders; skills |
|
||||
| [stepfun](/zh-TW/plugins/reference/stepfun) | 為 OpenClaw 新增 StepFun、StepFun Plan 模型供應器支援。 | `@openclaw/stepfun-provider`<br />包含於 OpenClaw | providers: stepfun, stepfun-plan |
|
||||
| [synthetic](/zh-TW/plugins/reference/synthetic) | 為 OpenClaw 新增 Synthetic 模型供應器支援。 | `@openclaw/synthetic-provider`<br />包含於 OpenClaw | providers: synthetic |
|
||||
| [tavily](/zh-TW/plugins/reference/tavily) | 新增可由代理呼叫的工具。新增網頁搜尋供應器支援。 | `@openclaw/tavily-plugin`<br />包含於 OpenClaw | contracts: tools, webSearchProviders; skills |
|
||||
| [telegram](/zh-TW/plugins/reference/telegram) | 新增 Telegram 通道介面，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/telegram`<br />包含於 OpenClaw | channels: telegram |
|
||||
| [tencent](/zh-TW/plugins/reference/tencent) | 為 OpenClaw 新增 Tencent TokenHub 模型供應商支援。 | `@openclaw/tencent-provider`<br />包含於 OpenClaw | providers: tencent-tokenhub |
|
||||
| [together](/zh-TW/plugins/reference/together) | 為 OpenClaw 新增 Together 模型供應商支援。 | `@openclaw/together-provider`<br />包含於 OpenClaw | providers: together; contracts: videoGenerationProviders |
|
||||
| [tokenjuice](/zh-TW/plugins/reference/tokenjuice) | 使用 tokenjuice reducer 壓縮 exec 和 bash 工具結果。 | `@openclaw/tokenjuice`<br />包含於 OpenClaw | contracts: agentToolResultMiddleware |
|
||||
| [tts-local-cli](/zh-TW/plugins/reference/tts-local-cli) | 新增文字轉語音供應商支援。 | `@openclaw/tts-local-cli`<br />包含於 OpenClaw | contracts: speechProviders |
|
||||
| [venice](/zh-TW/plugins/reference/venice) | 為 OpenClaw 新增 Venice 模型供應商支援。 | `@openclaw/venice-provider`<br />包含於 OpenClaw | providers: venice |
|
||||
| [vercel-ai-gateway](/zh-TW/plugins/reference/vercel-ai-gateway) | 為 OpenClaw 新增 Vercel AI Gateway 模型供應商支援。 | `@openclaw/vercel-ai-gateway-provider`<br />包含於 OpenClaw | providers: vercel-ai-gateway |
|
||||
| [vllm](/zh-TW/plugins/reference/vllm) | 為 OpenClaw 新增 vLLM 模型供應商支援。 | `@openclaw/vllm-provider`<br />包含於 OpenClaw | providers: vllm |
|
||||
| [volcengine](/zh-TW/plugins/reference/volcengine) | 為 OpenClaw 新增 Volcengine、Volcengine Plan 模型供應商支援。 | `@openclaw/volcengine-provider`<br />包含於 OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders |
|
||||
| [voyage](/zh-TW/plugins/reference/voyage) | 新增記憶體嵌入供應商支援。 | `@openclaw/voyage-provider`<br />包含於 OpenClaw | contracts: memoryEmbeddingProviders |
|
||||
| [vydra](/zh-TW/plugins/reference/vydra) | 為 OpenClaw 新增 Vydra 模型供應商支援。 | `@openclaw/vydra-provider`<br />包含於 OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders |
|
||||
| [web-readability](/zh-TW/plugins/reference/web-readability) | 從本機 HTML 網頁擷取回應中萃取可讀的文章內容。 | `@openclaw/web-readability-plugin`<br />已包含於 OpenClaw | contracts: webContentExtractors |
|
||||
| [webhooks](/zh-TW/plugins/reference/webhooks) | 已驗證的傳入 Webhook，將外部自動化綁定至 OpenClaw TaskFlows。 | `@openclaw/webhooks`<br />已包含於 OpenClaw | plugin |
|
||||
| [xai](/zh-TW/plugins/reference/xai) | 新增 OpenClaw 對 xAI 模型提供者的支援。 | `@openclaw/xai-plugin`<br />已包含於 OpenClaw | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders |
|
||||
| [xiaomi](/zh-TW/plugins/reference/xiaomi) | 新增 OpenClaw 對 Xiaomi 模型提供者的支援。 | `@openclaw/xiaomi-provider`<br />已包含於 OpenClaw | providers: xiaomi; contracts: speechProviders |
|
||||
| [zai](/zh-TW/plugins/reference/zai) | 新增 OpenClaw 對 Z.AI 模型提供者的支援。 | `@openclaw/zai-provider`<br />已包含於 OpenClaw | providers: zai; contracts: mediaUnderstandingProviders |
|
||||
| [tencent](/zh-TW/plugins/reference/tencent) | 為 OpenClaw 新增 Tencent TokenHub 模型供應器支援。 | `@openclaw/tencent-provider`<br />包含於 OpenClaw | providers: tencent-tokenhub |
|
||||
| [together](/zh-TW/plugins/reference/together) | 為 OpenClaw 新增 Together 模型供應器支援。 | `@openclaw/together-provider`<br />包含於 OpenClaw | providers: together; contracts: videoGenerationProviders |
|
||||
| [tokenjuice](/zh-TW/plugins/reference/tokenjuice) | 使用 tokenjuice reducer 壓縮 exec 與 bash 工具結果。 | `@openclaw/tokenjuice`<br />包含於 OpenClaw | contracts: agentToolResultMiddleware |
|
||||
| [tts-local-cli](/zh-TW/plugins/reference/tts-local-cli) | 新增文字轉語音供應器支援。 | `@openclaw/tts-local-cli`<br />包含於 OpenClaw | contracts: speechProviders |
|
||||
| [venice](/zh-TW/plugins/reference/venice) | 為 OpenClaw 新增 Venice 模型供應器支援。 | `@openclaw/venice-provider`<br />包含於 OpenClaw | providers: venice |
|
||||
| [vercel-ai-gateway](/zh-TW/plugins/reference/vercel-ai-gateway) | 為 OpenClaw 新增 Vercel AI Gateway 模型供應器支援。 | `@openclaw/vercel-ai-gateway-provider`<br />包含於 OpenClaw | providers: vercel-ai-gateway |
|
||||
| [vllm](/zh-TW/plugins/reference/vllm) | 為 OpenClaw 新增 vLLM 模型供應器支援。 | `@openclaw/vllm-provider`<br />包含於 OpenClaw | providers: vllm |
|
||||
| [volcengine](/zh-TW/plugins/reference/volcengine) | 為 OpenClaw 新增 Volcengine、Volcengine Plan 模型供應器支援。 | `@openclaw/volcengine-provider`<br />包含於 OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders |
|
||||
| [voyage](/zh-TW/plugins/reference/voyage) | 新增記憶體嵌入供應器支援。 | `@openclaw/voyage-provider`<br />包含於 OpenClaw | contracts: memoryEmbeddingProviders |
|
||||
| [vydra](/zh-TW/plugins/reference/vydra) | 為 OpenClaw 新增 Vydra 模型供應器支援。 | `@openclaw/vydra-provider`<br />包含於 OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders |
|
||||
| [web-readability](/zh-TW/plugins/reference/web-readability) | 從本機 HTML 網頁擷取回應中擷取可讀的文章內容。 | `@openclaw/web-readability-plugin`<br />包含於 OpenClaw | contracts: webContentExtractors |
|
||||
| [webhooks](/zh-TW/plugins/reference/webhooks) | 經驗證的傳入 Webhook，將外部自動化綁定至 OpenClaw TaskFlow。 | `@openclaw/webhooks`<br />包含於 OpenClaw | plugin |
|
||||
| [xai](/zh-TW/plugins/reference/xai) | 為 OpenClaw 新增 xAI 模型提供者支援。 | `@openclaw/xai-plugin`<br />包含於 OpenClaw | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders |
|
||||
| [xiaomi](/zh-TW/plugins/reference/xiaomi) | 為 OpenClaw 新增 Xiaomi 模型提供者支援。 | `@openclaw/xiaomi-provider`<br />包含於 OpenClaw | providers: xiaomi; contracts: speechProviders |
|
||||
| [zai](/zh-TW/plugins/reference/zai) | 為 OpenClaw 新增 Z.AI 模型提供者支援。 | `@openclaw/zai-provider`<br />包含於 OpenClaw | providers: zai; contracts: mediaUnderstandingProviders |
|
||||
|
||||
## 官方外部套件
|
||||
|
||||
| Plugin | 說明 | 發行方式 | 介面 |
|
||||
| Plugin | 說明 | 發佈 | 介面 |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
||||
| [acpx](/zh-TW/plugins/reference/acpx) | 嵌入式 ACP 執行階段後端，具備 Plugin 擁有的工作階段與傳輸管理。 | `@openclaw/acpx`<br />npm; ClawHub | skills |
|
||||
| [bluebubbles](/zh-TW/plugins/reference/bluebubbles) | 新增 BlueBubbles 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/bluebubbles`<br />npm; ClawHub | channels: bluebubbles |
|
||||
| [brave](/zh-TW/plugins/reference/brave) | 新增網頁搜尋供應器支援。 | `@openclaw/brave-plugin`<br />npm; ClawHub | contracts: webSearchProviders |
|
||||
| [codex](/zh-TW/plugins/reference/codex) | Codex 應用程式伺服器框架，以及由 Codex 管理的 GPT 模型目錄。 | `@openclaw/codex`<br />npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders |
|
||||
| [diagnostics-otel](/zh-TW/plugins/reference/diagnostics-otel) | OpenClaw 診斷 OpenTelemetry 匯出器。 | `@openclaw/diagnostics-otel`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-otel` | plugin |
|
||||
| [diagnostics-prometheus](/zh-TW/plugins/reference/diagnostics-prometheus) | OpenClaw 診斷 Prometheus 匯出器。 | `@openclaw/diagnostics-prometheus`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus` | plugin |
|
||||
| [diffs](/zh-TW/plugins/reference/diffs) | 供代理使用的唯讀差異檢視器與檔案呈現器。 | `@openclaw/diffs`<br />npm; ClawHub | contracts: tools; skills |
|
||||
| [discord](/zh-TW/plugins/reference/discord) | 新增 Discord 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/discord`<br />npm; ClawHub | channels: discord |
|
||||
| [feishu](/zh-TW/plugins/reference/feishu) | 新增 Feishu 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/feishu`<br />npm; ClawHub | channels: feishu; contracts: tools; skills |
|
||||
| [google-meet](/zh-TW/plugins/reference/google-meet) | 透過 Chrome 或 Twilio 傳輸加入 Google Meet 通話。 | `@openclaw/google-meet`<br />npm; ClawHub | contracts: tools |
|
||||
| [googlechat](/zh-TW/plugins/reference/googlechat) | 新增 Google Chat 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/googlechat`<br />npm; ClawHub | channels: googlechat |
|
||||
| [line](/zh-TW/plugins/reference/line) | 新增 LINE 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/line`<br />npm; ClawHub | channels: line |
|
||||
| [lobster](/zh-TW/plugins/reference/lobster) | 具備可恢復核准流程的型別化工作流程工具。 | `@openclaw/lobster`<br />npm; ClawHub | contracts: tools |
|
||||
| [memory-lancedb](/zh-TW/plugins/reference/memory-lancedb) | 新增代理可呼叫的工具。 | `@openclaw/memory-lancedb`<br />npm; ClawHub | contracts: tools |
|
||||
| [msteams](/zh-TW/plugins/reference/msteams) | 新增 Microsoft Teams 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/msteams`<br />npm; ClawHub | channels: msteams |
|
||||
| [nextcloud-talk](/zh-TW/plugins/reference/nextcloud-talk) | 新增 Nextcloud Talk 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/nextcloud-talk`<br />npm; ClawHub | channels: nextcloud-talk |
|
||||
| [nostr](/zh-TW/plugins/reference/nostr) | 新增 Nostr 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/nostr`<br />npm; ClawHub | channels: nostr |
|
||||
| [qqbot](/zh-TW/plugins/reference/qqbot) | 新增 QQ Bot 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/qqbot`<br />npm; ClawHub | channels: qqbot; contracts: tools; skills |
|
||||
| [synology-chat](/zh-TW/plugins/reference/synology-chat) | 新增 Synology Chat 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/synology-chat`<br />npm; ClawHub | channels: synology-chat |
|
||||
| [tlon](/zh-TW/plugins/reference/tlon) | 新增 Tlon 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/tlon`<br />npm; ClawHub | channels: tlon; contracts: tools; skills |
|
||||
| [twitch](/zh-TW/plugins/reference/twitch) | 新增 Twitch 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/twitch`<br />npm; ClawHub | channels: twitch |
|
||||
| [voice-call](/zh-TW/plugins/reference/voice-call) | 新增代理可呼叫的工具。 | `@openclaw/voice-call`<br />npm; ClawHub | contracts: tools |
|
||||
| [whatsapp](/zh-TW/plugins/reference/whatsapp) | 新增 WhatsApp 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/whatsapp`<br />npm; ClawHub | channels: whatsapp |
|
||||
| [zalo](/zh-TW/plugins/reference/zalo) | 新增 Zalo 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/zalo`<br />npm; ClawHub | channels: zalo |
|
||||
| [zalouser](/zh-TW/plugins/reference/zalouser) | 新增 Zalo Personal 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/zalouser`<br />npm; ClawHub | channels: zalouser; contracts: tools |
|
||||
| [acpx](/zh-TW/plugins/reference/acpx) | 內嵌 ACP 執行階段後端，含 Plugin 擁有的工作階段與傳輸管理。 | `@openclaw/acpx`<br />npm; ClawHub | skills |
|
||||
| [bluebubbles](/zh-TW/plugins/reference/bluebubbles) | 新增 BlueBubbles channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/bluebubbles`<br />npm; ClawHub | channels: bluebubbles |
|
||||
| [brave](/zh-TW/plugins/reference/brave) | 新增網頁搜尋提供者支援。 | `@openclaw/brave-plugin`<br />npm; ClawHub | contracts: webSearchProviders |
|
||||
| [codex](/zh-TW/plugins/reference/codex) | Codex app-server harness，以及由 Codex 管理的 GPT 模型目錄。 | `@openclaw/codex`<br />npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders |
|
||||
| [diagnostics-otel](/zh-TW/plugins/reference/diagnostics-otel) | OpenClaw diagnostics OpenTelemetry 匯出器。 | `@openclaw/diagnostics-otel`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-otel` | plugin |
|
||||
| [diagnostics-prometheus](/zh-TW/plugins/reference/diagnostics-prometheus) | OpenClaw diagnostics Prometheus 匯出器。 | `@openclaw/diagnostics-prometheus`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus` | plugin |
|
||||
| [diffs](/zh-TW/plugins/reference/diffs) | 供 agent 使用的唯讀差異檢視器與檔案算繪器。 | `@openclaw/diffs`<br />npm; ClawHub | contracts: tools; skills |
|
||||
| [discord](/zh-TW/plugins/reference/discord) | 新增 Discord channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/discord`<br />npm; ClawHub | channels: discord |
|
||||
| [feishu](/zh-TW/plugins/reference/feishu) | 新增 Feishu channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/feishu`<br />npm; ClawHub | channels: feishu; contracts: tools; skills |
|
||||
| [google-meet](/zh-TW/plugins/reference/google-meet) | 透過 Chrome 或 Twilio 傳輸加入 Google Meet 通話。 | `@openclaw/google-meet`<br />npm; ClawHub | contracts: tools |
|
||||
| [googlechat](/zh-TW/plugins/reference/googlechat) | 新增 Google Chat channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/googlechat`<br />npm; ClawHub | channels: googlechat |
|
||||
| [line](/zh-TW/plugins/reference/line) | 新增 LINE channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/line`<br />npm; ClawHub | channels: line |
|
||||
| [lobster](/zh-TW/plugins/reference/lobster) | 具備可恢復核准流程的型別化工作流程工具。 | `@openclaw/lobster`<br />npm; ClawHub | contracts: tools |
|
||||
| [memory-lancedb](/zh-TW/plugins/reference/memory-lancedb) | 新增 agent 可呼叫的工具。 | `@openclaw/memory-lancedb`<br />npm; ClawHub | contracts: tools |
|
||||
| [msteams](/zh-TW/plugins/reference/msteams) | 新增 Microsoft Teams channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/msteams`<br />npm; ClawHub | channels: msteams |
|
||||
| [nextcloud-talk](/zh-TW/plugins/reference/nextcloud-talk) | 新增 Nextcloud Talk channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/nextcloud-talk`<br />npm; ClawHub | channels: nextcloud-talk |
|
||||
| [nostr](/zh-TW/plugins/reference/nostr) | 新增 Nostr channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/nostr`<br />npm; ClawHub | channels: nostr |
|
||||
| [qqbot](/zh-TW/plugins/reference/qqbot) | 新增 QQ Bot channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/qqbot`<br />npm; ClawHub | channels: qqbot; contracts: tools; skills |
|
||||
| [synology-chat](/zh-TW/plugins/reference/synology-chat) | 新增 Synology Chat channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/synology-chat`<br />npm; ClawHub | channels: synology-chat |
|
||||
| [tlon](/zh-TW/plugins/reference/tlon) | 新增 Tlon channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/tlon`<br />npm; ClawHub | channels: tlon; contracts: tools; skills |
|
||||
| [twitch](/zh-TW/plugins/reference/twitch) | 新增 Twitch channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/twitch`<br />npm; ClawHub | channels: twitch |
|
||||
| [voice-call](/zh-TW/plugins/reference/voice-call) | 新增 agent 可呼叫的工具。 | `@openclaw/voice-call`<br />npm; ClawHub | contracts: tools |
|
||||
| [whatsapp](/zh-TW/plugins/reference/whatsapp) | 新增 WhatsApp channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/whatsapp`<br />npm; ClawHub | channels: whatsapp |
|
||||
| [zalo](/zh-TW/plugins/reference/zalo) | 新增 Zalo channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/zalo`<br />npm; ClawHub | channels: zalo |
|
||||
| [zalouser](/zh-TW/plugins/reference/zalouser) | 新增 Zalo Personal channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/zalouser`<br />npm; ClawHub | channels: zalouser; contracts: tools |
|
||||
|
||||
## 僅限來源簽出
|
||||
## 僅限原始碼 checkout
|
||||
|
||||
| Plugin | 說明 | 發行方式 | 介面 |
|
||||
| ------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------ | -------------------- |
|
||||
| [qa-channel](/zh-TW/plugins/reference/qa-channel) | 新增 QA Channel 通道介面，用於傳送與接收 OpenClaw 訊息。 | `@openclaw/qa-channel`<br />source checkout only | channels: qa-channel |
|
||||
| [qa-lab](/zh-TW/plugins/reference/qa-lab) | OpenClaw QA lab Plugin，具備私有偵錯器 UI 與情境執行器。 | `@openclaw/qa-lab`<br />source checkout only | plugin |
|
||||
| [qa-matrix](/zh-TW/plugins/reference/qa-matrix) | Matrix QA 傳輸執行器與基底。 | `@openclaw/qa-matrix`<br />source checkout only | plugin |
|
||||
| Plugin | 說明 | 發佈 | 介面 |
|
||||
| ------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------ | -------------------- |
|
||||
| [qa-channel](/zh-TW/plugins/reference/qa-channel) | 新增 QA Channel surface，用於傳送和接收 OpenClaw 訊息。 | `@openclaw/qa-channel`<br />僅限原始碼 checkout | channels: qa-channel |
|
||||
| [qa-lab](/zh-TW/plugins/reference/qa-lab) | OpenClaw QA lab Plugin，具備私人除錯器 UI 與情境執行器。 | `@openclaw/qa-lab`<br />僅限原始碼 checkout | plugin |
|
||||
| [qa-matrix](/zh-TW/plugins/reference/qa-matrix) | Matrix QA 傳輸執行器與基底。 | `@openclaw/qa-matrix`<br />僅限原始碼 checkout | plugin |
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要從 Plugin 呼叫核心輔助函式（TTS、STT、影像生成、網頁搜尋、子代理、節點）
|
||||
- 您想了解 api.runtime 公開了哪些內容
|
||||
- 你正在從 Plugin 程式碼存取設定、代理程式或媒體輔助工具
|
||||
- 你需要從 Plugin 呼叫核心輔助函式（TTS、STT、影像生成、網路搜尋、子代理、節點）
|
||||
- 你想了解 api.runtime 公開了哪些內容
|
||||
- 您正在從 Plugin 程式碼存取設定、代理程式或媒體輔助工具
|
||||
sidebarTitle: Runtime helpers
|
||||
summary: api.runtime -- 可供 Plugin 使用的已注入執行階段輔助工具
|
||||
summary: api.runtime -- 可供 Plugin 使用的注入式執行階段輔助工具
|
||||
title: Plugin 執行階段輔助工具
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:01:51Z"
|
||||
generated_at: "2026-05-04T09:37:16Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c
|
||||
source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw 在註冊期間注入每個 Plugin 的 `api.runtime` 物件參考。請使用這些輔助工具，而不是直接匯入主機內部項目。
|
||||
`api.runtime` 物件的參考資料，該物件會在註冊期間注入到每個 Plugin 中。請使用這些輔助函式，而不是直接匯入主機內部項目。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="通道 Plugin" href="/zh-TW/plugins/sdk-channel-plugins">
|
||||
在通道 Plugin 的情境中使用這些輔助工具的逐步指南。
|
||||
<Card title="Channel plugins" href="/zh-TW/plugins/sdk-channel-plugins">
|
||||
逐步指南，示範在頻道 Plugin 的情境中使用這些輔助函式。
|
||||
</Card>
|
||||
<Card title="提供者 Plugin" href="/zh-TW/plugins/sdk-provider-plugins">
|
||||
在提供者 Plugin 的情境中使用這些輔助工具的逐步指南。
|
||||
<Card title="Provider plugins" href="/zh-TW/plugins/sdk-provider-plugins">
|
||||
逐步指南，示範在供應商 Plugin 的情境中使用這些輔助函式。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -34,32 +34,32 @@ register(api) {
|
||||
|
||||
## 設定載入與寫入
|
||||
|
||||
優先使用已傳入作用中呼叫路徑的設定，例如註冊期間的 `api.config`，或通道/提供者回呼上的 `cfg` 引數。這會讓單一處理程序快照在工作中流動，而不是在熱路徑上重新剖析設定。
|
||||
優先使用已經傳入作用中呼叫路徑的設定，例如註冊期間的 `api.config`，或頻道／供應商回呼中的 `cfg` 參數。這會讓單一程序快照在工作中流動，而不是在高頻路徑上重新解析設定。
|
||||
|
||||
只有當長期存在的處理常式需要目前的處理程序快照，且該函式未收到設定時，才使用 `api.runtime.config.current()`。傳回的值是唯讀；編輯前請先複製，或使用變更輔助工具。
|
||||
只有在長生命週期處理常式需要目前程序快照，而且該函式沒有收到設定時，才使用 `api.runtime.config.current()`。傳回值是唯讀的；編輯前請先複製，或使用變更輔助函式。
|
||||
|
||||
工具工廠會收到 `ctx.runtimeConfig` 加上 `ctx.getRuntimeConfig()`。當工具定義建立後設定仍可能變更時，請在長期存在工具的 `execute` 回呼中使用 getter。
|
||||
工具工廠會收到 `ctx.runtimeConfig` 加上 `ctx.getRuntimeConfig()`。如果設定可能在工具定義建立後變更，請在長生命週期工具的 `execute` 回呼內使用 getter。
|
||||
|
||||
使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 保存變更。每次寫入都必須選擇明確的 `afterWrite` 政策：
|
||||
使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化變更。每次寫入都必須選擇明確的 `afterWrite` 政策：
|
||||
|
||||
- `afterWrite: { mode: "auto" }` 讓 Gateway 重新載入規劃器決定。
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` 在寫入者知道熱重新載入不安全時，強制乾淨重新啟動。
|
||||
- `afterWrite: { mode: "none", reason: "..." }` 只有在呼叫者擁有後續處理時，才抑制自動重新載入/重新啟動。
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` 會在寫入方知道熱重新載入不安全時強制乾淨重新啟動。
|
||||
- `afterWrite: { mode: "none", reason: "..." }` 只有在呼叫方擁有後續處理時，才會抑制自動重新載入／重新啟動。
|
||||
|
||||
變更輔助工具會傳回 `afterWrite` 加上具型別的 `followUp` 摘要，讓呼叫者可以記錄或測試它們是否要求重新啟動。Gateway 仍負責決定實際何時重新啟動。
|
||||
變更輔助函式會傳回 `afterWrite` 加上具型別的 `followUp` 摘要，讓呼叫方可以記錄或測試是否要求重新啟動。Gateway 仍然負責決定該重新啟動實際發生的時機。
|
||||
|
||||
`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已棄用的相容性輔助工具。它們會在執行階段警告一次，並在遷移期間維持可供舊的外部 Plugin 使用。內建 Plugin 不得使用它們；如果 Plugin 程式碼呼叫它們，或從 Plugin SDK 子路徑匯入那些輔助工具，設定邊界防護就會失敗。
|
||||
`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 底下已棄用的相容性輔助函式。它們會在執行階段警告一次，並在遷移期間仍提供給舊的外部 Plugin 使用。內建 Plugin 不得使用它們；如果 Plugin 程式碼呼叫它們，或從 Plugin SDK 子路徑匯入這些輔助函式，設定邊界防護會失敗。
|
||||
|
||||
對於直接 SDK 匯入，請使用專注的設定子路徑，而不是寬泛的
|
||||
若要直接匯入 SDK，請使用聚焦的設定子路徑，而不是寬泛的
|
||||
`openclaw/plugin-sdk/config-runtime` 相容性 barrel：`config-types` 用於
|
||||
型別，`plugin-config-runtime` 用於已載入的設定斷言與 Plugin
|
||||
項目查找，`runtime-config-snapshot` 用於目前處理程序快照，以及
|
||||
`config-mutation` 用於寫入。內建 Plugin 測試應直接模擬這些專注
|
||||
子路徑，而不是模擬寬泛的相容性 barrel。
|
||||
型別，`plugin-config-runtime` 用於已載入設定斷言與 Plugin
|
||||
進入點查找，`runtime-config-snapshot` 用於目前程序快照，而
|
||||
`config-mutation` 用於寫入。內建 Plugin 測試應直接 mock 這些聚焦的
|
||||
子路徑，而不是 mock 寬泛的相容性 barrel。
|
||||
|
||||
內部 OpenClaw 執行階段程式碼也採用相同方向：在 CLI、Gateway 或處理程序邊界載入一次設定，然後傳遞該值。成功的變更寫入會重新整理處理程序執行階段快照，並推進其內部修訂版；長期存在的快取應以執行階段擁有的快取鍵為基礎，而不是在本機序列化設定。長期存在的執行階段模組對環境中的 `loadConfig()` 呼叫有零容忍掃描器；請使用傳入的 `cfg`、請求的 `context.getRuntimeConfig()`，或在明確的處理程序邊界使用 `getRuntimeConfig()`。
|
||||
內部 OpenClaw 執行階段程式碼也採用相同方向：在 CLI、Gateway 或程序邊界載入設定一次，然後將該值一路傳遞下去。成功的變更寫入會重新整理程序執行階段快照，並推進其內部修訂版；長生命週期快取應以執行階段擁有的快取鍵為基準，而不是在本機序列化設定。長生命週期執行階段模組對環境式 `loadConfig()` 呼叫有零容忍掃描器；請使用傳入的 `cfg`、請求的 `context.getRuntimeConfig()`，或在明確程序邊界使用 `getRuntimeConfig()`。
|
||||
|
||||
提供者與通道執行路徑必須使用作用中的執行階段設定快照，而不是為設定讀回或編輯傳回的檔案快照。檔案快照會保留來源值，例如供 UI 和寫入使用的 SecretRef 標記；提供者回呼需要已解析的執行階段視圖。當輔助工具可能以作用中來源快照或作用中執行階段快照呼叫時，請在讀取憑證前透過 `selectApplicableRuntimeConfig()` 路由。
|
||||
供應商與頻道執行路徑必須使用作用中的執行階段設定快照，而不是為設定讀回或編輯所傳回的檔案快照。檔案快照會保留 UI 和寫入所需的來源值，例如 SecretRef 標記；供應商回呼需要已解析的執行階段視圖。當輔助函式可能以作用中來源快照或作用中執行階段快照呼叫時，請在讀取憑證前透過 `selectApplicableRuntimeConfig()` 路由。
|
||||
|
||||
## 執行階段命名空間
|
||||
|
||||
@ -109,15 +109,15 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` 是從 Plugin 程式碼啟動一般 OpenClaw agent 回合的中性輔助工具。它使用與通道觸發回覆相同的提供者/模型解析與 agent-harness 選擇。
|
||||
`runEmbeddedAgent(...)` 是從 Plugin 程式碼啟動一般 OpenClaw Agent 回合的中立輔助函式。它使用與頻道觸發回覆相同的供應商／模型解析與 Agent harness 選取。
|
||||
|
||||
`runEmbeddedPiAgent(...)` 會作為相容性別名保留。
|
||||
`runEmbeddedPiAgent(...)` 仍作為相容性別名保留。
|
||||
|
||||
`resolveThinkingPolicy(...)` 會傳回提供者/模型支援的 thinking level，以及選擇性的預設值。提供者 Plugin 透過其 thinking hooks 擁有模型特定設定檔，因此工具 Plugin 應呼叫這個執行階段輔助工具，而不是匯入或複製提供者清單。
|
||||
`resolveThinkingPolicy(...)` 會傳回供應商／模型支援的思考層級與選用預設值。供應商 Plugin 透過其思考 hook 擁有模型特定設定檔，因此工具 Plugin 應呼叫此執行階段輔助函式，而不是匯入或複製供應商清單。
|
||||
|
||||
`normalizeThinkingLevel(...)` 會先將使用者文字（例如 `on`、`x-high` 或 `extra high`）轉換為標準儲存等級，再依照解析出的政策檢查它。
|
||||
`normalizeThinkingLevel(...)` 會將使用者文字，例如 `on`、`x-high` 或 `extra high`，轉換為標準儲存層級，再與已解析的政策比對。
|
||||
|
||||
**工作階段儲存輔助工具** 位於 `api.runtime.agent.session` 之下：
|
||||
**工作階段儲存輔助函式** 位於 `api.runtime.agent.session` 底下：
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -133,7 +133,7 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.agent.defaults">
|
||||
預設模型與提供者常數：
|
||||
預設模型與供應商常數：
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
@ -170,14 +170,14 @@ register(api) {
|
||||
```
|
||||
|
||||
<Warning>
|
||||
模型覆寫（`provider`/`model`）需要操作者透過設定中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 選擇加入。不受信任的 Plugin 仍可執行 subagent，但覆寫要求會遭到拒絕。
|
||||
模型覆寫（`provider`/`model`）需要操作者透過設定中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 選擇啟用。不受信任的 Plugin 仍可執行 subagent，但覆寫要求會被拒絕。
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` 可以刪除同一 Plugin 透過 `api.runtime.subagent.run(...)` 建立的工作階段。刪除任意使用者或操作者工作階段仍需要具管理員範圍的 Gateway 請求。
|
||||
`deleteSession(...)` 可以刪除同一 Plugin 透過 `api.runtime.subagent.run(...)` 建立的工作階段。刪除任意使用者或操作者工作階段仍需要具管理員範圍的 Gateway 要求。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
從 Gateway 載入的 Plugin 程式碼或 Plugin CLI 命令列出已連線的 Node，並呼叫 Node 主機命令。當 Plugin 擁有已配對裝置上的本機工作時使用此項，例如另一台 Mac 上的瀏覽器或音訊橋接器。
|
||||
列出已連線的節點，並從 Gateway 載入的 Plugin 程式碼或 Plugin CLI 命令叫用節點主機命令。當 Plugin 擁有已配對裝置上的本機工作時，例如另一台 Mac 上的瀏覽器或音訊橋接器，請使用此項。
|
||||
|
||||
```typescript
|
||||
const { nodes } = await api.runtime.nodes.list({ connected: true });
|
||||
@ -190,13 +190,13 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
在 Gateway 內，這個執行階段是處理程序內的。在 Plugin CLI 命令中，它會透過 RPC 呼叫已設定的 Gateway，因此像 `openclaw googlemeet recover-tab` 這類命令可以從終端機檢查已配對的 Node。Node 命令仍會經過一般 Gateway Node 配對、命令允許清單、Plugin Node 呼叫政策，以及 Node 本機命令處理。
|
||||
在 Gateway 內，此執行階段是程序內的。在 Plugin CLI 命令中，它會透過 RPC 呼叫已設定的 Gateway，因此像 `openclaw googlemeet recover-tab` 這類命令可以從終端機檢查已配對的節點。Node 命令仍會通過一般 Gateway 節點配對、命令允許清單、Plugin 節點叫用政策，以及節點本機命令處理。
|
||||
|
||||
暴露危險 Node 主機命令的 Plugin 應使用 `api.registerNodeInvokePolicy(...)` 註冊 Node 呼叫政策。該政策會在 Gateway 中於命令允許清單檢查之後、命令轉送至 Node 之前執行，因此直接 `node.invoke` 呼叫和較高階的 Plugin 工具會共用相同的強制執行路徑。
|
||||
暴露危險節點主機命令的 Plugin 應使用 `api.registerNodeInvokePolicy(...)` 註冊節點叫用政策。該政策會在 Gateway 中於命令允許清單檢查之後、命令轉送至節點之前執行，因此直接 `node.invoke` 呼叫與較高階的 Plugin 工具會共用相同的強制執行路徑。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tasks.managedFlows">
|
||||
將 TaskFlow 執行階段繫結至現有的 OpenClaw 工作階段鍵或受信任工具情境，然後建立並管理 TaskFlow，而無需在每次呼叫時傳遞擁有者。
|
||||
將 Task Flow 執行階段繫結至既有 OpenClaw 工作階段鍵或受信任工具內容，然後建立並管理 Task Flows，而不需要在每次呼叫時傳入擁有者。
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
|
||||
@ -223,7 +223,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
當你已從自己的繫結層取得受信任的 OpenClaw 工作階段鍵時，請使用 `bindSession({ sessionKey, requesterOrigin })`。不要從原始使用者輸入進行繫結。
|
||||
當你已經從自己的繫結層取得受信任的 OpenClaw 工作階段鍵時，請使用 `bindSession({ sessionKey, requesterOrigin })`。不要從原始使用者輸入進行繫結。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
@ -249,7 +249,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
使用核心 `messages.tts` 設定與提供者選擇。傳回 PCM 音訊緩衝區 + 取樣率。
|
||||
使用核心 `messages.tts` 設定與供應商選取。傳回 PCM 音訊緩衝區加上取樣率。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.mediaUnderstanding">
|
||||
@ -286,7 +286,7 @@ register(api) {
|
||||
未產生輸出時會傳回 `{ text: undefined }`（例如略過的輸入）。
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍保留為 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的相容性別名。
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍是 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的相容性別名。
|
||||
</Info>
|
||||
|
||||
</Accordion>
|
||||
@ -342,7 +342,7 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.config">
|
||||
目前的執行階段設定快照與交易式設定寫入。優先使用已傳入作用中呼叫路徑的設定；只有在處理常式需要直接取得程序快照時，才使用 `current()`。
|
||||
目前的執行階段設定快照與交易式設定寫入。優先使用已傳入有效呼叫路徑的設定；只有在處理常式需要直接取得程序快照時，才使用 `current()`。
|
||||
|
||||
```typescript
|
||||
const cfg = api.runtime.config.current();
|
||||
@ -354,9 +354,7 @@ register(api) {
|
||||
});
|
||||
```
|
||||
|
||||
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 會傳回 `followUp`
|
||||
值，例如 `{ mode: "restart", requiresRestart: true, reason }`，
|
||||
這會記錄寫入者的意圖，而不會從 gateway 接管重新啟動控制。
|
||||
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 會傳回 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，用來記錄寫入者意圖，而不會從 Gateway 取走重新啟動控制權。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.system">
|
||||
@ -410,7 +408,7 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.state">
|
||||
狀態目錄解析與 SQLite 支援的鍵控儲存。
|
||||
狀態目錄解析與 SQLite 支援的鍵值儲存。
|
||||
|
||||
```typescript
|
||||
const stateDir = api.runtime.state.resolveStateDir(process.env);
|
||||
@ -421,12 +419,13 @@ register(api) {
|
||||
});
|
||||
|
||||
await store.register("key-1", { value: "hello" });
|
||||
const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });
|
||||
const value = await store.lookup("key-1");
|
||||
await store.consume("key-1");
|
||||
await store.clear();
|
||||
```
|
||||
|
||||
鍵控儲存會在重新啟動後保留，並依執行階段繫結的 Plugin id 隔離。限制：每個命名空間 `maxEntries`、每個 Plugin 1,000 筆即時資料列、64KB 以下的 JSON 值，以及選用的 TTL 到期。
|
||||
鍵值儲存會在重新啟動後保留，並依執行階段繫結的 Plugin ID 隔離。使用 `registerIfAbsent(...)` 進行原子去重宣告：當鍵不存在或已過期且已註冊時會傳回 `true`；當即時值已存在，且不覆寫其值、建立時間或 TTL 時會傳回 `false`。限制：每個命名空間的 `maxEntries`、每個 Plugin 1,000 個即時資料列、低於 64KB 的 JSON 值，以及選用的 TTL 到期。
|
||||
|
||||
<Warning>
|
||||
此版本僅限內建 Plugin。
|
||||
@ -434,7 +433,7 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tools">
|
||||
Memory 工具工廠與 CLI。
|
||||
記憶體工具工廠與 CLI。
|
||||
|
||||
```typescript
|
||||
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
|
||||
@ -444,9 +443,9 @@ register(api) {
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
通道專用執行階段輔助工具（載入通道 Plugin 時可用）。
|
||||
通道專屬的執行階段輔助工具（在載入通道 Plugin 時可用）。
|
||||
|
||||
`api.runtime.channel.mentions` 是使用執行階段注入的內建通道 Plugin 共享的入站提及政策介面：
|
||||
`api.runtime.channel.mentions` 是使用執行階段注入的內建通道 Plugin 的共用傳入提及原則介面：
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -481,7 +480,7 @@ register(api) {
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` 有意不公開較舊的 `resolveMentionGating*` 相容性輔助工具。請優先使用標準化的 `{ facts, policy }` 路徑。
|
||||
`api.runtime.channel.mentions` 刻意不公開較舊的 `resolveMentionGating*` 相容性輔助工具。請優先使用標準化的 `{ facts, policy }` 路徑。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -491,7 +490,7 @@ register(api) {
|
||||
使用 `createPluginRuntimeStore` 儲存執行階段參照，以便在 `register` 回呼之外使用：
|
||||
|
||||
<Steps>
|
||||
<Step title="建立儲存區">
|
||||
<Step title="建立儲存">
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -529,7 +528,7 @@ register(api) {
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
執行階段儲存的識別請優先使用 `pluginId`。較低階的 `key` 形式適用於少見情況，也就是同一個 Plugin 有意需要多個執行階段槽位。
|
||||
執行階段儲存識別建議使用 `pluginId`。較低階的 `key` 形式適用於少見情況：某個 Plugin 有意需要多個執行階段槽位。
|
||||
</Note>
|
||||
|
||||
## 其他頂層 `api` 欄位
|
||||
@ -537,29 +536,29 @@ register(api) {
|
||||
除了 `api.runtime` 之外，API 物件也提供：
|
||||
|
||||
<ParamField path="api.id" type="string">
|
||||
Plugin id。
|
||||
Plugin ID。
|
||||
</ParamField>
|
||||
<ParamField path="api.name" type="string">
|
||||
Plugin 顯示名稱。
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
目前的設定快照（可用時為作用中的記憶體內執行階段快照）。
|
||||
目前設定快照（可用時為有效的記憶體內執行階段快照）。
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
來自 `plugins.entries.<id>.config` 的 Plugin 專用設定。
|
||||
來自 `plugins.entries.<id>.config` 的 Plugin 專屬設定。
|
||||
</ParamField>
|
||||
<ParamField path="api.logger" type="PluginLogger">
|
||||
具範圍的記錄器（`debug`、`info`、`warn`、`error`）。
|
||||
範圍限定記錄器（`debug`、`info`、`warn`、`error`）。
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
目前的載入模式；`"setup-runtime"` 是完整進入點啟動前的輕量啟動／設定窗口。
|
||||
目前載入模式；`"setup-runtime"` 是輕量的完整進入點前啟動／設定視窗。
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
解析相對於 Plugin 根目錄的路徑。
|
||||
</ParamField>
|
||||
|
||||
## 相關內容
|
||||
## 相關
|
||||
|
||||
- [Plugin 內部機制](/zh-TW/plugins/architecture) — 能力模型與登錄檔
|
||||
- [SDK 進入點](/zh-TW/plugins/sdk-entrypoints) — `definePluginEntry` 選項
|
||||
- [SDK 概觀](/zh-TW/plugins/sdk-overview) — 子路徑參考
|
||||
- [SDK 概覽](/zh-TW/plugins/sdk-overview) — 子路徑參考
|
||||
|
||||
@ -1,35 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- 偵錯代理程式為何如此回答、失敗或以特定方式呼叫工具
|
||||
- 偵錯代理為何以特定方式回答、失敗或呼叫工具
|
||||
- 匯出 OpenClaw 工作階段的支援套件
|
||||
- 調查提示詞上下文、工具呼叫、執行階段錯誤或用量中繼資料
|
||||
- 停用或重新定位軌跡擷取
|
||||
summary: 匯出經過遮蔽的軌跡套件，用於偵錯 OpenClaw 代理程式工作階段
|
||||
- 調查提示詞上下文、工具呼叫、執行階段錯誤或使用量中繼資料
|
||||
- 停用或變更軌跡擷取位置
|
||||
summary: 匯出已遮蔽敏感資訊的軌跡套件，以便偵錯 OpenClaw 代理程式工作階段
|
||||
title: 軌跡套件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T03:48:24Z"
|
||||
generated_at: "2026-05-04T09:37:19Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8dad01b3662d5e75b7626eb7ed3c3ac2dce4e3a7db2ba5952d7086c721151d1f
|
||||
source_hash: b8b1256e52d27185a48ceddaf7937b4f37ad6d57d075fea0d0b6d3abb871f1d8
|
||||
source_path: tools/trajectory.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Trajectory capture 是 OpenClaw 的每工作階段飛行記錄器。它會為每次 agent 執行記錄結構化時間軸，接著 `/export-trajectory` 會將目前工作階段封裝成已遮蔽的支援套件。
|
||||
Trajectory capture 是 OpenClaw 針對每個工作階段的飛行記錄器。它會為每次代理程式執行記錄結構化時間軸，然後 `/export-trajectory` 會將目前工作階段封裝成已遮蔽敏感資訊的支援套件。
|
||||
|
||||
當你需要回答下列問題時，請使用它：
|
||||
當你需要回答以下問題時使用它：
|
||||
|
||||
- 傳送給模型的是什麼提示、系統提示和工具？
|
||||
- 哪些提示、系統提示與工具已傳送給模型？
|
||||
- 哪些逐字稿訊息與工具呼叫導致了這個答案？
|
||||
- 這次執行是否逾時、中止、進行 Compaction，或遇到供應商錯誤？
|
||||
- 哪個模型、plugins、Skills 和執行階段設定處於作用中？
|
||||
- 供應商回傳了哪些使用量與提示快取中繼資料？
|
||||
- 哪個模型、plugins、Skills 與執行階段設定處於啟用狀態？
|
||||
- 供應商傳回了哪些用量與提示快取中繼資料？
|
||||
|
||||
如果你要針對即時 Gateway 問題提交廣泛的支援報告，請從 [`/diagnostics`](/zh-TW/gateway/diagnostics#chat-command) 開始。Diagnostics 會收集已清理的 Gateway 套件，並且對於 OpenAI Codex harness 工作階段，也可以在核准後將 Codex 意見回饋傳送到 OpenAI 伺服器。當你特別需要每個工作階段的詳細提示、工具和逐字稿時間軸時，請使用 `/export-trajectory`。
|
||||
如果你要針對即時 Gateway 問題提交廣泛的支援報告，請從
|
||||
[`/diagnostics`](/zh-TW/gateway/diagnostics#chat-command) 開始。Diagnostics 會收集
|
||||
已清理的 Gateway 套件，而且對於 OpenAI Codex harness 工作階段，在核准後也可以將
|
||||
Codex 回饋傳送到 OpenAI 伺服器。當你特別需要詳細的每個工作階段提示、工具與逐字稿
|
||||
時間軸時，請使用 `/export-trajectory`。
|
||||
|
||||
## 快速開始
|
||||
|
||||
在作用中的工作階段中傳送：
|
||||
在作用中的工作階段傳送：
|
||||
|
||||
```text
|
||||
/export-trajectory
|
||||
@ -41,7 +45,7 @@ Trajectory capture 是 OpenClaw 的每工作階段飛行記錄器。它會為每
|
||||
/trajectory
|
||||
```
|
||||
|
||||
OpenClaw 會將套件寫入工作區下方：
|
||||
OpenClaw 會將套件寫入工作區底下：
|
||||
|
||||
```text
|
||||
.openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/
|
||||
@ -53,31 +57,38 @@ OpenClaw 會將套件寫入工作區下方：
|
||||
/export-trajectory bug-1234
|
||||
```
|
||||
|
||||
自訂路徑會在 `.openclaw/trajectory-exports/` 內解析。絕對路徑與 `~` 路徑會被拒絕。
|
||||
自訂路徑會在 `.openclaw/trajectory-exports/` 內解析。絕對
|
||||
路徑與 `~` 路徑會被拒絕。
|
||||
|
||||
Trajectory 套件可能包含提示、模型訊息、工具結構描述、工具結果、執行階段事件和本機路徑。因此，聊天斜線命令每次都會經過 exec 核准。當你打算建立套件時，只核准該次匯出；不要使用 allow-all。在群組聊天中，OpenClaw 會將核准提示與匯出結果私下傳送給擁有者，而不是把 trajectory 詳細資料發回共享聊天室。
|
||||
Trajectory 套件可能包含提示、模型訊息、工具結構描述、工具
|
||||
結果、執行階段事件與本機路徑。因此聊天斜線指令每次都會
|
||||
經過 exec 核准。當你打算建立套件時，核准該匯出一次；不要使用 allow-all。在群組聊天中，OpenClaw 會將
|
||||
核准提示與匯出結果私下傳送給擁有者，而不是將
|
||||
Trajectory 詳細資訊貼回共享聊天室。
|
||||
|
||||
若要進行本機檢查或支援工作流程，你也可以直接執行已核准的命令路徑：
|
||||
對於本機檢查或支援工作流程，你也可以直接執行已核准的指令
|
||||
路徑：
|
||||
|
||||
```bash
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
|
||||
```
|
||||
|
||||
## 存取權
|
||||
## 存取權限
|
||||
|
||||
Trajectory 匯出是擁有者命令。傳送者必須通過該頻道的一般命令授權檢查和擁有者檢查。
|
||||
Trajectory export 是擁有者指令。傳送者必須通過該頻道的正常指令
|
||||
授權檢查與擁有者檢查。
|
||||
|
||||
## 記錄內容
|
||||
## 會記錄的內容
|
||||
|
||||
OpenClaw agent 執行預設會啟用 Trajectory capture。
|
||||
OpenClaw 代理程式執行預設會啟用 Trajectory capture。
|
||||
|
||||
執行階段事件包括：
|
||||
執行階段事件包含：
|
||||
|
||||
- `session.started`
|
||||
- `trace.metadata`
|
||||
- `context.compiled`
|
||||
- `prompt.submitted`
|
||||
- `model.fallback_step`，包括來源模型、下一個模型、失敗原因/詳細資料、鏈結位置，以及 fallback 是否前進、成功或耗盡鏈結
|
||||
- `model.fallback_step`，包含來源模型、下一個模型、失敗原因/詳細資訊、鏈中位置，以及 fallback 是否推進、成功或耗盡鏈
|
||||
- `model.completed`
|
||||
- `trace.artifacts`
|
||||
- `session.ended`
|
||||
@ -85,7 +96,7 @@ OpenClaw agent 執行預設會啟用 Trajectory capture。
|
||||
逐字稿事件也會從作用中的工作階段分支重建：
|
||||
|
||||
- 使用者訊息
|
||||
- assistant 訊息
|
||||
- 助理訊息
|
||||
- 工具呼叫
|
||||
- 工具結果
|
||||
- Compaction
|
||||
@ -107,20 +118,21 @@ OpenClaw agent 執行預設會啟用 Trajectory capture。
|
||||
|
||||
| 檔案 | 內容 |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `manifest.json` | 套件結構描述、來源檔案、事件計數和產生的檔案清單 |
|
||||
| `manifest.json` | 套件結構描述、來源檔案、事件計數與產生的檔案清單 |
|
||||
| `events.jsonl` | 已排序的執行階段與逐字稿時間軸 |
|
||||
| `session-branch.json` | 已遮蔽的作用中逐字稿分支和工作階段標頭 |
|
||||
| `metadata.json` | OpenClaw 版本、OS/執行階段、模型、設定快照、plugins、Skills 和提示中繼資料 |
|
||||
| `artifacts.json` | 最終狀態、錯誤、使用量、提示快取、Compaction 計數、assistant 文字和工具中繼資料 |
|
||||
| `prompts.json` | 已提交的提示和選定的提示建構詳細資料 |
|
||||
| `system-prompt.txt` | 已擷取時的最新已編譯系統提示 |
|
||||
| `tools.json` | 已擷取時傳送給模型的工具定義 |
|
||||
| `session-branch.json` | 已遮蔽敏感資訊的作用中逐字稿分支與工作階段標頭 |
|
||||
| `metadata.json` | OpenClaw 版本、作業系統/執行階段、模型、設定快照、plugins、Skills 與提示中繼資料 |
|
||||
| `artifacts.json` | 最終狀態、錯誤、用量、提示快取、Compaction 計數、助理文字與工具中繼資料 |
|
||||
| `prompts.json` | 已提交的提示與選定的提示建構詳細資訊 |
|
||||
| `system-prompt.txt` | 最新編譯的系統提示（若已擷取） |
|
||||
| `tools.json` | 傳送給模型的工具定義（若已擷取） |
|
||||
|
||||
`manifest.json` 會列出該套件中存在的檔案。當工作階段未擷取對應的執行階段資料時，部分檔案會被省略。
|
||||
`manifest.json` 會列出該套件中存在的檔案。有些檔案會在
|
||||
工作階段未擷取對應的執行階段資料時省略。
|
||||
|
||||
## 擷取位置
|
||||
|
||||
預設情況下，執行階段 trajectory 事件會寫在工作階段檔案旁邊：
|
||||
預設情況下，執行階段 Trajectory 事件會寫在工作階段檔案旁邊：
|
||||
|
||||
```text
|
||||
<session>.trajectory.jsonl
|
||||
@ -132,65 +144,73 @@ OpenClaw 也會在工作階段旁邊寫入一個盡力而為的指標檔案：
|
||||
<session>.trajectory-path.json
|
||||
```
|
||||
|
||||
設定 `OPENCLAW_TRAJECTORY_DIR`，將執行階段 trajectory sidecar 儲存在專用目錄：
|
||||
設定 `OPENCLAW_TRAJECTORY_DIR`，即可將執行階段 Trajectory sidecar 儲存在
|
||||
專用目錄中：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories
|
||||
```
|
||||
|
||||
設定此變數時，OpenClaw 會在該目錄中為每個工作階段 ID 寫入一個 JSONL 檔案。
|
||||
設定此變數時，OpenClaw 會針對該目錄中的每個工作階段 ID 寫入一個 JSONL 檔案。
|
||||
|
||||
當擁有 trajectory sidecar 的工作階段項目因工作階段磁碟預算而遭到修剪、封頂或逐出時，工作階段維護會移除這些 sidecar。工作階段目錄外的執行階段檔案，只有在指標目標仍可證明它屬於該工作階段時才會被移除。
|
||||
工作階段維護會在其擁有的工作階段項目因工作階段磁碟預算而被
|
||||
剪除、封頂或逐出時，移除 Trajectory sidecar。只有當指標目標仍能證明它
|
||||
屬於該工作階段時，才會移除工作階段目錄外的執行階段檔案。
|
||||
|
||||
## 停用擷取
|
||||
|
||||
啟動 OpenClaw 前設定 `OPENCLAW_TRAJECTORY=0`：
|
||||
在啟動 OpenClaw 前設定 `OPENCLAW_TRAJECTORY=0`：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_TRAJECTORY=0
|
||||
```
|
||||
|
||||
這會停用執行階段 trajectory 擷取。`/export-trajectory` 仍然可以匯出逐字稿分支，但可能會缺少僅存在於執行階段的檔案，例如已編譯內容、供應商 artifacts 和提示中繼資料。
|
||||
這會停用執行階段 Trajectory capture。`/export-trajectory` 仍然可以匯出
|
||||
逐字稿分支，但僅限執行階段的檔案，例如已編譯的內容、
|
||||
供應商成品與提示中繼資料，可能會遺失。
|
||||
|
||||
## 隱私與限制
|
||||
|
||||
Trajectory 套件是為支援與除錯而設計，不適合公開張貼。OpenClaw 在寫入匯出檔案前會遮蔽敏感值：
|
||||
Trajectory 套件是為支援與偵錯而設計，不適合公開張貼。
|
||||
OpenClaw 會在寫入匯出檔案前遮蔽敏感值：
|
||||
|
||||
- 憑證與已知類似秘密的 payload 欄位
|
||||
- 圖片資料
|
||||
- 憑證與已知類似秘密的承載欄位
|
||||
- 圖像資料
|
||||
- 本機狀態路徑
|
||||
- 工作區路徑，替換為 `$WORKSPACE_DIR`
|
||||
- 偵測到的主目錄路徑
|
||||
- 工作區路徑，會取代為 `$WORKSPACE_DIR`
|
||||
- 主目錄路徑（偵測到時）
|
||||
|
||||
匯出器也會限制輸入大小：
|
||||
匯出工具也會限制輸入大小：
|
||||
|
||||
- 執行階段 sidecar 檔案：50 MiB
|
||||
- 執行階段 sidecar 檔案：即時擷取會在 10 MiB 停止，並在仍有空間時記錄截斷事件；匯出會接受最多 50 MiB 的既有執行階段 sidecar
|
||||
- 工作階段檔案：50 MiB
|
||||
- 執行階段事件：200,000
|
||||
- 匯出的事件總數：250,000
|
||||
- 匯出事件總數：250,000
|
||||
- 個別執行階段事件行超過 256 KiB 時會被截斷
|
||||
|
||||
在團隊外分享套件前，請先檢閱內容。遮蔽是盡力而為，無法知道每個應用程式特定的秘密。
|
||||
在團隊外分享套件前，請先檢閱。遮蔽敏感資訊是盡力而為，
|
||||
無法知道每一種應用程式特定的秘密。
|
||||
|
||||
## 疑難排解
|
||||
|
||||
如果匯出沒有執行階段事件：
|
||||
|
||||
- 確認 OpenClaw 啟動時沒有設定 `OPENCLAW_TRAJECTORY=0`
|
||||
- 確認 OpenClaw 啟動時未設定 `OPENCLAW_TRAJECTORY=0`
|
||||
- 檢查 `OPENCLAW_TRAJECTORY_DIR` 是否指向可寫入的目錄
|
||||
- 在工作階段中再執行一則訊息，然後重新匯出
|
||||
- 檢查 `manifest.json` 中的 `runtimeEventCount`
|
||||
|
||||
如果命令拒絕輸出路徑：
|
||||
如果指令拒絕輸出路徑：
|
||||
|
||||
- 使用像 `bug-1234` 這樣的相對名稱
|
||||
- 不要傳入 `/tmp/...` 或 `~/...`
|
||||
- 將匯出保留在 `.openclaw/trajectory-exports/` 內
|
||||
- 將匯出保持在 `.openclaw/trajectory-exports/` 內
|
||||
|
||||
如果匯出因大小錯誤而失敗，表示工作階段或 sidecar 超過匯出安全限制。請開始新的工作階段，或匯出較小的重現案例。
|
||||
如果匯出因大小錯誤而失敗，代表工作階段或 sidecar 超過了
|
||||
匯出安全限制。請開始新的工作階段，或匯出較小的重現案例。
|
||||
|
||||
## 相關
|
||||
|
||||
- [Diffs](/zh-TW/tools/diffs)
|
||||
- [工作階段管理](/zh-TW/concepts/session)
|
||||
- [Exec tool](/zh-TW/tools/exec)
|
||||
- [Exec 工具](/zh-TW/tools/exec)
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- 您想從瀏覽器操作 Gateway
|
||||
- 你想從瀏覽器操作 Gateway
|
||||
- 你想要無需 SSH 通道即可存取 Tailnet
|
||||
sidebarTitle: Control UI
|
||||
summary: 以瀏覽器為基礎的 Gateway 控制 UI（聊天、節點、設定）
|
||||
summary: 以瀏覽器為基礎的 Gateway 控制介面（聊天、節點、設定）
|
||||
title: 控制介面
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:06:16Z"
|
||||
generated_at: "2026-05-04T09:37:55Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Control UI 是由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程式：
|
||||
控制介面是一個由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程式：
|
||||
|
||||
- 預設：`http://<host>:18789/`
|
||||
- 選用前置路徑：設定 `gateway.controlUi.basePath`（例如 `/openclaw`）
|
||||
|
||||
它會在相同連接埠上**直接與 Gateway WebSocket** 通訊。
|
||||
它會在同一個連接埠上**直接與 Gateway WebSocket** 通訊。
|
||||
|
||||
## 快速開啟（本機）
|
||||
|
||||
@ -29,20 +29,20 @@ 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 的權杖；密碼不會被持久保存。首次連線時，入門設定通常會為共享密鑰驗證產生 Gateway 權杖，但當 `gateway.auth.mode` 為 `"password"` 時，密碼驗證也可使用。
|
||||
|
||||
## 裝置配對（首次連線）
|
||||
|
||||
當你從新的瀏覽器或裝置連線到 Control UI 時，Gateway 通常會要求**一次性配對核准**。這是一項安全措施，用於防止未授權存取。
|
||||
當你從新的瀏覽器或裝置連線到控制介面時，Gateway 通常需要**一次性配對核准**。這是一項防止未經授權存取的安全措施。
|
||||
|
||||
**你會看到的內容：**「disconnected (1008): pairing required」
|
||||
**你會看到：**「已中斷連線 (1008)：需要配對」
|
||||
|
||||
<Steps>
|
||||
<Step title="列出待處理要求">
|
||||
@ -57,96 +57,97 @@ Control UI 是由 Gateway 提供服務的小型 **Vite + Lit** 單頁應用程
|
||||
</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) 了解權杖輪替與撤銷。
|
||||
|
||||
<Note>
|
||||
- 直接 local loopback 瀏覽器連線（`127.0.0.1` / `localhost`）會自動核准。
|
||||
- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分通過驗證，且瀏覽器提供其裝置身分時，Tailscale Serve 可略過 Control UI 操作者工作階段的配對往返流程。
|
||||
- 當 `gateway.auth.allowTailscale: true`、Tailscale 身分驗證通過，且瀏覽器提供其裝置身分時，Tailscale Serve 可略過控制介面操作者工作階段的配對往返。
|
||||
- 直接 Tailnet 繫結、LAN 瀏覽器連線，以及沒有裝置身分的瀏覽器設定檔仍需要明確核准。
|
||||
- 每個瀏覽器設定檔都會產生唯一裝置 ID，因此切換瀏覽器或清除瀏覽器資料將需要重新配對。
|
||||
- 每個瀏覽器設定檔都會產生唯一的裝置 ID，因此切換瀏覽器或清除瀏覽器資料都需要重新配對。
|
||||
|
||||
</Note>
|
||||
|
||||
## 個人身分（瀏覽器本機）
|
||||
|
||||
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 身分。
|
||||
控制介面會從 `/__openclaw/control-ui-config.json` 擷取其執行階段設定。該端點受到與其餘 HTTP 介面相同的 Gateway 驗證保護：未驗證的瀏覽器無法擷取它，而成功擷取需要已有效的 Gateway 權杖/密碼、Tailscale Serve 身分，或受信任 Proxy 身分。
|
||||
|
||||
## 語言支援
|
||||
|
||||
Control UI 可在首次載入時根據你的瀏覽器語系自行本地化。若要稍後覆寫，請開啟 **概覽 -> Gateway 存取 -> 語言**。語系選擇器位於 Gateway 存取卡片中，而不是外觀之下。
|
||||
控制介面可在首次載入時根據你的瀏覽器語言環境進行本地化。若要稍後覆寫，請開啟**概覽 -> Gateway 存取 -> 語言**。語言環境選擇器位於 Gateway 存取卡片中，而不是外觀底下。
|
||||
|
||||
- 支援的語系：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`ar`、`it`、`tr`、`uk`、`id`、`pl`、`th`、`vi`、`nl`、`fa`
|
||||
- 支援的語言環境：`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`）文件仍會在發布儲存庫中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。
|
||||
|
||||
## 外觀主題
|
||||
|
||||
外觀面板保留內建的 Claw、Knot 和 Dash 主題，另加一個瀏覽器本機 tweakcn 匯入槽。若要匯入主題，請開啟 [tweakcn 編輯器](https://tweakcn.com/editor/theme)，選擇或建立主題，點擊 **分享**，並將複製的主題連結貼到外觀中。匯入器也接受 `https://tweakcn.com/r/themes/<id>` 登錄 URL、如 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的編輯器 URL、相對 `/themes/<id>` 路徑、原始主題 ID，以及如 `amethyst-haze` 的預設主題名稱。
|
||||
外觀面板保留內建的 Claw、Knot 和 Dash 主題，另外還有一個瀏覽器本機的 tweakcn 匯入槽。若要匯入主題，請開啟 [tweakcn 編輯器](https://tweakcn.com/editor/theme)，選擇或建立主題，按一下**分享**，並將複製的主題連結貼到外觀中。匯入器也接受 `https://tweakcn.com/r/themes/<id>` 登錄 URL、像 `https://tweakcn.com/editor/theme?theme=amethyst-haze` 的編輯器 URL、相對 `/themes/<id>` 路徑、原始主題 ID，以及 `amethyst-haze` 等預設主題名稱。
|
||||
|
||||
匯入的主題只會儲存在目前瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。取代匯入的主題會更新唯一的本機槽；若匯入的主題已被選取，清除它會將目前主題切回 Claw。
|
||||
匯入的主題只會儲存在目前的瀏覽器設定檔中。它們不會寫入 Gateway 設定，也不會跨裝置同步。取代匯入的主題會更新那個本機槽；如果匯入的主題已被選取，清除它會將作用中主題切回 Claw。
|
||||
|
||||
## 它可以做什麼（目前）
|
||||
## 它能做什麼（目前）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="聊天與語音交談">
|
||||
- 透過 Gateway WS 與模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。
|
||||
- 透過瀏覽器即時工作階段進行語音交談。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限制的一次性瀏覽器 token，而僅後端即時語音 Plugin 使用 Gateway 中繼傳輸。中繼會將供應商憑證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並透過 `chat.send` 將 `openclaw_agent_consult` 工具呼叫送回給較大型的已設定 OpenClaw 模型。
|
||||
- 透過 Gateway WS 與模型聊天（`chat.history`, `chat.send`, `chat.abort`, `chat.inject`）。
|
||||
- 透過瀏覽器即時工作階段進行語音交談。OpenAI 使用直接 WebRTC，Google Live 透過 WebSocket 使用受限的一次性瀏覽器權杖，而僅後端的即時語音 Plugin 會使用 Gateway 轉送傳輸。轉送會將提供者認證保留在 Gateway 上，同時瀏覽器透過 `talk.realtime.relay*` RPC 串流麥克風 PCM，並透過 `chat.send` 將 `openclaw_agent_consult` 工具呼叫傳回較大的已設定 OpenClaw 模型。
|
||||
- 在聊天中串流工具呼叫與即時工具輸出卡片（代理事件）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="頻道、執行個體、工作階段、夢境">
|
||||
- 頻道：內建加上隨附/外部 Plugin 頻道狀態、QR 登入，以及每個頻道設定（`channels.status`、`web.login.*`、`config.patch`）。
|
||||
- 頻道：內建以及隨附/外部 Plugin 頻道狀態、QR 登入，以及每個頻道的設定（`channels.status`, `web.login.*`, `config.patch`）。
|
||||
- 執行個體：存在清單 + 重新整理（`system-presence`）。
|
||||
- 工作階段：清單 + 每個工作階段的模型/思考/快速/詳細/追蹤/推理覆寫（`sessions.list`、`sessions.patch`）。
|
||||
- 夢境：Dreaming 狀態、啟用/停用切換，以及夢境日記讀取器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
|
||||
- 工作階段：清單 + 每個工作階段的模型/思考/快速/詳細/追蹤/推理覆寫（`sessions.list`, `sessions.patch`）。
|
||||
- 夢境：Dreaming 狀態、啟用/停用切換，以及 Dream Diary 讀取器（`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron、Skills、Node、執行核准">
|
||||
- Cron 作業：列出/新增/編輯/執行/啟用/停用 + 執行記錄（`cron.*`）。
|
||||
- Cron 作業：列出/新增/編輯/執行/啟用/停用 + 執行歷史（`cron.*`）。
|
||||
- Skills：狀態、啟用/停用、安裝、API 金鑰更新（`skills.*`）。
|
||||
- Node：清單 + 能力（`node.list`）。
|
||||
- Node：清單 + 功能（`node.list`）。
|
||||
- 執行核准：編輯 Gateway 或 Node 允許清單 + `exec host=gateway/node` 的詢問政策（`exec.approvals.*`）。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="設定">
|
||||
- 檢視/編輯 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。
|
||||
- 套用 + 透過驗證後重新啟動（`config.apply`），並喚醒最後的作用中工作階段。
|
||||
- 寫入包含基底雜湊防護，以防止覆蓋並行編輯。
|
||||
- 寫入（`config.set`/`config.apply`/`config.patch`）會預先檢查已提交設定承載中 refs 的作用中 SecretRef 解析；未解析的作用中已提交 refs 會在寫入前被拒絕。
|
||||
- Schema + 表單轉譯（`config.schema` / `config.schema.lookup`，包含欄位 `title` / `description`、相符的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin + 頻道 schema）；只有當快照具有安全的原始往返能力時，才可使用原始 JSON 編輯器。
|
||||
- 如果快照無法安全地往返原始文字，Control UI 會強制使用表單模式，並停用該快照的原始模式。
|
||||
- 原始 JSON 編輯器的「重設為已儲存」會保留原始作者撰寫的形狀（格式、註解、`$include` 版面），而不是重新轉譯扁平化快照，因此當快照可安全往返時，外部編輯可在重設後保留下來。
|
||||
- 結構化 SecretRef 物件值會在表單文字輸入中以唯讀方式轉譯，以防止意外的物件轉字串損毀。
|
||||
- 檢視/編輯 `~/.openclaw/openclaw.json`（`config.get`, `config.set`）。
|
||||
- 套用 + 以驗證重新啟動（`config.apply`），並喚醒最後一個作用中工作階段。
|
||||
- 寫入包含 base-hash 防護，以防止覆寫並行編輯。
|
||||
- 寫入（`config.set`/`config.apply`/`config.patch`）會針對已提交設定承載中的參照，預先檢查作用中 SecretRef 解析；未解析的作用中已提交參照會在寫入前被拒絕。
|
||||
- 結構描述 + 表單呈現（`config.schema` / `config.schema.lookup`，包括欄位 `title` / `description`、相符的 UI 提示、直接子項摘要、巢狀物件/萬用字元/陣列/組合節點上的文件中繼資料，以及可用時的 Plugin + 頻道結構描述）；只有當快照具有安全的原始往返時，才可使用原始 JSON 編輯器。
|
||||
- 如果快照無法安全地往返原始文字，控制介面會強制使用表單模式，並針對該快照停用原始模式。
|
||||
- 原始 JSON 編輯器的「重設為已儲存」會保留以原始方式撰寫的形狀（格式、註解、`$include` 版面），而不是重新呈現扁平化快照，因此當快照可以安全往返時，外部編輯會在重設後保留下來。
|
||||
- 結構化 SecretRef 物件值會在表單文字輸入中以唯讀方式呈現，以防止意外的物件轉字串損毀。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="偵錯、日誌、更新">
|
||||
- 偵錯：狀態/健康狀態/模型快照 + 事件日誌 + 手動 RPC 呼叫（`status`、`health`、`models.list`）。
|
||||
- 日誌：Gateway 檔案日誌的即時尾端追蹤，含篩選/匯出（`logs.tail`）。
|
||||
- 更新：執行 package/git 更新 + 重新啟動（`update.run`），並產生重新啟動報告，然後在重新連線後輪詢 `update.status` 以驗證正在執行的 Gateway 版本。
|
||||
<Accordion title="偵錯、記錄、更新">
|
||||
- 偵錯：狀態/健康狀態/模型快照 + 事件記錄 + 手動 RPC 呼叫（`status`, `health`, `models.list`）。
|
||||
- 事件記錄包含控制介面重新整理/RPC 時序，以及當瀏覽器公開這些 PerformanceObserver 項目類型時，長動畫影格或長任務的瀏覽器回應性項目。
|
||||
- 記錄：Gateway 檔案記錄的即時尾端追蹤，並提供篩選/匯出（`logs.tail`）。
|
||||
- 更新：執行套件/git 更新 + 重新啟動（`update.run`），附重新啟動報告，然後在重新連線後輪詢 `update.status` 以驗證執行中的 Gateway 版本。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron 作業面板備註">
|
||||
- 對於隔離作業，傳遞預設為宣布摘要。如果你想要僅內部執行，可以切換為無。
|
||||
- 選取宣布時會顯示頻道/目標欄位。
|
||||
- 對於隔離作業，傳遞預設為公告摘要。如果你想要僅供內部執行，可以切換為無。
|
||||
- 選取公告時會顯示頻道/目標欄位。
|
||||
- Webhook 模式使用 `delivery.mode = "webhook"`，並將 `delivery.to` 設為有效的 HTTP(S) Webhook URL。
|
||||
- 對於主工作階段作業，可使用 Webhook 和無傳遞模式。
|
||||
- 進階編輯控制項包含執行後刪除、清除代理覆寫、Cron 精確/錯開選項、代理模型/思考覆寫，以及盡力傳遞切換。
|
||||
- 表單驗證是內嵌的，並提供欄位層級錯誤；無效值會停用儲存按鈕，直到修正為止。
|
||||
- 設定 `cron.webhookToken` 以傳送專用 bearer token；若省略，Webhook 會在沒有驗證標頭的情況下傳送。
|
||||
- 已棄用的回退：儲存的舊版作業若有 `notify: true`，在遷移前仍可使用 `cron.webhook`。
|
||||
- 對於主要工作階段作業，可使用 Webhook 和無傳遞模式。
|
||||
- 進階編輯控制項包含執行後刪除、清除代理覆寫、Cron 精確/交錯選項、代理模型/思考覆寫，以及最佳努力傳遞切換。
|
||||
- 表單驗證會以欄位層級錯誤內嵌顯示；無效值會停用儲存按鈕，直到修正為止。
|
||||
- 設定 `cron.webhookToken` 以傳送專用承載權杖；若省略，Webhook 會在沒有驗證標頭的情況下傳送。
|
||||
- 已棄用的回退：儲存的舊版作業若含有 `notify: true`，在遷移前仍可使用 `cron.webhook`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -154,86 +155,89 @@ Control UI 可在首次載入時根據你的瀏覽器語系自行本地化。若
|
||||
## 聊天行為
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="傳送與歷史語意">
|
||||
<Accordion title="Send and history semantics">
|
||||
- `chat.send` 是**非阻塞**的：它會立即以 `{ runId, status: "started" }` 確認，回應則透過 `chat` 事件串流傳送。
|
||||
- 聊天上傳接受圖片加上非影片檔案。圖片保留原生圖片路徑；其他檔案會儲存為受管理媒體，並在歷史中顯示為附件連結。
|
||||
- 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 的更新使用（沒有 agent 執行，也沒有通道傳遞）。
|
||||
- 聊天標頭的模型與思考選擇器會透過 `sessions.patch` 立即修補作用中工作階段；它們是持久的工作階段覆寫，不是僅限單回合的傳送選項。
|
||||
- 在 Control UI 中輸入 `/new` 會建立並切換到與 New Chat 相同的全新儀表板工作階段。輸入 `/reset` 會保留 Gateway 對目前工作階段的明確原地重設。
|
||||
- 聊天模型選擇器會請求 Gateway 已設定的模型檢視。如果存在 `agents.defaults.models`，該允許清單會驅動選擇器。否則，選擇器會顯示明確的 `models.providers.*.models` 項目，以及具備可用驗證的提供者。完整目錄仍可透過除錯 `models.list` RPC 搭配 `view: "all"` 使用。
|
||||
- 當新的 Gateway 工作階段用量報告顯示高上下文壓力時，聊天撰寫區會顯示上下文通知，並在建議的 Compaction 層級顯示一個壓縮按鈕，用來執行一般工作階段 Compaction 路徑。過期的權杖快照會隱藏，直到 Gateway 再次回報新的用量。
|
||||
- `chat.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` 會從持久化的工作階段逐字稿重建。工具最終事件之後，控制 UI 會重新載入歷史記錄，並只合併一小段樂觀尾端；逐字稿邊界記載於 [WebChat](/zh-TW/web/webchat)。
|
||||
- `chat.inject` 會將助理備註附加到工作階段逐字稿，並廣播 `chat` 事件以供僅限 UI 的更新使用（沒有代理程式執行，沒有頻道傳遞）。
|
||||
- 聊天標頭會在工作階段選擇器前顯示代理程式篩選器，且工作階段選擇器會依所選代理程式限定範圍。切換代理程式時只會顯示與該代理程式綁定的工作階段；若尚無已儲存的儀表板工作階段，則會退回到該代理程式的主要工作階段。
|
||||
- 在桌面寬度下，聊天控制項會維持在一列精簡排列，並在向下捲動逐字稿時收合；向上捲動、回到頂端或到達底部時會還原控制項。
|
||||
- 連續重複且僅含文字的訊息會呈現為一個帶有計數徽章的氣泡。包含圖片、附件、工具輸出或畫布預覽的訊息不會收合。
|
||||
- 聊天標頭的模型與思考選擇器會透過 `sessions.patch` 立即修補作用中的工作階段；它們是持久化的工作階段覆寫，而不是僅限單次回合的傳送選項。
|
||||
- 在控制 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="對話模式（瀏覽器即時）">
|
||||
對話模式使用已註冊的即時語音提供者。使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 設定 OpenAI，或使用 `talk.provider: "google"` 加上 `talk.providers.google.apiKey` 設定 Google；Voice Call 即時提供者設定仍可作為備援重用。瀏覽器永遠不會收到標準提供者 API 金鑰。OpenAI 會收到用於 WebRTC 的臨時 Realtime 用戶端密鑰。Google Live 會收到用於瀏覽器 WebSocket 工作階段的一次性受限 Live API 驗證權杖，其中指示與工具宣告會由 Gateway 鎖定到權杖內。只公開後端即時橋接的提供者會透過 Gateway 中繼傳輸執行，因此憑證與廠商 socket 會保留在伺服器端，而瀏覽器音訊則透過已驗證的 Gateway RPC 傳輸。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫端提供的指示覆寫。
|
||||
<Accordion title="Talk mode (browser realtime)">
|
||||
Talk 模式使用已註冊的即時語音提供者。若要設定 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 中繼傳輸執行，因此憑證與廠商 socket 會保留在伺服器端，而瀏覽器音訊則透過已驗證的 Gateway RPC 傳輸。Realtime 工作階段提示由 Gateway 組裝；`talk.realtime.session` 不接受呼叫端提供的指示覆寫。
|
||||
|
||||
在聊天撰寫器中，對話控制項是麥克風聽寫按鈕旁的波形按鈕。對話開始時，撰寫器狀態列會顯示 `Connecting Talk...`，音訊連線後顯示 `Talk live`，或在即時工具呼叫正透過 `chat.send` 諮詢已設定的較大型模型時顯示 `Asking OpenClaw...`。
|
||||
在 Chat 撰寫器中，Talk 控制項是麥克風聽寫按鈕旁的波浪按鈕。Talk 啟動時，撰寫器狀態列會先顯示 `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`）以中止該工作階段的所有作用中執行。
|
||||
<Accordion title="Stop and abort">
|
||||
- 按一下 **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="Abort partial retention">
|
||||
- 當執行被中止時，部分助理文字仍可顯示在 UI 中。
|
||||
- 當存在已緩衝輸出時，Gateway 會將已中止的部分助理文字持久化到逐字稿歷史記錄中。
|
||||
- 持久化項目包含中止中繼資料，讓逐字稿消費者能分辨中止片段與正常完成輸出。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## PWA 安裝與網頁推播
|
||||
## PWA 安裝與 Web Push
|
||||
|
||||
Control UI 隨附 `manifest.webmanifest` 和 service worker，因此現代瀏覽器可將其安裝為獨立 PWA。網頁推播可讓 Gateway 透過通知喚醒已安裝的 PWA，即使分頁或瀏覽器視窗未開啟也可以。
|
||||
控制 UI 隨附 `manifest.webmanifest` 和 service worker，因此現代瀏覽器可以將它安裝為獨立 PWA。即使分頁或瀏覽器視窗未開啟，Web Push 也能讓 Gateway 以通知喚醒已安裝的 PWA。
|
||||
|
||||
| 介面 | 功能 |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | PWA manifest。瀏覽器會在可連線後提供「安裝應用程式」。 |
|
||||
| `ui/public/manifest.webmanifest` | PWA manifest。可存取後，瀏覽器會提供「安裝應用程式」。 |
|
||||
| `ui/public/sw.js` | 處理 `push` 事件與通知點擊的 service worker。 |
|
||||
| `push/vapid-keys.json`（位於 OpenClaw 狀態目錄下） | 自動產生的 VAPID 金鑰組，用於簽署網頁推播酬載。 |
|
||||
| `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 方法註冊並測試瀏覽器訂閱：
|
||||
控制 UI 使用這些受範圍限制的 Gateway 方法來註冊與測試瀏覽器訂閱：
|
||||
|
||||
- `push.web.vapidPublicKey` — 擷取作用中的 VAPID 公開金鑰。
|
||||
- `push.web.subscribe` — 註冊 `endpoint` 加上 `keys.p256dh`/`keys.auth`。
|
||||
- `push.web.subscribe` — 註冊 `endpoint` 以及 `keys.p256dh`/`keys.auth`。
|
||||
- `push.web.unsubscribe` — 移除已註冊的端點。
|
||||
- `push.web.test` — 傳送測試通知到呼叫端的訂閱。
|
||||
- `push.web.test` — 將測試通知傳送到呼叫端的訂閱。
|
||||
|
||||
<Note>
|
||||
網頁推播獨立於 iOS APNS 中繼路徑（中繼支援的推播請參閱 [設定](/zh-TW/gateway/configuration)）與現有的 `push.test` 方法；後者以原生行動裝置配對為目標。
|
||||
Web Push 獨立於 iOS APNS 中繼路徑（請參閱 [設定](/zh-TW/gateway/configuration) 了解中繼支援的推播）以及現有的 `push.test` 方法；後者以原生行動裝置配對為目標。
|
||||
</Note>
|
||||
|
||||
## 託管嵌入
|
||||
|
||||
助理訊息可以使用 `[embed ...]` 短代碼內嵌呈現託管的網頁內容。iframe sandbox 政策由 `gateway.controlUi.embedSandbox` 控制：
|
||||
助理訊息可以使用 `[embed ...]` shortcode 內嵌呈現託管的網頁內容。iframe sandbox 政策由 `gateway.controlUi.embedSandbox` 控制：
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
停用託管嵌入內的指令碼執行。
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
允許互動式嵌入，同時保留來源隔離；這是預設值，通常足以支援自包含的瀏覽器遊戲/小工具。
|
||||
允許互動式嵌入，同時保持來源隔離；這是預設值，通常足以用於自包含的瀏覽器遊戲／小工具。
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
在 `allow-scripts` 之上加入 `allow-same-origin`，用於刻意需要較強權限的同站文件。
|
||||
在 `allow-scripts` 之外再加入 `allow-same-origin`，供刻意需要更高權限的同站文件使用。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,14 +254,14 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
```
|
||||
|
||||
<Warning>
|
||||
只有在嵌入文件確實需要同源行為時才使用 `trusted`。對多數 agent 產生的遊戲與互動畫布而言，`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` 覆寫它，而無需修補 bundled CSS：
|
||||
群組化聊天訊息使用易讀的預設最大寬度。寬螢幕部署可透過設定 `gateway.controlUi.chatMessageMaxWidth` 覆寫，而不需要修補隨附的 CSS：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,12 +273,12 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
}
|
||||
```
|
||||
|
||||
此值會在到達瀏覽器前驗證。支援的值包含純長度與百分比，例如 `960px` 或 `82%`，以及受限的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。
|
||||
此值會在送達瀏覽器前驗證。支援的值包含純長度與百分比，例如 `960px` 或 `82%`，以及受限制的 `min(...)`、`max(...)`、`clamp(...)`、`calc(...)` 和 `fit-content(...)` 寬度運算式。
|
||||
|
||||
## Tailnet 存取（建議）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="整合式 Tailscale Serve（偏好）">
|
||||
<Tab title="Integrated Tailscale Serve (preferred)">
|
||||
將 Gateway 保持在 loopback，並讓 Tailscale Serve 以 HTTPS 代理它：
|
||||
|
||||
```bash
|
||||
@ -285,16 +289,16 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
|
||||
- `https://<magicdns>/`（或你設定的 `gateway.controlUi.basePath`）
|
||||
|
||||
預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，Control UI/WebSocket Serve 請求可透過 Tailscale 身分標頭（`tailscale-user-login`）驗證。OpenClaw 會透過 `tailscale whois` 解析 `x-forwarded-for` 位址並將其與標頭比對，以驗證身分，且只有當請求透過 loopback 搭配 Tailscale 的 `x-forwarded-*` 標頭送達時才會接受。對具備瀏覽器裝置身分的 Control UI 操作者工作階段而言，此已驗證的 Serve 路徑也會略過裝置配對往返；無裝置瀏覽器與 node 角色連線仍會遵循一般裝置檢查。如果你想即使對 Serve 流量也要求明確的共用密鑰憑證，請設定 `gateway.auth.allowTailscale: false`。然後使用 `gateway.auth.mode: "token"` 或 `"password"`。
|
||||
預設情況下，當 `gateway.auth.allowTailscale` 為 `true` 時，控制 UI／WebSocket Serve 請求可透過 Tailscale 身分標頭（`tailscale-user-login`）進行驗證。OpenClaw 會使用 `tailscale whois` 解析 `x-forwarded-for` 位址並將其與標頭比對來驗證身分，且只在請求透過 loopback 並帶有 Tailscale 的 `x-forwarded-*` 標頭時接受這些驗證。對於具備瀏覽器裝置身分的控制 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 主機受信任。如果不受信任的本機程式碼可能在該主機上執行，請要求 token／password 驗證。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="繫結到 tailnet + 權杖">
|
||||
<Tab title="Bind to tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -310,21 +314,21 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
|
||||
## 不安全的 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 相容性
|
||||
- 透過 `gateway.auth.mode: "trusted-proxy"` 成功進行的操作者 Control UI 驗證
|
||||
- 緊急解鎖 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- 透過 `gateway.auth.mode: "trusted-proxy"` 成功完成操作員 Control UI 驗證
|
||||
- 緊急破例 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**建議修正：**使用 HTTPS（Tailscale Serve）或在本機開啟 UI：
|
||||
**建議修正方式：**使用 HTTPS（Tailscale Serve）或在本機開啟 UI：
|
||||
|
||||
- `https://<magicdns>/`（Serve）
|
||||
- `http://127.0.0.1:18789/`（在 Gateway 主機上）
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="不安全驗證切換行為">
|
||||
<Accordion title="Insecure-auth toggle behavior">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -337,12 +341,12 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
|
||||
`allowInsecureAuth` 只是本機相容性切換：
|
||||
|
||||
- 它允許 localhost Control UI 工作階段在非安全 HTTP 情境中，不需要裝置身分即可繼續。
|
||||
- 它不會繞過配對檢查。
|
||||
- 它允許 localhost Control UI 工作階段在非安全 HTTP 內容中，在沒有裝置身分的情況下繼續進行。
|
||||
- 它不會略過配對檢查。
|
||||
- 它不會放寬遠端（非 localhost）裝置身分需求。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="僅限緊急破窗">
|
||||
<Accordion title="Break-glass only">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,68 +358,68 @@ Control UI 使用這些受作用域限制的 Gateway 方法註冊並測試瀏覽
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` 會停用 Control UI 裝置身分檢查，並造成嚴重的安全性降級。緊急使用後請盡快還原。
|
||||
`dangerouslyDisableDeviceAuth` 會停用 Control UI 裝置身分檢查，是嚴重的安全性降級。緊急使用後請盡快還原。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="可信任 Proxy 注意事項">
|
||||
- 成功的可信任 Proxy 驗證可以允許沒有裝置身分的 **operator** Control UI 工作階段進入。
|
||||
- 這**不會**延伸到節點角色的 Control UI 工作階段。
|
||||
- 同一主機的 loopback 反向 Proxy 仍不滿足可信任 Proxy 驗證；請參閱[可信任 Proxy 驗證](/zh-TW/gateway/trusted-proxy-auth)。
|
||||
<Accordion title="Trusted-proxy note">
|
||||
- 成功的 trusted-proxy 驗證可以允許沒有裝置身分的**操作員** Control UI 工作階段。
|
||||
- 這**不**會延伸到 node-role Control UI 工作階段。
|
||||
- 同一主機的 loopback 反向代理仍然不符合 trusted-proxy 驗證；請參閱 [Trusted proxy auth](/zh-TW/gateway/trusted-proxy-auth)。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
請參閱 [Tailscale](/zh-TW/gateway/tailscale) 以取得 HTTPS 設定指引。
|
||||
請參閱 [Tailscale](/zh-TW/gateway/tailscale) 以取得 HTTPS 設定指南。
|
||||
|
||||
## 內容安全政策
|
||||
## 內容安全性原則
|
||||
|
||||
Control UI 隨附嚴格的 `img-src` 政策：只允許**同源**資產、`data:` URL，以及本機產生的 `blob:` URL。遠端 `http(s)` 和協定相對圖片 URL 會被瀏覽器拒絕，且不會發出網路擷取。
|
||||
Control 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 的頭像輔助程式中被移除，並替換為內建標誌/徽章，因此遭入侵或惡意的頻道無法強制 operator 瀏覽器擷取任意遠端圖片。
|
||||
- 以相對路徑提供的頭像與圖片（例如 `/avatars/<id>`）仍會顯示，包括 UI 擷取並轉換成本機 `blob:` URL 的已驗證頭像路由。
|
||||
- 行內 `data:image/...` URL 仍會顯示（對協定內承載很有用）。
|
||||
- Control UI 建立的本機 `blob:` URL 仍會顯示。
|
||||
- 通道中繼資料發出的遠端頭像 URL 會由 Control UI 的頭像輔助程式移除，並改用內建標誌/徽章，因此受入侵或惡意通道無法強迫操作員瀏覽器擷取任意遠端圖片。
|
||||
|
||||
你不需要變更任何設定即可取得此行為——它一律啟用且不可設定。
|
||||
你不需要變更任何內容即可取得此行為，此行為一律啟用且不可設定。
|
||||
|
||||
## 頭像路由驗證
|
||||
|
||||
設定 Gateway 驗證時，Control UI 頭像端點需要與其餘 API 相同的 Gateway 權杖：
|
||||
設定 Gateway 驗證時，Control UI 頭像端點需要與 API 其餘部分相同的 Gateway token：
|
||||
|
||||
- `GET /avatar/<agentId>` 只會向已驗證呼叫端傳回頭像圖片。`GET /avatar/<agentId>?meta=1` 會依相同規則傳回頭像中繼資料。
|
||||
- 對任一路由的未驗證請求都會被拒絕（與相鄰的 assistant-media 路由一致）。這可避免頭像路由在原本受保護的主機上洩漏代理身分。
|
||||
- Control UI 本身在擷取頭像時會以 bearer 標頭轉送 Gateway 權杖，並使用已驗證的 Blob URL，讓圖片仍能在儀表板中呈現。
|
||||
- `GET /avatar/<agentId>` 只會向已驗證呼叫者傳回頭像圖片。`GET /avatar/<agentId>?meta=1` 會在相同規則下傳回頭像中繼資料。
|
||||
- 對任一路由的未驗證請求都會被拒絕（與同層的 assistant-media 路由一致）。這可防止頭像路由在其他方面已受保護的主機上洩漏代理身分。
|
||||
- Control UI 本身會在擷取頭像時將 Gateway token 作為 bearer 標頭轉送，並使用已驗證的 blob URL，讓圖片仍能在儀表板中顯示。
|
||||
|
||||
如果你停用 Gateway 驗證（不建議在共享主機上這麼做），頭像路由也會變成未驗證，與 Gateway 的其餘部分一致。
|
||||
如果你停用 Gateway 驗證（不建議在共用主機上這麼做），頭像路由也會變成未驗證，與 Gateway 其餘部分一致。
|
||||
|
||||
## Assistant 媒體路由驗證
|
||||
## Assistant media 路由驗證
|
||||
|
||||
設定 Gateway 驗證時，assistant 本機媒體預覽會使用兩步驟路由：
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` 需要一般的 Control UI operator 驗證。瀏覽器在檢查可用性時會將 Gateway 權杖作為 bearer 標頭傳送。
|
||||
- 成功的中繼資料回應會包含短效 `mediaTicket`，其範圍限定於該確切來源路徑。
|
||||
- 瀏覽器呈現的圖片、音訊、影片與文件 URL 會使用 `mediaTicket=<ticket>`，而不是有效的 Gateway 權杖或密碼。票證會很快到期，且無法授權不同來源。
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` 需要一般的 Control UI 操作員驗證。瀏覽器在檢查可用性時會將 Gateway token 作為 bearer 標頭傳送。
|
||||
- 成功的中繼資料回應會包含一個短效 `mediaTicket`，其範圍限定為該確切來源路徑。
|
||||
- 瀏覽器轉譯的圖片、音訊、影片與文件 URL 會使用 `mediaTicket=<ticket>`，而不是作用中的 Gateway token 或密碼。該 ticket 很快就會過期，且無法授權不同來源。
|
||||
|
||||
這可讓一般媒體呈現與瀏覽器原生媒體元素相容，同時不會把可重複使用的 Gateway 認證放入可見的媒體 URL。
|
||||
這能讓一般媒體轉譯與瀏覽器原生媒體元素相容，同時不會把可重複使用的 Gateway 認證放在可見的媒體 URL 中。
|
||||
|
||||
## 建置 UI
|
||||
|
||||
Gateway 會從 `dist/control-ui` 提供靜態檔案。使用以下命令建置：
|
||||
Gateway 從 `dist/control-ui` 提供靜態檔案。使用以下命令建置：
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
選用的絕對基底路徑（當你想要固定資產 URL 時）：
|
||||
選用的絕對基底（當你想要固定資產 URL 時）：
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
本機開發（獨立的開發伺服器）：
|
||||
用於本機開發（獨立開發伺服器）：
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
@ -425,15 +429,15 @@ pnpm ui:dev
|
||||
|
||||
## 偵錯/測試：開發伺服器 + 遠端 Gateway
|
||||
|
||||
Control UI 是靜態檔案；WebSocket 目標可設定，且可以與 HTTP 來源不同。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。
|
||||
Control UI 是靜態檔案；WebSocket 目標可設定，且可以不同於 HTTP 來源。當你想在本機使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這很方便。
|
||||
|
||||
<Steps>
|
||||
<Step title="啟動 UI 開發伺服器">
|
||||
<Step title="Start the UI dev server">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
</Step>
|
||||
<Step title="使用 gatewayUrl 開啟">
|
||||
<Step title="Open with gatewayUrl">
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
@ -448,18 +452,18 @@ Control UI 是靜態檔案；WebSocket 目標可設定，且可以與 HTTP 來
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="注意事項">
|
||||
<Accordion title="Notes">
|
||||
- `gatewayUrl` 會在載入後儲存在 localStorage 中，並從 URL 移除。
|
||||
- 如果你透過 `gatewayUrl` 傳入完整的 `ws://` 或 `wss://` 端點，請對 `gatewayUrl` 值進行 URL 編碼，讓瀏覽器正確解析查詢字串。
|
||||
- 盡可能透過 URL 片段（`#token=...`）傳入 `token`。片段不會傳送到伺服器，可避免請求記錄和 Referer 洩漏。舊版 `?token=` 查詢參數仍會為了相容性匯入一次，但只作為後備，且會在啟動後立即移除。
|
||||
- `password` 只保留在記憶體中。
|
||||
- 設定 `gatewayUrl` 時，UI 不會回退使用設定或環境認證。請明確提供 `token`（或 `password`）。缺少明確認證會造成錯誤。
|
||||
- Gateway 位於 TLS 後方時（Tailscale Serve、HTTPS Proxy 等），請使用 `wss://`。
|
||||
- 如果你透過 `gatewayUrl` 傳遞完整的 `ws://` 或 `wss://` 端點，請對 `gatewayUrl` 值進行 URL 編碼，讓瀏覽器正確解析查詢字串。
|
||||
- 應盡可能透過 URL 片段（`#token=...`）傳遞 `token`。片段不會傳送到伺服器，可避免請求記錄與 Referer 洩漏。舊版 `?token=` 查詢參數仍會為相容性匯入一次，但只作為備援，且會在啟動後立即移除。
|
||||
- `password` 只會保留在記憶體中。
|
||||
- 設定 `gatewayUrl` 時，UI 不會退回使用設定或環境認證。請明確提供 `token`（或 `password`）。缺少明確認證會造成錯誤。
|
||||
- 當 Gateway 位於 TLS 後方（Tailscale Serve、HTTPS 代理等）時，請使用 `wss://`。
|
||||
- `gatewayUrl` 只會在最上層視窗中被接受（不可嵌入），以防止點擊劫持。
|
||||
- 非 loopback Control UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整來源）。這包括遠端開發設定。
|
||||
- Gateway 啟動時可能會從有效的執行階段繫結與連接埠植入本機來源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但遠端瀏覽器來源仍需要明確項目。
|
||||
- 除了嚴格控管的本機測試外，請勿使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器來源，而不是「符合我正在使用的任何主機」。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host 標頭來源後備模式，但這是危險的安全模式。
|
||||
- 非 loopback 的 Control UI 部署必須明確設定 `gateway.controlUi.allowedOrigins`（完整來源）。這包括遠端開發設定。
|
||||
- Gateway 啟動時可能會從有效的執行階段 bind 與 port 播種本機來源，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但遠端瀏覽器來源仍需要明確項目。
|
||||
- 除非是嚴格受控的本機測試，否則不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允許任何瀏覽器來源，而不是「符合我正在使用的任何主機」。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 會啟用 Host-header 來源備援模式，但這是危險的安全模式。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -476,11 +480,11 @@ Control UI 是靜態檔案；WebSocket 目標可設定，且可以與 HTTP 來
|
||||
}
|
||||
```
|
||||
|
||||
遠端存取設定詳細資訊：[遠端存取](/zh-TW/gateway/remote)。
|
||||
遠端存取設定詳細資訊：[Remote access](/zh-TW/gateway/remote)。
|
||||
|
||||
## 相關
|
||||
|
||||
- [儀表板](/zh-TW/web/dashboard) — Gateway 儀表板
|
||||
- [健康檢查](/zh-TW/gateway/health) — Gateway 健康狀態監控
|
||||
- [TUI](/zh-TW/web/tui) — 終端使用者介面
|
||||
- [Dashboard](/zh-TW/web/dashboard) — Gateway 儀表板
|
||||
- [Health Checks](/zh-TW/gateway/health) — Gateway 健康監控
|
||||
- [TUI](/zh-TW/web/tui) — 終端機使用者介面
|
||||
- [WebChat](/zh-TW/web/webchat) — 瀏覽器式聊天介面
|
||||
|
||||
Loading…
Reference in New Issue
Block a user