# 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 比较指南](/guides/guides_v2-zh/ru-men/gpu-comparison.md) 以获取更多细节。

**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 指南](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) 以获取模型选择、性能调优和 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 指南](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) 以获取完整设置、量化选项和多 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](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) — 运行本地 LLM 以实现免费代理推理
* [Clore.ai 上的 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) — 高性能的本地 LLM 服务
* [GPU 比较指南](/guides/guides_v2-zh/ru-men/gpu-comparison.md) — 为你的工作负载选择合适的 GPU
* [OpenHands Discord](https://discord.gg/ESHStjSjD4) — 社区支持与模型推荐
* [SWE-bench 排行榜](https://www.swebench.com) — 在真实的 GitHub 问题上比较代理性能


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/openhands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.