Breaking
- Providers/Qwen: remove the deprecated
qwen-portal-authOAuth integration forportal.qwen.ai; migrate to Model Studio withopenclaw onboard --auth-choice modelstudio-api-key. (#52709) Thanks @pomelo-nwu. - Config/Doctor: drop automatic config migrations older than two months; very old legacy keys now fail validation instead of being rewritten on load or by
openclaw doctor.
Changes
- xAI/tools: move the bundled xAI provider to the Responses API, add first-class
x_search, and auto-enable the xAI plugin from owned web-search and tool config so bundled Grok auth/configured search flows work without manual plugin toggles. (#56048) Thanks @huntharo. - xAI/onboarding: let the bundled Grok web-search plugin offer optional
x_searchsetup duringopenclaw onboardandopenclaw configure --section web, including an x_search model picker with the shared xAI key. - MiniMax: add image generation provider for
image-01model, supporting generate and image-to-image editing with aspect ratio control. (#54487) Thanks @liyuan97. - Plugins/hooks: add async
requireApprovaltobefore_tool_callhooks, letting plugins pause tool execution and prompt the user for approval via the exec approval overlay, Telegram buttons, Discord interactions, or the/approvecommand on any channel. The/approvecommand now handles both exec and plugin approvals with automatic fallback. (#55339) Thanks @vaclavbelak and @joshavant. - ACP/channels: add current-conversation ACP binds for Discord, BlueBubbles, and iMessage so
/acp spawn codex --bind herecan turn the current chat into a Codex-backed workspace without creating a child thread, and document the distinction between chat surface, ACP session, and runtime workspace. - OpenAI/apply_patch: enable
apply_patchby default for OpenAI and OpenAI Codex models, and align its sandbox policy access withwritepermissions. - Plugins/CLI backends: move bundled Claude CLI, Codex CLI, and Gemini CLI inference defaults onto the plugin surface, add bundled Gemini CLI backend support, and replace
gateway run --claude-cli-logswith generic--cli-backend-logswhile keeping the old flag as a compatibility alias. - Plugins/startup: auto-load bundled provider and CLI-backend plugins from explicit config refs, so bundled Claude CLI, Codex CLI, and Gemini CLI message-provider setups no longer need manual
plugins.allowentries. - Podman: simplify the container setup around the current rootless user, install the launch helper under
~/.local/bin, and document the host-CLIopenclaw --container <name> ...workflow instead of a dedicatedopenclawservice user. - Slack/tool actions: add an explicit
upload-fileSlack action that routes file uploads through the existing Slack upload transport, with optional filename/title/comment overrides for channels and DMs. - Message actions/files: start unifying file-first sends on the canonical
upload-fileaction by adding explicit support for Microsoft Teams and Google Chat, and by exposing BlueBubbles file sends throughupload-filewhile keeping the legacysendAttachmentalias. - Plugins/Matrix TTS: send auto-TTS replies as native Matrix voice bubbles instead of generic audio attachments. (#37080) thanks @Matthew19990919.
- CLI: add
openclaw config schemato print the generated JSON schema foropenclaw.json. (#54523) Thanks @kvokka. - Config/TTS: auto-migrate legacy speech config on normal reads and secret resolution, keep legacy diagnostics for Doctor, and remove regular-mode runtime fallback for old bundled
tts.<provider>API-key shapes. - Memory/plugins: move the pre-compaction memory flush plan behind the active memory plugin contract so
memory-coreowns flush prompts and target-path policy instead of hardcoded core logic. - MiniMax: trim model catalog to M2.7 only, removing legacy M2, M2.1, M2.5, and VL-01 models. (#54487) Thanks @liyuan97.
- Plugins/runtime: expose
runHeartbeatOncein the plugin runtimesystemnamespace so plugins can trigger a single heartbeat cycle with an explicit delivery target override (e.g.heartbeat: { target: "last" }). (#40299) Thanks @loveyana. - Agents/compaction: preserve the post-compaction AGENTS refresh on stale-usage preflight compaction for both immediate replies and queued followups. (#49479) Thanks @jared596.
- Agents/compaction: surface safeguard-specific cancel reasons and relabel benign manual
/compactno-op cases as skipped instead of failed. (#51072) Thanks @afurm. - Docs: add
pnpm docs:check-links:anchorsfor Mintlify anchor validation while keepingscripts/docs-link-audit.mjsas the stable link-audit entrypoint. (#55912) Thanks @velvet-shark. - Tavily: mark outbound API requests with
X-Client-Source: openclawso Tavily can attribute OpenClaw-originated traffic. (#55335) Thanks @lakshyaag-tavily.
Fixes
- Agents/Anthropic: recover unhandled provider stop reasons (e.g.
sensitive) as structured assistant errors instead of crashing the agent run. (#56639) - Google/models: resolve Gemini 3.1 pro, flash, and flash-lite for all Google provider aliases by passing the actual runtime provider ID and adding a template-provider fallback; fix flash-lite prefix ordering. (#56567)
- OpenAI Codex/image tools: register Codex for media understanding and route image prompts through Codex instructions so image analysis no longer fails on missing provider registration or missing
instructions. (#54829) Thanks @neeravmakwana. - Agents/image tool: restore the generic image-runtime fallback when no provider-specific media-understanding provider is registered, so image analysis works again for providers like
openrouterandminimax-portal. (#54858) Thanks @MonkeyLeeT. - WhatsApp: fix infinite echo loop in self-chat DM mode where the bot's own outbound replies were re-processed as new inbound user messages. (#54570) Thanks @joelnishanth
- Telegram/splitting: replace proportional text estimate with verified HTML-length search so long messages split at word boundaries instead of mid-word; gracefully degrade when tag overhead exceeds the limit. (#56595)
- Telegram/delivery: skip whitespace-only and hook-blanked text replies in bot delivery to prevent GrammyError 400 empty-text crashes. (#56620)
- Telegram/send: validate
replyToMessageIdat all four API sinks with a shared normalizer that rejects non-numeric, NaN, and mixed-content strings. (#56587) - Mistral: normalize OpenAI-compatible request flags so official Mistral API runs no longer fail with remaining
422 status code (no body)chat errors. - Control UI/config: keep sensitive raw config hidden by default, replace the blank blocked editor with an explicit reveal-to-edit state, and restore raw JSON editing without auto-exposing secrets. Fixes #55322.
- CLI/zsh: defer
compdefregistration untilcompinitis available so zsh completion loads cleanly with plugin managers and manual setups. (#56555) - BlueBubbles/debounce: guard debounce flush against null message text by sanitizing at the enqueue boundary and adding an independent combiner guard. (#56573)
- Auto-reply: suppress JSON-wrapped
{"action":"NO_REPLY"}control envelopes before channel delivery with a strict single-key detector; preserves media when text is only a silent envelope. (#56612) - ACP/ACPX agent registry: align OpenClaw's ACPX built-in agent mirror with the latest
openclaw/acpxcommand defaults and built-in aliases, pin versionednpxbuilt-ins to exact versions, and stop unknown ACP agent ids from falling through to raw--agentcommand execution on the MCP-proxy path. (#28321) Thanks @m0nkmaster and @vincentkoc. - Security/audit: extend web search key audit to recognize Gemini, Grok/xAI, Kimi, Moonshot, and OpenRouter credentials via a boundary-safe bundled-web-search registry shim. (#56540)
- Docs/FAQ: remove broken Xfinity SSL troubleshooting cross-links from English and zh-CN FAQ entries — both sections already contain the full workaround inline. (#56500)
- Telegram: deliver verbose tool summaries inside forum topic sessions again, so threaded topic chats now match DM verbose behavior. (#43236) Thanks @frankbuild.
- BlueBubbles/CLI agents: restore inbound prompt image refs for CLI routed turns, reapply embedded runner image size guardrails, and cover both CLI image transport paths with regression tests. (#51373)
- BlueBubbles/groups: optionally enrich unnamed participant lists with local macOS Contacts names after group gating passes, so group member context can show names instead of only raw phone numbers.
- Discord/reconnect: drain stale gateway sockets, clear cached resume state before forced fresh reconnects, and fail closed when old sockets refuse to die so Discord recovery stops looping on poisoned resume state. (#54697) Thanks @ngutman.
- iMessage: stop leaking inline
[[reply_to:...]]tags into delivered text by sendingreply_toas RPC metadata and stripping stray directive tags from outbound messages. (#39512) Thanks @mvanhorn. - CLI/plugins: make routed commands use the same auto-enabled bundled-channel snapshot as gateway startup, so configured bundled channels like Slack load without requiring a prior config rewrite. (#54809) Thanks @neeravmakwana.
- CLI/message send: write manual
openclaw message senddeliveries into the resolved agent session transcript again by always threading the default CLI agent through outbound mirroring. (#54187) Thanks @KevInTheCloud5617. - CLI/onboarding: show the Kimi Code API key option again in the Moonshot setup menu so the interactive picker includes all Kimi setup paths together. Fixes #54412 Thanks @sparkyrider
- Agents/status: use provider-aware context window lookup for fresh Anthropic 4.6 model overrides so
/statusshows the correct 1.0m window instead of an underreported shared-cache minimum. (#54796) Thanks @neeravmakwana. - OpenAI/WebSocket: preserve reasoning replay metadata and tool-call item ids on WebSocket tool turns, and start a fresh response chain when full-context resend is required. (#53856) Thanks @xujingchen1996.
- OpenAI/WS: restore reasoning blocks for Responses WebSocket runs and keep reasoning/tool-call replay metadata intact so resumed sessions do not lose or break follow-up reasoning-capable turns. (#53856) Thanks @xujingchen1996.
- Agents/errors: surface provider quota/reset details when available, but keep HTML/Cloudflare rate-limit pages on the generic fallback so raw error pages are not shown to users. (#54512) Thanks @bugkill3r.
- Claude CLI: switch the bundled Claude CLI backend to
stream-jsonoutput so watchdogs see progress on long runs, and keep session/usage metadata even when Claude finishes with an empty result line. (#49698) Thanks @felear2022. - Claude CLI/MCP: always pass a strict generated
--mcp-configoverlay for background Claude CLI runs, including the empty-server case, so Claude does not inherit ambient user/global MCP servers. (#54961) Thanks @markojak. - Agents/embedded replies: surface mid-turn 429 and overload failures when embedded runs end without a user-visible reply, while preserving successful media-only replies that still use legacy
mediaUrl. (#50930) Thanks @infichen. - Chat/UI: move the chat send button onto the shared ghost-button theme styling, while keeping the stop button icon readable on the danger state. (#55075) Thanks @bottenbenny.
- WhatsApp/allowFrom: show a specific allowFrom policy error for valid blocked targets instead of the misleading
<E.164|group JID>format hint. Thanks @mcaxtr. - Agents/cooldowns: scope rate-limit cooldowns per model so one 429 no longer blocks every model on the same auth profile, replace the exponential 1 min -> 1 h escalation with a stepped 30 s / 1 min / 5 min ladder, and surface a user-facing countdown message when all models are rate-limited. (#49834) Thanks @kiranvk-2011.
- Agents/embedded transport errors: distinguish common network failures like connection refused, DNS lookup failure, and interrupted sockets from true timeouts in embedded-run user messaging and lifecycle diagnostics. (#51419) Thanks @scoootscooob.
- Telegram/pairing: ignore self-authored DM
messageupdates so bot-pinned status cards and similar service updates do not trigger bogus pairing requests or re-enter inbound dispatch. (#54530) thanks @huntharo - Mattermost/replies: keep pairing replies, slash-command fallback replies, and model-picker messages on the resolved config path so
exec:SecretRef bot tokens work across all outbound reply branches. (#48347) thanks @mathiasnagler. - Microsoft Teams/config: accept the existing
welcomeCard,groupWelcomeCard,promptStarters, and feedback/reflection keys in strict config validation so already-supported Teams runtime settings stop failing schema checks. (#54679) Thanks @gumclaw. - MCP/channels: add a Gateway-backed channel MCP bridge with Codex/Claude-facing conversation tools, Claude channel notifications, and safer stdio bridge lifecycle handling for reconnects and routed session discovery.
- Plugins/SDK: thread
moduleUrlthrough plugin-sdk alias resolution so user-installed plugins outside the openclaw directory (e.g.~/.openclaw/extensions/) correctly resolveopenclaw/plugin-sdk/*subpath imports, and gateplugin-sdk:check-exportsinrelease:check. (#54283) Thanks @xieyongliang. - Config/web fetch: allow the documented
tools.web.fetch.maxResponseBytessetting in runtime schema validation so valid configs no longer fail with unrecognized-key errors. (#53401) Thanks @erhhung. - Message tool/buttons: keep the shared
buttonsschema optional in merged tool definitions so plainaction=sendcalls stop failing validation when no buttons are provided. (#54418) Thanks @adzendo. - Agents/openai-compatible tool calls: deduplicate repeated tool call ids across live assistant messages and replayed history so OpenAI-compatible backends no longer reject duplicate
tool_call_idvalues with HTTP 400. (#40996) Thanks @xaeon2026. - Models/openai-completions: default non-native OpenAI-compatible providers to omit tool-definition
strictfields unless users explicitly opt back in, so tool calling keeps working on providers that reject that option. (#45497) Thanks @sahancava. - Plugins/context engines: retry strict legacy
assemble()calls without the newpromptfield when older engines reject it, preserving prompt-aware retrieval compatibility for pre-prompt plugins. (#50848) thanks @danhdoan. - CLI/update status: explicitly say
up to datewhen the local version already matches npm latest, while keeping the availability logic unchanged. (#51409) Thanks @dongzhenye. - Daemon/Linux: stop flagging non-gateway systemd services as duplicate gateways just because their unit files mention OpenClaw, reducing false-positive doctor/log noise. (#45328) Thanks @gregretkowski.
- Feishu: close WebSocket connections on monitor stop/abort so ghost connections no longer persist, preventing duplicate event processing and resource leaks across restart cycles. (#52844) Thanks @schumilin.
- Feishu: use the original message
create_timeinstead ofDate.now()for inbound timestamps so offline-retried messages carry the correct authoring time, preventing mis-targeted agent actions on stale instructions. (#52809) Thanks @schumilin. - Control UI/Skills: open skill detail dialogs with the browser modal lifecycle so clicking a skill row keeps the panel centered instead of rendering it off-screen at the bottom of the page.
- Matrix/replies: include quoted poll question/options in inbound reply context so the agent sees the original poll content when users reply to Matrix poll messages. (#55056) Thanks @alberthild.
- Matrix/plugins: keep plugin bootstrap from crashing when built runtime mixes bare and deep
matrix-js-sdkentrypoints, so unrelated channels do not get taken down during plugin load. (#56273) Thanks @aquaright1. - Agents/sandbox: honor
tools.sandbox.tools.alsoAllow, let explicit sandbox re-allows remove matching built-in default-deny tools, and keep sandbox explain/error guidance aligned with the effective sandbox tool policy. (#54492) Thanks @ngutman. - Agents/sandbox: make blocked-tool guidance glob-aware again, redact/sanitize session-specific explain hints for safer copy-paste, and avoid leaking control-character session keys in those hints. (#54684) Thanks @ngutman.
- Agents/compaction: trigger timeout recovery compaction before retrying high-context LLM timeouts so embedded runs stop repeating oversized requests. (#46417) thanks @joeykrug.
- Agents/compaction: reconcile
sessions.json.compactionCountafter a late embedded auto-compaction success so persisted session counts catch up once the handler reports completion. (#45493) Thanks @jackal092927. - Agents/failover: classify Codex accountId token extraction failures as auth errors so model fallback continues to the next configured candidate. (#55206) Thanks @cosmicnet.
- Plugins/runtime: reuse only compatible active plugin registries across tools, providers, web search, and channel bootstrap, align
/tools/invokeplugin loading with the session workspace, and retry outbound channel recovery when the pinned channel surface changes so plugin tools and channels stop disappearing or re-registering from mismatched runtime loads. Thanks @gumadeiras. - Talk/macOS: stop direct system-voice failures from replaying system speech, use app-locale fallback for shared watchdog timing, and add regression coverage for the macOS fallback route and language-aware timeout policy. (#53511) thanks @hongsw.
- Discord/gateway cleanup: keep late Carbon reconnect-exhausted errors suppressed through startup/dispose cleanup so Discord monitor shutdown no longer crashes on late gateway close events. (#55373) Thanks @Takhoffman.
- Discord/gateway shutdown: treat expected reconnect-exhausted events during intentional lifecycle stop as clean shutdowns so startup-abort cleanup no longer surfaces false gateway failures. (#55324) Thanks @joelnishanth.
- Discord/gateway shutdown: suppress reconnect-exhausted events that were already buffered before teardown flips
lifecycleStopping, so stale-socket Discord restarts no longer crash the whole gateway. Fixes #55403 and #55421. Thanks @lml2468 and @vincentkoc. - GitHub Copilot/auth refresh: treat large
expires_atvalues as seconds epochs and clamp far-future runtime auth refresh timers so Copilot token refresh cannot fall into asetTimeoutoverflow hot loop. (#55360) Thanks @michael-abdo. - Agents/status: use the persisted runtime session model in
session_statuswhen no explicit override exists, and honor per-agentthinkingDefaultin bothsession_statusand/status. (#55425) Thanks @scoootscooob, @xaeon2026, and @ysfbsf. - Heartbeat/runner: guarantee the interval timer is re-armed after heartbeat runs and unexpected runner errors so scheduled heartbeats do not silently stop after an interrupted cycle. (#52270) Thanks @MiloStack.
- Config/Doctor: rewrite stale bundled plugin load paths from legacy
extensions/*locations to the packaged bundled path, including directory-name mismatches and slash-suffixed config entries. (#55054) Thanks @SnowSky1. - WhatsApp/mentions: stop treating mentions embedded in quoted messages as direct mentions so replying to a message that @mentioned the bot no longer falsely triggers mention gating. (#52711) Thanks @lurebat.
- Matrix: keep separate 2-person rooms out of DM routing after
m.directseeds successfully, while still honoring explicitis_directstate and startup fallback recovery. (#54890) thanks @private-peter - Agents/ollama fallback: surface non-2xx Ollama HTTP errors with a leading status code so HTTP 503 responses trigger model fallback again. (#55214) Thanks @bugkill3r.
- Feishu/tools: stop synthetic agent ids like
agent-spawnerfrom being treated as Feishu account ids during tool execution, so tools fall back to the configured/default Feishu account unless the contextual id is a real enabled Feishu account. (#55627) Thanks @MonkeyLeeT. - Google/tools: strip empty
required: []arrays from Gemini tool schemas so optional-only tool parameters no longer trigger Google validator 400s. (#52106) Thanks @oliviareid-svg. - Onboarding/TUI/local gateways: show the resolved gateway port in setup output, clarify no-daemon local health/dashboard messaging, and preserve loopback Control UI auth on reruns and explicit local gateway URLs so local quickstart flows recover cleanly. (#55730) Thanks @shakkernerd.
- TUI/chat log: keep system messages as single logical entries and prune overflow at whole-message boundaries so wrapped system spacing stays intact. (#55732) Thanks @shakkernerd.
- TUI/activation: validate
/activationarguments in the TUI and reject invalid values instead of silently coercing them tomention. (#55733) Thanks @shakkernerd. - Agents/model switching: apply
/modelchanges to active embedded runs at the next safe retry boundary, so overloaded or retrying turns switch to the newly selected model instead of staying pinned to the old provider. - Agents/Codex fallback: classify Codex
server_errorpayloads as failoverable, sanitizeCodex error:payloads before they reach chat, preserve context-overflow guidance for prefixedinvalid_request_errorpayloads, and omit providerrequest_idvalues from user-facing UI copy. (#42892) Thanks @xaeon2026. - Memory/search: share memory embedding provider registrations across split plugin runtimes so memory search no longer fails with unknown provider errors after memory-core registers built-in adapters. (#55945) Thanks @glitch418x.
- Discord/Carbon beta: update
@buape/carbonto the latest beta and pass the newRateLimitErrorrequest argument so Discord stays compatible with the upstream beta constructor change. (#55980) Thanks @ngutman. - Plugins/inbound claims: pass full inbound attachment arrays through
inbound_claimhook metadata while keeping the legacy singular media attachment fields for compatibility. (#55452) Thanks @huntharo. - Plugins/Matrix: preserve sender filenames for inbound media by forwarding
originalFilenametosaveMediaBuffer. (#55692) thanks @esrehmki. - Matrix/mentions: recognize
matrix.tomentions whose visible label uses the bot's room display name, sorequireMention: truerooms respond correctly in modern Matrix clients. (#55393) thanks @nickludlam. - Ollama/thinking off: route
thinkingLevel=offthrough the live Ollama extension request path so thinking-capable Ollama models now receive top-levelthink: falseinstead of silently generating hidden reasoning tokens. (#53200) Thanks @BruceMacD. - Plugins/diffs: stage bundled
@pierre/diffsruntime dependencies during packaged updates so the bundled diff viewer keeps loading after global installs and updates. (#56077) Thanks @gumadeiras. - Plugins/diffs: load bundled Pierre themes without JSON module imports so diff rendering keeps working on newer Node builds. (#45869) thanks @NickHood1984.
- Plugins/uninstall: remove owned
channels.<id>config when uninstalling channel plugins, and keep the uninstall preview aligned with explicit channel ownership so built-in channels and shared keys stay intact. (#35915) Thanks @wbxl2000. - Plugins/Matrix: prefer explicit DM signals when choosing outbound direct rooms and routing unmapped verification summaries, so strict 2-person fallback rooms do not outrank the real DM. (#56076) thanks @gumadeiras
- Plugins/Matrix: resolve env-backed
accessTokenandpasswordSecretRefs against the active Matrix config env path during startup, and officially accept SecretRefaccessTokenconfig values. (#54980) thanks @kakahu2015. - Microsoft Teams/proactive DMs: prefer the freshest personal conversation reference for
user:<aadObjectId>sends when multiple stored references exist, so replies stop targeting stale DM threads. (#54702) Thanks @gumclaw. - Gateway/plugins: reuse the session workspace when building HTTP
/tools/invoketool lists and harden tool construction to infer the session agent workspace by default, so workspace plugins do not re-register on repeated HTTP tool calls. (#56101) thanks @neeravmakwana - Brave/web search: normalize unsupported Brave
countryfilters toALLbefore request and cache-key generation so locale-derived values likeVNstop failing with upstream 422 validation errors. (#55695) Thanks @chen-zhang-cs-code. - Discord/replies: preserve leading indentation when stripping inline reply tags so reply-tagged plain text and fenced code blocks keep their formatting. (#55960) Thanks @Nanako0129.
- Daemon/status: surface immediate gateway close reasons from lightweight probes and prefer those concrete auth or pairing failures over generic timeouts in
openclaw daemon status. (#56282) Thanks @mbelinky. - Agents/failover: classify HTTP 410 errors as retryable timeouts by default while still preserving explicit session-expired, billing, and auth signals from the payload. (#55201) thanks @nikus-pan.
- Agents/subagents: restore completion announce delivery for extension channels like BlueBubbles. (#56348)
- Plugins/Matrix: load bundled
@matrix-org/matrix-sdk-crypto-nodejsthroughcreateRequire(...)so E2EE media send and receive keep the package-local native binding lookup working in packaged ESM builds. (#54566) thanks @joelnishanth. - Plugins/Matrix: encrypt E2EE image thumbnails with
thumbnail_filewhile keeping unencrypted-room previews onthumbnail_url, so encrypted Matrix image events keep thumbnail metadata without leaking plaintext previews. (#54711) thanks @frischeDaten. - Telegram/forum topics: keep native
/newand/resetrouted to the active topic by preserving the topic target on forum-thread command context. (#35963)

