前言

在 AI 编程时代，OpenHands（原 OpenDevin）作为一款开源的 AI 软件开发代理框架，凭借其低门槛、高扩展性和强大的 Agent 能力，成为了开发者提升编程效率的利器。它支持自然语言交互、多 LLM 适配，还能实现代码生成、环境部署、任务自动化等一系列开发操作，不管是新手还是资深开发者，都能快速上手。

本文结合 OpenHands 官方文档和实际实操经验，用通俗易懂的方式讲清 OpenHands 的核心概念、安装部署和实战用法，让你轻松解锁 AI 编程新姿势～

一、先搞懂：OpenHands 到底是什么？

OpenHands 是一个聚焦AI 驱动开发的开源社区和工具集，核心是打造能自主完成开发任务的 AI Agent（智能代理），简单说就是你的 AI 编程助手，能听懂自然语言指令，帮你写代码、跑程序、调 bug、部署项目。

它基于CodeAct 范式开发（核心是让 LLM 通过「写代码 - 跑代码 - 看结果」的循环完成复杂任务），区别于传统的代码补全工具，OpenHands 能实现端到端的开发闭环，从需求分析到代码实现、运行测试，全程自动化完成。

OpenHands 的核心产品形态（官方核心能力）

OpenHands 提供了多种使用方式，适配不同开发场景，核心分为 5 类，底层由SDK驱动，从简易到企业级全覆盖：

产品形态	核心特点	适用人群 / 场景
Software Agent SDK	可组合的 Python 库，OpenHands 的核心引擎，支持自定义 Agent、本地运行 / 云端扩缩容	开发工程师、AI 开发者，需要二次开发 / 定制 Agent
CLI	命令行工具，上手最简单，支持 Claude/GPT 等任意 LLM，类似 Claude Code/Codex	习惯命令行操作的开发者，快速执行简单 AI 编程任务
Local GUI	本地图形界面，带 REST API 和 React 前端，体验类似 Devin/Jules	普通开发者，可视化操作，本地运行 AI Agent
Cloud	云端商业化部署的 GUI，带免费 $10 额度，集成 GitHub/Slack/Jira 等工具，支持多用户 / 权限管理	团队开发，需要云端协作、资源管控的场景
Enterprise	企业级私有化部署，基于 K8s 部署在自有 VPC，源码可见（需授权），含专属支持	大型企业，需要数据私有化、定制化服务和高级支持

核心优势

1. 低门槛：自然语言交互，无需复杂编码，小白也能快速上手；
2. 全开源：核心模块基于 MIT 协议开源，可自由查看 / 修改源码（企业版除外）；
3. 高兼容：支持 OpenAI、Anthropic 等主流 LLM，可自定义模型配置；
4. 强能力：覆盖代码生成、环境搭建、任务自动化、团队协作等全开发流程；
5. 易部署：支持 Docker 一键部署、本地 / 云端 / 私有化多环境运行。

二、准备工作：环境要求与核心依赖

OpenHands 的部署和使用非常轻量化，核心依赖只有两个，提前准备好即可：

1. Python 环境：3.8 及以上版本（SDK/CLI 使用）；
2. Docker（可选但推荐）：快速部署 Local GUI / 云端版本，无需手动处理依赖；
3. LLM API 密钥：需要 OpenAI（GPT-3.5/4）、Anthropic（Claude）或自定义模型（如 DeepSeek-R1）的 API Key，用于驱动 AI Agent。

可选工具：内网穿透工具（如 cpolar），用于远程访问本地部署的 OpenHands，适合团队协作。

三、快速上手：3 种最常用的安装部署方式

根据不同使用场景，推荐 3 种最实用的部署方式，从一键启动到定制化部署，按需选择即可。

方式 1：Docker 一键部署 Local GUI（推荐！小白首选）

Docker 部署是最简单的方式，无需处理复杂依赖，一条命令即可启动 OpenHands 图形界面，支持 Windows/Linux/MacOS。

步骤 1：安装 Docker

已安装 Docker 的可跳过，未安装的参考Docker 官方文档完成安装，确保 Docker 服务正常运行。

步骤 2：拉取并启动 OpenHands 容器

打开终端 / 命令行，执行以下命令（Linux/MacOS 加 sudo，Windows 直接执行）：

# 拉取并启动OpenHands最新版，映射3000端口（本地访问）
docker run -it --rm -p 3000:3000 -v ~/.local/share/OpenHands:/opt/OpenHands/workspace ghcr.io/all-hands-ai/openhands:main

国内环境优化：若拉取镜像缓慢，可使用华为云 / 阿里云镜像源，或参考华为云部署的镜像拉取命令。

步骤 3：本地访问 OpenHands

启动成功后，打开浏览器，输入地址：http://localhost:3000，即可进入 OpenHands 图形界面。

方式 2：Pip 安装（轻量版，CLI/SDK 使用）

适合习惯命令行操作，或需要使用 OpenHands SDK 进行二次开发的开发者，纯 Python 环境即可运行。

步骤 1：安装 OpenHands

# 从PyPI安装最新版
pip install openhands

步骤 2：启动服务

# 启动OpenHands服务（默认带简易界面和CLI）
openhands start

启动后同样访问http://localhost:3000即可使用。

方式 3：Linux 服务器部署（含公网访问，团队协作）

若需要在服务器部署并实现公网远程访问，可结合Docker+cpolar 内网穿透实现，适合团队共享使用。

步骤 1：服务器部署 OpenHands（同方式 1 的 Docker 命令）

步骤 2：安装 cpolar 内网穿透工具

# 一键安装cpolar
sudo curl https://get.cpolar.sh | sh
# 启动cpolar服务
sudo systemctl start cpolar
# 设置开机自启
sudo systemctl enable cpolar

步骤 3：配置公网访问

1. 访问 cpolar 管理界面：http://服务器IP:9200，用注册账号登录；
2. 点击隧道管理 - 创建隧道，配置参数：
   • 隧道名称：openhands（自定义）；
   • 协议：HTTP；
   • 本地地址：3000（OpenHands 默认端口）；
   • 地区：根据服务器位置选择（如 China Top）；
3. 创建成功后，在在线隧道列表获取公网地址，即可在任意设备访问服务器上的 OpenHands。

四、首次使用：配置 LLM 模型（关键步骤）

OpenHands 本身不提供大模型，需要对接外部 LLM，首次打开界面会弹出模型配置窗口，按以下步骤操作即可。

步骤 1：基础配置（主流 LLM，如 GPT/Claude）

1. 在配置界面选择LLM 提供商（如 OpenAI/Anthropic）；
2. 输入你的API Key（从对应大模型平台获取，如 OpenAI 官网 - 个人中心 - API Keys）；
3. 选择模型（如 gpt-3.5-turbo、claude-3-sonnet）；
4. 点击Save保存，完成基础配置。

步骤 2：自定义模型配置（如 DeepSeek-R1 / 国产模型）

若需要使用自定义模型（如华为云 MaaS 的 DeepSeek-R1），开启高级配置（Advanced），按以下参数填写：

• Custom Model：模型标识（如 openrouter/DeepSeek-R1）；
• Base URL：模型 API 地址（从模型平台获取）；
• API Key：模型平台的 API 密钥；
• 其他参数保持默认，点击Save Changes保存。

五、实战操作：用 OpenHands 完成第一个 AI 编程任务

配置完成后，即可开始使用 OpenHands 的核心能力，以Local GUI为例，手把手教你用自然语言让 AI 帮你写代码、跑程序。

核心界面介绍

OpenHands 的图形界面非常直观，核心功能区分为 6 部分：

1. 聊天面板：输入自然语言指令，查看 AI 的回复和操作步骤；
2. Changes：查看 AI 执行的文件更改记录（如创建 / 修改代码文件）；
3. VS Code：嵌入式代码编辑器，可直接浏览 / 修改 AI 生成的代码；
4. Terminal：内置终端，AI 可自动运行命令，你也可以手动操作；
5. Jupyter：Python 代码运行环境，适合数据可视化 / 脚本运行；
6. App：Web 服务预览，AI 部署的网页项目可直接在这里查看效果。

实战案例：让 AI 生成一个 Hello World 程序 + 运行

步骤 1：发起任务

在聊天面板的输入框中，输入自然语言指令：帮我写一个Python的Hello World程序，并运行它，点击发送。

步骤 2：AI 自动执行

OpenHands 会自动完成以下操作：

1. 分析需求，生成 Python 代码文件（如 hello.py）；
2. 在内置 Terminal 中运行python hello.py命令；
3. 在聊天面板返回运行结果，同时在 Changes/VS Code 中展示文件内容。

步骤 3：验证结果

在 Terminal 中可看到输出Hello World!，在 VS Code 中可直接修改代码，再次让 AI 重新运行，实现交互式开发。

进阶案例：生成一个简易网页计算器

输入指令：用HTML+CSS+JavaScript写一个简易的网页计算器，支持加减乘除，并且启动一个本地服务让我预览，OpenHands 会自动完成：

1. 生成 3 个文件：index.html（结构）、style.css（样式）、script.js（逻辑）；
2. 启动本地 Web 服务（如 Python 的 http.server）；
3. 在App面板中生成预览链接，直接点击即可使用计算器。

如果对效果不满意，可继续输入指令：把计算器的样式改成深色主题，按钮变大一点，AI 会自动修改代码并刷新预览。

六、高级用法：解锁 OpenHands 更多能力

1. 使用 CLI 命令行操作

适合快速执行简单任务，打开终端输入openhands即可进入 CLI 模式，直接输入自然语言指令即可，例如：

openhands
# 进入后输入：写一个bash脚本，实现批量重命名当前目录的txt文件

2. 自定义 AI Agent（SDK 使用）

OpenHands SDK 是核心引擎，可通过 Python 代码自定义 Agent 的行为，实现个性化需求，核心是基于CodeAct 范式编写 Agent 逻辑。

简单示例：创建一个能自动执行 Python 代码的简易 Agent

from openhands import MinimalAgent, State

# 初始化Agent
agent = MinimalAgent()
agent.reset()

# 定义任务状态
state = State(history=[])
# 执行任务：生成并运行斐波那契数列代码
result = agent.step(state, prompt="写一个Python函数，生成前10个斐波那契数，并打印结果")
print(result)

3. 团队协作（Cloud/Enterprise 版）

OpenHands Cloud/Enterprise 版支持多用户协作和资源管控：

1. 集成 GitHub/GitLab：AI 可直接拉取 / 提交代码，实现代码托管联动；
2. 集成 Slack/Jira：任务进度自动同步到协作工具，无需手动通知；
3. RBAC 权限管理：为团队成员分配不同权限，管控 AI 使用额度；
4. 对话共享：将 AI 开发过程分享给团队成员，实现协同调试。

七、避坑指南：常见问题与解决方法

1. 镜像拉取失败：国内环境建议使用国内 Docker 镜像源，或直接下载华为云 / 阿里云的 OpenHands 镜像；
2. 模型调用失败：检查 API Key 是否正确、模型是否支持、网络是否能访问模型平台（国内环境可能需要代理）；
3. 端口占用：若 3000 端口被占用，启动时修改映射端口，如-p 3001:3000；
4. AI 执行无响应：检查 Docker 服务是否正常，或重启 OpenHands 容器，同时确保 LLM 模型的调用额度充足；
5. 公网访问无法打开：检查 cpolar 隧道配置是否正确，服务器防火墙是否开放对应端口。

八、总结

OpenHands 作为一款开源的 AI 编程框架，真正实现了自然语言到代码的端到端转化，它不是简单的代码补全工具，而是能自主完成开发任务的 AI 助手，不管是个人开发提效，还是团队协作，都能发挥巨大作用。

核心学习重点：

1. 先通过Docker 一键部署快速上手，熟悉图形界面的基本操作；
2. 掌握模型配置，对接自己常用的 LLM；
3. 用自然语言指令尝试简单任务，逐步过渡到复杂项目开发；
4. 进阶学习SDK 二次开发，自定义 AI Agent，实现个性化需求。

OpenHands 的社区还在快速发展，后续会推出更多功能（如多 Agent 协作、更丰富的工具集成），关注OpenHands 官方文档和 GitHub 仓库，获取最新更新～

附：官方资源

1. OpenHands 官方文档：https://docs.openhands.dev/overview/introduction
2. GitHub 仓库：https://github.com/all-hands-ai/openhands
3. 社区交流：Slack（官方推荐，可获取最新技术支持）

---

创作不易，如果这篇教程对你有帮助，欢迎点赞 + 收藏 + 关注～ 后续会持续更新 OpenHands 进阶用法和 AI 编程技巧！