使用 OpenAI Codex SDK 集成 Open Interpreter：从一行改动到完整线程化应用

Open Interpreter 本身不维护独立的 SDK，而是一套面向 Codex 客户端表面的「即插即用」替代实现：既有 SDK 集成只需把启动的 agent 进程指向 interpreter 二进制即可接入，底层协议保持不变。本文将以 docs/sdk.md 为骨架，完整介绍 TypeScript 与 Python 两类 SDK 的接入方法、interpreter exec 与 SDK 的适用边界，并结合仓库源码说明 exec/app-server 协议的兼容机制、模型与 harness 的配置方式，以及仓库自带的兼容性冒烟测试，帮助你在一小时内把现有 Codex 自动化迁移到 Open Interpreter 之上。

设计前提：Open Interpreter 不提供独立 SDK

Open Interpreter 面向的是开放模型（如 Kimi K3、GLM 5.3 等）的编码 agent，但它刻意没有为 Python、TypeScript 或 Rust 各自打造一套专有 SDK。官方设计哲学是：既然它是对 Codex 客户端表面的 drop-in replacement（即插即用替换品），那么 SDK 集成就不该发明新协议，而应当直接使用 OpenAI 官方的 Codex SDK，并让 SDK 启动的 agent 进程指向 Open Interpreter。

现有集成代码（调用 Codex SDK）
          │
          │ 启动进程：codex / codex app-server（被替换）
          ▼
interpreter / interpreter app-server（Open Interpreter）
          │
          │ 仍讲 Codex exec / app-server 协议
          ▼
     Codex 客户端功能全部可用

这正是仓库内大量 Codex 兼容面存在的原因：Open Interpreter 继承并保持 Codex 的 exec 协议与 app-server 协议，客户端无需感知替换。仓库文档系统也以相同口径组织：当需要构建更丰富的客户端时用 app-server 协议，当需要让 ACP 兼容编辑器直接拉起 Open Interpreter 做编码 agent 时用 Agent Client Protocol。

TypeScript SDK：只需改动一行

对于已存在的 TypeScript 集成，迁移成本被压缩到一行：给 Codex 构造函数传入 codexPathOverride，把默认启动的 codex 二进制替换为 interpreter。

-const codex = new Codex();
+const codex = new Codex({ codexPathOverride: "interpreter" });

这个选项在仓库内的 SDK 类型定义中即可确认：sdk/typescript/src/codexOptions.ts 第 6 行声明了可选字段 codexPathOverride?: string，用于覆盖实际启动的 agent 可执行文件路径。

结合模型配置的完整示例（指定 Moonshot AI 平台上的 Kimi K3，并使用 kimi-code harness）：

import { Codex } from "@openai/codex-sdk";

const codex = new Codex({
  codexPathOverride: "interpreter",
  config: {
    model_provider: "moonshotai",
    harness: "kimi-code",
  },
});

const thread = codex.startThread({ model: "kimi-k3" });
const result = await thread.run(
  "Review this repo and list the first migration step.",
);

console.log(result);

关于配置的两点提示：

• OpenAI 模型场景：如果使用 OpenAI 官方模型，省略 harness 覆盖即可，模型名与你在命令行中使用的一致，不需要为 open 模型指定 harness。
• 进程路径也可以是绝对路径：codexPathOverride 接受可执行文件路径，若 interpreter 不在 PATH 中，可传 /path/to/interpreter 形式的绝对路径。

Python App-Server SDK：覆盖启动参数

对使用 codex_app_server 的 Python 集成，核心动作同样只有一个：把 AppServerConfig.launch_args_override 指向 interpreter app-server，而不是 codex app-server。

from codex_app_server import AppServerConfig, Codex

oi_server = AppServerConfig(
    launch_args_override=(
        "interpreter",
        "app-server",
        "--listen",
        "stdio://",
    ),
)

with Codex(config=oi_server) as codex:
    thread = codex.thread_start(
        model_provider="moonshotai",
        model="kimi-k3",
        config={"harness": "kimi-code"},
    )
    result = thread.run("Review this repo and list the first migration step.")
    print(result.final_response)

这里的核心语义是进程覆盖：SDK 依然讲 Codex app-server 协议（通过 stdio 与子进程通信），Open Interpreter 提供的是兼容的 app-server 实现。thread_start 中的 config={"harness": "kimi-code"} 会被传递给启动的 interpreter app-server 进程，作为其运行配置。

底层原理：协议不变，只有被启动的二进制变化

无论是 exec 还是 app-server 形态，迁移原理高度一致——Open Interpreter 扮演协议兼容的替代运行时：

• exec 形态：SDK 通过 codexPathOverride 启动 interpreter，之后二者以 Codex exec 协议在标准输入输出上通信，交互层（turn、消息流、tool call）完全沿用 Codex 语义。
• app-server 形态：SDK 通过 launch_args_override 启动 interpreter app-server --listen stdio://，服务端能力（线程、流式事件、审批、会话状态、模型选择、MCP 状态）由 Open Interpreter 的 app-server 运行时提供，客户端无需改协议。

这一设计还带来另一个好处：同一套 SDK 代码可以在本地 Codex 与 Open Interpreter 之间切换，只需要调整进程覆盖参数，业务代码不变。仓库内 docs/app-server.md 也印证了协议继承关系——Open Interpreter 继承 Codex app-server 的协议面，让既有 Codex app-server 客户端可以直接以 interpreter app-server 作为被启动进程。

在仓库源码中也能看到 harness 是配置系统的一等公民。codex-rs/config/src/config_toml.rs 定义了可选配置字段 harness（第 160 行，注释示例为 claude-code，即模拟的 harness 家族）、harness_guidance（是否包含所选 harness 的 Open Interpreter 引导，第 163 行）等。这意味着除了示例中的 kimi-code，你还可以通过 harness 切换机制让同一模型适配不同工具调用风格，具体可用 harness 以各模型文档为准（例如 Kimi K3 指南、zai-glm 相关文档、deepseek 相关文档）。

兼容性验证：仓库自带冒烟测试

仓库提供了免 provider 的兼容性冒烟测试脚本 scripts/test-codex-sdk-compat.sh，用于验证已安装的 interpreter 二进制能否通过 Codex SDK 正常工作。其要点如下：

• 通过环境变量 INTERPRETER_BIN 指定被测的 Open Interpreter 可执行文件；若未设置，则回退到 PATH 中的 interpreter（脚本第 5、12–14 行）。
• 若 interpreter 不存在或不可执行，脚本会提示设置 INTERPRETER_BIN 后退出（第 16–19 行）。
• 若缺少 node_modules 或 sdk/typescript/node_modules，会先执行 pnpm install --frozen-lockfile --filter @openai/codex-sdk...（第 23–25 行）。
• 构建 @openai/codex-sdk 后，通过环境变量 CODEX_EXEC_PATH="${interpreter_bin}" 让 SDK 覆盖启动路径（第 29–34 行），并在 sdk/typescript 目录中运行 Jest 测试 tests/run.test.ts，仅匹配用例名 "resumes thread by id"——即验证通过 thread id 恢复会话的能力。

从源码检出后直接运行：

./scripts/test-codex-sdk-compat.sh

该测试不需要任何模型 provider（不产生真实模型调用），是一条低成本的回归防线：确保 Open Interpreter 在 Codex SDK 客户端眼里"看起来就是 Codex"。

CI 场景：优先考虑 interpreter exec

如果你的 CI 只需要让一个 job 完整跑完，官方推荐优先使用非交互模式 interpreter exec，而不是把 SDK 嵌入流水线：

interpreter exec \
  -c 'model_provider="moonshotai"' \
  -c 'harness="kimi-code"' \
  -m "kimi-k3" \
  "Review this pull request and report blocking issues."

exec 的语义是"单任务跑到完成即退出"，无需维护长生命周期连接，天然适配脚本与流水线。结合 非交互模式文档，CI 中更完整的形态常配合 --json 输出结构化事件、--output-schema 约束最终答案格式，例如：

interpreter exec --json --sandbox read-only \
  "review this pull request diff for regressions" \
  < pr.diff > review.jsonl

而 SDK 更适合以下场景：

• 需要把 thread 保持存活、跨多个 turn 持续对话；
• 需要把流式事件（progress、tool calls、reasoning、最终消息）灌入应用界面；
• 需要在程序层面处理审批（approvals）；
• 需要把 agent 嵌入更大的工作流 / 更长生命周期的宿主进程。

简言之：「一次任务，等结果」用 exec；「长会话、要事件、要审批、要嵌入」用 SDK。若构建更丰富的独立客户端（如自己的 TUI/IDE 面板），则可进一步考虑 app-server 协议或 ACP，参考 app-server 文档 与 ACP 文档。

小结：集成决策速查

需求	推荐方式	关键入口
已有 TypeScript Codex 集成迁移	Codex({ codexPathOverride: "interpreter" })	sdk/typescript/src/codexOptions.ts
已有 Python codex_app_server 集成迁移	AppServerConfig(launch_args_override=("interpreter", "app-server", "--listen", "stdio://"))	上游 codex_app_server 包
CI 单次任务	interpreter exec（可加 --json/--output-schema）	exec 文档
长会话/事件流/审批/工作流嵌入	Codex SDK（exec 或 app-server 形态）	docs/sdk.md
更丰富客户端 / ACP 编辑器	interpreter app-server / interpreter acp	app-server 文档、ACP 文档
免 provider 兼容性回归	scripts/test-codex-sdk-compat.sh	test-codex-sdk-compat.sh

无论采用哪种接入方式，核心结论始终只有一个：Open Interpreter 不另起炉灶，而是让 Codex SDK 这条成熟链路继续发光——你只需要换掉它启动的那个进程。这也是本仓库模型接入文档（如 Kimi K3）反复强调同一段 diff（codexPathOverride: "interpreter"）的原因：整条工具链的 SDK 生态无需学习新协议，即可获得面向开放模型与对应 harness 的编码 agent 能力。