OpenHands：AI 开发者控制中心入门指南

是什么

OpenHands 是一个聚焦于人工智能驱动软件开发的开源项目与社区。其核心控制台为 Agent Canvas —— 一个支持自托管的开发者控制中心，专门用于管理自主软件工程智能体（Agent）并实现日常编程工作流的自动化。

OpenHands 并没有设计成单一僵化的程序，而是采用模块化架构，拆分为分布在多个代码仓库中的核心组件：

• Agent Canvas：基于浏览器的可视化控制中心，开发者可以在此与智能体交互、审查其操作记录并配置自动化任务。
• Software Agent SDK：一个可灵活组合的 Python 核心库，为构建软件智能体、管理工作区以及处理对话与事件提供底层框架。
• OpenHands Agent Server：提供 REST 与 WebSocket 应用程序编程接口（API）的专用后端服务，支持系统在本地或远程机器上驱动智能体、调度工具以及管理工作区。
• Automation Server：负责定时任务调度、接收 Webhook（来自第三方平台的事件通知）、跟踪运行记录并将任务分发给智能体运行时的后台引擎。
• Sandbox Server：用于构建和管理隔离计算环境（沙箱）的独立控制平面，确保 Agent Server 能够在安全受控的环境中执行代码。

OpenHands 不仅开箱自带内置智能体，还广泛支持各类外部编程智能体。目前兼容的智能体包括 Claude Code、Codex、Gemini CLI、Pi、OpenCode，以及任何遵循 Agent-Client Protocol（ACP，智能体-客户端协议）通信的智能体。ACP 作为通用的通信桥梁，能够让不同架构的自主智能体直接接入 Agent Canvas 等控制中心。

平台提供了非常灵活的部署选项。你可以将它直接安装在个人开发机上，部署在 Mac Mini 等专用物理设备中，运行在企业内网的虚拟机（VM）内，或者放置在 Docker 容器中执行。对于希望省去服务器运维烦恼、直接使用全托管服务的团队，该项目还推出了商业化的 OpenHands Cloud 与 OpenHands Enterprise 解决方案。

能做什么

OpenHands 能将编程智能体转变为全天候在线的研发搭档，既能胜任交互式协同编码，也能在后台自主完成自动化任务。

根据官方文档介绍，其核心功能亮点包括：

• 交互式编程协作：开发者可以通过 Web 界面与智能体实时协作。智能体能够检索代码仓库、编写与修改代码、在专用工作区中执行命令，并处理多步骤的复杂工程任务。
• 多后端自由切换：用户可以使用同一个 Agent Canvas 前端连接到部署在不同环境中的多个 Agent Server。开发者无需离开主界面，就能在笔记本上的本地专属智能体与云端服务器上运行自动化任务的共享智能体之间自如切换。
• 自动化工作流与定时调度：借助 Automation Server，团队可以设定智能体按预设周期定时运行，或在接收到第三方服务的 Webhook 触发信号时自动响应。
• 第三方工具集成：OpenHands 支持与主流开发和协作平台深度打通，涵盖 GitHub、Slack、Linear、Notion 以及 Datadog。例如，智能体可以自动把 GitHub 上新提的 Issue 拆解成具体的工程子任务，或者直接将研发进度汇总报告发送到指定的 Slack 频道。
• Model Context Protocol（MCP）与自定义扩展：平台全面支持 Model Context Protocol（模型上下文协议），智能体能够通过该开放标准读取外部数据源并调用第三方工具。用户还可以通过自定义技能（Skills）、钩子（Hooks）、插件（Plugins）、扩展包以及特定仓库的专属配置来定制智能体行为。
• 自定义模型配置：OpenHands 允许用户自带语言模型。开发者可以配置自定义大语言模型（LLM）Profile，将平台无缝对接到所选的模型接口端点。
• 覆盖多类软件研发场景：依据官方文档，OpenHands 能够贯穿软件开发生命周期（SDLC）中的各个环节：
  • 漏洞修复：检测软件项目中的潜在安全隐患并自动生成修复补丁。
  • 自动化代码审查：评估提交的代码变更并给出建设性的技术反馈。
  • 自动化 QA 测试：自动编写并运行测试用例，校验系统逻辑是否符合预期。
  • 故障排查与分流：分析系统告警信息，协助工程师开展技术溯源。
  • 依赖项升级：扫描项目依赖并批量处理第三方库的日常版本更新。
  • 遗留系统现代化改造：协助处理复杂的代码重构与迁移，例如 COBOL 旧系统重写或 Spark 数据平台升级。
  • 软件工厂与日常研发：支持全自动的持续开发流水线，分担工程师繁琐的日常开发工作。

怎么开始

OpenHands 提供了多种安装与部署方式。项目文档指出，将 OpenHands 部署在专用设备或云端服务器上，即便合上个人电脑，智能体依然可以在后台持续工作。

方案一：无沙箱模式

该方案直接在宿主机操作系统上运行 Agent Server，没有容器环境隔离，这意味着智能体可以直接读写你的本地文件系统。

前置条件：Node.js 24 或更高版本，以及快速 Python 包管理与运行工具 uv。

全局安装并启动完整的本地服务栈：

npm install -g @openhands/agent-canvas
agent-canvas

如果希望分立运行各个组件，可以使用专用参数拆分启动流程：

agent-canvas --frontend-only  # static frontend + ingress only
agent-canvas --backend-only   # agent server + automation backend + ingress only

方案二：Docker 单沙箱模式

在 Docker 容器中运行 OpenHands 可以实现智能体环境隔离，将其权限严格限制在挂载的项目目录之内。

前置条件：macOS 或 Windows 上的 Docker Desktop，或 Linux 上的 Docker Engine / Docker Desktop；以及一个用于存放需要开放给智能体的代码仓库目录。

在 macOS 或 Linux 系统中，执行以下命令启动容器：

export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.27.1 # x-release-please-version

在此配置下，智能体只能访问位于 PROJECTS_PATH 指定路径下的项目文件。

方案三：Docker 多沙箱模式

为了支撑多任务并发，OpenHands 支持为每一个新会话单独拉起一个 Docker 容器，并为其配备独立的 Agent Server 与工具链。Canvas 界面和外部主服务运行在宿主机上，负责把对话指令精确路由至对应的容器。

前置条件：Node.js 24 或更高版本、uv，以及当前用户具备访问权限的处于运行状态的 Docker 守护进程。

在 macOS 或 Linux 上，通过指定环境变量启动多沙箱环境：

npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas

每个容器都会自动挂载专属的工作区与持久化状态，即便容器发生销毁或替换，工作区文件和历史会话数据也不会丢失。

方案四：源码运行

如果你计划对 OpenHands 进行二次开发，或希望体验最新的开发分支代码，可以直接使用源码启动。该方式与方案一相同，直接运行于宿主机环境，对本地文件系统拥有完全读写权限。

前置条件：Node.js 24 或更高版本、npm 以及 uv。

克隆代码并本地运行：

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

访问 Web 界面与网络安全

服务成功启动后，使用浏览器访问 http://localhost:8000（若使用 Docker 单沙箱镜像部署，则访问 http://localhost:8000/canvas）。

默认情况下，本地 npm 启动与源码运行均严格绑定在回环地址（127.0.0.1），以避免自动注入的 Session Key 在局域网中泄漏。如果需要支持其他网卡接口访问，可以指定参数 --host 0.0.0.0 或配置环境变量 OH_BIND_HOST；此时系统会自动停用密钥自动注入机制，改为在 Web 界面中要求用户手动输入 API Key。

价格与门槛

OpenHands 属于开源软件项目。根据其 GitHub 主仓库的元数据，OpenHands/OpenHands 采用 MIT 许可证开源。官方文档同时也说明，OpenHands 生态涵盖多个独立公共仓库，各个仓库分别维护各自的开源许可证。

在面向社区的自托管版本之外，项目方还提供了商业托管服务：

• OpenHands Cloud：商用托管平台，无需团队自行维护后端服务器，直接提供计算运行设施、团队协作、权限管控、第三方工具集成、用量追踪与预算配额管理功能。
• OpenHands Enterprise：面向大型组织的商用解决方案，支持获得商业授权的私有化自托管或托管部署，并附带专属的企业级技术支持。

具体收费标准与套餐内容以 OpenHands 官方网站 与 OpenHands Enterprise 页面 公布的最新信息为准。

系统配置要求

选择自托管部署 OpenHands 时，不同安装途径对应以下环境门槛：

• Node.js：通过 npm 运行 Agent Canvas、使用多容器模式或源码编译时，要求版本达到 24 或更高。
• Python 工具链：需要安装 uv 包管理工具，用以运行和调度基于 Python 编写的 Agent Server 组件。
• Docker：在使用容器隔离沙箱或多对话隔离运行时，需要部署 Docker Desktop 或 Docker Engine。
• 语言模型凭据：需要自备在 OpenHands LLM Profile 中所绑定的模型接口 API Key 或访问权限。

适合谁

OpenHands 能够服务于多种技术角色与团队组织：

• 软件工程师：希望在浏览器中使用统一控制台，与自主 AI 智能体协同完成日常编码、Bug 排查及重构工作的开发者。
• 工程研发团队：希望将重复琐碎的任务自动化处理的团队，例如自动分流 Issue、自动化审查 Pull Request（PR）以及定期跟进依赖包升级。
• DevOps 与 SRE 工程师：需要将 Datadog 等监控观测工具接入自动化排障工作流，以此分析警报原因并将诊断结论回传给 Slack 等沟通群组的运维技术人员。
• 对数据安全有严格要求的机构：必须把源代码与智能体执行环境保留在内部基础设施的企业，可通过虚拟机、私有云或 Docker 容器完成私有化安全部署。
• 遗留系统维护团队：正在推进复杂旧系统改造的技术团队，例如 COBOL 系统重构或 Spark 大数据架构升级迁移。
• 智能体开发者与研究员：希望基于前沿大模型进行实验，或利用 Agent-Client Protocol（ACP）和 Model Context Protocol（MCP）等标准化协议打造专属智能体的技术人员。

替代品

SWE-agent 是一个开源系统，旨在让语言模型能够直接与代码仓库进行交互并解决软件工程中的实际问题。

Aider 是一款开源的命令行工具，支持开发者在本地代码仓库中直接与人工智能展开结对编程。

来源

• OpenHands GitHub 仓库
• OpenHands 官方文档
• SWE-agent GitHub 仓库
• Aider GitHub 仓库