OpenHands：开源AI软件工程师Agent安装与使用指南

一、项目背景

2024 年 3 月，Cognition AI 发布 Devin 演示视频——一个 AI 自己打开浏览器、写代码、跑测试、修 bug，像一个真正的初级工程师。整个开发者圈炸了。但 Devin 闭源且昂贵。一个月后，CMU、斯坦福、北大等机构的研究者联合推出了 OpenDevin，目标是做开源版 Devin；2024 年底项目改名为 OpenHands，由 All-Hands-AI 团队维护。

OpenHands 不是简单的代码补全工具，而是一个完整的"AI 软件工程师"：它运行在 Docker 沙箱里，能读写你本地的代码仓库、执行 shell 命令、跑测试、用浏览器查文档、调用 Jupyter 调试。你用自然语言说"修复这个 issue 并提个 PR"，它就会自己 clone 仓库、定位问题、改代码、跑测试、推分支、在 GitHub 上开 PR。

OpenHands 在 SWE-Bench 评测上成绩长期名列前茅，已经被字节、阿里、腾讯等公司内部用于自动化修 bug。它同时提供 Web UI、CLI、Python SDK、Headless 模式，是目前最成熟的开源 Coding Agent。

二、核心特性

• 完整软件工程环境：沙箱里预装 Python、Node、Ruby、Java、编译器、Git。
• 多 Action 工具集：Bash、FileEdit、FileRead、Browse、IPython、Task 等。
• GitHub 集成：自动 clone issue 对应仓库、提 PR、评论。
• 浏览器工具：内置 Playwright，能自己上网查文档、登网站。
• 事件流可观测：每一步思考、动作、观察都记录，可回放。
• 多 LLM 后端：Claude、GPT-4o、DeepSeek、Qwen、本地模型。
• Headless / CLI / Web 三种模式：可嵌入 CI/CD，也可人工协同。
• 沙箱安全隔离：所有命令在 Docker 里跑，不碰主机。

三、环境要求

• Docker：Docker 24+（必须，OpenHands 自身跑在容器里，再 spawn 子容器）。
• 操作系统：Linux / macOS（Windows 需 WSL2）。
• 内存：8 GB 起步，推荐 16 GB。
• 磁盘：20 GB+。
• LLM API Key：强烈推荐 Claude 3.5/4 Sonnet 或 GPT-4o；DeepSeek-V3 性价比高。

四、详细部署步骤

方式一：Docker 一键启动（推荐）

docker pull docker.all-hands.dev/all-hands-ai/openhands:0.32-nikolaik

docker run -it --rm \
  --pull=always \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.32-nikolaik \
  -e LOG_ALL_EVENTS=true \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:0.32-nikolaik

启动后访问 http://localhost:3000。

注意：挂载了 /var/run/docker.sock，意味着 OpenHands 容器可以在你的主机上再 spawn 子容器。这是设计如此（它需要沙箱跑代码），但请不要在不可信网络下公网暴露 3000 端口。

方式二：从源码跑开发版

git clone https://github.com/All-Hands-AI/OpenHands.git
cd OpenHands

# 安装前端与后端依赖
make build

# 启动
make run

方式三：pip 安装 SDK

pip install -U openhands-sdk openhands-tools openhands-workspace

配置 LLM

Web UI 启动后，右上角 Settings → LLM，填入：

• Provider：OpenAI / Anthropic / DeepSeek / Ollama
• API Key：你的 Key
• Model：如 claude-3-5-sonnet-20241022 或 gpt-4o 或 deepseek-chat

用 DeepSeek：

# 在 .env 或 UI Settings 里
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-xxxx
LLM_BASE_URL=https://api.deepseek.com/v1

跑第一个任务

1. Web UI 点击 "New Conversation"。
2. 选择一个本地目录或 GitHub 仓库。
3. 输入任务，例如："请阅读 main.py，找出为什么单元测试 test_add 失败，并修复它。"
4. 观察 OpenHands 自己执行：浏览文件 → 读代码 → 跑 pytest → 修改 → 再跑。
5. 满意后点 "Push Branch" 推到 GitHub。

Headless 模式（CI/CD 自动化）

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LLM_API_KEY=sk-xxxx \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  docker.all-hands.dev/all-hands-ai/openhands:0.32-nikolaik \
  python -m openhands.cli --task "修复 issue #123"

五、进阶生产部署建议

5.1 资源与安全加固

OpenHands 需要挂载 docker.sock，相当于容器拥有了在主机上启动任意容器的能力。生产部署请务必：

• 用非 root 用户运行容器；
• 在 docker run 加 --memory=8g --cpus=4；
• 不要把 3000 端口暴露到公网，前面加 Nginx + OIDC；
• 定期更新镜像到最新 patch 版本。

5.2 搭配 GitHub App 自动修 PR

在 Settings → GitHub 里创建一个 GitHub App，授予 contents:write、issues:read、pull_requests:write 权限。之后只要在 issue 评论 @openhands fix this，OpenHands 就会自动开 PR。

5.3 模型选择建议

OpenHands 在 SWE-Bench 上的成绩对模型非常敏感。推荐组合：

• 性价比：DeepSeek-V3 / Qwen2.5-Coder-32B；
• 效果最佳：Claude 3.5/4 Sonnet、GPT-4o；
• 本地：Qwen2.5-Coder-32B-Instruct via vLLM。

六、使用方法示例

搭配 GitHub Issue 自动修 bug：在 UI 里连接 GitHub Token，输入 issue URL，OpenHands 会自动开 PR。

Python SDK 调用：

from openhands.sdk import OpenHands
agent = OpenHands(model="claude-3-5-sonnet-20241022")
result = agent.run_task("在 /workspace 里写一个快速排序并跑通测试", workspace="./myproj")
print(result.final_state)

典型任务示例：

• "把这个 Flask 项目升级到 Flask 3.0，修复所有 deprecation warning。"
• "为 utils.py 补全单元测试，目标覆盖率 80%。"
• "把 README 翻译成英文，并补一张架构图。"

默认账号密码：本地 Web UI 默认无登录，任何能访问 3000 端口的人都能用。公网部署务必加反向代理 + Basic Auth 或 OIDC。

七、常见问题（FAQ）

Q1：容器启动报 docker.sock 权限错误？

把当前用户加入 docker 组：sudo usermod -aG docker $USER，重新登录。

Q2：跑一个任务要花多少钱？

用 Claude 3.5 Sonnet 修一个中等 issue 大约 0.5-3 美元；用 DeepSeek-V3 大约 0.1-0.5 元人民币。建议先设预算上限。

Q3：OpenHands 会把我主机搞坏吗？

它在子 Docker 容器里跑所有命令，文件系统也挂载在隔离目录。但它能调用 docker.sock，理论上有权限做更多事。生产环境建议加资源限制。

Q4：和 Devin、Cursor 比？

OpenHands 是开源、可自托管、可二次开发；Devin 闭源 SaaS；Cursor 是 IDE 插件偏交互式。OpenHands 适合做自动化流水线，Cursor 适合人在回路。

Q5：SWE-Bench 成绩如何？

OpenHands 在 SWE-Bench Verified 上长期保持 30%+ 解决率，是开源 Coding Agent 第一梯队。

Q6：支持哪些编程语言？

沙箱镜像里预装了 Python 3、Node.js、Ruby、Java、Go，主流语言都能跑。其他语言可以在沙箱里现装。

Q7：和 Cursor、GitHub Copilot Workspace 比？

OpenHands 是完全自主的 Agent，你给任务它自己干，适合自动化流水线；Cursor 是 IDE 插件，人在回路里写代码；Copilot Workspace 偏 PRD→代码草稿。OpenHands 适合"扔个 issue 等 PR"，Cursor 适合"我写代码 AI 帮忙"。

八、跳转链接

• GitHub 仓库：https://github.com/All-Hands-AI/OpenHands
• 官方文档：https://docs.all-hands.dev/
• 官网：https://www.all-hands.dev/
• Docker 镜像：OpenHands Docker
• 论文：OpenHands: An Open Platform for AI Software Developers