OpenHands v1.24.0更新解读：4项新功能与7处关键修复

版本定位：一次把教程功能修顺的小版本

OpenHands 在完成 v1.13 到 v1.23 共 11 个版本的大盘点之后，仅隔两天就在 9 月 25 日推出了 v1.24.0。从发布节奏看，这是大盘点后的首个修复版本，并没有急于做架构级别的大改。

整个版本累计 29 次代码提交、136 个文件变更，表面数字不小，但真正的大头落在测试与文档上——新增 5607 行、删除 1562 行代码，其中测试与贡献指引占了绝大部分。换句话说，功能层面改动克制，核心价值在于把此前系列教程里配置过的功能逐个修顺。

据 B 站 UP 主「大叔大」的持续实测分享，这一版可以用三条主线概括：教程功能修顺、多后端切换更稳、贡献指引重构。本期就围绕这三条主线，拆解 4 件新功能与 7 处关键修复。

四件新功能：入口更集中，协作更安全

工作区文件夹集中开关

过去要开关某个文件夹，得钻进文件树里一个个翻找。v1.24.0 把入口挪到了对话头部，可以一次性集中管理所有文件夹，省去反复展开目录树的操作。该功能由贡献者 CodeepSync19 提交。

订阅缓存按后端隔离

切换后端后订阅缓存互相串台，是 OpenHands 的老毛病。新版让 OpenAI 等订阅缓存跟随后端走，切换后端时不再出现缓存错乱。这一改动对经常在多个后端之间切换的用户尤为实用，由贡献者 WoochLTW6 完成。

首页文案改版

首页介绍被改写成贴近日常工程工作的口吻，打开应用就能直观理解它能替你完成哪些任务，降低了新用户的理解门槛。

共享自动化对话默认只读

云端协作时最怕手滑覆盖别人的自动化配置。这版把共享的自动化对话默认设为只读，避免误操作造成的协作事故，由贡献者 Hyptail 提交。

上半场三处修复：画布、工具调用与模型提醒

接下来是重点——这些修复几乎都落在系列教程讲过的章节里，跟着教程配过环境的用户一个配置都不用动就能感知到改善。

画布直连运行时：现在画布直连运行时的服务验证可以正常走通，确认运行链路畅通，由 John Michelini 提交。

ACP 工具调用显示完整：以前对话卡片里的工具调用只剩一个标题，无法看到细节。现在工具调用的内容块会完整渲染在聊天卡片中，排查过程更透明，由 Chocolating75 提交。

模型不可用会提醒：过去配置里引用的模型若被下架，系统只会默默失败，让人摸不着头脑。现在 LLM 配置引用不到模型时会直接给出警告，由 AK6800 提交。

下半场四处修复：云端同步、调度与历史记录

剩下四处同样都是教程里动过手的地方。

MCP 登录状态云端同步：以前每次云端对话都要重新授权 MCP，现在凭据跟随云端保存，Token 仍有效时直接复用，省去重复授权，由 Hypto 提交。

自动化调度更宽容：以前 Cron 表达式写单项起始值会报错，现在调度校验器接受这种写法，任务能按计划正常运行，由 Harsh R3 提交。

设置按后端分别缓存：以前切换后端后，设置面板会出现张冠李戴的情况，现在设置也按后端独立缓存。

失败消息不再被冲掉：以前重新加载历史时，较新的失败消息会丢失，现在历史重载会保留较新的失败记录，排查问题更有据可查，由 AK6800 提交。

贡献流程重构：700 多行指南拆成技能文档

功能之外，这版还对贡献流程动了手，对想参与开源的人很实用。原本 700 多行的贡献指南被拆成五份可直接执行的技能文档，放进代码仓库的 Agents/Skills 技能目录，照着做就能提交 PR。

技能目录按五个方向细分：前端接口约定、前端开发、端到端测试、本地运行时冒烟测试、分析等，想从哪个方向切入都可以。本次共有七位贡献者首次合并代码，社区活跃度持续走高。

依赖方面也做了跟进：SDK 升到 1.49.6，相关扩展升到 0.24.0，并新增多组单元测试与端到端测试，这部分测试改动正是本次 136 个文件变更的主要来源。

将单一大型贡献指南拆分为按技能方向细分的独立文档，是开源项目维护中降低新贡献者门槛的常见做法。原本 700 多行的线性文档要求读者从头到尾通读才能找到与自己关注方向相关的内容，而按「前端接口约定、前端开发、端到端测试、本地冒烟测试、分析」五个维度拆分后，贡献者只需按需取用对应的技能文档，每份文档均设计为可直接执行的操作指引。放置在代码仓库 Agents/Skills 目录下也意味着文档与代码版本同步演进，避免了单独维护 Wiki 时常见的文档与实现脱节问题。七位新贡献者在同一版本中首次合并代码，在一定程度上印证了这一结构调整降低了参与难度。

到底要不要升级？

结论很干脆：这版没有破坏性变更，配置文件不用改，什么时候升都行。分人群来看：

• 跟着教程走的用户：建议升级。画布、ACP、LLM、MCP、自动化这五处问题，正是教程章节讲过的功能点，升完就能直接感受到改善。
• 新用户：直接拿 v1.24.0 上手，不用回头补历史版本。
• 多后端或云端用户：缓存与设置按后端隔离之后，切换体验明显更稳。

升级命令也很简单：

# 新安装
uvx install openhands==1.24.0

# 老用户升级
uvx upgrade openhands

整体看，v1.24.0 不是面向架构的大改版，而是一次把常用功能逐个修顺、把贡献流程理清的务实版本。对持续跟进 OpenHands 系列的用户来说，这类「稳定迭代」往往比大改版更值得第一时间跟进。

背景补充

ACP（Agent Communication Protocol）是 OpenHands 中用于协调 AI 智能体与外部工具之间交互的协议层。当智能体需要调用搜索、代码执行、文件读写等外部能力时，底层会生成结构化的工具调用请求，并将结果以「内容块」形式写回对话上下文。此前该内容块仅在卡片头部显示调用名称，具体入参与返回值被折叠或截断，开发者在排查智能体行为异常时无法直接在聊天界面核对调用细节，必须翻阅后台日志。此次修复后，完整的请求参数和响应内容会直接渲染在聊天卡片内，使调试链路从「猜测→查日志→复现」缩短为「看卡片→定位问题」，对需要精细调优工具调用策略的用户意义较大。

MCP（Model Context Protocol）是由 Anthropic 主导推动的开放协议，旨在为 AI 模型提供标准化的上下文与工具接入方式。第三方服务（如 GitHub、Notion、数据库连接器等）可以通过实现 MCP Server 将自身能力暴露给兼容该协议的 AI 客户端，而无需为每个客户端单独开发集成。在 OpenHands 的云端模式下，每次新建对话都相当于启动一个独立的运行时会话，若 MCP 凭据不随云端状态持久化，则每次会话开始前都需要重新完成 OAuth 授权或手动粘贴 Token。此次修复将有效凭据绑定到云端账户层面，只要 Token 未过期，跨会话均可直接复用，避免了高频授权带来的摩擦。

Cron 表达式是一种用于描述定时任务执行计划的字符串格式，由五到六个字段依次表示分钟、小时、日期、月份、星期（以及可选的秒），字段间以空格分隔。标准写法支持通配符 *、范围 1-5、步长 */2 以及列举 1,3,5 等语法。此次修复针对的是「单项起始值」场景，即某个字段只填写一个具体数字而非范围或通配符时（例如 0 9 * * 1 表示每周一上午 9 点），旧版校验器会将其误判为非法表达式并拒绝保存，导致看似合法的调度配置静默失败。新版校验器放宽了对此类写法的判断逻辑，确保符合 POSIX 标准的 Cron 表达式均能被正确解析并按计划触发任务。