——
OpenClaw 2026.5.12-beta.3 发布：9个关键修复与4项核心改进解析
OpenClaw 作为新一代 AI Agent 自动化平台，持续为开发者提供自托管的智能工作流解决方案。本次 2026.5.12-beta.3 版本聚焦工具链稳定性、第三方集成安全性和主流模型适配三大方向，带来 9 项关键修复与 4 项核心改进。无论你是正在部署生产环境的运维工程师，还是探索 MCP（Model Context Protocol） 集成的开发者，这篇文章将帮你快速掌握升级要点。
—
核心修复：工具链与权限安全双升级
Codex 媒体工具：环境变量 vs 认证配置文件的兼容性修复
此前，当 OpenAI 认证信息存储在 Agent 的 auth-profile store 而非环境变量时，image_generate 等依赖认证的媒体工具会意外失效。本次修复确保了两种认证方式的无缝兼容：
验证 auth-profile 配置
openclaw auth profile list
openclaw auth profile show default --format json
影响场景：使用 Codex harness 进行多 Agent 协作时，子 Agent 的图像生成能力不再受父级认证方式限制。
内存与搜索权限：最小权限原则落地
memory-wiki 模块引入更严格的 OAuth scope 控制：
| 操作 | 所需权限 | 变更说明 |
|:—|:—|:—|
| 数据摄取 (ingest) | admin | 新增要求，防止误操作 |
| Obsidian 搜索 | write | 从 read 提升，匹配实际写入需求 |
检查当前 token 权限范围
openclaw memory wiki auth verify --show-scopes
> 感谢社区贡献者 @pgondhi987 的安全审计反馈。
—
开发者体验：调试与会话可视化改进
子 Agent 会话层级可视化
长期困扰开发者的 #77628 问题终于解决——会话选择器现在用 └─ 前缀清晰展示父子关系：
├─ 主会话 (parent-session-uuid)
│ └─ 子 Agent 执行 (subagent-session-uuid)
│ └─ 孙子 Agent 执行 (nested-session-uuid)
配置路径：Control UI → Sessions → 下拉选择器
自动回复故障透明化
当配置的模型后端失败且降级策略未产生可见回复时，系统现在会显式报错而非静默失败。同时保留以下场景的静默行为：
- 故意设计的空回复轮次
- 纯副作用执行（如状态更新、日志记录）
// 自动回复配置示例
{
"autoReply": {
"model": "openai/gpt-4o",
"fallback": {
"enabled": true,
"errorVisibility": "explicit" // 新增：explicit | silent
}
}
}
—
性能优化：减少无效 LLM 调用
子 Agent 心跳机制精简
修复 #66748：子 Agent 会话执行完成时，父会话不再收到冗余的心跳唤醒 (heartbeat wake-ups)。实测可减少 15-30% 的无效 LLM 调用。
查看 Agent 执行统计
openclaw agents exec stats --session-id --include-heartbeats
流式响应稳定性增强
OpenAI 兼容 SSE 和 JSON fallback 流现在能正确处理分块传输，Azure Responses 流在首事件超时时会返回明确的诊断信息而非无限挂起。
—
模型适配：OpenAI 与 Gemini 双更新
OpenAI 认证流程优化
CLI 登录命令行为调整，更符合开发者直觉：
默认启动 ChatGPT/Codex 账号登录（浏览器 OAuth）
openclaw models auth login --provider openai
显式使用 API Key 方式（原有行为）
openclaw models auth login --provider openai --method api-key
Gemini 3 Pro Preview ID 规范化
Google retiring 旧版模型 ID 期间，OpenClaw 在三个入口自动映射：
| 用户输入 | 实际调用 |
|:—|:—|
| google/gemini-3-pro-preview | google/gemini-3.1-pro-preview |
| SDK OAuth 默认配置 | 自动重写 |
| API Key 仅重置默认时 | 目录行自动转换 |
验证当前默认模型
openclaw models default show
—
构建与部署：WhatsApp 安装修复
Baileys 库的 libsignal git 子依赖在 pnpm 11 下导致源码安装失败。本次更新允许固定该依赖，本地构建和检查可正常完成：
清理后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install --frozen-lockfile
验证 WhatsApp 插件状态
openclaw plugins status whatsapp
—
常见问题 (FAQ)
Q1: 升级后 Codex 的 image_generate 仍提示认证失败怎么办？
检查 auth-profile 中是否包含有效的 OpenAI 凭证，而非仅依赖环境变量：
openclaw auth profile set-default
openclaw tools verify image_generate
Q2: memory-wiki 的 admin scope 如何申请？
联系你的 OpenClaw Gateway 管理员，在 OAuth 应用配置中添加 wiki:admin scope，或临时使用 API Key 认证绕过。
Q3: 子 Agent 的层级显示会影响现有 API 调用吗？
不会。└─ 前缀仅作用于 Control UI 的会话选择器，所有 API 返回的 session ID 和父子关系字段保持不变。
Q4: Gemini 3.1 测试需要手动修改配置吗？
不需要。通过 openclaw models auth login --set-default 或 SDK 构建的流程会自动完成 ID 映射。但建议验证：
openclaw models list --provider google | grep gemini
Q5: 生产环境建议立即升级吗？
beta.3 包含重要的权限安全修复和性能优化，建议测试环境验证后升级。若使用 WhatsApp 集成或 Codex 工具链，此版本为推荐最低版本。
—
总结与下一步
OpenClaw 2026.5.12-beta.3 通过 9 项修复和 4 项改进，显著提升了 AI Agent 平台的稳定性、安全性和开发者体验。关键行动建议：
1. 安全优先：检查 memory-wiki 的权限配置，确保符合新的 scope 要求
2. 性能调优：利用子 Agent 心跳优化，降低 LLM 调用成本
3. 模型迁移：验证 Gemini 3.1 的自动映射是否正常
—
相关阅读
—
参考来源
