OpenClaw 2026.3.31-beta.1 发布:5个重大变更与安全强化指南
OpenClaw 2026.3.31-beta.1 是一次聚焦安全加固与架构简化的重要更新。本次版本移除了冗余的节点执行层、弃用了旧版插件 SDK 路径,并默认启用更严格的危险代码扫描策略。对于运行生产环境的 AI Agent 平台和依赖插件生态的开发者而言,理解这些 Breaking Changes 是避免服务中断的关键。
本文将逐条解析 5 项重大变更与 6 项功能改进,提供迁移代码示例与故障排查思路。
—
一、节点执行层重构:统一 exec 通道
变更背景
此前 OpenClaw 的节点(Node)执行存在两条路径:nodes.run 包装器与 exec host=node 直接调用。这种设计导致行为不一致,且难以维护节点特定的能力(如媒体控制、地理位置、通知推送)。
新行为
从本版本开始,所有节点 Shell 执行统一走 exec host=node:
• 旧命令:nodes.run ;新命令:exec host=node ;用途:在远程节点执行 Shell 脚本
• 旧命令:nodes invoke;新命令:nodes invoke(保留);用途:调用节点原生能力(媒体/位置/通知)
迁移示例
❌ 旧方式(已移除)
openclaw nodes.run --target pi-kitchen "systemctl restart home-assistant"
✅ 新方式
openclaw exec host=pi-kitchen "systemctl restart home-assistant"
节点特定能力仍通过 invoke 调用
openclaw nodes invoke pi-kitchen notify --title="部署完成" --message="Home Assistant 已重启"
> 影响范围:使用 CLI nodes 工具或 Agent nodes 工具进行远程执行的自动化流程。
---
二、插件 SDK 弃用警告:清理遗留兼容层
被弃用的路径
OpenClaw 插件 SDK 正在精简历史包袱。以下路径将在未来主版本中彻底移除:
• 弃用路径:openclaw/plugin-sdk/providers/compat/;替代方案:openclaw/plugin-sdk/
• 弃用路径:旧版捆绑 Provider 设置;替代方案:本地 api.ts / runtime-api.ts 入口
• 弃用路径:Channel-runtime 兼容垫片;替代方案:标准运行时 API
迁移检查清单
// ❌ 旧导入(将触发警告)
import { legacyProvider } from 'openclaw/plugin-sdk/providers/compat/legacy';
// ✅ 新导入
import { defineProvider } from 'openclaw/plugin-sdk';
import type { RuntimeAPI } from './runtime-api.ts';
export default defineProvider({
name: 'my-provider',
async setup(api: RuntimeAPI) {
// 实现逻辑
}
});
安装插件时如遇弃用警告,建议立即更新 package.json 中的 SDK 版本并重构入口文件。
---
三、安全策略默认收紧:危险代码扫描失败即阻断
关键变更
Skills/install 与 Plugins/install 现在对内置危险代码扫描的 critical 级别发现默认失败关闭(fail closed)。此前仅警告即可通过的安装,现在可能完全阻断。
何时需要覆盖
场景:内部开发的插件被误报为危险
openclaw plugins install ./my-internal-plugin \
--dangerously-force-unsafe-install
场景:技能依赖包含必要的系统级操作
openclaw skills install gateway://team-prod/security-scanner \
--dangerously-force-unsafe-install
> ⚠️ 警告:--dangerously-force-unsafe-install 应仅限受控环境使用,CI/CD 流水线中建议配合 --scan-report=verbose 先行审计。
---
四、网关认证与节点权限双重加固
4.1 可信代理配置收紧
trusted-proxy 配置现在拒绝混合共享令牌配置,且本地直接回退(local-direct fallback)必须使用配置的令牌显式认证,不再隐式信任同主机调用者。
openclaw-gateway.yaml
auth:
trusted-proxy:
- 10.0.0.0/24
tokens:
- name: internal-services
value: ${INTERNAL_TOKEN} # 必须配置,不再自动生成
allowed_proxies: [10.0.0.0/24]
4.2 节点命令与事件隔离
• 场景:设备配对后;旧行为:自动暴露声明的节点命令;新行为:需显式批准配对后启用
• 场景:节点触发的工作流;旧行为:继承完整主机/会话工具访问;新行为:限制在缩减的受信表面
排查命令:
检查节点配对状态
openclaw gateway nodes list --format=table
批准待处理的节点配对
openclaw gateway nodes approve
查看节点事件受限范围
openclaw gateway nodes inspect --show-trust-boundary
---
五、MCP 工具与 Agent 运行时改进
5.1 MCP 工具命名与传输增强
- Provider 安全命名:
serverName__toolName格式避免命名冲突 - 流式 HTTP 传输:可选启用
streamable-http降低延迟 - 连接超时配置:支持按服务器设置
agent-mcp-config.yaml
mcpServers:
filesystem:
transport: streamable-http
connectionTimeout: 30000 # 毫秒
tools:
- readFile
- writeFile # 实际注册为 filesystem__readFile, filesystem__writeFile
5.2 空闲流超时保护
新增 idleStreamTimeout 配置,防止模型流停滞导致整个运行超时:
agents:
default:
llm:
provider: openai
idleStreamTimeout: 15000 # 15秒无数据则中断
---
六、其他值得关注的更新
• 功能:ACPX MCP 桥接;说明:默认关闭,需显式启用;强化日志路径隔离;适用场景:全局安装与 stdio MCP 会话
• 功能:Android 通知转发;说明:包名过滤、安静时段、速率限制;适用场景:移动端自动化与消息路由
• 功能:后台任务统一;说明:SQLite 账本整合 ACP/子代理/Cron/CLI 执行;适用场景:审计追踪与丢失任务恢复
---
常见问题 (FAQ)
Q1: 升级后节点执行命令报错 "nodes.run: command not found",如何解决?
这是预期的 Breaking Change。将所有 nodes.run 调用替换为 exec host= 格式,并确认节点名称正确。若需节点特定能力(如发送通知),改用 nodes invoke。
Q2: 插件安装被阻断,如何确认是否为误报?
运行 openclaw plugins install ,查看 critical 级别的具体发现。若为误报,向插件开发者提交 issue;若为自己维护的插件,审查 postinstall 脚本与动态代码执行。
Q3: 节点配对后命令仍不可用,如何排查?
执行 openclaw gateway nodes list 检查 pairingStatus 是否为 approved 而非仅 paired。新版本中设备配对(paired)与命令授权(approved)分离,需在网关管理界面或 CLI 中二次确认。
Q4: MCP 工具名称变更会影响现有 Agent 配置吗?
若 Agent 配置中硬编码了工具名称(如 readFile),需更新为 serverName__toolName 格式(如 filesystem__readFile)。建议改用动态工具发现而非硬编码名称。
Q5: 是否需要立即升级生产环境?
建议按以下节奏操作:
1. 测试环境:立即升级,验证所有节点执行与插件安装流程
2. 预发布环境:测试网关认证与节点权限变更
3. 生产环境:等待 1-2 周社区反馈,或锁定 2026.3.x 补丁版本
---
总结与下一步
OpenClaw 2026.3.31-beta.1 的核心主题是"安全优先,债务清偿"。节点执行统一、SDK 精简、安全策略默认收紧,均为 2026 年主版本发布铺路。
建议行动:
1. 审计现有工作流中的 nodes.run 用法
2. 运行 openclaw plugins doctor 检查 SDK 弃用警告
3. 在 staging 环境测试 --dangerously-force-unsafe-install 的替代方案
相关阅读:
---