OpenHands 完整教程:从安装到自动化实战(v1.40.0)

作者:demo2026.11.17 03:29浏览量:0

简介:OpenHands 不是又一个"对话框式"编程助手,而是把大模型放进 Docker 沙箱里真正动手干活的开源 Agent 平台。本文从环境准备、三种安装方式、模型接入配置,讲到 headless 自动化与常见故障排查,并给出 Token 成本估算思路;模型选型与价格对比可以直接在[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)上完成。

一、OpenHands 到底是什么,和 Cursor、Copilot 有什么不同

大多数 AI 编程工具的工作方式是”你问、它答、你贴代码”。OpenHands(前身 OpenDevin)的核心思路完全不同: 把大模型放进一个可执行环境里,让它自己写代码、跑命令、看报错、再改 。

它的运行结构大致是三层:

层级 作用
Agent(LLM 侧) 负责推理与决策,决定下一步执行什么动作
Agent Server 管理会话、事件流(Event Stream)、上下文与工具调用
Runtime(Docker 沙箱) 真正执行 bash、编辑文件、跑测试、开浏览器的隔离环境

Agent 的行为是一个 动作—观察循环(Action–Observation Loop) :模型输出一个动作(比如 run bash: pytest),沙箱执行后把 stdout/stderr 作为观察结果回灌给模型,模型据此决定下一步。整个过程被记录成事件流,可以回放、可以导出。

这带来三个和补全类工具的本质差异:

  1. 有真实反馈闭环 ——代码能不能跑通由环境判定,而不是由模型”猜”。
  2. 有隔离边界 ——所有危险操作发生在容器里,误删 rm -rf 不会伤到宿主机。
  3. 长任务可自主推进 ——一个 issue 从读代码到改完提交,中间几十轮迭代不需要人逐步确认。

代价也很直接: Token 消耗远高于对话式工具 ,因为每一轮都要把上下文和命令输出重新送进模型。这一点后面会单独讲成本。

二、安装前的准备

  • Docker 24+ 可用(Linux / macOS / WSL2 均可,Windows 原生建议走 WSL2)
  • 至少 4 核 CPU、8 GB 内存,跑前端构建类任务建议 16 GB
  • 一个可用的模型 API Key(OpenAI、Anthropic,或任意 OpenAI 兼容端点)
  • 磁盘预留 10 GB 以上,runtime 镜像本身不小

先验证 Docker 是否正常:

  1. docker version
  2. docker run --rm hello-world

三、三种安装方式,按需求选

方式一:Docker 一键启动(推荐新手)

这是官方主推路径,宿主机只需要 Docker,Agent 和运行时都在容器里:

  1. docker pull docker.all-hands.dev/all-hands-ai/openhands:1.40-nodocker
  2. docker run -it --rm --pull=always \
  3. -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:1.40-nodocker \
  4. -e LOG_ALL_EVENTS=true \
  5. -v ~/.openhands:/.openhands \
  6. -v /var/run/docker.sock:/var/run/docker.sock \
  7. -p 3000:3000 \
  8. --add-host=host.docker.internal:host-gateway \
  9. --name openhands-app \
  10. docker.all-hands.dev/all-hands-ai/openhands:1.40-nodocker

启动后浏览器打开 http://localhost:3000,在 Settings 里填模型名、Base URL 和 API Key 即可开始。

几个参数的含义值得注意:-v /var/run/docker.sock 是把宿主 Docker 暴露给容器,让 Agent 能”套娃”起沙箱容器;~/.openhands 用于持久化会话与配置;--add-host=host.docker.internal 解决容器访问宿主服务的解析问题。

具体镜像 tag 会随版本更新,拉取前建议对照官方文档确认当前可用标签。

方式二:CLI 安装(适合终端党)

  1. # 使用 uv 隔离安装,避免污染系统 Python
  2. uvx --python 3.12 --from openhands-ai openhands
  3. # 或常规安装
  4. pip install "openhands-ai"
  5. openhands

CLI 模式不需要手动起 Web 服务,直接在终端里对话,适合远程服务器和脚本化场景。

方式三:源码模式(二次开发)

  1. git clone https://github.com/All-Hands-AI/OpenHands.git
  2. cd OpenHands
  3. make build && make setup-config && make run

需要改 Agent 策略、加自定义工具或调试事件流时才建议走这条路。

四、配置大模型:这是最容易踩坑的一步

OpenHands 底层用 LiteLLM 做模型路由,所以 任何 OpenAI 兼容的端点都能接 。配置文件 ~/.openhands/config.toml:

  1. [core]
  2. workspace_base = "./workspace"
  3. max_iterations = 50
  4. cache_dir = "~/.openhands/cache"
  5. [llm]
  6. model = "openai/deepseek-chat"
  7. base_url = "https://your-openai-compatible-endpoint/v1"
  8. api_key = "sk-xxxxxx"
  9. temperature = 0.0
  10. max_output_tokens = 8192

关键规则:

  • model 必须带 provider 前缀(openai/、anthropic/、litellm_proxy/),否则 LiteLLM 无法路由。
  • 用第三方兼容端点时,base_url 一定要写到 /v1 这一级,少写或多写都会 404。
  • max_iterations 是 成本闸门 ,不是性能参数。设 50 意味着单个任务最多 50 轮模型调用,超了就中断。

如果你同时想用多家模型做对比测试,逐个改配置文件会很痛苦。这时候可以用词元所的多模型统一 API 接入能力,把不同厂商的模型收敛到一套 API 和 Key 下,OpenHands 侧只需要改 model 字段就能切换,不用为每个供应商单独维护一套鉴权和 SDK。

五、跑通第一个任务

Web UI 里新建会话,输入一个可验证的任务,比如:

  1. 在当前仓库里找到所有 print 调试语句,删掉它们,然后运行 pytest 确认测试仍然通过。

观察 Agent 的执行轨迹,你会看到典型序列:execute_bash(grep 搜索)→ str_replace_editor(改文件)→ execute_bash(跑测试)→ finish。每一步的输入输出都在事件流里,可以展开看。

新手最容易犯的错 是给模糊任务,比如”优化一下这个项目”。Agent 没有验收标准就会无限迭代,直到撞 max_iterations。任务描述里带上 明确的验证方式 (跑哪个命令、期望什么输出),成功率会明显提升。

六、自动化:headless 模式与 CI 集成

交互式使用只是入门,OpenHands 真正的价值在无人值守。

Headless 单次任务

  1. openhands --task "修复 issue #123 并写好单元测试" --max-iterations 30

不同小版本的子命令和参数名会有调整,升级后先跑 openhands --help 确认当前 CLI 契约,不要照抄旧脚本。

接入 GitHub Actions

思路是在 CI 里起一个容器执行 headless 任务,把结果作为 PR 或 artifact 输出:

  1. - name: Run OpenHands
  2. run: |
  3. docker run --rm \
  4. -e LLM_MODEL="openai/your-model" \
  5. -e LLM_API_KEY="${{ secrets.LLM_API_KEY }}" \
  6. -e LLM_BASE_URL="${{ secrets.LLM_BASE_URL }}" \
  7. -e SANDBOX_VOLUMES="${{ github.workspace }}:/workspace:rw" \
  8. -v /var/run/docker.sock:/var/run/docker.sock \
  9. docker.all-hands.dev/all-hands-ai/openhands:1.40-nodocker \
  10. openhands --task "${{ github.event.issue.title }}"

安全提醒: 不要把带写权限的 Token 交给自动触发的公开 issue 工作流 。建议只在 workflow_dispatch 或维护者评论触发时运行,并把沙箱网络出口限制在必要的域名内。

用 MCP 扩展工具集

OpenHands 支持通过 MCP(Model Context Protocol)挂载外部工具,比如数据库查询、内部 Wiki、Jira。在配置里声明 MCP server 后,Agent 就能像调用 bash 一样调用这些工具,不必把逻辑硬写进 prompt。

七、常见问题排查

现象 常见原因 处理方式
启动后卡在 “Waiting for runtime” runtime 镜像没拉下来 / 架构不匹配 手动 docker pull runtime 镜像;Apple Silicon 确认 arm64 标签
沙箱容器起不来 未挂载 docker.sock,或用户无 Docker 权限 补上 -v /var/run/docker.sock:...,或加入 docker 组
401 / 模型不存在 model 缺 provider 前缀、base_url 少了 /v1 按上文规则修正,先用 curl 验证端点
任务老是中途停止 撞到 max_iterations 提高上限,同时把任务拆小、验收标准写清
上下文报超长 命令输出太大(如 cat 大文件、跑全量日志) 提示 Agent 用 head/grep 过滤,或换更大上下文窗口的模型
容器内访问宿主 API 失败 缺少 host-gateway 映射 加 --add-host=host.docker.internal:host-gateway

agent-">八、成本与模型选型:Agent 场景的账要单独算

Agent 的 Token 消耗结构和聊天完全不同。粗略估算:

  1. 总 Token ≈ Σ(每轮上下文长度) ≈ 单轮平均上下文 × 迭代轮数

因为上下文是 累积 的,第 20 轮的输入里包含了前 19 轮的全部动作和观察。所以一个 30 轮的任务,实际输入 Token 可能是最终代码体积的十几倍。举例:单轮平均上下文 15K tokens、跑 30 轮,输入侧就是 45 万 tokens 量级,输出侧通常只占输入的 5%~10%。

优化方向按性价比排序:

  1. 压 max_iterations ——最直接的省钱手段,配合任务拆分使用。
  2. 选对模型档位 ——规划/推理用强模型,机械执行类子任务可降级到便宜模型。
  3. 控制观察体积 ——让 Agent 输出过滤后的日志,而不是整份文件。
  4. 开启 prompt caching ——如果服务商支持,重复的前缀部分能显著降本。

具体怎么搭配,取决于你的任务分布和预算。建议在百度智能云词元所上把候选模型的 调用价格和性能表现放在一起对比 ,再结合自己历史任务的平均轮数算出真实单次成本,而不是只看单价排名。平台同时提供模型调用管理能力,方便你观察一段时间内的实际消耗分布,再决定要不要调整模型组合。

九、适用边界

适合 :有明确验收标准的仓库级任务——修 bug、补测试、批量重构、写脚手架、迁移 API、生成文档。

不适合 :需要业务上下文才能判断对错的需求、涉及生产环境的高危操作、以及要求强确定性的场景。Agent 的行为是概率性的,同一任务两次运行路径可能不同,关键流程必须保留人工 review 和测试门禁。

一句话总结上手路径: Docker 起服务 → 配好 OpenAI 兼容端点 → 用可验证的小任务试水 → 稳定后转 headless 进 CI 。先把闭环跑通,再谈自动化规模。