OpenHands安装使用小白教程

用Docker在本地跑通开源AI编程助手让AI帮你写代码、改Bug

— — — — — — — — — —

一、OpenHands是什么？

OpenHands（前身OpenDevin）是一个由All-Hands-AI团队开发的AI驱动软件开发代理平台，GitHub 70K+ Star。简单来说，它就是一个AI程序员——你用自然语言描述需求，它帮你写代码、改Bug、做代码审查，甚至在安全的沙箱环境中直接运行代码。

OpenHands的核心优势：

• 专为编程场景打造：代码生成、Bug修复、代码审查、测试编写

• 沙箱安全执行：AI生成的代码在Docker容器中运行，不污染本机环境

• Web可视化界面：浏览器操作，不需要命令行交互

• 多模型支持：兼容OpenAI、Anthropic、DeepSeek等主流LLM

二、安装前准备

2.1 系统要求

项目	要求
操作系统	Ubuntu 22.04/24.04（推荐）、macOS、Windows（WSL2）
Docker	24+版本
内存	至少8GB RAM
硬盘	至少5GB可用空间（Docker镜像较大）
网络	能访问大模型API和Docker Hub

2.2 安装Docker

Ubuntu/Debian：

sudo apt update sudo apt install -y docker.io sudo systemctl start docker sudo systemctl enable docker # 将当前用户加入docker组（避免每次sudo） sudo usermod -aG docker $USER newgrp docker

macOS：

brew install --cask docker # 安装后打开Docker Desktop应用

Windows：

# 下载安装 Docker Desktop for Windows # https://www.docker.com/products/docker-desktop/ # 安装时确保启用WSL2后端

⚠️ Docker是OpenHands的必须依赖，不能跳过！如果拉取镜像慢，建议配置Docker国内镜像源。

三、一键部署OpenHands

创建持久化目录：

mkdir -p ~/.openhands

拉取镜像并启动（复制整段命令执行）：

docker run -it --rm --pull=always \ -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \ -e LOG_ALL_EVENTS=true \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.openhands:/.openhands \ -p 3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:0.54

关键参数解释：

• -v /var/run/docker.sock:... → 允许容器调用宿主机Docker（关键！）

• -v ~/.openhands:... → 持久化配置数据

• -p 3000:3000 → 映射3000端口到本机

四、首次配置

1. 浏览器打开 http://localhost:3000

2. 在设置页面选择LLM Provider（如OpenAI）

3. 填入API Key

4. 如果使用兼容接口（如DeepSeek），还需配置Base URL和模型名称

💡 国内用户推荐使用DeepSeek API： Provider: OpenAI (兼容模式) Base URL: https://api.deepseek.com/v1 Model: deepseek-chat API Key: 你的DeepSeek密钥

五、跑通第一个任务

配置完成后，在对话框输入一个简单的测试任务：

请帮我创建一个Python Hello World程序，并运行它

你会看到OpenHands：

• 1. 理解你的需求

• 2. 在沙箱中创建Python文件

• 3. 运行代码

• 4. 将结果返回给你

如果看到正确的输出，恭喜你——部署成功！🎉

六、实用场景

场景	示例提示
写代码	请用Python写一个Web爬虫，爬取天气数据
修Bug	这段代码运行报错：[粘贴代码]，请帮我修复
代码审查	请审查以下代码的安全性和性能：[粘贴代码]
写测试	请为以下函数编写单元测试：[粘贴代码]
项目搭建	请帮我创建一个React+TypeScript项目的脚手架

七、常见问题

问题	解决方法
Docker权限报错	sudo usermod -aG docker $USER && newgrp docker
端口3000被占用	改用 -p 3001:3000 映射到3001端口
任务不执行	检查API Key和Base URL配置是否正确
拉取镜像失败	配置Docker国内镜像源或使用代理
容器秒退	去掉 --rm 参数启动，用 docker logs openhands-app 查看日志

⚠️ 安全提醒：此部署方式适合单用户本地工作站体验。如果暴露到公网，务必通过反向代理+身份认证做安全加固！

— — — — — — — — — —

本文发布于2026年6月4日。OpenHands更新频繁，镜像版本号可能变化，请关注 github.com/OpenHands/OpenHands 获取最新版本。