OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

发表评论

OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

OpenClaw 2026.3.31-beta.1 是一次重大安全更新，包含6个破坏性变更和多项功能增强，显著提升了系统的安全性和可靠性。

本文将详细解析这些变更的影响，并提供完整的迁移指南，帮助你顺利升级。

目录

破坏性变更（Breaking Changes）

1. 节点执行方式重构 ⚠️

变更内容：移除了 nodes.run shell 包装器，节点 shell 执行现在统一通过 exec host=node。

#### 影响

  • 之前使用 nodes.run 执行 shell 命令的脚本需要修改
  • 节点特定功能保留在 nodes invoke 和专用媒体/位置/通知操作中

#### 迁移方案

旧方式（已弃用）

nodes.run "ls -la"



新方式

exec host=node ls -la

#### 何时使用哪个命令？

  • exec host=node — 在节点上执行 shell 命令
  • nodes invoke — 调用节点特定功能（相机、位置、通知）

—

2. 插件 SDK 弃用警告 ⚠️

变更内容：弃用旧版提供程序兼容子路径和旧版捆绑提供程序设置。

#### 影响

  • 使用旧版 SDK 路径的插件将看到迁移警告
  • 未来主要版本将完全移除这些兼容层

#### 迁移方案

// 旧方式（已弃用）
import { ... } from 'openclaw/legacy-compat';



// 新方式
import { ... } from 'openclaw/plugin-sdk';
// 或本地 barrel
import { ... } from './api';
import { ... } from './runtime-api';

—

3. 危险代码扫描默认阻止 ⚠️

变更内容：内置危险代码 critical 发现和安装时扫描失败现在默认阻止安装。

#### 影响

  • 之前可能成功安装的不安全插件现在会被阻止
  • 需要显式覆盖才能继续安装

#### 迁移方案

如果遇到安装失败，显式覆盖（谨慎使用！）

openclaw skills install  --dangerously-force-unsafe-install



openclaw plugins install  --dangerously-force-unsafe-install

⚠️ 警告：仅在信任代码来源时使用此选项！

—

4. 可信代理认证强化 ⚠️

变更内容：trusted-proxy 现在拒绝混合共享令牌配置，本地直接回退需要配置令牌。

#### 影响

  • 混合共享令牌配置将不再工作
  • 同主机调用也需要显式配置令牌

#### 迁移方案

config.yaml

gateway:
  auth:
    trusted-proxy:
      - 127.0.0.1
      - 10.0.0.0/8
    tokens:
      - name: local
        token: ${LOCAL_TOKEN}  # 使用环境变量

—

5. 节点命令权限收紧 ⚠️

变更内容：节点命令现在保持禁用状态，直到节点配对被批准。

#### 影响

  • 仅设备配对不再足以暴露声明的节点命令
  • 需要在 OpenClaw Control UI 中明确批准

#### 迁移方案
1. 完成设备配对
2. 访问 OpenClaw Control UI
3. 在「节点管理」中批准该节点
4. 节点命令将自动启用

—

6. 节点事件权限限制 ⚠️

变更内容：节点发起的运行现在保持在减少的信任表面上。

#### 影响

  • 通知驱动或节点触发的流程可能需要调整
  • 之前依赖更广泛主机/会话工具访问的流程可能无法工作

#### 迁移方案

为节点触发的工作流显式配置权限

nodes:
  :
    permissions:
      tools:
        - notify
        - camera_snap
      sessions:
        - read

安全增强

7. ACPX 插件工具 MCP 桥接

新增显式默认关闭的 ACPX 插件工具 MCP 桥接配置：

acp:
  mcp-bridge:
    enabled: false  # 默认关闭，需显式启用
    trust-boundary: strict

8. 代码安装安全扫描强化

  • 危险代码扫描现在失败关闭
  • 安装时安全检查更加严格
  • 新增 --dangerously-force-unsafe-install 覆盖选项

9. 可信代理认证安全

  • 拒绝混合共享令牌配置
  • 本地回退需要显式令牌
  • 防止同主机隐式认证绕过

功能改进

10. Agent 空闲流超时

新增可配置的空闲流超时，防止模型流挂起：

agents:
  llm:
    idle-stream-timeout: 30000  # 30秒

11. MCP 工具增强

  • 工具名称使用提供程序安全格式（serverName__toolName）
  • 支持可选的 streamable-http 传输选择
  • 每个服务器可配置连接超时
  • 保留中止/错误轮次的真实工具结果

#### 配置示例

mcp:
  servers:
    my-server:
      transport: streamable-http
      timeout: 30000
      tools:
        naming: provider-safe  # serverName__toolName

12. Android 通知转发控制

新增通知转发控制功能：

  • 包名过滤
  • 安静时段设置
  • 速率限制
  • 更安全的选择器行为
nodes:
  android:
    notifications:
      forwarding:
        enabled: true
        package-filter:
          - com.whatsapp
          - com.telegram
        quiet-hours:
          start: "22:00"
          end: "08:00"
        rate-limit: 10  # 每分钟最大转发数

13. 后台任务控制平面重构

重大改进：将任务转变为真正的共享后台运行控制平面：

  • 统一 ACP、子代理、cron 和后台 CLI 执行
  • SQLite 支持的账本
  • 分离生命周期更新路由
  • 审计/维护/状态可见性
  • 自动清理和丢失运行恢复
  • 改进的任务感知

#### 查看任务状态

查看所有任务

openclaw tasks list



查看任务详情

openclaw tasks status 


任务审计日志

openclaw tasks audit

迁移指南

升级前检查清单

  • [ ] 备份当前配置
  • [ ] 检查是否有使用 nodes.run 的脚本
  • [ ] 确认插件 SDK 导入路径
  • [ ] 记录当前节点配对状态
  • [ ] 检查是否有自定义安全覆盖

升级步骤

1. 备份配置

cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.backup


2. 更新 OpenClaw

docker pull openclaw/openclaw:2026.3.31-beta.1


3. 重启服务

docker restart openclaw


4. 检查日志

docker logs openclaw | grep -i "breaking\|deprecat\|warning"


5. 验证节点状态

openclaw nodes list

常见迁移问题

| 问题 | 原因 | 解决方案 |
|——|——|———-|
| 节点命令不工作 | 未批准配对 | 在 Control UI 中批准节点 |
| 插件安装失败 | 安全扫描 | 检查代码或显式覆盖 |
| shell 命令失败 | nodes.run 已移除 | 改用 exec host=node |
| 本地 API 401 | 可信代理变更 | 配置显式令牌 |

总结

OpenClaw 2026.3.31-beta.1 是一次以安全为核心的重大更新：

1. 6个破坏性变更 — 强化安全边界，减少攻击面
2. 后台任务重构 — 统一控制平面，提升可靠性
3. MCP 增强 — 更好的工具管理和传输支持
4. Android 通知 — 更细粒度的控制
5. 安装安全 — 默认阻止危险代码

下一步行动：
1. 在测试环境验证所有工作流
2. 按迁移指南逐步升级
3. 在 Control UI 中重新批准节点
4. 更新使用旧 SDK 路径的插件

常见问题

Q: 为什么节点命令突然不工作了？

A: 2026.3.31-beta.1 要求节点配对后显式批准才能使用节点命令：
1. 打开 OpenClaw Control UI（通常是 http://localhost:5678）
2. 进入「节点」页面
3. 找到你的设备，点击「批准」
4. 节点命令将自动恢复

Q: 如何安全地安装被阻止的插件？

A: 如果你有充分理由信任该插件，可以使用覆盖选项：

openclaw skills install  --dangerously-force-unsafe-install

⚠️ 仅在以下情况使用：

  • 你自己开发的插件
  • 来自官方或可信源的插件
  • 已在隔离环境测试过

Q: nodes.run 和 exec host=node 有什么区别？

A:

  • nodes.run — 已移除，旧版包装器
  • exec host=node — 标准 shell 执行，推荐方式
  • nodes invoke — 调用节点特定功能（相机、位置等）

Q: 后台任务重构对我有什么影响？

A: 主要改进：

  • 更可靠的任务状态跟踪
  • 统一的任务管理界面
  • 更好的失败恢复
  • 审计日志支持

使用 openclaw tasks 命令管理任务，之前通过 ACP 或 cron 启动的任务会自动迁移。

Q: 如何回退到之前的版本？

A: 

停止当前容器

docker stop openclaw


启动旧版本（替换为之前的标签）

docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:2026.3.30


恢复配置

cp ~/.openclaw/config.yaml.backup ~/.openclaw/config.yaml

Q: MCP 工具命名变更会影响现有配置吗？

A: 新的 serverName__toolName 格式是附加功能，不影响现有配置。但如果你希望使用显式服务器选择，可以更新配置：

mcp:
  naming: provider-safe  # 启用新格式

参考来源

—

相关阅读：

OpenClaw 2026.4.1-beta.1 发布：15个新功能与改进全解析

发表评论

OpenClaw 2026.4.1-beta.1 发布：15个新功能与改进全解析

OpenClaw 2026.4.1-beta.1 带来任务管理、搜索增强、企业安全等15项重大更新，让你的 AI 自动化工作流更加强大。

本文将深入解析这个版本的核心功能，帮助你快速上手这些新特性。

目录

核心新功能

1. 任务看板 /tasks

OpenClaw 现在内置了原生任务管理功能！通过 /tasks 命令，你可以在会话中直接查看和管理后台任务。

#### 功能亮点

  • 实时查看当前会话的后台任务状态
  • 显示最近任务详情
  • 当没有可见任务时显示 agent 本地回退计数

#### 如何使用

在对话中输入

/tasks



查看特定任务详情

/tasks

2. SearXNG 搜索集成

新增 SearXNG 搜索提供程序，让你的 AI Agent 拥有更强大的隐私搜索能力。

#### 配置方法

config.yaml

web_search:
  provider: searxng
  searxng:
    host: "https://your-searxng-instance.com"

#### 使用场景

  • 企业内部知识库搜索
  • 隐私保护的网页搜索
  • 自建搜索基础设施

3. Amazon Bedrock Guardrails

Bedrock 用户现在可以使用 Guardrails 功能，为 AI 响应添加安全层。

#### 配置示例

providers:
  bedrock:
    guardrails:
      enabled: true
      guardrailId: "your-guardrail-id"
      guardrailVersion: "DRAFT"

任务管理增强

4. macOS 语音唤醒

macOS 用户现在可以使用语音唤醒功能触发 Talk Mode！

#### 启用步骤
1. 打开 OpenClaw 设置
2. 进入「语音」选项
3. 开启「语音唤醒」
4. 设置唤醒词

5. 飞书文档评论集成

飞书 集成新增文档评论工作流，支持：

  • 评论事件流转
  • 评论线程上下文解析
  • 文档协作工作流中的回复

#### 使用示例

channels:
  feishu:
    drive:
      commentActions:
        - reply
        - resolve

搜索与集成

6. Webchat 历史记录可配置

Gateway 的 chat.history 文本截断现在可配置了！

#### 配置选项

gateway:
  webchat:
    chatHistoryMaxChars: 4000  # 全局默认

或者在请求中指定：

{
  "maxChars": 2000
}

7. Z.AI 模型更新

Z.AI 提供程序新增两个模型：

  • glm-5.1 — 更强的文本处理能力
  • glm-5v-turbo — 优化的视觉理解模型

企业级安全

8. Agent 默认参数全局配置

现在可以通过 agents.defaults.params 设置全局默认参数：

agents:
  defaults:
    params:
      temperature: 0.7
      max_tokens: 2000

9. Agent 故障转移优化

改进了 Agent 的故障转移逻辑：

  • 限制同一认证配置文件的速率限制重试次数
  • 跨提供程序模型回退前进行多次尝试
  • 新增 auth.cooldowns.rateLimitedProfileRotations 配置项

#### 配置示例

auth:
  cooldowns:
    rateLimitedProfileRotations: 3

10. Cron 工具白名单

Cron 作业现在支持工具白名单，提升安全性：

创建只允许特定工具的 cron 作业

openclaw cron add --name daily-report --schedule "0 9   *" \
  --tools web_search,message_send \
  --script "scripts/daily_report.py"

开发者优化

11. 频道会话路由改进

会话路由逻辑重构，将提供程序特定的会话对话语法移至插件拥有的会话密钥层：

  • 保留 Telegram 话题路由
  • 飞书 作用域继承

12. WhatsApp 反应级别指导

WhatsApp 集成新增 reactionLevel 指导，让 Agent 的反应更加智能：

channels:
  whatsapp:
    reactionLevel: moderate  # conservative | moderate | expressive

13. Telegram 错误策略

Telegram 新增可配置的 errorPolicy 和 errorCooldownMs 控制：

channels:
  telegram:
    errorPolicy: suppress-repeated
    errorCooldownMs: 300000  # 5分钟

14. Agent 压缩模型配置

agents.defaults.compaction.model 现在在各种上下文引擎压缩路径中一致解析。

15. 错误处理改进

  • 停止将原始提供程序/运行时错误泄露到外部聊天频道
  • 返回友好的重试消息
  • 为 Bedrock toolResult/toolUse 会话不匹配添加特定的 /new 提示

总结

OpenClaw 2026.4.1-beta.1 是一次重大更新，涵盖：

1. 任务管理 — 原生 /tasks 看板功能
2. 搜索增强 — SearXNG 和隐私搜索支持
3. 企业安全 — Bedrock Guardrails 和故障转移优化
4. 集成扩展 — 飞书评论、语音唤醒、Z.AI 新模型
5. 开发者体验 — Cron 白名单、错误处理改进

下一步行动：
1. 升级到你的 OpenClaw 实例：openclaw update
2. 配置 SearXNG 搜索提供程序
3. 尝试新的 /tasks 任务管理功能
4. 如果你是企业用户，配置 Bedrock Guardrails

常见问题

Q: 如何升级到 2026.4.1-beta.1？

A: 运行以下命令：

Docker 部署

docker pull openclaw/openclaw:2026.4.1-beta.1


或直接更新

openclaw update

Q: SearXNG 搜索和默认搜索有什么区别？

A: SearXNG 是一个元搜索引擎，可以聚合多个搜索引擎的结果，同时提供更好的隐私保护。适合：

  • 企业内部部署
  • 隐私敏感场景
  • 需要自定义搜索源的场景

Q: Bedrock Guardrails 如何工作？

A: Guardrails 是 Amazon Bedrock 的内容过滤和治理功能，可以：

  • 过滤敏感内容
  • 阻止特定主题
  • 掩码 PII 信息
  • 自定义拒绝消息

Q: /tasks 命令能看到其他会话的任务吗？

A: 不能。/tasks 只显示当前会话的后台任务，保护任务隐私。

Q: Cron 工具白名单是必需的吗？

A: 不是必需的，但推荐用于生产环境，可以限制 cron 作业的权限，提升安全性。

Q: macOS 语音唤醒支持哪些语言？

A: 当前版本支持英语和中文唤醒词，具体取决于系统语音识别设置。

参考来源

—

相关阅读：

OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

发表评论

OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

OpenClaw 2026.3.31-beta.1 是一次重大安全更新，包含6个破坏性变更和多项功能增强，显著提升了系统的安全性和可靠性。

本文将详细解析这些变更的影响，并提供完整的迁移指南，帮助你顺利升级。

目录

破坏性变更（Breaking Changes）

1. 节点执行方式重构 ⚠️

变更内容：移除了 nodes.run shell 包装器，节点 shell 执行现在统一通过 exec host=node。

#### 影响

  • 之前使用 nodes.run 执行 shell 命令的脚本需要修改
  • 节点特定功能保留在 nodes invoke 和专用媒体/位置/通知操作中

#### 迁移方案

旧方式（已弃用）

nodes.run "ls -la"



新方式

exec host=node ls -la

#### 何时使用哪个命令？

  • exec host=node — 在节点上执行 shell 命令
  • nodes invoke — 调用节点特定功能（相机、位置、通知）

—

2. 插件 SDK 弃用警告 ⚠️

变更内容：弃用旧版提供程序兼容子路径和旧版捆绑提供程序设置。

#### 影响

  • 使用旧版 SDK 路径的插件将看到迁移警告
  • 未来主要版本将完全移除这些兼容层

#### 迁移方案

// 旧方式（已弃用）
import { ... } from 'openclaw/legacy-compat';



// 新方式
import { ... } from 'openclaw/plugin-sdk';
// 或本地 barrel
import { ... } from './api';
import { ... } from './runtime-api';

—

3. 危险代码扫描默认阻止 ⚠️

变更内容：内置危险代码 critical 发现和安装时扫描失败现在默认阻止安装。

#### 影响

  • 之前可能成功安装的不安全插件现在会被阻止
  • 需要显式覆盖才能继续安装

#### 迁移方案

如果遇到安装失败，显式覆盖（谨慎使用！）

openclaw skills install  --dangerously-force-unsafe-install



openclaw plugins install  --dangerously-force-unsafe-install

⚠️ 警告：仅在信任代码来源时使用此选项！

—

4. 可信代理认证强化 ⚠️

变更内容：trusted-proxy 现在拒绝混合共享令牌配置，本地直接回退需要配置令牌。

#### 影响

  • 混合共享令牌配置将不再工作
  • 同主机调用也需要显式配置令牌

#### 迁移方案

config.yaml

gateway:
  auth:
    trusted-proxy:
      - 127.0.0.1
      - 10.0.0.0/8
    tokens:
      - name: local
        token: ${LOCAL_TOKEN}  # 使用环境变量

—

5. 节点命令权限收紧 ⚠️

变更内容：节点命令现在保持禁用状态，直到节点配对被批准。

#### 影响

  • 仅设备配对不再足以暴露声明的节点命令
  • 需要在 OpenClaw Control UI 中明确批准

#### 迁移方案
1. 完成设备配对
2. 访问 OpenClaw Control UI
3. 在「节点管理」中批准该节点
4. 节点命令将自动启用

—

6. 节点事件权限限制 ⚠️

变更内容：节点发起的运行现在保持在减少的信任表面上。

#### 影响

  • 通知驱动或节点触发的流程可能需要调整
  • 之前依赖更广泛主机/会话工具访问的流程可能无法工作

#### 迁移方案

为节点触发的工作流显式配置权限

nodes:
  :
    permissions:
      tools:
        - notify
        - camera_snap
      sessions:
        - read

安全增强

7. ACPX 插件工具 MCP 桥接

新增显式默认关闭的 ACPX 插件工具 MCP 桥接配置：

acp:
  mcp-bridge:
    enabled: false  # 默认关闭，需显式启用
    trust-boundary: strict

8. 代码安装安全扫描强化

  • 危险代码扫描现在失败关闭
  • 安装时安全检查更加严格
  • 新增 --dangerously-force-unsafe-install 覆盖选项

9. 可信代理认证安全

  • 拒绝混合共享令牌配置
  • 本地回退需要显式令牌
  • 防止同主机隐式认证绕过

功能改进

10. Agent 空闲流超时

新增可配置的空闲流超时，防止模型流挂起：

agents:
  llm:
    idle-stream-timeout: 30000  # 30秒

11. MCP 工具增强

  • 工具名称使用提供程序安全格式（serverName__toolName）
  • 支持可选的 streamable-http 传输选择
  • 每个服务器可配置连接超时
  • 保留中止/错误轮次的真实工具结果

#### 配置示例

mcp:
  servers:
    my-server:
      transport: streamable-http
      timeout: 30000
      tools:
        naming: provider-safe  # serverName__toolName

12. Android 通知转发控制

新增通知转发控制功能：

  • 包名过滤
  • 安静时段设置
  • 速率限制
  • 更安全的选择器行为
nodes:
  android:
    notifications:
      forwarding:
        enabled: true
        package-filter:
          - com.whatsapp
          - com.telegram
        quiet-hours:
          start: "22:00"
          end: "08:00"
        rate-limit: 10  # 每分钟最大转发数

13. 后台任务控制平面重构

重大改进：将任务转变为真正的共享后台运行控制平面：

  • 统一 ACP、子代理、cron 和后台 CLI 执行
  • SQLite 支持的账本
  • 分离生命周期更新路由
  • 审计/维护/状态可见性
  • 自动清理和丢失运行恢复
  • 改进的任务感知

#### 查看任务状态

查看所有任务

openclaw tasks list



查看任务详情

openclaw tasks status 


任务审计日志

openclaw tasks audit

迁移指南

升级前检查清单

  • [ ] 备份当前配置
  • [ ] 检查是否有使用 nodes.run 的脚本
  • [ ] 确认插件 SDK 导入路径
  • [ ] 记录当前节点配对状态
  • [ ] 检查是否有自定义安全覆盖

升级步骤

1. 备份配置

cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.backup


2. 更新 OpenClaw

docker pull openclaw/openclaw:2026.3.31-beta.1


3. 重启服务

docker restart openclaw


4. 检查日志

docker logs openclaw | grep -i "breaking\|deprecat\|warning"


5. 验证节点状态

openclaw nodes list

常见迁移问题

| 问题 | 原因 | 解决方案 |
|——|——|———-|
| 节点命令不工作 | 未批准配对 | 在 Control UI 中批准节点 |
| 插件安装失败 | 安全扫描 | 检查代码或显式覆盖 |
| shell 命令失败 | nodes.run 已移除 | 改用 exec host=node |
| 本地 API 401 | 可信代理变更 | 配置显式令牌 |

总结

OpenClaw 2026.3.31-beta.1 是一次以安全为核心的重大更新：

1. 6个破坏性变更 — 强化安全边界，减少攻击面
2. 后台任务重构 — 统一控制平面，提升可靠性
3. MCP 增强 — 更好的工具管理和传输支持
4. Android 通知 — 更细粒度的控制
5. 安装安全 — 默认阻止危险代码

下一步行动：
1. 在测试环境验证所有工作流
2. 按迁移指南逐步升级
3. 在 Control UI 中重新批准节点
4. 更新使用旧 SDK 路径的插件

常见问题

Q: 为什么节点命令突然不工作了？

A: 2026.3.31-beta.1 要求节点配对后显式批准才能使用节点命令：
1. 打开 OpenClaw Control UI（通常是 http://localhost:5678）
2. 进入「节点」页面
3. 找到你的设备，点击「批准」
4. 节点命令将自动恢复

Q: 如何安全地安装被阻止的插件？

A: 如果你有充分理由信任该插件，可以使用覆盖选项：

openclaw skills install  --dangerously-force-unsafe-install

⚠️ 仅在以下情况使用：

  • 你自己开发的插件
  • 来自官方或可信源的插件
  • 已在隔离环境测试过

Q: nodes.run 和 exec host=node 有什么区别？

A:

  • nodes.run — 已移除，旧版包装器
  • exec host=node — 标准 shell 执行，推荐方式
  • nodes invoke — 调用节点特定功能（相机、位置等）

Q: 后台任务重构对我有什么影响？

A: 主要改进：

  • 更可靠的任务状态跟踪
  • 统一的任务管理界面
  • 更好的失败恢复
  • 审计日志支持

使用 openclaw tasks 命令管理任务，之前通过 ACP 或 cron 启动的任务会自动迁移。

Q: 如何回退到之前的版本？

A: 

停止当前容器

docker stop openclaw


启动旧版本（替换为之前的标签）

docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:2026.3.30


恢复配置

cp ~/.openclaw/config.yaml.backup ~/.openclaw/config.yaml

Q: MCP 工具命名变更会影响现有配置吗？

A: 新的 serverName__toolName 格式是附加功能，不影响现有配置。但如果你希望使用显式服务器选择，可以更新配置：

mcp:
  naming: provider-safe  # 启用新格式

参考来源

—

相关阅读：