tkmind/memind

Fork 0

Files

T

john d7cbf3cc96 chore: add 105 runtime and openhands ops tooling

2026-07-01 18:10:48 +08:00

7.1 KiB

Raw Blame History

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`

uv tool install openhands --python 3.12

安装完成后启动：

openhands serve --mount-cwd

说明：

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

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

openhands serve

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

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

安装后同样可以启动：

openhands serve --mount-cwd

方式 C：Docker / Agent Canvas

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

方式 D：本仓库 Colima compose

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

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 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 是否可用

在终端执行：

docker ps

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

4.4 启动 OpenHands

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

openhands serve --mount-cwd

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

5. 如果你暂时不想装 Docker

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

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

6. 启动后如何确认正常

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

浏览器能打开 OpenHands 的界面。
curl http://127.0.0.1:3000 返回 200 OK。
Postgres 中可以看到 OpenHands 表，例如 event_callback、conversation_metadata。
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 镜像修复

11. 官方参考

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

7.1 KiB Raw Blame History Unescape Escape