OpenHands v1.28.0：OpenCode与PI成内置Agent，密钥可对话申请

OpenHands 在 21 天内连续推送了 5 个版本，累计 310 次提交，新增代码 39847 行，删除仅 44 行。这轮更新几乎全是功能叠加，而非重构精简。最值得关注的是 v1.27.0 将 OpenCode 和 PI 写入了内置 Agent 列表，意味着你手头正在用的 coding agent 可以直接作为 OpenHands 的后端运行。本文基于 B 站 UP 主「大叔大」的 release 解读视频，梳理这轮更新的核心变化与升级建议。

内置 Agent：从手动配置到开箱即用

此前想在 OpenHands 里挂一个外部 coding agent，需要自己拼命令、自己配凭证，配置错一处就前功尽弃。v1.27.0 把 OpenCode 和 PI 直接写进了内置 provider 列表，引导页上五个选项并排摆放：Claude Code、Codex、Gemini CLI、OpenCode、PI。

agent server把agent自己的命令行拉成子进程

这套机制走的是 ACP 协议（Agent Client Protocol），本质是用 JSON-RPC 在标准输入输出上与 coding agent 通信。agent server 会把 agent 自己的命令行拉成子进程，模型、工具、执行权限全部由 agent 自己管理。四家启动命令遵循同一套路——用 npx 加对应参数拉起 ACP 包：Claude Code 拉 Claude Agent ACP，Codex 拉 Codex ACP，Gemini CLI 拉 Gemini CLI ACP，OpenCode 直接是 opencode-ai 后跟 ACP 参数。

配置入口在设置的 agent 页，共五项：preset、command、credentials、model。选好 preset 保存后，会通过 PATCH 方法写入 /api-settings，包含 agent-kind（代理类型）、acp-command（启动命令）、acp-model（留空表示由 agent 决定默认模型）三个字段。

ACP（Agent Client Protocol）是一个开放协议，旨在标准化代码编辑器/IDE 与 AI coding agent 之间的通信。它由 Zed Industries 主导提出，采用 JSON-RPC 2.0 消息格式，通过标准输入输出（stdio）在客户端与 agent 子进程之间传输请求与通知。协议定义了会话初始化、模型选择、工具调用、权限确认等核心方法，使不同的 agent 实现（如 Claude Code、Gemini CLI）能够以统一方式被宿主程序驱动。OpenHands 借助 ACP 将外部 agent 作为子进程拉起，从而在不修改 agent 内部逻辑的前提下完成集成，这也是其“编排层”定位的技术基础。

凭证规则：登录优先于 Key

很多人会在这里踩坑。规则很简单：如果你在 provider 自己的命令行里登录过，OpenHands 会直接复用登录态，引导页上两栏 Key 留空即可，本机后端会自动查找 provider 存下来的登录记录。

各家的登录态位置不同：Claude Code 在 macOS 上存在系统钥匙串，Linux 上是 ~/.claude/.credentials.json；Codex 写在 ~/.codex/auth.json；Gemini CLI 在 ~/.gemini/oauth_creds.json；PI 在 ~/.pi/agent-auth.json；OpenCode 在 ~/.local/share/opencode/auth.json。

对应的环境变量也各自独立：Claude Code 和 PI 用 ANTHROPIC_API_KEY，Codex 用 OPENAI_API_KEY，Gemini CLI 用 GEMINI_API_KEY，OpenCode 用 OPENCODE_API_KEY。两个例外值得记住：OpenCode 走 Zen 的免费模型不需要任何凭证，那一步永远不会卡住；PI 缺凭证则会直接报错要求认证。

这一步整个可以跳过

v1.28.0 进一步把密钥申请搬进了对话——agent 可以弹窗要密钥，你在弹窗里直接填入上下文，存储位置是设置里的 Secrets，名字必须与注入给执行层的环境变量完全一致。容器后端没有宿主机的登录态，需要显式传入凭证，OpenCode 用 OPENCODE_AUTH_CONTENT，值就是 auth.json 文件的内容。

系统钥匙串（Keychain）是 macOS 提供的安全凭证存储服务，用于集中保存密码、令牌和证书，并通过访问控制列表限制哪些应用可以读取特定条目。Claude Code 在 macOS 上会把 OAuth 登录令牌写入钥匙串而非普通文件，因此 OpenHands 复用登录态时需要调用系统 API 读取钥匙串条目，而不是简单读取某个 JSON 文件。这也意味着在无图形界面的 CI 环境或容器中，钥匙串不可用，必须改用环境变量或显式传入凭证文件内容。理解这一点有助于排查“本机明明登录过却提示未认证”的问题。

模型列表改由 Agent 上报

以前 Canvas 自己写死一份清单，换了套餐或 Key，界面还显示过时的型号。现在本地后端会拉起一次 agent server，询问它有哪些模型、默认用哪个，结果缓存起来。于是 Codex 显示的是你实际订阅的型号，OpenCode 的免费档和付费档也不再是同一份清单。

模型列表的来源也跟着改了

模型路由器（Model Router）是 v1.25.0 引入的机制，指在多个模型或 provider 之间根据任务类型、成本或可用性自动选择并分发请求的中间层。它不同于简单的默认模型设置：路由器可以在一次会话中针对不同请求切换后端，例如将轻量任务交给免费模型、复杂推理交给付费模型。当模型列表改由 agent 上报后，路由器的可选集合也随之动态化，不再依赖 Canvas 中写死的静态清单，从而避免套餐变更后界面与实际可用模型不一致的问题。

21 天版本脉络

v1.25.0（10 月 6 日）：模型路由器、语音听写、工作区文件发现可配置。
v1.26.0（10 月 8 日）：后端挂起时给出解释并支持一键切换，官方验证技能铺开。
v1.27.0（10 月 12 日）：OpenCode 与 PI 进入内置列表，模型列表交给 agent 上报。
v1.27.1：热补丁，补进项文件、警告样式跟随主题。
v1.28.0：对话内申请密钥，输出改为逐字淡入的流式效果。

内置 Agent 之外的三个变化

自动化方面补上了草稿流，草稿可持久化管理，设置分了栏，agent 能辅助填表，草稿保存失败时也会显示服务端给出的原因。浏览器在 v1.27.0 加了录屏能力，验证流程可以直接留下视频证据，不再只有一行日志。DeepSeek^广告进入了官方验证链路——v1.26.0 起官方用模拟模型跑端到端行为，v1.27.0 把这套流程跑在 DeepSeek 上，还把差距映射成清单。这是给国内用户的一个信号：官方验证链路里已经在跑国产模型了。

值得留意的六条修复

手机端文件发现弹窗适配了屏宽；切换后端后设置页显示真实值而非旧值；云沙箱挂起后 resume 能直接唤醒，暂停任务可以接上；运行时未就位时消息会等待而非直接失败；自动化草稿被拒会显示服务端原因；深色模式下拉菜单的对比度修好了。另外，拖入的文件夹现在真正可用，本地路径会解析成输入框里的引用标签；标签页反复聚焦不再触发云端限流；手机切到后台时连接会干净断开。

运行时未就位时消息会等待

升级建议

本地跑 OpenHands 的话，升级理由只有一条：OpenCode 与 PI 能直接当后端了。只用云端服务的话，拿到的是那三家主流 provider，收益有限。顺带还能把模型换成国内的——OpenCode 本身支持 DeepSeek、通义千问^广告、智谱 GLM、月之暗面 Kimi，在 OpenCode 里登录好，OpenHands 会自动复用登录态；要显式给 Key，就在 Secrets 里加一条名字与环境变量完全一致。

这轮更新体现了 OpenHands 的一个明确方向：不做 agent 本身，而是做 agent 的编排层，通过 ACP 把外部 coding agent 统一接入。对已经在用 Claude Code 或 OpenCode 的开发者来说，迁移成本正在变得可以忽略。