diff --git a/release-notes/2026-03-28.md b/release-notes/2026-03-28.md new file mode 100644 index 0000000..cd72a28 --- /dev/null +++ b/release-notes/2026-03-28.md @@ -0,0 +1,384 @@ +# OpenClaw v2026.3.28 版本發佈說明 + +[GitHub Release](https://github.com/openclaw/openclaw/releases/tag/v2026.3.28) + +## ⚠️ 升級前必讀 + +### Breaking Changes 摘要 + +| 項目 | 影響 | 行動 | +|------|------|------| +| Qwen `qwen-portal-auth` OAuth 整合移除 | 使用 Qwen Portal 登入的用戶將無法驗證 | 執行 `openclaw onboard --auth-choice modelstudio-api-key` 遷移至 Model Studio API Key | +| Config/Doctor 停止自動遷移兩個月以上的舊設定 | 超過兩個月的舊版 config key 將驗證失敗，不再自動修復 | 執行 `openclaw doctor` 手動確認並修正舊版設定 | + +### 新功能亮點 + +- **Plugin `requireApproval` hooks**：工具執行前可暫停並透過 Telegram 按鈕、Discord 互動或 `/approve` 指令請求用戶確認 +- **xAI Responses API + `x_search`**：Grok 整合升級，內建網路搜尋無需手動啟用 plugin +- **ACP current-conversation binds**：`/acp spawn codex --bind here` 可直接將現有聊天室轉為 Codex 工作區 +- **MiniMax 圖片生成**：支援 `image-01` 模型的文生圖與圖生圖（含長寬比控制） +- **`openclaw config schema`**：新增指令可輸出 `openclaw.json` 的完整 JSON Schema + +--- + +## 概覽 + +### 功能更新 (Features) + +- ⭐⭐⭐ Plugin `before_tool_call` 新增 async `requireApproval`，支援多渠道審核工具執行 ([#55339](https://github.com/openclaw/openclaw/pull/55339)) +- ⭐⭐⭐ xAI 整合升級至 Responses API，新增 `x_search` 工具並自動啟用 ([#56048](https://github.com/openclaw/openclaw/pull/56048)) +- ⭐⭐⭐ ACP/channels 新增 current-conversation binds（Discord、BlueBubbles、iMessage）([#55339](https://github.com/openclaw/openclaw/pull/55339)) +- ⭐⭐ MiniMax 新增圖片生成 provider（`image-01`）([#54487](https://github.com/openclaw/openclaw/pull/54487)) +- ⭐⭐ Plugins/CLI backends：Claude CLI、Codex CLI、Gemini CLI 移至 plugin 層，新增 Gemini CLI backend ([#54809](https://github.com/openclaw/openclaw/pull/54809)) +- ⭐⭐ Slack 新增 `upload-file` action，支援頻道與 DM 檔案上傳 +- ⭐⭐ `openclaw config schema` 新指令輸出 JSON Schema ([#54523](https://github.com/openclaw/openclaw/pull/54523)) +- ⭐ xAI onboarding 整合 `x_search` 設定流程 +- ⭐ Podman 簡化 rootless 容器設定，安裝 helper 至 `~/.local/bin` +- ⭐ Matrix TTS 改為原生 voice bubble 格式 ([#37080](https://github.com/openclaw/openclaw/pull/37080)) +- ⭐ Memory/plugins：記憶體 flush 邏輯移至 `memory-core` plugin 管理 +- ⭐ Plugins/runtime：新增 `runHeartbeatOnce` 供 plugin 觸發單次 heartbeat ([#40299](https://github.com/openclaw/openclaw/pull/40299)) +- ⭐ MCP/channels：新增 Gateway-backed channel MCP bridge，含 Codex/Claude 對話工具 +- ⭐ Message actions/files：統一 `upload-file` action，新增 Teams、Google Chat 支援 + +### 安全性提升 (Security) + +- ⭐⭐ Security/audit：擴充 web search key 審計，涵蓋 Gemini、Grok/xAI、Kimi、Moonshot、OpenRouter ([#56540](https://github.com/openclaw/openclaw/pull/56540)) +- ⭐ ACP/ACPX：修正未知 agent id 不再落入 raw `--agent` 執行路徑 ([#28321](https://github.com/openclaw/openclaw/pull/28321)) +- ⭐ Agents/sandbox：修正 `tools.sandbox.tools.alsoAllow` 及 glob-aware blocked-tool guidance ([#54492](https://github.com/openclaw/openclaw/pull/54492)) +- ⭐ Control UI/config：敏感設定預設隱藏，需明確解鎖才可編輯（修復 #55322） + +### 錯誤修復 (Bug Fixes) + +- ⭐⭐⭐ Telegram 長訊息分割改用 HTML 長度計算，避免中途截斷 ([#56595](https://github.com/openclaw/openclaw/pull/56595)) +- ⭐⭐⭐ WhatsApp 自聊 DM 模式無限 echo loop 修復 ([#54570](https://github.com/openclaw/openclaw/pull/54570)) +- ⭐⭐⭐ Discord gateway 重連狀態清理，修復 poisoned resume state 導致的無限重連 ([#54697](https://github.com/openclaw/openclaw/pull/54697)) +- ⭐⭐ Google/models：修復 Gemini 3.1 pro/flash/flash-lite 解析失敗 ([#56567](https://github.com/openclaw/openclaw/pull/56567)) +- ⭐⭐ Agents/cooldowns：rate-limit 冷卻改為 per-model，避免一個 429 封鎖所有模型 ([#49834](https://github.com/openclaw/openclaw/pull/49834)) +- ⭐⭐ OpenAI Codex/image tools：修復圖片分析因 provider 未註冊而失敗 ([#54829](https://github.com/openclaw/openclaw/pull/54829)) +- ⭐⭐ Heartbeat/runner：修復 heartbeat 在中斷後靜默停止的問題 ([#52270](https://github.com/openclaw/openclaw/pull/52270)) +- ⭐⭐ Agents/compaction：修復高 context LLM timeout 前觸發壓縮，避免重複超大請求 ([#46417](https://github.com/openclaw/openclaw/pull/46417)) +- ⭐ Telegram/delivery：跳過空白或 hook-blanked 回覆，避免 GrammyError 400 ([#56620](https://github.com/openclaw/openclaw/pull/56620)) +- ⭐ Telegram/send：統一驗證 `replyToMessageId`，拒絕非數字值 ([#56587](https://github.com/openclaw/openclaw/pull/56587)) +- ⭐ Telegram/forum topics：修復 verbose tool summary 在 forum topic 中不顯示 ([#43236](https://github.com/openclaw/openclaw/pull/43236)) +- ⭐ iMessage：修復 `[[reply_to:...]]` tag 洩漏至送出訊息 ([#39512](https://github.com/openclaw/openclaw/pull/39512)) +- ⭐ Auto-reply：過濾 `{"action":"NO_REPLY"}` 控制封包，避免送至渠道 ([#56612](https://github.com/openclaw/openclaw/pull/56612)) +- ⭐ Mistral：修復 422 chat 錯誤（OpenAI-compatible request flags 正規化） +- ⭐ BlueBubbles/debounce：修復 null message text 導致的 flush 崩潰 ([#56573](https://github.com/openclaw/openclaw/pull/56573)) +- ⭐ Feishu：修復 WebSocket ghost connection 與重複事件處理 ([#52844](https://github.com/openclaw/openclaw/pull/52844)) +- ⭐ Feishu：修復離線重試訊息使用錯誤時間戳 ([#52809](https://github.com/openclaw/openclaw/pull/52809)) +- ⭐ GitHub Copilot/auth：修復 `expires_at` 大數值導致 setTimeout overflow 熱迴圈 ([#55360](https://github.com/openclaw/openclaw/pull/55360)) +- ⭐ CLI/zsh：延遲 `compdef` 註冊，修復 zsh completion 載入問題 ([#56555](https://github.com/openclaw/openclaw/pull/56555)) +- ⭐ Memory/search：修復 split plugin runtime 中 memory embedding provider 未共享 ([#55945](https://github.com/openclaw/openclaw/pull/55945)) +- ⭐ Agents/model switching：`/model` 切換在下次安全重試邊界生效，不再卡在舊 provider +- ⭐ Google/tools：移除空 `required: []` 陣列，修復 Gemini 400 驗證錯誤 ([#52106](https://github.com/openclaw/openclaw/pull/52106)) +- ⭐ Matrix/mentions：識別使用 room display name 的 `matrix.to` mentions ([#55393](https://github.com/openclaw/openclaw/pull/55393)) +- ⭐ Ollama/thinking off：修復 `thinkingLevel=off` 未正確傳遞 `think: false` ([#53200](https://github.com/openclaw/openclaw/pull/53200)) +- ⭐ Discord/replies：修復 strip inline reply tags 時破壞縮排與 code block 格式 ([#55960](https://github.com/openclaw/openclaw/pull/55960)) +- ⭐ Brave/web search：修復不支援的 `country` 值導致 422 錯誤 ([#55695](https://github.com/openclaw/openclaw/pull/55695)) + +--- + +## 功能更新 (Features) - by Star Rating + +### ⭐⭐⭐ Plugin `requireApproval`：工具執行前多渠道審核 ([#55339](https://github.com/openclaw/openclaw/pull/55339)) + +- **用途**: `before_tool_call` hooks 新增 async `requireApproval`，讓 plugin 可暫停工具執行並請求用戶確認 +- **解決問題**: 高風險工具（如檔案刪除、外部 API 呼叫）缺乏人工審核機制 +- **影響**: 支援 exec approval overlay、Telegram 按鈕、Discord 互動、`/approve` 指令，`/approve` 現統一處理 exec 與 plugin 審核 + +```text +┌─────────────────────┐ +│ tool_call 觸發 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ before_tool_call │ +│ hook 執行 │ +└──────────┬──────────┘ + │ + ┌──────┴──────┐ + │ requireApproval?│ + └──────┬──────┘ + │ + ┌─────┴──────┐ + Yes No + │ │ + ▼ ▼ +┌─────────┐ ┌──────────┐ +│ 暫停等待 │ │ 直接執行 │ +│ 用戶審核 │ └──────────┘ +└────┬────┘ + │ /approve 或 Telegram/Discord 按鈕 + ▼ +┌─────────────────────┐ +│ 工具繼續執行 │ +└─────────────────────┘ +``` + +### ⭐⭐⭐ xAI 整合升級：Responses API + `x_search` ([#56048](https://github.com/openclaw/openclaw/pull/56048)) + +- **用途**: 將 bundled xAI provider 移至 Responses API，新增 `x_search` 工具，並從 web-search 與 tool config 自動啟用 xAI plugin +- **解決問題**: 舊版需手動切換 plugin toggle 才能使用 Grok 網路搜尋 +- **影響**: Grok auth 與 configured search 流程無需手動設定即可運作 + +```text +┌──────────────────────┐ +│ xAI / Grok 設定 │ +└──────────┬───────────┘ + │ + ▼ +┌──────────────────────┐ +│ 自動偵測 web-search │ +│ 或 tool config │ +└──────────┬───────────┘ + │ + ▼ +┌──────────────────────┐ +│ 自動啟用 xAI plugin │ +│ + x_search 工具 │ +└──────────┬───────────┘ + │ + ▼ +┌──────────────────────┐ +│ Responses API 執行 │ +│ 含即時網路搜尋 │ +└──────────────────────┘ +``` + +### ⭐⭐⭐ ACP current-conversation binds ([#55339](https://github.com/openclaw/openclaw/pull/55339)) + +- **用途**: Discord、BlueBubbles、iMessage 新增 current-conversation ACP bind，`/acp spawn codex --bind here` 可將現有聊天室直接轉為 Codex 工作區 +- **解決問題**: 過去 ACP spawn 必須建立子 thread，無法在原聊天室中使用 +- **影響**: 明確區分 chat surface、ACP session、runtime workspace 三層概念 + +```text +┌─────────────────────┐ +│ /acp spawn codex │ +│ --bind here │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 現有聊天室 │ +│ (Discord/BB/iMsg) │ +└──────────┬──────────┘ + │ bind（不建立子 thread） + ▼ +┌─────────────────────┐ +│ Codex ACP session │ +│ 在原聊天室運作 │ +└─────────────────────┘ +``` + +### ⭐⭐ MiniMax 圖片生成 ([#54487](https://github.com/openclaw/openclaw/pull/54487)) + +- **用途**: 新增 MiniMax `image-01` 模型支援，可文生圖與圖生圖，支援長寬比控制 +- **解決問題**: MiniMax 過去僅支援文字對話 +- **影響**: 同時精簡模型目錄至 M2.7，移除舊版 M2/M2.1/M2.5/VL-01 + +### ⭐⭐ CLI backends 移至 Plugin 層 + +- **用途**: Claude CLI、Codex CLI、Gemini CLI 推論預設移至 plugin 層，新增 Gemini CLI backend，`--claude-cli-logs` 改為 `--cli-backend-logs`（舊 flag 保留相容） +- **解決問題**: bundled CLI backend 需手動加入 `plugins.allow` +- **影響**: 設定 bundled CLI backend 後自動載入，無需額外設定 + +### ⭐⭐ Slack `upload-file` action + +- **用途**: 新增明確的 `upload-file` Slack action，支援 filename/title/comment 覆寫 +- **解決問題**: 過去 Slack 檔案上傳路徑不統一 +- **影響**: 與 Teams、Google Chat 的 `upload-file` 統一介面 + +### ⭐⭐ `openclaw config schema` ([#54523](https://github.com/openclaw/openclaw/pull/54523)) + +- **用途**: 新增 CLI 指令輸出 `openclaw.json` 的完整 JSON Schema +- **解決問題**: 開發者難以驗證設定檔格式 +- **影響**: 可整合至 IDE 或 CI 進行設定驗證 + +### ⭐ Matrix TTS 原生 voice bubble ([#37080](https://github.com/openclaw/openclaw/pull/37080)) + +- **用途**: auto-TTS 回覆改為 Matrix 原生 voice bubble，而非一般音訊附件 +- **影響**: Matrix 客戶端可正確顯示語音訊息 UI + +### ⭐ `runHeartbeatOnce` plugin API ([#40299](https://github.com/openclaw/openclaw/pull/40299)) + +- **用途**: plugin runtime `system` namespace 新增 `runHeartbeatOnce`，可觸發單次 heartbeat 並指定 delivery target +- **影響**: plugin 可主動觸發 heartbeat，不需等待排程 + +--- + +## 安全性提升 (Security) - by Star Rating + +### ⭐⭐ Web Search Key 審計擴充 ([#56540](https://github.com/openclaw/openclaw/pull/56540)) + +- **用途**: 擴充 web search key 審計範圍，新增 Gemini、Grok/xAI、Kimi、Moonshot、OpenRouter 憑證識別 +- **解決問題**: 舊版審計遺漏多個主流 provider 的 API key 格式 +- **影響**: 更完整的憑證洩漏偵測，透過 boundary-safe bundled-web-search registry shim 實作 + +### ⭐ ACP/ACPX agent registry 強化 ([#28321](https://github.com/openclaw/openclaw/pull/28321)) + +- **用途**: 未知 ACP agent id 不再落入 raw `--agent` 命令執行路徑 +- **解決問題**: 惡意或錯誤的 agent id 可能觸發非預期的命令執行 +- **影響**: MCP-proxy 路徑更安全 + +### ⭐ Agents/sandbox 修復 ([#54492](https://github.com/openclaw/openclaw/pull/54492)) + +- **用途**: 修正 `tools.sandbox.tools.alsoAllow`、glob-aware blocked-tool guidance，並清理 session key 洩漏 +- **影響**: sandbox 工具政策更精確，避免 session key 出現在用戶可見的提示中 + +### ⭐ Control UI 敏感設定保護（修復 #55322） + +- **用途**: 敏感 config 預設隱藏，需明確解鎖才可編輯，移除空白封鎖編輯器 +- **影響**: 避免意外暴露 API key 等敏感資訊 + +--- + +## 錯誤修復 (Bug Fixes) - by Star Rating + +### ⭐⭐⭐ Telegram 長訊息分割修復 ([#56595](https://github.com/openclaw/openclaw/pull/56595)) + +- **用途**: 改用 HTML 長度計算取代比例估算，確保在詞語邊界分割 +- **解決問題**: 長訊息在 HTML tag 中途被截斷，導致格式錯誤 +- **影響**: 長訊息分割更可靠，tag overhead 超出限制時優雅降級 + +```text +┌─────────────────────┐ +│ 長訊息（含 HTML） │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 計算實際 HTML 長度 │ +│（非比例估算） │ +└──────────┬──────────┘ + │ + ┌──────┴──────┐ + 超出限制 未超出 + │ │ + ▼ ▼ +┌─────────┐ ┌──────────┐ +│ 詞語邊界 │ │ 直接送出 │ +│ 分割 │ └──────────┘ +└─────────┘ +``` + +### ⭐⭐⭐ WhatsApp 自聊 DM 無限 echo loop 修復 ([#54570](https://github.com/openclaw/openclaw/pull/54570)) + +- **用途**: 修復 self-chat DM 模式中 bot 自身回覆被重新處理為新訊息的問題 +- **解決問題**: bot 在自聊模式下陷入無限回覆迴圈 +- **影響**: self-chat DM 模式可正常使用 + +```text +┌─────────────────────┐ +│ Bot 送出回覆 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 偵測是否為自身訊息 │ +└──────────┬──────────┘ + │ + ┌─────┴──────┐ + 是自身 非自身 + │ │ + ▼ ▼ +┌─────────┐ ┌──────────┐ +│ 忽略 │ │ 正常處理 │ +└─────────┘ └──────────┘ +``` + +### ⭐⭐⭐ Discord gateway 重連修復 ([#54697](https://github.com/openclaw/openclaw/pull/54697)) + +- **用途**: 清除 stale gateway socket 與 resume state，強制 fresh reconnect，修復 poisoned resume state +- **解決問題**: Discord 重連後因舊 resume state 持續失敗，陷入無限重連迴圈 +- **影響**: Discord 連線穩定性大幅提升 + +```text +┌─────────────────────┐ +│ Discord 連線中斷 │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 清除 stale socket │ +│ 清除 resume state │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ Fresh reconnect │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ 連線恢復正常 │ +└─────────────────────┘ +``` + +### ⭐⭐ Google/models Gemini 3.1 解析修復 ([#56567](https://github.com/openclaw/openclaw/pull/56567)) + +- **用途**: 修復 Gemini 3.1 pro/flash/flash-lite 在所有 Google provider alias 下的解析失敗 +- **解決問題**: 傳入錯誤的 runtime provider ID，導致模型無法解析 +- **影響**: 所有 Gemini 3.1 系列模型可正常使用 + +### ⭐⭐ Agents/cooldowns per-model 修復 ([#49834](https://github.com/openclaw/openclaw/pull/49834)) + +- **用途**: rate-limit 冷卻改為 per-model 範圍，冷卻梯度改為 30s/1min/5min +- **解決問題**: 一個模型的 429 錯誤封鎖同 auth profile 下所有模型 +- **影響**: 多模型設定下可靠性提升，並顯示倒數計時訊息 + +### ⭐⭐ Heartbeat 靜默停止修復 ([#52270](https://github.com/openclaw/openclaw/pull/52270)) + +- **用途**: 確保 heartbeat interval timer 在執行後與意外錯誤後都重新設定 +- **解決問題**: heartbeat 在中斷的 cycle 後靜默停止 +- **影響**: 排程 heartbeat 更可靠 + +### ⭐ Telegram 空白回覆過濾 ([#56620](https://github.com/openclaw/openclaw/pull/56620)) + +- **用途**: 跳過空白或 hook-blanked 的文字回覆，避免 GrammyError 400 +- **影響**: Telegram bot 穩定性提升 + +### ⭐ iMessage reply_to tag 洩漏修復 ([#39512](https://github.com/openclaw/openclaw/pull/39512)) + +- **用途**: `reply_to` 改為 RPC metadata 傳遞，並清除送出訊息中的殘留 directive tag +- **影響**: iMessage 訊息不再出現 `[[reply_to:...]]` 殘留文字 + +### ⭐ Auto-reply NO_REPLY 過濾 ([#56612](https://github.com/openclaw/openclaw/pull/56612)) + +- **用途**: 在渠道送出前過濾 `{"action":"NO_REPLY"}` 控制封包，保留 media +- **影響**: 靜默回覆不再送出 JSON 控制字串至用戶 + +### ⭐ GitHub Copilot auth refresh 修復 ([#55360](https://github.com/openclaw/openclaw/pull/55360)) + +- **用途**: 修復大數值 `expires_at` 被誤判為毫秒，導致 setTimeout overflow 熱迴圈 +- **影響**: Copilot token refresh 不再造成 CPU 異常 + +### ⭐ Memory/search embedding provider 修復 ([#55945](https://github.com/openclaw/openclaw/pull/55945)) + +- **用途**: 跨 split plugin runtime 共享 memory embedding provider 註冊 +- **影響**: memory search 不再因 unknown provider 錯誤失敗 + +### ⭐ Feishu WebSocket ghost connection 修復 ([#52844](https://github.com/openclaw/openclaw/pull/52844)) + +- **用途**: monitor stop/abort 時關閉 WebSocket 連線，防止 ghost connection 持續存在 +- **影響**: Feishu 重啟後不再有重複事件處理 + +### ⭐ Brave web search country 修復 ([#55695](https://github.com/openclaw/openclaw/pull/55695)) + +- **用途**: 不支援的 `country` 值（如 `VN`）正規化為 `ALL` +- **影響**: 非英語地區用戶的 Brave 搜尋不再回傳 422 錯誤 + +--- + +## 總結 + +| 類別 | 3 顆星 | 2 顆星 | 1 顆星 | 摘要 | +|------|--------|--------|--------|------| +| 功能更新 | 3 | 4 | 7 | Plugin 審核機制、xAI 升級、ACP bind 為主要亮點 | +| 安全性提升 | 0 | 1 | 3 | Web search key 審計擴充、sandbox 強化 | +| 錯誤修復 | 3 | 5 | 15+ | Telegram/Discord/WhatsApp 穩定性大幅改善 | + +**發佈日期**: 2026-03-28 +**版本**: 2026.3.28 +**狀態**: Production Ready +**GitHub Release**: [v2026.3.28](https://github.com/openclaw/openclaw/releases/tag/v2026.3.28)