Skip to content

安装选项

本页是安装程序参数的参考,并说明如何用默认方式以外的方式安装:在已有反向代理之后、在托管平台上使用 Docker Compose,或在无法访问互联网的主机上。默认安装无需任何选项。

传入参数 ​

sh
curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --public-url https://core.example
powershell
& ([scriptblock]::Create((irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1))) --public-url https://core.example

Windows 上 irm … | iex 无法传参,默认执行策略也会拦截下载的 .ps1 文件,因此以脚本块运行脚本。除非传入 --version,脚本会选择最新稳定版,并校验原生命令和 Compose 文件的 SHA-256。

参数 ​

参数默认值写入 .env 的变量作用
--public-url由主机的私网地址推导,或 http://localhost:<web port>;参阅选择公开 URLOAC_PUBLIC_URL应用、节点和执行器使用的源地址
--host0.0.0.0OAC_HOSTWeb 绑定的地址;参阅监听器与访问
--web-port8080OAC_WEB_PORTWeb 的主机端口;参阅端口
--install-dir~/.oac/core绝对安装目录。新安装使用空目录或不存在的目录;重试时使用已有安装目录
--versionlatest已发布的版本标签

映射到 .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 下载到一个空目录,然后运行:

sh
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 ​

  1. 创建一个 Docker Compose 应用并粘贴 compose.yaml。
  2. 将 OAC_PUBLIC_URL 设置为公共 HTTPS 源地址,并启用隔离部署。
  3. 为 web 服务添加域名,端口 8080。为该域名启用 HTTPS,并选择 Let's Encrypt 等证书提供程序。
  4. 移除 web 服务的 ports 块,让 Dokploy 路由到容器端口,而不发布主机端口。
  5. 部署。

将此 Compose 文件打包到 Dokploy 模板目录时,模板元数据会提供生成的域名和环境;导入后仍需启用 HTTPS 及其证书提供程序。

Coolify ​

  1. 创建一个 Docker Compose Empty 服务并粘贴 compose.yaml。
  2. 将 OAC_PUBLIC_URL 设置为公共 HTTPS 源地址,并将该域名分配给 web 服务的端口 8080。
  3. 将 Coolify 的 exclude_from_hc: true 添加到 init 的服务定义中,使已完成的初始化不会影响其总体健康状态。
  4. 移除 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 选项 ​

sh
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绝对安装目录
--host127.0.0.1Web 绑定的地址。与 oac install 不同,install.py 默认使用回环地址:需要从其他机器访问时传入 0.0.0.0
--web-port8080Web 的主机端口
--public-url浏览器和节点使用的源地址。新安装必须提供

将 YOUR_CORE_HOST 替换为浏览器和沙箱节点都能访问的地址,或在反向代理之后使用你的 HTTPS 源地址。新安装会打印 Core 密钥;重新运行则打印显示它的命令。该安装是标准的 Compose 安装,外加一个只读的 node-payload 目录,其中保存安装包的公开节点制品。请为解压后的安装包和已安装的副本都预留磁盘空间。

在其安装目录上重新运行同一安装包的 install.py,会以已保存的设置继续安装。来自其他提交的安装包会拒绝已有安装。如果新安装在启动服务之前失败,它会保持安装目录原样;修复原因后重新运行同一命令。

启动失败或安装中断时,使用已保存的配置,而不是重新安装:

sh
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

基于 MIT 许可证发布。© 2026 MiniMax-AI