《OpenHands 安装部署教程：用 Docker 在本地快速跑通开源 AI 编码助手》

OpenHands 这类项目，第一眼看上去都像"下一代开发神器"，第二眼就容易掉进环境、权限、端口和 API Key 的坑里。

这篇文章不聊概念泡沫，直接走普通开发者最容易复现的路线：用 Docker 在本地启动 OpenHands，配置模型，打开 Web 页面，并完成第一个最小可用任务验证。

一、项目背景

OpenHands 是一个面向软件开发场景的开源 AI Agent 平台，前身是 OpenDevin。它的目标不是做一个普通聊天框，而是让 AI 具备更接近开发者的操作能力，比如修改代码、执行命令、浏览网页、调用 API 等。

对于普通开发者来说，OpenHands 值得折腾一下的原因很直接：

它不是单纯"对话式问答"
它更强调执行能力
本地启动后就能直接看到图形界面
很适合写成"安装部署 + 跑通第一个任务"的教程闭环

官方GitHub的项目地址:

https://github.com/All-Hands-AI/OpenHands

官方文档：

https://docs.all-hands.dev

从官方 README 来看，OpenHands 提供了两条主线路：

用 uv 直接启动
用 Docker 运行本地 GUI

这篇文章优先选择 Docker 本地部署，原因很现实：隔离更好、复现更稳、也更适合大多数 CSDN 读者照着跑。

二、本文环境说明

本文采用的是本地简化部署方案，目标是先把 OpenHands 跑起来，而不是一步到位做复杂生产级加固。

1. 操作系统

Ubuntu 22.04 / 24.04 均可
理论上其他支持 Docker 的 Linux 发行版也可参考

2. 软件环境

Docker 24+
可用的公网网络环境
一个可用的 LLM API Key

3. 部署方式

Docker 单容器启动
浏览器访问本地 Web GUI
首次进入页面后再配置 LLM 提供商和 API Key

4. 端口说明

OpenHands Web GUI 默认映射到本机：
- 3000

5. 重要说明

这是一个适合单用户本地工作站的项目。官方也明确提醒：

不适合多租户多人共用
默认不带完整认证、隔离和扩展能力
如果部署在公网，必须额外做安全加固

换句话说，拿它本地体验没问题；直接裸奔到公网，风险不小，别图省事。

三、安装前准备

1. 检查 Docker 是否安装成功

先执行：

bash 复制代码

docker --version

如果能看到类似输出，说明 Docker 已安装：

bash 复制代码

Docker version 24.x.x, build xxxxxxx

再检查 Docker 服务是否正常：

bash 复制代码

docker ps

如果这里直接报权限错误，先不要怀疑人生，十有八九只是当前用户没进 docker 组。

可以这样处理：

bash 复制代码

sudo usermod -aG docker $USER
newgrp docker

然后重新执行：

bash 复制代码

docker ps

2. 准备本地持久化目录

OpenHands 官方 Docker 启动命令会把本地 ~/.openhands 挂载到容器里，用来保存配置和状态。

先手动创建一下：

bash 复制代码

mkdir -p ~/.openhands

3. 确认端口 3000 未被占用

执行：

bash 复制代码

ss -lntp | grep 3000

如果已经有进程占用 3000 端口，要么停掉旧服务，要么稍后改端口映射。

4. 准备 API Key

OpenHands 启动后，需要你在页面里选择 LLM 提供商并填入 API Key。

常见可选路线包括：

Anthropic
OpenAI
兼容 OpenAI API 的第三方服务

如果你暂时没有 Key，服务能启动，但核心能力跑不起来。这不是 OpenHands 坏了，是模型没法干活。

四、安装与部署

这一节是主线，尽量别跳步。

1. 拉取运行时镜像

官方 README 中给出的运行时镜像类似下面这样：

bash 复制代码

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik

这个镜像标签未来可能变化，所以如果你看到官方 README 里版本更新，优先以官方文档为准 。

2. 启动 OpenHands 容器

直接执行下面这条命令：

bash 复制代码

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

3. 这条命令里几个关键参数的作用

很多人复制命令就跑，出了问题又不知道问题在哪。这里把关键项拆开说一下：

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=...
- 指定 OpenHands 使用的运行时容器镜像
-e LOG_ALL_EVENTS=true
- 打开更完整的事件日志，排错时比较有用
-v /var/run/docker.sock:/var/run/docker.sock
- 让容器内部可以调用宿主机 Docker
- 这是关键，也是风险点
-v ~/.openhands:/.openhands
- 持久化 OpenHands 的本地数据
-p 3000:3000
- 把容器内 3000 端口映射到本机 3000
--add-host host.docker.internal:host-gateway
- 让容器能更方便访问宿主机网络

4. 启动成功后访问页面

容器正常启动后，浏览器打开：

text 复制代码

http://localhost:3000

如果你是远程 Linux 服务器部署，不是在本机图形桌面上跑，那就把 localhost 换成服务器 IP，再确认安全组、防火墙和端口策略。

5. 首次进入页面需要做什么

第一次打开 OpenHands 页面，通常会提示你：

选择 LLM Provider
填写 API Key
保存配置

如果你使用的是 OpenAI 兼容接口，除了 Key 外，可能还需要配置：

Base URL
Model 名称

这一部分以页面实际配置项为准，不建议在没确认版本结构的情况下乱填教程字段名。因为这类项目更新速度快，UI 字段名偶尔会变。

五、配置说明

OpenHands 的本地快速体验配置，重点其实不在一堆 YAML，而在以下几个核心点。

1. 数据目录

本教程挂载的数据目录是：

bash 复制代码

~/.openhands

这个目录通常用于保存：

本地状态
会话数据
配置信息

如果你之前用过较老版本 OpenHands，官方 README 提到过一个迁移操作：

bash 复制代码

mv ~/.openhands-state ~/.openhands

只有你确实存在旧目录时再执行，不要为了"看起来完整"硬搬。

2. LLM 配置

首次启动后，最重要的配置就是模型提供商信息，包括：

Provider
API Key
可能的 Base URL
模型名称

最小可用思路是：

先只配置一套能用的模型服务
不要一上来接一堆 provider
先确保能完成一个简单任务，再慢慢折腾高级配置

3. Docker Socket 权限

这一项很容易被忽略，但它决定 OpenHands 是否能正常调用沙箱能力：

bash 复制代码

-v /var/run/docker.sock:/var/run/docker.sock

如果这项没挂进去，或者当前 Docker 环境权限异常，OpenHands 的很多执行能力会直接受影响。

4. 安全提醒

如果你只是本机体验，这种启动方式可以接受。

如果你打算部署到公网，请至少考虑：

不要直接监听公网开放访问
反向代理加认证
限制来源 IP
降低容器权限
做好主机安全隔离

不然你部署的不是 AI 助手，是给外部世界开了扇门。

六、跑通第一个 Demo

这一节只做最小闭环，不追求高级。

1. 打开 OpenHands Web 界面

访问：

text 复制代码

http://localhost:3000

如果页面正常打开，说明：

容器起来了
Web GUI 正常
端口映射没问题

2. 完成模型配置

在页面中选择你的模型提供商，并填入 API Key。

建议第一步先用你最熟悉、最稳定的一套模型服务。别上来就折腾代理、转发、私有网关、奇怪兼容层，不然最后你会分不清是 OpenHands 的问题，还是模型接入链路炸了。

3. 输入一个简单任务

建议先用最基础的任务验证，比如：

text 复制代码

请帮我创建一个 Python Hello World 示例，并说明如何运行。

或者：

text 复制代码

分析一个最小的 Python 项目结构，并给出 main.py 示例。

这种任务的好处是：

不依赖复杂外部资源
输出容易判断是否成功
不会一上来就把 Agent 压成高难副本

4. 成功后你应该看到什么

如果链路正常，通常会看到这些现象：

页面内开始出现任务执行过程
Agent 有步骤性输出
可能会展示命令执行、文件生成、思考过程摘要
最终返回结果内容

如果页面能打开，但任务完全不执行，大概率不是"部署成功了"，而是模型配置链路没打通。

七、效果验证

部署成功不能只靠"页面打开了"。至少做下面 3 类验证。

1. 验证容器状态

执行：

bash 复制代码

docker ps

你应该能看到类似容器在运行：

bash 复制代码

CONTAINER ID   IMAGE                                             STATUS         PORTS
xxxxxx         docker.all-hands.dev/all-hands-ai/openhands:0.54  Up xx minutes  0.0.0.0:3000->3000/tcp

如果看不到，说明容器压根没活着。

2. 验证服务日志

执行：

bash 复制代码

docker logs -f openhands-app

关注这些内容：

服务启动日志
端口监听是否正常
是否有模型配置相关报错
是否有 Docker Socket 访问异常

如果日志一直刷错误，页面就算打开了，也只是"壳子活着"。

3. 验证 Web 页面可访问

浏览器访问：

text 复制代码

http://localhost:3000

成功标志：

页面能完整加载
能看到 OpenHands 界面
可以正常提交任务

4. 验证 Agent 任务执行成功

输入一个简单任务后，观察：

是否开始执行
是否有步骤输出
是否最终返回结果
是否提示模型调用失败或权限错误

只有这一步成功，才能算你真正把 OpenHands 跑通了。

八、常见报错与解决方案

这一节我说得直接一点，因为很多问题真不是项目本身有多离谱，而是环境和权限在搞事。

1. 报错：Docker 命令无权限 / cannot connect to the Docker daemon

典型现象：

bash 复制代码

permission denied while trying to connect to the Docker daemon socket

原因

当前用户没有权限访问 Docker 守护进程。

解决方案

bash 复制代码

sudo usermod -aG docker $USER
newgrp docker
docker ps

如果还是不行，确认 Docker 服务已启动：

bash 复制代码

sudo systemctl status docker
sudo systemctl start docker

2. 报错：3000 端口被占用

典型现象：

bash 复制代码

bind: address already in use

原因

本机已有服务占用了 3000 端口。

解决方案

先找占用进程：

bash 复制代码

ss -lntp | grep 3000

如果不想停掉它，就改端口映射，比如改成 3001：

bash 复制代码

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 3001:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:0.54

然后访问：

text 复制代码

http://localhost:3001

3. 页面能打开，但任务不执行

原因

这种情况十有八九出在：

API Key 没填对
Provider 选错
Base URL 配错
模型名写错
模型服务本身不可用

解决方案

按下面顺序查：

检查 Provider 是否与你的 Key 对应
检查 API Key 是否有效
如果是兼容 OpenAI 的服务，确认 Base URL 是否正确
检查模型名是否存在
看页面报错或容器日志

别一遇到这类问题就重装容器，重装对错误的 Key 没有治疗效果。

4. 报错：容器反复退出 / 启动后秒退

原因

常见原因包括：

镜像拉取不完整
Docker 环境异常
参数写错
本地资源不足
某些挂载路径不存在或权限异常

解决方案

先看日志：

bash 复制代码

docker logs openhands-app

如果因为 --rm 导致容器退出后日志难看，建议先去掉 --rm 再重启观察。

同时检查：

bash 复制代码

ls -al ~/.openhands
docker images | grep openhands
docker images | grep runtime

必要时重新拉镜像：

bash 复制代码

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.54

5. 报错：拉取镜像失败

典型现象：

网络超时
TLS 错误
拉取速度极慢

原因

网络环境问题最常见。

解决方案

可以尝试：

切换网络环境
配置 Docker 代理
稍后重试
确认镜像地址和标签是否与官方 README 一致

如果官方版本号更新了，别死磕旧标签。

6. 报错：Docker Socket 相关异常

原因

OpenHands 需要访问宿主机 Docker Socket 才能完成某些运行时操作。

解决方案

确认启动参数里包含：

bash 复制代码

-v /var/run/docker.sock:/var/run/docker.sock

然后检查宿主机上这个文件是否存在：

bash 复制代码

ls -l /var/run/docker.sock

如果宿主机 Docker 本身没启动，挂进去也没意义。

九、进阶说明

当你已经完成本地启动后，后续可以继续往下面几个方向深入：

1. 使用 CLI 或 uv 方式运行

官方也支持：

bash 复制代码

uvx --python 3.12 --from openhands-ai openhands serve

这种方式更适合想深入研究本地 Python 环境和开发链路的同学。

2. 对接更多模型提供商

后续你可以逐步尝试：

OpenAI
Anthropic
兼容 OpenAI API 的第三方网关
私有模型服务

但建议一次只改一项，不要把排错复杂度主动拉满。

3. 研究源码和开发模式

如果你不只是想"用"，而是想"改"，可以继续看：

项目源码目录
Development 文档
官方 Docs 的 SDK / CLI 说明

4. 做更安全的部署

如果你想在团队内部用，就别停留在本文这个最简方案。需要进一步考虑：

反向代理
身份认证
访问控制
日志审计
主机级隔离

十、总结

到这里，你已经完成了 OpenHands 的一条最小可运行闭环：

准备 Docker 环境
拉取官方镜像
启动本地 GUI
配置模型提供商
跑通第一个简单任务
用容器状态、日志和页面结果验证部署是否成功

如果你的目标只是先体验 OpenHands 到底能不能用 ，做到这里其实已经够了。

后面那些更复杂的能力，比如更深的 Agent 执行链、更多模型接入、甚至更重的企业级部署，完全可以等你把第一步踩稳再说。别一上来就想把所有功能都拎起来，那通常不是高效，是给自己加班。

十一、适合谁？继续深入

想做 AI 编码助手 体验和对比测试的开发者
想研究 软件工程 Agent 的工程师
想把 Agent 能力接入现有研发流程的团队
想阅读源码、参与二次开发的 Python / AI Infra 开发者
想探索 CLI、SDK、Local GUI 多种使用方式的技术用户

这些读者比较适合继续往深处研究 OpenHands

如果你只是想先感受一下"AI 代理式开发"到底是不是那么回事，那跑通本文这条 Docker 路线就已经有参考价值了。