Breaking

• Nodes/exec: remove the duplicated nodes.run shell wrapper from the CLI and agent nodes tool so node shell execution always goes through exec host=node, keeping node-specific capabilities on nodes invoke and the dedicated media/location/notify actions.
• Plugin SDK: deprecate the legacy provider compat subpaths plus the older bundled provider setup and channel-runtime compatibility shims, emit migration warnings, and keep the current documented openclaw/plugin-sdk/* entrypoints plus local api.ts / runtime-api.ts barrels as the forward path ahead of a future major-release removal.
• Skills/install and Plugins/install: built-in dangerous-code critical findings and install-time scan failures now fail closed by default, so plugin installs and gateway-backed skill dependency installs that previously succeeded may now require an explicit dangerous override such as --dangerously-force-unsafe-install to proceed.
• Gateway/auth: trusted-proxy now rejects mixed shared-token configs, and local-direct fallback requires the configured token instead of implicitly authenticating same-host callers. Thanks @zhangning-agent, @jacobtomlinson, and @vincentkoc.
• Gateway/node commands: node commands now stay disabled until node pairing is approved, so device pairing alone is no longer enough to expose declared node commands. (#57777) Thanks @jacobtomlinson.
• Gateway/node events: node-originated runs now stay on a reduced trusted surface, so notification-driven or node-triggered flows that previously relied on broader host/session tool access may need adjustment. (#57691) Thanks @jacobtomlinson.

Changes

• ACP/plugins: add an explicit default-off ACPX plugin-tools MCP bridge config, document the trust boundary, and harden the built-in bridge packaging/logging path so global installs and stdio MCP sessions work reliably. (#56867) Thanks @joe2643.
• Agents/LLM: add a configurable idle-stream timeout for embedded runner requests so stalled model streams abort cleanly instead of hanging until the broader run timeout fires. (#55072) Thanks @liuy.
• Agents/MCP: materialize bundle MCP tools with provider-safe names (serverName__toolName), support optional streamable-http transport selection plus per-server connection timeouts, and preserve real tool results from aborted/error turns unless truncation explicitly drops them. (#49505) Thanks @ziomancer.
• Android/notifications: add notification-forwarding controls with package filtering, quiet hours, rate limiting, and safer picker behavior for forwarded notification events. (#40175) Thanks @nimbleenigma.
• Background tasks: turn tasks into a real shared background-run control plane instead of ACP-only bookkeeping by unifying ACP, subagent, cron, and background CLI execution under one SQLite-backed ledger, routing detached lifecycle updates through the executor seam, adding audit/maintenance/status visibility, tightening auto-cleanup and lost-run recovery, improving task awareness in internal status/tool surfaces, and clarifying the split between heartbeat/main-session automation and detached scheduled runs. Thanks @mbelinky and @vincentkoc.
• Background tasks: add the first linear task flow control surface with openclaw flows list|show|cancel, keep manual multi-task flows separate from one-task auto-sync flows, and surface doctor recovery hints for obviously orphaned or broken flow/task linkage. Thanks @mbelinky and @vincentkoc.
• Channels/QQ Bot: add QQ Bot as a bundled channel plugin with multi-account setup, SecretRef-aware credentials, slash commands, reminders, and media send/receive support. (#52986) Thanks @sliverp.
• Diffs: skip unused viewer-versus-file SSR preload work so diffs view-only and file-only runs do less render work while keeping mode outputs aligned. (#57909) thanks @gumadeiras.
• Tasks: add a minimal SQLite-backed task flow registry plus task-to-flow linkage scaffolding, so orchestrated work can start gaining a first-class parent record without changing current task delivery behavior. Thanks @mbelinky and @vincentkoc.
• Tasks: persist blocked state on one-task task flows and let the same flow reopen cleanly on retry, so blocked detached work can carry a parent-level reason and continue without fragmenting into a new job. Thanks @mbelinky and @vincentkoc.
• Tasks: route one-task ACP and subagent updates through a parent task-flow owner context, so detached work can emerge back through the intended parent thread/session instead of speaking only as a raw child task. Thanks @mbelinky and @vincentkoc.
• LINE/outbound media: add LINE image, video, and audio outbound sends on the LINE-specific delivery path, including explicit preview/tracking handling for videos while keeping generic media sends on the existing image-only route. (#45826) Thanks @masatohoshino.
• Matrix/history: add optional room history context for Matrix group triggers via channels.matrix.historyLimit, with per-agent watermarks and retry-safe snapshots so failed trigger retries do not drift into newer room messages. (#57022) thanks @chain710.
• Matrix/network: add explicit channels.matrix.proxy config for routing Matrix traffic through an HTTP(S) proxy, including account-level overrides and matching probe/runtime behavior. (#56931) thanks @patrick-yingxi-pan.
• Matrix/streaming: add draft streaming so partial Matrix replies update the same message in place instead of sending a new message for each chunk. (#56387) Thanks @jrusz.
• Matrix/threads: add per-DM threadReplies overrides and keep thread session isolation aligned with the effective room or DM thread policy from the triggering message onward. (#57995) thanks @teconomix.
• MCP: add remote HTTP/SSE server support for mcp.servers URL configs, including auth headers and safer config redaction for MCP credentials. (#50396) Thanks @dhananjai1729.
• Memory/QMD: add per-agent memorySearch.qmd.extraCollections so agents can opt into cross-agent session search without flattening every transcript collection into one shared QMD namespace. Thanks @vincentkoc.
• Microsoft Teams/member info: add a Graph-backed member info action so Teams automations and tools can resolve channel member details directly from Microsoft Graph. (#57528) Thanks @sudie-codes.
• Nostr/inbound DMs: verify inbound event signatures before pairing or sender-authorization side effects, so forged DM events no longer create pairing requests or trigger reply attempts. Thanks @smaeljaish771 and @vincentkoc.
• OpenAI/Responses: forward configured text.verbosity across Responses HTTP and WebSocket transports, surface it in /status, and keep per-agent verbosity precedence aligned with runtime behavior. (#47106) Thanks @merc1305 and @vincentkoc.
• Pi/Codex: add native Codex web search support for embedded Pi runs, including config/docs/wizard coverage and managed-tool suppression when native Codex search is active. (#46579) Thanks @Evizero.
• Slack/exec approvals: add native Slack approval routing and approver authorization so exec approval prompts can stay in Slack instead of falling back to the Web UI or terminal. Thanks @vincentkoc.
• TTS: Add structured provider diagnostics and fallback attempt analytics. (#57954) Thanks @joshavant.
• WhatsApp/reactions: agents can now react with emoji on incoming WhatsApp messages, enabling more natural conversational interactions like acknowledging a photo with ❤️ instead of typing a reply. Thanks @mcaxtr.
• Agents/BTW: force /btw side questions to disable provider reasoning so Anthropic adaptive-thinking sessions stop failing with No BTW response generated. Fixes #55376. Thanks @Catteres and @vincentkoc.
• CLI/onboarding: reset the remote gateway URL prompt to the safe loopback default after declining a discovered endpoint, so onboarding does not keep a previously rejected remote URL. (#57828)
• Agents/exec defaults: honor per-agent tools.exec defaults when no inline directive or session override is present, so configured exec host, security, ask, and node settings actually apply. (#57689)
• Sandbox/networking: sanitize SSH subprocess env vars through the shared sandbox policy and route marketplace archive downloads plus Ollama discovery, auth, and pull requests through the guarded fetch path so sandboxed execution and remote fetches follow the repo's trust boundaries. (#57848, #57850)

Fixes

• Slack: stop retry-driven duplicate replies when draft-finalization edits fail ambiguously, and log configured allowlisted users/channels by readable name instead of raw IDs.
• Agents/OpenAI Responses: normalize raw bundled MCP tool schemas on the WebSocket/Responses path so bare-object, object-ish, and top-level union MCP tools no longer get rejected by OpenAI during tool registration. (#58299) Thanks @yelog.
• ACP/security: replace ACP's dangerous-tool name override with semantic approval classes, so only narrow readonly reads/searches can auto-approve while indirect exec-capable and control-plane tools always require explicit prompt approval. Thanks @vincentkoc.
• ACP/sessions_spawn: register ACP child runs for completion tracking and lifecycle cleanup, and make registration-failure cleanup explicitly best-effort so callers do not assume an already-started ACP turn was fully aborted. (#40885) Thanks @xaeon2026 and @vincentkoc.
• ACP/tasks: mark cleanly exited ACP runs as blocked when they end on deterministic write or authorization blockers, and wake the parent session with a follow-up instead of falsely reporting success.
• ACPX/runtime: derive the bundled ACPX expected version from the extension package metadata instead of hardcoding a separate literal, so plugin-local ACPX installs stop drifting out of health-check parity after version bumps. (#49089) Thanks @jiejiesks and @vincentkoc.
• Agents/Anthropic failover: treat Anthropic api_error payloads with An unexpected error occurred while processing the response as transient so retry/fallback can engage instead of surfacing a terminal failure. (#57441) Thanks @zijiess and @vincentkoc.
• Agents/compaction: keep late compaction-retry completions from double-resolving finished compaction futures, so interrupted or timed-out compactions stop surfacing spurious second-completion races. (#57796) Thanks @joshavant.
• Agents/disabled providers: make disabled providers disappear from default model selection and embedded provider fallback, while letting explicitly pinned disabled providers fail with a clear config error instead of silently taking traffic. (#57735) Thanks @rileybrown-dev and @vincentkoc.
• Agents/OAuth output: force exec-host OAuth output readers through the gateway fs policy so embedded gateway runs stop crashing when provider auth writes land outside the current sandbox workspace. (#58249) Thanks @joshavant.
• Agents/system prompt: fix agent.name interpolation in the embedded runtime system prompt and make provider/model fallback text reflect the effective runtime selection after start. (#57625) Thanks @StllrSvr and @vincentkoc.
• Android/device info: read the app's version metadata from the package manager instead of hidden APIs so Android 15+ onboarding and device info no longer fail to compile or report placeholder values. (#58126) Thanks @L3ER0Y.
• Android/pairing: stop appending duplicate push receiver entries to gateway-service.conf on repeated QR pairing and keep push registration bounded to the current successful pairing, so Android push delivery stays healthy across re-pair and token rotation. (#58256) Thanks @surrealroad.
• App install smoke: pin the latest-release lookup to latest, cache the first stable install version across the rerun, and relax prerelease package assertions so the Parallels smoke lane can validate stable-to-main upgrades even when beta moves ahead or the guest starts from an older stable. (#58177) Thanks @vincentkoc.
• Auth/profiles: keep the last successful config load in memory for the running process and refresh that snapshot on successful writes/reloads, so hot paths stop reparsing openclaw.json between watcher-driven swaps.
• Config/SecretRef + Control UI: harden SecretRef redaction round-trip restore, block unsafe raw fallback (force Form mode when raw is unavailable), and preflight submitted-config SecretRefs before config write RPC persistence. (#58044) Thanks @joshavant.
• Config/Telegram: migrate removed channels.telegram.groupMentionsOnly into channels.telegram.groups[\"*\"].requireMention on load so legacy configs no longer crash at startup. (#55336) thanks @jameslcowan.
• Config/update: stop openclaw doctor write-backs from persisting plugin-injected channel defaults, so openclaw update no longer seeds config keys that later break service refresh validation. (#56834) Thanks @openperf.
• Control UI/agents: auto-load agent workspace files on initial Files panel open, and populate overview model/workspace/fallbacks from effective runtime agent metadata so defaulted models no longer show as Not set. (#56637) Thanks @dxsx84.
• Control UI/slash commands: make /steer and /redirect work from the chat command palette with visible pending state for active-run /steer, correct redirected-run tracking, and a single canonical /steer entry in the command menu. (#54625) Thanks @fuller-stack-dev.
• Cron/announce: preserve all deliverable text payloads for announce mode instead of collapsing to the last chunk, so multi-line cron reports deliver in full to Telegram forum topics.
• Cron/isolated sessions: carry the full live-session provider, model, and auth-profile selection across retry restarts so cron jobs with model overrides no longer fail or loop on mid-run model-switch requests. (#57972) Thanks @issaba1.
• Diffs/config: preserve schema-shaped plugin config parsing from diffsPluginConfigSchema.safeParse(), so direct callers keep defaults and security sections instead of receiving flattened tool defaults. (#57904) Thanks @gumadeiras.
• Diffs: fall back to plain text when lang hints are invalid during diff render and viewer hydration, so bad or stale language values no longer break the diff viewer. (#57902) Thanks @gumadeiras.
• Discord/voice: enforce the same guild channel and member allowlist checks on spoken voice ingress before transcription, so joined voice channels no longer accept speech from users outside the configured Discord access policy. Thanks @cyjhhh and @vincentkoc.
• Docker/setup: force BuildKit for local image builds (including sandbox image builds) so ./docker-setup.sh no longer fails on RUN --mount=... when hosts default to Docker's legacy builder. (#56681) Thanks @zhanghui-china.
• Docs/anchors: fix broken English docs links and make Mint anchor audits run against the English-source docs tree. (#57039) thanks @velvet-shark.
• Doctor/plugins: skip false Matrix legacy-helper warnings when no migration plans exist, and keep bundled enabledByDefault plugins in the gateway startup set. (#57931) Thanks @dinakars777.
• Exec approvals/macOS: unwrap arch and xcrun before deriving shell payloads and allow-always patterns, so wrapper approvals stay bound to the carried command instead of the outer carrier. Thanks @tdjackey and @vincentkoc.
• Exec approvals: unwrap caffeinate and sandbox-exec before persisting allow-always trust so later shell payload changes still require a fresh approval. Thanks @tdjackey and @vincentkoc.
• Exec/approvals: infer Discord and Telegram exec approvers from existing owner config when execApprovals.approvers is unset, extend the default approval window to 30 minutes, and clarify approval-unavailable guidance so approvals do not appear to silently disappear.
• Pi/TUI: flush message-boundary replies at message_end so turns stop looking stuck until the next nudge when the final reply was already ready. Thanks @vincentkoc.
• Exec/approvals: keep awk and sed family binaries out of the low-risk safeBins fast path, and stop doctor profile scaffolding from treating them like ordinary custom filters. Thanks @vincentkoc.
• Exec/env: block proxy, TLS, and Docker endpoint env overrides in host execution so request-scoped commands cannot silently reroute outbound traffic or trust attacker-supplied certificate settings. Thanks @AntAISecurityLab.
• Exec/env: block Python package index override variables from request-scoped host exec environment sanitization so package fetches cannot be redirected through a caller-supplied index. Thanks @nexrin and @vincentkoc.
• Exec/node: stop gateway-side workdir fallback from rewriting explicit host=node cwd values to the gateway filesystem, so remote node exec approval and runs keep using the intended node-local directory. (#50961) Thanks @openperf.
• Exec/runtime: default implicit exec to host=auto, resolve that target to sandbox only when a sandbox runtime exists, keep explicit host=sandbox fail-closed without sandbox, and show /exec effective host state in runtime status/docs.
• Exec: fail closed when the implicit sandbox host has no sandbox runtime, and stop denied async approval followups from reusing prior command output from the same session. (#56800) Thanks @scoootscooob.
• Feishu/groups: keep quoted replies and topic bootstrap context aligned with group sender allowlists so only allowlisted thread messages seed agent context. Thanks @AntAISecurityLab and @vincentkoc.
• Gateway/attachments: offload large inbound images without leaking media:// markers into text-only runs, preserve mixed attachment order for model input/transcripts, and fail closed when model image capability cannot be resolved. (#55513) Thanks @Syysean.
• Gateway/auth: keep shared-auth rate limiting active during WebSocket handshake attempts even when callers also send device-token candidates, so bogus device-token fields no longer suppress shared-secret brute-force tracking. Thanks @kexinoh and @vincentkoc.
• Gateway/auth: reject mismatched browser Origin headers on trusted-proxy HTTP operator requests while keeping origin-less headless proxy clients working. Thanks @AntAISecurityLab and @vincentkoc.
• Gateway/device tokens: disconnect active device sessions after token rotation so newly rotated credentials revoke existing live connections immediately instead of waiting for those sockets to close naturally. Thanks @zsxsoft and @vincentkoc.
• Gateway/health: carry webhook-vs-polling account mode from channel descriptors into runtime snapshots so passive channels like LINE and BlueBubbles skip false stale-socket health failures. (#47488) Thanks @karesansui-u.
• Gateway/pairing: restore QR bootstrap onboarding handoff so fresh /pair qr iPhone setup can auto-approve the initial node pairing, receive a reusable node device token, and stop retrying with spent bootstrap auth. (#58382) Thanks @ngutman.
• Gateway/OpenAI compatibility: accept flat Responses API function tool definitions on /v1/responses and preserve strict when normalizing hosted tools into the embedded runner, so spec-compliant clients like Codex no longer fail validation or silently lose strict tool enforcement. Thanks @malaiwah and @vincentkoc.
• Gateway/OpenAI HTTP: restore default operator scopes for bearer-authenticated requests that omit x-openclaw-scopes, so headless /v1/chat/completions and session-history callers work again after the recent method-scope hardening. (#57596) Thanks @openperf.
• Gateway/plugins: scope plugin-auth HTTP route runtime clients to read-only access and keep gateway-authenticated plugin routes on write scope, so plugin-owned webhook handlers do not inherit write-capable runtime access by default. Thanks @davidluzsilva and @vincentkoc.
• Gateway/SecretRef: resolve restart token drift checks with merged service/runtime env sources and hard-fail unsupported mutable SecretRef plus OAuth-profile combinations so restart warnings and policy enforcement match runtime behavior. (#58141) Thanks @joshavant.
• Gateway/tools HTTP: tighten HTTP tool-invoke authorization so owner-only tools stay off HTTP invoke paths. (#57773) Thanks @jacobtomlinson.
• Harden async approval followup delivery in webchat-only sessions (#57359) Thanks @joshavant.
• Heartbeat/auth: prevent exec-event heartbeat runs from inheriting owner-only tool access from the session delivery target, so node exec output stays on the non-owner tool surface even when the target session belongs to the owner. Thanks @AntAISecurityLab and @vincentkoc.
• Hooks/config: accept runtime channel plugin ids in hooks.mappings[].channel (for example feishu) instead of rejecting non-core channels during config validation. (#56226) Thanks @AiKrai001.
• Hooks/session routing: rebind hook-triggered agent: session keys to the actual target agent before isolated dispatch so dedicated hook agents keep their own session-scoped tool and plugin identity. Thanks @kexinoh and @vincentkoc.
• Host exec/env: block additional request-scoped env overrides that can redirect Docker endpoints, trust roots, compiler include paths, package resolution, or Python environment roots during approved host runs. Thanks @tdjackey and @vincentkoc.
• Image generation/build: write stable runtime alias files into dist/ and route provider-auth runtime lookups through those aliases so image-generation providers keep resolving auth/runtime modules after rebuilds instead of crashing on missing hashed chunk files.
• iOS/Live Activities: mark the ActivityKit import in LiveActivityManager.swift as @preconcurrency so Xcode 26.4 / Swift 6 builds stop failing on strict concurrency checks. (#57180) Thanks @ngutman.
• LINE/ACP: add current-conversation binding and inbound binding-routing parity so /acp spawn ... --thread here, configured ACP bindings, and active conversation-bound ACP sessions work on LINE like the other conversation channels.
• LINE/markdown: preserve underscores inside Latin, Cyrillic, and CJK words when stripping markdown, while still removing standalone _italic_ markers on the shared text-runtime path used by LINE and TTS. (#47465) Thanks @jackjin1997.
• Agents/failover: make overloaded same-provider retry count and retry delay configurable via auth.cooldowns, default to one retry with no delay, and document the model-fallback behavior.

View full changelog

Breaking

• Providers/Qwen: remove the deprecated qwen-portal-auth OAuth integration for portal.qwen.ai; migrate to Model Studio with openclaw 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_search setup during openclaw onboard and openclaw configure --section web, including an x_search model picker with the shared xAI key.
• MiniMax: add image generation provider for image-01 model, supporting generate and image-to-image editing with aspect ratio control. (#54487) Thanks @liyuan97.
• Plugins/hooks: add async requireApproval to before_tool_call hooks, letting plugins pause tool execution and prompt the user for approval via the exec approval overlay, Telegram buttons, Discord interactions, or the /approve command on any channel. The /approve command 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 here can 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_patch by default for OpenAI and OpenAI Codex models, and align its sandbox policy access with write permissions.
• 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-logs with generic --cli-backend-logs while 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.allow entries.
• Podman: simplify the container setup around the current rootless user, install the launch helper under ~/.local/bin, and document the host-CLI openclaw --container ... workflow instead of a dedicated openclaw service user.
• Slack/tool actions: add an explicit upload-file Slack 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-file action by adding explicit support for Microsoft Teams and Google Chat, and by exposing BlueBubbles file sends through upload-file while keeping the legacy sendAttachment alias.
• Plugins/Matrix TTS: send auto-TTS replies as native Matrix voice bubbles instead of generic audio attachments. (#37080) thanks @Matthew19990919.
• CLI: add openclaw config schema to print the generated JSON schema for openclaw.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. API-key shapes.
• Memory/plugins: move the pre-compaction memory flush plan behind the active memory plugin contract so memory-core owns 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 runHeartbeatOnce in the plugin runtime system namespace 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 /compact no-op cases as skipped instead of failed. (#51072) Thanks @afurm.
• Docs: add pnpm docs:check-links:anchors for Mintlify anchor validation while keeping scripts/docs-link-audit.mjs as the stable link-audit entrypoint. (#55912) Thanks @velvet-shark.
• Tavily: mark outbound API requests with X-Client-Source: openclaw so 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 openrouter and minimax-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 replyToMessageId at 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 compdef registration until compinit is 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/acpx command defaults and built-in aliases, pin versioned npx built-ins to exact versions, and stop unknown ACP agent ids from falling through to raw --agent command 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 sending reply_to as 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 send deliveries 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 /status shows 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-json output 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-config overlay 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 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 message updates 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 moduleUrl through plugin-sdk alias resolution so user-installed plugins outside the openclaw directory correctly resolve openclaw/plugin-sdk/* subpath imports, and gate plugin-sdk:check-exports in release:check. (#54283) Thanks @xieyongliang.
• Config/web fetch: allow the documented tools.web.fetch.maxResponseBytes setting in runtime schema validation so valid configs no longer fail with unrecognized-key errors. (#53401) Thanks @erhhung.
• Message tool/buttons: keep the shared buttons schema optional in merged tool definitions so plain action=send calls 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_id values with HTTP 400. (#40996) Thanks @xaeon2026.
• Models/openai-completions: default non-native OpenAI-compatible providers to omit tool-definition strict fields 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 new prompt field when older engines reject it, preserving prompt-aware retrieval compatibility for pre-prompt plugins. (#50848) thanks @danhdoan.
• CLI/update status: explicitly say up to date when 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_time instead of Date.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-sdk entrypoints, 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.compactionCount after 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/invoke plugin 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_at values as seconds epochs and clamp far-future runtime auth refresh timers so Copilot token refresh cannot fall into a setTimeout overflow hot loop. (#55360) Thanks @michael-abdo.
• Agents/status: use the persisted runtime session model in session_status when no explicit override exists, and honor per-agent thinkingDefault in both session_status and /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 bundled-plugin 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.direct seeds successfully, while still honoring explicit is_direct state 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-spawner from 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 /activation arguments in the TUI and reject invalid values instead of silently coercing them to mention. (#55733) Thanks @shakkernerd.
• Agents/model switching: apply /model changes 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_error payloads as failoverable, sanitize Codex error: payloads before they reach chat, preserve context-overflow guidance for prefixed invalid_request_error payloads, and omit provider request_id values 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/carbon to the latest beta and pass the new RateLimitError request argument so Discord stays compatible with the upstream beta constructor change. (#55980) Thanks @ngutman.
• Plugins/inbound claims: pass full inbound attachment arrays through inbound_claim hook metadata while keeping the legacy singular media attachment fields for compatibility. (#55452) Thanks @huntharo.
• Plugins/Matrix: preserve sender filenames for inbound media by forwarding originalFilename to saveMediaBuffer. (#55692) thanks @esrehmki.
• Matrix/mentions: recognize matrix.to mentions whose visible label uses the bot's room display name, so requireMention: true rooms respond correctly in modern Matrix clients. (#55393) thanks @nickludlam.
• Ollama/thinking off: route thinkingLevel=off through the live Ollama extension request path so thinking-capable Ollama models now receive top-level think: false instead of silently generating hidden reasoning tokens. (#53200) Thanks @BruceMacD.
• Plugins/diffs: stage bundled @pierre/diffs runtime 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. 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 accessToken and password SecretRefs against the active Matrix config env path during startup, and officially accept SecretRef accessToken config values. (#54980) thanks @kakahu2015.
• Microsoft Teams/proactive DMs: prefer the freshest personal conversation reference for user: 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/invoke tool 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 country filters to ALL before request and cache-key generation so locale-derived values like VN stop 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-nodejs through createRequire(...) 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_file while keeping unencrypted-room previews on thumbnail_url, so encrypted Matrix image events keep thumbnail metadata without leaking plaintext previews. (#54711) thanks @frischeDaten.
• Telegram/forum topics: keep native /new and /reset routed to the active topic by preserving the topic target on forum-thread command context. (#35963)

View full changelog

Breaking

Changes

• Gateway/OpenAI compatibility: add /v1/models and /v1/embeddings, and forward explicit model overrides through /v1/chat/completions and /v1/responses for broader client and RAG compatibility. Thanks @vincentkoc.
• Agents/tools: make /tools show the tools the current agent can actually use right now, add a compact default view with an optional detailed mode, and add a live "Available Right Now" section in the Control UI so it is easier to see what will work before you ask.
• Microsoft Teams: migrate to the official Teams SDK and add AI-agent UX best practices including streaming 1:1 replies, welcome cards with prompt starters, feedback/reflection, informative status updates, typing indicators, and native AI labeling. (#51808)
• Microsoft Teams: add message edit and delete support for sent messages, including in-thread fallbacks when no explicit target is provided. (#49925)
• Skills/install metadata: add one-click install recipes to bundled skills (coding-agent, gh-issues, openai-whisper-api, session-logs, tmux, trello, weather) so the CLI and Control UI can offer dependency installation when requirements are missing. (#53411) Thanks @BunsDev.
• Control UI/skills: add status-filter tabs (All / Ready / Needs Setup / Disabled) with counts, replace inline skill cards with a click-to-detail dialog showing requirements, toggle switch, install action, API key entry, source metadata, and homepage link. (#53411) Thanks @BunsDev.
• Slack/interactive replies: restore rich reply parity for direct deliveries, auto-render simple trailing Options: lines as buttons/selects, improve Slack interactive setup defaults, and isolate reply controls from plugin interactive handlers. (#53389) Thanks @vincentkoc.
• CLI/containers: add --container and OPENCLAW_CONTAINER to run openclaw commands inside a running Docker or Podman OpenClaw container. (#52651) Thanks @sallyom.
• Discord/auto threads: add optional autoThreadName: "generated" naming so new auto-created threads can be renamed asynchronously with concise LLM-generated titles while keeping the existing message-based naming as the default. (#43366) Thanks @davidguttman.
• Plugins/hooks: add before_dispatch with canonical inbound metadata and route handled replies through the normal final-delivery path, preserving TTS and routed delivery semantics. (#50444) Thanks @gfzhx.
• Control UI/agents: convert agent workspace file rows to expandable
  with lazy-loaded inline markdown preview, and add comprehensive .sidebar-markdown styles for headings, lists, code blocks, tables, blockquotes, and details/summary elements. (#53411) Thanks @BunsDev.
• Control UI/markdown preview: restyle the agent workspace file preview dialog with a frosted backdrop, sized panel, and styled header, and integrate @create-markdown/preview v2 system theme for rich markdown rendering (headings, tables, code blocks, callouts, blockquotes) that auto-adapts to the app's light/dark design tokens. (#53411) Thanks @BunsDev.
• macOS app/config: replace horizontal pill-based subsection navigation with a collapsible tree sidebar using disclosure chevrons and indented subsection rows. (#53411) Thanks @BunsDev.
• CLI/skills: soften missing-requirements label from "missing" to "needs setup" and surface API key setup guidance (where to get a key, CLI save command, storage path) in openclaw skills info output. (#53411) Thanks @BunsDev.
• macOS app/skills: add "Get your key" homepage link and storage-path hint to the API key editor dialog, and show the config path in save confirmation messages. (#53411) Thanks @BunsDev.
• Control UI/agents: add a "Not set" placeholder to the default agent model selector dropdown. (#53411) Thanks @BunsDev.
• Runtime/install: lower the supported Node 22 floor to 22.14+ while continuing to recommend Node 24, so npm installs and self-updates do not strand Node 22.14 users on older releases.
• CLI/update: preflight the target npm package engines.node before openclaw update runs a global package install, so outdated Node runtimes fail with a clear upgrade message instead of attempting an unsupported latest release.

Fixes

• Outbound media/local files: align outbound media access with the configured fs policy so host-local files and inbound-media paths keep sending when workspaceOnly is off, while strict workspace-only agents remain sandboxed.
• Security/sandbox media dispatch: close the mediaUrl/fileUrl alias bypass so outbound tool and message actions cannot escape media-root restrictions. (#54034)
• Gateway/restart sentinel: wake the interrupted agent session via heartbeat after restart instead of only sending a best-effort restart note, retry outbound delivery once on transient failure, and preserve explicit thread/topic routing through the wake path so replies land in the correct Telegram topic or Slack thread. (#53940) Thanks @VACInc.
• Docker/setup: avoid the pre-start openclaw-cli shared-network namespace loop by routing setup-time onboard/config writes through openclaw-gateway, so fresh Docker installs stop failing before the gateway comes up. (#53385) Thanks @amsminn.
• Gateway/channels: keep channel startup sequential while isolating per-channel boot failures, so one broken channel no longer blocks later channels from starting. (#54215) Thanks @JonathanJing.
• Embedded runs/secrets: stop unresolved SecretRef config from crashing embedded agent runs by falling back to the resolved runtime snapshot when needed. Fixes #45838.
• WhatsApp/groups: track recent gateway-sent message IDs and suppress only matching group echoes, preserving owner /status, /new, and /activation commands from linked-account fromMe traffic. (#53624) Thanks @w-sss.
• WhatsApp/reply-to-bot detection: restore implicit group reply detection by unwrapping botInvokeMessage payloads and reading selfLid from creds.json, so reply-based mentions reach the bot again in linked-account group chats.
• Telegram/forum topics: recover #General topic 1 routing when Telegram omits forum metadata, including native commands, interactive callbacks, inbound message context, and fallback error replies. (#53699) thanks @huntharo
• Discord/gateway supervision: centralize gateway error handling behind a lifetime-owned supervisor so early, active, and late-teardown Carbon gateway errors stay classified consistently and stop surfacing as process-killing teardown crashes.
• Discord/timeouts: send a visible timeout reply when the inbound Discord worker times out before a final reply starts, including created auto-thread targets and queued-run ordering. (#53823) Thanks @Kimbo7870.
• ACP/direct chats: always deliver a terminal ACP result when final TTS does not yield audio, even if block text already streamed earlier, and skip redundant empty-text final synthesis. (#53692) Thanks @w-sss.
• Telegram/outbound errors: preserve actionable 403 membership/block/kick details and treat bot not a member as a permanent delivery failure so Telegram sends stop retrying doomed chats. (#53635) Thanks @w-sss.
• Telegram/photos: preflight Telegram photo dimension and aspect-ratio rules, and fall back to document sends when image metadata is invalid or unavailable so photo uploads stop failing with PHOTO_INVALID_DIMENSIONS. (#52545) Thanks @hnshah.
• Slack/runtime defaults: trim Slack DM reply overhead, restore Codex auto transport, and tighten Slack/web-search runtime defaults around DM preview threading, cache scoping, warning dedupe, and explicit web-search opt-in. (#53957) Thanks @vincentkoc.

View full changelog