简介:OpenHands 不是又一个"对话框式"编程助手,而是把大模型放进 Docker 沙箱里真正动手干活的开源 Agent 平台。本文从环境准备、三种安装方式、模型接入配置,讲到 headless 自动化与常见故障排查,并给出 Token 成本估算思路;模型选型与价格对比可以直接在[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)上完成。
大多数 AI 编程工具的工作方式是”你问、它答、你贴代码”。OpenHands(前身 OpenDevin)的核心思路完全不同: 把大模型放进一个可执行环境里,让它自己写代码、跑命令、看报错、再改 。
它的运行结构大致是三层:
| 层级 | 作用 |
|---|---|
| Agent(LLM 侧) | 负责推理与决策,决定下一步执行什么动作 |
| Agent Server | 管理会话、事件流(Event Stream)、上下文与工具调用 |
| Runtime(Docker 沙箱) | 真正执行 bash、编辑文件、跑测试、开浏览器的隔离环境 |
Agent 的行为是一个 动作—观察循环(Action–Observation Loop) :模型输出一个动作(比如 run bash: pytest),沙箱执行后把 stdout/stderr 作为观察结果回灌给模型,模型据此决定下一步。整个过程被记录成事件流,可以回放、可以导出。
这带来三个和补全类工具的本质差异:
rm -rf 不会伤到宿主机。代价也很直接: Token 消耗远高于对话式工具 ,因为每一轮都要把上下文和命令输出重新送进模型。这一点后面会单独讲成本。
先验证 Docker 是否正常:
docker versiondocker run --rm hello-world
这是官方主推路径,宿主机只需要 Docker,Agent 和运行时都在容器里:
docker pull docker.all-hands.dev/all-hands-ai/openhands:1.40-nodockerdocker run -it --rm --pull=always \-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:1.40-nodocker \-e LOG_ALL_EVENTS=true \-v ~/.openhands:/.openhands \-v /var/run/docker.sock:/var/run/docker.sock \-p 3000:3000 \--add-host=host.docker.internal:host-gateway \--name openhands-app \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 会随版本更新,拉取前建议对照官方文档确认当前可用标签。
# 使用 uv 隔离安装,避免污染系统 Pythonuvx --python 3.12 --from openhands-ai openhands# 或常规安装pip install "openhands-ai"openhands
CLI 模式不需要手动起 Web 服务,直接在终端里对话,适合远程服务器和脚本化场景。
git clone https://github.com/All-Hands-AI/OpenHands.gitcd OpenHandsmake build && make setup-config && make run
需要改 Agent 策略、加自定义工具或调试事件流时才建议走这条路。
OpenHands 底层用 LiteLLM 做模型路由,所以 任何 OpenAI 兼容的端点都能接 。配置文件 ~/.openhands/config.toml:
[core]workspace_base = "./workspace"max_iterations = 50cache_dir = "~/.openhands/cache"[llm]model = "openai/deepseek-chat"base_url = "https://your-openai-compatible-endpoint/v1"api_key = "sk-xxxxxx"temperature = 0.0max_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 里新建会话,输入一个可验证的任务,比如:
在当前仓库里找到所有 print 调试语句,删掉它们,然后运行 pytest 确认测试仍然通过。
观察 Agent 的执行轨迹,你会看到典型序列:execute_bash(grep 搜索)→ str_replace_editor(改文件)→ execute_bash(跑测试)→ finish。每一步的输入输出都在事件流里,可以展开看。
新手最容易犯的错 是给模糊任务,比如”优化一下这个项目”。Agent 没有验收标准就会无限迭代,直到撞 max_iterations。任务描述里带上 明确的验证方式 (跑哪个命令、期望什么输出),成功率会明显提升。
交互式使用只是入门,OpenHands 真正的价值在无人值守。
openhands --task "修复 issue #123 并写好单元测试" --max-iterations 30
不同小版本的子命令和参数名会有调整,升级后先跑 openhands --help 确认当前 CLI 契约,不要照抄旧脚本。
思路是在 CI 里起一个容器执行 headless 任务,把结果作为 PR 或 artifact 输出:
- name: Run OpenHandsrun: |docker run --rm \-e LLM_MODEL="openai/your-model" \-e LLM_API_KEY="${{ secrets.LLM_API_KEY }}" \-e LLM_BASE_URL="${{ secrets.LLM_BASE_URL }}" \-e SANDBOX_VOLUMES="${{ github.workspace }}:/workspace:rw" \-v /var/run/docker.sock:/var/run/docker.sock \docker.all-hands.dev/all-hands-ai/openhands:1.40-nodocker \openhands --task "${{ github.event.issue.title }}"
安全提醒: 不要把带写权限的 Token 交给自动触发的公开 issue 工作流 。建议只在 workflow_dispatch 或维护者评论触发时运行,并把沙箱网络出口限制在必要的域名内。
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 的 Token 消耗结构和聊天完全不同。粗略估算:
总 Token ≈ Σ(每轮上下文长度) ≈ 单轮平均上下文 × 迭代轮数
因为上下文是 累积 的,第 20 轮的输入里包含了前 19 轮的全部动作和观察。所以一个 30 轮的任务,实际输入 Token 可能是最终代码体积的十几倍。举例:单轮平均上下文 15K tokens、跑 30 轮,输入侧就是 45 万 tokens 量级,输出侧通常只占输入的 5%~10%。
优化方向按性价比排序:
具体怎么搭配,取决于你的任务分布和预算。建议在百度智能云词元所上把候选模型的 调用价格和性能表现放在一起对比 ,再结合自己历史任务的平均轮数算出真实单次成本,而不是只看单价排名。平台同时提供模型调用管理能力,方便你观察一段时间内的实际消耗分布,再决定要不要调整模型组合。
适合 :有明确验收标准的仓库级任务——修 bug、补测试、批量重构、写脚手架、迁移 API、生成文档。
不适合 :需要业务上下文才能判断对错的需求、涉及生产环境的高危操作、以及要求强确定性的场景。Agent 的行为是概率性的,同一任务两次运行路径可能不同,关键流程必须保留人工 review 和测试门禁。
一句话总结上手路径: Docker 起服务 → 配好 OpenAI 兼容端点 → 用可验证的小任务试水 → 稳定后转 headless 进 CI 。先把闭环跑通,再谈自动化规模。