OpenClaw Troubleshooting: Gateway Errors & Bot Fixes

Run this command first — it shows exactly what went wrong:

openclaw logs --tail 100

Look for lines starting with ERROR. The message almost always tells you the problem. If you can't make sense of it, copy it and search below.

Channel startup failures are now isolated — one broken channel no longer blocks later channels from starting. Check logs for the specific channel that failed; the rest will continue to operate normally.

As of v2026.4.12, photo dimension validation has been improved. If an image doesn't meet Telegram's requirements, it automatically falls back to sending as a document. Voice note transcription in direct messages is now restored. Telegram command reply threading is preserved for QA verification.

Forum topic names are now surfaced in agent context and persisted across restarts. AAC voice notes are remapped to .m4a so they transcribe correctly on strict endpoints. Read-only status commands bypass busy topic turns so /status responds immediately without waiting for an in-flight reply.

Binary document uploads (.mobi, .epub) no longer leak binary bytes into prompt context or inflate token counts. Native Telegram commands keep auto-registering when commands.native and commands.nativeSkills are auto. The command-sync cache is now process-local — gateway restarts re-register the slash menu instead of relying on stale on-disk state.

Telegram group chats now parse remote markdown image syntax (![alt](url)) into outbound media payloads on the final reply path. If the model or a tool emitted markdown image syntax instead of a MEDIA: token, group deliveries previously fell back to plain-text image URLs. Images now render natively in groups. (Fixes #66191)

Watchdog timeouts are reset after reconnect, so quiet chats should no longer fall into reconnect loops. Per-account connection ownership is now centralized, so reconnects and login recovery stay attached to the live socket. Message reactions now route properly through the gateway-owned action path in both DMs and groups. Fallback now properly uses the first mediaUrls entry when mediaUrl is empty, restoring silently dropped media attachments.

The pending per-auth credentials save queue is now drained before sockets are reopened, preventing a reconnect-time race that could cause auth bootstrap to falsely restore from backup. Large outbound media send reliability has also been improved.

First-run WhatsApp setup is kept off the Baileys runtime dependency path, so packaged QuickStart installs can reach the WhatsApp setup screen before runtime deps are staged. If your packaged install was stuck on the WhatsApp step during onboarding, upgrading resolves it. (Fixes #70932)

As of v2026.4.14, the global allowFrom owner allowlist is enforced on Slack block-action and modal interactive events. If you have interactive components (buttons, modals) in your Slack integration, make sure your allowFrom list includes all users who should be able to trigger them.

Option menus for slash commands such as /verbose now work correctly when Slack renders native buttons. Each button is given a unique action ID while still routing through the shared openclaw_cmdarg* listener — previously, option selections could be rejected or misrouted when multiple buttons shared the same action ID.

As of v2026.4.21, thread aliases are preserved in runtime outbound sends. Generic runtime sends now correctly stay in the intended Slack thread when the caller supplies threadTs. If your custom replies or automations were landing in the wrong thread, upgrading to v2026.4.21 resolves this. (#62947)

Multi-person group DMs (MPIMs) are now classified as group chat context. Verbose tool and plan progress messages are suppressed on non-DM Slack surfaces, so internal "Working…" traces no longer leak into group rooms while 1:1 DMs keep tool-call progress. If you were seeing unexpected tool progress output in Slack group DMs, upgrading to v2026.4.23 resolves it. (Fixes #70912)

Startup failures now retry transient watch.subscribe errors before tearing down the monitor. Startup error logging is sanitized so brief local transport stalls don't bounce the channel or leak raw imsg RPC payloads into logs.

Media cap is now 100MB (previously 25MB), so larger video and audio files upload correctly. Generated images are tracked with real file paths. Text-plus-video deliveries intelligently split so both arrive properly. Numeric Discord server and channel IDs in config are auto-coerced to strings.

Standalone Gemma-style <function>...</function> tool-call payloads are now stripped from visible assistant text in Discord. This prevents raw tool-call XML from appearing in your channel when using Gemma-format models. Prose text and trailing replies are preserved — only actual standalone tool-call payloads are removed.

Native slash-command channel policy no longer bypasses configured owner or member restrictions. If a permissive channel policy was unintentionally opening owner-only or member-only slash commands to a broader audience, the stricter access rule now wins. Channel-policy fallback still applies when no stricter rule exists. (#70711)

Room mention gating stays strict while accepting visible @displayName Matrix URI labels, so requireMention works for non-OpenClaw Matrix clients again.

Invalid ax<N> accessibility refs in browser act paths are now rejected immediately on receipt instead of waiting for the full browser action timeout to expire. If your agent or a skill passes a malformed accessibility ref, you'll see a fast, descriptive error in the logs rather than a long silence followed by a timeout. (#69924)

The Codex plugin is now auto-enabled when codex is selected as an embedded agent harness runtime (including forced default, per-agent, and OPENCLAW_AGENT_RUNTIME paths). Previously, you had to manually enable the Codex plugin in your config even when selecting Codex as your runtime.

OpenAI image generation and reference-image editing now route through Codex OAuth when an openai-codex profile is active. This means openai/gpt-image-2 works without an OPENAI_API_KEY for users already authenticated with Codex. Previously, image generation probed OPENAI_API_KEY first and would fail if only Codex OAuth was configured. (Fixes #70703)

Reference-image edits are now sent as guarded multipart uploads instead of JSON data URLs, restoring complex multi-reference gpt-image-2 edits that were failing. If your image-edit runs were silently losing reference images, upgrading resolves it. (Fixes #70642) Thanks @dashhuang.

OpenRouter image generation and reference-image editing now work through image_generate with OPENROUTER_API_KEY. (Fixes #55066) Additionally, OpenRouter multimodal image-understanding prompts now send user text before image parts, restoring non-empty vision responses. (Fixes #70410) Thanks @notamicrodose.

Google Gemini image generation and OpenAI-compatible image generation endpoints now honor the private-network SSRF opt-in. Trusted proxy setups that resolve Google API hosts to private addresses can use image_generate with Gemini, and trusted LocalAI/LAN image_generate routes work without disabling SSRF checks globally. (Fixes #67216, #62879) Thanks @seitzbg.

Explicit image-model configuration is now honored before native-vision skips. OpenClaw respects agents.defaults.imageModel, tools.media.image.models, and provider image defaults (such as MiniMax VL) when the active chat model is text-only. If media understanding was skipping your configured image model because the chat model advertised vision, this is fixed. (Fixes #47614, #63722, #69171)

ADC-backed Anthropic Vertex model discovery is restored after the lightweight provider-discovery path. Synthetic auth is exposed on bootstrap discovery, and copied env snapshots are honored when probing the default GCP ADC path. If Vertex-backed Claude models stopped appearing in discovery, upgrading resolves it. (Fixes #65715) Thanks @feiskyer.

OpenClaw now includes bundled LM Studio provider with onboarding, runtime model discovery, stream preload support, and memory-search embeddings for local/self-hosted OpenAI-compatible models. A bundled Codex provider is also available with plugin-owned app-server harness so codex/gpt-* models use Codex-managed auth and native threads.

The Control UI Overview now includes a Model Auth status card showing OAuth token health and provider rate-limit pressure at a glance. The card surfaces attention callouts when OAuth tokens are expiring or have already expired. If you see a warning on this card, re-authenticate the affected provider using openclaw configure or the Control UI setup flow. See Key Concepts for more detail on what the Model Auth status card monitors.

openclaw doctor now warns when on-disk agent directories still exist under ~/.openclaw/agents/<id>/agent but the matching agents.list[] entries are missing from config. This helps catch stale agent state. The --fix flag no longer rewrites legacy Discord preview-streaming config into the nested modern shape, so downgrades can recover without hand-editing.

As of v2026.4.21, openclaw doctor --fix can now repair bundled plugin runtime dependencies from doctor paths. This means packaged installs can recover missing channel or provider dependencies without triggering broad core dependency installs. If a channel or provider plugin was silently failing to load after a packaged install, run openclaw doctor --fix to restore the missing dependencies.

openclaw update now respawns tracked plugin refresh from the updated entrypoint after package self-updates, so update stops failing on stale hashed dist/install.runtime-*.js chunk imports.

As of v2026.4.21, the node-domexception alias is mirrored into the root package.json overrides. npm installs no longer surface the deprecated google-auth-library → gaxios → node-fetch → fetch-blob → node-domexception dependency chain pulled through Pi/Google runtime dependencies. If you were seeing this deprecation warning on npm install, upgrading to v2026.4.21 resolves it. Thanks @vincentkoc.

Dreaming now properly consumes managed heartbeat events exactly once, stages light-sleep confidence from all recorded short-term signals instead of recall-only counts, and stops dreaming from re-ingesting its own narrative transcripts. Transient narrative cleanup is more robust with retry logic for timed-out deletes and stale session artifact scrubbing. Dream diary timestamps now use host local timezone when dreaming.timezone is unset and include timezone abbreviation in DREAMS.md.

memory directory watching now works reliably on macOS + Node 25, ignoring non-markdown churn so nested note changes still sync. Unicode letters, digits, and combining marks in wiki slugs are now preserved with safe byte-length caps. Channel sessions are now allowed in the shipped default QMD scope. The legacy lowercase root memory file is no longer registered as a separate default collection. Nested daily notes under memory/**/YYYY-MM-DD.md now feed short-term recall properly.

New optional Active Memory plugin gives your agent a dedicated memory sub-agent right before the main reply, pulling in relevant preferences without manual "remember this" prompts. Includes configurable message/recent/full context modes, live /verbose inspection, and advanced prompt/thinking overrides for tuning. Memory recall now defaults to search mode with better search-path telemetry for more predictable out-of-the-box behavior.

As of v2026.4.14, recalled memories are placed on the hidden untrusted prompt-prefix path rather than injected into the system prompt. This is a security and reliability improvement — it means Active Memory context is properly isolated and labeled in gateway debug logs, so you can see exactly what the model received.

Stale managed QMD collections are now recreated on startup repair when the collection name already exists. This means root memory narrows back to MEMORY.md instead of getting stuck on broad workspace markdown indexing after a collection-name collision. If your memory recall was returning unrelated files from across your workspace instead of focused MEMORY.md context, upgrading resolves it.

Plugin loading has been tightened to manifest-declared needs. CLI, provider, and channel activation are now narrowed to what plugins explicitly declare, preserving explicit scope and trust boundaries. This means plugins no longer load unrelated runtime code on startup — only what's needed.

openclaw wiki now properly honors memory-wiki when plugins.allow is set, and passes the active app config into the metadata registrar so plugin-owned wiki commands resolve the live plugin config instead of falling back to defaults.

Experimental local MLX speech provider for Talk Mode on macOS with explicit provider selection, local utterance playback, interruption handling, and system-voice fallback.

The shipped example gateway credential in .env.example is now blanked, and startup fails when a copied placeholder token or password is still configured. This prevents operators from accidentally launching with a publicly known secret.

As of v2026.4.21, owner-enforced commands require explicit owner identity — either an owner-candidate match or the internal operator.admin role — when enforceOwnerForCommands is true.

What changed: Previously, a wildcard allowFrom setting or an empty commands.ownerAllowFrom list could act as a permissive fallback, allowing non-owner senders to reach owner-only commands. This fallback has been removed. (#69774) Thanks @drobison00.

Who is affected: If you have enforceOwnerForCommands: true set and have not explicitly configured commands.ownerAllowFrom, review your setup. Non-owner users who previously reached owner-only commands through a permissive allowFrom wildcard will now be correctly rejected.

What to do: Explicitly list your intended owner identities in commands.ownerAllowFrom:

{
  "commands": {
    "enforceOwnerForCommands": true,
    "ownerAllowFrom": ["telegram:123456789", "slack:U0123ABCDEF"]
  }
}

If you intentionally want multiple users to reach certain commands, use role-based allowFrom on those specific commands rather than relying on the owner enforcement path.