月度归档：2026年05月

OpenClaw Agent Cron 回退机制优化：5 个关键改进解析

——

OpenClaw Agent Cron 回退机制优化：5 个关键改进解析

OpenClaw 最新提交的 PR #82328 针对 AI Agent 的定时任务（Cron）子代理回退选择机制进行了深度重构。这项更新解决了多模型调度场景下的回退策略不一致问题，让自动化工作流更加稳定可靠。本文将拆解 5 个核心改进点，帮助开发者快速理解并应用到实际项目中。

—

为什么需要优化 Cron 回退机制？

在 OpenClaw 的 AI Agent 架构中，Subagent（子代理）负责执行特定的定时任务。当主模型不可用时，系统需要自动回退（Fallback）到备用模型。然而，之前的实现存在以下痛点：

多个子代理重复执行相同的模型选择逻辑，造成资源浪费
回退策略在不同模块间表现不一致
用户自定义的回退配置可能被意外覆盖

本次重构通过”共享模型选择”机制，将这些问题一并解决。

—

5 项核心改进详解

1. 修复：正确执行子代理 Cron 回退配置

问题：早期版本中，Subagent 的 Cron 任务未能正确读取用户配置的回退模型列表。

改进：现在系统会严格遵循 subagent.fallback_models 配置，按优先级顺序尝试可用模型。

配置示例：subagent-config.yaml
subagent:
  name: "data-processor"
  cron: "0 /6   "  # 每6小时执行
  primary_model: "gpt-4"
  fallback_models:      # ← 现在会被正确执行
    - "gpt-3.5-turbo"
    - "claude-3-haiku"

2. 重构：共享 Cron 子代理模型选择逻辑

核心优化：将原本分散在各处的模型选择代码提取为可复用模块。

重构后的共享选择器（示意）
from openclaw.agents import SharedModelSelector

selector = SharedModelSelector(
    agent_type="cron_subagent",
    selection_policy="round_robin_with_fallback"
)

所有 Cron Subagent 共用同一选择器实例
selected_model = selector.pick_available(
    primary="gpt-4",
    fallbacks=["gpt-3.5-turbo", "claude-3-haiku"]
)

收益：

代码量减少约 30%
模型选择行为全局一致
便于集中监控和调优

3. 测试对齐：统一回退策略预期

测试用例已更新，确保所有场景下的回退行为符合预期：

| 场景 | 预期行为 | 验证状态 |
|:—|:—|:—|
| 主模型正常 | 直接使用主模型 | ✅ 通过 |
| 主模型限流 | 触发第1回退 | ✅ 通过 |
| 全部模型不可用 | 进入队列等待 + 告警 | ✅ 通过 |
| 用户强制指定回退 | 跳过主模型，直接使用指定模型 | ✅ 通过 |

4. 修复：保留已选模型的回退链

关键修复：当系统成功回退到某个备用模型后，该模型的专属回退配置会被保留，而非重置为默认链。

修复前（问题代码）
selected = fallback_chain[0]  # 选中了 gpt-3.5-turbo
但后续如果该模型也失败，会错误地回到默认链

修复后
selected = fallback_chain[0]  # gpt-3.5-turbo
继承该模型的自定义回退配置：gpt-3.5-turbo → local-llm → queue

5. 修复：保护仅回退模式的覆盖配置

针对特殊场景——用户明确只想使用回退模型（如成本优化场景）：

仅回退模式配置
subagent:
  fallback_only: true        # ← 新增保护标记
  allowed_models:
    - "gpt-3.5-turbo"        # 只允许使用这些模型
    - "local-llama-7b"

系统现在会识别 fallback_only 标记，防止被动态策略意外覆盖。

—

升级指南

检查当前版本

查看 OpenClaw 版本
openclaw --version

确认包含本更新（v2.4.0+）
openclaw changelog | grep "82328"

配置迁移建议

若你已有 Cron Subagent 配置，建议按以下步骤验证：

1. 导出当前配置
openclaw config export --agent-type=cron_subagent > backup.yaml

2. 验证回退链完整性
openclaw doctor --check=fallback-chain

3. 试运行检测（dry-run）
openclaw agent test --config=backup.yaml --dry-run

—

常见问题（FAQ）

Q1: 什么是 Subagent 的 Cron 回退机制？

A: 当 OpenClaw 的定时任务子代理（Cron Subagent）执行时，如果配置的主 AI 模型 因限流、故障或成本原因不可用，系统会自动按预设顺序尝试备用模型，这个过程称为”回退”（Fallback）。

Q2: 本次更新会影响现有定时任务的执行吗？

A: 不会。本次重构为向后兼容更新，现有配置无需修改即可运行。但建议运行 openclaw doctor 检查，以确认回退链配置符合预期。

Q3: 如何查看 Subagent 实际使用的模型？

A: 启用调试日志：

openclaw agent run --subagent=data-processor --log-level=debug

查找包含 [model-selection] 的日志条目，可看到完整的选择决策过程。

Q4: “共享模型选择器”会带来性能提升吗？

A: 主要提升在一致性和可维护性。对于高频定时任务场景（每分钟执行多次），共享选择器可减少重复的模型健康检查调用，降低约 15-20% 的 API 开销。

Q5: 能否为不同 Subagent 设置独立的回退策略？

A: 可以。虽然底层选择器共享，但每个 Subagent 的配置独立生效。在 subagent-config.yaml 中通过 selection_policy 字段指定：

subagent:
  selection_policy: "cost_optimized"  # 或 "latency_optimized", "quality_first"

—

总结

PR #82328 的 5 项改进让 OpenClaw 的 AI Agent 定时任务调度更加健壮：

下一步行动：
1. 升级至 OpenClaw v2.4.0+
2. 运行 openclaw doctor --check=fallback-chain 验证配置
3. 阅读 OpenClaw 文档中的”高级调度策略”章节

—

参考来源

OpenClaw 2026.5.14-beta.2 发布：10大新功能解析与升级指南

——

OpenClaw 2026.5.14-beta.2 发布：10大新功能解析与升级指南

OpenClaw 2026.5.14-beta.2 版本带来了十余项关键更新，从 Canvas 懒加载 启动优化到 WhatsApp 状态反应 的完整生命周期支持，再到 Agent 级配置覆盖 的精细化控制。本文将逐条解析这些变化，并提供可直接使用的升级命令与配置示例。

—

为什么这次更新值得关注？

本次 beta 版本聚焦三大方向：启动性能优化、多平台体验统一、运维可观测性增强。无论你是通过 Docker 部署的运维工程师，还是开发自定义插件的技术用户，都能从中获得实质性的效率提升。

—

核心更新详解

1. Canvas 懒加载：Gateway 启动速度提升

Canvas 模块（HTTP 主机、媒体解析器、CLI 实现、工具运行时）现已改为按需加载。这意味着 Gateway 启动时不再预加载 Canvas 实现，首次调用时才初始化。

验证启动时间优化（对比前后版本）
docker logs openclaw-gateway 2>&1 | grep -E "(startup|Canvas|lazy)"

适用场景：频繁重启 Gateway 的开发环境、资源受限的边缘部署。

—

2. Agent 级配置覆盖：精细化上下文控制

现在可以为单个 Agent 覆盖以下配置，未指定时自动继承 agents.defaults：

agents.yaml 示例
agents:
  defaults:
    bootstrapMaxChars: 4000
    bootstrapTotalMaxChars: 8000
  
  my-custom-agent:
    # 覆盖默认值
    bootstrapMaxChars: 6000
    contextInjection: "selective"

修复问题：#69966

—

3. WhatsApp 状态反应：完整生命周期支持

WhatsApp 频道 现已集成 StatusReactionController，消息状态流转与 Telegram、Discord 保持一致：

queued → 🧠 thinking → 🛠️ tool → ✅ done / ❌ error

新增 emoji 分类与语义：

| Emoji | 含义 | 触发场景 |
|——-|——|———|
| 🧠 | thinking | 推理中 |
| 🛠️ | tool | 工具调用 |
| 💻 | coding | 代码生成 |
| 🌐 | web | 网页浏览 |
| ⏳ | stallSoft | 软阻塞 |
| ⚠️ | stallHard | 硬阻塞 |
| ✅ | done | 完成 |
| ❌ | error | 错误 |
| 🗜️ | compacting | 上下文压缩 |

新增 deploy/build/concierge 分类，支持工具令牌路由。

修复问题：#59077、#80612

—

4. 插件钩子增强：上下文预算透明化

llm_output 和 model_call_* 钩子事件现在暴露：

resolved effective contextTokenBudget：实际生效的上下文令牌预算
source/reference 元数据：预算来源追踪

// 插件示例：监控上下文健康
onLlmOutput: (event) => {
  const { contextTokenBudget, source } = event.context;
  if (contextTokenBudget.remaining < 1000) {
    alert(Agent ${event.agentId} 上下文即将耗尽，来源: ${source});
  }
}

修复问题：#64327

—

5. Gateway 启动追踪：Owner 级可观测性

新增 owner-level startup trace，覆盖：

认证流程
插件加载
查找计数（lookup counts）
插件 sidecar 服务

查看启动追踪日志
docker logs openclaw-gateway 2>&1 | grep -E "startup_trace|owner"

关联 PR：#81738

—

6. 依赖优化：代理与安全清理

根环境 Node 代理 统一路由至 @openclaw/proxyline
移除 proxy-agent、https-proxy-agent、minimatch 三个根依赖

升级后清理：

清理旧依赖缓存
pnpm store prune
rm -rf node_modules/.pnpm/proxy-agent*

—

7. Codex 应用服务器重构

—

8. 维护者工具升级

新增 codex-review 技能：

本地脏工作区审查
pnpm skill:run codex-review --dirty

PR 分支审查（循环至无问题）
pnpm skill:run codex-review --pr 123 --base main

避免不支持的行内提示
pnpm skill:run codex-review --base HEAD~1

CI 强化：PR 若添加包补丁文件或 pnpm patched 依赖，CI 将失败，强制使用上游升级工作流。

—

9. 控制面板体验优化

浏览器本地字体大小设置：

路径：Appearance → Quick Settings → Text size
特性：缩放聊天和密集 UI 文本，同时保持输入框在移动端 Safari 聚焦缩放阈值之上

修复问题：#8547

i18n 基线报告：

生成硬编码文案聚焦区域报告
pnpm ui:i18n:report

关联 PR：#81320

—

10. DeepSeek V4 Flash 文档与 Docker 验证

新增 ds4 provider 专属页面，包含：

本地 DeepSeek V4 Flash 配置
按需启动指南
上下文大小设置
实时验证步骤

Docker 用户旅程验证（发布验证新增）：

验证完整 onboarding 流程
docker run --rm -it openclaw/openclaw:v2026.5.14-beta.2 \
  /opt/openclaw/scripts/verify-user-journey.sh

—

升级指南

Docker 部署

拉取最新镜像
docker pull openclaw/openclaw:v2026.5.14-beta.2

备份当前配置
cp -r /opt/openclaw/config /opt/openclaw/config.backup.$(date +%Y%m%d)

更新并重启
docker compose down
docker compose up -d

源码构建

更新代码
git fetch origin
git checkout v2026.5.14-beta.2

清理并安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

验证代理依赖清理
pnpm list proxy-agent https-proxy-agent minimatch 2>/dev/null || echo "✓ 旧代理依赖已移除"

—

常见问题 FAQ

Q1: Canvas 懒加载会影响首次调用性能吗？

A: 会有轻微的首次调用延迟（通常 <500ms），但换取的是 Gateway 启动时间显著缩短。对于长运行实例，这是净收益。如需预热，可在启动后发送一条测试消息触发初始化。

Q2: 如何为特定 Agent 设置更大的上下文窗口？

A: 在 agents.yaml 中针对该 Agent 覆盖 bootstrapMaxChars 和 bootstrapTotalMaxChars，参考上文第2节的配置示例。注意总字符数受限于底层 LLM 的上下文上限。

Q3: WhatsApp 状态反应需要额外配置吗？

A: 无需配置，更新后自动生效。如需自定义 emoji 映射，可通过插件钩子拦截 status_reaction 事件进行修改。

Q4: 升级后 Codex 相关功能异常怎么办？

A: 检查模型引用是否已从 codex-cli/ 迁移至 openai/。如有自定义配置，参考 OpenClaw 文档的迁移指南。

Q5: 如何验证 Docker 部署成功？

A: 执行以下命令检查关键指标：

docker exec openclaw-gateway /opt/openclaw/scripts/health-check.sh
预期输出包含: startup_trace, lazy_load, status_reaction

—

总结与下一步

OpenClaw 2026.5.14-beta.2 通过 懒加载架构、精细化配置 和 全平台体验统一，进一步巩固了其作为 AI Agent 基础设施的地位。建议用户：

1. 优先升级：测试环境的 Canvas 懒加载收益
2. 配置审查：利用新的 Agent 覆盖能力优化上下文策略
3. 监控增强：启用 Gateway 启动追踪，建立基线指标

—

参考来源

OpenClaw 新功能：5 步实现 AI Agent 历史图片自动关联

——

OpenClaw 新功能：5 步实现 AI Agent 历史图片自动关联

一句话总结：OpenClaw 最新提交让 AI Agent 能够自动”记住”对话中的历史图片，彻底解决多轮对话中视觉上下文丢失的痛点。

在多模态 AI 应用中，用户经常遇到这样的困扰：第一轮发送了一张产品截图询问问题，第二轮追问”这个按钮怎么处理”时，AI 却”忘记”了之前的图片。OpenClaw 最新功能更新（#82068）通过自动关联历史入站图片到 Agent 对话轮次，让 AI Agent 真正具备持续的视觉记忆能力。

—

为什么需要历史图片关联？

传统的文本对话系统只保留文字记录，但现代 AI 应用越来越依赖视觉输入。当用户连续发送多张图片或图文混合对话时，AI 需要理解：

当前问题指向哪张历史图片？
图片之间的时序关系是什么？
如何避免无关图片干扰当前判断？

OpenClaw 的这次更新正是为了解决这些核心问题。

—

核心功能解析

1. 智能历史媒体绑定

系统现在会自动识别并绑定最近的入站图片到 Agent 对话轮次：

// 配置历史媒体关联参数
const agentConfig = {
  // 启用历史图片关联
  attachRecentInboundHistory: true,
  
  // 限制历史媒体数量，防止上下文过长
  historyMediaCap: 5,
  
  // 是否包含贴纸类媒体
  preserveStickerHistory: true
};

关键设计：通过 historyMediaCap 参数严格限制历史媒体数量，避免上下文窗口被图片占满。

2. 运行时优化：避免不必要的媒体处理

更新引入了智能判断机制，纯文本对话轮次不会触发媒体运行时：

// 内部优化逻辑示意
function shouldAttachMedia(turn) {
  // 纯文本轮次跳过媒体处理
  if (turn.type === 'text-only') {
    return false;
  }
  
  // 检查当前媒体是否为非图片类型
  if (turn.currentMedia && !turn.currentMedia.isImage) {
    // 跳过历史图片关联，避免混淆
    return false;
  }
  
  return true;
}

这一优化显著降低了 API 调用成本和处理延迟。

3. 媒体类型兼容与边界处理

—

5 步快速配置指南

步骤 1：升级 OpenClaw 版本

拉取最新代码
git pull origin main

或指定包含该功能的版本
git checkout 8859e89

步骤 2：更新 Agent 配置

在 agent.config.js 或对应配置文件中添加：

module.exports = {
  // ... 其他配置
  
  // 启用历史图片关联（新增）
  historyMedia: {
    enabled: true,
    maxItems: 5,           // 最多保留 5 张历史图片
    includeStickers: true, // 包含贴纸
    visibilityGated: true  // 权限控制
  }
};

步骤 3：配置媒体下载边界

防止恶意或意外的大量媒体下载：

historyMedia: {
  // ... 其他配置
  
  // 下载限制（字节）
  downloadBounds: {
    maxFileSize: 10  1024  1024,  // 10MB
    maxTotalSize: 50  1024  1024  // 50MB 总计
  }
}

步骤 4：测试多轮对话

验证历史图片是否正确关联：

[用户] 发送图片 A（产品截图）
[AI]  识别并回复...

[用户] 发送图片 B（错误提示）
[AI]  识别并回复...

[用户] 纯文字："第一张图的问题怎么解决？"
[AI]  ✓ 正确引用图片 A 进行回答（新功能！）

步骤 5：监控与调优

查看历史媒体关联日志
openclaw logs --filter="history_media"

检查媒体运行时性能
openclaw metrics --component="agent.media_runtime"

—

开发者注意事项

并发安全处理

该功能修复了多个竞态条件（race condition），确保在高并发场景下历史媒体记录的一致性：

// 内部使用原子操作记录待处理媒体
async function recordPendingHistoryMedia(media) {
  // 使用锁机制避免并发冲突
  await lock.acquire('history_media', async () => {
    const pending = await getPendingMedia();
    pending.push(media);
    await setPendingMedia(pending);
  });
}

Slack 集成适配

如果使用 Slack 作为接入渠道，注意 mocked 媒体获取的配置：

// 测试环境配置
slack: {
  mediaFetch: {
    // 测试时使用 mock，生产环境关闭
    useMock: process.env.NODE_ENV === 'test',
    respectMockedFetches: true
  }
}

—

常见问题 FAQ

Q1: 历史图片关联会显著增加 API 成本吗？

不会。系统通过三项优化控制成本：(1) 纯文本轮次跳过媒体处理；(2) 严格的历史媒体数量上限；(3) 智能判断当前媒体类型，避免不必要的关联。

Q2: 如何调整历史图片的记忆时长？

目前通过 maxItems 控制数量而非时间。如需按时间过滤，可在业务层实现：

// 自定义过滤逻辑
historyMedia: {
  filter: (media) => {
    const age = Date.now() - media.timestamp;
    return age < 5  60  1000; // 5 分钟内
  }
}

Q3: 贴纸和普通图片的处理有什么区别？

贴纸默认受相同 maxItems 限制，但可通过 includeStickers: false 完全排除。贴纸通常尺寸较小，对上下文影响有限。

Q4: 升级后现有对话会受到影响吗？

不会。该功能仅作用于新产生的对话轮次，历史对话保持原有行为。如需迁移，需手动重建对话上下文。

Q5: 如何调试历史图片关联是否正常工作？

启用详细日志：

DEBUG=openclaw:history-media openclaw start

观察日志中的 attaching_history_media 和 skipping_media_runtime 事件。

—

总结与下一步

OpenClaw 的这次更新让 AI Agent 具备了真正的多轮视觉记忆能力，核心改进包括：

✅ 自动关联历史入站图片
✅ 智能运行时优化降低成本
✅ 完善的边界处理和并发安全
✅ 灵活的贴纸和媒体类型控制

建议下一步行动：
1. 在测试环境验证功能行为
2. 根据业务场景调整 maxItems 参数
3. 监控首周的生产指标变化

—

参考来源

OpenClaw 小米模型集成：4个核心钩子函数详解与实战配置

——

OpenClaw 小米模型集成：4个核心钩子函数详解与实战配置

OpenClaw 最新版本为小米 AI 模型生态引入了四项关键钩子函数，彻底解决流式输出控制、思考模式动态切换、模型版本识别和对话重放等核心场景的配置难题。本文将逐层拆解每个钩子的设计原理，并提供可直接落地的配置代码。

—

为什么需要这 4 个钩子函数？

小米 AI 模型家族（包括 MiLM、MiMo 等系列）在 API 行为上存在显著差异：早期模型不支持流式输出，思考模式（Thinking Mode）的触发参数因版本而异，且部分场景需要完整重放对话历史。OpenClaw 通过注册式钩子架构，让开发者无需修改核心代码即可适配这些差异。

—

钩子一：wrapStreamFn — 流式输出包装器

功能定位

wrapStreamFn 负责将非标准流式响应转换为 OpenClaw 统一的流式格式，解决小米部分模型 SSE 数据格式不兼容的问题。

配置示例

// openclaw.config.js
module.exports = {
  providers: {
    xiaomi: {
      model: 'milm-pro',
      // 注册流式包装函数
      wrapStreamFn: (rawStream, ctx) => {
        // 小米模型返回的 data: 前缀可能包含额外空格
        const normalizedStream = rawStream.pipeThrough(
          new TransformStream({
            transform(chunk, controller) {
              // 标准化 SSE 格式
              const cleanChunk = chunk
                .replace(/^data:\s*/gm, 'data: ')
                .replace(/\n\n/g, '\n');
              controller.enqueue(cleanChunk);
            }
          })
        );
        return normalizedStream;
      }
    }
  }
};

适用场景

—

钩子二：resolveThinkingProfile — 思考模式动态解析

功能定位

resolveThinkingProfile 根据对话上下文动态决定是否启用模型的”深度思考”模式，并自动选择正确的参数名（enable_thinking vs thinking_mode）。

配置示例

resolveThinkingProfile: (messages, modelRef) => {
  // 检测是否需要深度推理
  const needsDeepThinking = messages.some(m => 
    /分析|解释|为什么|对比|评估/i.test(m.content)
  );
  
  // 根据模型版本返回正确的参数
  const isModern = modelRef.version >= '2.0';
  
  return {
    enabled: needsDeepThinking,
    // 现代模型使用 thinking_mode，旧版用 enable_thinking
    paramKey: isModern ? 'thinking_mode' : 'enable_thinking',
    // 思考深度等级：1-5
    depth: needsDeepThinking ? 3 : 1
  };
}

关键设计

向后兼容：自动识别模型版本，避免手动维护参数映射表
上下文感知：基于用户问题类型智能触发，减少 Token 浪费
粒度控制：支持 5 级思考深度，平衡响应质量与延迟

—

钩子三：isModernModelRef — 模型版本自动识别

功能定位

isModernModelRef 为 resolveThinkingProfile 和其他钩子提供统一的模型版本判断能力，解决小米模型命名混乱导致的配置错误。

版本映射规则

isModernModelRef: (modelId) => {
  const modernPatterns = [
    /^milm-pro-2/,      // MilM Pro 2.x 系列
    /^mimo-large-v2/,   // MiMo Large V2+
    /^xiaomi-mt-/       // 2024 年后发布的 MT 系列
  ];
  
  const legacyPatterns = [
    /^milm-standard/,   // 标准版无版本号
    /^mimo-base-v1/,    // 初代 MiMo
    /^mi-nlp-/          // 早期 NLP 模型
  ];
  
  // 优先匹配现代模式，默认保守回退到旧版
  if (modernPatterns.some(p => p.test(modelId))) return true;
  if (legacyPatterns.some(p => p.test(modelId))) return false;
  
  // 未知模型：检查 API 版本元数据
  return modelId.includes('2024') || modelId.includes('v2');
}

实战技巧

快速验证模型识别结果
npx openclaw doctor --provider xiaomi --model milm-pro-2.1
输出: ✓ 识别为现代模型 (API v2.3, 支持 thinking_mode)

—

钩子四：replay hooks — 对话历史重放

功能定位

replay hooks 处理需要完整重建对话上下文的场景，如多轮工具调用后的状态恢复、长对话的断点续传等。

完整配置

replay: {
  // 序列化当前对话状态
  capture: (session) => ({
    messages: session.messages,
    toolResults: session.toolCalls.map(t => t.result),
    thinkingProfile: session.thinkingProfile,
    timestamp: Date.now()
  }),
  
  // 重建对话上下文
  restore: (snapshot, modelRef) => {
    // 小米模型有 4K 上下文限制，需要截断
    const maxTokens = isModernModelRef(modelRef.id) ? 4096 : 2048;
    const truncated = truncateMessages(snapshot.messages, maxTokens);
    
    return {
      messages: truncated,
      // 重放时保持原思考配置
      thinkingProfile: snapshot.thinkingProfile,
      // 标记为重放会话，跳过欢迎语
      metadata: { isReplay: true }
    };
  },
  
  // 重放后的清理
  onComplete: (session) => {
    console.log([Replay] 会话恢复完成，共 ${session.messages.length} 轮对话);
  }
}

—

完整集成配置

将四个钩子组合为生产级配置：

// xiaomi.config.js
const { isModernModelRef } = require('@openclaw/xiaomi-utils');

module.exports = {
  provider: 'xiaomi',
  apiKey: process.env.XIAOMI_API_KEY,
  
  hooks: {
    wrapStreamFn: require('./hooks/wrapStream'),
    resolveThinkingProfile: require('./hooks/thinkingResolver'),
    isModernModelRef,
    replay: require('./hooks/replayManager')
  },
  
  // 模型特定覆盖
  models: {
    'milm-pro-2.1': {
      maxTokens: 4096,
      defaultThinkingDepth: 3
    },
    'mimo-base-v1': {
      maxTokens: 2048,
      disableStreaming: true  // 旧版不支持流式
    }
  }
};

启动验证：

export XIAOMI_API_KEY=sk-xxx
npx openclaw start --config ./xiaomi.config.js

—

常见问题 FAQ

Q1: 如何判断我的小米模型是否支持流式输出？

运行诊断命令查看模型元数据：

npx openclaw provider:inspect xiaomi --model <你的模型ID>

若输出包含 streaming: true 且 protocol: sse，则原生支持。若显示 streaming: wrapRequired，则必须配置 wrapStreamFn。

Q2: 思考模式会增加多少 Token 消耗？

根据 OpenClaw 实测数据，启用深度思考后：

Token 消耗增加 40%-120%（取决于 depth 等级）
首 Token 延迟增加 200-800ms
建议仅在分析类、推理类任务中启用，日常对话保持关闭

Q3: 四个钩子是否必须全部配置？

生产环境建议至少配置 isModernModelRef 以确保参数正确性。

Q4: 能否为不同模型设置不同的钩子实现？

可以。利用 OpenClaw 的条件钩子注册：

hooks: {
  resolveThinkingProfile: (messages, modelRef) => {
    // 为代码模型启用最高思考深度
    if (modelRef.id.includes('code')) {
      return { enabled: true, depth: 5 };
    }
    // 其他模型使用默认逻辑
    return defaultThinkingResolver(messages, modelRef);
  }
}

Q5: 升级后现有配置会失效吗？

OpenClaw 承诺钩子 API 的向后兼容性：

v1.x 版本的钩子函数在 v2.x 中继续有效
新增参数以可选方式提供，不影响现有配置
破坏性变更将提前 2 个 minor 版本发布迁移指南

—

总结与下一步

本文详解了 OpenClaw 为小米 AI 模型引入的四大核心钩子：wrapStreamFn 解决流式格式兼容、resolveThinkingProfile 实现思考模式智能切换、isModernModelRef 自动识别模型版本、replay hooks 支持对话状态重放。通过组合这些钩子，开发者可以构建适配小米全系列模型的健壮 AI Agent。

建议下一步行动：
1. 运行 npx openclaw doctor 检测当前小米模型配置状态
2. 参考 OpenClaw 小米集成文档获取完整参数手册
3. 在测试环境验证思考模式对业务场景的实际效果

—

参考来源

GitHub Commit: f976454 — 本次功能更新的源代码变更
OpenClaw 官方文档 — 钩子函数完整 API 参考
小米 AI 开放平台 — 模型规格与限制说明
阅读原文：OpenClaw 教学小站

OpenClaw Gateway 新功能：如何正确转发响应格式参数？

——

OpenClaw Gateway 新功能：如何正确转发响应格式参数？

一句话总结：OpenClaw 最新版本支持将下游大模型的 响应格式参数（response format params） 完整转发至上游服务，彻底解决 AI Agent 在多模型网关场景下的 JSON Schema 配置丢失问题。

在使用 OpenClaw 作为 AI 网关统一调度多个大模型服务时，你是否遇到过这样的困扰：明明在请求中指定了 response_format: { type: "json_object" }，但返回的结果却是普通文本格式？这通常是因为网关层未能正确透传格式控制参数导致的。本文将详细解读这一关键更新的技术细节与实战配置方法。

—

为什么响应格式参数转发如此重要？

AI Agent 开发的痛点场景

现代 AI Agent 应用普遍依赖结构化输出（Structured Output）来实现可靠的工具调用和数据处理。以 OpenAI GPT-4、Claude 3、Gemini 为代表的模型均支持通过 response_format 参数强制返回 JSON 格式：

// 典型的结构化输出请求
const response = await openai.chat.completions.create({
  model: "gpt-4-turbo-preview",
  messages: [{ role: "user", content: "生成用户资料，包含 name 和 age" }],
  response_format: { 
    type: "json_object"  // 强制 JSON 输出
  }
});

然而，当企业采用 OpenClaw Gateway 作为统一入口时，早期版本存在参数截断问题——网关仅转发基础请求体，却丢弃了 response_format、seed、tools 等扩展参数，导致：

本次更新的核心价值

OpenClaw 在 commit 8503418 中实现了 forward response format params 功能，确保所有与响应格式相关的参数完整无损地传递至目标模型服务。

—

技术实现详解

支持转发的参数清单

更新后的 OpenClaw Gateway 现已完整支持以下参数的透传：

配置示例：启用完整参数转发

#### 场景一：单模型路由配置

openclaw-gateway.yaml
routes:
  - name: "gpt4-structured"
    model: "gpt-4-turbo-preview"
    upstream: "https://api.openai.com/v1"
    # 关键配置：启用参数透传
    forward_params:
      - response_format
      - seed
      - tools
      - tool_choice
    headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

#### 场景二：多模型负载均衡

routes:
  - name: "smart-router"
    strategy: "weighted_round_robin"
    targets:
      - model: "gpt-4-turbo-preview"
        weight: 60
        upstream: "https://api.openai.com/v1"
      - model: "claude-3-opus-20240229"
        weight: 40
        upstream: "https://api.anthropic.com/v1"
    # 统一启用格式参数转发
    forward_params: ["response_format", "seed", "tools"]
    # 自动适配不同模型的参数差异
    param_mapping:
      claude-3-opus-20240229:
        response_format: "json_mode"  # Claude 使用不同字段名

客户端调用验证

配置完成后，可通过以下方式验证参数透传是否生效：

测试 JSON 模式强制输出
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENCLAW_API_KEY" \
  -d '{
    "model": "gpt4-structured",
    "messages": [{"role": "user", "content": "List 3 planets"}],
    "response_format": {"type": "json_object"},
    "seed": 42
  }' | jq .

预期返回包含 system_fingerprint 字段（表明 seed 生效），且内容格式为合法 JSON。

—

进阶应用：JSON Schema 严格模式

对于需要精确控制输出结构的场景，可结合 JSON Schema 实现：

// 使用 zod 生成 schema 并透传
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const UserSchema = z.object({
  name: z.string().min(1),
  age: z.number().int().min(0).max(150),
  email: z.string().email().optional()
});

const response = await fetch("http://openclaw-gateway/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "gpt-4-turbo-preview",
    messages: [{
      role: "system",
      content: "You are a helpful assistant. Respond only with valid JSON."
    }, {
      role: "user", 
      content: "Create a user profile for Alice, 28 years old"
    }],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "user_profile",
        strict: true,
        schema: zodToJsonSchema(UserSchema)
      }
    }
  })
});

> 注意：json_schema 模式需要上游模型原生支持，OpenClaw Gateway 会透传该参数，但不会验证模型兼容性。建议通过 OpenClaw 文档查询各模型的能力矩阵。

—

常见问题解答（FAQ）

Q1: 启用参数转发会影响网关性能吗？

不会。参数透传属于零拷贝操作，OpenClaw Gateway 仅解析请求头进行路由决策，请求体以流式方式直接转发，额外开销可忽略不计。实测显示，开启完整参数转发后 P99 延迟增加 < 2ms。

Q2: 如果上游模型不支持某些参数会怎样？

OpenClaw 采用”透传优先”策略：网关不拦截未知参数，直接转发至上游。若目标模型返回 400 错误，建议检查：

该模型是否支持对应参数（如 Claude 的 json_mode 与 OpenAI 的 json_object 差异）
是否在 param_mapping 中配置了正确的字段映射

Q3: 如何调试参数是否成功转发？

启用调试日志级别，查看完整请求链路：

启动网关时设置日志级别
LOG_LEVEL=debug openclaw-gateway --config ./gateway.yaml

关键日志标识
[gateway] forward: response_format={type: json_object}
[upstream] received: 200 OK with content-type: application/json

Q4: 该功能是否兼容 OpenAI 兼容接口？

完全兼容。OpenClaw Gateway 的 /v1/chat/completions 端点遵循 OpenAI API 规范，现有客户端代码无需修改即可接入，仅需将 baseURL 指向网关地址。

Q5: 企业级部署有哪些最佳实践？

1. 参数白名单：生产环境建议显式配置 forward_params，避免意外透传敏感字段
2. Schema 校验：在网关层前置校验 json_schema 合法性，减少无效请求
3. 熔断降级：对不支持结构化输出的模型配置 fallback 路由

生产环境推荐配置
routes:
  - name: "production-llm"
    forward_params: ["response_format", "seed"]  # 显式白名单
    validation:
      json_schema_max_depth: 10  # 防止递归过深
    fallback:
      on_unsupported_format: "text_mode"  # 降级策略

—

总结与下一步

OpenClaw 的 forward response format params 更新标志着 AI 网关向”透明代理”模式的重要演进。通过完整保留下游模型的格式控制能力，开发者可以：

✅ 统一网关入口，同时保留各模型的原生特性
✅ 构建可靠的 AI Agent 工作流，确保结构化输出稳定性
✅ 简化多模型切换的适配成本

立即行动：
1. 升级至最新版本：git pull origin main 或查看 Release 页面
2. 阅读 OpenClaw 文档获取完整配置指南
3. 加入社区讨论：GitHub Discussions

—

参考来源

OpenClaw 新功能：3 步实现 per-agent Bootstrap 配置精细化控制

——

OpenClaw 新功能：3 步实现 per-agent Bootstrap 配置精细化控制

OpenClaw 最新版本引入了 per-agent bootstrap profiles 功能，彻底解决了多 Agent 场景下配置粒度不足的问题。现在，你可以为每个 AI Agent 单独设置上下文注入规则、字符限制等关键参数，而不再受限于全局默认配置。

—

为什么需要 per-agent Bootstrap Profiles？

在之前的版本中，OpenClaw 的 bootstrap 配置只能通过 agents.defaults 全局设置。这意味着：

所有 Agent 共享相同的上下文注入策略
无法针对特定 Agent 优化字符限制
复杂多 Agent 系统难以精细化管理

新功能允许你在单个 Agent 层级覆盖以下参数：

—

快速上手：3 步配置指南

第 1 步：定义 Agent 专属 Profile

在你的 OpenClaw 配置文件中，为特定 Agent 添加 bootstrapProfile 字段：

.claw/agents.yaml
agents:
  - name: "code-reviewer"
    description: "代码审查专家"
    # 专属 bootstrap 配置
    bootstrapProfile:
      contextInjection: "compact"      # 紧凑模式，节省 token
      bootstrapMaxChars: 8000          # 单条上限 8000 字符
      bootstrapTotalMaxChars: 32000    # 总计上限 32K 字符
  
  - name: "doc-writer"
    description: "技术文档撰写"
    bootstrapProfile:
      contextInjection: "full"         # 完整模式，保留全部上下文
      bootstrapMaxChars: 15000
      bootstrapTotalMaxChars: 60000

第 2 步：验证配置生效

使用 OpenClaw CLI 检查配置解析结果：

查看特定 Agent 的解析后配置
claw agent inspect code-reviewer --show-bootstrap

预期输出包含 resolved bootstrapProfile

第 3 步：运行时诊断确认

通过 /context 诊断路径验证实际生效参数：

启动交互式诊断会话
claw session start --diagnostic-context

在会话中执行
/context show bootstrap --agent code-reviewer

—

技术实现细节

配置解析优先级

OpenClaw 采用明确的优先级规则解析 bootstrap 设置：

Agent.bootstrapProfile > agents.defaults > 系统内置默认值

这意味着：
1. 如果 Agent 定义了 bootstrapProfile，完全使用该配置
2. 否则回退到 agents.defaults
3. 最后使用系统安全默认值

支持的路径与工具

该功能已集成到以下核心路径：

—

实际应用场景

场景一：混合团队的多 Agent 系统

企业级配置示例
agents:
  - name: "security-auditor"
    bootstrapProfile:
      contextInjection: "compact"    # 安全审计注重效率
      bootstrapTotalMaxChars: 16000  # 严格限制防止信息泄露
  
  - name: "architecture-advisor"
    bootstrapProfile:
      contextInjection: "full"       # 架构设计需要完整上下文
      bootstrapTotalMaxChars: 100000 # 大容量支持复杂系统分析

场景二：CI/CD 流水线优化

// 在 Node.js 项目中动态配置
const { createAgent } = require('@openclaw/core');

const prAgent = await createAgent('pr-summary', {
  bootstrapProfile: {
    contextInjection: 'compact',
    bootstrapMaxChars: 4000,        // PR 描述简洁优先
    bootstrapTotalMaxChars: 12000
  }
});

—

配置验证与测试

OpenClaw 团队已为该功能提供完整的测试覆盖：

本地验证命令
pnpm check:changed        # 变更文件检查
pnpm check:test-types     # TypeScript 类型测试（Node 24）

自动回复测试
claw test auto-reply --focus bootstrap-profiles

—

FAQ：常见问题解答

Q1: per-agent bootstrap profile 会覆盖全局默认值吗？

A: 是的，配置优先级为 Agent 专属 > agents.defaults > 系统默认。建议将通用设置放在 agents.defaults，仅在需要特殊调优的 Agent 上定义 bootstrapProfile。

Q2: 如何迁移现有的全局配置？

A: 无需立即迁移。现有配置完全兼容，新功能为可选增强。建议逐步将需要差异化配置的 Agent 迁移到 bootstrapProfile 模式。

Q3: 字符限制参数的具体作用是什么？

bootstrapMaxChars：控制单个上下文片段的最大长度，防止单条内容过长
bootstrapTotalMaxChars：控制所有上下文片段的累计上限，保护系统资源

Q4: 该功能对性能有何影响？

A: 配置解析在 Agent 初始化阶段完成，运行时零开销。实际性能取决于你设置的字符限制——更严格的限制通常意味着更快的响应速度。

Q5: 哪些 OpenClaw 版本支持此功能？

A: 该功能在提交 930852af 中引入，包含在最新稳定版本中。建议通过 claw --version 确认版本，或使用 claw update 升级。

—

总结与下一步

per-agent bootstrap profiles 让 OpenClaw 的多 Agent 管理能力迈入新阶段。关键要点：

1. 精细化控制：每个 Agent 独立配置，告别一刀切
2. 优先级清晰：Agent > 全局 > 默认，逻辑简单明了
3. 全路径支持：Embedded、CLI、诊断工具完整覆盖

建议行动：

审查现有 Agent 配置，识别需要差异化设置的场景
参考 OpenClaw 文档获取完整配置参考
关注后续更新，更多 per-agent 参数即将开放

—

参考来源

OpenClaw 自动回复重构：5 个关键修复让命令上下文管理更可靠

——

OpenClaw 自动回复重构：5 个关键修复让命令上下文管理更可靠

OpenClaw 最新代码提交对 auto-reply 模块进行了深度重构，将分散在各处的命令轮次上下文（command turn context）集中管理。这一改动不仅提升了代码可维护性，更解决了多个影响 AI Agent 命令执行稳定性的边缘场景问题。本文将逐条解析这 5 个关键修复，帮助开发者理解其技术价值。

—

为什么需要集中化命令上下文？

在 OpenClaw 的架构中，auto-reply 模块负责处理用户与 AI 的自动交互流程。当 AI 执行需要用户确认的命令时（如文件修改、代码部署），系统需要维护一个”命令轮次”状态来跟踪交互进度。

此前，命令上下文分散在多个子模块中，导致：

状态同步困难，容易出现竞态条件
代码重复，维护成本高
SDK 兼容性难以保证

本次重构通过集中化管理，将命令轮次的创建、更新、销毁统一到一个核心位置。

—

5 个关键修复详解

1. 核心重构：集中化命令轮次上下文

// 重构前：上下文分散在各处理器中
class ReplyHandler {
  async process(message) {
    const context = await this.loadContext(message.threadId); // 多处重复
    // ...
  }
}

// 重构后：统一通过 CommandTurnManager 管理
class CommandTurnManager {
  getContext(threadId) { / 单一入口 / }
  updateContext(threadId, update) { / 统一更新 / }
  finalizeContext(threadId) { / 统一清理 / }
}

核心价值：消除重复代码，确保所有命令轮次操作遵循同一套状态管理规则。

—

2. 精确收窄命令上下文字面量类型

// 修复前：过于宽泛的类型定义
type CommandContext = Record;

// 修复后：精确的字面量联合类型
type CommandTurnContext = 
  | { status: 'pending'; command: string; authToken?: string }
  | { status: 'executing'; executionId: string }
  | { status: 'completed'; result: unknown }
  | { status: 'failed'; error: ErrorCode };

通过 narrow command turn context literals，编译时即可捕获非法状态转换，减少运行时错误。

—

3. 重新最终化时保留命令授权

// 关键修复：防止授权信息在流程重启后丢失
async refinalizeCommandTurn(turnId) {
  const existing = await this.store.get(turnId);
  
  // 修复前：直接覆盖，丢失 authToken
  // const newContext = { ...baseContext, status: 'pending' };
  
  // 修复后：显式保留授权信息
  const newContext = {
    ...baseContext,
    status: 'pending',
    authToken: existing.authToken, // 关键保留
    authExpiry: existing.authExpiry,
  };
}

此修复解决了 AI Agent 在长时间运行任务中，因流程重启导致用户重复授权的问题。

—

4. 保持命令轮次上下文的 SDK 兼容性

// 确保与 OpenClaw SDK 的序列化格式一致
interface SDKCompatibleContext {
  // 必须使用 snake_case 以匹配 SDK 规范
  turn_id: string;
  thread_id: string;
  created_at: number;
  command_payload: unknown;
  
  // 内部状态使用 _ 前缀，避免与 SDK 字段冲突
  _internal_state: InternalState;
}

// 转换层：自动处理命名风格差异
function toSDKFormat(internal: CommandTurnContext): SDKCompatibleContext {
  return {
    turn_id: internal.turnId,
    thread_id: internal.threadId,
    // ...
  };
}

SDK 兼容性是生态扩展的基础，此修复确保第三方开发者能无缝集成 OpenClaw 的命令系统。

—

5. 在回复设置前路由结构化命令轮次

// 修复前：时序问题导致命令响应丢失
async setupReply(message) {
  await this.prepareReplyContent(message);  // 可能覆盖命令状态
  await this.routeCommandTurn(message);     // 命令处理太晚
}

// 修复后：优先路由命令轮次
async setupReply(message) {
  // 关键调整：先处理结构化命令，再设置回复内容
  const commandResult = await this.routeStructuredCommandTurn(message);
  
  if (commandResult.requiresReply) {
    await this.prepareReplyContent(message, commandResult.context);
  }
}

此修复解决了命令执行结果与用户回复内容竞争的问题，确保 AI Agent 的响应逻辑正确优先。

—

附：CLI 测试类型修复

修复 launchd 作业模拟的类型定义影响：macOS 系统服务集成测试的稳定性

npm test -- --grep "launchd integration"

—

开发者如何应用这些改进？

对于使用 OpenClaw 的开发者，建议采取以下行动：

—

常见问题 FAQ

Q1: 这次重构会破坏现有的 auto-reply 插件吗？

不会。 所有变更均保持向后兼容，旧版 API 已标记为 deprecated 但继续可用。建议在下个主版本发布前完成迁移，参考 OpenClaw 迁移指南。

Q2: 如何验证我的命令上下文是否正常工作？

使用内置诊断命令：

npx openclaw doctor --check command-turn

Q3: “命令轮次”与普通的对话轮次有什么区别？

命令轮次（command turn） 特指需要用户授权或确认的操作流程，具有：

明确的授权状态机
超时和重试机制
执行结果回滚能力

普通对话轮次仅涉及信息交换，无需这些保障机制。

Q4: SDK 兼容性修复具体解决了什么问题？

此前，使用 OpenClaw Python SDK 的开发者会遇到上下文字段命名不一致（turnId vs turn_id），导致反序列化失败。现在系统自动处理这种转换。

Q5: 这次更新对性能有影响吗？

集中化管理减少了约 30% 的数据库查询次数（通过上下文缓存），整体性能略有提升。具体数据可参考性能基准测试报告。

—

总结

本次 OpenClaw 的 centralize command turn context 重构，通过 5 个精准修复解决了 auto-reply 模块的长期技术债务：

1. 架构层面：统一上下文管理，提升可维护性
2. 类型安全：精确字面量类型，编译期错误捕获
3. 可靠性：授权信息持久化，避免重复认证
4. 生态兼容：SDK 格式对齐，降低集成门槛
5. 时序正确性：路由优先级调整，消除竞态条件

建议所有 OpenClaw 用户升级到包含此提交的最新版本，以获得更稳定的 AI Agent 命令执行体验。

—

参考来源

OpenClaw 2026.5.14-beta.1 发布：5大核心功能升级与Docker部署实战

—# OpenClaw 2026.5.14-beta.1 发布：5大核心功能升级与Docker部署实战

OpenClaw 作为新一代 AI Agent 编排平台，在 2026.5.14-beta.1 版本中带来了从消息通道到维护工具的全方位升级。本文将深入解析本次更新的核心价值，帮助开发者快速掌握 Telegram Mini App 集成、智能状态反应系统、Codex 架构迁移等关键特性，并提供完整的 Docker 部署验证方案。

—

一、消息通道全面升级：Telegram Mini App 与跨平台状态同步

1.1 Telegram Mini App 原生支持

本次更新最引人注目的功能是为 Telegram 消息通道引入了 Mini App 支持。开发者现在可以通过 web_app 按钮类型，在私聊场景中渲染原生内联应用界面。

发送带 Mini App 按钮的消息
openclaw message send --presentation \
  --channel telegram \
  --recipient "@username" \
  --content "点击打开数据面板" \
  --button-type web_app \
  --button-url "https://miniapp.example.com"

这一特性显著提升了 AI Agent 的交互体验，用户无需离开 Telegram 即可完成复杂操作，如数据填报、订单确认或可视化分析。

1.2 统一的状态反应生命周期

WhatsApp 通道现已支持完整的 StatusReactionController，与 Telegram 和 Discord 保持功能对齐：

| 状态阶段 | 对应 Emoji | 含义 |
|———|———–|——|
| 队列等待 | ⏳ | 请求已接收，等待处理 |
| 思考中 | 🧠 | LLM 正在推理生成 |
| 工具调用 | 🛠️ | 执行外部工具/API |
| 编码任务 | 💻 | 代码生成或分析 |
| 网络搜索 | 🌐 | 执行 search 或浏览 |
| 软阻塞 | ⏳ | 轻度延迟，可恢复 |
| 硬阻塞 | ⚠️ | 严重阻塞，需干预 |
| 完成 | ✅ | 成功结束 |
| 错误 | ❌ | 执行失败 |
| 压缩中 | 🗜️ | 上下文压缩优化 |

新版 Emoji 设计摒弃了情感化表达，转为直观的状态指示器，降低用户认知负担。

—

二、Codex 架构迁移：从 CLI 到 App-Server 的演进

2.1 移除捆绑式 CLI 后端

本次更新彻底移除了内置的 codex-cli 后端，所有 Codex 功能统一路由至 openai/* 的 App-Server 架构。这一变更带来三大优势：

降低包体积：减少约 15MB 的依赖占用
简化维护：单一后端减少版本碎片化
功能对齐：所有客户端享受同等能力

2.2 流式评论草稿机制

Codex 现在支持将思考过程流式传输至可编辑的频道进度草稿，而不会直接发布为最终答案。这让开发者可以：

1. 实时观察 AI 的推理链条
2. 在发布前人工干预或修正
3. 建立更透明的 Agent 工作流

// 启用流式草稿模式（skill 配置示例）
{
  "skill": "codex-review",
  "config": {
    "streamPreamble": true,
    "promoteToAnswer": false,
    "editableDraft": true
  }
}

2.3 维护者工具：codex-review Skill

新增 codex-review Skill 专为代码审查场景设计，支持两种工作模式：

本地脏工作区审查
openclaw skill run codex-review --mode dirty-work

PR 分支审查（自动迭代至无问题）
openclaw skill run codex-review --mode pr-branch --base main

该工具会自动规避不支持的行内提示，通过 --base 参数确保审查范围精准。

—

三、Docker 部署与验证流程强化

3.1 完整的用户旅程验证

新版本引入了系统化的 Docker 验证通道，覆盖从安装到运维的全生命周期：

3.2 真实 TTY 与持久化测试

针对生产环境需求，新增以下验证场景：

启动完整验证环境
docker run -it \
  -v openclaw-data:/data \
  -v openclaw-media:/media \
  -e OPENCLAW_PERSISTENCE=strict \
  openclaw/openclaw:v2026.5.14-beta.1 \
  --validate-journey full

关键验证点包括：

TTY 交互式终端 onboarding 体验
媒体文件持久化存储
内存状态跨重启保留
已发布版本的平滑升级路径
本地市场插件的更新/卸载流程

—

四、开发者体验与国际化优化

4.1 本地化文本尺寸控制

Control UI 新增浏览器本地文本大小设置，解决移动端 Safari 的焦点缩放问题：

// Quick Settings 程序化调用
openclaw.ui.setTextScale(1.25); // 125% 放大
openclaw.ui.setTextScale(0.875); // 87.5% 缩小

该设置会智能保持输入框高于 iOS 强制缩放阈值（16px），避免破坏布局。

4.2 国际化基线报告

新增 pnpm ui:i18n:report 命令生成硬编码文本聚焦报告，包含：

未抽取的硬编码字符串定位
区域回退元数据完整性检查
翻译覆盖率热力图

生成 i18n 基线报告
pnpm ui:i18n:report --baseline --output ./i18n-report.json

—

五、依赖精简与架构优化

5.1 代理层重构

路由层代理代理已统一通过 @openclaw/proxyline 处理，移除了以下根级依赖：

proxy-agent
https-proxy-agent
minimatch

这一变更减少了约 2.3MB 的依赖树，同时提升了代理配置的一致性。

5.2 CI 强化：禁止补丁依赖

CI 流程现在会自动检测并阻止包含以下内容的 PR：

patches/ 目录下的包补丁文件
pnpm.patchedDependencies 配置项

这确保了团队遵循”上游修复 + 版本升级”的健康依赖管理策略。

—

六、启动追踪与贡献者工具

6.1 所有者级启动归因

Gateway 启动过程新增细粒度追踪，覆盖：

认证流程耗时
插件加载顺序与数量
查找服务调用统计
插件 Sidecar 服务健康状态

6.2 Clawdtributor：智能 PR 分类

新增 Clawdtributor Skill 基于 Discrawl 实现贡献者 PR 智能分类：

运行贡献者 PR 分类
openclaw skill run clawdtributor --repo openclaw/openclaw \
  --triage-rules ./triage-config.yaml \
  --live-status

功能包括实时状态检查、紧凑审查格式输出，以及基于历史数据的自动路由建议。

—

FAQ：常见问题解答

Q1: 如何从旧版 Codex CLI 迁移到 App-Server？

所有 codex-cli/ 模型引用已自动重定向至 openai/ 路由。只需更新 Skill 配置中的模型名称，无需修改业务逻辑。建议在测试环境验证后再部署生产。

Q2: Telegram Mini App 与普通内联键盘有何区别？

Mini App 支持完整的 Web 应用能力（包括 JavaScript、复杂布局、实时数据），而传统内联键盘仅限于按钮回调。使用 --button-type web_app 即可启用，需确保目标 URL 符合 Telegram 安全策略。

Q3: Docker 验证失败如何排查？

执行 openclaw doctor 获取诊断报告，重点检查：

卷挂载权限（openclaw-data 和 openclaw-media）
网络连通性（插件市场、LLM API 端点）
环境变量 OPENCLAW_PERSISTENCE 是否设置为 strict

Q4: 状态反应 Emoji 可以自定义吗？

当前版本为标准化体验，Emoji 映射为固定配置。后续版本计划开放 StatusReactionController 的主题配置接口，可通过 Plugin 系统注入自定义映射表。

Q5: 新版本对 Node.js 版本有要求吗？

由于代理层重构，建议 Node.js ≥ 20.12.0 以获得最佳的 fetch 代理支持。使用 Docker 部署时，官方镜像已包含兼容运行时。

—

总结与下一步

OpenClaw 2026.5.14-beta.1 通过 Codex 架构统一、跨平台消息通道完善、Docker 验证体系强化，为 AI Agent 生产部署奠定了更坚实的基础。建议开发者：

1. 立即体验：在测试环境部署 Docker 版本，验证完整用户旅程
2. 迁移规划：评估现有 Codex CLI 依赖，制定 App-Server 切换计划
3. 通道扩展：利用 Telegram Mini App 提升终端用户交互体验

—

参考来源

OpenClaw v2026.5.12 发布：5大核心改进让 AI Agent 部署更轻量

——

OpenClaw v2026.5.12 发布：5大核心改进让 AI Agent 部署更轻量

一句话总结：OpenClaw 最新版本通过模块化依赖管理和稳定性增强，让生产级 AI Agent 的部署体积更小、运行更可靠，特别适合需要多平台集成的复杂工作流场景。

如果你正在维护基于 OpenClaw 的自动化系统，或计划将 AI Agent 接入 Telegram、Slack、WhatsApp 等平台，这篇更新解读将帮你快速判断是否需要升级，以及如何最大化利用新特性。

—

一、更精简的安装：按需加载依赖

核心变化：依赖外部化

过去，安装 OpenClaw 核心运行时会自动拉取大量你可能用不到的 SDK——即使你不使用 AWS 服务，Amazon Bedrock 的依赖也会被包含。v2026.5.12 彻底改变了这一设计：

具体外部化的组件：

Amazon Bedrock 及 Bedrock Mantle provider 包
Slack 集成插件
OpenShell 沙箱环境
Anthropic Vertex provider

升级建议

如果你当前使用 Docker 部署，建议重建镜像以清理冗余依赖：

拉取最新镜像
docker pull openclaw/openclaw:latest

清理旧镜像层（可选，回收磁盘空间）
docker image prune -f

重新部署，仅安装需要的插件
docker run -d \
  --name openclaw \
  -e OPENCLAW_PLUGINS="telegram,slack" \
  -v $(pwd)/config:/app/config \
  openclaw/openclaw:latest

> 💡 提示：通过 OPENCLAW_PLUGINS 环境变量显式声明所需插件，可确保最小化运行时体积。

—

二、Telegram 集成：从”能用”到”可靠”

四大稳定性改进

1. 隔离式轮询（Isolated Polling）

以往 Telegram Bot 的 Bot API 轮询与主事件循环耦合，当主线程阻塞时会导致消息接收中断。新版本将 ingress 移至独立 worker，并配备持久化本地缓冲队列（durable local spooling）：

消息流：Telegram API → 隔离 Worker → 本地 Spool → 主事件循环
                    ↑______________↓
                    （主循环阻塞时不丢消息）

2. HTML/Markdown 格式保留

修复了定时消息（cron announce）中 Markdown 链接退化为纯文本锚点的问题。现在富媒体格式的消息在流式传输和定时投递中都能正确渲染。

3. 智能群媒体过滤

当启用 requireMention 时，Bot 会跳过未提及的群组媒体下载，避免不必要的网络请求和失败回复。

4. 配置示例

config/telegram.yaml
telegram:
  botToken: "${TELEGRAM_BOT_TOKEN}"
  requireMention: true  # 仅在@机器人时响应
  formatting:
    preserveHtml: true   # 保留 HTML 标签
    markdownSupport: true # 启用 Markdown 解析
  resilience:
    isolatedPolling: true      # 启用隔离轮询
    spoolPath: "/app/spool"    # 本地缓冲路径
    maxSpoolSize: "100MB"

—

三、Codex/OpenAI 路径：开发体验全面升级

关键改进一览

MCP（Model Context Protocol）集成实践

MCP 是 Anthropic 推出的开放协议，用于标准化 AI 模型与外部工具的交互。OpenClaw 现在支持将自身作为 MCP 服务器投影：

// mcp-config.json
{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["-y", "@openclaw/mcp-server@latest"],
      "env": {
        "OPENCLAW_API_URL": "http://localhost:3000",
        "OPENCLAW_API_KEY": "${OPENCLAW_API_KEY}"
      }
    }
  }
}

配合 Claude Desktop 或 Cline 等支持 MCP 的客户端，可直接调用 OpenClaw 的 agent 能力：

通过 MCP 触发 OpenClaw 工作流
claude "使用 openclaw 查询今日销售数据并生成报告"

—

四、插件系统：安装更新更稳健

pnpm 11 支持与依赖保护

插件安装常见问题（如 peer-dependency 冲突、运行时扫描失败）在新版本中得到系统性修复：

推荐：使用 pnpm 11 安装插件
npm install -g pnpm@11

安装插件时保留 peer 依赖
openclaw plugin install @openclaw/slack --preserve-peer-deps

从 Git 源安装（修复了之前的路径解析问题）
openclaw plugin install github:custom-org/custom-plugin#main

安全加固

网关（Gateway）、浏览器自动化（Browser）、节点配对（Node pairing）、沙箱（Sandbox）和会话记录（Transcript）等路径均通过了安全与溯源强化审查（security/provenance hardening pass），建议生产环境用户审查以下配置：

security.yaml gateway: provenance: verifySignatures: true # 验证插件签名 allowedOrigins: # 限制插件来源 - "https://registry.openclaw.dev" - "https://github.com/openclaw/*"

sandbox: isolation: "strict" # 严格隔离模式 allowedSyscalls: [] # 显式允许的系统调用

—

五、UI 与交互：细节体验优化

流式输出控制

Control UI 和 WebChat 新增持久化的自动滚动模式选择器，解决长期困扰用户的滚动跳动问题：

通过环境变量预设模式
OPENCLAW_UI_SCROLL_MODE=always-follow

—

FAQ：常见问题解答

Q1: 升级后现有配置会失效吗？

不会。v2026.5.12 保持向后兼容，但建议检查：

若使用了 Amazon Bedrock 或 Slack，需显式安装对应插件：openclaw plugin install @openclaw/bedrock @openclaw/slack
自定义插件若依赖核心内部的 AWS SDK，需更新为独立依赖

Q2: 如何验证 Telegram 的隔离轮询已生效？

查看日志中是否出现 worker:ingress:isolated 标记：

docker logs openclaw | grep "isolated worker"
预期输出：INFO [worker:ingress:isolated] Telegram polling isolated, spool active

Q3: MCP server projection 与直接 API 调用有何区别？

MCP 提供标准化工具发现机制，客户端可自动识别可用能力；直接 API 调用需手动管理端点。MCP 更适合与 Claude Desktop、Cline 等工具链集成。

Q4: 新版本是否支持自托管 WhatsApp？

支持，但 WhatsApp 依赖已外部化。部署时需：

openclaw plugin install @openclaw/whatsapp
并配置 WhatsApp Business API 凭证

Q5: 如何回滚到旧版本？

指定历史标签
docker pull openclaw/openclaw:v2026.4.28
docker run ... openclaw/openclaw:v2026.4.28

> ⚠️ 回滚前备份数据库，新版本可能有 schema 变更。

—

总结与下一步

OpenClaw v2026.5.12 的核心价值在于生产就绪性提升：

✅ 部署体积减小 30-50%（依赖实际使用场景）
✅ Telegram 等关键集成达到企业级稳定性
✅ 开发工具链与 MCP 生态对齐
✅ 安全基线全面提升

建议行动：
1. 在测试环境验证插件依赖外部化影响
2. 评估 Telegram 隔离轮询对现有 Bot 的改进
3. 探索 MCP 集成以简化工具链配置

—

参考来源

OpenClaw v2026.5.12-beta.7 发布：5大核心改进与ACP故障转移详解

——

OpenClaw v2026.5.12-beta.7 发布：5大核心改进与ACP故障转移详解

OpenClaw 最新 Beta 版本 v2026.5.12-beta.7 正式发布，本次更新聚焦插件架构优化、运行时可靠性与安全加固三大方向。无论你是构建企业级 AI Agent 工作流，还是部署自托管的自动化网关，这 5 个关键改进都将直接影响你的生产环境稳定性。

本文将逐一解析新功能的技术细节，并提供可直接落地的配置代码。

—

一、Amazon Bedrock 插件化：告别臃肿依赖

核心变化

AWS SDK 依赖已从 OpenClaw 核心包中移除。现在，只有当你显式安装 bedrock 或 bedrock-mantle 提供商插件时，才会拉取相关依赖。

为什么重要？

此前，即使你不使用 AWS 服务，核心安装也会捆绑 50MB+ 的 AWS SDK。这在容器化部署（Docker/Kubernetes）中显著增加了镜像体积和启动时间。

迁移操作

全新安装（无 AWS 依赖）
npm install -g @openclaw/cli

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

验证依赖瘦身

对比安装前后
du -sh node_modules/@aws-sdk  # 安装插件后才会出现

—

二、ACP 故障转移：多后端高可用配置

ACP（Agent Control Protocol） 新增 acp.fallbacks 配置，允许在主后端不可用时自动切换备用运行时，且在输出产生前完成切换，避免用户看到中断或错误片段。

配置示例

openclaw.config.yaml
acp:
  runtime: primary-backend
  fallbacks:
    - name: backup-gpu-pool
      runtime: bedrock-runtime-us-west-2
      condition: "error_rate > 5% or latency_p99 > 3000ms"
    - name: cold-standby
      runtime: openai-gpt4o-fallback
      condition: "primary_unavailable > 30s"

故障转移触发条件

> 注意：故障转移决策在首个 token 生成前完成，确保用户无感知切换。

—

三、Telegram Bot 稳定性：隔离工作进程

问题背景

此前，当 OpenClaw 主事件循环阻塞（如复杂工作流执行）时，Telegram Bot API 轮询会中断，导致消息丢失。

解决方案

新版本将消息入口（ingress）移至独立工作进程，并引入本地持久化队列（durable local spool）：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Telegram API   │────▶│  Isolated Worker │────▶│  Local Spool    │
│  (长轮询)        │     │  (独立进程)       │     │  (持久化队列)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
                              ▼
                        ┌─────────────────┐
                        │  Main Event Loop │
                        │  (主业务逻辑)     │
                        └─────────────────┘

环境变量配置

.env
OPENCLAW_TELEGRAM_ISOLATED_WORKER=true
OPENCLAW_TELEGRAM_SPOOL_PATH=/var/spool/openclaw/telegram
OPENCLAW_TELEGRAM_SPOOL_MAX_SIZE=100MB

—

四、安全加固：Windows 沙箱路径拦截

漏洞修复

Windows 环境下，沙箱现在会拦截 %USERPROFILE% 下的敏感路径绑定，即使 HOME 环境变量指向其他位置。

被拦截的凭证路径

%USERPROFILE%\.codex
%USERPROFILE%\.openclaw
%USERPROFILE%\.ssh
%USERPROFILE%\.aws

Docker 部署建议

Dockerfile
FROM openclaw/openclaw:latest

显式设置非敏感 HOME（额外防护层）
ENV HOME=/tmp/openclaw-home

运行非特权用户
USER 1000:1000

—

五、UI 体验：自动滚动模式持久化

WebChat/Control UI 新增自动滚动行为选择器，用户偏好现在会持久化存储：

前端配置

// 通过 localStorage 查看当前设置
localStorage.getItem('openclaw:autoscroll:mode');
// 返回值: "near-bottom" | "always-follow" | "manual"

—

六、其他值得关注的修复

—

常见问题 FAQ

Q1: 我已在使用 Amazon Bedrock，升级后需要做什么？

A: 运行以下命令补装插件即可，配置无需变更：

openclaw plugin install provider-bedrock provider-bedrock-mantle

Q2: ACP 故障转移会影响对话连续性吗？

A: 不会。故障转移在首个 token 生成前完成，用户侧表现为”响应稍慢”而非”回答中断”。上下文（memory）会通过 OpenClaw 的会话层保持。

Q3: Telegram 独立工作进程会增加资源消耗吗？

A: 约增加 50-80MB 内存占用，但消除了消息丢失风险。可通过 OPENCLAW_TELEGRAM_ISOLATED_WORKER=false 回退到旧模式（不推荐生产环境）。

Q4: 如何验证沙箱路径拦截是否生效？

A: 在 Windows 执行：

openclaw sandbox test --bind %USERPROFILE%\.ssh
预期输出: Error: EACCES: path blocked by sandbox policy

Q5: 这个版本适合生产部署吗？

A: Beta.7 已修复多个生产环境关键问题（Telegram 稳定性、网关状态同步），建议非关键业务先行验证，关键业务等待 RC 版本。

—

总结与下一步

OpenClaw v2026.5.12-beta.7 的核心价值在于模块化架构与运行时韧性：

1. 按需安装减少攻击面和部署体积
2. ACP 故障转移保障 AI Agent 高可用
3. 进程隔离解决长期存在的消息可靠性问题

建议操作：

开发环境：立即升级验证新功能
生产环境：等待 RC 后配合蓝绿部署
关注 OpenClaw 官方文档获取 GA 版本通知

—

OpenClaw Agent Cron 回退机制优化：5 个关键改进解析

为什么需要优化 Cron 回退机制？

5 项核心改进详解

1. 修复：正确执行子代理 Cron 回退配置

配置示例：subagent-config.yaml

2. 重构：共享 Cron 子代理模型选择逻辑

重构后的共享选择器（示意）

所有 Cron Subagent 共用同一选择器实例

3. 测试对齐：统一回退策略预期

4. 修复：保留已选模型的回退链

修复前（问题代码）

但后续如果该模型也失败，会错误地回到默认链

修复后

继承该模型的自定义回退配置：gpt-3.5-turbo → local-llm → queue

5. 修复：保护仅回退模式的覆盖配置

仅回退模式配置

升级指南

检查当前版本

查看 OpenClaw 版本

确认包含本更新（v2.4.0+）

配置迁移建议

1. 导出当前配置

2. 验证回退链完整性

3. 试运行检测（dry-run）

常见问题（FAQ）

Q1: 什么是 Subagent 的 Cron 回退机制？

Q2: 本次更新会影响现有定时任务的执行吗？

Q3: 如何查看 Subagent 实际使用的模型？

Q4: “共享模型选择器”会带来性能提升吗？

Q5: 能否为不同 Subagent 设置独立的回退策略？

总结

相关阅读

参考来源

OpenClaw 2026.5.14-beta.2 发布：10大新功能解析与升级指南

为什么这次更新值得关注？

核心更新详解

1. Canvas 懒加载：Gateway 启动速度提升

验证启动时间优化（对比前后版本）

2. Agent 级配置覆盖：精细化上下文控制

agents.yaml 示例

3. WhatsApp 状态反应：完整生命周期支持

4. 插件钩子增强：上下文预算透明化

5. Gateway 启动追踪：Owner 级可观测性

查看启动追踪日志

6. 依赖优化：代理与安全清理

清理旧依赖缓存

7. Codex 应用服务器重构

8. 维护者工具升级

本地脏工作区审查

PR 分支审查（循环至无问题）

避免不支持的行内提示

9. 控制面板体验优化

生成硬编码文案聚焦区域报告

10. DeepSeek V4 Flash 文档与 Docker 验证

验证完整 onboarding 流程

升级指南

Docker 部署

拉取最新镜像

备份当前配置

更新并重启

源码构建

更新代码

清理并安装

验证代理依赖清理

常见问题 FAQ

Q1: Canvas 懒加载会影响首次调用性能吗？

Q2: 如何为特定 Agent 设置更大的上下文窗口？

Q3: WhatsApp 状态反应需要额外配置吗？

Q4: 升级后 Codex 相关功能异常怎么办？

Q5: 如何验证 Docker 部署成功？

预期输出包含: startup_trace, lazy_load, status_reaction

总结与下一步

相关阅读

参考来源

OpenClaw 新功能：5 步实现 AI Agent 历史图片自动关联

为什么需要历史图片关联？

核心功能解析

1. 智能历史媒体绑定

2. 运行时优化：避免不必要的媒体处理

3. 媒体类型兼容与边界处理