—# OpenClaw 2026.5.12-beta.8 发布：5大核心改进与安装指南

OpenClaw 2026.5.12-beta.8 版本带来了显著的架构优化，核心安装包体积大幅缩减，同时增强了 AI Agent 工作流的稳定性和多平台集成能力。本文将深入解析 5 项关键更新，并提供可直接落地的配置方案。

—

一、核心改进概览

本次更新聚焦于三个方向：依赖精简、稳定性增强和安全加固。以下是值得优先关注的变更：

| 改进领域 | 关键变更 | 影响 |
|———|———|——|
| 依赖管理 | AWS SDK 等外部化 | 核心安装包减小 40%+ |
| 消息流 | 自动滚动模式持久化 | WebChat 体验优化 |
| 故障恢复 | ACP 备用后端机制 | 关键任务可靠性提升 |
| 平台集成 | Telegram 长连接优化 | Bot 稳定性显著改善 |
| 安全沙箱 | Windows 凭证路径加固 | 防止敏感信息泄露 |

—

二、详细功能解析

2.1 依赖外部化：更轻量的核心安装

Amazon Bedrock 和 Bedrock Mantle 提供商包现已从核心安装中分离。这意味着：

基础安装（不再包含 AWS SDK）
docker pull openclaw/openclaw:2026.5.12-beta.8

按需添加 Bedrock 支持
openclaw plugin install provider-bedrock

同理，Slack、OpenShell Sandbox 和 Anthropic Vertex 插件也改为按需安装：

安装 Slack 集成
openclaw plugin install slack

安装 Anthropic Vertex
openclaw plugin install anthropic-vertex

收益：最小化部署场景（如边缘节点或 CI/CD 环境）的镜像体积和启动时间大幅降低。

2.2 WebChat 自动滚动：三种模式自由切换

控制界面新增持久化的自动滚动模式选择器，解决长期困扰用户的滚动行为不一致问题：

| 模式 | 行为 | 适用场景 |
|—–|——|———|
| Near-bottom（默认） | 接近底部时自动跟随 | 常规对话 |
| Always follow | 始终跟随流式输出 | 实时监控 |
| Manual | 关闭自动滚动，使用”新消息”按钮 | 需要回溯历史时 |

配置持久化至浏览器本地存储，刷新页面后设置保留。

2.3 ACP 故障转移：关键任务的可靠性保障

ACP（Agent Control Protocol） 新增 acp.fallbacks 配置，允许为单个 ACP 回合配置备用运行时后端：

openclaw.yaml 配置示例
acp:
  fallbacks:
    - name: "primary"
      backend: "claude-cli"
      priority: 1
    - name: "backup"
      backend: "openai-gpt4"
      priority: 2
      # 主后端不可用时自动切换
      triggerOn: ["timeout", "rate_limit", "unavailable"]

关键特性：切换发生在任何输出产生之前，确保用户不会看到中断或混合的响应。

2.4 Telegram 集成：三大稳定性修复

针对生产环境高频反馈的问题，本次集中修复：

长连接保活：将 Bot API 轮询移至独立工作线程，配备本地持久化队列，避免主事件循环阻塞导致的消息丢失。

Telegram 配置优化建议
telegram:
  bot:
    polling:
      workerIsolation: true      # 启用独立工作线程
      spoolPath: "/var/spool/openclaw/telegram"  # 持久化队列路径

HTML 格式保留：定时任务（Cron）触发的公告消息，Markdown 链接现在正确渲染为可点击格式，而非纯文本锚标签。

智能媒体过滤：启用 requireMention 时，未提及机器人的群组媒体消息将跳过下载，减少无效请求。

2.5 安全加固：Windows 沙箱与凭证管理

Windows 沙箱 现在将 USERPROFILE 纳入阻断路径，防止以下场景的信息泄露：

即使 HOME 环境变量指向其他位置
以下路径仍被禁止绑定：
C:\Users\\.codex
C:\Users\\.openclaw
C:\Users\\.ssh

凭证解析严格化：停止从宽泛的 ^[A-Z_][A-Z0-9_]*$ 模式推断提供商环境变量，仅通过结构化 SecretRefs 解析：

推荐：显式密钥引用
secrets:
  providers:
    openai:
      apiKey:
        envRef: "OPENAI_API_KEY"  # 明确指定
  # 不再自动识别 OPENAI_API_KEY_2024 等变体

—

三、快速开始

Docker 一键部署

拉取最新镜像
docker pull openclaw/openclaw:2026.5.12-beta.8

最小化启动（无外部提供商）
docker run -d \
  --name openclaw \
  -p 8080:8080 \
  -v $(pwd)/data:/data \
  openclaw/openclaw:2026.5.12-beta.8

完整功能启动（含常用插件）
docker run -d \
  --name openclaw-full \
  -p 8080:8080 \
  -e OPENCLAW_PLUGINS="slack,telegram,bedrock" \
  -v $(pwd)/data:/data \
  openclaw/openclaw:2026.5.12-beta.8

CLI 安装与初始化

安装 CLI
npm install -g @openclaw/cli

初始化配置（自动传递提供商密钥）
openclaw init \
  --openai-api-key "$OPENAI_API_KEY" \
  --anthropic-api-key "$ANTHROPIC_API_KEY"

验证安装
openclaw version
输出: 2026.5.12-beta.8

—

四、常见问题 (FAQ)

Q1: 升级后现有工作流会中断吗？

不会。依赖外部化仅影响新安装，已有配置中的插件引用保持兼容。建议升级后运行 openclaw doctor 检查插件状态。

Q2: 如何确认 ACP 故障转移已生效？

查看运行时日志中的 acp.fallback 事件：

openclaw logs --filter "acp.fallback" --follow
预期输出: [acp.fallback] primary backend unavailable, switching to backup: openai-gpt4

Q3: Telegram Bot 消息仍偶尔丢失？

检查 spoolPath 的磁盘权限和可用空间，并确认 workerIsolation: true 已启用：

docker exec openclaw ls -la /var/spool/openclaw/telegram/

Q4: 最小化安装能节省多少空间？

对比测试数据（AMD64 镜像）：

• 完整版：~1.2 GB
• 最小化版（无 AWS/Vertex）：~680 MB
• 节省约 43%

Q5: Windows 沙箱阻断会影响正常开发吗？

仅影响显式绑定到用户配置目录的容器路径。标准开发工作流使用项目级 .openclaw 配置不受影响。

—

五、总结与下一步

OpenClaw 2026.5.12-beta.8 通过模块化架构降低了部署门槛，以故障转移机制提升了生产可靠性，并在安全基线上做了重要加固。建议：

1. 新用户：从最小化安装开始，按需添加插件
2. 现有用户：优先升级 Telegram 和 ACP 相关配置
3. 企业部署：评估 ACP fallbacks 对 SLA 的改善

—

相关阅读

• OpenClaw 官方文档
• Docker 部署最佳实践
• ACP 协议详解
• Telegram Bot 集成指南

—

参考来源

• GitHub Release: openclaw 2026.5.12-beta.8
• OpenClaw 官方文档
• Docker Hub: openclaw/openclaw
• 阅读原文：OpenClaw 教学小站

——

OpenClaw v2026.5.12-beta.5 发布：10+ 安全修复与 AI Agent 性能优化详解

OpenClaw 2026.5.12-beta.5 版本带来了超过 15 项关键修复与优化，重点强化了设备配对安全、Gateway 协议兼容性以及 AI Agent 执行效率。无论你是自托管用户还是企业级部署，这次更新都显著提升了系统的稳定性与安全性。

本文将逐条解析核心变更，并提供升级建议与配置示例。

—

一、Gateway 协议升级：v4 客户端强制与实时流式优化

1.1 强制 v4 客户端协议

本次更新要求所有 SDK 客户端必须升级至 Gateway Protocol v4，主要改进包括：

• 显式 deltaText/replace 帧：助手更新现在通过独立帧传输，客户端无需本地 diff 计算
• 降低延迟：减少 30-50% 的消息处理开销

// v4 客户端连接示例
const client = new OpenClawClient({
  protocolVersion: 'v4',  // 必须指定
  streamMode: 'deltaText' // 启用增量文本流
});

1.2 Talk Session 作用域传递

修复了 Gateway 在解析器中未正确传递 Talk session scope 的问题，确保多轮对话的上下文连续性。

—

二、安全加固：设备配对与权限控制

2.1 三重配对验证机制

本次更新引入了更严格的设备配对流程，涉及三个 AI 辅助安全补丁：

| 功能 | 变更 | 影响 |
|:—|:—|:—|
| 设置码配对 | 强制审批 | 防止未授权设备接入 |
| 浏览器设备配对 | 显式确认 | 阻断自动化攻击向量 |
| Control UI 代理访问 | 前置配对要求 | 保护敏感操作接口 |

查看待审批配对请求
openclaw admin pairings list --pending

批准特定设备
openclaw admin pairings approve --id 

2.2 可信代理源验证强化

针对 trusted-proxy 配置的源 IP 验证逻辑进行了加固，防止伪造头部绕过安全策略。

—

三、AI Agent 核心优化

3.1 同进程子代理调度

重大性能改进：子代理（subagent）完成交接现在通过进程内调度器直接传递，不再经过 Gateway RPC 回环。

收益：

• 延迟降低 60-80ms（典型场景）
• 减少 Gateway 连接池压力
• 避免循环依赖导致的死锁

3.2 工具参数模式修复

修复了 OpenAI 兼容模式下的 array 类型参数验证问题。插件工具现在会自动添加宽松的 items 模式，防止因缺失数组元素定义而被拒绝。

// 修复前可能失败的工具定义
{
  "type": "array",
  // 缺少 items 定义
}

// 修复后自动补全
{
  "type": "array",
  "items": { "type": "string" }  // 自动注入的宽松模式
}

3.3 LLM 空闲超时与模型回退

当 LLM idle watchdog 触发超时时，系统现在会：
1. 尝试 profile rotation（配置档案轮换）
2. 自动切换至 configured model fallback
3. 避免代理任务无响应挂起

3.4 Claude CLI 会话记忆修复

针对 Anthropic Claude 的修复：会话轮换后，系统会从有界的 OpenClaw 对话记录中重新播种上下文，彻底解决”对话失忆”问题。

—

四、插件系统与集成修复

4.1 飞书/ WhatsApp / Line 媒体限制

入站媒体附件现在强制执行流式大小限制，避免超大文件导致内存溢出：

openclaw.config.yaml 示例
plugins:
  whatsapp:
    media:
      maxDownloadSize: "50MB"  # 流式截断，非全量缓冲
      streamChunkSize: "64KB"

4.2 企业微信插件更新

• 官方引导安装升级至 @wecom/wecom-openclaw-plugin@2026.5.7
• 修复现有托管 npm 安装的目录冲突问题

升级企业微信插件
openclaw plugin update @wecom/wecom-openclaw-plugin

4.3 第三方依赖管理优化

| 场景 | 修复内容 |
|:—|:—|
| 插件安装/更新 | 保留第三方 peer dependencies，避免依赖树重计算时丢失 |
| 插件卸载 | 自动清理孤立的 peer dependencies，失败不阻塞卸载流程 |

—

五、Docker 与部署修复

5.1 容器路径固定

关键安全修复：Docker 构建时固定容器内路径，防止宿主机过期的 .env 中 OpenClaw 路径泄露到 Linux 容器。

修复后的 Dockerfile 片段
构建阶段路径完全隔离
ARG OPENCLAW_ROOT=/opt/openclaw
ENV OPENCLAW_CONFIG_PATH=${OPENCLAW_ROOT}/config
不再读取宿主机 .env 中的路径变量

5.2 安装器版本锁定

--version 参数现在正确作用于 git 安装模式，并从检入的 lockfile 安装，避免 pnpm 的 minimum-release-age 门控导致安装失败。

指定版本安装示例
curl -fsSL https://openclaw.dev/install.sh | bash -s -- --version v2026.5.12-beta.5

—

六、GitHub Copilot 图像理解修复

针对 Copilot Gemini 图像描述的修复：

• OAuth token 自动交换为 Copilot API token
• Gemini 图像负载路由至 Chat Completions 端点

// 图像理解请求现在正常工作
const result = await openclaw.copilot.vision.analyze({
  image: base64EncodedImage,
  prompt: "描述这张图片的内容"
});

—

七、配置系统原子化更新

语义配置变更现在支持集中序列化与重试：

• 并发命令可安全 rebase 变更，而非覆盖或各自实现重试循环
• 消除配置竞争导致的意外状态

—

常见问题 (FAQ)

Q1: 升级到 v2026.5.12-beta.5 是否需要修改现有配置？

不需要。本次更新向后兼容，但建议检查：

• SDK 客户端是否支持 Gateway Protocol v4
• Docker 部署是否重新构建镜像以获取路径隔离修复

Q2: 设备配对审批功能会影响现有自动化流程吗？

会。如果现有流程依赖自动设备配对，需要：
1. 在管理后台预批准已知设备
2. 或使用服务账户令牌绕过配对流程（推荐用于 CI/CD）

Q3: AI Agent 的同进程优化对现有插件有影响吗？

无影响。这是内部调度优化，插件 API 保持不变。性能提升对透明，无需代码变更。

Q4: 如何验证 Claude CLI 的会话记忆修复是否生效？

运行多轮图像分析任务，检查第三轮及以后是否仍能引用前面对话内容。修复前会出现”忘记”前文的情况。

Q5: 企业微信插件升级失败怎么办？

强制清理后重装
openclaw plugin uninstall @wecom/wecom-openclaw-plugin --force
openclaw plugin install @wecom/wecom-openclaw-plugin@2026.5.7

—

总结与下一步

OpenClaw v2026.5.12-beta.5 是一次安全优先、性能并重的重要更新：

| 优先级 | 行动项 |
|:—|:—|
| 🔴 高 | 立即升级 Docker 部署，修复路径泄露 |
| 🟡 中 | 审查设备配对策略，启用审批流程 |
| 🟢 低 | 评估 SDK v4 迁移，获取流式优化 |

推荐操作：

备份后升级
openclaw backup create --name pre-2026.5.12
openclaw update --version v2026.5.12-beta.5
openclaw doctor  # 验证安装状态

—

相关阅读

• OpenClaw 官方文档
• Gateway Protocol v4 迁移指南
• AI Agent 最佳实践
• Docker 自托管部署教程

—

参考来源

• OpenClaw GitHub Releases v2026.5.12-beta.5
• OpenClaw 官方文档
• Gateway Protocol 规范
• MCP (Model Context Protocol) 介绍
• 阅读原文：OpenClaw 教学小站

——

OpenClaw v2026.5.12-beta.6 更新解读：15项关键修复与安全增强

一句话总结：本次更新聚焦 AI Agent 稳定性、第三方平台集成深度、以及多层级安全加固，为构建企业级自动化工作流提供更可靠的基础设施。

如果你正在使用 OpenClaw 连接 WhatsApp、Telegram、飞书 等渠道，或部署 自托管 (self-hosted) 方案管理敏感业务，这篇文章将帮你快速识别影响现有系统的关键变更。

—

一、核心功能改进

1. AI Agent 会话预创建机制

问题背景：此前当 Agent A 向尚未启动的 Agent B 发送消息时，会因目标会话不存在而失败。

解决方案：OpenClaw 现在在首次 sessions_send 或网关发送前，自动创建配置好的 Agent 主会话。这意味着：

// 此前：需要手动确保目标 Agent 已启动
// 现在：消息队列自动处理会话生命周期
agentA.sendTo(agentB, "任务指令"); // 即使 agentB 未启动也能成功

适用场景：多 Agent 协作工作流、事件驱动的自动化编排。

—

2. iMessage 媒体发送优化

修复了纯图片消息中 占位文本可见的问题，同时保留内部 echo key 防止自回复循环。

| 场景 | 修复前 | 修复后 |
|:—|:—|:—|
| 发送单张图片 | 用户看到 文本 | 仅显示图片，无多余文本 |
| 快速连续发送 | 可能触发重复回复 | echo key 有效去重 |

—

3. GitHub Copilot 图像理解能力恢复

技术细节：

• 新增 OAuth token 与 Copilot API token 的自动交换机制
• Gemini 图像负载改道至 Chat Completions 接口

配置 Copilot 图像理解（示例）
openclaw config set github.copilot.image_understanding=true

此前使用 Gemini 模型时图像描述功能失效的问题已彻底解决。

—

二、安全与权限强化

本次更新引入 4 项 AI 辅助的安全策略，显著降低未授权访问风险：

| 功能 | 变更内容 | 影响 |
|:—|:—|:—|
| 设备配对 | 设置码 (setup-code) 配对需显式审批 | 防止暴力破解 |
| 浏览器配对 | 浏览器设备配对需显式确认 | 阻断钓鱼攻击 |
| 控制界面 | 代理范围访问前需完成 Control UI 配对 | 权限最小化 |
| 节点配对 | 待审批 Node 的命令/能力/权限对管理员隐藏 | 减少攻击面 |

配置建议：

openclaw.yaml 安全策略示例
security:
  pairing:
    setup_code_approval: required      # 新增
    browser_device_approval: required  # 新增
    control_ui_before_proxy: required  # 新增
  gateway:
    hide_pending_node_capabilities: true  # 新增

—

三、平台集成优化

飞书 / WhatsApp / Line 媒体限制

新增入站媒体大小上限检查，在下载流读取阶段即拦截超大附件，避免内存溢出：

// 插件配置示例
{
  "plugin": "feishu",
  "config": {
    "inbound_media_max_size": "50MB",  // 新增配置项
    "stream_buffer_size": "1MB"
  }
}

企业微信 (WeCom) 插件更新

官方 onboarding 安装包升级至 @wecom/wecom-openclaw-plugin@2026.5.7，并修复现有托管 npm 安装的目录冲突问题。

更新现有 WeCom 插件
openclaw plugin update @wecom/wecom-openclaw-plugin

—

四、开发者体验提升

插件安装优化

问题：大型依赖树的受信任包因第三方运行时内部被误拦截。

修复：安装时代码安全扫描仅针对插件自有运行时入口点，同时保留依赖清单黑名单检查。

此前可能触发警告
openclaw plugin install large-trusted-plugin

现在：快速通过，仅扫描插件核心代码

对等依赖管理

• 安装时：保留第三方对等依赖到托管 npm 根目录
• 卸载时：自动清理孤立的对等依赖，失败不阻塞清理流程

配置并发控制

语义配置变更现在支持中央序列化与重试，并发命令可安全 rebase 而非相互覆盖：

// 此前：并发配置更新可能丢失
Promise.all([
  config.set("key1", "value1"),
  config.set("key2", "value2")  // 可能覆盖 key1 的变更
]);

// 现在：自动合并安全变更

—

五、基础设施修复

Docker 路径固定

修复了宿主机 .env 中的旧 OpenClaw 路径可能泄漏到 Linux 容器的问题：

推荐使用 pinned 路径的镜像版本
FROM openclaw/openclaw:v2026.5.12-beta.6
或明确指定 setup-time 路径
ENV OPENCLAW_PATH=/opt/openclaw

Anthropic Claude CLI 会话记忆

修复会话轮换后的”对话失忆”问题：Claude CLI 新鲜会话重试时，现在从有界的 OpenClaw 转录历史重新播种上下文。

查看转录历史边界设置
openclaw config get anthropic.transcript_history_bound  # 默认 100 轮

—

六、网关协议升级 (破坏性变更注意)

Gateway Protocol v4 现已要求客户端升级：

| 变更项 | 说明 |
|:—|:—|
| 最低版本 | v4 |
| 新增帧类型 | deltaText（增量文本） |
| | replace（全量替换） |
| 优势 | SDK 客户端无需本地 diff 即可消费助手更新 |

SDK 升级示例：

// 旧版 SDK（需本地 diff）
const client = new OpenClawClient({ version: 'v3' });

// 新版 SDK（推荐）
const client = new OpenClawClient({ 
  version: 'v4',
  streamMode: 'delta'  // 自动处理 deltaText/replace
});

—

常见问题 (FAQ)

Q1: 升级后现有 Agent 工作流会中断吗？

不会。Agent 会话预创建是向后兼容的增强，仅解决此前可能失败的边缘场景。建议测试多 Agent 消息传递以验证改进效果。

Q2: 安全审批功能是否强制启用？

默认启用，但可配置。如需降级（不推荐生产环境）：

security:
  pairing:
    setup_code_approval: optional

Q3: 如何确认 Gateway Protocol 版本？

openclaw gateway version
或检查连接日志中的 protocol-version 字段

Q4: Docker 部署需要重新构建镜像吗？

建议重新拉取。若使用自定义 Dockerfile，请显式设置 OPENCLAW_PATH 环境变量以避免路径泄漏。

Q5: 插件安装扫描策略变更会影响安全审计吗？

不会。黑名单检查仍然全局执行，仅放宽对受信任包内部依赖的深入扫描，平衡安全与性能。

—

总结与下一步

OpenClaw v2026.5.12-beta.6 的核心价值在于：
1. 可靠性：Agent 会话预创建、配置并发控制
2. 安全性：四层配对审批机制、路径隔离
3. 兼容性：Copilot 图像理解、多平台媒体优化

推荐行动：

• [ ] 升级测试环境验证 Agent 工作流
• [ ] 审查并更新安全策略配置
• [ ] 规划 Gateway Protocol v4 SDK 迁移

—

相关阅读

• OpenClaw 官方文档
• MCP (Model Context Protocol) 入门指南
• OpenClaw Docker 部署最佳实践
• 构建多 Agent 协作系统

—

参考来源

• OpenClaw v2026.5.12-beta.6 Release Notes
• OpenClaw 官方文档
• GitHub Copilot API 文档
• MCP 协议规范
• 阅读原文：OpenClaw 教学小站

—# OpenClaw 新增功能：如何在 Telegram 中使用 Web App 演示按钮

一句话总结：OpenClaw 最新版本正式支持 Telegram Web App 演示按钮，让 AI Agent 能够通过沉浸式网页界面与用户交互，大幅提升 Bot 的用户体验。

如果你正在开发 Telegram Bot，一定遇到过这样的困境：纯文本回复难以展示复杂信息，而跳转到外部链接又打断了对话流程。OpenClaw 团队最新提交的代码（commit 5f8e1dd）正是为了解决这个痛点——通过原生支持的 Web App 演示按钮，在聊天窗口内直接嵌入交互式网页应用。

—

什么是 Telegram Web App 演示按钮

Web App 演示按钮（Web App Presentation Buttons）是 Telegram Bot API 提供的一项高级功能，允许 Bot 在聊天界面中展示全屏或半屏的网页应用，无需用户离开对话环境。

与传统按钮相比，这项功能的核心优势在于：

| 功能特性 | 传统内联按钮 | Web App 演示按钮 |
|———|———–|—————|
| 交互形式 | 固定选项点击 | 完整网页交互 |
| 数据展示 | 纯文本/图片 | 动态图表、表单、地图等 |
| 用户体验 | 线性对话流 | 沉浸式操作界面 |
| 开发复杂度 | 低 | 中等（需前端配合） |

OpenClaw 作为开源 AI Agent 框架，此次更新将这一能力深度集成到自动化工作流中，开发者无需手动调用 Telegram Bot API 即可启用。

—

核心应用场景

场景一：数据可视化仪表盘

当用户查询销售数据时，Bot 可直接弹出交互式图表：

// OpenClaw 工作流配置示例
{
  "trigger": "销售报表",
  "action": "telegram_webapp",
  "config": {
    "url": "https://your-domain.com/dashboard",
    "button_text": "📊 查看实时数据",
    "mode": "fullscreen"  // 或 "compact" 紧凑模式
  }
}

场景二：复杂表单收集

用户注册、订单填写等场景，避免多轮对话的繁琐：

// 在 OpenClaw Agent 中调用
const result = await ctx.telegram.presentWebApp({
  title: "完善个人信息",
  url: ${WEBAPP_BASE}/form?userId=${ctx.user.id},
  // 支持返回数据自动解析到工作流变量
  return_data: true
});

场景三：AI 生成内容的交互确认

让用户体验 生成式 AI 的实时调整能力，如图片编辑、文案优化等。

—

快速开始：5 分钟完成配置

步骤 1：确认 OpenClaw 版本

更新到包含该功能的最新版本
npm update @openclaw/core
或
pip install -U openclaw

验证版本
openclaw --version  # 需 >= 0.12.0

步骤 2：配置 Telegram Bot 权限

在 @BotFather 中启用 Web App 权限：

对话流程
1. /mybots → 选择你的 Bot
2. Bot Settings → Menu Button
3. Configure menu button → 输入 Web App URL

步骤 3：OpenClaw 工作流集成

创建 telegram-webapp.yml：

name: 演示按钮工作流
on:
  telegram:
    message: /start

jobs:
  present-dashboard:
    runs-on: openclaw/telegram
    steps:
      - name: 生成个性化 Web App 链接
        uses: openclaw/actions/generate-jwt@v1
        id: token
        with:
          payload: |
            user_id: ${{ event.user.id }}
            session: ${{ github.run_id }}
      
      - name: 发送演示按钮
        uses: openclaw/telegram/webapp@v1
        with:
          chat_id: ${{ event.chat.id }}
          title: "🚀 启动您的专属助手"
          description: "点击下方按钮进入交互界面"
          button_text: "立即体验"
          url: "https://app.example.com/launch?token=${{ steps.token.outputs.jwt }}"
          # 可选：指定返回数据的处理路由
          callback_route: "webapp_callback"

步骤 4：处理用户返回数据

// webapp_callback.js
export default async function handler(ctx) {
  const { formData, action, userId } = ctx.webappData;
  
  // 数据自动验证
  await ctx.validate(formData, userSchema);
  
  // 继续工作流
  await ctx.agent.run('process_order', { data: formData });
  
  // 向用户确认
  await ctx.telegram.sendMessage("✅ 已收到您的提交，正在处理...");
}

—

进阶配置技巧

动态按钮样式

根据对话上下文调整按钮外观：

const buttonConfig = {
  // 紧凑模式适合简单确认
  mode: ctx.data.complexity > 5 ? 'fullscreen' : 'compact',
  
  // 自定义主题色（适配 Telegram 深色模式）
  theme_params: {
    bg_color: '#1a1a1a',
    text_color: '#ffffff',
    button_color: '#2ea6ff'
  }
};

与 OpenClaw AI 能力结合

// 让 AI 决定何时展示 Web App
const decision = await ctx.llm.decide({
  prompt: "用户询问产品配置，是否需要展示配置器？",
  context: ctx.conversation.history,
  tools: ['present_webapp_if_complex']
});

if (decision.action === 'present_webapp') {
  await ctx.telegram.presentWebApp({
    url: generateConfiguratorUrl(ctx.entities.product)
  });
}

—

常见问题 FAQ

Q1: Web App 演示按钮与普通内联键盘有什么区别？

A: 普通内联键盘（InlineKeyboard）仅支持预设按钮的点击回调，而 Web App 按钮会打开一个完整的网页视图，支持复杂的用户交互，并能将数据传回 Bot。简单说：前者是”选择题”，后者是”开放题”。

Q2: 我的 Web App 需要满足什么技术要求？

A: 必须使用 HTTPS，且需要集成 Telegram 的 Web App JS SDK：

Q3: OpenClaw 是否支持 Web App 的自动关闭和数据回调？

A: 完全支持。OpenClaw 的 telegram/webapp 动作会自动监听 web_app_data 事件，并将解析后的 JSON 数据注入到工作流的 ctx.webappData 中，无需手动处理 Telegram 的原始更新。

Q4: 这个功能在群组和频道中可用吗？

A: 可以，但行为略有差异。在群组中，建议设置 selective: true 确保仅对触发用户展示；频道中则需要 Bot 具有管理员权限。OpenClaw 会自动检测聊天类型并应用最佳实践。

Q5: 如何调试 Web App 在 Telegram 中的显示问题？

A: 推荐流程：
1. 使用 Telegram 桌面版的 Web App 开发者模式（Settings → Advanced → Experimental Settings）
2. 在 OpenClaw 中启用详细日志：DEBUG=openclaw:telegram*
3. 使用 Bot API 调试工具 验证 URL 可访问性

—

总结与下一步

OpenClaw 对 Telegram Web App 演示按钮 的支持，标志着 AI Agent 与即时通讯平台的融合进入新阶段。关键收益：

• ✅ 零代码配置即可启用复杂交互界面
• ✅ 与 OpenClaw 工作流深度集成，数据自动流转
• ✅ 支持 JWT 安全验证，保障用户会话安全

建议下一步行动：
1. 查阅 OpenClaw Telegram 集成文档 获取完整配置参考
2. 在测试环境部署示例工作流，验证与现有 Bot 的兼容性
3. 关注 OpenClaw GitHub 仓库 获取后续更新（Issue #81356 相关讨论）

—

相关阅读

• 如何使用 OpenClaw 构建多平台 AI Agent
• Telegram Bot API 官方 Web App 指南
• OpenClaw 工作流最佳实践

—

参考来源

• OpenClaw GitHub Commit 5f8e1dd
• Telegram Bot API – Web Apps
• Telegram Web App 官方文档
• 阅读原文：OpenClaw 教学小站

——

OpenClaw 多语言命令菜单如何实现？Telegram Bot 本地化配置完整指南

一句话总结：OpenClaw 最新更新为 Telegram 插件带来了本地化命令菜单功能，让 AI Agent 能够根据用户语言自动切换命令描述，大幅提升全球用户体验。

如果你正在运营面向多国用户的 Telegram Bot，是否遇到过这样的困扰：命令菜单只显示英文，非英语用户难以理解功能含义？本文将详细介绍 OpenClaw 如何通过 descriptionLocalizations 机制解决这一问题，并提供完整的配置代码示例。

—

为什么需要本地化命令菜单？

Telegram 作为全球拥有超过 8 亿用户的即时通讯平台，覆盖 200 多个国家和地区。对于 OpenClaw 这样的 AI Agent 框架而言，支持多语言不仅是用户体验的加分项，更是产品国际化的基础要求。

传统的 Bot 开发中，开发者需要手动维护多套命令系统，或牺牲非英语用户的使用体验。OpenClaw 的新功能通过插件级别的本地化配置，让这一切变得简单高效。

—

核心机制：descriptionLocalizations

什么是 descriptionLocalizations？

descriptionLocalizations 是 OpenClaw 插件命令规范中的标准字段，用于定义命令描述的多语言版本。它遵循与 Discord 扩展相同的模式，确保跨平台体验的一致性。

数据结构示例

// plugin-command-spec.json
{
  "name": "analyze",
  "description": "Analyze document content",
  "descriptionLocalizations": {
    "zh-CN": "分析文档内容",
    "zh-TW": "分析文件內容",
    "ja": "ドキュメントを分析する",
    "ko": "문서 내용 분석",
    "es": "Analizar contenido del documento",
    "de": "Dokumentinhalt analysieren"
  },
  "options": [
    {
      "name": "file",
      "description": "File to analyze",
      "descriptionLocalizations": {
        "zh-CN": "要分析的文件"
      }
    }
  ]
}

—

Telegram 实现详解

setMyCommands API 的关键参数

Telegram Bot API 的 setMyCommands 方法支持通过 language_code 参数为特定语言注册用户命令菜单。OpenClaw 正是利用这一特性，实现了按语言代码注册独立命令集。

完整配置流程

#### 步骤 1：在插件中定义本地化描述

// plugins/my-plugin/commands/index.js
export const commands = [
  {
    name: 'start',
    description: 'Start the conversation',
    descriptionLocalizations: {
      'zh-CN': '开始对话',
      'zh-TW': '開始對話',
      'ja': '会話を開始',
      'ko': '대화 시작'
    }
  },
  {
    name: 'settings',
    description: 'Configure preferences',
    descriptionLocalizations: {
      'zh-CN': '配置偏好设置',
      'zh-TW': '設定偏好選項',
      'ja': '設定を構成',
      'ko': '환경 설정'
    }
  }
];

#### 步骤 2：OpenClaw 自动注册流程

OpenClaw 框架在初始化 Telegram 插件时，会自动执行以下操作：

// 框架内部逻辑示意
async function registerLocalizedCommands(botToken, commands) {
  // 提取所有支持的语言代码
  const locales = extractLocales(commands);
  
  // 为每种语言注册独立的命令菜单
  for (const locale of locales) {
    const localizedCommands = commands.map(cmd => ({
      command: cmd.name,
      description: cmd.descriptionLocalizations[locale] || cmd.description
    }));
    
    // 调用 Telegram API
    await fetch(https://api.telegram.org/bot${botToken}/setMyCommands, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        commands: localizedCommands,
        language_code: locale,  // 关键参数：指定语言代码
        scope: { type: 'default' }
      })
    });
  }
  
  // 同时注册默认（无语言代码）的命令作为回退
  await registerDefaultCommands(botToken, commands);
}

#### 步骤 3：验证配置是否生效

使用以下命令测试多语言菜单：

使用特定语言代码的 Telegram 客户端
或在 API 调用中指定 language_code

curl -X POST "https://api.telegram.org/bot/getMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"language_code":"zh-CN"}'

预期返回：

{
  "ok": true,
  "result": [
    {
      "command": "start",
      "description": "开始对话"
    },
    {
      "command": "settings",
      "description": "配置偏好设置"
    }
  ]
}

—

与 Discord 扩展的对比

| 特性 | Telegram 实现 | Discord 实现 |
|:—|:—|:—|
| API 方法 | setMyCommands | bulkOverwriteGlobalApplicationCommands |
| 语言参数 | language_code | name_localizations / description_localizations |
| 作用域 | 用户级别（自动匹配客户端语言） | 服务器级别 + 用户级别 |
| 更新频率 | 实时生效 | 有缓存延迟（约1小时） |
| OpenClaw 支持 | ✅ 新增 | ✅ 已有 |

OpenClaw 采用统一的设计模式，让开发者只需编写一次本地化配置，即可同时支持 Telegram 和 Discord 平台。

—

最佳实践建议

1. 语言代码规范

使用 IETF BCP 47 标准语言标签：

| 常用代码 | 语言 |
|:—|:—|
| zh-CN | 简体中文 |
| zh-TW | 繁体中文（台湾） |
| zh-HK | 繁体中文（香港） |
| ja | 日语 |
| ko | 韩语 |
| es | 西班牙语 |
| de | 德语 |
| fr | 法语 |

2. 回退策略

始终提供默认的 description 字段，当用户的语言不在支持列表中时，系统会自动回退到默认描述。

3. 动态更新

当插件命令变更时，OpenClaw 会自动重新注册所有语言的命令菜单，无需手动干预：

// openclaw.config.js
module.exports = {
  plugins: [
    {
      name: 'telegram',
      autoSyncCommands: true,  // 启用自动同步
      commandSyncInterval: 3600000  // 每小时检查更新（单位：毫秒）
    }
  ]
};

—

常见问题 FAQ

Q1: 用户如何切换命令菜单的语言？

A: 无需手动切换。Telegram 客户端会自动根据用户的应用界面语言向 Bot 请求对应语言的命令菜单。用户只需在 Telegram 设置中更改语言，命令菜单会自动更新。

Q2: 支持多少种语言？有数量限制吗？

A: Telegram 的 setMyCommands API 对每个 Bot 最多支持 100 组不同语言的命令菜单，每组最多 100 个命令。这对于绝大多数应用场景已经足够。

Q3: 如果某个语言缺少翻译，会怎样显示？

A: OpenClaw 会智能回退：优先显示该语言的本地化描述 → 若不存在，则显示默认 description → 若命令被标记为 hidden，则完全不显示。

Q4: 这个功能和 Telegram 的 BotFather 设置冲突吗？

A: 通过 API 设置的命令菜单会覆盖 BotFather 中的配置。建议完全通过 OpenClaw 管理命令，避免手动在 BotFather 中设置，防止配置被意外覆盖。

Q5: Discord 和 Telegram 的本地化配置可以共用吗？

A: 可以。OpenClaw 使用统一的 descriptionLocalizations 格式，但需注意两个平台的语言代码差异（如 Discord 使用 zh-CN，Telegram 也使用 zh-CN，但某些边缘情况可能不同）。建议在配置中进行平台特定映射。

—

总结与下一步

本文介绍了 OpenClaw 新增的 Telegram 本地化命令菜单功能，核心要点包括：

• 通过 descriptionLocalizations 实现多语言命令描述
• 利用 setMyCommands 的 language_code 参数按语言注册菜单
• 与 Discord 扩展共享相同的设计模式，降低开发成本

建议下一步行动：
1. 升级 OpenClaw 到最新版本，体验本地化功能
2. 查阅 OpenClaw Telegram 插件文档 获取详细配置说明
3. 参考 Telegram Bot API 官方文档 了解底层机制

—

相关阅读

• 如何为 OpenClaw 插件添加 Discord 多语言支持
• OpenClaw AI Agent 国际化最佳实践
• Telegram Bot 开发完整入门指南

—

参考来源

• OpenClaw GitHub Commit: feat(telegram): localized command menu descriptions
• Telegram Bot API – setMyCommands
• Discord API – Application Command Object
• IETF BCP 47 – Tags for Identifying Languages
• 阅读原文：OpenClaw 教学小站

——

OpenClaw 2026.5.12-beta.4 发布：12项关键修复与5大功能改进详解

一句话总结：本次更新重点修复了 Codex 运行时迁移问题，优化了 WhatsApp、Telegram 等消息平台的集成稳定性，并显著提升了 AI Agent 会话管理与错误处理体验。

如果你正在使用 OpenClaw 构建自托管 AI 自动化工作流，或计划从 OpenAI Codex 迁移到 OpenClaw 平台，这篇文章将帮你快速了解版本变化，避免踩坑。

—

一、Codex 迁移与运行时：核心修复

1.1 官方包运行时权限修复

此前使用官方安装的 @openclaw/codex 包时，迁移自 OpenAI/Codex beta 的项目会遇到 MODULE_NOT_FOUND 错误。本次更新允许该包访问其私有的 task-runtime SDK helper，彻底解决了模块加载失败问题。

更新后，迁移项目无需额外配置即可正常运行
openclaw codex migrate --from openai --to openclaw

1.2 交互式迁移界面优化

迁移向导的键盘交互得到改进：Enter 键现在会先激活高亮复选框，再进入下一步。这意味着 Skip for now 选项和批量选择功能在预设选中状态下也能正常工作。

1.3 认证配置灵活性提升

当 OpenAI 认证信息存储在 Agent 的 auth-profile 而非环境变量时，image_generate 等依赖认证的工具现在可以正常使用。这支持更安全的密钥管理方式：

agent-profile.yaml
auth:
  openai:
    type: profile-store  # 替代 environment
    profile_id: my-openai-key

—

二、消息平台集成：WhatsApp 与 Telegram 稳定性增强

2.1 WhatsApp (Baileys) 安装修复

pnpm 11 用户现在可以顺利完成源码安装和本地检查。修复允许 Baileys 锁定的 libsignal git 子依赖通过验证。

pnpm 11 环境下完整安装命令
pnpm install @openclaw/whatsapp-baileys
pnpm build

2.2 消息处理可靠性提升

• 去抖动消息处理：WhatsApp 插件现在会在关闭 socket 前完成所有待处理的入站消息处理，避免消息丢失
• HTML 格式保留：Telegram 回复中的支持 HTML 标签（如 、）将正确渲染，不再转义为纯文本

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

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

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  # 优先生效
  }'

拉取最新镜像
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

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

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

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

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