john
9b4a25799f
Replace fixed ackText with a rule-based AckProvider that picks response templates by message type and intent (translate, summary, rewrite, poster, ppt, mindmap, code, search, schedule). Pure sync, zero I/O, auto-falls back to config.ackText on any error. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
# 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
|