# OpenHands 安装说明

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

## 1. 推荐方案

如果你的目标是后续和 Goose 做集成，要先分清两条链：

- `OpenHands Web / GUI`：浏览器访问的服务，适合人工打开页面验证
- `Goose -> OpenHands`：Goose 直接拉起 `OpenHands CLI` 进程做委托执行，不走 `127.0.0.1:3000` 这个网页入口

本仓库当前建议：

- 页面服务用 `Colima + docker compose`
- Goose 委托执行继续用本机 `OpenHands CLI`

这样边界最清楚，也不会把 Goose 和 OpenHands 强耦合到一个镜像里。

## 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 作为更独立的执行环境来跑。

### 方式 D：本仓库 Colima compose

如果本机 Docker 实际跑在 Colima，而不是 Docker Desktop 默认 socket，可以直接使用仓库内置的 compose 文件：

```bash
cd /Users/john/Project/Memind
bash scripts/openhands-colima.sh pull
bash scripts/openhands-colima.sh build
bash scripts/openhands-colima.sh up
```

默认行为：

- 启动 `postgres:16-alpine`
- 启动本地 overlay 镜像 `memind/openhands-colima:local`
- 挂载 Colima socket：`/Users/john/.colima/default/docker.sock`
- 挂载当前仓库到容器内：`/workspace`
- 对外暴露 GUI 端口：`3000`
- OpenHands 持久化走本地 Postgres，而不是 SQLite

常用命令：

```bash
bash scripts/openhands-colima.sh build
bash scripts/openhands-colima.sh status
bash scripts/openhands-colima.sh logs
bash scripts/openhands-colima.sh restart
bash scripts/openhands-colima.sh down
```

当前 PG 默认值：

- `OPENHANDS_DB_NAME=openhands`
- `OPENHANDS_DB_USER=openhands`
- `OPENHANDS_DB_PASS=openhands_dev_password`

如果需要自定义，可在执行脚本前导出环境变量。

### 端口与资源

- 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. `curl http://127.0.0.1:3000` 返回 `200 OK`。
3. Postgres 中可以看到 OpenHands 表，例如 `event_callback`、`conversation_metadata`。
4. Docker 不报权限或 socket 错误。

## 7. Goose 集成边界

当前 Goose 不是调用 `http://127.0.0.1:3000` 这个 GUI 服务，而是直接执行本机 `OpenHands CLI`：

- `GOOSE_OPENHANDS_BIN=/Users/john/.openhands/bin/studio-openhands`
- `GOOSE_OPENHANDS_RUNNER=host`

其中：

- `/Users/john/.openhands/bin/studio-openhands` 目前只是一个 wrapper
- 实际执行的是 `/Users/john/.local/bin/openhands`

这意味着：

- `Colima` 里的 OpenHands Web 服务，主要用于人手打开页面和验证 PG 持久化
- Goose 的 OpenHands 委托执行，主要取决于本机 CLI 是否可用、模型环境变量是否齐全

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

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

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

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

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

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

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

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

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

## 10. 本地验证结论

本仓库本机 `Colima` 已验证通过：

- OpenHands Web 服务可访问
- OpenHands 数据落本地 Postgres
- 官方镜像直接切 PG 有迁移坑，因此当前 compose 使用的是仓库内的薄 overlay 镜像修复

相关文件：

- `/Users/john/Project/Memind/docker-compose.openhands-colima.yml`
- `/Users/john/Project/Memind/docker/openhands-colima/Dockerfile`
- `/Users/john/Project/Memind/docker/openhands-colima/002.py`
- `/Users/john/Project/Memind/docker/openhands-colima/010.py`

## 11. 官方参考

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