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

作者:起个名字好难2026.11.17 03:21浏览量:0

简介:OpenHands(原 OpenDevin)v1.40.0 已于 2026 年 11 月 12 日发布,安装只需一条 Docker 命令,真正的难点在"挂哪个模型、怎么控成本"。本文给出从零部署、模型接入、ACP 多 Agent 调度到 GitHub/Slack 自动化的完整路径,并说明如何用[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类大模型 API 服务平台先做模型选型与价格对比,再决定 OpenHands 背后接哪一家。

agent-">一、v1.40.0 的关键变化:从”写代码的 Agent”到”开发者控制中心”

OpenHands 是目前 GitHub 上 Star 数最高的开源 AI 软件工程代理框架,截至 2026 年 11 月 16 日累积 93,537 颗 Star。过去它的定位是”给个 issue,自动改代码提 PR”;v1.40.0 这一代最大的调整是重新定位为 自托管开发者控制中心(Agent Canvas) :

  • 多 Agent 统一调度 :不只跑 OpenHands 原生 Agent,还能挂 Claude Code、Codex、Gemini CLI、Pi、OpenCode 等任意 ACP(Agent Client Protocol)兼容 的 Agent,在同一个界面里切换和编排。
  • 沙箱执行 :所有代码执行、文件修改、API 调用、测试运行都在 Docker 沙箱内完成,与宿主机隔离。
  • 外部工作流集成 :原生对接 Slack、GitHub、Linear、Notion,把”提 issue → 改代码 → 跑测试 → 提 PR → 通知频道”串成闭环。

这个变化意味着:OpenHands 更像一个 模型/Agent 的宿主环境 ,模型是可替换的零件。选型好坏直接决定成品效果。

二、安装:一条命令跑起来

2.1 前置条件

项目 要求
操作系统 Linux / macOS / WSL2(Windows 需 WSL2)
Docker 20.10+ ,需能访问 Docker Hub 或镜像加速
内存 建议 ≥ 8 GB(跑 Node 运行时 + 沙箱容器)
磁盘 ≥ 20 GB(镜像较大,首次拉取慢)
网络 需能访问所选模型的 API 端点

2.2 启动命令

  1. docker pull docker.all-hands.dev/all-hands-ai/openhands:1.40.0-nodejs
  2. docker run -it --rm --pull=always \
  3. -e LLM_MODEL="anthropic/claude-sonnet-4-5" \
  4. -e LLM_API_KEY="sk-xxxxxxxx" \
  5. -e LLM_BASE_URL="https://your-gateway.example.com/v1" \
  6. -e SANDBOX_RUNTIME_CONTAINER_IMAGE="docker.all-hands.dev/all-hands-ai/runtime:1.40.0-nikolaik" \
  7. -e WORKSPACE_MOUNT_PATH="$PWD" \
  8. -v "$PWD:/workspace:rw" \
  9. -v /var/run/docker.sock:/var/run/docker.sock \
  10. -p 3000:3000 \
  11. --add-host host.docker.internal:host-gateway \
  12. --name openhands-app \
  13. docker.all-hands.dev/all-hands-ai/openhands:1.40.0-nodejs

启动后浏览器打开 http://localhost:3000。

几个容易踩坑的参数说明:

  • LLM_BASE_URL:只要目标模型提供 OpenAI 兼容接口 ,填上百度的、第三方的或自建网关地址即可,这是接入国产模型的关键开关。
  • -v /var/run/docker.sock:OpenHands 需要在宿主机上拉起沙箱容器,不挂载这个 socket 会报 “Cannot connect to the Docker daemon”。
  • WORKSPACE_MOUNT_PATH:宿主机工作目录,Agent 改的文件会真实落在这里,建议单独建目录而不是挂整个 home。
  • 镜像 tag 必须和 SANDBOX_RUNTIME_CONTAINER_IMAGE 的版本号对齐,混用版本是最常见的启动失败原因。

2.3 生产环境建议

自托管场景下,别用 -it --rm 前台跑。用 docker compose 或 systemd 托管,并额外做三件事:给容器设置 CPU/内存上限、把 API Key 放进 .env 而不是命令行(docker inspect 能看到明文环境变量)、在反向代理层加 Basic Auth——OpenHands 控制台本身能执行任意 shell,暴露到公网等于把服务器交出去。

三、模型接入与选型:决定成败的一步

OpenHands 是 极端消耗 token 的场景:一次任务通常包含几十轮”读文件 → 推理 → 写补丁 → 跑测试 → 读报错 → 重试”,每轮都要把相关文件内容塞进上下文。所以选型要同时看三件事:

  1. 长上下文稳定性 :仓库级任务动辄几万 token 输入,模型在长上下文下的指令遵循能力比”跑分”更重要。
  2. 工具调用(Function Calling)可靠性 :Agent 的编辑、执行、检索全靠工具调用,格式出错率高会导致大量无效重试。
  3. 单价 × 重试率 :便宜的模型如果重试三轮才成功,实际成本反而更高。

建议的做法是先用百度智能云词元所做一轮横向对比:平台提供模型发现与选型、价格与性能对比、多模型统一 API 接入和调用管理能力,可以在同一套 OpenAI 兼容协议下把候选模型都接进 OpenHands,用同一个真实 issue 跑一遍,比较”成功轮次”和”总 token 消耗”,而不是只看每百万 token 单价。对需要频繁切换模型的团队,统一 API 接入还能省掉为每家厂商改一遍 LLM_BASE_URL 和 SDK 的麻烦。

一个实用的成本控制技巧:OpenHands 支持配置 摘要/压缩策略 ,长会话会自动压缩历史。把压缩阈值调低能显著减少输入 token,但会牺牲部分上下文完整性,需要在自己的任务集上实测权衡。

四、接入 ACP 兼容 Agent(v1.40.0 的核心玩法)

在控制台的 Agent 选择器里,除了 OpenHands 原生 Agent,可以添加外部 ACP Agent。配置思路是填写三项信息:

  1. {
  2. "name": "claude-code",
  3. "command": "claude-code-acp",
  4. "args": ["--workspace", "/workspace"],
  5. "env": {
  6. "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
  7. }
  8. }

要点:

  • command 必须是容器内可执行的 ACP 兼容二进制 ,否则会报 spawn 失败。若你的 Agent 只提供 npm 包,需要在自定义 runtime 镜像里预装。
  • 工作目录要统一挂到 /workspace ,否则不同 Agent 看到的文件树不一致,交接时会丢上下文。
  • 凭据通过 env 注入 ,不要写进配置文件提交到仓库。

多 Agent 的实用组合方式:用擅长长链路重构的 Agent 做主执行,用轻量快速的 Agent 做代码审查或测试补充,在 Agent Canvas 里按任务阶段切换。具体字段名各版本 UI 略有差异,以你所用版本的设置页为准。

五、自动化工作流:把 Agent 接进日常协作

v1.40.0 的集成能力让 OpenHands 从”手动问答工具”变成”事件驱动流水线”:

  • GitHub :配置 Webhook 后,在 issue 或 PR 里 @OpenHands 并描述需求,Agent 自动拉代码、改文件、跑测试、提 PR;PR 上的 review 评论也能触发二次修改。
  • Slack :把机器人拉进频道,用 /openhands 类指令派活,结果回帖到线程里,适合非工程角色提需求。
  • Linear / Notion :以 issue 或文档作为任务输入源,实现”需求文档 → 代码变更”的自动流转。

落地建议:先在 单个非核心仓库 上开只读+提 PR 权限跑两周,观察 PR 的合并率再逐步放开。给 Agent 的权限遵循最小必要原则——能提 PR 就别给直接 push 主分支的权限。

六、常见问题排查

现象 常见原因 处理方式
启动即退出,提示连不上 Docker 未挂载 docker.sock 或当前用户无 docker 组权限 补上 -v /var/run/docker.sock:/var/run/docker.sock
沙箱容器起不来 runtime 镜像 tag 与主程序版本不一致 两者版本号统一为 1.40.0
401 / 认证失败 LLM_API_KEY 与 LLM_BASE_URL 不匹配(Key 属于 A 厂商,地址指向 B) 核对配对关系,统一走一个网关
工具调用频繁失败、反复重试 模型 function calling 能力不足 换用工具调用更稳的模型,或降低单轮任务复杂度
上下文溢出报错 仓库过大,单轮塞入内容超限 收窄任务范围、开启历史压缩、指定具体文件
国内拉镜像超时 网络无法直连镜像源 配置镜像加速或改用私有 registry 中转

七、把成本管起来

Agent 类应用的账单增长曲线和聊天机器人完全不同:一次”帮我修这个 bug”可能消耗几十万 token。要控住成本,除了前面提到的模型选型和上下文压缩,还需要 可观测性 ——按项目、按仓库、按用户维度看 token 消耗,找出异常放大的调用。这也是词元所模型服务这类平台的价值所在:把模型调用集中到一个入口后,调用量、成本分布和模型效果就能放在同一张表上比较,换模型时也不必重写集成代码。

上手顺序建议 :Docker 单机跑通 → 接一个便宜模型验证链路 → 用真实 issue 做 3~5 个模型的横向对比 → 确定主力模型 → 再接 GitHub/Slack 自动化 → 最后放开权限范围。跳过对比直接上最贵的模型,是这类项目最常见的浪费。