# OpenHands AI 开发者

## 概览

[OpenHands](https://github.com/All-Hands-AI/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 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) 以获取更多细节。

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

* Docker 引擎（所有 Clore.ai 镜像预装）
* NVIDIA 容器工具包（GPU 镜像上预装）
* Docker socket 可通过以下路径访问： `/var/run/docker.sock`
* 用于拉取 GHCR 镜像的出站互联网访问

***

## 快速开始

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

在 [Clore.ai 市场](https://clore.ai)，按以下条件过滤服务器：

* 内存 ≥ 16 GB（用于本地 LLM 组合）
* Docker：✓ 已启用
* 如果使用本地模型，请选择你偏好的 GPU

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

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

### 步骤 2：验证 Docker 是否运行

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

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

### 步骤 3：拉取并运行 OpenHands

```bash
# 设置工作区目录
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 的环境变量来配置，`:

```bash
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`  |

### 持久化配置文件

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

```bash
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 上的长时间会话：

```bash
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 指向它：

```bash
# 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 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) 以获取模型选择、性能调优和 GPU 配置。

### 方案 B：OpenHands + vLLM（高性能）

对于更大模型以获得最大吞吐量：

```bash
# 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 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/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 可以直接编辑你的文件：

```bash
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. 监控资源使用情况

```bash
# 监视 GPU 和内存使用情况
watch -n 2 'nvidia-smi && docker stats --no-stream'
```

### 4. 设定迭代限制

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

```bash
-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 权限被拒绝

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

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

### 沙箱容器无法启动

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

# 检查 GHCR 速率限制（可能需要认证）
docker login ghcr.io
```

### 端口 3000 无法访问

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

# 检查 Clore.ai 防火墙 — 确保在你的端口映射中包含 3000
# 在 Clore.ai 仪表板：服务器 → 端口 → 添加 3000:3000
```

### 与 Ollama 的 LLM 连接错误

```bash
# 测试 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
```

### 代理循环无限运行

```bash
# 减少最大迭代次数
docker stop openhands
docker run ... -e MAX_ITERATIONS=30 ...

# 或设置超时
-e SANDBOX_TIMEOUT=60
```

### 内存不足（OOM）

```bash
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 仓库](https://github.com/All-Hands-AI/OpenHands) — 源代码、问题与版本发布
* [OpenHands 文档](https://docs.all-hands.dev) — 官方文档，包括 LLM 配置
* [Clore.ai 上的 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) — 运行本地 LLM 以实现免费代理推理
* [Clore.ai 上的 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) — 高性能的本地 LLM 服务
* [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) — 为你的工作负载选择合适的 GPU
* [OpenHands Discord](https://discord.gg/ESHStjSjD4) — 社区支持与模型推荐
* [SWE-bench 排行榜](https://www.swebench.com) — 在真实的 GitHub 问题上比较代理性能