前言
在 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，源码可见（需授权），含专属支持 | 大型企业，需要数据私有化、定制化服务和高级支持 |
核心优势
二、准备工作：环境要求与核心依赖
OpenHands 的部署和使用非常轻量化，核心依赖只有两个，提前准备好即可：
可选工具：内网穿透工具（如 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：配置公网访问
- 隧道名称：openhands（自定义）；
- 协议：HTTP；
- 本地地址：3000（OpenHands 默认端口）；
- 地区：根据服务器位置选择（如 China Top）；
四、首次使用：配置 LLM 模型（关键步骤）
OpenHands 本身不提供大模型，需要对接外部 LLM，首次打开界面会弹出模型配置窗口，按以下步骤操作即可。
步骤 1：基础配置（主流 LLM，如 GPT/Claude）
步骤 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 部分：
实战案例：让 AI 生成一个 Hello World 程序 + 运行
步骤 1：发起任务
在聊天面板的输入框中，输入自然语言指令：帮我写一个Python的Hello World程序，并运行它，点击发送。
步骤 2：AI 自动执行
OpenHands 会自动完成以下操作：
步骤 3：验证结果
在 Terminal 中可看到输出Hello World!，在 VS Code 中可直接修改代码，再次让 AI 重新运行，实现交互式开发。
进阶案例：生成一个简易网页计算器
输入指令：用HTML+CSS+JavaScript写一个简易的网页计算器，支持加减乘除，并且启动一个本地服务让我预览，OpenHands 会自动完成：
如果对效果不满意，可继续输入指令：把计算器的样式改成深色主题，按钮变大一点，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 版支持多用户协作和资源管控：
七、避坑指南：常见问题与解决方法
八、总结
OpenHands 作为一款开源的 AI 编程框架，真正实现了自然语言到代码的端到端转化，它不是简单的代码补全工具，而是能自主完成开发任务的 AI 助手，不管是个人开发提效，还是团队协作，都能发挥巨大作用。
核心学习重点：
OpenHands 的社区还在快速发展，后续会推出更多功能（如多 Agent 协作、更丰富的工具集成），关注OpenHands 官方文档和 GitHub 仓库，获取最新更新～
附：官方资源
创作不易，如果这篇教程对你有帮助，欢迎点赞 + 收藏 + 关注～ 后续会持续更新 OpenHands 进阶用法和 AI 编程技巧！
