—

三、AI Agent 核心功能改进

3.1 会话层级可视化

子 Agent 会话现在在会话选择器中显示为父会话的嵌套项，使用 └─ 前缀清晰标识层级关系：

Main Session (Parent)
├─ Subtask A
└─ Subtask B
   └─ Nested Subtask

修复 Issue #77628，感谢 @chinar-amrutkar 的贡献。

3.2 执行效率优化

• 消除冗余心跳唤醒：子 Agent 会话完成时，父会话不再触发多余的 LLM 调用（修复 #66748）
• 模型故障可见性：当配置的模型后端失败且降级无可见回复时，系统会显示明确的错误提示，同时保留静默回合和纯副作用交付的原有行为

3.3 错误信息友好化

通用提供商内部错误现在会重写为包含支持请求 ID 的用户友好提示，方便排查和反馈：

❌ 旧提示：Error 500: internal_server_error
✅ 新提示：服务暂时不可用（请求 ID: req_abc123），请稍后重试或联系支持

—

四、API 与网关层更新

4.1 OpenAI 兼容端点增强

/v1/chat/completions 端点现在正确处理 max_completion_tokens 和 max_tokens 参数，通过 streamParams.maxTokens 传递至上游提供商。当两者同时存在时，max_completion_tokens 优先。

curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_completion_tokens": 500  # 优先生效
  }'

4.2 流式响应稳定性

• 分块流处理：OpenAI 兼容的 SSE 和 JSON 降级流现在能正确处理分割的数据块
• Azure Responses 诊断：失败时返回有界的首事件诊断信息，而非无限挂起

—

五、安全与权限控制

5.1 Memory Wiki 权限收紧

| 操作 | 所需权限 | 变更 |
|:—|:—|:—|
| 内容摄取 (ingest) | admin | 新增要求 |
| Obsidian 搜索 | write | 从 read 提升 |

感谢 @pgondhi987 的安全贡献（#80897, #80904）。

5.2 构建系统优化

排除在构建条目外的捆绑插件不再复制元数据，防止更新/状态重建时错误提示缺失的 QQ Bot 运行时文件。

—

六、快速升级指南

Docker 部署

拉取最新镜像
docker pull openclaw/openclaw:v2026.5.12-beta.4

带数据卷升级
docker run -d \
  --name openclaw \
  -v openclaw_data:/app/data \
  -p 3000:3000 \
  openclaw/openclaw:v2026.5.12-beta.4

源码升级

使用 pnpm
pnpm update @openclaw/core@beta
pnpm build

验证版本
openclaw --version
应显示: v2026.5.12-beta.4

—

常见问题 (FAQ)

Q1: 从 OpenAI Codex 迁移到 OpenClaw 需要注意什么？

确保使用最新 beta 版本执行迁移命令。迁移前备份现有配置，迁移过程中使用交互式向导的批量选择功能可大幅提高效率。如遇 MODULE_NOT_FOUND，请确认已更新至 2026.5.12-beta.4 或更高版本。

Q2: WhatsApp 集成在 pnpm 11 下仍然安装失败怎么办？

尝试清理 pnpm 缓存并重新安装：

pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

如问题持续，检查是否使用了兼容的 Node.js 版本（建议 v18+）。

Q3: 如何配置子 Agent 的层级会话管理？

无需额外配置，更新后自动生效。在 Control UI 的会话选择器中，子 Agent 会话会以树形结构显示。如需程序化访问，使用会话 API 的 parent_session_id 字段：

const session = await openclaw.sessions.create({
  agent_id: 'sub-agent-1',
  parent_session_id: 'main-session-abc'  // 建立层级关系
});

Q4: max_completion_tokens 和 max_tokens 有什么区别？应该用哪个？

OpenAI 已弃用 max_tokens，推荐使用 max_completion_tokens。OpenClaw 遵循此规范：当两者同时提供时，优先使用 max_completion_tokens。建议新代码统一使用新参数名。

Q5: 自托管部署如何安全存储 OpenAI API 密钥？

推荐使用 auth-profile store 而非环境变量：

交互式配置（默认方式）
openclaw models auth login --provider openai

如需显式使用 API key 方式
openclaw models auth login --provider openai --method api-key

—

总结与下一步

OpenClaw 2026.5.12-beta.4 是一次聚焦稳定性与开发者体验的更新，核心改进包括：

• ✅ Codex 迁移流程彻底修复
• ✅ 消息平台（WhatsApp/Telegram）可靠性提升
• ✅ AI Agent 会话管理与错误处理优化
• ✅ API 网关兼容性与安全性增强