OpenHands AI 开发者

在 Clore.ai 部署 OpenHands（前称 OpenDevin）——在经济型 GPU 云服务器上运行一个完全自主的 AI 软件工程师，用于编码、调试和解决 GitHub 问题。

概览

OpenHands （前称 OpenDevin）是一个用于自主 AI 软件开发代理的开源平台。拥有 65K+ GitHub 星标，它已成为将实际编程任务委派给 AI 的最受欢迎工具之一——编写代码、修复错误、解决 GitHub 问题、运行 shell 命令、浏览网页，并端到端地与代码库交互。

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

为什么选择 Clore.ai 托管 OpenHands？

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

• 然而，将其与同一服务器上的 本地大模型 （Ollama、vLLM）配合使用可以消除 API 成本和延迟

• Clore.ai 的低成本 GPU 服务器让你以最低 $0.20–$0.35/小时

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

• 非常适合那些通过云 LLM API 会非常昂贵的长时间自动化任务

在 Clore.ai 上的典型使用场景：

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

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

• 在 100% 离线环境下运行 OpenHands + Ollama 进行代理式开发

• 无需 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）	速度	24 GB	16 GB	40 GB	~$0.20/小时
+ Ollama（Qwen2.5 32B）	512x512	24 GB	32 GB	60 GB	~$0.35/小时
+ vLLM（Llama 3.1 70B）	4 小时会话	80 GB	64 GB	100 GB	~$1.10/小时
+ vLLM（Llama 3.3 70B INT4）	512x512	24 GB	32 GB	80 GB	~$0.35/小时

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

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

• Docker 引擎（所有 Clore.ai 镜像预装）

• NVIDIA 容器工具包（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 可通过以下地址访问： http://<server-ip>:3000

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

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

步骤 5：配置你的 LLM

在 Web 界面设置中：

• 提供商： 选择 OpenAI、Anthropic、Google 或 自定义

• API 密钥： 输入你的 API 密钥

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

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

• 提供商： ollama

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

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

---

配置

使用环境变量进行 SSH 和 Jupyter 访问：

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

变量	4s	默认值
LLM_MODEL	模型标识符（例如 gpt-4o, claude-3-5-sonnet-20241022)	在 UI 中设置
LLM_API_KEY	LLM 提供商的 API 密钥	在 UI 中设置
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，但将其与运行在 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. 启动将 OpenHands 指向 Ollama
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 配置。

推荐的本地编码模型

A100	规模	最小显存	质量
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. 为获得最佳结果的任务提示（Prompt）

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 令牌：你的个人访问令牌，需具备 repo 权限范围

• OpenHands 会克隆仓库、修复问题并创建一个 PR

6. 成本估算

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

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

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

• 对于每天 100+ 个任务，Clore.ai 上的本地 LLM 能收回成本

---

# 使用固定种子以获得一致结果

Docker Socket 权限被拒绝

# 错误：尝试连接 Docker 守护进程时权限被拒绝
# 修复：确保 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 仪表板：服务器 → 端口 → 添加 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

# 或使用量化版本（占用更少显存）
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 问题上比较代理性能