OpenHands：74K+ Star

简介 #

大多数 AI 编程工具止步于"建议"。你拿到一段补全代码，粘贴进去，祈祷它能跑通。OpenHands 走的是不同的路：它是一个完整的软件工程代理，会读取你的代码库、编辑文件、跑测试，反复迭代直到任务通过。凭借超过 74,000 个 GitHub Star，在 SWE-bench Verified 上拿到 72% 的分数，它是生产环境里部署最广的开源编程代理。

这份指南带你走完在本地安装 OpenHands、接入你偏好的 LLM 服务商、和 GitHub 集成，以及以无头模式跑在 CI/CD 流水线里的全过程。无论你想要一个处理日常任务的本地 AI 工程师，还是一个批量解决 issue 的自主代理，这篇教程都用真实命令和配置覆盖了每一步。

OpenHands 是什么？ #

OpenHands（前身是 OpenDevin）是一个开源 AI 软件工程代理，跑在 Docker 容器里。它用控制器-沙箱架构：一个基于 Python 的控制器管理代理循环（观察、思考、行动），隔离的沙箱容器负责代码执行、文件操作和测试运行。

核心能力包括：

• 自主任务执行：给它一个 GitHub issue 或自然语言任务，它能端到端地解决
• 沙箱化代码执行：所有代码都在 Docker 容器内运行，和主机隔离
• 多代理委派：复杂任务会被拆分给专门的子代理
• 自带模型支持：支持 Claude、GPT、Gemini、通过 Ollama 或 vLLM 跑的本地模型，以及通过 LiteLLM 接入的 100+ 服务商
• 无头模式：面向 CI/CD 和批处理的编程化 API 访问
• 网页界面 + CLI：既有基于浏览器的界面，也有以终端为主的工作流

OpenHands 是怎么工作的 #

它的架构有两个主要组件：

控制器节点：一个 Python 服务器，管理代理循环，通过 LiteLLM 处理 LLM 抽象层，协调沙箱的生命周期。它接收任务，拆解成步骤，调用 LLM 做决策，并在多次迭代之间追踪状态。

沙箱容器：每个任务生成一个 Docker 容器，所有代码执行都在这里发生。代理在这个隔离环境里读取文件、运行 shell 命令、执行测试、编写补丁。任务完成后，沙箱会被销毁。

代理循环遵循这个模式：

1. 观察：读取任务描述、代码库状态、之前的行动结果
2. 思考：LLM 生成一个计划（编辑哪个文件、跑什么命令）
3. 行动：执行计划好的操作（read_file、write_file、run_cmd 等）
4. 观察：捕获结果（输出、错误、测试结果）
5. 重复：迭代直到任务完成或达到最大迭代次数

这个循环通常每个任务要跑 30-50 次 LLM 调用。内存压缩器（v1.5 新增）会总结较旧的上下文，让上下文窗口保持聚焦，提升长任务的延迟表现并减少 token 消耗。

安装与配置 #

前置条件 #

安装 OpenHands 之前，确保你有：

• 已安装并运行的 Docker Desktop（需要 Docker socket 访问权限）
• 4GB+ 内存（并发会话建议 8GB）
• Python 3.12+（用于通过 uv 安装 CLI）
• 一个 LLM API key（Anthropic、OpenAI、Google，或本地模型端点）

方式一：用 uv 安装 CLI（推荐） #

跑起 OpenHands 最快的方式是通过基于 uv 的 CLI 安装器：

# 如果没有 uv 先安装它
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 OpenHands
uv tool install openhands --python 3.12

# 启动图形界面服务
openhands serve

服务会跑在 http://localhost:3000。打开浏览器，选择你的 LLM 服务商，输入你的 API key，就可以开始分配任务了。

之后升级：

uv tool upgrade openhands --python 3.12

方式二：直接用 Docker 运行 #

如果你不想装 Python 工具，更倾向直接用 Docker：

# 拉取最新镜像
docker pull ghcr.io/openhands/openhands:latest

# 挂载 Docker socket 运行（沙箱管理必需）
docker run -it --rm \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/openhands/openhands:latest \
  ghcr.io/openhands/openhands:latest

--mount-cwd 参数会把你当前工作目录挂载进沙箱：

openhands serve --mount-cwd

对于 GPU 加速的本地模型：

openhands serve --gpu

方式三：pip 安装 #

pip install openhands-ai

# 启动网页界面
openhands serve

Windows 配置说明 #

在 Windows 上，所有命令都要在 WSL2（Ubuntu）里运行：

# 以管理员身份打开 PowerShell
wsl --install -d Ubuntu
wsl -d Ubuntu

然后在 WSL 内：

# 先安装 Docker Desktop for Windows，然后：
uv tool install openhands --python 3.12
openhands serve

配置与第一个任务 #

配置你的 LLM 服务商 #

启动 OpenHands 后，在设置面板（齿轮图标）里配置你的模型：

1. 选择服务商：Anthropic (Claude)、OpenAI (GPT)、Google (Gemini) 或本地模型
2. 选择模型：推荐用 anthropic/claude-sonnet-4-20250514 获得最佳效果
3. 输入 API Key：粘贴你服务商的 API key
4. 保存改动

进阶配置：切换到高级设置，用 LiteLLM 的前缀格式设置自定义模型：

anthropic/claude-sonnet-4-5-20250929
openai/gpt-5-2025-08-07
gemini/gemini-3-pro-preview
deepseek/deepseek-chat

用本地模型（Ollama） #

对于需要网络隔离部署的团队：

# 用一个能力够强的编程模型启动 Ollama
ollama run qwen3-coder:32b

# 在 OpenHands 设置里，设置：
# Custom Model: openai/qwen3-coder:32b
# Base URL: http://host.docker.internal:11434/v1
# API Key: ollama（随便填一个值）

运行你的第一个任务 #

在 localhost:3000 打开的界面里：

1. 在聊天框里输入一个任务：“给 app.py 里的主函数加一个 docstring”
2. 代理会生成一个沙箱，读取文件，写入 docstring，并确认改动
3. 接受之前先审查一下 diff

对于 GitHub issue 解决：

修复 issue #42 里描述的认证 bug。
克隆仓库，复现错误，实现修复，然后跑测试套件。

与 VS Code、GitHub、Docker、CI/CD 集成 #

通过 Agent Control Plane (ACP) 集成 VS Code #

OpenHands v1.5+ 包含用于 IDE 集成的 Agent Control Plane：

# 安装 OpenHands VS Code 扩展
# 在 VS Code 扩展市场里搜索 "OpenHands"

# 配置扩展连接到你本地的 OpenHands 服务
# Settings > OpenHands > Server URL: http://localhost:3000

ACP 协议让 VS Code 能直接把任务发给 OpenHands，并以 diff 补丁的形式接收结构化的编辑结果。

GitHub 集成 #

把 OpenHands 接入你的 GitHub 仓库，实现自动化 issue 解决：

# 设置一个细粒度的 GitHub PAT（个人访问令牌）
export GITHUB_TOKEN=ghp_your_token_here

# 用 GitHub 凭证启动 OpenHands
docker run -it --rm \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  ghcr.io/openhands/openhands:latest

在界面里，粘贴一个 GitHub issue 的 URL，OpenHands 就会：

1. 克隆仓库
2. 读取 issue 描述
3. 复现 bug
4. 实现修复
5. 跑测试验证
6. 生成一份 diff 供审查

GitLab 集成 #

GitLab 支持（v1.5 新增）用法类似：

export GITLAB_TOKEN=glpat-your-token
docker run -it --rm \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITLAB_TOKEN=$GITLAB_TOKEN \
  ghcr.io/openhands/openhands:latest

生产环境用 Docker Compose #

对于持久化部署，用 Docker Compose：

version: "3.8"
services:
  openhands:
    image: ghcr.io/openhands/openhands:latest
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./workspace:/workspace
    environment:
      - SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/openhands/openhands:latest
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_MODEL=anthropic/claude-sonnet-4-20250514
      - SANDBOX_NETWORK_DISABLED=true
      - LOG_LEVEL=info
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

部署：

docker-compose up -d

面向 CI/CD 流水线的无头模式 #

无头模式不带交互界面运行 OpenHands，非常适合自动化：

# 以无头模式跑一个任务
openhands --headless -t "Write unit tests for the auth module"

# 从文件加载任务
openhands --headless -f task.txt

# JSON 输出便于流水线解析
openhands --headless --json -t "Fix the API endpoint in routes.py" > output.jsonl

GitHub Actions 工作流示例：

name: OpenHands Auto-Fix
on:
  issues:
    types: [labeled]
jobs:
  fix:
    if: github.event.label.name == 'auto-fix'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run OpenHands
        run: |
          docker run --rm \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v $(pwd):/workspace \
            -e LLM_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
            ghcr.io/openhands/openhands:latest \
            openhands --headless --json \
            -f .openhands/task.txt > results.jsonl

MCP 服务器集成 #

OpenHands 支持 Model Context Protocol (MCP) 服务器来扩展能力：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  }
}

性能测试 / 真实使用场景 #

SWE-bench Verified 表现 #

SWE-bench Verified 用 500 个真实 GitHub issue 测试代理。分数越高，意味着代理能自主解决更多生产环境的 bug。

每次成功修复的成本 #

对于一个消耗约 5.5 万 token 的典型 SWE-bench 任务：

真实部署指标 #

基于社区反馈的生产环境部署数据：

• Issue 解决率：被标记的 bug 中有 30-40% 首次尝试就能自主解决
• 代码审查辅助：200 行以下的 PR 审查时间减少 60%
• 测试生成：用"给 X 写测试"这类提示词，新模块能达到 80%+ 的覆盖率
• 文档编写：docstring 和 README 生成任务的准确率超过 90%

使用 OpenHands 的公司 #

AMD、Apple、Google 和 Netflix 都已在内部部署 OpenHands 用于自动化维护任务。最常见的用例是跨多个仓库的依赖升级、漏洞修复扫荡，以及 PR 审查自动化。

进阶用法 / 生产环境加固 #

安全检查清单 #

运行一个能自主执行代码的代理，需要谨慎的安全配置：

1. 沙箱网络隔离

environment:
  - SANDBOX_NETWORK_DISABLED=true

这能防止沙箱容器发起出站请求。只在需要安装依赖包的任务上选择性开启。

2. Docker Socket 安全

Docker socket 挂载实际上相当于 root 访问权限。用这些手段缓解风险：

docker run --security-opt no-new-privileges \
  --cap-drop ALL \
  --cap-add SYS_ADMIN \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/openhands/openhands:latest

3. 细粒度 GitHub PAT

永远不要用组织级全权限 token。把 PAT 限定到特定仓库：

# 在 GitHub > Settings > Developer settings 创建细粒度 PAT
# 只勾选：Contents（读/写）、Issues（读）、Pull Requests（写）

4. 密钥管理

把密钥挂载成只读卷，而不是环境变量：

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - /opt/secrets:/secrets:ro
environment:
  - LLM_API_KEY_FILE=/secrets/anthropic_key

多代理委派 #

对于大型功能，开启多代理模式：

# 在 config.toml 里或通过环境变量
[agent]
enable_multi_agent = true
max_subagents = 3

一个父代理会把"搭建一个带认证的 REST API"拆解成：

• 子代理 1：实现 API 端点
• 子代理 2：编写认证中间件
• 子代理 3：创建数据库模型

内存压缩器调优 #

对于长时间运行的任务，调整内存压缩器：

[llm]
enable_condenser = true
condenser_max_history = 240  # 240 个事件后开始摘要（默认：240）

监控与日志 #

开启结构化 JSON 日志以实现可观测性：

openhands --headless --json -t "Your task" 2>&1 | tee openhands.log

解析日志获取指标：

# 统计 LLM 调用次数
jq 'select(.type == "llm")' openhands.log | wc -l

# 查找错误
jq 'select(.type == "error")' openhands.log

# 计算任务耗时
jq 'select(.type == "finish") | .timestamp' openhands.log

用 Kubernetes 扩展 #

面向团队部署，社区维护了一个 Helm chart：

# 添加 OpenHands Helm 仓库
helm repo add openhands https://charts.openhands.dev
helm repo update

# 用自定义值安装
helm install openhands openhands/openhands \
  --set llm.apiKey=$LLM_API_KEY \
  --set llm.model=anthropic/claude-sonnet-4-20250514 \
  --set sandbox.networkDisabled=true \
  --set replicas=2

与其他方案对比 #

该怎么选 #

• OpenHands：你需要一个自托管、支持沙箱化执行和多代理的自主代理，想要对基础设施和模型选择有完全控制权。
• Claude Code：你想要最高的首次通过成功率，已经在用 Claude，不需要自托管，更喜欢没有 Docker 复杂度的简单 CLI。
• Aider：你常年泡在终端里，想要 Git 原生操作、自动提交，需要一个没有容器开销的轻量工具。
• Codex CLI：你深度嵌入 OpenAI 生态，想要官方 VS Code 支持，更偏好托管服务。

局限性 / 真实评估 #

OpenHands 并不适合所有场景。以下是它不擅长的地方：

1. 需要视觉反馈的前端/UI 任务：代理"看不到"渲染出来的效果。“把这个按钮居中"或"修一下 CSS 渐变"这类任务往往需要多次迭代，因为代理缺乏视觉验证能力。

2. 快速原型开发：Docker 沙箱启动每个任务会增加 10-30 秒延迟。对于快速的一次性修改，Aider 或 Cursor 会更快。

3. 没有 Docker 的小型机器：如果你没法跑 Docker Desktop（企业锁定的笔记本、ARM Chromebook），OpenHands 就用不了。Docker socket 挂载是硬性要求。

4. 模糊的需求：“改进代码库"或"重构出更好的架构"这类任务会让代理陷入循环。它需要具体、可测试的指令。

5. 复杂任务的 token 成本：每个任务要烧 30-50 次 LLM 调用。Claude Sonnet 每次调用约 0.01 美元，一个任务就是 0.30-0.50 美元。对于大批量处理，成本会很快累积。

6. 学习曲线：多代理系统、事件流和配置选项都很强大，但相比 Devin 两分钟的注册流程会让人有点招架不住。预计要花 1-2 小时配置和试验才能真正上手。

常见问题 #

跑 OpenHands 需要什么硬件？ #

最低要求是现代 CPU、4GB 内存和 Docker Desktop。跑本地模型的话，需要至少 24GB 显存的 GPU（RTX 4090 或更好）才能以能接受的速度跑 Qwen3-Coder-32B。用云端 API 模型的话完全不需要 GPU。

OpenHands 能完全离线运行吗？ #

能，通过 Ollama、vLLM 或 LM Studio 用本地模型。把 base URL 设成你的本地端点（比如 http://localhost:11434/v1），API key 随便填一个值。复杂任务的表现会比前沿 API 落后 20-30%，但日常 bug 修复和重构完全够用。

OpenHands 和 Devin 比怎么样？ #

Devin（每月 20-500 美元）配置更简单（2 分钟注册），但会把你锁定在 Cognition 的模型和基础设施里。OpenHands 需要 10-15 分钟配置，但给你完全的模型选择权、自托管能力，没有厂商锁定。在 SWE-bench Verified 上，OpenHands 拿到约 72%，Devin 约 50%。

我的代码用 OpenHands 安全吗？ #

代码跑在 Docker 沙箱容器里，每个任务结束后容器就会被销毁。设置 SANDBOX_NETWORK_DISABLED=true 后沙箱就没有网络访问权限。不过挂载 Docker socket 会给控制器相当大的主机访问权限，所以 OpenHands 应该跑在专用机器或虚拟机上，而不是你的生产笔记本。

我能把 OpenHands 接入现有的 CI/CD 流水线吗？ #

能，通过无头模式。--headless --json 参数会产出结构化的 JSONL 输出，任何 CI 系统都能解析。一个典型的 GitHub Actions 工作流会克隆仓库，对被标记的 issue 跑 OpenHands，再从生成的 diff 创建 PR。

哪些模型和 OpenHands 搭配最好？ #

对大多数任务来说，Claude Sonnet 4.6 在成本和质量之间平衡得最好。Claude Opus 4.6 准确率最高，但 token 成本是前者的 3-4 倍。GPT-5 对已经在用 OpenAI 的团队效果不错。本地部署的话，Qwen3-Coder-32B 或 Devstral 24B 是最好的开放权重选择。

OpenHands 卡在循环里怎么调试？ #

查看界面里的事件日志，找重复失败的操作。常见的解决办法：(1) 提供更具体的指令，(2) 换用更强的模型，(3) 把任务拆成更小的子任务，或 (4) 在设置里调高 max_iterations 限制。

结语 #

OpenHands 是 2026 年能力最强的开源 AI 软件工程代理。它 74,000+ 的 GitHub Star、72% 的 SWE-bench 分数，加上 Docker 沙箱化架构，让它成为需要自主编程能力、又不想被厂商锁定的团队的正确选择。

配置只需 10-15 分钟：通过 uv 或 Docker 安装，配置你的 LLM 服务商，开始分配任务。生产环境使用时，开启沙箱网络隔离，用细粒度的 GitHub PAT，并部署无头模式实现 CI/CD 集成。

下一步：

1. 克隆仓库：git clone https://github.com/OpenHands/OpenHands.git
2. 通过 uv tool install openhands --python 3.12 安装
3. 用 openhands serve 启动，在 localhost:3000 连接
4. 加入 Slack 社区获取支持和功能更新

推荐的托管与基础设施 #

在把上面这些工具部署到生产环境之前，你需要靠谱的基础设施。以下两个是 dibi8 实际在用、并推荐的方案：

• DigitalOcean — 60 天 200 美元免费额度，覆盖 14+ 全球区域。独立开发者跑开源 AI 工具的默认选择。
• HTStack — 香港 VPS，大陆访问低延迟。dibi8.com 本身就托管在这家 IDC——生产环境实测过硬。

以上为联盟链接——不会让你多花一分钱，但能帮 dibi8.com 持续运营下去。

来源与延伸阅读 #

• OpenHands GitHub 仓库 — 源码与发布记录
• 官方文档 — 完整配置和 API 文档
• OpenHands LLM 配置指南 — 模型推荐与服务商配置
• 无头模式文档 — CI/CD 与脚本参考
• SWE-bench 排行榜 — 官方基准测试结果
• LiteLLM 服务商文档 — 支持的模型服务商
• OpenHands 社区论坛 — 问答与故障排查
• Agent Control Plane 文档 — VS Code 集成和多代理配置

本指南独立维护，定期更新。最后核实时间：2026 年 5 月。

参考与来源 #

• OpenHands
• OpenHands Documentation
• LiteLLM
• Ollama
• vLLM
• Aider
• SWE-bench
• Model Context Protocol
• uv