本页是安装程序参数的参考,并说明如何用默认方式以外的方式安装:在已有反向代理之后、在托管平台上使用 Docker Compose,或在无法访问互联网的主机上。默认安装无需任何选项。
传入参数
curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --public-url https://core.example& ([scriptblock]::Create((irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1))) --public-url https://core.exampleWindows 上 irm … | iex 无法传参,默认执行策略也会拦截下载的 .ps1 文件,因此以脚本块运行脚本。除非传入 --version,脚本会选择最新稳定版,并校验原生命令和 Compose 文件的 SHA-256。
参数
| 参数 | 默认值 | 写入 .env 的变量 | 作用 |
|---|---|---|---|
--public-url | 由主机的私网地址推导,或 http://localhost:<web port>;参阅选择公开 URL | OAC_PUBLIC_URL | 应用、节点和执行器使用的源地址 |
--host | 0.0.0.0 | OAC_HOST | Web 绑定的地址;参阅监听器与访问 |
--web-port | 8080 | OAC_WEB_PORT | Web 的主机端口;参阅端口 |
--install-dir | ~/.oac/core | 绝对安装目录。新安装使用空目录或不存在的目录;重试时使用已有安装目录 | |
--version | latest | 已发布的版本标签 |
映射到 .env 的参数只会写入一次。安装完成后,编辑该文件并运行 oac apply。对已有安装重新运行安装程序时,这些参数会被忽略,安装程序会指出与已保存设置不同的参数,并以已保存的设置启动。
只要使用不同的安装目录和端口,多个安装就可以共用一台机器。需要更多安装时,请使用不同的 IP 地址或共享反向代理。每个安装都有自己的数据库、Core 密钥和节点。
反向代理与 HTTPS
请用 --host 127.0.0.1 安装,把反向代理指向 Web,并把 --public-url 设为它的 HTTPS 源地址。代理要求、Caddy 和 nginx 示例、路由检查,以及 --host、--web-port 和端口检查,见配置公开地址。
Docker Compose 与托管平台
在任一支持的 Core 主机上使用发行版中的 compose.yaml。发行流程会固定初始化、Core、Web 和 PostgreSQL 镜像及源码版本。Compose 配置负责管理各项设置和数据目录。
进行本地试用时,请将发行版的 compose.yaml 下载到一个空目录,然后运行:
docker compose up -d --wait --wait-timeout 900
docker compose exec web oac-web core-key打开 http://localhost:8080,使用输出的 Core 密钥登录。
你可以在选择域名前进行部署:将 OAC_PUBLIC_URL 保持未设置或留空,然后在平台的域名准备好后,按照 Compose 配置进行设置并重新部署。初始的 localhost 源地址允许服务启动;Web 仅接受已配置的主机,因此重新部署后即可通过平台域名访问。
Dokploy
- 创建一个 Docker Compose 应用并粘贴
compose.yaml。 - 将
OAC_PUBLIC_URL设置为公共 HTTPS 源地址,并启用隔离部署。 - 为
web服务添加域名,端口8080。为该域名启用 HTTPS,并选择 Let's Encrypt 等证书提供程序。 - 移除
web服务的ports块,让 Dokploy 路由到容器端口,而不发布主机端口。 - 部署。
将此 Compose 文件打包到 Dokploy 模板目录时,模板元数据会提供生成的域名和环境;导入后仍需启用 HTTPS 及其证书提供程序。
Coolify
- 创建一个 Docker Compose Empty 服务并粘贴
compose.yaml。 - 将
OAC_PUBLIC_URL设置为公共 HTTPS 源地址,并将该域名分配给web服务的端口8080。 - 将 Coolify 的
exclude_from_hc: true添加到init的服务定义中,使已完成的初始化不会影响其总体健康状态。 - 移除
web服务的ports块,再保存并部署。Coolify 路由到容器端口并提供 HTTPS。
在这两个平台上,打开服务器终端并运行 docker compose ls,查找已部署的项目名称和 Compose 文件。使用这些完全一致的值以及该部署的 OAC_PUBLIC_URL,运行 docker compose -p <project-name> -f <compose-file> exec web oac-web core-key,然后在已配置的源地址登录。Dokploy 域名指南和 Coolify Compose 指南介绍了各自的域名和服务控制项。
登录后,选择沙箱提供商,并按添加和管理节点添加节点。Compose 堆栈部署控制平面;执行机器仍需单独部署。
使用相同的文件和环境运行 docker compose stop 以停止服务。停止服务后,一并备份数据卷和配置。要换到另一个版本,请连同数据卷一起移除该栈(docker compose down --volumes),然后部署新版本。
离线主机
安装程序使用当前 shell 的网络设置(包括 HTTPS_PROXY)从 GitHub Releases 下载发行文件。Docker 通过其守护进程拉取镜像,守护进程不读取 shell 的代理变量。所有镜像(包括 PostgreSQL)都来自 GHCR(ghcr.io),不需要 Docker Hub。如果只能经代理或镜像加速器访问 GHCR,请配置守护进程代理或镜像加速器,然后重新运行安装程序。
无法访问这些地址的 Linux amd64 主机可使用发行资产 oac-<commit>-linux-amd64-offline.tar.gz 安装,其中包含所有镜像、节点制品和包含全部 Harness 的 Linux amd64 自托管安装程序。macOS 和 Windows 上的自托管机器从 GitHub Releases 下载各自的安装程序。将其复制到该主机并解压,然后用 Python 3.9 或更高版本和 Docker 运行其中的 install.py。该主机上不需要检出代码、Go、Node 或 pnpm。安装完成前请保留解压后的安装包;之后已安装的服务和节点下载不再依赖它原来的位置。开发 OpenAgentCore从检出代码构建的就是同一个归档。
install.py 选项
python3 oac-<commit>-linux-amd64/install.py --install-dir "$HOME/.oac/local" --host 0.0.0.0 --public-url http://YOUR_CORE_HOST:8080| 选项 | 默认值 | 作用 |
|---|---|---|
--install-dir | ~/.oac/local | 绝对安装目录 |
--host | 127.0.0.1 | Web 绑定的地址。与 oac install 不同,install.py 默认使用回环地址:需要从其他机器访问时传入 0.0.0.0 |
--web-port | 8080 | Web 的主机端口 |
--public-url | 浏览器和节点使用的源地址。新安装必须提供 |
将 YOUR_CORE_HOST 替换为浏览器和沙箱节点都能访问的地址,或在反向代理之后使用你的 HTTPS 源地址。新安装会打印 Core 密钥;重新运行则打印显示它的命令。该安装是标准的 Compose 安装,外加一个只读的 node-payload 目录,其中保存安装包的公开节点制品。请为解压后的安装包和已安装的副本都预留磁盘空间。
在其安装目录上重新运行同一安装包的 install.py,会以已保存的设置继续安装。来自其他提交的安装包会拒绝已有安装。如果新安装在启动服务之前失败,它会保持安装目录原样;修复原因后重新运行同一命令。
启动失败或安装中断时,使用已保存的配置,而不是重新安装:
cd "$HOME/.oac/local"
docker compose logs --tail 100
# Retry without downloading release images or replacing saved configuration.
docker compose up -d --wait --pull never
./oac core-key --show