OpenClaw 2026.5.12-beta.3 发布：更灵活的权限控制、更稳定的渠道集成和更完善的开发者体验

我们刚刚发布了 OpenClaw 2026.5.12-beta.3 版本。这次更新主要集中在三个方向：细粒度的工具权限策略、主流消息渠道（Slack、iMessage、Discord）的稳定性与功能增强，以及插件 SDK 的清理与开发者体验优化。此外，还包含了对 Gemini 模型 ID 的自动化迁移、Cron 任务管理、会话上下文可视化等一系列实用改进。

如果你是 OpenClaw 的日常使用者、自托管运维人员，或者正在基于它开发插件，这个版本值得你关注。

一、网关与大模型接入：更符合 API 习惯，更顺滑的 Gemini 迁移

OpenAI 兼容网关现在会尊重客户端传来的 token 上限

当你在 OpenClaw 网关中使用 OpenAI 兼容的 /v1/chat/completions 接口时，客户端如果同时传递了 max_completion_tokens 和 max_tokens 这两个参数，网关会优先采用 max_completion_tokens，并将最终的值传递给上游的 OpenAI 服务。这意味着你可以更精确地控制单次请求的 token 消耗，避免因为客户端与网关之间的参数不一致而导致意外截断或超额。

OpenAI 命令行登录：默认走 ChatGPT/Codex 账号流程

对于习惯使用命令行的用户，openclaw models auth login --provider openai 现在会默认启动 ChatGPT 或 Codex 账号的登录流程（类似网页授权）。如果你依然想使用传统的 API Key 方式，可以显式加上 --method api-key。这个改动让新用户 onboarding 更直观 —— 不需要一开始就去翻 API Key，直接用已有账号就能测试。

Gemini 3 Pro Preview 自动迁移到 3.1 Pro Preview

Google 已经将 Gemini 3 Pro Preview 模型标记为“退休”。为了不让你的配置突然失效，OpenClaw 会在以下几种场景中自动把配置里的 google/gemini-3-pro-preview 替换成 google/gemini-3.1-pro-preview：

  • 通过 SDK OAuth 认证后写入配置时
  • 通过 openclaw models auth login --set-default 登录并设为默认时
  • 仅用 API Key 重新应用代理默认模型时

你不需要手动修改任何配置文件，旧模型 ID 会平滑过渡到可用的新版本。

二、代理与工具：权限控制粒度大幅细化

按发送者身份限制危险工具

这是本次更新中对生产环境运维最有价值的功能之一。现在你可以为不同的发送者（sender）设置独立的工具使用策略。所谓的“发送者”是基于渠道和用户身份生成的一个规范键（canonical channel-scoped sender key）。举例来说：

  • 来自 Discord 某个服务器的普通成员，可能只允许使用天气查询、文档检索等安全工具；
  • 来自同一个服务器的管理员，可以额外使用执行命令、读写文件等工具；
  • 来自内部测试群的某个特定用户，甚至可以使用所有插件工具。

这个策略可以作用在多个层级：

  • 全局级别
  • 某个代理级别
  • 群组级别
  • 核心工具级别
  • 预捆绑工具级别
  • 插件工具级别

这意味着你可以真正做到“谁请求，谁使用”，而不是所有渠道一视同仁。对于多人共享一个 OpenClaw 实例的场景，这是安全性的重大提升。

跨上下文消息发送限制

在代理（agent）配置中，新增了 tools.message.crossContext 覆盖选项。如果你希望某个沙箱环境或公开代理只能回复当前会话内的消息，而不能主动向其他对话发送内容，现在可以通过这个开关独立控制，不必修改全局策略。

同时，tools.message.actions.allow 允许你为每个代理单独定义“仅发送”的消息工具行为。例如，让某个受限代理只能发送文本，不能发送附件或执行其他消息操作。

会话背景任务保持与调试

修复了一个复杂但影响较深的 bug：在会话压缩（compaction）后，后台执行或进程会话的引用可能丢失，导致无法继续与背景进程交互。现在这些引用会正确地跨压缩和轮次传递。

另外，代理在处理后台会话时，系统会提示它们先用 process log 检查会话状态，并利用 waitingForInput / stdinWritable 这些从 log 或 poll 返回的提示信息，再决定是否发送交互输入。这减少了“对着一个已终止的进程发 stdin”的无效操作。

Agent 间对话轮次上限可调至 20

如果你经常使用“代理调用代理”的链式对话，可能会遇到默认 5 轮 ping-pong 后对话被截断的问题。现在 session.agentToAgent.maxPingPongTurns 可以调整到最多 20 轮，同时默认保持 5 轮，按需调高即可。

系统提示词精简

为了减少每次请求的 token 消耗，默认的系统提示词被修剪了，尤其是“仅发送消息工具”的 schema 描述变得更紧凑。OpenClaw 内置的 GPT-5 人格引导逻辑依然保留，但总 token 数更友好。

三、消息渠道集成：Slack、iMessage、Discord 都有了显著改进

Slack：链接预览、回广播和提及元数据

过去在 Slack 渠道中，机器人发送的消息默认会展开链接和媒体预览。现在你可以通过 unfurlLinks 和 unfurlMedia 两个配置项，针对每个账号或全局，控制 chat.postMessage 回复时是否展开预览。对于需要保持消息简洁或避免泄露预览内容的场景很有用。

此外，新增了 replyBroadcast 支持。当代理在某个线程中回复时，如果将此选项设为 true，消息会同时广播到父频道（Slack 的 reply_broadcast 行为）。这让某些需要高可见度的回复不必再单独发一条新消息。

最重要的改进之一：Slack 消息的 prompt 上下文中现在会保留“提及目标/来源”的元数据。代理可以区分以下两种情况：

  • 机器人被直接 @ 提及
  • 线程被唤醒，但实际 @ 的是另一个人

以前这两种情况混在一起，代理容易误以为是在叫自己。现在可以正确识别。

另外，针对 Slack 原生 DM 频道 ID 以 D... 开头的情况，消息发送的路由被规范化到对等用户会话。同一个 Slack 私聊对话不会再被拆分成两个不同会话视图，体验更连贯。

iMessage：新增状态过滤和迁移文档

新增命令 openclaw channels status --channel <name>，可以只查看特定渠道（比如 iMessage）的运行状态。同时文档中补充了从 BlueBubbles 迁移到 iMessage 的路径说明，帮助用户在不启动两个频道监控的情况下，单独探测 iMessage 的工作情况。

Discord：语音频道精细化控制和诊断

如果你使用 Discord 语音频道，这个版本加入了一系列实用工具：

  • voice.allowedChannels 配置项：限制机器人可以加入或移动的语音频道。如果未设置，则保持开放行为。这避免了机器人误入不应该出现的频道。
  • 实时语音诊断功能：可以分析说话人轮换、播放重置、插话检测（barge-in）以及音频截断等表现。
  • 默认使用纯 JavaScript 的 opusscript 解码器，不再强制编译原生 @discordjs/opus。如果你追求低延迟、高性能语音，可以通过专用安装脚本开启原生 opus 支持。

四、开发者与插件 SDK：清理公共导出，新增会话操作能力

废弃过时的公共子路径

为了减少插件对内部不稳定接口的依赖，SDK 做了几项清理：

  • 删除了仅被极少数插件使用的 provider-auth-login 公共子路径，Chutes、GitHub Copilot、OpenAI Codex 的认证流程已移回各插件自己的模块中。
  • 移除了 provider 相关的模型、流处理、xAI 兼容性辅助函数，不再对外暴露。调用这些接口的插件已改为使用自有模块。
  • 标记了一批已经存在至少一个月、且没有外部生产代码使用的公共子路径为 deprecated。为了不破坏现有插件，它们仍然可以导入，但会收到警告，新插件应避免使用。

新增会话操作能力

现在插件可以通过 SDK 调用以下与当前会话相关的操作：

  • sendSessionAttachment：向当前会话发送附件
  • 基于 Cron 的 scheduleSessionTurn：在未来的某个时间点触发一次会话轮次，并附带标签清理机制

这些功能都放在分组好的会话命名空间下，更易于发现和使用。

媒体理解扩展

对于需要做图像结构化提取的插件，新增了 extractStructuredWithModel(...) 方法。该方法运行在有边界的图像优先提取流程中，可以附带可选的补充文本上下文。调用方可以选择通过 provider 自身的运行时（如 Codex）来执行。这是一个相对高级的功能，但为构建“看图回答结构化问题”的插件提供了标准路径。

暴露当前模型元数据

原生插件的工具工厂现在可以获取到运行时提供的活动模型元数据。这意味着插件可以根据当前正在使用的模型名、提供商等信息，动态调整自己的行为或记录诊断数据。

五、Cron 任务管理：支持按 ID 查询单条任务

过去查看 Cron 任务可能需要列出所有任务再手动筛选。现在新增了三种方式直接获取单个任务的信息：

  • 直接使用 cron.get 函数
  • 命令行 openclaw cron get <id>
  • 通过代理工具中的 get 操作

这对于自动化脚本或需要精确控制某个定时任务的场景更方便。

六、控制 UI：空白页面恢复面板

如果你曾经遇到过 OpenClaw 的网页控制台（Control UI）一直卡在空白页面，可能是因为前端模块未能正常注册。现在当检测到应用模块从未注册时，页面会显示一个纯 HTML 恢复面板，提供一个重试路径，并附带浏览器扩展问题的排查链接。这直接解决了社区反馈的 #44107 问题。

七、构建、依赖与环境适配

全面迁移到 pnpm 11

整个工作区的包管理已经从旧版本升级到 pnpm 11。包括 Docker 镜像、安装脚本、更新流程和发布工作流都已适配新版本。如果你是从源码编译或自建 Docker 镜像，建议也升级本地的 pnpm 到 11.x 系列。

依赖大量刷新

核心依赖版本批量更新，例如：

  • ACPX @agentclientprotocol/claude-agent-acp → 0.33.1
  • Codex ACP → 0.14.0
  • WhatsApp 驱动从 @whiskeysockets/baileys 转为官方 baileys（版本仍为 7.0.0-rc10）
  • Google GenAI → 2.0.1
  • OpenAI → 6.37.0
  • AWS SDK → 3.1045.0
  • Kysely → 0.29.0

同时，所有直接依赖（非 peer 依赖）现在都做了硬锁定（hard-pin），保证你安装时解析到的版本和开发维护者测试过的完全一致。

Fly.io 容器环境自动检测

当 OpenClaw 运行在 Fly Machines 上时，会自动从环境变量中识别容器类型，并调整网关绑定和 Bonjour 默认行为，使其更符合远程容器的预期。你在本地和 Fly 上可以使用相同的配置，而无需手动区分。

八、语音与实时通信：Talks 和 Discord 语音的细节打磨

Talk 实时语音风格指令

对于使用 talk.realtime 功能的用户，新增了 talk.realtime.instructions 配置项。你可以追加实时语音的风格提示（例如“用更慢的语速强调重要信息”），而不会覆盖 OpenClaw 内置的代理咨询指导。这使得语音人格可以更灵活地根据场景调整。

Discord 语音优化

  • 默认使用 opusscript 纯 JS 解码，避免编译原生模块带来的构建负担。
  • 提供了可选的 @discordjs/opus 原生安装脚本和高性能解码器偏好，供语音性能敏感的场景使用。
  • 新增语音频道白名单（voice.allowedChannels），只有列表中的频道才允许机器人加入或移动。

九、质量保证与测试自动化

Mantis 自动化测试增强

针对 Telegram 渠道的 QA 流程加入了：

  • Telegram 实时 PR 证据自动化：使用 Convex 租凭的凭证、Crabbox 转录捕获、生成 GIF 预览，并自动在 PR 下评论。
  • Telegram 桌面场景构建器：自动租凭 Crabbox，安装原生 Telegram Desktop，配置 OpenClaw Telegram 网关并使用租来的 bot 凭证，记录 VNC 截图和视频。

这意味着未来 Telegram 相关的改动会有更可靠的可视化回归测试。

插件兼容性检查

在 Plugin Prerelease 流程中，新增了一个非阻塞的 plugin-inspector-advisory 构件。它会捕捉捆绑插件的兼容性问题，但不会阻止整个发布流程。这让你在正式发布前就能知道哪些插件可能需要调整。

十、常见问题 (FAQ)

问：我升级到新版本后，Gemini 模型报错说 “model not found”，怎么办？
答：这个版本会自动把旧的 gemini-3-pro-preview 替换成 gemini-3.1-pro-preview。如果你看到错误，可以尝试重新运行 openclaw models auth login --provider google --set-default，或者手动检查配置文件中的模型 ID 是否已被更新。

问：我想限制某个 Discord 用户只能使用天气和计算器工具，不允许执行命令，如何配置？
答：你需要使用新引入的“按发送者工具策略”。首先确定该用户的 sender key（通常是渠道:用户ID 的组合），然后在配置中针对该 key 设置 tools.policy 白名单。具体格式可以参考 agents.defaults.tools.policy 示例。

问：Slack 机器人现在不回应用户 @ 提及了？
答：不是不回，而是现在能正确区分“@ 机器人”和“@ 其他人但机器人也在线程里”。如果你的机器人行为异常，请检查 prompt 中是否包含提及目标的元数据，并微调你的系统提示词。

问：编译时遇到 opus 相关错误，怎么跳过？
答：新版默认已经不要求原生 opus 了。如果你还遇到，请确认你的安装方式没有强制 @discordjs/opus。可以尝试删除 node_modules 并重新 pnpm install，或者设置环境变量 OPENCLAW_DISCORD_VOICE_USE_OPUSSCRIPT=1。

问：我的插件用了 @openclaw/plugin-sdk/provider-auth-login，升级后报错找不到模块。
答：该子路径已被移除。你需要将认证逻辑迁移到插件自己的模块中，或者改用新的通用认证接口。查看本次更新对应的 PR #66933 获取迁移指引。

问：Cron 任务能支持秒级调度吗？
答：目前仍使用标准的 cron 表达式（最小单位为分钟）。秒级调度不在本次发布范围内。

问：控制台一直显示空白，怎么修复？
答：新版本已经加入了恢复面板。如果出现空白，页面会提示一个重试按钮和浏览器扩展排查链接。你可以先尝试清除浏览器缓存并禁用可能干扰的扩展。如果依然无效，查看后端日志确认前端资源是否正确加载。

下一步建议

  • 如果你是普通用户：重点关注 Slack 和 Discord 渠道的体验改进，以及按发送者限制工具权限的配置。升级后建议检查原有 Slack 集成是否仍按预期工作。
  • 如果你是自托管运维：注意 pnpm 11 升级和依赖硬锁定机制。Fly.io 用户可直接部署，自动适配容器环境。
  • 如果你是插件开发者：尽快检查你的插件是否依赖了任何被废弃或移除的公共子路径。升级 SDK 并改用新的会话操作 API 和媒体提取方法。
  • 如果你是 QA 或 CI 负责人：可以研究 Mantis 的 Telegram 自动化方案，看是否可以移植到自己的测试流程中。

这次 beta 版本已经过内部测试，并且修复了多个稳定性和安全性问题。下一个稳定版本预计在两周内发布。如果你遇到任何问题，欢迎在 GitHub 仓库提交 issue，或通过社区频道反馈。