OpenHands：82.5K Star 的自主编码 Agent 框架，SWE-bench 77.6% 是怎么做到的

一个被低估的真相：Coding Agent 真正的瓶颈不是模型能力，而是"工作流编排"

用过 Claude Code、Kotori、或其他 Coding Agent 的人都有同感——让 Agent 修一个简单 bug 还行，但让它独立完成一个完整的功能模块、从理解代码到写测试再到提交 PR，Agent 就会开始"迷路"。一会儿读错了文件，一会儿忘了中间状态，一会儿又跑偏了方向。

OpenHands 的思路很聪明：不卷模型，卷工作流。它承认 LLM 已经很聪明了，真正的问题是"如何把智能转化为可执行的、有状态的、有回滚能力的工作流"。正是这种对"自主性"的理解，让 OpenHands 在短短两年内拿下 82,510 Star，并在 SWE-bench 基准测试中取得了 77.6% 的分数——这意味着它能在真实开源仓库上自动修复约 3/4 的问题。

核心架构：一个 SDK + 一个 Agent Server + 一个 Canvas 控制台的铁三角

OpenHands 的代码库分布在几个关键仓库中，它们共同构成了一套完整的自主 Agent 开发框架：

工作流：Agent 如何独立完成一个任务

OpenHands Agent 的工作流远比简单的"对话-响应"要复杂。它遵循一个标准的感知-规划-执行-反思循环：

用户指令（"修复登录接口的内存泄漏"）
    ↓
[感知] 读取代码库 → 理解文件结构 → 定位问题区域
    ↓
[规划] 生成任务分解 → 子任务列表（分析代码 → 找到根因 → 编写修复 → 测试验证）
    ↓
[执行] 逐个执行子任务：
  - 使用 FileEditorTool 读取文件
  - 使用 TerminalTool 运行测试
  - 使用 LLM 生成修复方案
    ↓
[反思] 检查测试是否通过 → 失败则调整策略 → 成功后生成 PR
    ↓
输出：修复代码 + 提交说明 + PR 描述

这个循环的核心在于状态管理——Agent 会记住它做了什么、读过了哪些文件、试过什么方案、失败了的原因是什么。正是这种"记忆"能力，让 Agent 可以处理多步骤的复杂任务，而不是每次调用都是全新的。

三大技术亮点

① EPH（Ephemeral Workspaces）：隔离的 Docker 工作区

OpenHands 最聪明的设计之一是临时工作区。Agent 不在你的本地机器上直接操作代码，而是在一个隔离的 Docker 容器中运行。这意味着：

• 安全——Agent 没有你主机的 filesystem 访问权限，只能访问指定的项目目录
• 干净——每次任务都是从干净的容器开始，不会污染本地环境
• 可复现——任务的环境（依赖、工具链）是确定的，不会"在我机器上没问题"
• 分布式——Agent Server 可以部署在远程机器上，你的本地只是控制台

② ACP（Agent-Client Protocol）：Agent 通信的统一协议

OpenHands 设计了一个轻量级的Agent-Client Protocol，让不同的 Agent 和客户端可以互相通信。这是 OpenHands 能支持"任意 Agent"的关键：

• OpenHands Agent 本身是 ACP 兼容的
• Claude Code、Codex、Gemini 等第三方 Agent 也可以通过 ACP 适配接入
• Agent Canvas 可以统一管理多个不同来源的 Agent

这就像 TCP/IP 协议让不同的网络设备可以互联，ACP 让不同的 Agent 可以在同一个工作流中协作。

③ 任务分解与自修正：从"单步对话"到"多步自主"

这是 OpenHands 在 SWE-bench 上取得高分的关键。当用户提交一个 issue 时，OpenHands 会：

1. 自动分解任务——把一个复杂 issue 拆解为多个原子步骤（如：先理解代码结构 → 定位问题 → 设计修复方案 → 编写代码 → 运行测试 → 提交 PR）
2. 独立执行每个步骤——每一步都是一个完整的感知-规划-执行-反思循环
3. 失败自动回退——如果某一步测试失败，Agent 会分析错误原因，调整策略，重新尝试，而不是简单地报错停止
4. 生成完整 PR——任务完成后，自动生成符合规范的 commit message 和 PR 描述

对比：OpenHands vs 传统 Coding Agent

踩坑指南：真实部署中的三个问题

在实际搭建 OpenHands 框架的过程中，我发现以下三个问题需要特别注意：

坑 1：Docker 工作区的依赖配置

当你使用 Docker 临时工作区时，Agent 需要在容器内安装各种开发依赖（Python 版本、node、git、测试工具等）。如果配置不当，Agent 会因为"缺少依赖"而失败，即使你的本地机器上这些工具都安装好了。

解决：在 agent-server 的配置中定义 custom Docker image，预装所有你可能需要的工具。或者使用 OpenHands 提供的 openhands/agent-server 镜像，它已经预装了常见依赖。

坑 2：LSTM 上下文限制在多步任务中的累积

虽然 OpenHands 有状态管理，但随着任务步骤的增加，对话上下文会越来越长。当运行超过 10-15 步的任务时，LLM 开始忽略早期的指令和上下文，导致 Agent"遗忘"了最初的任务目标。

解决：使用 摘要机制——在每一步完成后，让 Agent 用一句话总结当前的状态和下一步计划，然后把这个摘要而非完整的对话历史传递给下一步。OpenHands SDK 中已经有 TaskTrackerTool 可以帮助管理任务状态。

坑 3：Agent Canvas 的认证与权限配置

当你把 Agent Canvas 部署到远程服务器或云环境时，默认的配置可能会暴露安全风险。Agent Server 有文件系统访问权限，如果未经过认证就公开访问，后果很严重。

解决：严格遵循 SELF_HOSTING.md 中的安全指南：

• 设置 AUTH_ENABLED=true 启用认证
• 使用 reverse proxy（如 Nginx）+ HTTPS
• 限制 Agent Server 只能访问白名单目录
• 定期更新 Agent Server 镜像到最新版本

# 安装 Node.js 22+ 和 npm
# 安装 Agent Canvas（需要 npm）
npm install -g @openhands/agent-canvas

# 启动
agent-canvas

# 浏览器访问 http://localhost:8000
# 然后配置你的 LLM API Key（OpenAI / Claude / Gemini 等）
# 开始写任务："帮我写一个 Python Web 框架的例子"

export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 8000:8000 \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.6.1

git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool
from openhands.tools.llm import LLMTool

# 配置 LLM
llm = LLM(
    model="gpt-4o",
    api_key=os.getenv("LLM_API_KEY"),
    max_tokens=4096,
)

# 创建 Agent，赋予它必要的工具
agent = Agent(
    llm=llm,
    tools=[
        FileEditorTool.name,
        TerminalTool.name,
        TaskTrackerTool.name,
        LLMTool.name,  # 让 Agent 可以自我提问和反思
    ],
    max_iterations=50,  # 最大迭代步数
)

# 指定工作目录
cwd = "/path/to/your/project"

# 创建对话并开始任务
conversation = Conversation(agent=agent, workspace=cwd)
conversation.send_message("分析这个项目的依赖，找出过时的库并建议更新方案。")
conversation.run()

print(f"完成！总共执行了 {len(conversation.messages)} 步。")