# OpenHands 安装说明

> 目标：先把 OpenHands 独立安装并跑起来，确认可用后，再接入 `memindadm` 的 Goose 网关策略中心。
>
> 原则：安装阶段不改动现有 Goose 服务，不影响当前生产/测试链路。

## 1. 推荐方案

如果你的目标是后续和 Goose 做集成，建议先用 **OpenHands CLI + GUI Server** 方式启动：

- 本地直接运行
- 可挂载当前仓库目录
- 便于后续做执行器接入验证

官方文档对 `openhands serve` 的说明是：它会通过 Docker 启动本地 GUI Server，支持挂载当前目录，适合直接对仓库做任务。

## 2. 前置条件

### 必需

- `uv`
- Python 3.12+
- Docker Desktop 已安装并运行
- 可用的 LLM Provider / Model / API Key

### Mac 上建议额外确认

- Docker Desktop 的默认 socket 访问已开启
- `docker ps` 可以正常执行

如果后面 `serve` 起不来，优先检查 Docker 是否在运行，以及 Docker Desktop 的相关网络设置。

## 3. 安装方式

### 方式 A：推荐，使用 `uv`

```bash
uv tool install openhands --python 3.12
```

安装完成后启动：

```bash
openhands serve --mount-cwd
```

说明：

- `serve` 会启动 GUI Server
- `--mount-cwd` 会把当前目录挂进 OpenHands 的工作区
- 这样它可以直接面对你的仓库做任务
- 首次启动后需要在界面里选择 LLM Provider、Model，并填入对应 API Key

如果你只想先验证能跑起来，也可以先不加 `--mount-cwd`：

```bash
openhands serve
```

### 方式 B：使用官方安装脚本

```bash
curl -fsSL https://install.openhands.dev/install.sh | sh
```

安装后同样可以启动：

```bash
openhands serve --mount-cwd
```

### 方式 C：Docker / Agent Canvas

如果你更偏向容器化，可按 OpenHands 的 Agent Canvas / Docker 文档走容器启动方式。这个方式适合未来把 OpenHands 作为更独立的执行环境来跑。

### 端口与资源

- GUI Server 默认会占用 `3000` 端口
- Docker 镜像和运行时需要一定磁盘空间
- 如果要跑 GPU，可以在 `serve` 时加 `--gpu`

## 4. Mac 最短安装路径

如果你现在是在 Mac 上直接装，我建议按这个顺序走：

### 4.1 安装 Docker Desktop

去 Docker 官方页面下载安装包，按芯片类型选择 Apple Silicon 或 Intel 版本。

- 安装页：`Docker Desktop for Mac`

安装完成后，先启动 Docker Desktop，等左上角状态变成运行中。

### 4.2 打开 Docker Socket 选项

按 OpenHands 官方本地安装说明，进入：

- `Docker Desktop`
- `Settings`
- `Advanced`
- 勾选 `Allow the default Docker socket to be used`

这个开关是 OpenHands 本地运行最关键的前置条件之一。

### 4.3 验证 Docker 是否可用

在终端执行：

```bash
docker ps
```

如果能正常返回容器列表或空列表，说明 Docker daemon 已经起来了。

### 4.4 启动 OpenHands

回到你的仓库目录后执行：

```bash
openhands serve --mount-cwd
```

如果一切正常，你会看到 OpenHands GUI Server 在本机启动。

## 5. 如果你暂时不想装 Docker

如果你只是想先体验界面，不急着本地执行仓库任务，可以先考虑 OpenHands 的 `web` 模式。这个模式是终端界面的浏览器版，不是完整 GUI Server，和 `serve` 不是一回事。

但如果你的目标是后面和 `memindadm` 做执行器集成，我还是建议装 Docker，后续链路会更稳。

## 6. 启动后如何确认正常

启动成功后，确认以下几点：

1. 浏览器能打开 OpenHands 的界面。
2. 可以创建一次简单任务。
3. 如果用了 `--mount-cwd`，任务可以看到当前仓库。
4. Docker 不报权限或 socket 错误。

## 7. 用于后续 Goose 集成时的建议

为了后面接入 `memindadm`，建议你先准备好这些信息：

- OpenHands 的启动方式
- 本地可访问地址
- 是否需要挂载仓库目录
- 是否允许命令执行
- 是否要使用 GPU
- 计划给 Goose 侧调用的入口方式

建议后续接入时优先走“策略中心路由到 OpenHands”，而不是让 Goose 直接接管 OpenHands 的所有行为。这样 `memindadm` 的审计和拦截链路会更清晰。

如果你后面已经决定把 `Goose / Aider / OpenHands` 的模型统一收口到 `memindadm`，那么 OpenHands 这边也不要再单独维护自己的模型配置，统一从后台读取即可。

## 8. 和现有 Goose 服务的关系

这一步是旁路安装，不会改动现有 Goose 服务。

后续集成时，建议保持下面的边界：

- 现有 Goose 服务继续照常运行
- `memindadm` 只在旁路做策略判断、审计记录、路由建议
- OpenHands 先作为独立执行器接入
- 真正切流之前，先做只读审计和联调验证

## 9. 官方参考

- OpenHands 安装文档
- OpenHands GUI Server
- OpenHands Local Setup
- OpenHands Docker Sandbox