—# OpenClaw 2026.5.22-beta.1 发布：8 大核心更新与文档优化指南
OpenClaw 作为开源的 AI Agent 编排平台，持续为开发者提供强大的自动化能力。本次 2026.5.22-beta.1 版本聚焦文档完善、Agent 安全隔离、Media 处理优化三大方向，共合并 30+ 项社区贡献。无论你是初次部署还是生产环境调优，这篇指南将帮你快速掌握关键变更。
—
一、Agent 子代理安全隔离：默认最小权限原则
核心变更：限制子代理上下文范围
本次更新对 Agent/Subagent 机制进行了重要安全加固。默认情况下，子代理启动时的上下文文件被严格限制为：
- ✅ 保留：
AGENTS.md、TOOLS.md（核心功能定义） - ❌ 排除：
persona.md、identity.md、用户记忆、心跳配置、环境设置文件
查看当前 Agent 上下文配置
openclaw agent config --show-context
如需恢复完整上下文（不推荐生产环境）
openclaw agent config --full-context --env=development
为什么重要：此前子代理继承完整上下文可能导致敏感信息泄露或权限过度扩散。#85283 的修复确保委托工作器（delegated workers）遵循最小权限原则，特别适用于多租户场景或外部工具调用。
—
二、Media 理解策略调整：更可控的图像视频处理
Gemini CLI 自动探测下线
OpenClaw 不再自动探测 Gemini CLI 作为 Media 处理后端。新的优先级策略如下：
| 优先级 | 处理方式 | 触发条件 |
|:—|:—|:—|
| 1 | 已配置的 Provider API（如 OpenAI Vision、Claude 3） | 始终优先 |
| 2 | Antigravity CLI | 仅作为低优先级回退 |
| 3 | 本地处理 | 无外部服务可用时 |
config/media.yaml 示例
media:
providers:
- name: openai
priority: 1
api_key: ${OPENAI_API_KEY}
fallback:
enabled: true
antigravity_cli: true # 显式启用回退
> 迁移提示：此前依赖 Gemini CLI 自动探测的用户，需在配置中显式指定 Provider 或启用 Antigravity 回退。
—
三、Plugin SDK 增强：通用频道消息支持
新增 channel-message 通用接口
Plugin SDK 现支持跨平台的消息统一处理，简化 Telegram、Discord、WhatsApp 等渠道的插件开发：
// plugin-sdk 示例：发送频道消息
import { channelMessage } from '@openclaw/plugin-sdk';
await channelMessage.send({
channel: 'telegram', // 或 'discord', 'whatsapp', 'slack'
target: '@channel_or_user_id',
content: {
text: '任务完成通知',
attachments: [] // 可选媒体文件
},
options: {
ackReaction: true, // 自动确认反应（新增）
threadId: 'optional_thread'
}
});
关联改进：文档新增 Plugin SDK allowlist imports 说明，解决第三方依赖导入的权限边界问题。
—
四、文档体系全面升级：30+ 社区贡献整合
本次文档更新覆盖部署、调试、集成全生命周期，以下是重点板块：
4.1 部署与运维
| 主题 | 关键更新 | 适用场景 |
|:—|:—|:—|
| Gateway 启动路径 | 明确 IPv4-only BYOH 绑定、可信代理范围清除 | 自托管网络配置 |
| Docker/Compose | 新增 Upstash Box 安装指南、Gateway 暴露运行手册 | 云原生部署 |
| EasyRunner | 完整部署流程与配置路径引号规范 | 快速启动验证 |
Gateway IPv4 强制绑定示例
docker run -p 0.0.0.0:8080:8080 \
-e OPENCLAW_GATEWAY_BIND=0.0.0.0 \
openclaw/gateway:v2026.5.22-beta.1
4.2 平台集成优化
- WhatsApp：QR 码刷新机制、408 超时恢复流程
- Telegram：多 Agent 群组管理、ack 反应配置
- Feishu（飞书）：动态 Agent 接入指南
- Zalo：环境变量配置文档
4.3 安全与凭证管理
Bitwarden SecretRef 配置示例
secrets:
provider: bitwarden
config:
server: https://vault.bitwarden.com
secret_ref: "bw://item-id/field-name"
密码存储（password-store）替代方案
secrets:
provider: pass
config:
store_path: ~/.password-store/openclaw/
> 安全提示：文档明确 secrets 明文边界，禁止在日志、调试输出中暴露完整凭证。
4.4 调试与诊断
新增 Browser CDP 诊断、队列转向行为（queue steering）、有限工具故障排查等高级主题，配合 OpenTelemetry 烟雾测试框架的扩展：
执行完整的可观测性验证
openclaw qa-lab smoke --telemetry --prometheus --observability
输出示例
✓ Trace export verified
✓ Metrics collection active
✓ Log aggregation confirmed
✓ Prometheus endpoint: http://localhost:9090
—
五、打包优化：npm 包体积缩减
Packaging 改进排除文档图片与资源文件，显著降低发布包大小：
| 指标 | 优化前 | 优化后 |
|:—|:—|:—|
| 包体积 | ~45 MB | ~12 MB |
| 影响范围 | 无（运行时文档搜索、CLI 行为保持不变） |
验证本地安装包内容
npm pack --dry-run 2>&1 | grep -E "(size|files)"
—
六、维护者工具：Bug Sweep 范围精确定义
openclaw-landable-bug-sweep 技能现排除 Plugin SDK/API 边界工作，确保社区 Bug Bash 聚焦于：
- ✅ UI/UX 细微修复（paper-cut fixes）
- ✅ 文档错别字、链接失效
- ❌ SDK 接口变更、API 兼容性调整
—
常见问题（FAQ）
Q1: 升级后子代理无法访问记忆文件，如何解决？
这是预期的安全行为。如需特定记忆文件，请在 Agent 配置中显式挂载：
agent:
subagent:
context:
include:
- "memory/project-knowledge.md"
exclude: [] # 覆盖默认排除列表
Q2: Gemini CLI 停止自动探测后，图像分析失效怎么办？
检查 Media Provider 配置顺序，建议显式指定 Vision API：
media:
providers:
- name: gemini
type: google
model: gemini-1.5-flash
api_key: ${GEMINI_API_KEY}
# 移除 auto_probe: true（已废弃）
Q3: 如何验证 OpenTelemetry 集成是否正常工作？
使用扩展的 QA-Lab 命令：
openclaw qa-lab smoke --telemetry --verbose
成功标志：trace_id 在日志中完整传播，Jaeger/Zipkin 端点可查询。
Q4: Telegram 多 Agent 群组有哪些新限制？
文档明确：同一群组内多个 Agent 需配置 不同的 bot token，避免消息路由冲突。启用 ackReaction 可减少重复处理。
Q5: 自托管 Gateway 的 IPv6 双栈支持状态？
当前版本聚焦 IPv4-only 绑定稳定性。IPv6 完整支持计划在 2026.6.x 路线图，可通过 GitHub Discussions 跟踪进展。
—
总结与下一步
OpenClaw 2026.5.22-beta.1 的核心价值在于：更安全的 Agent 隔离、更可控的 Media 处理、更完善的文档体系。建议用户：
1. 立即检查：子代理上下文配置是否符合最小权限原则
2. 验证 Media 管道：确认 Provider 优先级符合预期
3. 升级测试：利用 openclaw qa-lab smoke 验证部署健康度
相关阅读
- OpenClaw 官方文档（部署指南）
- GitHub Releases 页面（完整变更日志）
- Plugin SDK 开发手册（API 参考）
- MCP 协议集成教程（Model Context Protocol）
—
参考来源
