上周（2026-08-19）OpenAI 官宣 "Codex as a platform"，Codex Harness 正式成为可嵌入第三方产品的 Agent 底座（背景见本站 OpenAI 交出 Agent 的发动机）。官方给了三个入口：codex exec、Codex SDK、codex app-server。
这篇 SOP 回答一个具体问题：一个普通团队，怎么按「三级火箭」的节奏把这套底座用起来--从一条命令跑通，到代码里调用，到产品级 Runtime。每级都给到最小可运行的示例与升级判据，全部基于 openai/codex 仓库官方文档（GitHub API 实测 2026-08-22）整理。
先说两条边界：第一，Harness 开源（Apache-2.0）不等于模型免费，token 照常计费；第二，本文是接入路径梳理，非法律与安全合规意见，上生产前请过自家的安全评审。
第零步：认证与环境
三級火箭共用同一个认证层。Python SDK 的官方推荐路径：
from openai_codex import Codex
with Codex() as codex:
login = codex.login_chatgpt() # ChatGPT 浏览器登录
print(login.auth_url, login.wait().success)
# 或 API key：codex.login_api_key("sk-...")要点：已有 Codex 登录态会被自动复用；Python SDK（pip install openai-codex，需 Python 3.10+）会自动捆绑安装匹配版本的 CLI；TS SDK（npm install @openai/codex-sdk，需 Node 18+）则是 spawn CLI 并通过 stdin/stdout 交换 JSONL 事件。key 走环境变量或登录态，绝不写进 prompt。
第一级：codex exec--一条命令的集成
适用：CI 流水线、定时任务、一次性后台作业。零代码改造。
codex exec --json "分析当前仓库并输出风险清单"升级判据：当你需要在任务之间传递状态（上一个任务的结论喂给下一个任务）、或需要结构化输出喂给下游程序时，升级到第二级。
第二级：Codex SDK--把 Agent 当函数调
适用：在自家 TS / Python 服务里编排 Agent。两级核心能力：
多轮线程 + 断点恢复（线程持久化在 ~/.codex/sessions，进程重启可续）：
import { Codex } from "@openai/codex-sdk";
const codex = new Codex();
const thread = codex.startThread({ workingDirectory: "/path/to/project" });
const turn = await thread.run("诊断测试失败并给出修复方案");
console.log(turn.finalResponse);
// 进程重启后：codex.resumeThread(savedThreadId) 接着跑JSON Schema 结构化输出（Agent 的回答强制符合你的 schema，喂下游系统不用再解析自然语言）：
const schema = {
type: "object",
properties: {
summary: { type: "string" },
status: { type: "string", enum: ["ok", "action_required"] },
},
required: ["summary", "status"],
} as const;
const turn = await thread.run("总结仓库当前状态", { outputSchema: schema });需要实时感知进度（工具调用、文件变更）时用 runStreamed() 拿事件流，替代缓冲到结束的 run()。
安全与沙盒的官方开关（这些参数就是你的第一道缰绳）：
const codex = new Codex({
config: {
sandbox_workspace_write: { network_access: false }, // 关沙盒内网络出口
default_permissions: "audit",
},
configOverrides: [
// 文件系统粒度：根目录只读，.env 明确拒绝
'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
],
});升级判据：当你要自定义 UI、自建审批流、把事件流原样转发给前端时，升级到第三级。
第三级：codex app-server--产品级 Agent Runtime
适用：Agent 本身是你产品的一部分。codex app-server 是 Codex VS Code 扩展背后的同一套接口：JSON-RPC 2.0 协议服务，传输层支持 stdio（默认，JSONL）、WebSocket（实验性）、Unix socket。
接之前先拿 schema（每个版本生成对应的 schema，保证接口对齐）：
codex app-server generate-ts # TypeScript 类型
codex app-server generate-json-schema # JSON Schema bundle三个工程要点（均出自官方 README）：
- 审批是协议内一等公民。App Server 的 API 包含 Approvals 语义--高危动作挂起等你确认，这层要在你的产品里做成人机交互界面，而不是图省事全放行。
- 过载要按重试处理。请求饱和时服务端返回 JSON-RPC 错误码
-32001（Server overloaded），官方要求客户端做指数退避+抖动重试。 - 健康探测有现成端点。
--listen ws://模式下GET /readyz（监听就绪）与GET /healthz（无 Origin 头时 200）可直接接你的探活系统。
上线前 10 项 checklist
- 认证凭据走环境变量 / KMS，不进代码不进 prompt
- 沙盒模式明确声明（workspace-write + 关网络出口，除非必需）
- 文件系统粒度权限：
.env、密钥目录显式 deny - 高危动作（删库、外发、支付）挂审批门，禁止默认放行
- 全量行为日志：thread id、turn 用量、工具调用序列
- token 与操作次数双限额 + 异常自动熔断
- 长任务用
resumeThread()恢复，别无脑重跑（重复计费） - 结构化输出用
outputSchema，别用正则解析自然语言 - app-server 过载错误
-32001接了重试逻辑 - 灰度：先只读任务跑两周，再放开写操作
五个典型踩坑
- 把 key 粘进 prompt「省事」--日志系统会把 prompt 全量存下来，等于密钥入库。
- 默认信任沙盒默认值--各家默认配置偏宽松，网络出口、文件读写范围要自己收紧（背景案例见 OpenAI 踩下刹车：官方评测沙盒被自家 agent 从内部凿穿）。
- 在非 Git 目录直接启动--Codex 默认要求工作目录是 Git 仓库（防误操作不可回滚）；确需跳过用
skipGitRepoCheck: true，但要清楚你在放弃哪层保险。 - 长任务失败就整体重跑--线程持久化的意义就是断点续跑，重跑烧的是双倍 token。
- 第一天就上 app-server--协议层耦合深、迁移成本高；两级 SDK 能解决的，别上第三级。五家官方 Runtime 的横向对比见 Agent Runtime 五强横评。
一句话收尾：白嫖底座省下的两三个月，刚好够把审批、审计、熔断这三件缰绳做扎实--省下的时间花在哪，决定这套底座在你手里是生产力还是事故源。
常见问题
Q1：exec / SDK / app-server 三个都要装吗？
A1：不用，按集成深度递进选一即可：脚本与 CI 用 codex exec；代码内编排用 SDK；自定义 UI 与审批流才上 app-server。每升一级耦合深度翻倍，永远从够用的最低级开始。
Q2：SDK 和 CLI 是什么关系，会版本冲突吗？
A1：SDK 不是重写，是 CLI 的封装--TS SDK spawn @openai/codex CLI 并交换 JSONL 事件；Python SDK（openai-codex）自动捆绑安装匹配版本的 CLI（openai-codex-cli-bin），SDK 版本与 CLI release 对齐，避免了你手动管版本匹配。
Q3：任务跑到一半进程挂了，之前的进度还有吗？
A3：有。线程持久化在 ~/.codex/sessions，用 resumeThread(threadId) 可以恢复继续跑，不需要从头重跑（也就不会重复烧 token）。TS 里通过 process.env.CODEX_THREAD_ID 之类的变量跨进程传递 thread id 是常见做法。
Q4：开源 Apache-2.0 之后，商用还要付什么钱？ A4：框架层免费可改可商用；模型推理按 OpenAI 计费走（API key 或 ChatGPT 账号额度）。另外 IDE Extension 与 Codex Cloud 不在开源范围内。
Q5：我的产品已经有自研 Agent 循环，值得迁过来吗？ A5：判据是「你的差异化在哪」。如果团队精力都耗在维护循环、上下文管理、工具调度这些官方 Runtime 免费送的东西上，迁移是净收益；如果你的差异化恰在执行层本身（或需要深度定制），保留自研但可以对照 Codex 的设计（线程恢复、审批语义、结构化输出）补短板。缰绳层（审批/审计/熔断）无论迁不迁都要自建，见 给 Agent 上缰绳部署 SOP。
参考来源
- openai/codex 仓库（GitHub API 实测 2026-08-22，Apache-2.0，111,646 星）
sdk/typescript/README.md：startThread / run / runStreamed / outputSchema / resumeThread / workingDirectory / env / config overridessdk/python/docs/getting-started.md：安装、三种登录方式、thread_start(sandbox=...) 示例codex-rs/app-server/README.md：JSON-RPC 2.0 协议、stdio/ws/unix 传输、Approvals、-32001过载重试、/readyz /healthz、generate-ts / generate-json-schema- OpenAI 官方博文（2026-08-19）：Codex as a platform
本文基于官方文档整理（截至 2026-08-22），非法律与安全合规意见；上生产前请过自家安全评审。