——
OpenClaw 2026.5.12-beta.2 发布：10 项关键修复与 AI Agent 性能优化详解
OpenClaw 2026.5.12-beta.2 版本带来了 10 余项关键修复与功能改进，重点解决了 AI Agent 认证流程、Memory Wiki 权限控制、WhatsApp 安装兼容性以及 Codex 工具链的稳定性问题。本文将逐一解析这些更新，帮助开发者快速上手并规避常见坑点。
—
核心亮点速览
| 类别 | 更新数量 | 重点改进 |
|:—|:—|:—|
| Bug 修复 | 9 项 | 认证流程、权限控制、流式响应 |
| 功能变更 | 5 项 | OpenAI 网关、Gemini 模型映射、CLI 登录 |
| 性能优化 | 2 项 | 子代理心跳、SSE 流处理 |
—
一、Codex 与认证系统修复
1.1 修复 auth-profile backed 媒体工具可用性问题
问题背景：当 OpenAI 认证信息存储在 Agent 的 auth-profile 而非环境变量时，image_generate 等媒体工具会意外失效。
修复内容：Codex harness 现在能正确识别并保留基于 auth-profile 的媒体工具权限，无论认证信息存储位置如何。
配置建议：
推荐：使用 auth-profile 存储敏感凭证
openclaw models auth login --provider openai
而非直接写入环境变量
1.2 OpenAI CLI 登录流程优化
新版调整了默认登录行为：
新默认：启动 ChatGPT/Codex 账户登录（网页授权）
openclaw models auth login --provider openai
显式指定 API Key 方式（自动化场景推荐）
openclaw models auth login --provider openai --method api-key
> 💡 最佳实践：个人开发使用默认登录，CI/CD 流水线使用 --method api-key。
—
二、Memory Wiki 权限安全加固
2.1 强制 Admin 权限执行数据摄取
修复编号：#80897
此前 Memory Wiki 的数据摄取（ingest）操作未严格校验权限，存在越权风险。现已强制要求 admin scope：
| 操作 | 所需权限 | 影响 |
|:—|:—|:—|
| ingest | admin | 防止普通用户批量写入知识库 |
| obsidian-search | write | 限制搜索范围为授权笔记 |
权限配置示例：
~/.openclaw/auth-profiles.yaml
my-wiki-profile:
provider: memory-wiki
scopes:
- read
- write # 搜索需要
# - admin # 摄取需要，按需开启
—
三、WhatsApp 安装与构建修复
3.1 解决 Baileys libsignal 依赖问题
问题现象：使用 pnpm 11 进行源码安装时，Baileys 的 git 子依赖 libsignal 无法正确解析，导致安装失败。
修复方案：允许 pnpm 识别 Baileys 固定的 libsignal 子依赖，支持完整源码安装和本地校验。
安装命令：
确保 pnpm 版本 >= 11
pnpm --version
安装 WhatsApp 插件
openclaw plugins install whatsapp
或源码安装
git clone https://github.com/openclaw/openclaw.git
pnpm install # 现在可正常完成
—
四、Agent 执行与会话管理优化
4.1 子代理会话可视化（#77628）
改进内容：会话选择下拉菜单中，子代理会话现在以 └─ 前缀嵌套显示在父会话下方，层级关系一目了然。
会话选择器示例：
├─ main-session-001
│ └─ subagent-session-001a
│ └─ subagent-session-001b
├─ main-session-002
4.2 消除冗余心跳唤醒（#66748）
性能影响：修复前，子代理会话完成时会触发父会话的冗余 LLM 调用；修复后完全跳过此类唤醒，显著降低 Token 消耗。
适用场景：嵌套 Agent 工作流、批量任务分发、并行子任务执行。
—
五、流式响应与错误处理改进
5.1 OpenAI 兼容 SSE 流稳定性
修复内容：
- 保持 SSE 和 JSON fallback 流在分块传输时的持续消费
- Azure Responses 流在首事件失败时返回有界诊断信息，而非无限挂起
技术细节：
// 流式请求示例（修复后更稳定）
const response = await fetch('http://localhost:3000/v1/chat/completions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Hello' }],
stream: true, // 启用 SSE
// max_completion_tokens 现在正确透传（见下文）
}),
});
5.2 提供商错误信息友好化
将技术性的 provider internal error 重写为包含请求 ID 的用户友好提示，便于问题追踪：
修复前：Error: provider internal error (code: 500)
修复后：服务暂时不可用，请稍后重试。如需协助，请提供请求 ID: req_abc123xyz
—
六、网关与模型配置变更
6.1 OpenAI HTTP 网关支持 Token 限制
关键变更：/v1/chat/completions 端点现在正确透传 max_completion_tokens 和 max_tokens 参数。
| 参数 | 优先级 | 透传方式 |
|:—|:—|:—|
| max_completion_tokens | 高（优先） | streamParams.maxTokens |
| max_tokens | 低（兼容） | streamParams.maxTokens |
请求示例：
curl http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Summarize this"}],
"max_completion_tokens": 150
}'
6.2 Gemini 3 Pro Preview ID 规范化
Google 已退役 gemini-3-pro-preview，OpenClaw 自动映射至新版：
自动替换（无需手动修改配置）
gemini-3-pro-preview → gemini-3.1-pro-preview
影响场景：
- SDK OAuth 认证结果默认配置
openclaw models auth login --set-default直接认证- API Key onboarding 仅应用 Agent 默认值时
—
七、自动回复与构建优化
7.1 模型故障可见性提升
当配置的模型后端失败且降级无可见回复时，现在会显示明确错误（同时保留故意静默的回合和纯副作用交付）。
7.2 排除插件构建元数据
修复了被排除在构建条目外的捆绑插件（如 QQ Bot）仍会宣传缺失运行时文件的问题，避免更新/状态重建时的误导信息。
—
常见问题 FAQ
Q1: 升级后 WhatsApp 插件安装仍失败怎么办？
确认 pnpm 版本 ≥ 11，并清理缓存重试：
pnpm store prune
rm -rf node_modules
pnpm install
Q2: 如何为子代理配置独立的 auth-profile？
子代理继承父代理的 auth-profile，但可通过 OPENCLAW_AUTH_PROFILE 环境变量覆盖：
OPENCLAW_AUTH_PROFILE=subagent-profile openclaw agent run subagent.yaml
Q3: Memory Wiki 的 admin scope 如何申请？
联系你的 OpenClaw 实例管理员，或通过以下命令检查当前权限：
openclaw auth profiles list --verbose
Q4: max_completion_tokens 和 max_tokens 同时设置会怎样？
max_completion_tokens 优先生效，这是 OpenAI 最新 API 规范的行为。
Q5: 如何验证 Gemini 模型 ID 是否已自动更新？
执行以下命令查看实际使用的模型 ID：
openclaw models list --provider google | grep gemini
—
总结与下一步
OpenClaw 2026.5.12-beta.2 聚焦 认证安全、流稳定性 和 开发者体验 三大方向，建议所有使用 AI Agent、Memory Wiki 或 WhatsApp 集成 的用户尽快升级。
推荐操作：
1. 阅读 OpenClaw 升级指南 完成版本迁移
2. 检查现有 Agent 的 auth-profile 配置
3. 验证 WhatsApp 等插件的依赖兼容性
相关阅读：
—
