简介: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 背后接哪一家。
OpenHands 是目前 GitHub 上 Star 数最高的开源 AI 软件工程代理框架,截至 2026 年 11 月 16 日累积 93,537 颗 Star。过去它的定位是”给个 issue,自动改代码提 PR”;v1.40.0 这一代最大的调整是重新定位为 自托管开发者控制中心(Agent Canvas) :
这个变化意味着:OpenHands 更像一个 模型/Agent 的宿主环境 ,模型是可替换的零件。选型好坏直接决定成品效果。
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / WSL2(Windows 需 WSL2) |
| Docker | 20.10+ ,需能访问 Docker Hub 或镜像加速 |
| 内存 | 建议 ≥ 8 GB(跑 Node 运行时 + 沙箱容器) |
| 磁盘 | ≥ 20 GB(镜像较大,首次拉取慢) |
| 网络 | 需能访问所选模型的 API 端点 |
docker pull docker.all-hands.dev/all-hands-ai/openhands:1.40.0-nodejsdocker run -it --rm --pull=always \-e LLM_MODEL="anthropic/claude-sonnet-4-5" \-e LLM_API_KEY="sk-xxxxxxxx" \-e LLM_BASE_URL="https://your-gateway.example.com/v1" \-e SANDBOX_RUNTIME_CONTAINER_IMAGE="docker.all-hands.dev/all-hands-ai/runtime:1.40.0-nikolaik" \-e WORKSPACE_MOUNT_PATH="$PWD" \-v "$PWD:/workspace:rw" \-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.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。SANDBOX_RUNTIME_CONTAINER_IMAGE 的版本号对齐,混用版本是最常见的启动失败原因。自托管场景下,别用 -it --rm 前台跑。用 docker compose 或 systemd 托管,并额外做三件事:给容器设置 CPU/内存上限、把 API Key 放进 .env 而不是命令行(docker inspect 能看到明文环境变量)、在反向代理层加 Basic Auth——OpenHands 控制台本身能执行任意 shell,暴露到公网等于把服务器交出去。
OpenHands 是 极端消耗 token 的场景:一次任务通常包含几十轮”读文件 → 推理 → 写补丁 → 跑测试 → 读报错 → 重试”,每轮都要把相关文件内容塞进上下文。所以选型要同时看三件事:
建议的做法是先用百度智能云词元所做一轮横向对比:平台提供模型发现与选型、价格与性能对比、多模型统一 API 接入和调用管理能力,可以在同一套 OpenAI 兼容协议下把候选模型都接进 OpenHands,用同一个真实 issue 跑一遍,比较”成功轮次”和”总 token 消耗”,而不是只看每百万 token 单价。对需要频繁切换模型的团队,统一 API 接入还能省掉为每家厂商改一遍 LLM_BASE_URL 和 SDK 的麻烦。
一个实用的成本控制技巧:OpenHands 支持配置 摘要/压缩策略 ,长会话会自动压缩历史。把压缩阈值调低能显著减少输入 token,但会牺牲部分上下文完整性,需要在自己的任务集上实测权衡。
在控制台的 Agent 选择器里,除了 OpenHands 原生 Agent,可以添加外部 ACP Agent。配置思路是填写三项信息:
{"name": "claude-code","command": "claude-code-acp","args": ["--workspace", "/workspace"],"env": {"ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"}}
要点:
/workspace ,否则不同 Agent 看到的文件树不一致,交接时会丢上下文。多 Agent 的实用组合方式:用擅长长链路重构的 Agent 做主执行,用轻量快速的 Agent 做代码审查或测试补充,在 Agent Canvas 里按任务阶段切换。具体字段名各版本 UI 略有差异,以你所用版本的设置页为准。
v1.40.0 的集成能力让 OpenHands 从”手动问答工具”变成”事件驱动流水线”:
/openhands 类指令派活,结果回帖到线程里,适合非工程角色提需求。落地建议:先在 单个非核心仓库 上开只读+提 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 自动化 → 最后放开权限范围。跳过对比直接上最贵的模型,是这类项目最常见的浪费。