> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/openhands.md).

# OpenHands AI 开发者

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

## 概览

[OpenHands](https://github.com/All-Hands-AI/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 | [裸机](https://clore.ai/bare-metal) |
| **+ 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 比较指南](/guides/guides_v2-zh/ru-men-zhi-nan/gpu-comparison.md) 。

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

* Docker Engine（Clore.ai 所有镜像均已预装）
* NVIDIA Container Toolkit（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

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

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

| 变量                | 描述                                               | 默认值     |
| ----------------- | ------------------------------------------------ | ------- |
| `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` |

### 持久化配置文件

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

```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，但将它与一个 **本地 LLM** 运行在 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. 启动指向 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 指南](/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 配置。

### 推荐用于编程的本地模型

| 模型                      | 大小  | 最低显存  | 质量    |
| ----------------------- | --- | ----- | ----- |
| `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. 通过任务提示获得最佳结果

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

```bash
# 错误：尝试连接 Docker daemon 时权限被拒绝
# 修复：确保该 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 仪表板中：Server → Ports → Add 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

# 或使用量化版本（更少 VRAM）
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-zhi-nan/gpu-comparison.md) — 为你的工作负载选择合适的 GPU
* [OpenHands Discord](https://discord.gg/ESHStjSjD4) — 社区支持和模型推荐
* [SWE-bench 排行榜](https://www.swebench.com) — 对比代理在真实 GitHub 问题上的表现


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.