安全

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

作者 Thinkingthigh

2026年4月2日 3 分钟阅读

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

常见迁移问题

总结

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` 有什么区别？

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

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

A: 主要改进：

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

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

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

停止当前容器
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.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

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

目录

破坏性变更（Breaking Changes）

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

旧方式（已弃用）

新方式

2. 插件 SDK 弃用警告 ⚠️

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

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

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

config.yaml

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

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

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

安全增强

7. ACPX 插件工具 MCP 桥接

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

9. 可信代理认证安全

功能改进

10. Agent 空闲流超时

11. MCP 工具增强

12. Android 通知转发控制

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

查看所有任务

查看任务详情

任务审计日志

迁移指南

升级前检查清单

升级步骤

1. 备份配置

2. 更新 OpenClaw

3. 重启服务

4. 检查日志

5. 验证节点状态

常见迁移问题

总结

常见问题

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

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

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

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

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

停止当前容器

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

恢复配置

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

参考来源

Thinkingthigh

其他文章

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

OpenClaw 新功能：TinyFish 浏览器自动化插件使用指南

暂无评论！成为第一个。

发表回复

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