OpenHands AI 开发者

在 Clore.ai 上部署 OpenHands（原 OpenDevin）——在经济实惠的 GPU 云服务器上运行一个完全自主的 AI 软件工程师，用于编码、调试和 GitHub issue 处理。

概览

OpenHands （原名 OpenDevin）是一个用于自主 AI 软件开发代理的开源平台。凭借 6.5 万+ GitHub 星标，它已成为将真实编程任务委托给 AI 的最受欢迎工具之一——编写代码、修复漏洞、解决 GitHub 问题、运行 shell 命令、浏览网页，并端到端地与你的代码库交互。

不同于典型的代码补全工具，OpenHands 运行的是一个 代理循环：它接收任务，进行规划，编写代码，执行代码，观察输出，并不断迭代——全程无需人工干预。它支持数十种 LLM 后端，包括 OpenAI、Anthropic Claude、Google Gemini，以及通过 Ollama 或 vLLM 托管在本地的模型。

为什么选择用 Clore.ai 运行 OpenHands？

• OpenHands 本身基于 CPU，不需要 GPU

• 不过，将它与 本地 LLM （Ollama、vLLM）部署在同一台服务器上，可以消除 API 成本和延迟

• Clore.ai 价格亲民的 GPU 服务器让你可以同时运行 OpenHands 和本地模型，最低只需 $0.20–$0.35/小时

• 你将获得持久化工作区存储、Docker-in-Docker 支持以及完整的 root 访问权限

• 非常适合那些通过云端 LLM API 运行会很昂贵的长时间自主任务

在 Clore.ai 上的典型用例：

• 根据规范或问题描述自主生成代码

• 对大型代码库进行批量重构

• 将 OpenHands + Ollama 一起运行，实现 100% 离线的代理式开发

• 无需 API 成本的 CI/CD 任务自动化

---

需求

OpenHands 需要访问 Docker socket，并会在内部运行一个沙箱化的运行时容器。下表列出了在 Clore.ai 上推荐的配置：

配置	GPU	显存	内存	存储	预估价格
仅 API（不使用本地 LLM）	任意 / 仅 CPU	不适用	8 GB	20 GB	约 $0.05–0.10/小时
+ Ollama（Llama 3.1 8B）	RTX 3090	24 GB	16 GB	40 GB	$0.07–0.21/小时
+ Ollama（Qwen2.5 32B）	RTX 4090	24 GB	32 GB	60 GB	$0.14–0.42/小时
+ vLLM（Llama 3.1 70B）	A100 80GB	80 GB	64 GB	100 GB	裸机
+ vLLM（Llama 3.3 70B INT4）	RTX 4090	24 GB	32 GB	80 GB	$0.14–0.42/小时

注意： 如果你只使用 OpenAI/Anthropic/Gemini API，任何内存 ≥8 GB 的服务器都可以。只有当你希望在同一台机器上运行本地 LLM 时才需要 GPU。更多详情请参见 GPU 比较指南 。

Clore.ai 服务器上的软件要求：

• Docker Engine（Clore.ai 所有镜像均已预装）

• NVIDIA Container Toolkit（GPU 镜像已预装）

• Docker socket 可访问于 /var/run/docker.sock

• 可访问外网以拉取 GHCR 镜像

---

快速开始

步骤 1：选择并连接到 Clore.ai 服务器

在 Clore.ai 市场，按以下条件筛选服务器：

• 内存 ≥ 16 GB（用于本地 LLM 组合）

• Docker：✓ 已启用

• 如果使用本地模型，请选择你偏好的 GPU

服务器配置完成后，通过 SSH 连接：

ssh root@<server-ip> -p <port>

步骤 2：验证 Docker 是否正在运行

docker info
ls -la /var/run/docker.sock

这两个命令都应成功。如果 Docker socket 缺失，请联系 Clore.ai 支持或选择其他镜像。

步骤 3：拉取并运行 OpenHands

# 设置工作区目录
export WORKSPACE_BASE=$(pwd)/workspace
mkdir -p $WORKSPACE_BASE

# 运行 OpenHands（会从 GHCR 拉取最新的 0.38 镜像）
docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

步骤 4：访问 Web UI

UI 可访问于 http://<server-ip>:3000

Clore.ai 端口转发： 在 Clore.ai 仪表板中，确保端口 3000 已在你的服务器配置中转发/暴露。某些模板会限制外部端口——请查看服务器详情中的“Ports”部分。

首次启动时，OpenHands 会提示你配置一个 LLM 提供商。

步骤 5：配置你的 LLM

在 Web UI 设置中：

• 提供商： 选择 OpenAI、Anthropic、Google 或 Custom

• API Key： 输入你的 API 密钥

• 模型： 例如， gpt-4o, claude-3-5-sonnet-20241022，或 ollama/llama3.1

对于本地 Ollama（见下方 GPU 加速部分），请使用：

• 提供商： ollama

• 基础 URL： http://host.docker.internal:11434

• 模型： ollama/llama3.1:8b

---

配置

环境变量

OpenHands 可以完全通过传递给 docker run:

docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_BASE_URL="" \
  -e SANDBOX_TIMEOUT=120 \
  -e MAX_ITERATIONS=100 \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

变量	描述	默认值
LLM_MODEL	模型标识符（例如 gpt-4o, claude-3-5-sonnet-20241022)	在界面中设置
LLM_API_KEY	LLM 提供商的 API 密钥	在界面中设置
LLM_BASE_URL	自定义基础 URL（用于 Ollama、vLLM、LiteLLM）	提供商默认值
SANDBOX_TIMEOUT	代理沙箱超时时间（秒）	120
MAX_ITERATIONS	每个任务的最大代理循环迭代次数	100
SANDBOX_USER_ID	沙箱运行使用的 UID（使用 $(id -u))	0
LOG_ALL_EVENTS	启用详细事件日志记录（true/false)	false

持久化配置文件

你可以通过挂载配置目录来持久化设置：

mkdir -p /opt/openhands/config

docker run -it --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/config:/app/config \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

后台运行（分离模式）

对于在 Clore.ai 上长时间运行的会话：

export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \\
  --name openhands \
  --restart unless-stopped \
  --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 \
  -e LLM_API_KEY=your_api_key_here \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

# 查看日志
docker logs -f openhands

---

GPU 加速（本地 LLM 集成）

虽然 OpenHands 本身不会使用 GPU，但将它与一个 本地 LLM 运行在 Clore.ai GPU 上的模型结合起来，你就能获得一个强大、经济、无需 API 的自主代理。

选项 A：OpenHands + Ollama（推荐新手）

先运行 Ollama，然后让 OpenHands 指向它：

# 1. 启动 Ollama（完整详情请参见 Ollama 指南）
docker run -d \\
  --name ollama \\
  --gpus all \\
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

# 2. 拉取一个适合编程的优化模型
docker exec ollama ollama pull qwen2.5-coder:7b
# 或者选择更强一些的：
docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull deepseek-coder-v2:16b

# 3. 启动指向 Ollama 的 OpenHands
export WORKSPACE_BASE=/opt/workspace
mkdir -p $WORKSPACE_BASE

docker run -d \\
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \
  -e LLM_MODEL=ollama/qwen2.5-coder:7b \
  -e LLM_BASE_URL=http://host.docker.internal:11434 \
  -e LLM_API_KEY=ollama \
  -v $WORKSPACE_BASE:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

查看完整的 Ollama 指南 以了解模型选择、性能调优和 GPU 配置。

选项 B：OpenHands + vLLM（高性能）

若要在更大模型上获得最高吞吐量：

# 1. 使用一个编程模型启动 vLLM
docker run -d \\
  --name vllm \\
  --gpus all \\
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 16384 \\
  --gpu-memory-utilization 0.92

# 等待模型加载（约 2-5 分钟）
docker logs -f vllm | grep "Application startup"

# 2. 使用 vLLM 后端启动 OpenHands
docker run -d \\
  --name openhands \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.38-nikolaik \
  -e SANDBOX_USER_ID=0 \
  -e WORKSPACE_MOUNT_PATH=/opt/workspace \
  -e LLM_MODEL=openai/Qwen/Qwen2.5-Coder-32B-Instruct \
  -e LLM_BASE_URL=http://host.docker.internal:8000/v1 \
  -e LLM_API_KEY=none \
  -v /opt/workspace:/opt/workspace_base \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  ghcr.io/all-hands-ai/openhands:0.38

请参阅 vLLM 指南 以了解完整设置、量化选项和多 GPU 配置。

推荐用于编程的本地模型

模型	大小	最低显存	质量
qwen2.5-coder:7b	7B	8 GB	★★★☆☆
deepseek-coder-v2:16b	16B	12 GB	★★★★☆
qwen2.5-coder:32b	32B	24 GB	★★★★☆
llama3.1:70b	70B	48 GB	★★★★★

---

提示与最佳实践

1. 明智地使用工作区挂载

将你的实际项目目录挂载为工作区，这样 OpenHands 就能直接编辑你的文件：

export WORKSPACE_BASE=/opt/my-project
git clone https://github.com/your/repo $WORKSPACE_BASE

2. 通过任务提示获得最佳结果

OpenHands 最适合使用具体、可执行的提示：

✅ 好："修复 src/auth/login.py 中的认证漏洞，其中 JWT 令牌 
         会立即过期。问题出在令牌过期时间的计算上。"

❌ 差："修复这个 bug"

3. 监控资源使用情况

# 观察 GPU 和内存使用情况
watch -n 2 'nvidia-smi && docker stats --no-stream'

4. 设置迭代限制

防止失控的代理消耗过多 API 令牌：

-e MAX_ITERATIONS=50  # 每个任务限制为 50 步

5. GitHub 集成

OpenHands 可以直接解决 GitHub 问题。在 UI 中配置：

• GitHub Token：你拥有以下权限的个人访问令牌： repo 范围

• OpenHands 将克隆仓库、修复问题并创建 PR

6. 成本估算

对于基于 API 的 LLM，按每个任务估算成本：

• 简单 bug 修复：约 $0.05–0.15（Claude Haiku/GPT-4o-mini）

• 复杂功能：约 $0.50–2.00（Claude Sonnet/GPT-4o）

• 对于每天 100+ 个任务，在 Clore.ai 上运行本地 LLM 就能回本

---

故障排查

Docker Socket 拒绝权限

# 错误：尝试连接 Docker daemon 时权限被拒绝
# 修复：确保该 socket 可访问
ls -la /var/run/docker.sock
# 应显示：srw-rw---- 1 root docker ...

# 如有需要，将你的用户加入 docker 组
usermod -aG docker $USER
# 然后重启 shell 或使用：newgrp docker

沙箱容器启动失败

# 检查运行时镜像是否可访问
docker pull ghcr.io/all-hands-ai/runtime:0.38-nikolaik

# 检查 GHCR 限流（可能需要认证）
docker login ghcr.io

端口 3000 无法访问

# 验证容器正在运行且端口已绑定
docker ps | grep openhands
docker port openhands

# 检查 Clore.ai 防火墙——确保端口 3000 已包含在你的端口映射中
# 在 Clore.ai 仪表板中：Server → Ports → Add 3000:3000

与 Ollama 的 LLM 连接错误

# 测试 OpenHands 容器是否能访问 Ollama
docker exec openhands curl http://host.docker.internal:11434/api/tags

# 如果失败，请验证 docker run 中是否包含 --add-host 标志
# 另外检查 Ollama 容器是否正在运行：
docker ps | grep ollama
docker logs ollama | tail -20

代理无限循环

# 降低最大迭代次数
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# 或设置超时
-e SANDBOX_TIMEOUT=60

内存不足（OOM）

# 检查内存使用情况
free -h
docker stats

# 如果正在运行本地 LLM，尝试更小的模型
docker exec ollama ollama pull qwen2.5-coder:3b

# 或使用量化版本（更少 VRAM）
docker exec ollama ollama pull llama3.1:8b-instruct-q4_K_M

---

延伸阅读

• OpenHands GitHub 仓库 — 源代码、问题和发布版本

• OpenHands 文档 — 包括 LLM 配置在内的官方文档

• Clore.ai 上的 Ollama — 免费运行本地 LLM 进行代理推理

• Clore.ai 上的 vLLM — 高性能本地 LLM 服务

• GPU 比较指南 — 为你的工作负载选择合适的 GPU

• OpenHands Discord — 社区支持和模型推荐

• SWE-bench 排行榜 — 对比代理在真实 GitHub 问题上的表现