6 万 Star 的 OpenHands 源码解析(一):那个最火的开源 AI 程序员,正在＂拆掉＂自己

第一篇先不讲某个函数。

先看 README 的前 55 行：OpenHands 已经不再把自己描述成“一个会写代码的 AI”，而是写成了 self-hosted developer control center。它可以运行 OpenHands、Claude Code、Gemini 等第三方 agent，或者任何 ACP-compatible agent。

更直接的是那句：The code in this repo is moving!

OpenHands Agent 和 Agent Server 的源码，已经迁到 OpenHands/software-agent-sdk；Agent Canvas 的源码，则在 OpenHands/agent-canvas。

这不是一句普通的项目介绍变更。它意味着：这个 78K+ Star 的仓库，正在从“单体 AI 程序员”变成一个 **Agent Canvas 控制中心**。

真正执行代码、跑测试、调用工具、驱动 agent 的部分，正在被搬到数据面；这个仓库留下的核心，是会话、沙箱、事件、密钥、MCP、设置、集成这些控制面能力。

1. README 已经把坐标系改了

README 现在讲的是 Agent Canvas：把 coding agents 变成 self-hosted、always-on 的 engineering team。

它默认能跑 OpenHands agent，也能使用 Claude Code、Gemini 等第三方 agent。

再往下，迁移声明说得更直：

The code in this repo is moving!The source code for OpenHands Agent and Agent Server lives in OpenHands/software-agent-sdk.The source code for Agent Canvas lives in OpenHands/agent-canvas.

这几行决定了本系列的读法。

如果继续按旧思路读 OpenHands，很容易在仓库里找“agent 到底怎么思考、怎么改代码、怎么执行工具”。但现在更重要的问题变成了：

这个仓库如何创建一场对话？
如何选择 docker / process / remote 沙箱？
如何把用户的 LLM 配置、skills、MCP、secrets 装配成一次启动请求？
如何接收 agent-server 回流的事件？
如何让一个不可信的执行环境用上 GitHub token、Tavily API key，却拿不到底牌？

这就是控制面 / 数据面分离。

2. app_server 是控制面，不是 agent 内核

openhands/app_server/ 下的 Python 文件约 33,523 行。目录名已经很说明问题：

app_conversation/sandbox/event/event_callback/mcp/secrets/settings/user/git/integrations/web_client/

这些模块不像一个“agent 运行时”，更像一个平台控制层：

app_conversation
管会话元数据、启动任务、状态查询、模型切换。
sandbox
管 docker / process / remote 这些数据面后端。
event
和 event_callback 管事件落库、回调处理。
mcp
管服务端工具代理。
secrets
和 settings 管用户配置与密钥边界。

入口文件也很直接。openhands/app_server/app.py 创建 FastAPI app，挂载 /mcp，再挂 /api/v1 路由和健康检查。

旧入口 openhands/server/listen.py 现在只剩兼容层：

from openhands.app_server.app import app__all__ = ['app']

文件开头还写着 deprecated，建议直接使用 openhands.app_server.app。

这一刀很关键：读 OpenHands，不应再从旧 server 入口一路追到 agent 内核，而应该从 app_server 看它如何组织一个外部执行系统。

3. 执行内核已经以依赖形式接回来

pyproject.toml 里有三行：

openhands-agent-server==1.29.0openhands-sdk==1.29.0openhands-tools==1.29.0

同一个文件还专门标了 # V1 dependencies。

再看沙箱 spec：默认 agent-server 镜像是：

AGENT_SERVER_IMAGE = 'ghcr.io/openhands/agent-server:1.29.0-python'

这就把边界画清楚了：控制面不再把所有 agent 逻辑揉进自己，而是通过 SDK、agent-server 包和 agent-server 镜像，把执行内核接回来。

创建会话时，启动链路会先等沙箱启动，拿到 agent_server_url，校验 agent-server SDK 版本，构造 StartConversationRequest，最后带 X-Session-API-Key POST 到：

{agent_server_url}/api/conversations

这不是函数调用，是跨边界启动。

控制面负责“准备一次运行所需的一切”；数据面负责“真的运行”。

4. 三条回路把拆开的系统接起来

拆出去以后，系统不能断。OpenHands 用三条回路把 app_server 和 agent-server 接起来。

第一条：Start 请求

AppConversationStartTask 本身就说明了“启动会话不是瞬时操作”。模型里列出 8 个状态：

WORKINGWAITING_FOR_SANDBOXPREPARING_REPOSITORYRUNNING_SETUP_SCRIPTSETTING_UP_GIT_HOOKSSETTING_UP_SKILLSSTARTING_CONVERSATIONREADYERROR

模型注释写得很直接：启动会话可能很慢，因为可能涉及启动沙箱，所以要踢一个 background task。

这条链路的本质是：用户点“开始”，控制面先把沙箱、工作区、LLM、skills、secrets、MCP 全部准备好，再把一个完整请求交给 agent-server。

第二条：事件回流

agent-server 执行过程中产生事件，不是直接塞进前端。它通过 webhook 回到 app_server：

@router.post('/events/{conversation_id}')async def on_event(events: list[Event], conversation_id: UUID, ...)

这个 handler 做三件事：

保存事件。
从 stats / execution_status 事件更新会话元数据。
后台跑 callback processor。

所以 app_server 不是一个薄薄的实时转发层。它更像 event sink：先落事件，再用事件驱动标题生成、终态追踪、集成回写等后续动作。

第三条：能力与密钥

这一条最有意思。

OpenHands 需要让沙箱里的 agent 用上 GitHub token、Tavily 搜索、MCP 工具，但又不能把所有底牌直接交给一个会执行代码的环境。

处理 git provider token 时，它不是直接把明文 token 塞进请求，而是生成一个 JWS access token，然后构造：

LookupSecret(    url=web_url + '/api/v1/webhooks/secrets',    headers={'X-Access-Token': access_token},    description=description,)

沙箱拿到的是“去哪兑换”的票，不是 token 本身。

MCP 也类似。Tavily MCP proxy 的注释直接说：让沙箱使用 Tavily search，但不暴露 API key。

默认 MCP server 会被配成：

{web_url}/mcp/mcp

再带上 conversation id 和 session key。

这就是反向 MCP：工具能力看起来在沙箱里可用，但关键凭证和服务端行为留在 app_server。

5. 它不是“变薄”，而是边界变硬

看到“agent 内核迁走”，容易误以为这个仓库变薄了。源码看下来不是这样。

app_server 仍然有三万多行 Python，复杂度没有消失，只是换了位置：

生命周期复杂度：一次对话要经历启动任务、沙箱状态、agent-server 状态、pending message、归档删除。
安全复杂度：密钥要能用，但不能随便回显；MCP 要能调，但 API key 不能进沙箱。
数据复杂度：事件要落存储，状态要回填，回调要后台跑。
扩展复杂度：同一套 app_server 要服务 OSS、本地、远端、云平台和企业版。

更准确的说法是：OpenHands 正在把“会写代码的那部分”拆出去，把自己变成“管会写代码的系统”。

这也是为什么 README 第一屏现在写的是 developer control center。

6. 亮点和隐患都在边界上

这一版架构的亮点很明显：边界清楚以后，OpenHands 可以同时接 OpenHands Agent、Claude Code、Gemini 等第三方 agent，甚至任何 ACP-compatible agent。

不同 agent 可以共享前端、会话、沙箱、事件、密钥、MCP、集成这些平台能力。

但隐患也在同一个地方。

第一，版本漂移会变成长期问题。源码里专门有 agent-server 版本校验：读取 /server_info，比较 agent-server 报告的 SDK version 和 app 期望版本。这段代码本身就是证据：一旦控制面和数据面分开，版本兼容就从“代码仓库内部问题”变成“跨服务协议问题”。

第二，启动链路会天然变长。从创建 task、等沙箱、准备 workspace、装配 request，到 POST agent-server，每一步都可能失败。

第三，安全边界越硬，越要小心例外路径。LookupSecret、反向 MCP、session key 都是在降低明文泄漏面，但只要 fallback、调试开关、兼容逻辑处理不好，边界就会变软。

结语：先把地图摆正

这一篇只做一件事：把读 OpenHands 的地图摆正。

后面 12 篇都会沿着这张地图往下拆：

对话生命周期：一次 conversation 如何从创建走到归档。
沙箱后端：docker / process / remote 三种数据面如何切换。
event sink：事件如何落库、回调如何驱动后续动作。
安全边界：API key、secrets、session key、MCP 代理如何配合。
前端实时系统：双 WebSocket 栈如何汇到同一份 UI 状态。
企业版：MIT 内核如何叠加成 SaaS 平台。

OpenHands 已经不是“一个 AI 程序员”的单点故事。它更像一个控制中心：把不同 agent、不同沙箱、不同事件源、不同凭证边界，组织成一套可运行的平台。

问题也就来了：

如果“发起一次对话”不再是一次普通 API 调用，而是一个可能启动沙箱、准备仓库、注入能力、等待数据面就绪的长任务，它到底需要怎样的状态机？