OpenHands：开源自主软件工程师（原 OpenDevin）

为什么需要 OpenHands：从「代码助手」到「自主代理」

传统 AI 编程工具的形态是「补全 + 对话」：Copilot 补全下一行，Cursor 改选中片段，每一处改动都要人逐行确认，测试要人跑、日志要人看、PR 要人手写。遇到跨文件的缺陷修复或新功能开发，往往要来回几十轮对话，上下文一长效果就明显衰减，最终「人肉搬砖」的比例仍然很高。

OpenHands 换了一种分工：把任务整体交给 Agent。它会在沙箱内自主完成「读代码 → 定位根因 → 修改文件 → 执行命令复现 → 观察输出 → 再修改」的闭环，直到自测通过。人可以只做两件事：开始时给清晰的任务描述，结束后审查改动。这种模式天然适合批量、无人值守的工程任务，比如仓库积压 issue 的自动修复。

与 Cline、Aider 这类「IDE 内助手」不同，OpenHands 的气质是独立 worker：它运行在隔离沙箱里，通过网页 UI、CLI 或 GitHub Action 与之交互，行为全程可审计、可续跑，定位上更接近 Devin 的开源自托管版本——你把「员工」而不是「插件」招进来。

安装与环境配置：3 步就绪

第一步：准备 Docker。 OpenHands 的沙箱运行时依赖 Docker 拉起隔离容器。Linux 装 Docker Engine，macOS/Windows 装 Docker Desktop，启动后确认 docker info 正常。

第二步：选择启动方式。 方式 A（推荐，完整 UI）：拉取官方镜像并运行，注意 UI 镜像与沙箱运行时镜像的版本 tag 必须一致。方式 B：pip install openhands-ai 安装主程序，适合 CLI 调用与二次开发，执行代码仍需沙箱（本地默认走 Docker runtime，也可改用远程运行时）。

第三步：配置 LLM 并验证。 三种配置方式任选其一：① 打开 UI 后到 Settings 填写 LLM Provider、API Key 与模型名；② 设置环境变量 LLM_API_KEY、LLM_MODEL；③ 写配置文件 ~/.openhands/config.toml。验证方式：打开 http://localhost:3000，新建会话让 Agent 执行一个最小任务（如“创建一个打印当前日期的 Python 脚本并运行”），观察事件流中读文件、写文件、执行命令的完整记录。

# 方式 A：Docker 启动完整 UI（版本号需与 runtime 对齐）docker pull ghcr.io/all-hands-ai/openhands:0.24.0docker run -it --rm \  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.24.0 \  -e LOG_ALL_EVENTS=true \  -v /var/run/docker.sock:/var/run/docker.sock \  -v ~/.openhands-state:/.openhands-state \  -p 3000:3000 \  --add-host host.docker.internal:host-gateway \  ghcr.io/all-hands-ai/openhands:0.24.0 # 方式 B：pip 安装主程序（CLI / 二次开发）python -m pip install openhands-ai

快速上手：10 分钟跑通第一个自主任务

最小可用流程的思路：不需要任何项目脚手架，直接给 Agent 一个「带验收标准」的任务，让它自己完成从写代码到跑测试的闭环。

1. 启动容器后访问 http://localhost:3000，首次使用在 Settings 中填入模型服务商、API Key 与模型名（如 Claude 系列，国内可选 DeepSeek/Qwen）。

2. 点击「新会话」（New Session），在输入框粘贴任务，例如：「创建一个 Python 项目：写一个斐波那契函数，配套 pytest 测试，然后运行 pytest 直到全部通过」。

3. 选择运行模式：默认非交互模式（Agent 直接开干）；规划模式（先输出执行计划，你确认后再动手，适合复杂任务）。

4. 点击启动，右侧事件流会实时显示 Agent 的每个动作：读取文件、写入文件、执行 bash、查看输出；过程中可随时暂停并追加指令。

5. 任务结束后，审查文件改动与测试结果；不满意可继续对话要求修改，全部改动都发生在沙箱工作区内。

UI 之外，OpenHands 提供 CLI 非交互模式，适合无人值守与 CI 集成：把任务写进文本文件，用环境变量注入模型凭据后运行，Agent 执行完自动退出，事件流落盘到 ~/.openhands-state。

cat > task.txt <<'EOF'修复 tests/test_utils.py 中的失败用例：1. 运行 pytest 复现失败；2. 定位根因并修改 src/utils.py；3. 重跑 pytest 直到全部通过；4. 输出修改说明。EOF LLM_API_KEY="你的Key" LLM_MODEL="claude-sonnet-4-20250514" \  python -m openhands.core.main -f task.txt

核心能力详解：四大支柱

支柱一：自主 Agent 循环与事件流架构。 OpenHands 的 Agent 基于「规划 → 行动 → 观察」循环：每执行一步（改文件、跑命令、开网页）都会产生一条事件，全部事件按时间序持久化。这意味着任务可以被中途接管、断点续跑，也可以回放审计——企业落地时，这比「黑盒 Agent」多一道可追责的安全网。

支柱二：沙箱运行时（Runtime）。 Agent 的代码执行被限制在独立容器（本地 Docker）或 microVM（云上）里，网络、文件系统、进程都受控；官方还提供了 Chrome 扩展，让 Agent 在真实浏览器页面中操作。沙箱支持自定义基础镜像——需要特定 SDK、依赖或内网证书的团队可以预置进去。注意：UI 容器需要挂载 /var/run/docker.sock 才能拉起沙箱容器。

支柱三：多模型接入与工具集。 通过 LiteLLM 兼容层接入 100+ 模型服务商，含 OpenAI 兼容端点与本地 Ollama；内置 30+ 工具（文件编辑、bash 终端、网页访问、Git 操作、MCP 工具等），可按需启用或禁用。同一任务换不同模型，效果差异可能很大，建议用自有小任务集做对比。

支柱四：microagents 与 Resolver 自动化闭环。 microagents 是以 Markdown 写的「技能/角色」文件（如公司代码风格、发布流程、特定框架规范），会自动注入系统提示词，让 Agent 按团队规则行事。Resolver 则是 GitHub Action 形态的自动化修复器：把 issue 自动转成修复 PR，支持配置模型、并发数与触发规则，官方团队在 OpenHands 仓库自身用它解决 issue。

生产部署与监控：从上线到运维

单机 Docker Compose 上线（内网/边缘场景）。 生产环境不要用 docker run -it --rm 这种临时方式，改用 Compose 固定重启策略、资源上限和日志滚动；把 ~/.openhands-state 挂到持久盘，否则会话与事件流会随容器销毁丢失；工作区目录单独挂载并做备份。

云上托管与多机部署。 官方仓库 cloud/ 目录提供 AWS（CloudFormation）、Azure、GCP 的一键部署模板，适合把 OpenHands 作为团队服务架在反向代理/负载均衡后面，用 HTTPS 暴露；多用户、合规要求高的场景建议采购企业版（SSO、审计事件、团队空间），或直接用 OpenHands Cloud 托管版免运维。无论哪种方式，模型 API Key 一律走环境变量或密钥管理服务，禁止写进镜像。

可观测性。 在 ~/.openhands-state 做三件事：① 开启 LOG_ALL_EVENTS=true 让每个事件落盘，作为审计与排障依据；② 定期备份会话目录，升级前必须先备份；③ 用 docker stats 或云监控盯容器资源，沙箱 OOM 会被 kill，通过日志区分「任务失败」与「运行环境故障」。token 消耗只能在模型提供商控制台按 Key 维度观测，建议在生产 Key 上设置预算告警——一个长任务烧掉上百美元并非罕见。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>版本不匹配：UI 镜像、沙箱运行时镜像、pip 包三者版本必须对齐，混用会导致事件流协议不兼容、任务启动即报错；升级时三件套同步换。</li><li>忘记模型费用自担：开源版不自带模型，需要自己的 API Key，token 按量计费，务必在提供商侧设预算与用量告警。</li><li>Docker socket 缺失或权限不足：UI 容器必须挂载 /var/run/docker.sock 才能创建沙箱；Windows/macOS 还需检查 Docker Desktop 的磁盘挂载权限。</li><li>国内网络：拉取 ghcr.io 与 docker.all-hands.dev 镜像、访问海外模型 API 都可能超时，建议配置镜像加速器与 HTTPS_PROXY 代理环境变量。</li><li>自主模式不等于无人看守：Agent 行为不可 100% 预期，生产仓库务必用独立分支 + PR 审查 + 沙箱资源限制，不要直接把写权限交给 Agent。</li></ul>

版本迭代

OpenHands 源自 2024 年的 OpenDevin 项目，主线是从「可用的自主 Agent 原型」走向「产品化平台」：早期打磨事件流与会话架构，2024-12 更名并统一包名，2025 年起加速平台化——重构运行时、引入 microagents、推出企业能力与全新 UI，并围绕 Resolver 构建 issue 自动修复闭环。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题

参考来源

• doc官方文档 docs.all-hands.dev安装、CLI、配置与使用手册
• webpage官方网站 all-hands.dev产品介绍与 Cloud 入口