OpenHands - 安装与使用指南 | AI 智能体工具

概述

OpenHands 是由 All-Hands-AI 团队维护的开源 AI 软件工程师平台。它继承了 OpenDevin 项目，旨在构建能够自主完成软件工程任务的通用 AI Agent。OpenHands 提供完整的开发框架，包括 Agent 运行时、工具系统、沙箱环境和评估框架。它支持多种 LLM 后端，可用于研究和生产环境。

安装

推荐使用 Docker 安装 OpenHands，以确保环境隔离和一致性。需要 Docker 26.0+ 和 Python 3.12+。安装过程包括拉取 Docker 镜像、配置环境变量和启动服务。也支持通过 pip 安装 Python 包用于开发。

bash

# Docker installation
docker pull openhands/openhands:latest

# Start OpenHands
docker run -it \
  -p 3000:3000 \
  -e OPENAI_API_KEY=your-key \
  -v /var/run/docker.sock:/var/run/docker.sock \
  openhands/openhands:latest

# Or use pip
pip install openhands-ai

Docker 配置

OpenHands 使用 Docker 进行沙箱隔离，每个 Agent 在独立容器中运行。需要配置 Docker socket 挂载、工作目录映射、网络设置等。Docker 配置确保 Agent 在安全环境中执行代码，不影响宿主系统。

bash

# docker-compose.yml
version: '3'
services:
  openhands:
    image: openhands/openhands:latest
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./workspace:/workspace

架构

OpenHands 的架构包括：Agent Runtime、Event Stream、Runtime Environment 和 Tool System。Agent 通过事件流与环境及工具交互，每个操作都记录在事件历史中，支持回放和审计。

创建 Agent

OpenHands 支持自定义 Agent。通过继承 Agent 类，可以实现特定的 Agent 行为、工具调用逻辑和推理策略。Agent 可配置不同的 LLM、系统提示词、工具集等。

bash

# Custom agent example
from openhands.agent import Agent

class MyAgent(Agent):
    def __init__(self, llm, config):
        super().__init__(llm, config)
        self.name = "MyAgent"
    
    def step(self, state):
        # Implement agent logic
        action = self.llm.chat(state.history)
        return action

运行时

OpenHands 的运行时环境提供沙箱执行能力，支持文件系统操作、命令执行、代码运行等。运行时基于 Docker，确保 Agent 操作在隔离环境中进行。支持自定义运行时镜像，可预装特定工具和依赖。

安全

OpenHands 非常重视安全，使用 Docker 沙箱隔离 Agent 操作，防止对宿主系统的潜在危害。支持网络隔离、资源限制和文件系统权限控制。建议在生产环境中使用额外的安全措施，如 API key 管理和访问控制。

评估

OpenHands 提供评估框架，支持在 SWE-bench、HumanEval 等基准上评估 Agent 性能。评估框架可衡量 Agent 的任务完成率、代码质量、执行效率等指标。这有助于比较不同配置和模型的效果。

bash

# Run SWE-bench evaluation
python -m openhands.eval \
  --benchmark swe-bench \
  --agent CodeActAgent \
  --model gpt-4 \
  --max-iterations 30

社区

OpenHands 拥有活跃的开源社区，GitHub 上有众多贡献者。社区通过 Discord 和 GitHub Discussions 交流。定期举行开发者会议讨论路线图和新功能。欢迎社区贡献代码、文档和 issue 反馈。

Configuration

OpenHands is configured through environment variables and a config file. The LLM is selected via LLM_MODEL and authenticated with LLM_API_KEY (or OPENAI_API_KEY). Docker is required for the sandbox runtime—each agent runs in an isolated container. The docker-compose.yml mounts the Docker socket and a workspace directory.

bash

# Environment variables (.env)
OPENAI_API_KEY=your-key
LLM_MODEL=gpt-4
LLM_API_KEY=your-key
WORKSPACE_BASE=/path/to/workspace

# docker-compose.yml
services:
  openhands:
    image: openhands/openhands:latest
    ports: ["3000:3000"]
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - LLM_MODEL=gpt-4
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./workspace:/workspace

# Start
docker compose up -d
# Access http://localhost:3000

Docker is mandatory—agents run in sandboxed containers so the host system stays safe.

FAQ

Common questions cover Docker setup, model support, security, cost, and custom agents. OpenHands supports any OpenAI-compatible LLM and runs each agent in an isolated Docker container. Custom agents are built by subclassing the Agent class.

bash

Q: Why is Docker required?
A: Agents run in isolated Docker containers so file and command operations
   cannot harm the host system.

Q: Which models are supported?
A: Any OpenAI-compatible LLM (OpenAI, Anthropic via proxy, local vLLM/Ollama);
   set LLM_MODEL and LLM_API_KEY.

Q: Is it safe to run?
A: Yes—Docker sandboxing isolates agent operations; use resource limits and
   network isolation in production.

Q: Can I write a custom agent?
A: Yes—subclass the Agent class and implement the step() method.

Q: How do I cut costs?
A: Use a smaller model for routine steps, limit max-iterations, and run
   evaluation jobs on cheaper models.

For production, add API key management, access control, and resource limits on top of the default sandbox.

Ready to try OpenHands?

Visit the official site for the latest version and full documentation.

Visit OpenHands

All AI guides