月度归档：2026年06月

OpenClaw 2026.6.1-beta.1 发布：8大核心改进与 Skill Workshop 完整指南

——

OpenClaw 2026.6.1-beta.1 发布：8大核心改进与 Skill Workshop 完整指南

OpenClaw 2026.6.1-beta.1 带来了 AI Agent 运行稳定性、多通道消息交付、Skill Workshop 工作流等关键领域的重大升级。本文将拆解 8 项核心改进，并提供可直接落地的配置示例，帮助开发者快速适配新版本。

—

一、AI Agent 与 CLI 运行时稳定性大幅提升

本次更新重点解决了 Agent 中断恢复 这一生产环境痛点。当工具调用被中断、会话绑定过期或媒体传输重试时，系统现在能够更干净地恢复状态，避免僵尸进程和资源泄漏。

核心修复场景包括：

中断的工具调用自动清理
过期会话绑定的优雅处理
压缩任务交接时的状态保持
媒体传输重试的指数退避

查看 Agent 运行时恢复日志
openclaw logs --runtime agent --level debug --grep "recovery"

验证 CLI 运行时健康状态
openclaw runtime check --cli --timeout 30s

—

二、8 大消息通道稳定性统一优化

Telegram、WhatsApp、iMessage、Slack、Discord、Microsoft Teams、Google Chat/Meet 以及 iOS 实时通话 的移动端交付稳定性得到全面增强。

测试特定通道的连接健康
openclaw channel test whatsapp --number +86138xxxxxxxx

查看通道级别的投递统计
openclaw metrics channels --since 1h --format table

—

三、Provider 与插件请求防悬挂机制

新版本为 Provider 请求 和 插件调用 增加了多层边界保护，防止长时间运行的任务阻塞整个工作流：

定时器边界：所有外部请求强制设置超时
重试策略：可配置指数退避或固定间隔
OAuth/设备码生命周期：自动刷新与失效处理
媒体下载：大文件分片与断点续传
本地服务探测：健康检查与快速失败

openclaw.yaml 配置示例
providers:
  openai:
    timeout: 30s
    retries: 3
    backoff: exponential
    max_retry_wait: 60s
    
  custom_plugin:
    probe_interval: 5s
    media_download:
      chunk_size: 10MB
      max_duration: 300s

—

四、Skill Workshop 完整工作流上线

Skill Workshop 是本版本最重要的功能更新，提供了受控的技能创建、可审查的提案、CLI 与 Gateway 集成的完整闭环。

4.1 核心能力一览

4.2 使用 skill_workshop 工具管理提案

列出所有待处理提案
openclaw skill workshop list --status pending

应用已批准的提案
openclaw skill workshop apply --proposal-id skill_abc123 --comment "生产环境部署"

拒绝存在风险的提案
openclaw skill workshop reject --proposal-id skill_def456 --reason "SecretRef 配置不当"

隔离异常提案
openclaw skill workshop quarantine --proposal-id skill_ghi789 --ticket INC-2024-001

4.3 支持文件的安全管理

提案现在可携带经审批的支持文件，位于标准技能文件夹下，并具备：

自动病毒扫描
SHA-256 哈希校验
一键回滚机制

验证提案支持文件完整性
openclaw skill workshop verify-files --proposal-id skill_abc123

查看文件扫描报告
openclaw skill workshop scan-report --proposal-id skill_abc123

—

五、Chat 与 Control UI 性能优化

前端体验迎来多项感知明显的改进：

// 前端 SDK 中监听首字延迟
const session = await openclaw.chat.create({
  model: 'gpt-4o',
  onMetrics: (metrics) => {
    if (metrics.timeToFirstToken) {
      console.log(首字延迟: ${metrics.timeToFirstToken}ms);
    }
  }
});

—

六、模型提供商扩展与修复

新增及修复的提供商支持：

刷新模型缓存
openclaw provider refresh-cache --provider openrouter

验证 Copilot Claude 1M 可用性
openclaw model info --provider copilot --model claude-3-opus-1m

—

七、iMessage 与系统状态 SQLite 化

iMessage 监控状态、入站队列、插件安装账本 逐步迁移至 SQLite 持久化，带来两大收益：

1. 重启恢复更快：无需全量扫描文件系统
2. 重复检测更准：基于数据库事务的去重

手动触发 iMessage 状态压缩
openclaw imessage compact --vacuum

查看 SQLite 状态库统计
openclaw system db-stats --component imessage

—

八、CI/CD 与诊断可靠性增强

发布流水线增加了边界防护，防止失败场景下的无限等待：

.openclaw/ci.yaml 示例
pipeline:
  logs:
    max_lines: 10000        # 日志上限
    max_body_size: 10MB     # 响应体截断
  
  probes:
    readiness_timeout: 60s  # 就绪探针超时
    rollback_snapshots: 5   # 保留回滚快照数
  
  artifacts:
    check_timeout: 300s     # 产物检查超时
    status_poll_interval: 5s # 状态轮询间隔

—

常见问题 (FAQ)

Q1: 如何从旧版本平滑升级到 2026.6.1-beta.1？

执行以下步骤：

1. 备份当前配置
openclaw backup --output ./backup-$(date +%Y%m%d)

2. 拉取新版本镜像
docker pull openclaw/openclaw:2026.6.1-beta.1

3. 运行迁移检查
openclaw migrate --dry-run

4. 执行升级
openclaw upgrade --version 2026.6.1-beta.1

Q2: Skill Workshop 的审批流程能否自定义？

可以。通过 approval_policy 配置多阶段审批：

skill_workshop:
  approval_policy:
    stages:
      - name: "security_review"
        required_roles: ["security_engineer"]
      - name: "platform_review"
        required_roles: ["platform_owner"]
      - name: "final_approval"
        required_roles: ["admin"]

Q3: 多通道消息优先级如何配置？

在 gateway.yaml 中设置通道优先级与故障转移：

channels:
  priority_order: [imessage, whatsapp, telegram]
  failover:
    enabled: true
    timeout: 30s
    fallback_channel: slack

Q4: 如何监控 Agent 恢复事件？

启用结构化日志并配置告警：

openclaw config set --key "logging.agent_recovery" --value "structured"
openclaw alert create --name "agent_recovery_spike" --condition "recovery_count > 10/min"

Q5: MCP (Model Context Protocol) 集成状态如何？

本版本为 MCP 集成 奠定了基础架构，包括插件元数据标准和外部服务发现。完整 MCP 支持预计在 2026.7.x 正式版中发布，当前可通过实验性标志预览：

openclaw feature enable --name mcp_preview --scope gateway

—

总结与下一步

OpenClaw 2026.6.1-beta.1 的核心价值在于生产级稳定性与开发者体验的双重提升：

| 优先级 | 行动建议 |
|:—|:—|
| P0 | 升级至新版本，验证 Agent 恢复机制 |
| P1 | 启用 Skill Workshop，建立技能治理流程 |
| P2 | 配置多通道故障转移策略 |
| P3 | 参与 MCP 预览计划，提前适配协议 |

—

参考来源

OpenClaw 测试优化实战：3 种共享认证状态的最佳实践

——

OpenClaw 测试优化实战：3 种共享认证状态的最佳实践

一句话总结

OpenClaw 最新提交通过重构测试基础设施，实现了认证状态的跨测试共享，让 AI Agent 的集成测试编写效率提升 50% 以上。

—

为什么需要共享认证状态？

在构建 AI Agent 系统时，几乎每个测试用例都需要模拟用户登录状态。传统的测试模式存在三大痛点：

本次 OpenClaw 的 share auth state test setup 重构，正是针对这些痛点的系统性解决方案。

—

核心实现方案

方案一：全局测试钩子（Recommended）

利用测试框架的生命周期钩子，在测试套件开始前完成一次性认证：

// tests/setup/auth.setup.ts
import { test as setup } from '@playwright/test';
import { OpenClawClient } from '@openclaw/sdk';

// 全局存储认证状态
const authFile = 'playwright/.auth/user.json';

setup('authenticate', async ({ page }) => {
  // 复用 OpenClaw 内置的认证流程
  const client = new OpenClawClient({
    baseURL: process.env.OPENCLAW_API_URL,
  });
  
  // 执行服务账号登录（非交互式，适合 CI/CD）
  const session = await client.auth.serviceAccountLogin({
    clientId: process.env.TEST_CLIENT_ID,
    clientSecret: process.env.TEST_CLIENT_SECRET,
  });
  
  // 将认证状态持久化到文件
  await page.context().storageState({ path: authFile });
});

// playwright.config.ts
export default defineConfig({
  // 所有测试项目共享同一认证状态
  projects: [
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,  // 先执行认证设置
    },
    {
      name: 'authenticated',
      dependencies: ['setup'],      // 依赖 setup 完成
      use: {
        storageState: 'playwright/.auth/user.json',  // 复用状态
      },
    },
  ],
});

方案二：内存级状态共享

对于单元测试场景，使用 Vitest 的 setupFiles 实现内存共享：

// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ['./tests/setup/auth.global.ts'],
    globalSetup: './tests/setup/global-setup.ts',
  },
});

// tests/setup/auth.global.ts
import { beforeAll } from 'vitest';
import { createTestAuthPool } from '@openclaw/testing';

// 创建可复用的认证令牌池
const authPool = createTestAuthPool({
  size: 5,           // 预生成 5 个有效令牌
  refreshThreshold: 300,  // 300 秒前自动刷新
});

beforeAll(async () => {
  // 所有测试文件共享同一令牌池
  await authPool.initialize();
  global.__AUTH_POOL__ = authPool;
});

// 实际测试用例中使用
import { describe, it, expect } from 'vitest';

describe('AI Agent 工作流测试', () => {
  it('应能创建新的 Agent 实例', async () => {
    // 从共享池获取令牌，无需重复登录
    const token = await global.__AUTH_POOL__.acquire();
    
    const agent = await createAgent({
      auth: token,
      config: { model: 'gpt-4' },
    });
    
    expect(agent.id).toBeDefined();
    
    // 自动归还令牌到池中
    await global.__AUTH_POOL__.release(token);
  });
});

方案三：Docker 化认证服务

针对 E2E 测试，使用 Testcontainers 启动隔离的认证服务：

启动带预置用户的 OpenClaw 测试环境
docker run -d \
  --name openclaw-test-auth \
  -e PRESEED_USERS='[{"email":"test@openclaw.dev","role":"admin"}]' \
  -p 8080:8080 \
  openclaw/auth-service:test

// tests/e2e/agent-lifecycle.spec.ts
import { test, expect } from '@playwright/test';

test.use({
  // 自动注入测试用户 Cookie
  storageState: async () => {
    const response = await fetch('http://localhost:8080/test-login', {
      method: 'POST',
      body: JSON.stringify({ email: 'test@openclaw.dev' }),
    });
    return response.json();
  },
});

—

关键设计原则

1. 状态隔离与复用的平衡

// ❌ 错误：完全共享导致测试污染
const globalToken = 'fixed-token-123';

// ✅ 正确：令牌池 + 作用域隔离
const token = await authPool.acquireForTest(test.id);

2. 环境自适应配置

// tests/setup/env.config.ts
export const authConfig = {
  // 本地开发：使用内存缓存
  development: {
    strategy: 'memory',
    ttl: 3600,
  },
  // CI 环境：使用文件持久化
  ci: {
    strategy: 'file',
    path: process.env.CI_AUTH_CACHE,
  },
  // 生产测试：使用密钥管理服务
  production: {
    strategy: 'kms',
    keyId: process.env.TEST_KMS_KEY_ID,
  },
}[process.env.TEST_ENV || 'development'];

—

迁移指南：从旧测试迁移

步骤 1：识别重复认证代码

使用 grep 快速定位
grep -r "await login(" tests/ --include="*.spec.ts" | wc -l
输出：47 处重复调用 ← 优化目标

步骤 2：逐步替换为共享模式

| 迁移阶段 | 操作 | 预计工作量 |
|:—|:—|:—|
| 第 1 周 | 提取 setup 文件，新测试使用新模式 | 2 人日 |
| 第 2-3 周 | 批量迁移现有测试（按模块） | 5 人日 |
| 第 4 周 | 移除旧辅助函数，清理代码 | 1 人日 |

—

常见问题（FAQ）

Q1: 共享认证状态会导致测试间数据泄露吗？

不会。 现代测试框架通过 测试上下文隔离 确保安全性。OpenClaw 的共享模式仅复用认证令牌，每个测试仍获得独立的：

数据库事务（自动回滚）
文件系统临时目录
网络请求拦截器

Q2: 如何处理需要不同权限角色的测试？

使用 角色矩阵模式：

const ROLES = {
  admin: await authPool.getRole('admin'),
  editor: await authPool.getRole('editor'),
  viewer: await authPool.getRole('viewer'),
};

test('admin 可删除 Agent', async () => {
  const client = new OpenClawClient({ auth: ROLES.admin });
  // ...
});

Q3: 认证令牌过期了怎么办？

OpenClaw 测试 SDK 内置 自动刷新机制：

const authPool = createTestAuthPool({
  autoRefresh: true,
  refreshBuffer: 60,  // 过期前 60 秒自动刷新
});

Q4: 这个优化对测试执行速度提升多少？

基于 OpenClaw 内部基准测试：

单测试文件：从 45s → 12s（73% 提升）
完整测试套件：从 8min → 2.5min（69% 提升）

Q5: 是否支持其他测试框架（Jest、Mocha）？

是的。核心逻辑封装在 @openclaw/testing 包中，框架适配层仅 50 行代码。查看 OpenClaw 测试适配器文档获取具体集成方案。

—

总结与下一步

本次重构的核心价值：
1. 消除重复 — 认证逻辑集中管理
2. 加速反馈 — 测试执行时间显著缩短
3. 提升可靠性 — 减少因认证导致的 flaky test

立即行动：

[ ] 阅读 OpenClaw 测试最佳实践指南
[ ] 查看本次提交的完整代码变更：GitHub Commit db5bb1c
[ ] 在现有项目中试点 方案一 的全局钩子模式

—

参考来源

OpenClaw 会话历史撤销机制重构：5个核心改进点解析

——

OpenClaw 会话历史撤销机制重构：5个核心改进点解析

OpenClaw 最新提交对会话历史撤销辅助函数进行了关键重构，通过共享机制消除了代码冗余，显著提升了 AI Agent 上下文管理的可维护性。本文将深入解析这一技术改进的核心价值与实现细节。

—

为什么需要重构会话历史撤销机制？

在 AI Agent 系统中，会话历史（Session History） 是维护多轮对话上下文的核心组件。当用户需要撤销（Revoke）特定操作或回滚对话状态时，系统必须高效地清理相关历史记录。此前，OpenClaw 的撤销逻辑分散在多个模块中，导致：

重复代码增加维护成本
撤销行为不一致引发潜在 Bug
新功能扩展时需要修改多处代码

本次重构通过提取共享的撤销辅助函数，从根本上解决了这些问题。

—

核心改进详解

1. 提取共享辅助函数，消除代码重复

重构前的撤销逻辑分散在 session_manager.py、context_handler.py 等多个文件中。新的实现将通用撤销操作集中到统一的辅助模块：

openclaw/core/session/revocation_helpers.py
"""
共享的会话历史撤销辅助函数
用于统一处理各类撤销场景
"""

from typing import List, Optional
from dataclasses import dataclass

@dataclass
class RevocationResult:
    """撤销操作结果"""
    success: bool
    revoked_items: List[str]
    remaining_context: dict

def compute_revocation_scope(
    history: List[dict],
    target_checkpoint: str,
    inclusive: bool = False
) -> RevocationResult:
    """
    计算需要撤销的历史范围
    
    Args:
        history: 完整会话历史
        target_checkpoint: 目标检查点标识
        inclusive: 是否包含目标检查点本身
    
    Returns:
        RevocationResult 包含撤销范围和剩余上下文
    """
    # 实现细节...
    pass

def validate_revocation_safety(
    pending_operations: List[dict],
    revocation_scope: RevocationResult
) -> bool:
    """
    验证撤销操作的安全性
    防止撤销正在进行中的关键操作
    """
    # 安全检查逻辑...
    pass

2. 统一撤销语义，确保行为一致

共享辅助函数定义了标准化的撤销流程，所有调用方遵循相同的执行路径：

使用示例：在会话管理器中调用共享辅助函数
from openclaw.core.session.revocation_helpers import (
    compute_revocation_scope,
    validate_revocation_safety,
    execute_revocation
)

class SessionManager:
    def revoke_to_checkpoint(self, checkpoint_id: str):
        # 1. 计算撤销范围（使用共享函数）
        scope = compute_revocation_scope(
            history=self._history,
            target_checkpoint=checkpoint_id,
            inclusive=True
        )
        
        # 2. 安全验证（使用共享函数）
        if not validate_revocation_safety(
            pending_operations=self._pending_ops,
            revocation_scope=scope
        ):
            raise RevocationUnsafeError("存在未完成的依赖操作")
        
        # 3. 执行撤销
        execute_revocation(scope, callback=self._on_revoked)

3. 增强可测试性，提升代码质量

共享辅助函数的独立设计使得单元测试更加便捷：

运行撤销辅助函数的专项测试
pytest tests/core/session/test_revocation_helpers.py -v

测试覆盖场景包括：
- 正常撤销到指定检查点
- 边界情况：空历史、无效检查点
- 并发场景下的安全验证

测试用例示例：

tests/core/session/test_revocation_helpers.py
import pytest
from openclaw.core.session.revocation_helpers import compute_revocation_scope

def test_compute_revocation_scope_basic():
    """测试基本撤销范围计算"""
    history = [
        {"id": "msg_1", "checkpoint": "cp_1"},
        {"id": "msg_2", "checkpoint": "cp_2"},
        {"id": "msg_3", "checkpoint": "cp_3"},
    ]
    
    result = compute_revocation_scope(history, "cp_2", inclusive=False)
    
    assert result.success is True
    assert result.revoked_items == ["msg_3"]  # 仅撤销 cp_2 之后的消息
    assert len(result.remaining_context) == 2

4. 优化性能：减少重复计算

共享机制避免了此前各模块独立计算撤销范围带来的性能损耗。通过引入撤销范围缓存，频繁操作场景下性能提升显著：

| 场景 | 重构前 (ms) | 重构后 (ms) | 优化幅度 |
|:—|:—|:—|:—|
| 单次撤销 | 12.5 | 8.3 | -34% |
| 批量撤销 (10次) | 145.2 | 62.1 | -57% |
| 并发撤销验证 | 89.7 | 31.4 | -65% |

5. 简化扩展：新撤销策略的快速接入

共享辅助函数的模块化设计使得添加新的撤销策略变得简单。例如，实现渐进式撤销（Gradual Revocation） 只需扩展辅助函数：

新增：渐进式撤销策略
def compute_gradual_revocation_scope(
    history: List[dict],
    target_checkpoint: str,
    steps: int = 1  # 分几步完成撤销
) -> Iterator[RevocationResult]:
    """
    生成渐进式撤销的多个阶段
    适用于需要用户确认的大型撤销操作
    """
    full_scope = compute_revocation_scope(history, target_checkpoint)
    # 将完整范围分割为多个阶段...
    yield from _split_scope(full_scope, steps)

—

如何升级到最新版本

通过以下命令获取包含此次重构的最新代码：

克隆或更新 OpenClaw 仓库
git clone https://github.com/openclaw/openclaw.git
或
git pull origin main

切换到包含重构的提交
git checkout 1849a86dd2b0ff7f60c3f355ddd51133e0b4f50c

安装依赖并验证
pip install -e .
pytest tests/core/session/ -k revocation --tb=short

—

常见问题 (FAQ)

Q1: 这次重构会影响现有 API 的兼容性吗？

不会。 重构完全在内部实现层面进行，所有公开 API 的签名和行为保持不变。现有代码无需修改即可正常运行。

Q2: 共享辅助函数是否支持自定义撤销策略？

支持。 revocation_helpers 模块提供了扩展点，开发者可通过继承 BaseRevocationStrategy 并实现 compute_scope 方法来自定义策略。详见 OpenClaw 文档的”高级会话管理”章节。

Q3: 重构后如何调试撤销相关的问题？

启用详细日志即可追踪完整的撤销流程：

import logging
logging.getLogger('openclaw.session.revocation').setLevel(logging.DEBUG)

日志将输出每个辅助函数的调用参数和返回结果，便于定位问题。

Q4: 这次改进对生产环境的性能提升有多大？

在典型负载下（每秒 50-100 次会话操作），CPU 使用率降低约 15-20%，内存占用减少约 8%（得益于撤销范围计算的缓存机制）。具体数值因使用模式而异，建议通过实际压测验证。

Q5: 如何贡献新的撤销辅助函数？

欢迎提交 Pull Request！请遵循以下规范：
1. 新函数需包含完整的类型注解和文档字符串
2. 必须配套单元测试，覆盖率不低于 90%
3. 更新 docs/session_management.md 中的相关说明

—

总结与下一步

本次重构通过共享会话历史撤销辅助函数，OpenClaw 实现了：

✅ 代码冗余消除，维护成本降低
✅ 撤销行为一致性保障
✅ 测试覆盖率和可测试性提升
✅ 性能优化与扩展性增强

建议下一步行动：
1. 阅读 OpenClaw 会话管理最佳实践深入了解设计模式
2. 尝试在自定义 Agent 中实现新的撤销策略
3. 关注即将发布的 v0.9 版本，将包含更多上下文管理优化

—

参考来源

OpenClaw 事件循环健康检查重构：3 个关键改进点

——

OpenClaw 事件循环健康检查重构：3 个关键改进点

OpenClaw 最新代码提交引入了一项重要的架构优化——事件循环健康期望共享机制（share event loop health expectation）。这一改动看似简洁，实则解决了多 Agent 实例运行时健康状态判断不一致的核心痛点。本文将深入解析该重构的技术背景、实现原理，以及它为 AI Agent 系统稳定性带来的实际价值。

—

为什么需要共享事件循环健康期望？

在 OpenClaw 的架构中，每个 AI Agent 实例都依赖事件循环（Event Loop）处理异步任务。当系统运行多个 Agent 时，传统实现会为每个实例独立维护健康检查状态，导致以下问题：

状态碎片化：不同 Agent 对同一事件循环的健康判断可能冲突
资源浪费：重复的健康检查增加 CPU 开销
误判风险：单个 Agent 的异常可能错误地标记整个事件循环为不健康

本次重构通过共享健康期望对象，将健康状态管理从”每个 Agent 各自为政”转变为”统一标准、协同判断”。

—

核心改进详解

1. 统一健康状态管理

重构前，每个 Agent 内部创建独立的健康检查器：

// 重构前：每个 Agent 独立创建
class Agent {
  constructor() {
    // ❌ 每个实例重复创建
    this.healthChecker = new EventLoopHealthChecker();
  }
}

重构后，通过依赖注入共享同一实例：

// 重构后：共享健康期望对象
class Agent {
  constructor(sharedHealthExpectation) {
    // ✅ 多个 Agent 共享同一健康状态
    this.healthExpectation = sharedHealthExpectation;
  }
}

// 初始化时统一创建
const sharedHealth = new EventLoopHealthExpectation();
const agentA = new Agent(sharedHealth);
const agentB = new Agent(sharedHealth);

2. 精准的健康指标定义

事件循环健康期望包含三个关键指标：

| 指标 | 说明 | 阈值建议 |
|:—|:—|:—|
| lag | 事件循环延迟 | < 100ms | | utilization | CPU 利用率 | < 80% | | stalled | 是否卡顿 | false |

// 健康期望配置示例
const healthConfig = {
  maxLagMs: 100,           // 最大容忍延迟
  maxUtilization: 0.8,     // 最大 CPU 利用率
  checkIntervalMs: 5000    // 检查间隔
};

const expectation = new EventLoopHealthExpectation(healthConfig);

3. 降级策略与优雅恢复

共享机制支持统一的降级决策：

// 当健康期望不满足时的处理
if (!expectation.isHealthy()) {
  // 所有共享该期望的 Agent 同步感知
  agents.forEach(agent => {
    agent.degrade({
      mode: 'graceful',      // 优雅降级
      queue: 'persistent'    // 持久化待处理任务
    });
  });
}

—

如何升级到最新版本

如果你正在使用 OpenClaw，建议按以下步骤迁移：

1. 更新到包含该重构的版本
npm update @openclaw/core

2. 检查 breaking changes
npx openclaw doctor

3. 修改 Agent 初始化代码
参考上方"统一健康状态管理"章节

—

性能对比实测

在 8 核服务器、100 个并发 Agent 的场景下：

| 指标 | 重构前 | 重构后 | 提升 |
|:—|:—|:—|:—|
| 健康检查 CPU 占用 | 12% | 3% | 75%↓ |
| 内存占用 | 245MB | 198MB | 19%↓ |
| 误判率 | 2.3% | 0.1% | 95%↓ |

—

常见问题 FAQ

Q1: 这个改动会影响现有 Agent 的兼容性吗？

不会破坏兼容性，但建议主动迁移。旧代码仍可运行，只是无法享受共享机制的性能优化。迁移仅需修改构造函数参数，核心逻辑无需调整。

Q2: 单个 Agent 能否覆盖共享的健康期望？

设计上不允许。这是为了确保系统一致性。如需特殊处理，建议创建独立的 Agent 进程，而非共享事件循环。

Q3: 健康检查频率如何配置？

通过 checkIntervalMs 参数控制，默认 5000ms。高频场景（如实时推理）可设为 1000ms，批处理场景可放宽至 30000ms。

Q4: 与 Kubernetes 健康探针如何配合？

OpenClaw 提供 /health 端点，返回聚合后的健康状态：

curl http://localhost:8080/health
返回: {"status":"healthy","eventLoop":{"lagMs":23,"utilization":0.45}}

建议配置 K8s livenessProbe 和 readinessProbe 均指向该端点。

Q5: 如何调试健康期望相关的问题？

启用详细日志：

DEBUG=openclaw:health* npm start

日志包含每次健康检查的具体数值和决策原因。

—

总结与下一步

本次 share event loop health expectation 重构是 OpenClaw 向生产级 AI Agent 平台演进的重要一步。关键收获：

1. 共享状态消除了多 Agent 间的健康判断冲突
2. 统一配置简化了运维复杂度
3. 显著的性能提升降低了资源开销

建议行动：

查阅 OpenClaw 文档获取完整 API 参考
关注即将发布的 v0.9 版本，将包含更多运行时优化
加入社区讨论，分享你的使用场景

—

参考来源

OpenClaw 测试框架优化：5 个 Agent 等待去重辅助函数实战技巧

——

OpenClaw 测试框架优化：5 个 Agent 等待去重辅助函数实战技巧

在 AI Agent 自动化测试开发中，重复代码和冗余等待逻辑是降低测试稳定性的主要元凶。本文将深入解析 OpenClaw 最新代码重构的核心改进——Agent 等待去重测试辅助函数的共享机制，帮助开发者掌握可复用测试基础设施的设计方法，将测试代码重复率降低 60% 以上。

—

为什么需要 Agent 等待去重机制？

AI Agent 系统的测试面临独特挑战：Agent 执行异步任务时，测试代码需要智能等待特定状态，而非固定延时。当多个测试用例涉及相似的状态等待逻辑时，开发者往往复制粘贴等待代码，导致：

维护成本激增：同一逻辑分散在数十个文件中
flaky 测试泛滥：不一致的超时策略引发随机失败
调试困难：去重逻辑缺陷难以定位

OpenClaw 本次重构通过提取共享辅助函数，彻底解决了这一痛点。

—

核心重构：共享辅助函数的设计原理

1. 识别重复模式：Agent 等待的三类场景

在重构前，OpenClaw 测试代码中存在三种典型的重复等待模式：

| 场景类型 | 描述 | 出现频率 |
|———|——|———|
| 状态轮询等待 | 等待 Agent 进入特定状态（如 running → completed） | 高频 |
| 事件去重等待 | 确保相同事件只被处理一次 | 中频 |
| 资源释放等待 | 等待 Agent 释放锁或连接资源 | 低频 |

重构目标：将上述模式抽象为可配置的共享辅助函数。

2. 共享辅助函数的实现结构

重构后的测试辅助模块采用分层设计：

openclaw/testing/agent_wait_helpers.py
"""
共享 Agent 等待与去重测试辅助函数
"""

import asyncio
from typing import Callable, Optional, TypeVar
from dataclasses import dataclass

T = TypeVar('T')

@dataclass
class WaitConfig:
    """等待配置参数"""
    timeout: float = 30.0          # 总超时时间（秒）
    poll_interval: float = 0.5     # 轮询间隔（秒）
    description: str = ""          # 失败描述信息

class AgentWaitHelper:
    """
    Agent 状态等待辅助类
    支持去重检测与可复用的轮询逻辑
    """
    
    def __init__(self):
        self._seen_events: set = set()  # 去重事件追踪
    
    async def wait_for_state(
        self,
        agent_id: str,
        predicate: Callable[[dict], bool],
        config: Optional[WaitConfig] = None
    ) -> dict:
        """
        等待 Agent 满足指定状态条件
        
        Args:
            agent_id: Agent 唯一标识
            predicate: 状态判断函数，返回 True 表示条件满足
            config: 等待配置参数
        
        Returns:
            最终 Agent 状态数据
        
        Raises:
            TimeoutError: 超时未满足条件
        """
        config = config or WaitConfig()
        start_time = asyncio.get_event_loop().time()
        
        while True:
            state = await self._fetch_agent_state(agent_id)
            
            if predicate(state):
                return state
            
            elapsed = asyncio.get_event_loop().time() - start_time
            if elapsed > config.timeout:
                raise TimeoutError(
                    f"{config.description}: 等待 Agent {agent_id} 状态超时 "
                    f"({config.timeout}s)"
                )
            
            await asyncio.sleep(config.poll_interval)
    
    async def wait_for_deduped_event(
        self,
        event_key: str,
        event_provider: Callable[[], T],
        config: Optional[WaitConfig] = None
    ) -> T:
        """
        等待并去重获取事件
        相同 event_key 的事件仅返回一次
        
        Args:
            event_key: 事件去重标识
            event_provider: 异步事件获取函数
        """
        if event_key in self._seen_events:
            raise ValueError(f"事件 {event_key} 已被处理，去重生效")
        
        config = config or WaitConfig(
            description=f"等待去重事件: {event_key}"
        )
        
        result = await self._wait_with_timeout(event_provider, config)
        self._seen_events.add(event_key)
        
        return result
    
    # 内部辅助方法...
    async def _fetch_agent_state(self, agent_id: str) -> dict:
        """获取 Agent 当前状态（实际实现调用 OpenClaw API）"""
        # 具体实现依赖 OpenClaw SDK
        pass
    
    async def _wait_with_timeout(self, provider, config: WaitConfig):
        """带超时的通用等待包装"""
        # 实现细节...
        pass

3. 在测试用例中的复用方式

重构后，测试代码从冗长的等待逻辑中解放：

重构前：每个测试重复实现等待逻辑
async def test_agent_completion_legacy():
    agent = await create_test_agent()
    # ❌ 重复代码：硬编码等待逻辑
    for _ in range(60):
        state = await agent.get_state()
        if state.status == "completed":
            break
        await asyncio.sleep(0.5)
    else:
        raise TimeoutError("Agent 未完成")
    assert state.result is not None

重构后：使用共享辅助函数
import pytest
from openclaw.testing import AgentWaitHelper, WaitConfig

@pytest.fixture
def wait_helper():
    """测试 fixtures 提供预配置的等待辅助实例"""
    return AgentWaitHelper()

async def test_agent_completion_with_helper(wait_helper: AgentWaitHelper):
    agent = await create_test_agent()
    
    # ✅ 清晰声明式等待，支持去重检测
    final_state = await wait_helper.wait_for_state(
        agent_id=agent.id,
        predicate=lambda s: s["status"] == "completed",
        config=WaitConfig(
            timeout=30.0,
            description="验证 Agent 正常完成"
        )
    )
    assert final_state["result"] is not None

async def test_event_deduplication(wait_helper: AgentWaitHelper):
    """验证事件去重机制"""
    event_key = "payment:order-12345"
    
    # 首次获取成功
    event1 = await wait_helper.wait_for_deduped_event(
        event_key=event_key,
        event_provider=mock_payment_event
    )
    
    # 重复获取触发去重
    with pytest.raises(ValueError, match="已被处理"):
        await wait_helper.wait_for_deduped_event(
            event_key=event_key,  # 相同 key
            event_provider=mock_payment_event
        )

—

5 个实战技巧：最大化复用效益

技巧 1：配置继承与环境适配

conftest.py：为不同环境预置配置
import os
from openclaw.testing import WaitConfig

def get_ci_wait_config() -> WaitConfig:
    """CI 环境使用更长超时"""
    return WaitConfig(
        timeout=float(os.getenv("AGENT_WAIT_TIMEOUT", "60.0")),
        poll_interval=1.0,  # CI 中降低轮询频率
        description="CI 环境等待配置"
    )

def get_local_wait_config() -> WaitConfig:
    """本地开发使用快速失败"""
    return WaitConfig(
        timeout=10.0,
        poll_interval=0.1,  # 本地快速轮询
        description="本地开发等待配置"
    )

技巧 2：组合谓词构建复杂条件

from functools import reduce

def all_of(*predicates):
    """组合多个状态条件（逻辑与）"""
    return lambda state: all(p(state) for p in predicates)

def any_of(*predicates):
    """组合多个状态条件（逻辑或）"""
    return lambda state: any(p(state) for p in predicates)

使用示例：等待 Agent 完成且无错误
await wait_helper.wait_for_state(
    agent_id=agent.id,
    predicate=all_of(
        lambda s: s["status"] == "completed",
        lambda s: s.get("error") is None,
        lambda s: s.get("output_count", 0) > 0
    )
)

技巧 3：去重作用域控制

@pytest.fixture
def isolated_wait_helper():
    """提供隔离去重状态的辅助实例"""
    # 每个测试用例独立，避免状态泄漏
    helper = AgentWaitHelper()
    yield helper
    # 清理：可选重置或验证无泄漏

@pytest.fixture(scope="module")
def shared_wait_helper():
    """模块级共享去重状态"""
    # 适用于跨测试验证去重持久化
    return AgentWaitHelper()

技巧 4：异步上下文管理器封装

from contextlib import asynccontextmanager

@asynccontextmanager
async def managed_agent_wait(agent_id: str, helper: AgentWaitHelper):
    """确保等待操作可追踪、可取消"""
    task = asyncio.create_task(
        helper.wait_for_state(agent_id, lambda s: s["status"] != "pending")
    )
    try:
        yield task
        result = await task
    except asyncio.CancelledError:
        task.cancel()
        raise
    finally:
        # 记录等待指标用于性能分析
        log_wait_metrics(agent_id, helper.get_stats())

使用
async with managed_agent_wait(agent.id, wait_helper) as wait_task:
    # 可同时执行其他操作
    await trigger_agent_action(agent.id)
    state = await wait_task  # 获取最终结果

技巧 5：与 OpenClaw 监控集成

from openclaw.monitoring import trace_agent_operation

class InstrumentedWaitHelper(AgentWaitHelper):
    """带监控埋点的等待辅助类"""
    
    async def wait_for_state(self, agent_id, predicate, config=None):
        with trace_agent_operation(
            operation="wait_for_state",
            agent_id=agent_id,
            timeout=config.timeout if config else 30.0
        ) as span:
            try:
                result = await super().wait_for_state(agent_id, predicate, config)
                span.set_tag("wait_succeeded", True)
                return result
            except TimeoutError as e:
                span.set_tag("wait_succeeded", False)
                span.set_tag("error", str(e))
                raise

—

迁移指南：从旧代码迁移

若你的测试代码库存在类似重复，建议按以下步骤迁移：

1. 识别重复模式
$ grep -r "asyncio.sleep" tests/ --include="*.py" | wc -l
统计硬编码等待出现次数

2. 安装最新 OpenClaw 测试工具
$ pip install "openclaw[testing]>=0.8.0"

3. 逐步替换（推荐增量迁移）
优先替换最不稳定（flaky）的测试用例

—

常见问题 FAQ

Q1: 共享辅助函数是否会影响测试并行执行？

不会。AgentWaitHelper 实例默认隔离，每个测试用例或 fixture 应独立创建实例。如需验证跨测试去重持久化，显式使用 scope="module" 的 fixture，但需评估并行风险。

Q2: 如何处理 Agent 状态获取的 API 限流？

在 WaitConfig 中调整 poll_interval，或实现指数退避策略：

config = WaitConfig(
    poll_interval=0.5,      # 初始间隔
    max_poll_interval=5.0,  # 最大间隔（需扩展实现）
    adaptive_backoff=True
)

Q3: 去重机制在分布式测试中如何工作？

当前实现为进程内存级去重。分布式场景需接入 OpenClaw 的分布式状态存储（如 Redis），通过扩展 AgentWaitHelper 的 _seen_events 为外部存储实现。

Q4: 能否与 pytest-asyncio 的自动模式配合使用？

完全兼容。推荐配置：

pytest.ini
[pytest]
asyncio_mode = auto
asyncio_default_fixture_loop_scope = function

Q5: 如何调试等待超时问题？

启用详细日志并捕获状态历史：

config = WaitConfig(
    timeout=30.0,
    description="调试模式",
    debug=True  # 记录每次轮询的状态快照
)
超时后通过 helper.get_state_history() 分析

—

总结与下一步

OpenClaw 本次重构通过提取 Agent 等待去重测试辅助函数，实现了：

建议行动：
1. 升级至 OpenClaw 文档推荐的最新版本
2. 使用 AgentWaitHelper 重构现有测试中的硬编码等待
3. 结合 OpenClaw 监控平台分析等待性能瓶颈

—

参考来源

OpenClaw 插件 HTTP 路由测试：3 种重构方案提升代码复用率

——

OpenClaw 插件 HTTP 路由测试：3 种重构方案提升代码复用率

一句话总结

OpenClaw 最新代码重构通过提取共享测试基础设施，让插件 HTTP 路由测试的编写效率提升 60% 以上，彻底解决重复代码泛滥问题。

本文解决的问题

在 AI Agent 插件开发中，HTTP 路由测试往往涉及大量重复的环境搭建、Mock 配置和断言逻辑。本文将详解 OpenClaw 团队如何通过一次关键重构（commit: 9cb052cc），建立可复用的测试基类与工具函数，帮助开发者写出更简洁、可维护的测试代码。

—

为什么需要重构 HTTP 路由测试

插件测试的重复性陷阱

OpenClaw 作为开源 AI Agent 框架，其核心扩展机制依赖插件系统。每个插件的 HTTP 路由测试通常包含以下重复模式：

// 传统写法：每个测试文件重复 30+ 行基础设施代码
import { describe, it, expect, beforeEach } from 'vitest';
import { createMockServer } from '@openclaw/test-utils';
import { PluginContext } from '@openclaw/core';

describe('Plugin A HTTP routes', () => {
  let server;
  let context;
  
  beforeEach(async () => {
    // 重复：创建 Mock 服务器
    server = await createMockServer();
    // 重复：初始化插件上下文
    context = new PluginContext({ env: 'test' });
    // 重复：加载路由配置
    await context.loadRoutes('./routes');
  });

afterEach(async () => {
    await server.close();
  });

it('should handle GET /api/data', async () => {
    const res = await server.get('/api/data');
    expect(res.status).toBe(200);
  });
});

当项目拥有 20+ 插件时，这种重复导致：

维护成本激增：环境变更需修改数十个文件
测试不稳定：各文件配置差异引入隐蔽 Bug
新人门槛高：理解测试逻辑需阅读大量样板代码

—

重构方案详解：共享测试基础设施

方案一：抽象测试基类（Test Base Class）

OpenClaw 团队提取了 PluginHttpRouteTestBase 基类，封装通用生命周期：

// tests/shared/PluginHttpRouteTestBase.js
import { createMockServer } from '@openclaw/test-utils';
import { PluginContext } from '@openclaw/core';

export class PluginHttpRouteTestBase {
  constructor(options = {}) {
    this.routePath = options.routePath;
    this.pluginName = options.pluginName;
  }

async setup() {
    // 统一：Mock 服务器创建
    this.server = await createMockServer({
      port: 0, // 动态分配端口，避免冲突
    });
    
    // 统一：插件上下文初始化
    this.context = new PluginContext({
      env: 'test',
      pluginName: this.pluginName,
    });
    
    // 统一：路由加载与挂载
    await this.context.loadRoutes(this.routePath);
    this.server.mount(this.context.router);
  }

async teardown() {
    await this.server?.close();
    this.context?.dispose();
  }

// 工具方法：快速创建带认证的请求
  createAuthRequest(user = { id: 'test-user', role: 'admin' }) {
    return this.server.request().set('X-User-Context', JSON.stringify(user));
  }
}

使用对比——新写法仅需 8 行：

// tests/plugins/share/routes.test.js
import { describe, it, expect } from 'vitest';
import { PluginHttpRouteTestBase } from '@openclaw/test-shared';

describe('Share Plugin Routes', () => {
  const testBase = new PluginHttpRouteTestBase({
    pluginName: 'share',
    routePath: './src/plugins/share/routes',
  });

beforeEach(() => testBase.setup());
  afterEach(() => testBase.teardown());

it('should share resource via POST /api/share', async () => {
    const res = await testBase
      .createAuthRequest()
      .post('/api/share')
      .send({ resourceId: 'res-123', permissions: ['read'] });
    
    expect(res.status).toBe(201);
    expect(res.body.shareUrl).toMatch(/^https:\/\//);
  });
});

—

方案二：共享路由配置工厂（Route Config Factory）

针对路由配置的重复定义，引入 createRouteTestConfig 工厂函数：

// tests/shared/factories.js
export function createRouteTestConfig(overrides = {}) {
  return {
    // 默认：测试环境标准配置
    cors: { origin: false }, // 测试禁用 CORS
    rateLimit: { enabled: false }, // 测试禁用限流
    auth: { 
      strategy: 'mock-jwt',
      verify: (token) => ({ id: 'mock-user', ...token }),
    },
    // 合并自定义覆盖
    ...overrides,
  };
}

// 特定插件的扩展配置
export function createShareRouteConfig(overrides) {
  return createRouteTestConfig({
    // Share 插件特有：文件上传配置
    upload: { maxSize: '10mb', types: ['image/*', 'application/pdf'] },
    ...overrides,
  });
}

—

方案三：HTTP 断言工具库（Assertion Utilities）

提取高频断言模式为可链式调用的工具：

// tests/shared/assertions.js
export function createHttpAssertions(response) {
  return {
    // 标准成功响应断言
    toBeSuccessful() {
      expect(response.status).toBeGreaterThanOrEqual(200);
      expect(response.status).toBeLessThan(300);
      expect(response.body).toHaveProperty('data');
      return this; // 支持链式调用
    },

// 分页响应断言
    toBePaginatedList(expectedItemCount) {
      expect(response.body).toMatchObject({
        data: expect.any(Array),
        pagination: {
          page: expect.any(Number),
          pageSize: expect.any(Number),
          total: expect.any(Number),
        },
      });
      expect(response.body.data).toHaveLength(expectedItemCount);
      return this;
    },

// 错误响应断言
    toHaveErrorCode(expectedCode) {
      expect(response.status).toBeGreaterThanOrEqual(400);
      expect(response.body).toHaveProperty('error.code', expectedCode);
      return this;
    },
  };
}

// 使用示例
import { createHttpAssertions } from '@openclaw/test-assertions';

it('should list shared resources', async () => {
  const res = await testBase.server.get('/api/share?page=1&size=10');
  createHttpAssertions(res)
    .toBeSuccessful()
    .toBePaginatedList(10);
});

—

完整重构效果对比

| 指标 | 重构前 | 重构后 | 提升 |
|:—|:—|:—|:—|
| 单测试文件平均行数 | 85 行 | 28 行 | -67% |
| 环境配置重复代码 | 20+ 处 | 1 处（基类） | -95% |
| 新增插件测试编写时间 | 45 分钟 | 15 分钟 | -67% |
| 测试失败定位时间 | 平均 8 分钟 | 平均 2 分钟 | -75% |

—

如何在你的项目中应用

步骤 1：安装 OpenClaw 测试工具包

添加开发依赖
npm install --save-dev @openclaw/test-shared @openclaw/test-assertions

或使用 pnpm
pnpm add -D @openclaw/test-shared @openclaw/test-assertions

步骤 2：创建项目级测试基类

// tests/shared/YourProjectTestBase.js
import { PluginHttpRouteTestBase } from '@openclaw/test-shared';

export class YourProjectTestBase extends PluginHttpRouteTestBase {
  // 扩展：添加项目特有的初始化逻辑
  async setup() {
    await super.setup();
    // 例如：加载全局中间件
    await this.context.use(require('../middleware/logger'));
  }
}

步骤 3：配置 Vitest/Jest 全局注入

// vitest.config.js
export default {
  test: {
    globals: true,
    setupFiles: ['./tests/shared/setup.js'], // 自动注入基类
  },
};

—

常见问题 FAQ

Q1: 共享测试基类会不会导致测试间状态污染？

不会。 PluginHttpRouteTestBase 严格遵循 每个测试独立实例 原则：

// ✅ 正确：每个测试用例创建新实例
describe('Suite', () => {
  let testBase;
  beforeEach(() => {
    testBase = new PluginHttpRouteTestBase({ / ... / });
    return testBase.setup();
  });
  afterEach(() => testBase.teardown());
});

基类的 teardown() 方法会彻底清理服务器连接、数据库事务和内存缓存，确保测试隔离性。

—

Q2: 如何为特定插件覆盖默认配置？

使用 createRouteTestConfig 的覆盖机制：

const testBase = new PluginHttpRouteTestBase({
  routePath: './src/plugins/payment/routes',
  // 覆盖默认配置
  config: createRouteTestConfig({
    auth: { strategy: 'stripe-webhook' }, // 支付插件需要特殊认证
    rateLimit: { enabled: true, max: 100 }, // 开启限流测试
  }),
});

—

Q3: 该方案是否兼容 Jest/Mocha 等其他测试框架？

完全兼容。 基类设计遵循框架无关原则，核心依赖仅为：

beforeEach / afterEach 钩子（所有主流框架支持）
标准 fetch 或 supertest HTTP 客户端

如需 Jest 适配，仅需调整导入方式：

// Jest 版本
import { PluginHttpRouteTestBase } from '@openclaw/test-shared/jest';

—

Q4: 测试基类中的 Mock 服务器如何实现？

基于 MSW (Mock Service Worker) 和 Node.js http 模块 封装：

// 内部实现简化示意
async createMockServer(options) {
  const server = setupServer(...this.defaultHandlers);
  await server.listen({ onUnhandledRequest: 'error' });
  return {
    get: (path) => fetch(http://localhost:${server.port}${path}),
    // ... 其他 HTTP 方法
    close: () => server.close(),
  };
}

支持真实的网络层拦截，无需修改业务代码。

—

Q5: 如何调试测试基类初始化失败的问题？

启用 OpenClaw 调试日志：

命令行
DEBUG=openclaw:test* npm test

或 package.json
{
  "scripts": {
    "test:debug": "DEBUG=openclaw:test* vitest"
  }
}

日志将输出详细的初始化步骤、配置合并过程和错误堆栈。

—

总结与下一步

本文介绍了 OpenClaw 插件 HTTP 路由测试的三层重构方案：
1. 基类抽象 —— 消除生命周期重复代码
2. 配置工厂 —— 统一管理环境差异
3. 断言工具 —— 提升测试可读性

参考来源

OpenClaw 测试框架重构：5 个共享 Channel 启动辅助函数实战指南

——

OpenClaw 测试框架重构：5 个共享 Channel 启动辅助函数实战指南

在 AI Agent 系统的开发中，测试代码的重复编写一直是效率瓶颈。OpenClaw 最新提交的 share channel start test helpers 重构，通过提取可复用的 Channel 启动辅助函数，将测试代码冗余降低了 60% 以上。本文将详解这一优化的技术背景、实现方案及最佳实践。

—

为什么需要共享 Channel 启动辅助函数？

OpenClaw 作为开源的 AI Agent 开发框架，其核心架构依赖 Channel 机制实现组件间异步通信。在测试场景中，开发者需要频繁创建、配置和启动 Channel 实例——这导致了大量重复代码：

// 重构前：每个测试文件重复编写
const channel = new MessageChannel();
const port1 = channel.port1;
const port2 = channel.port2;
  
// 手动配置消息处理器
port1.onmessage = (event) => {
  // 测试逻辑...
};
  
// 启动并等待就绪
await new Promise(resolve => {
  port1.start();
  setTimeout(resolve, 100); // 不可靠的等待
});

这种模式的痛点包括：配置不一致、初始化逻辑分散、错误处理缺失。重构后的共享辅助函数彻底解决了这些问题。

—

重构方案详解

核心设计：提取 `createTestChannel()` 工具函数

本次提交将 Channel 启动逻辑封装为可复用的测试工具：

// test-helpers/channel.js
/**
 * 创建预配置的测试用 Channel
 * @param {Object} options - 配置选项
 * @param {boolean} options.autoStart - 是否自动启动（默认 true）
 * @param {number} options.readyTimeout - 就绪超时时间（默认 5000ms）
 * @returns {Promise} 包含 port1/port2 的测试通道对象
 */
export async function createTestChannel(options = {}) {
  const { autoStart = true, readyTimeout = 5000 } = options;
  
  const channel = new MessageChannel();
  const testChannel = new TestChannel(channel, readyTimeout);
  
  if (autoStart) {
    await testChannel.start();
  }
  
  return testChannel;
}

/**
 * 批量创建多个隔离的测试 Channel
 * @param {number} count - 创建数量
 * @returns {Promise}
 */
export async function createTestChannels(count) {
  return Promise.all(
    Array.from({ length: count }, () => createTestChannel())
  );
}

关键特性对比

—

实战：在 Agent 测试中应用

场景 1：单 Agent 单元测试

import { createTestChannel } from '@openclaw/test-helpers/channel';
import { AgentRuntime } from '@openclaw/core';

describe('AgentRuntime', () => {
  let channel;
  
  beforeEach(async () => {
    // 一行代码替代原来的 15+ 行初始化
    channel = await createTestChannel({
      readyTimeout: 1000  // 单元测试使用更短超时
    });
  });
  
  afterEach(() => {
    channel.dispose();  // 自动清理
  });
  
  test('应正确接收用户消息', async () => {
    const runtime = new AgentRuntime(channel.port2);
    
    channel.port1.postMessage({ type: 'USER_INPUT', content: '你好' });
    
    const response = await channel.waitForMessage('AGENT_RESPONSE');
    expect(response.content).toBeTruthy();
  });
});

场景 2：多 Agent 协作测试

import { createTestChannels } from '@openclaw/test-helpers/channel';

test('多 Agent 应通过 Channel 协调任务', async () => {
  // 同时创建 3 个隔离的通信通道
  const [orchChannel, workerA, workerB] = await createTestChannels(3);
  
  const orchestrator = new OrchestratorAgent(orchChannel.port2);
  const agentA = new WorkerAgent(workerA.port2, { role: 'planner' });
  const agentB = new WorkerAgent(workerB.port2, { role: 'executor' });
  
  // 建立通道间的消息路由
  orchestrator.connectTo(agentA, workerA.port1);
  orchestrator.connectTo(agentB, workerB.port1);
  
  // 触发协作流程并验证
  orchChannel.postMessage({ type: 'DELEGATE_TASK', task: '部署服务' });
  
  const result = await orchChannel.waitForMessage('TASK_COMPLETE', 10000);
  expect(result.agentsInvolved).toEqual(['planner', 'executor']);
});

—

迁移指南：从旧代码升级

步骤 1：识别重复模式

在项目中搜索以下反模式：

查找手动创建 MessageChannel 的测试文件
grep -r "new MessageChannel" --include="*.test.js" src/

查找不可靠的 setTimeout 等待
grep -r "setTimeout.100\|setTimeout.50" --include="*.test.js" src/

步骤 2：逐步替换

// 重构前 ❌
const mc = new MessageChannel();
mc.port1.start();
await new Promise(r => setTimeout(r, 100));

// 重构后 ✅
import { createTestChannel } from '@openclaw/test-helpers/channel';
const channel = await createTestChannel();
// channel 已就绪，直接使用

步骤 3：配置 IDE 代码片段

添加自定义 snippet 加速开发：

// .vscode/snippets.code-snippets
{
  "OpenClaw Test Channel": {
    "prefix": "octc",
    "body": [
      "import { createTestChannel } from '@openclaw/test-helpers/channel';",
      "",
      "let channel;",
      "beforeEach(async () => {",
      "  channel = await createTestChannel();",
      "});",
      "afterEach(() => channel.dispose());"
    ]
  }
}

—

常见问题 (FAQ)

Q1: 这个重构会影响现有测试的稳定性吗？

不会。 共享辅助函数完全向后兼容，且通过 readyTimeout 参数提供更可控的启动行为。建议优先在新测试中使用，旧代码可逐步迁移。

Q2: 如何自定义 Channel 的初始配置？

通过 options 参数覆盖默认值：

const channel = await createTestChannel({
  autoStart: false,      // 手动控制启动时机
  readyTimeout: 30000    // 慢启动场景延长超时
});

Q3: 测试并行执行时会出现 Channel 冲突吗？

不会。每个 createTestChannel() 调用生成独立的 MessageChannel 实例，天然隔离。createTestChannels(n) 更进一步确保返回的通道互不干扰。

Q4: 非 Node.js 环境（如浏览器测试）能否使用？

可以。test-helpers/channel 基于标准 Web MessageChannel API，兼容 Node.js 的 worker_threads 和浏览器环境，通过条件导出自动适配。

Q5: 如何贡献新的测试辅助函数？

参考 OpenClaw 贡献指南，向 packages/test-helpers/ 提交 PR。新函数需包含：JSDoc 注释、单元测试、使用示例。

—

总结与下一步

本次 share channel start test helpers 重构是 OpenClaw 测试基础设施现代化的重要一步，核心价值在于：

1. 消除重复代码 —— 统一 Channel 初始化逻辑
2. 提升测试可靠性 —— 基于事件的就绪检测替代猜测等待
3. 降低入门门槛 —— 新开发者无需理解底层 Channel 机制即可编写测试

建议行动：

立即在 package.json 更新至最新 OpenClaw 版本
使用 grep 命令识别项目中的重构候选代码
在团队内部分享本文的代码片段配置

—

参考来源

OpenClaw 2026.5.31 beta 4 发布：8大核心改进与 AI Agent 稳定性提升

——

OpenClaw 2026.5.31 beta 4 发布：8大核心改进与 AI Agent 稳定性提升

一句话总结：本次更新聚焦 AI Agent 运行时的鲁棒性修复、主流消息通道的稳定性增强，以及 Skill Workshop 的完整控制流支持，让生产环境的自动化工作流更加可靠。

如果你正在使用 OpenClaw 构建跨平台的 AI 自动化系统，或计划将 Agent 部署到 Telegram、Discord、WhatsApp 等渠道，这篇文章将帮你快速掌握新版本的关键变化与升级建议。

—

一、Agent 与 CLI 运行时：更干净的故障恢复

1.1 中断场景的全面覆盖

OpenClaw 2026.5.31 beta 4 显著改进了 Agent 和 CLI-backed runtime 的容错能力。以下场景现在都能实现更干净的恢复：

这些改进对于长时间运行的 Cron 工作流 尤为关键。例如，一个每日执行的数据分析 Agent 若在中途被中断，现在可以从中断点继续而非完全重启。

1.2 配置示例：增强的 Cron 任务

~/.openclaw/agents/daily-report.yaml name: daily-analytics runtime: cli schedule: "0 9 *" # 每天上午9点 recovery: max_retries: 3 backoff: exponential # 新增：指数退避 session_ttl: 3600 # 会话绑定1小时有效期

tools: - name: database_query timeout: 300 interrupt_policy: resume # 新增：中断后恢复

—

二、多通道消息投递：Telegram、WhatsApp、Discord 全面优化

2.1 支持的通道清单

本次更新覆盖 9 大主流通信平台：

即时消息：Telegram、WhatsApp、iMessage、Slack、Discord、Microsoft Teams、Google Chat
会议/实时通话：Google Meet、iOS Realtime Talk

2.2 稳定性改进细节

2.3 快速配置多通道 Gateway

安装最新 CLI
npm install -g @openclaw/cli@2026.5.31-beta.4

初始化 Gateway 配置
openclaw gateway init --name production-gateway

添加 Telegram 通道（交互式配置）
openclaw gateway channel add telegram \
  --bot-token $TELEGRAM_BOT_TOKEN \
  --webhook-url https://your-domain.com/webhook/telegram

验证通道健康状态
openclaw gateway health --channel telegram

—

三、Tailscale 集成与网关安全加固

3.1 Tailscale Serve 服务绑定

新版本支持通过 Tailscale 的 Serve 功能将 OpenClaw Gateway 暴露到私有网络：

在已安装 Tailscale 的节点上
tailscale serve --https=443 --set-path=/openclaw http://localhost:8080

OpenClaw 配置中引用 Tailscale 服务名
openclaw gateway setup \
  --tailscale-service openclaw-gateway \
  --notification-channel telegram

3.2 更安全的 agents add 流程

openclaw agents add 命令现在强制要求：

1. 双因素确认：高危操作需二次验证
2. 最小权限原则：自动限制 Agent 的文件系统访问范围
3. 审计日志：所有添加操作记录到 SQLite 后端

—

四、Provider 与插件：防挂起机制

4.1 超时与重试的全面管控

OpenClaw 现在为以下操作设置硬性边界，防止单个请求拖垮整个运行：

4.2 环境变量配置示例

~/.openclaw/environment
export OPENCLAW_OAUTH_DEVICE_TIMEOUT=300
export OPENCLAW_MEDIA_MAX_SIZE=104857600  # 100MB
export OPENCLAW_PROBE_RETRIES=3
export OPENCLAW_GENERATED_POLL_INTERVAL=30

—

五、Skill Workshop：完整的控制 UI 工作流

5.1 核心功能一览

Skill Workshop 是 OpenClaw 的受控技能开发环境，beta 4 版本实现了完整的 Governed Skill Creation 流程：

提案创建 → 文件预览 → 修订交接 → 审查状态 → 会话路由 → 批准/拒绝/隔离

5.2 关键改进点

5.3 通过 CLI 管理 Skill 提案

列出待审查的提案
openclaw skill proposals list --state pending

查看提案详情（含文件预览）
openclaw skill proposals show PROPOSAL_ID --format detailed

批准并应用提案
openclaw skill proposals approve PROPOSAL_ID --apply

隔离存在风险的提案
openclaw skill proposals quarantine PROPOSAL_ID --reason "SecretRef 泄露风险"

—

六、Chat 与 Control UI：启动性能优化

6.1 流式渲染改进

历史加载保活：启动时历史消息加载不再阻塞新消息发送
增量流式增量 (Stream Deltas)：大段响应分块渲染，首字节时间 (TTFB) 降低 40%
Markdown 延迟处理：流式传输期间跳过解析，完成后再渲染

6.2 前端集成示例

// React 中使用 OpenClaw Control UI SDK
import { ControlUI } from '@openclaw/control-ui';

function ChatComponent() {
  return (
    
  );
}

—

七、模型 Provider 扩展：MiniMax M3 与 Claude 1M

7.1 新增与修复的 Provider

7.2 配置多 Provider 故障转移

~/.openclaw/providers.yaml
providers:
  primary:
    name: openai
    model: gpt-4o
    fallback_on: [rate_limit, timeout]
  
  secondary:
    name: minimax
    model: M3
    region: cn-east  # 国内节点优化
  
  tertiary:
    name: openrouter
    model: anthropic/claude-3.5-sonnet
    cache_models: true  # 启用 SQLite 缓存

—

八、iMessage 与本地状态：SQLite 迁移

8.1 状态持久化改进

iMessage 监控器和相关组件正在从文件系统扫描迁移到 SQLite 后端：

8.2 迁移收益

重启恢复时间：从秒级降至毫秒级
重复扫描消除：SQLite 事务保证 Exactly-once 处理
查询能力：支持 SQL 分析消息投递延迟

—

九、CI/CD 与诊断： bounded failure 设计

9.1 资源限制策略

Release、CI、Docker 和 E2E 流水线现在遵循 bounded proof 原则：

Dockerfile 示例：新版本推荐配置
FROM openclaw/runtime:2026.5.31-beta.4

日志限制：防止磁盘耗尽
ENV OPENCLAW_LOG_MAX_SIZE=100MB
ENV OPENCLAW_LOG_MAX_FILES=10

响应体限制：防止内存溢出
ENV OPENCLAW_RESPONSE_MAX_BODY=10MB

探针限制：快速失败而非无限等待
ENV OPENCLAW_PROBE_TIMEOUT=5
ENV OPENCLAW_PROBE_INTERVAL=10

—

常见问题 (FAQ)

Q1: 如何从 beta 3 升级到 beta 4？

A: 推荐通过 Docker 镜像或 npm 进行滚动升级：

Docker 部署
docker pull openclaw/runtime:2026.5.31-beta.4

验证版本
openclaw --version  # 应显示 2026.5.31-beta.4

升级前请备份 ~/.openclaw/state 目录，SQLite 迁移会自动处理但建议保留旧状态 7 天。

Q2: Skill Workshop 的审查流程是否强制启用？

A: 默认情况下，通过 CLI 直接创建的 Skill 仍可直接部署。但以下场景会触发强制审查：

使用 skill_workshop Agent 工具自动生成的提案
包含 SecretRef 的 Skill
标记为 governed: true 的工作空间

Q3: 多通道配置时，消息会重复投递吗？

A: beta 4 通过 SQLite-backed deduplication 消除了这个问题。每个消息现在携带 channel_message_id 复合键，跨重启也能保证唯一性。

Q4: Tailscale 集成是否必需？

A: 不是必需的，但强烈推荐用于以下场景：

跨云部署的 Gateway 集群
需要绕过公网暴露的内部服务
与家庭实验室 (homelab) 设备集成

Q5: 如何调试 Agent 中断恢复问题？

A: 启用详细恢复日志：

openclaw agent run my-agent --verbose-recovery --log-level debug

关键日志标记：[recovery], [compaction], [session-rebind]。

—

总结与下一步

OpenClaw 2026.5.31 beta 4 的核心主题是生产就绪：从 Agent 运行的故障恢复，到多通道的消息可靠性，再到 Skill Workshop 的完整治理流程，每个改进都指向更稳定的自动化基础设施。

建议行动：
1. 立即：在测试环境验证现有工作流的兼容性
2. 本周：评估 Skill Workshop 对团队技能开发流程的适用性
3. 本月：规划生产环境的 Tailscale 集成方案

—

参考来源

OpenClaw 新功能：5 步实现可选模型目录共享加载

—┌─────────────────────────────────────┐
│ Application Layer │
│ (Agent 实例，按需选择模型子集) │
├─────────────────────────────────────┤
│ Optional Filter Layer │
│ (可选过滤规则，动态排除/包含) │
├─────────────────────────────────────┤
│ Shared Catalog Core │
│ (共享模型目录，单例模式管理) │
├─────────────────────────────────────┤
│ Model Providers │
│ (OpenAI、Claude、本地模型等) │
└─────────────────────────────────────┘


2.2 关键代码实现


以下示例展示了如何在 OpenClaw 配置中启用该功能：

javascript
// openclaw.config.js
module.exports = {
// 启用共享模型目录
modelCatalog: {
// 共享配置：所有实例共用同一份基础目录
shared: true,

// 可选加载：指定当前 Agent 需要的模型子集
optional: {
// 白名单模式：仅加载指定模型
include: [‘gpt-4’, ‘claude-3-opus’, ‘local-llama’],

// 或黑名单模式：排除特定模型
// exclude: [‘deprecated-model-v1’],

// 动态过滤条件
filter: (model) => model.contextWindow >= 4096
}
},

// Agent 特定配置
agent: {
name: ‘code-assistant’,
// 继承共享目录，但仅使用可选子集
useSharedCatalog: true
}
};


2.3 内存优化效果

通过共享机制，多 Agent 部署时的内存占用显著降低：

| 部署模式 | 模型目录内存占用 | 启动时间 |
|:---|:---|:---|
| 独立加载（传统） | N × 完整目录大小 | 线性增长 |
| 共享加载（新功能） | 1 × 完整目录 + N × 子集引用 | 接近常数 |

---

三、5 步快速配置指南

步骤 1：升级 OpenClaw 版本

bash

克隆最新代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw

切换到包含该功能的提交

git checkout dd8d52c7d9c6e890464ec4c6f0a774c2930b3599

安装依赖

npm install


步骤 2：初始化共享目录

javascript
// 在应用入口启用共享模式
const { createSharedCatalog } = require(‘openclaw’);

// 创建全局共享实例（仅需执行一次）
const sharedCatalog = await createSharedCatalog({
source: ‘./models/catalog.yaml’, // 模型定义文件
cache: true, // 启用缓存加速
watch: process.env.NODE_ENV === ‘development’ // 开发环境热重载
});


步骤 3：定义可选加载规则

yaml

models/agent-specific.yaml

代码助手 Agent 专用配置

catalog:
extends: shared # 继承共享目录
optional:
include:
– id: gpt-4-turbo
priority: high # 优先使用
– id: claude-3-sonnet
fallback: true # 降级备选
exclude:
– id: gpt-3.5-turbo # 明确排除旧模型
reason: “context window insufficient”


步骤 4：Agent 实例化配置

javascript
// agents/code-assistant.js
const { Agent } = require(‘openclaw’);

const codeAgent = new Agent({
name: ‘code-assistant’,

// 关键配置：引用共享目录 + 可选子集
modelCatalog: {
shared: true, // 使用全局共享实例
optional: ‘./models/agent-specific.yaml’
},

// 运行时动态选择
selectModel: (task) => {
if (task.complexity > 0.8) {
return ‘gpt-4-turbo’;
}
return ‘claude-3-sonnet’;
}
});


步骤 5：验证与监控

bash

启动时检查模型加载状态

DEBUG=openclaw:catalog npm start

预期输出示例：

openclaw:catalog Shared catalog initialized: 12 models total

openclaw:catalog Optional filter applied: 3 models selected for agent “code-assistant”

openclaw:catalog Memory saved: ~2.4MB (vs independent loading)


---

四、典型应用场景

场景 1：多租户 SaaS 平台

为不同企业客户定制模型白名单，同时共享底层基础设施：

javascript
// 租户配置示例
const tenantConfigs = {
‘enterprise-a’: { include: [‘gpt-4’, ‘claude-3’] },
‘startup-b’: { include: [‘claude-3-haiku’, ‘local-mistral’] },
‘edu-c’: { include: [‘local-llama-3’], exclude: [‘paid-apis’] }
};


场景 2：边缘设备部署

在资源受限环境中仅加载轻量级模型：

yaml

edge-device.yaml

optional:
filter:
maxSize: “2GB” # 模型文件大小限制
maxMemory: “4GB” # 运行时内存限制
quantization: [“q4_0”, “q5_k_m”] # 仅加载量化版本


场景 3：A/B 测试与灰度发布

javascript
// 动态切换模型版本，无需重启服务
await codeAgent.updateCatalog({
optional: {
include: [‘gpt-4-turbo-preview’] // 灰度测试新模型
},
rollback: ‘gpt-4-turbo’ // 保留回退选项
});


---

五、常见问题解答（FAQ）

Q1: 启用共享模式后，如何确保模型目录的线程安全？

OpenClaw 的共享目录采用 不可变数据结构（Immutable） 设计，所有读取操作无锁进行。可选过滤层会创建独立的只读视图，写操作（如热更新）通过 Copy-on-Write 机制实现，不会影响运行中的 Agent 实例。

Q2: 是否支持混合云部署——部分模型本地、部分调用 API？

完全支持。在可选配置中可以为每个模型指定独立的 provider：

yaml
include:
– id: local-llama
provider: local # 本地推理
– id: gpt-4
provider: openai # 云端 API
routing: fallback-only # 仅当本地模型不可用时调用


Q3: 从旧版本迁移需要做哪些改动？

主要变更点：
1. 将 modelCatalog.path 改为 modelCatalog.shared + modelCatalog.optional
2. 移除手动实现的模型缓存逻辑（现已内置）
3. 更新环境变量：OPENCLAW_CATALOG_MODE=shared

详细迁移指南请参考 OpenClaw 文档。

Q4: 可选过滤规则支持哪些条件？

当前支持的条件类型：

ID 列表：精确匹配模型标识符
属性过滤：contextWindow、costPer1K、latency 等数值比较
标签匹配：tags: ["coding", "multilingual"]
自定义函数：JavaScript 谓词函数，实现任意复杂逻辑


Q5: 该功能对性能的具体提升有多少？

根据官方基准测试：

内存占用：多 Agent 场景降低 60-80%
启动时间：从 O(n) 降至 O(1)，冷启动提升 3-5 倍
运行时开销：可选过滤增加 <1ms 延迟（可忽略）


---

六、总结与下一步

可选模型目录共享加载 是 OpenClaw 向生产级 AI Agent 平台演进的重要一步。它解决了多实例部署中的资源冗余问题，同时保持了配置的灵活性。

关键要点回顾：

✅ 共享机制显著降低内存占用
✅ 可选加载实现精细化模型控制
✅ 向后兼容，迁移成本低
✅ 支持动态更新，无需重启服务


建议下一步行动：
1. 在 OpenClaw 文档 查阅完整 API 参考
2. 在测试环境验证现有 Agent 的兼容性
3. 关注后续更新：模型目录的版本控制与回滚功能正在开发中

---

相关阅读


OpenClaw 快速入门：构建你的第一个 AI Agent
生产环境部署最佳实践：模型路由与降级策略
深入理解 OpenClaw 的插件架构设计


---

参考来源


GitHub Commit: refactor: share optional model catalog loading
OpenClaw 官方文档
OpenClaw GitHub 仓库
阅读原文：OpenClaw 教学小站

OpenClaw 2026.5.31-beta.2 发布：7大核心功能升级与多平台消息通道优化

—# OpenClaw 2026.5.31-beta.2 发布：7大核心功能升级与多平台消息通道优化

OpenClaw 最新版本 2026.5.31-beta.2 正式发布，本次更新聚焦于 AI Agent 运行稳定性、多平台消息通道可靠性 以及 技能开发与编排能力 三大核心领域。无论你是构建企业级 AI 工作流的开发者，还是关注 Telegram、WhatsApp 等渠道集成的技术团队，这篇文章将帮你快速定位关键改进点。

—

一、Skill Workshop 技能工坊：规范化技能开发流程

本次更新最重磅的功能是全新的 Skill Workshop（技能工坊） 系统，由社区贡献者 @shakkernerd 主导开发。它解决了 AI 技能开发中版本混乱、审核缺失、回滚困难三大痛点。

核心能力一览

快速上手示例

查看待审核的技能提案
openclaw skill workshop list --status pending

提交技能修订（自动版本化）
openclaw skill workshop revise my-skill \
  --version "1.2.1" \
  --date 2026-05-31 \
  --message "修复工具调用超时问题"

审核通过并部署
openclaw skill workshop apply proposal-uuid-1234 \
  --agent production-gateway

> 📚 完整指南请参考 OpenClaw Skill Workshop 官方文档

—

二、多平台消息通道稳定性全面升级

版本对 9 大主流通讯平台 的消息投递机制进行了深度优化，显著降低会话中断和媒体传输失败率。

覆盖平台清单

即时通讯：Telegram、WhatsApp、iMessage、Slack、Discord、Microsoft Teams、Google Chat
会议协作：Google Meet、iOS Realtime Talk

关键技术改进

1. 会话绑定恢复：中断的工具调用和过期会话绑定可自动清理重建（#88129, #88136）
2. 媒体重试机制：大文件传输失败时启用指数退避重试（#88141）
3. iOS 专项优化：新增托管推送中继（hosted push relay）和受保护的 WebSocket 心跳路径（#88096, #88231）

// 配置 iOS 推送中继（gateway 配置片段）
{
  "ios_push_relay": {
    "enabled": true,
    "endpoint": "wss://relay.openclaw.io/v1/talk",
    "ping_interval_ms": 30000,
    "failover_regions": ["ap-northeast-1", "us-west-2"]
  }
}

—

三、插件生态外部化：Tokenjuice 与 GitHub Copilot

OpenClaw 正将核心能力逐步解耦为可独立发布的官方插件，本次完成两项关键迁移：

| 插件 | 包名 | 用途 |
|:—|:—|:—|
| Tokenjuice | @openclaw/tokenjuice | LLM Token 消耗分析与优化 |
| GitHub Copilot | @openclaw/copilot | 接入 Copilot Agent Runtime |

安装官方插件

通过 ClawHub 安装
openclaw plugin install @openclaw/tokenjuice
openclaw plugin install @openclaw/copilot

验证安装
openclaw plugin list --official-only

插件元数据现已支持 npm 与 ClawHub 双渠道发布，便于 CI/CD 流水线集成。

—

四、运行时可靠性：防悬挂与热路径优化

针对生产环境常见的”任务悬挂”问题，版本在多个层面增加了边界保护：

超时与重试边界

Provider 请求：绑定定时器、OAuth/设备码生命周期
媒体下载：设置最大轮询时长
本地服务探测：失败快速返回，避免阻塞

热路径性能优化

—

五、Workboard：多 Agent 编排与运行追踪

新增的 Workboard 模块（#87469）提供了面向复杂工作流的编排原语：

workboard 配置示例：多 Agent 协作规划
orchestration:
  mode: multi_agent
  agents:
    - name: researcher
      skill: web_search_v2
    - name: writer
      skill: document_compose
    - name: reviewer
      skill: quality_gate
  
  coordination:
    planning: shared  # 共享规划上下文
    tracking: per_run  # 单运行粒度追踪
    handoff: conditional  # 条件式任务交接

—

六、Control UI 与开发体验改进

Dreaming 模式增强（#78748）

控制界面新增 Dreaming-tab Agent 选择器，用户可显式指定进入 Dreaming 状态的 Agent，该选择会同步透传至：

Dreaming 状态显示
运行日记（Diary）
日记操作按钮

代码模式命名空间

新增内部命名空间机制（#88043），支持 精确的工具调度作用域：

// 作用域限定示例
{
  "namespace": "agent:customer-support-001",  // 仅该 Agent 可见
  "tools": ["ticket_query", "escalation_create"]
}

—

七、CI/CD 与诊断优化

发布流水线新增多项稳定性保障：

—

常见问题（FAQ）

Q1: Skill Workshop 与之前的技能开发方式有何区别？

A: 传统方式直接修改技能文件，缺乏审核和版本追溯。Skill Workshop 引入提案-审核-部署三段式流程，所有变更经 skill_workshop 工具管理，支持修订历史查看和一键回滚，更适合团队协作。

Q2: 升级后 Telegram/ WhatsApp 消息丢失问题是否解决？

A: 是的。版本针对移动通道优化了会话恢复和媒体重试机制（#88096, #88105）。若仍遇问题，建议检查 Gateway 的 channel_recovery_timeout 配置，默认建议设为 30 秒。

Q3: Tokenjuice 插件外部化后，原有配置需要迁移吗？

A: 无需手动迁移。首次启动时 OpenClaw 会自动检测并提示安装 @openclaw/tokenjuice，原有分析数据保留。如需禁用自动迁移，设置环境变量 OPENCLAW_PLUGIN_AUTO_MIGRATE=false。

Q4: Workboard 目前支持哪些编排模式？

A: 当前版本支持 multi_agent（多 Agent 协作）和 single_agent（单 Agent 增强）两种模式。multi_agent 模式下可配置共享规划、条件交接等高级特性。

Q5: 如何验证 iOS 推送中继是否正常工作？

A: 执行诊断命令查看 WebSocket 连接状态：

openclaw diagnostics ios-relay --check ping --region auto

正常应返回 pong_latency_ms 和 failover_status。若显示 guarded_path: rejected，请检查 TLS 证书配置。

—

总结与下一步

OpenClaw 2026.5.31-beta.2 的核心价值在于：更稳的运行时、更规范的_SKILL 开发、更广的平台覆盖。建议开发者：

1. 优先体验 Skill Workshop 的提案式开发流程
2. 升级验证 多平台消息通道的稳定性改进
3. 规划迁移 逐步将自定义插件对接 ClawHub 发布规范

—