三条路，选一条
OpenHands 提供三种使用方式，按你的需求选：
| 方式 | 适合谁 | 需要什么 |
|---|---|---|
| Docker（推荐） | 想要完整功能 + Web GUI | Docker Desktop + API Key |
| CLI（pip 安装） | 喜欢终端工作流的开发者 | Python 3.12+ + API Key |
| Cloud 版 | 不想折腾环境 | GitHub 账号 |
方式一：Docker 部署（5 分钟）
这是官方推荐的方式，带完整 Web GUI 和 Docker 沙箱隔离。
前置条件：
- Docker Desktop 已安装并启动
- 一个 LLM API Key（推荐 Anthropic Claude 或 OpenAI）
- 至少 4GB 可用内存
docker run -it --rm --pull=always \
-e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
-e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
-e LOG_ALL_EVENTS=true \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.openhands:/.openhands \
-p 3000:3000 \
--add-host host.docker.internal:host-gateway \
--name openhands-app \
docker.openhands.dev/openhands/openhands:1.7
启动后打开浏览器访问 http://localhost:3000，首次会弹出设置面板让你填：
- LLM Provider（选 Anthropic / OpenAI / Google 等）
- Model（推荐
claude-sonnet-4-20250514或gpt-4o） - API Key
填完就能开始用了。
方式二：CLI 安装（终端党最爱）
不想开浏览器？CLI 模式一样强大：
# 用 uv 安装（最快）
uv tool install openhands --python 3.12
# 或者用 pip
pip install openhands-ai
# 或者一行脚本
curl -fsSL https://install.openhands.dev/install.sh | sh
安装完直接跑：
# 交互模式——像跟同事对话一样
openhands
# 直接给任务
openhands -t "给 src/auth.py 写单元测试，覆盖所有边界情况"
# 从文件读任务描述
openhands -f task.md
# YOLO 模式——自动批准所有操作（⚠️ 谨慎使用）
openhands --always-approve -t "升级所有依赖到最新版"
首次运行会要求配置 LLM，设置保存在 ~/.openhands/agent_settings.json。
方式三：Cloud 版（零配置）
访问 app.openhands.dev，用 GitHub 登录，免费版每天 10 次对话。不用装 Docker，不用管环境，打开就用。
适合：快速试用、偶尔用一下、机器配置不够跑 Docker 的情况。
跑通第一个任务
假设你有一个 Node.js 项目需要加一个 API endpoint。在 OpenHands GUI 里输入：
在 src/routes/ 下创建一个 GET /api/health endpoint，
返回 { status: "ok", timestamp: Date.now() }。
加上对应的单元测试。
OpenHands 会自动：
- 读你的项目结构
- 找到路由文件的组织方式
- 创建新文件
- 写测试
- 跑
npm test确认通过
你在界面上能实时看到它的每一步操作——终端命令、文件编辑、测试输出全部可见。
挂载本地项目
Docker 模式下想让 OpenHands 操作你本地的代码？用 SANDBOX_VOLUMES 环境变量：
docker run -it --rm --pull=always \
-e SANDBOX_VOLUMES="/path/to/your/project:/workspace:rw" \
-e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
-e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.openhands:/.openhands \
-p 3000:3000 \
--add-host host.docker.internal:host-gateway \
--name openhands-app \
docker.openhands.dev/openhands/openhands:1.7
CLI 模式更简单：
cd /path/to/your/project
openhands serve --mount-cwd
验证安装成功
跑一个简单任务测试所有组件是否正常：
openhands -t "在当前目录创建一个 hello.py，打印 Hello from OpenHands，然后运行它"
如果你看到它成功创建文件并输出 Hello from OpenHands，恭喜——你的 AI Agent 就位了。
