john
246 lines
7.1 KiB
Markdown
246 lines
7.1 KiB
Markdown
# 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
|