openclaw4.1更新升级手册

OpenClaw 4.1 更新升级手册版本号2026.4.1发布日期2026 年 4 月 1 日官方文档https://docs.openclaw.ai零、升级步骤升级前推荐先看一下当前版本状态openclaw update status确认当前版本和升级通道stable/beta/dev没问题之后执行升级openclaw update这是最常用的升级命令会自动处理以下流程检查工作区是否干净如果有未提交的改动会停下来让你先处理切换到目标 channelstable 装 npm 包dev 从 git checkout 拉代码Dev 通道额外步骤运行 lint TypeScript 构建失败了自动尝试回退最多 10 个 commit 找能构建的版本安装依赖pnpm 优先没有的话用 npm构建 构建 Control UI运行openclaw doctor这是最后的安全检查通过了才算升级完成同步插件根据通道同步 bundled 插件或 npm 插件升级完成后gateway 会自动重启。如果想跳过重启自己控制重启时机加--no-restartopenclaw update --no-restart预览升级会做什么但不实际执行用--dry-runopenclaw update --dry-run切换到 beta 通道openclaw update--channelbeta切回 stableopenclaw update--channelstable⚠️ 3.31 升级后 Control UI 500 报错问题这是一个已知的打包问题升级到 3.31 后 Control UIWeb 界面打不开页面一直报 Internal Server Error控制台看是 500。原因是 3.31 的安装包漏掉了一些核心插件的依赖包。4.1 版本已修复此问题建议直接升级到 4.1 避开这个坑。如果你目前还在 3.31 且遇到这个问题手动补齐依赖即可# 进入 OpenClaw 安装目录cd/opt/homebrew/lib/node_modules/openclaw# macOS Homebrew 安装路径# 或者 npm 全局安装的话大概是cd$(npmroot-g)/openclaw# 手动安装缺失的依赖npminstallslack/bolt slack/web-api grammy grammyjs/runner grammyjs/transformer-throttler buape/carbon aws-sdk/client-bedrock# 重启 gatewayopenclaw gateway restart重启后刷新页面UI 应该就能正常加载了。一、这个版本更新了什么4.1 是一个问题修复大礼包主要工作是让 3.31 引入的那些新功能跑得更稳。如果你从 3.31 升级过来用户端能感知到的变化不算多但每一个修复都是实打实的坑。下面按日常使用场景来介绍新功能最后单独说升级注意事项。二、新功能介绍1. 后台任务面板 /tasks现在可以直接在聊天里输入/tasks看到一个简洁的任务列表显示当前会话相关的后台任务。方便的地方在于不用切到别的地方在对话里就能看到任务跑到哪了、有没有卡住。支持查看最近的任务详情任务数量不多时直接在这里管理就够了。2. 内置 SearXNG 搜索 provider如果你的网络环境不方便访问某些搜索引擎或者希望用自己的 SearXNG 实例现在可以直接在 OpenClaw 里配置providers:searxng:type:searxnghost:https://your-searxng-instance.com搜索请求会走你指定的实例。适合有私有部署需求的用户。3. Telegram 消息发送错误控制Telegram 发送消息偶尔会遇到各种错误之前的问题是没有区分度同一个错误反复触发会很烦人。4.1 新增了两个配置项errorPolicy控制遇到错误时的行为策略errorCooldownMs同类错误的冷却时间说人话就是同一个问题不会一直重试轰炸你冷却机制让错误处理变得更理智。4. QQ Bot /bot-logs 导出权限收紧了这个是安全相关的收紧之前 /bot-logs 导出的权限判断不够严格4.1 修复为只有明确配置的 QQ 账号才能导出日志通配符和混合通配符的写法会被拒绝。如果你的脚本里有调用这个接口升级后需要确认权限配置是否符合新的要求。5. WhatsApp 消息支持表情回应现在 agent 可以对收到的 WhatsApp 消息发表情了。发一张照片收到一个 ❤️发一个想法收到一个 ——对话更自然了。6. Feishu 文档评论事件支持飞书云文档的评论现在可以触发 agent 响应了。配置好飞书 Drive 相关的 event 后文档下的评论会被转发进来适合做文档协作类的自动化流程。7. Cron 任务支持单独的工具白名单之前 Cron 任务继承 agent 的全部工具权限现在可以精细化控制openclawcron--toolsweb_search,calendaradd...每个任务可以指定自己能用哪些工具权限最小化原则更容易执行。8. 模型回退行为更稳定4.1 修复了一个让人头疼的问题同一个 provider 下的 auth profile比如 key 用完了或者被限速了会反复重试白白浪费时间。4.1 增加了同 provider 级别 retry 上限超过后直接切到其他 provider 的模型不再死磕。对应的配置项是auth.cooldowns.rateLimitedProfileRotations。三、重大改动和升级注意事项⚠️ 必看3.31 引入的破坏性改动4.1 本身没有引入新的 breaking change但3.31 的改动仍然需要你注意如果你是从更早版本升级过来的务必检查以下几项1.nodes.run命令没了Node 相关的 shell 执行路径统一改成了exec hostnode。如果你有脚本在用nodes.run会直接报错需要改成新语法。2. Plugin SDK 旧路径已废弃旧版的兼容路径providers/compat/*之类的已经在 3.31 打了废弃警告。还没迁移的话未来的大版本会直接报错。建议近期把插件迁移到官方推荐的路径上。3. 危险代码扫描默认失败之前有些插件带的代码会被标记为危险但还是能装上3.31 开始直接不让装了。如果某个插件在升级后装不上可以用--dangerously-force-unsafe-install强制安装但建议优先联系插件作者等官方更新。4.trusted-proxy认证变严了混用 shared-token 的配置现在会被拒绝同主机回环调用也不能免 token 了需要显式带上检查一下你的 gateway 配置里有没有这种写法有的话需要改掉。5. Node 命令现在需要单独配对3.31 之前只要完成设备配对就能跑 node commands现在不行了需要再做一步 Node Pairing 审批。升级后如果发现 node commands 跑不了试着重新走一遍配对流程。6. Node 触发运行的权限收窄了如果你的自动化流程里有依赖 node 端触发、并且需要比较宽泛的工具权限3.31 之后这个权限面被缩小了。建议review一下相关流程看是不是需要调整权限配置。升级后验证清单升级完成后建议做这几件事确认一切正常运行openclaw doctor看有没有报错试试 node commands 能不能正常执行检查一下各渠道的消息收发是否正常Telegram、QQ、飞书等跑一个 cron 任务确认工具白名单生效如果有 SearXNG 配置确认搜索走的是你自己的实例四、其他值得注意的修复下面挑几个对日常使用影响比较大的修复说一下不感兴趣的可以跳过这节Telegram 论坛话题的 exec 审批不再跑到根聊天去了之前在 Telegram 论坛里触发一个需要审批的命令审批结果会跑到根聊天而不是原地回复。4.1 修好了审批流会在你发起的话题里完成。Discord 上传大文件不会卡住消息处理了之前 Discord 附件下载慢的时候会连带整条消息处理卡住现在下载走独立超时控制了这个问题解决。Docker 用户注意BuildKit 强制启用如果你的 docker-setup.sh 之前在非 BuildKit 环境下跑会报错3.31 修复了这个问题。Docker 用户升级后建议重新跑一遍初始化脚本。全剧安装后 LINE 插件起不来3.31 之前全局 npm 安装后 LINE 插件会因为找不到某个模块而起不来4.1 已经修复。Gateway 重启循环问题修改gateway.auth.*相关的配置之前有时候会触发意外的 restart loop4.1 修复了——只有真正改了配置才会触发重启gateway 自己生成的 token 不会再触发了。任务系统不会让 gateway 卡住了3.31 引入了新的任务系统但有个 bug 导致 gateway 运行约一分钟后开始卡住4.1 修复了。五、为什么新版本开始频繁弹审批这是 3.31 以来困扰不少人的问题——升级之后几乎每执行一条 shell 命令都要弹一次审批比之前频繁多了。这个问题其实不是 bug是设计变了。原因是这样OpenClaw 的 exec 审批系统~/.openclaw/exec-approvals.json是用来在命令真正跑到你机器上之前加一道检查的。3.31 之前审批策略相对宽松很多命令默认可过。3.31 之后安全策略收紧默认变成了白名单模式security: allowlist即默认阻止所有命令只有明确加入白名单的才能直接跑。每次你在审批框里点「Always allow」就是把这条命令的路径写进白名单。所以升级之后第一次跑各种命令都会逐一触发审批——这是正常的白名单建起来之后就会好很多。另外还有一个原因3.31 开始allow-always信任一次就永久信任变得更严格了。以前某些 shell 包装命令比如caffeinate、arch、xcrun之类的可能会绕过审批现在这些都被拆解检查审批流程更细致弹窗自然就多了。六、如何减少/关闭频繁审批有几种方式取决于你的安全诉求和便利诉求怎么平衡。方式一逐条信任推荐兼顾安全每次弹审批的时候点「Always allow」把这条命令加到白名单里。跑一段时间之后常用的命令都进白名单了弹窗就会少很多。适合人群不想降低安全性但能接受建设期多点点鼠标的用户。方式二只对常用命令开白名单如果你有明确知道哪些命令经常跑可以用 CLI 手动加白名单openclaw approvals allowlistadd--agentmain--pattern~/bin/*openclaw approvals allowlistadd--agentmain--pattern~/.local/bin/*或者直接在 Control UI → Nodes → Exec approvals 里管理白名单规则。方式三彻底关闭审批⚠️ 有风险如果你在可信环境自己的 VPS 或本地机器不需要每次都审批执行下面这条openclaw configsettools.exec.security full openclaw configsettools.exec.ask off openclaw gateway restart解释一下这两个参数security: full—— 相当于完全信任不再走白名单检查所有命令直接放行ask: off—— 即使有审批请求也不弹窗直接执行⚠️ 风险提示执行之后AI 对你的机器有完全的 shell 执行权限。这意味着如果 AI 被引导执行了恶意命令也是直接执行的。所以⚠️ 只在你自己一个人用的、信任的机器上开⚠️ 不要在多人共享的环境、公网可达的服务器上开⚠️ 如果不确定先看方式一点点「Always allow」就好了如果之后想恢复审批重新设回来openclaw configsettools.exec.security allowlist openclaw configsettools.exec.ask on-miss openclaw gateway restart方式四审批路由到聊天频道如果不想在终端/Web UI 里审批想直接在 Telegram、Discord、Slack 里批准 exec 命令4.1 支持这个功能参考官方文档的approvals.exec.targets配置。这个适合已经在用 Telegram/Discord 作为日常聊天的用户审批和日常聊天在一起体验更顺。七、官方资源文档https://docs.openclaw.aiGitHubhttps://github.com/openclaw/openclaw社区 Discordhttps://discord.com/invite/clawdSkills 市场https://clawhub.ai升级顺利有问题直接问龙虾啊