OpenClaw 2026.5.12-beta.3 Release: Finer Tool Permissions, Smoother Channel Integrations, and a Cleaner Plugin SDK

We have just released OpenClaw 2026.5.12-beta.3. This update focuses on three main areas: granular per‑sender tool policies, stability and feature enhancements for mainstream messaging channels (Slack, iMessage, Discord), and plugin SDK clean‑up with better developer experience. There are also several practical improvements like automatic Gemini model ID migration, cron job inspection by ID, and session context visualisation.

Whether you are a daily user, a self‑hosting operator, or someone building plugins on top of OpenClaw, this release brings valuable changes.

1. Gateway and LLM Providers: API‑Friendly Token Handling and Seamless Gemini Migration

The OpenAI‑compatible gateway now respects client‑provided token caps

When you use the OpenAI‑compatible /v1/chat/completions endpoint in the OpenClaw gateway, and the client sends both max_completion_tokens and max_tokens, the gateway now gives priority to max_completion_tokens and forwards the final value to the upstream OpenAI service. This means you can control per‑request token consumption more precisely, avoiding unexpected truncation or overruns caused by mismatched parameters between client and gateway.

OpenAI CLI login: ChatGPT/Codex account flow by default

For command‑line users, openclaw models auth login --provider openai now defaults to the ChatGPT or Codex account login flow (similar to a web authorisation). If you still prefer to use a traditional API key, you can explicitly add --method api-key. This change makes onboarding more intuitive – new users don’t have to hunt for an API key immediately; they can test with an existing account.

Automatic migration from Gemini 3 Pro Preview to 3.1 Pro Preview

Google has marked the gemini-3-pro-preview model as retired. To keep your configuration working without manual edits, OpenClaw now automatically replaces any google/gemini-3-pro-preview reference with google/gemini-3.1-pro-preview in the following scenarios:

  • When writing configuration after SDK OAuth authentication
  • When logging in and setting as default via openclaw models auth login --set-default
  • When re‑applying the agent default model using only an API key (e.g. during provider catalogue updates)

You do not need to touch any configuration files – the old model ID smoothly transitions to a usable new version.

2. Agents and Tools: Much Finer Access Control

Restrict dangerous tools by sender identity

This is one of the most valuable features for production operations in this release. You can now define independent tool policies for different senders. A “sender” is identified by a canonical channel‑scoped sender key that combines the channel type and the user’s local identifier. For example:

  • A regular member from a Discord server might only be allowed to use safe tools like weather queries or documentation retrieval.
  • An administrator from the same server could additionally use command execution, file read/write, and other powerful tools.
  • A specific user from an internal test group might even be allowed to use all plugin tools.

This policy can be applied at multiple levels:

  • Global
  • Per agent
  • Per group
  • Core tools
  • Bundled tools
  • Plugin tools

You can now truly enforce “who requests, who uses” instead of treating all channels equally. For teams sharing a single OpenClaw instance, this is a major security upgrade.

Cross‑context message sending restrictions

For each agent, there is a new tools.message.crossContext override. If you want a sandboxed or public agent to only reply within the current conversation and never actively send messages to other dialogues, you can now control that independently without changing the global bot policy.

At the same time, tools.message.actions.allow lets you define per‑agent “send‑only” message tool behaviours. For example, you can force a restricted agent to only send plain text, not attachments or other message actions.

Preserving background session references across compaction

A complex but impactful bug has been fixed: after session compaction, references to background execution or process sessions could be lost, making it impossible to continue interacting with a background process. These references are now correctly preserved across compaction and turn boundaries.

Additionally, when agents deal with background sessions, the system now hints that they should first inspect the session with process log and use flags like waitingForInput / stdinWritable (returned by log or poll) before sending interactive input. This reduces useless “stdin to a dead process” operations.

Agent‑to‑agent ping‑pong turns can be increased to 20

If you often use chained “agent calls agent” conversations, you may have hit the default limit of 5 ping‑pong turns. You can now raise session.agentToAgent.maxPingPongTurns to a maximum of 20, while keeping the default at 5. Increase it only when your workflow genuinely requires longer chains.

Trimmed default system prompt

To reduce token consumption per request, the default system prompt has been trimmed – especially the schema descriptions for send‑only message tools. OpenClaw’s built‑in GPT‑5 personality guidance is still intact, but the overall token footprint is friendlier.

3. Messaging Channel Integrations: Slack, iMessage, and Discord All See Significant Improvements

Slack: link previews, reply broadcasting, and mention metadata

In the past, messages sent by the bot in Slack would automatically expand link and media previews. You can now control this with two configuration options: unfurlLinks and unfurlMedia. They can be set per account or globally, allowing you to suppress link/ media previews for chat.postMessage replies. This is useful when you want to keep message content clean or avoid leaking previews.

A new replyBroadcast flag is also supported. When an agent replies inside a thread and sets this to true, the message will also be broadcast to the parent channel (Slack’s reply_broadcast behaviour). This allows certain high‑visibility replies to be seen without sending an entirely separate message.

One of the most important fixes: the inbound prompt context for Slack messages now preserves “mention target / source” metadata. The agent can distinguish two cases:

  • The bot was directly @‑mentioned.
  • The thread was woken up, but the actual @‑mention was for someone else.

Previously these two cases were mixed, and the agent often mistakenly thought it was being called. Now it correctly identifies who was mentioned.

Also, for Slack native DM channel IDs starting with D..., outgoing message routing has been normalised to the peer user’s session. The same Slack direct message conversation will no longer be split into two different sessions – the experience is more coherent.

iMessage: status filtering and migration documentation

A new command openclaw channels status --channel <name> lets you inspect the status of a specific channel (e.g. iMessage) without seeing all channels at once. The documentation now also includes a cutover path from BlueBubbles to iMessage, helping you probe iMessage without starting both channel monitors.

Discord voice: granular channel control and diagnostics

If you use Discord voice channels, this release adds several useful tools:

  • voice.allowedChannels configuration: restricts which voice channels the bot can join or move to. If unset, the behaviour remains open. This prevents the bot from accidentally entering channels where it shouldn’t be.
  • Real‑time voice diagnostics: analyse speaker turns, playback resets, barge‑in detection, and audio cut‑off behaviour.
  • Defaults to the pure‑JavaScript opusscript decoder, no longer forcing compilation of the native @discordjs/opus module. If you need low‑latency, high‑performance voice, you can opt into the native opus support via a dedicated install script.

4. Plugin SDK: Deprecating Obsolete Public Subpaths, Adding Session Actions

Removing outdated public subpaths

To reduce plugin reliance on unstable internal interfaces, the SDK has undergone several clean‑ups:

  • The provider-auth-login public subpath – used by only a few plugins – has been removed. Authentication flows for Chutes, GitHub Copilot, and OpenAI Codex have been moved back into the respective provider‑owned modules.
  • Provider‑specific helpers for models, streaming, and xAI compatibility have been removed from public exports. Plugins that called these have been migrated to their own modules.
  • A number of public subpaths that have existed for at least one month and have no production imports from bundled extensions have been marked deprecated. They remain importable for backward compatibility (with warnings), but new plugins should avoid them.

New session actions for plugins

Plugins can now call the following session‑related operations via the SDK:

  • sendSessionAttachment: send an attachment to the current session.
  • Cron‑backed scheduleSessionTurn: trigger a session turn at a future time, with tag clean‑up mechanisms.

These are grouped under a clear session namespace, making them easier to discover and use.

Media understanding extension

For plugins that need structured extraction from images, a new extractStructuredWithModel(...) method is available. It runs a bounded, image‑first extraction flow with optional supplementary text context. The caller can choose to let the extraction run through provider‑owned runtimes such as Codex. This is an advanced feature but provides a standard path for building “look at an image and answer structured questions” plugins.

Expose active model metadata to plugin tool factories

Native plugin tool factories can now access runtime‑supplied active model metadata. This means a plugin can dynamically adjust its behaviour or log diagnostic information based on the model name, provider, etc., currently being used.

5. Cron Job Management: Inspect a Single Job by ID

Previously, checking a cron job might require listing all jobs and manually filtering. Now you have three ways to directly fetch a single job’s information:

  • The cron.get function
  • The command line: openclaw cron get <id>
  • The get operation exposed through the agent tool

This is more convenient for automation scripts or when you need to precisely control a specific scheduled task.

6. Control UI: Recovery Panel for Blank Dashboard

If you have ever seen the OpenClaw web control UI stuck on a blank page (likely because the frontend module failed to register), this version adds a plain HTML recovery panel. When the app module never registers, the page will show a recovery panel with a retry path and a browser‑extension troubleshooting link. This directly addresses community issue #44107.

7. Build, Dependencies, and Environment Detection

Full migration to pnpm 11

The entire workspace package management has been upgraded from older versions to pnpm 11. This includes Docker images, install scripts, update workflows, and release processes. If you build from source or maintain your own Docker images, we recommend updating your local pnpm to the 11.x series.

Extensive dependency refresh

Core dependencies have been updated to recent versions, for example:

  • ACPX @agentclientprotocol/claude-agent-acp → 0.33.1
  • Codex ACP → 0.14.0
  • WhatsApp driver: moved from @whiskeysockets/baileys to official baileys (still at version 7.0.0-rc10)
  • Google GenAI → 2.0.1
  • OpenAI → 6.37.0
  • AWS SDK → 3.1045.0
  • Kysely → 0.29.0

Additionally, all direct (non‑peer) dependencies are now hard‑pinned. This ensures that when you install OpenClaw, the resolved versions match exactly what the maintainers tested.

Automatic Fly.io container detection

When OpenClaw runs on Fly Machines, it now automatically detects the container environment from runtime environment variables and adjusts gateway binding and Bonjour defaults to better suit remote containers. You can use the same configuration locally and on Fly without manual tweaking.

8. Voice and Realtime Communication: Talk and Discord Voice Polish

Talk realtime voice style instructions

For those using the talk.realtime feature, a new talk.realtime.instructions configuration option is available. You can append realtime voice style hints (e.g., “use a slower pace for important information”) without overwriting OpenClaw’s built‑in agent‑consult guidance. This makes the voice persona more flexible to adjust per scenario.

Discord voice optimisation

  • Defaults to the pure‑JS opusscript decoder, avoiding the need to compile native modules.
  • An optional native @discordjs/opus install script and decoder preference is provided for voice‑performance‑sensitive setups.
  • Added voice.allowedChannels – only channels in this list are allowed for bot voice joins or voice‑state moves.

9. Quality Assurance and Test Automation

Mantis automated testing enhancements for Telegram

The QA workflow for Telegram now includes:

  • Telegram live PR evidence automation: uses Convex‑leased credentials, Crabbox transcript capture, motion GIF previews, and inline PR comments.
  • A Telegram desktop scenario builder: automatically leases a Crabbox instance, installs native Telegram Desktop, configures the OpenClaw Telegram gateway with leased bot credentials, and records VNC screenshot/video artefacts.

This means future Telegram‑related changes will have more reliable visual regression testing.

Plugin compatibility inspection

A non‑blocking plugin-inspector-advisory artifact has been added to the Plugin Prerelease workflow. It captures compatibility issues with bundled plugins but does not block the release itself. This lets you know which plugins might need adjustments before a release is finalised.

10. Frequently Asked Questions (FAQ)

Q: After upgrading, Gemini models report “model not found”. What should I do?
A: This version automatically replaces the old gemini-3-pro-preview with gemini-3.1-pro-preview. If you still see errors, try re‑running openclaw models auth login --provider google --set-default, or manually check your configuration files to ensure the model ID has been updated.

Q: I want to restrict a specific Discord user to only use weather and calculator tools, and forbid command execution. How do I configure that?
A: You need to use the new per‑sender tool policy. First determine the sender key for that user (usually channel:userID). Then set a tools.policy whitelist for that key in the configuration. Refer to the agents.defaults.tools.policy example format.

Q: My Slack bot no longer responds when I @‑mention it?
A: It does respond, but now it correctly distinguishes between “@‑bot” and “@‑someone‑else while the bot is also in the thread”. If your bot’s behaviour seems off, check whether the prompt includes the mention target metadata and adjust your system prompt accordingly.

Q: I get opus‑related compilation errors. How can I skip native opus?
A: The new version already defaults to not requiring native opus. If you still encounter errors, ensure your installation method does not force @discordjs/opus. Try deleting node_modules and re‑running pnpm install, or set the environment variable OPENCLAW_DISCORD_VOICE_USE_OPUSSCRIPT=1.

Q: My plugin imports @openclaw/plugin-sdk/provider-auth-login and now fails with “module not found”.
A: That subpath has been removed. You need to migrate authentication logic to your plugin’s own module or use the new generic authentication interfaces. Check the corresponding PR (#66933) for migration guidance.

Q: Can cron jobs be scheduled with second precision?
A: Currently, cron expressions still use standard minute‑level granularity. Second‑level scheduling is not part of this release.

Q: The control UI shows a blank page. How do I fix it?
A: The new version includes a recovery panel. If the page stays blank, the panel will appear with a retry button and a browser‑extension troubleshooting link. First try clearing your browser cache and disabling extensions that might interfere. If the problem persists, check the backend logs to confirm frontend assets are being loaded correctly.

What to do next

  • If you are an everyday user – focus on the Slack and Discord improvements and the new per‑sender tool policies. After upgrading, test your existing Slack integration to confirm it still behaves as expected.
  • If you are a self‑hosting operator – note the pnpm 11 upgrade and dependency hard‑pinning. Fly.io users can deploy as usual; the container environment will be auto‑detected.
  • If you are a plugin developer – immediately check whether your plugin depends on any deprecated or removed public subpaths. Upgrade the SDK and migrate to the new session actions and media extraction methods where useful.
  • If you are involved in QA or CI – study the Mantis Telegram automation approach; you may be able to adapt parts of it to your own testing workflows.

This beta has undergone internal testing and fixes multiple stability and security issues. The next stable release is expected within two weeks. If you encounter any problems, please open an issue on GitHub or reach out through the community channels.