OpenAgentCore 是什么：自托管 Agents API 跑 Codex/Claude

OpenAgentCore 是 MiniMax 开源、MIT 许可的自托管 OpenAI Agents API：把官方 OpenAI SDK（或裸 HTTP）指到你自己的安装，每个 Session 可原生跑 Codex、Claude Code 或 MiniMax Code，模型提供商由你配置。截至 2026-10-30（北京时间），GitHub 约 306 星，最新正式版标签 v0.0.13（2026-10-25 发布）。下面按官方 README 与安装文档整理它是什么、怎么装、怎么调。

它是什么

OpenAgentCore 把「Agents API 兼容面」和「本机/沙箱里的 coding harness」拆开：Core 持久化执行状态；Runtime 在 Environment 里跑你选的 Harness。边界都是可替换协议：Sandbox Provider、工作区文件系统、Harness、模型提供商可各自换掉。官网横幅写的是 One core. Many agents：同一套 Core，多种 Agent。

解决什么问题

很多团队想在自己机器 / 自己模型上跑 Codex 或 Claude Code 一类 Agent，又希望应用侧仍用 OpenAI 官方 SDK，不想另学一套客户端。OpenAgentCore 给这条路：API 面兼容 Agents API；Session 里跑原生 harness；沙箱可选 Docker、microsandbox（闲置可释放算力、工作区独立存储可恢复）、E2B，或直接在你自己的 Linux / macOS / Windows 上跑 self-hosted Session。

官方强调：沙箱、Harness、模型提供商都通过协议接入，部件可单独替换。

怎么装（文档步骤）

安装文档要求：用普通用户跑安装器与 oac，不要 sudo（否则 ~/.oac 属主变成 root，后续会失败）。Docker 守护进程要能拉镜像；发布包下载需要能访问 GitHub。

# Linux / macOS
curl -fsSL https://openagentcore.dev/install.sh | bash

# 指定公网地址示例
curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --public-url https://core.example

# Windows PowerShell
irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex

安装器检查 Docker 与端口，写出目录 ~/.oac/core（含 .env 与 oac 命令），启动 Core、Web、PostgreSQL。Web 在 8080 提供控制台并转发 API。新装会打印 Core key；重跑可用 oac core-key --show。

文档里的后续清单：

1. 浏览器打开安装器打印的同一公网地址，用 Core key 登录（Web 没有普通用户账号）。
2. Settings → Models：给默认 Harness（默认多为 Codex，可用 OAC_DEFAULT_HARNESS 改）配模型 ID、协议、base URL 与 API key。
3. Projects and keys：建项目、发 Project API key（只显示一次）。
4. 加沙箱容量：自管 Linux 节点 + 工作区存储，或 E2B；也可只跑本机 self-hosted Session。

装完先核对这几项

• 控制台地址必须与安装器打印（或 --public-url）一致，浏览器开错 host 会登不进。
• 默认模型未 Ready 前，Core 托管 Session 若未自带 provider，会踩空；到 Settings → Models 把协议、base URL、密钥填齐。
• Project API key 只显示一次；泄漏等于别人能以你的项目建 Session。
• 重跑安装脚本是安全的：失败检查、三分钟内不健康或 Ctrl-C 后，修好再跑同一命令；配置与数据保留。升级版本文档写的是先卸载再装。

怎么调（官方 SDK 示例）

把 OPENAI_BASE_URL 设成你的 API 根（例如 https://core.example/v1），OPENAI_API_KEY 用 Project key：

from openai import OpenAI

client = OpenAI()  # 读 OPENAI_BASE_URL 与 OPENAI_API_KEY
session = client.beta.agents.sessions.create(
    environment={"type": "openai_hosted"},
    input="Create /workspace/hello.txt with a short greeting, then describe it.",
    extra_body={"agent": {"x_agents_core": {"harness": "codex"}}},
)
print(session.id)

等待结果与回读见文档「Run your first Session」。Harness 能力与限制对照表在 Harness capabilities 合约页。本站已有的 MiniMax 工作流 Skill 另见 MCode Stack；通用 MCP 接入见 MCP 是什么怎么配。

两套 API、三种运行面

应用与运维拆开：

README 还写了 microsandbox 的闲置策略：工作区在独立存储上，空闲沙箱可释放算力，之后在兼容节点上带着文件恢复；E2B 则在原地暂停。开发扩展时从「Develop OpenAgentCore」与仓库 AGENTS.md 的协议边界入手。

和微软 Foundry 上的 Copilot harness 对比：那边是云托管 harness、你声明 Skills；这边是自托管 Agents API 面、Session 里跑原生 Codex/Claude/MiniMax Code。选型看你要不要自己运 Docker 与沙箱节点。

适合谁，不适合谁

适合：要在自有基建上对外暴露与 OpenAI Agents API 兼容的入口、并在 Session 里跑 Codex / Claude Code / MiniMax Code 的团队；愿意用 Docker 装 Core+Web+Postgres、自己管模型密钥与沙箱容量的人。

不适合：只想用云端托管、零运维的人——安装文档明确要运维侧配模型、密钥与沙箱；也不要把早期 v0.0.x 当成生产 SLA 承诺，版本与接口以仓库 Release / 文档为准。

最后：先在一台空闲 Docker 主机跑安装脚本，用 Core key 登录 Web，配好默认模型并发一把 Project key，再按官方 quickstart 用 SDK 建一个写 /workspace/hello.txt 的 Session，确认 harness 与沙箱路径通了再接到业务仓库。