安装#

模型概念 —— 请先阅读#

OpenProgram 是宿主。你只需安装它一次，然后把 agent 程序（programs）加进去。

OpenProgram  (the host runtime — install this first, anywhere you like)
└── openprogram/functions/agentics/      ← owner安装的program位于此处
    ├── GUI-Agent-Harness/               ← `gui_agent`      (clone in + run its installer)
    ├── Research-Agent-Harness/          ← `research_agent` (openprogram programs install research)
    └── Wiki-Agent-Harness/              ← `wiki_agent`     (openprogram programs install wiki)

通过 openprogram programs install 安装的程序会登记来源，并在启动时注册 （import_installed_programs() 导入它的 agentics 子包，触发 @agentic_function 装饰器），因此它会出现在 web UI 和函数列表中。 未登记的目录不会被导入。所以安装顺序始终是：先装 OpenProgram，再装程序。

⚠️ 只安装 Python 包并不是全部工作 —— 它不会 构建 web UI（需要 npm）、不会拉取 GUI agent 的模型权重，也不会预热 OCR 模型。下面的安装脚本才是权威来源 —— 它会 把这些都做好。

一条命令（推荐）#

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.sh | bash
# from a checkout: ./scripts/install.sh   # everything · bare host: --minimal

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.ps1 | iex
# from a checkout: .\scripts\install.ps1   # everything · bare host: -Minimal

不在 checkout 里运行时，脚本会先把仓库 clone 到 ~/OpenProgram（--target DIR 可改），再接力安装。默认安装装好 host 的全部轻量内容：web UI（已构建）、终端 UI、浏览器工具 + channels。agent 程序（GUI / Research / Wiki）不随默认安装 —— 有终端时脚本会弹菜单让你挑，或之后用 openprogram programs install <research|wiki|gui> 单独装（GUI 会下载 PyTorch），也可 openprogram setup → programs。--minimal 则改为安装一个裸宿主。

然后直接启动它 —— 首次运行会引导你完成 provider 配置，随后 打开聊天界面：

openprogram                                   # first run = guided provider setup, then chat
openprogram web                               # or the browser UI -> http://localhost:18100

安装脚本是幂等的 —— 任何时候都可以重新运行以修复或更新。

安装脚本做了什么#

命令行参数#

完整参数矩阵（install.sh --help 会打印；PowerShell 的参数写在 install.ps1 文件头部注释里）：

为 GUI harness 显式指定 CUDA/CPU 版 PyTorch：在宿主安装完成后运行它 自己的安装脚本 —— openprogram/functions/agentics/GUI-Agent-Harness/scripts/install.sh --cuda cu124。

非交互 / AI agent 安装#

给 agent 驱动安装用 —— 不必特意加参数：那条 curl … | bash 一行命令本身就能无人值守跑。没有终端（管道、CI）时它自动取默认值；即便有终端，每个 /dev/tty 读取也有 60 秒超时，到点自动回落到默认值（并打印一行 (no input in 60s — using default)）—— 所以任何提示都不会永久卡住。用 OPENPROGRAM_PROMPT_TIMEOUT=<秒> 可改超时时长。

想立即取默认值、不等超时，就加 --yes / -y；想顺带非交互地装上 agent 程序，再加 --programs all（或 gui / research / wiki）。以下环境变量与 --yes 等价 —— 命中任意一个就全部取默认值、不弹任何提示：

一条命令即可完全非交互、并顺带装上 agent 程序：

curl -fsSL https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.sh | bash -s -- -y --programs all

Windows 的 Read-Host 没有超时机制，所以 install.ps1 的提示不会自动 取默认值 —— agent 在 Windows 上必须传 -Yes 或设上表任一环境变量。

添加 agent 程序#

通过CLI安装的程序位于 functions/agentics/<Repo>/，并在下次启动时注册。 同一条命令适用于已编目的Harness和第三方仓库；如果Harness还有额外资产，随后运行 它自己的安装脚本：

openprogram programs install <harness-repo>
cd openprogram/functions/agentics/<Harness>
./scripts/install.sh          # if it ships one (Windows: .\scripts\install.ps1)

GUI agent 有原生依赖（PyTorch、检测器权重、OCR），因此它附带了 自己的分平台安装脚本 —— 按上面的步骤使用它；完整指南见它的 安装章节。 （选装了 GUI 时 —— 菜单里勾选或 --programs gui/all —— 安装脚本会把它克隆进来并拉 PyTorch；之后运行该 harness 自己的安装脚本来配资产或指定 CUDA/CPU torch。）

对于已编目的 harness，有一条单行快捷命令，会为你完成克隆、安装并注册：

openprogram programs install research     # or: wiki / gui / all
openprogram programs available            # see install status

programs install 会克隆仓库并 pip 安装它声明的依赖（非可编辑：依赖装到 site-packages，代码在源码树内运行）。对 gui 来说这包括 PyTorch，但不含 YOLO 权重、OCR 预热这类原生资产 —— 这些要运行 GUI harness 自己的安装脚本（见上文）。

执行上述任意操作后，重启 worker（或在 Functions 页面点击 Refresh）， 该程序就会出现在 web UI 中。第三方 harness 的安装方式相同 —— openprogram programs install <git-url | owner/repo>；详见 installing-harnesses.md。

Extras#

浏览器工具 + 聊天 channels 默认安装（即 [all] extra），且 安装脚本会为你拉取 Playwright Chromium 二进制 —— 无需任何主动开启。 传入 --minimal / -Minimal 以跳过它们（例如 CI / 隔离网络 / 带宽受限场景）。

更重、仍需主动开启（加上对应参数）：

Provider SDK（anthropic、openai、google-genai）已包含在基础安装中 —— 无需额外 extra。

Providers / 凭据#

进行任何聊天回合前，至少需要一个 provider：

openprogram providers login openai-codex      # ChatGPT subscription (recommended)
openprogram providers login anthropic          # Claude
export ANTHROPIC_API_KEY=sk-ant-...             # …or an API key (Windows: $env:ANTHROPIC_API_KEY="...")

会自动采用已安装的 Claude Code / Codex / Gemini CLI。用 openprogram doctor 检查。

端口#

一个端口承载全部——FastAPI worker 同时提供 API、WebSocket 和 web UI 静态导出：

使用 openprogram ports --port <p> 修改（单次运行可用 OPENPROGRAM_WEB_PORT）。

完整依赖矩阵#

pip 之外的全部内容。安装脚本会处理每一行标记为 “auto” 的项。

宿主（OpenProgram）#

GUI-Agent-Harness 程序（opt-in，选装后 —— 见 添加 agent 程序）#

* EasyOCR 作为跨平台回退方案被安装，所以 GUI agent 在 没有 Xcode CLT 的 macOS 上也能工作 —— Apple Vision 只是更快而已。完整的 GUI 细节： GUI-Agent-Harness/docs/install.md。

故障排查#

• openprogram web 显示了一个加载不出来的页面。 web UI 静态导出（web/out/）没构建——web/ 的 node_modules 没有安装。 重新运行安装脚本，然后打开 http://localhost:18100。
• pip 无法重装：WinError 32 … openprogram.exe is being used。 先停掉正在运行的 openprogram web / worker，然后重新运行。
• gui_agent 没有出现在 UI 中。 重启 worker（或在 Functions 页面点 Refresh）。用 openprogram programs available 确认它已注册。
• NVIDIA GPU 未被使用。 安装脚本会自动检测它；如果它选了 CPU（安装时没有驱动，或你传了 --cpu）：执行 pip uninstall -y torch torchvision，然后重新运行安装脚本。
• GPA 权重没有下载下来（离线）：hf download Salesforce/GPA-GUI-Detector model.pt --local-dir ~/GPA-GUI-Detector。

手动 / 进阶#

python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .                                  # host
( cd web && npm install )                         # web UI
( cd cli && npm install && npm run build )         # TUI (POSIX)
# GUI program (editable, in-tree → auto-registers):
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install -e "openprogram/functions/agentics/GUI-Agent-Harness[ocr]"
hf download Salesforce/GPA-GUI-Detector model.pt --local-dir ~/GPA-GUI-Detector
python -c "import easyocr; easyocr.Reader(['en','ch_sim'], gpu=False)"

多 repo 本地开发（并排编辑多个 harness）： troubleshooting.md → 本地开发安装（多仓库）。