Codex SDKCodex SDK

模型与开放条件Model & openness

默认走 OpenAI，但架构上没锁死。

三条证据：

• README 的配置示例里 baseUrl 会被翻译成 --config openai_base_url=... 传给 CLI —— 也就是说，换 API 端点是一等配置项

• 官方 config-advanced 有专节 Custom model providers（已核验）： 顶层 model = ... 配 model_provider = "proxy"，再写 [model_providers.<id>] （字段有 base_url / env_key / wire_api / http_headers / auth.command）

• ThreadOptions 有独立的 model?: string 字段

内置的 provider ID：保留 openai、ollama、lmstudio， 另内置 amazon-bedrock 与 azure。openai_base_url 可以改内置 provider 的 base URL。

官方示例直接给了第三方：

官方示例：[model_providers.mistral] base_url = "https://api.mistral.ai/v1"

还支持 OSS 模式：--oss 配 oss_provider = "ollama" | "lmstudio"。

即：官方明确支持接非 OpenAI 模型（本地 Ollama / LM Studio、Mistral、Bedrock 等）。

README 原文：If you set baseUrl, the SDK passes it as a --config openai_base_url=... override

⚠ 但换第三方模型之后呢？工具调用与 structured output 的质量如何？官方没给量化结论。本站也没实测。

Defaults to OpenAI, but the architecture is not locked down.

Three pieces of evidence:

• the README's config example translates baseUrl into --config openai_base_url=... passed to the CLI — i.e. switching the API endpoint is a first-class config item

• the official config-advanced page has a dedicated Custom model providers section (verified): top-level model = ... with model_provider = "proxy", then [model_providers.<id>] (fields include base_url / env_key / wire_api / http_headers / auth.command)

• ThreadOptions has its own model?: string field

Built-in provider IDs: reserved openai, ollama, lmstudio, plus built-in amazon-bedrock and azure. openai_base_url can change a built-in provider's base URL.

The official example directly gives a third party:

Official example: [model_providers.mistral] base_url = "https://api.mistral.ai/v1"

OSS mode is also supported: --oss with oss_provider = "ollama" | "lmstudio".

That is: the official docs explicitly support non-OpenAI models (local Ollama / LM Studio, Mistral, Bedrock etc.).

README wording: If you set baseUrl, the SDK passes it as a --config openai_base_url=... override

⚠ But after switching to a third-party model? How good are tool calling and structured output quality? The official docs give no quantified conclusion. This site has not measured either.

运行位置Where it runs

进程形态是「你的 Node 进程 + 一个被 spawn 的 CLI 子进程」。

README 的 env 参数说明值得注意。默认情况下 CLI 继承 Node 进程的环境变量。 所以你可以整体控制 CLI 能看到哪些变量。官方给的用途是 sandboxed hosts（例如 Electron 应用）。

SDK 会在继承之上再注入自己需要的变量（如 CODEX_API_KEY）。

这条对 Electron / 桌面应用集成是决定性的 —— 官方明确点了这个场景。

README 原文：By default, the Codex CLI inherits the Node.js process environment

The process form is "your Node process + a spawned CLI subprocess."

The README's env parameter note is worth attention. By default the CLI inherits the Node process environment. So you can fully control which variables the CLI sees. The official use case given is sandboxed hosts (e.g. Electron apps).

The SDK injects its own needed variables (like CODEX_API_KEY) on top of the inheritance.

This is decisive for Electron / desktop-app integration — the official docs call out this scenario explicitly.

README wording: By default, the Codex CLI inherits the Node.js process environment

本地文件Local files

本地文件是 CLI 的原生能力，SDK 侧只需要给工作目录。

三个相关参数：

• workingDirectory —— 设置运行目录
• additionalDirectories —— 追加额外目录
• local_image 类型的输入条目 —— 把本地图片传给 CLI（走 --image）

⚠ 一个必须知道的行为：Codex 要求工作目录是一个 Git 仓库。不满足就拒绝运行。 可以用 skipGitRepoCheck 跳过这个检查。

这对选型是硬约束：非 Git 目录（纯数据目录、临时目录）里开箱用不了。

官方原文：To avoid unrecoverable errors, Codex requires the working directory to be a Git repository

Local files are a native CLI capability; the SDK side only needs a working directory.

Three relevant parameters:

• workingDirectory — sets the run directory
• additionalDirectories — appends extra directories
• local_image type input items — pass local images to the CLI (via --image)

⚠ One behavior you must know: Codex requires the working directory to be a Git repository. It refuses to run otherwise. The check can be skipped with skipGitRepoCheck.

This is a selection-level hard constraint: it does not work out of the box in non-Git directories (pure data dirs, temp dirs).

Official wording: To avoid unrecoverable errors, Codex requires the working directory to be a Git repository

关机后的任务Tasks after shutdown

这是本站收录对象里，唯一被官方明确支持「非交互执行」的一个。

核验：官方 noninteractive 页已核验（docs/exec.md 指向它）。 codex exec 面向 scripts 与 CI。

• 默认 read-only sandbox；可用 --sandbox workspace-write 或 danger-full-access
• --json 输出 JSONL
• --output-schema 给结构化输出
• --ephemeral 不落盘
• 可续跑：codex exec resume --last，或 codex exec resume <SESSION_ID>

SDK 侧对应 resumeThread()，Threads 持久化在 ~/.codex/sessions。

（这与 CLI 条目的对照构成一组。那边「Gemini CLI 是唯一明确支持非交互」。）

⚠ 注意 ~/.codex/sessions 是文件目录，不是数据库。状态与进程在同一台机器上。

跨机迁移与多进程并发写的语义，官方未说明。 （已查 noninteractive 与 config-reference 两页，它们只讲 history.persistence 与 resume。）

官方对 codex exec 的定位：scripts and CI

Among objects collected on this site, this is the only one officially and explicitly supported for non-interactive execution.

Verified: the official noninteractive page is verified (docs/exec.md points to it). codex exec targets scripts and CI.

• default read-only sandbox; --sandbox workspace-write or danger-full-access available
• --json outputs JSONL
• --output-schema for structured output
• --ephemeral writes nothing to disk
• resumable: codex exec resume --last, or codex exec resume <SESSION_ID>

The SDK-side counterpart is resumeThread(); Threads persist under ~/.codex/sessions.

(This forms a pair with the CLI entry. Over there, "Gemini CLI is the only one explicitly supporting non-interactive".)

⚠ Note ~/.codex/sessions is a file directory, not a database. State and process live on the same machine.

Cross-machine migration and multi-process concurrent-write semantics are not stated officially. (noninteractive and config-reference pages checked; they only cover history.persistence and resume.)

The official positioning of codex exec: scripts and CI

工具与扩展Tools & extensions

工具面完全由 CLI 决定 —— SDK 既不新增也不裁剪。

SDK 侧你拿到的是结构化事件流。runStreamed() 返回 async generator。事件类型有：

• item.completed —— 工具调用、流式响应、文件变更通知
• turn.completed —— 含 usage 统计

Structured output 是 SDK 明确支持的一等能力：outputSchema 可以传 JSON Schema， 官方还推荐 Zod 转换路径 zodToJsonSchema(schema, { target: "openAi" })。

⚠ 这里有个命名陷阱：那个 target 写的是 "openAi"。 但它产出的是通用 JSON Schema。给任何遵守该 schema 的模型用都行，不代表只能用 OpenAI。

MCP 的情况要说清。README 全文没出现 MCP。本站收录的 9 个 MCP server 里也没有它的位置。 但 Codex CLI 的 MCP 支持已核验（官方有独立 MCP 页）：

• 传输：STDIO（command / args / env / env_vars / cwd）与 Streamable HTTP（url / bearer / headers）
• 配置：codex mcp 命令行，或 config.toml 的 [mcp_servers.<name>]
• 工具开关：enabled_tools / disabled_tools
• 审批：per-server 与 per-tool 的 approval_mode（auto / prompt / approve）
• 认证：codex mcp login 走 OAuth

官方原文：Codex supports MCP servers in both the CLI and the IDE extension SDK 侧：SDK 的 config 透传即写入 CLI 的 config.toml，故 MCP 可经此可用； 但官方未在 SDK README 明写这条衔接，本站只把它记作 CLI 能力， 仍不与 MCP 站的 server 建立关联。

The tool surface is entirely decided by the CLI — the SDK neither adds nor trims.

On the SDK side you get a structured event stream. runStreamed() returns an async generator. Event types:

• item.completed — tool calls, streaming responses, file-change notifications
• turn.completed — includes usage stats

Structured output is a first-class capability the SDK explicitly supports: outputSchema takes a JSON Schema, and the official docs also recommend the Zod conversion path zodToJsonSchema(schema, { target: "openAi" }).

⚠ There is a naming trap here: that target says "openAi". But what it produces is generic JSON Schema. Any model honoring that schema can use it — it does not mean OpenAI only.

The MCP situation needs stating clearly. The README never mentions MCP. None of the 9 MCP servers collected on this site involve it either. But Codex CLI's MCP support is verified (the official docs have a standalone MCP page):

• transports: STDIO (command / args / env / env_vars / cwd) and Streamable HTTP (url / bearer / headers)
• config: the codex mcp command line, or [mcp_servers.<name>] in config.toml
• tool switches: enabled_tools / disabled_tools
• approvals: per-server and per-tool approval_mode (auto / prompt / approve)
• auth: codex mcp login via OAuth

Official wording: Codex supports MCP servers in both the CLI and the IDE extension SDK side: the SDK's config passthrough writes into the CLI's config.toml, so MCP is reachable this way; but the official SDK README does not spell out this linkage, so this site records it only as a CLI capability and still does not link it to the MCP-site servers.

上下文与记忆Context & memory

它提供的是「会话续接」，不是「上下文管理」。

证据是 resumeThread(threadId)。它能恢复对话继续跑，但没有压缩、摘要或落盘机制。

换句话说，Thread 解决的是可靠续跑（本站说的「状态」面）， 不解决长上下文（本站说的「上下文」面）。

要压上下文，只能靠 CLI 侧的配置或换模型 —— SDK 层没有暴露相关选项。

⚠ SDK 侧与 MCP 的衔接：SDK 的 config 透传会写入 CLI 的 config.toml， 所以 MCP 理论上可经此可用。但官方没有在 SDK README 里明写这条衔接 —— 本站只把它记作 CLI 的能力，不与 MCP 站的 server 建立关联。

What it provides is "session continuation", not "context management".

The evidence is resumeThread(threadId). It can restore a conversation and keep running, but there is no compaction, summarization or offloading mechanism.

In other words, Thread solves reliable resume (the "state" surface as this site defines it), not long context (the "context" surface as this site defines it).

To compact context you can only rely on CLI-side config or switch models — the SDK layer exposes no related options.

⚠ SDK-side linkage with MCP: the SDK's config passthrough writes into the CLI's config.toml, so MCP is theoretically reachable this way. But the official SDK README does not spell out this linkage — this site records it only as a CLI capability and does not link it to the MCP-site servers.

权限与限制Permissions & limits

这是本站核对下来最有价值的一处发现：它补上了 CLI 条目里遗留的审批枚举缺口。

证据来自 SDK 源码（不是文档）sdk/typescript/src/threadOptions.ts 的类型定义：

• 审批模式四档 —— ApprovalMode = "never" | "on-request" | "on-failure" | "untrusted"
• 沙箱三档 —— SandboxMode = "read-only" | "workspace-write" | "danger-full-access"
• 网络单独控制 —— networkAccessEnabled?: boolean、 webSearchMode?: "disabled" | "cached" | "live"、webSearchEnabled?: boolean

• 推理强度 8 档 —— ModelReasoningEffort：minimal / low / medium / high / xhigh / max / ultra / persistent

另一层是配置透传。SDK 支持 config，它会自动展平成 dotted path、转 TOML 传给 --config。 另有 configOverrides（原始 TOML 逐条透传）。官方示例直接给了文件系统级规则：

官方示例：permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}

也就是可以按路径精确拒绝读 .env 这类文件。官方说明的优先级： 原始 overrides > 结构化 config > SDK 托管设置。

沙箱与审批的官方口径已核验（agent-approvals-security 与 config-advanced）：

• 本地默认 workspace-write + 网络关闭；非版本控制目录默认 read-only
• 顶层键 approval_policy（untrusted / on-request / never / granular， 含 approvals_reviewer = "auto_review"）与 sandbox_mode 成对使用

• [sandbox_workspace_write] 可设 writable_roots、network_access
• 有命名 profile：:read-only / :workspace / :danger-full-access
• workspace-write 下，.git / .agents / .codex 仍递归只读
• 网络另有 features.network_proxy 域名 allowlist + DNS 重绑定防护

⚠ 三档沙箱在各平台的实现有差异。平台指 Windows / macOS / Linux。官方没有逐条给出这些差异。 官方只说「OS-level mechanisms enforce sandbox policies」，默认无网络、写入限工作区。

（已查 agent-approvals-security、config-advanced、config-reference 三页。）

This is the most valuable finding from this site's cross-check: it fills the approval-enum gap left in the CLI entry.

The evidence comes from SDK source (not docs), the type definitions in sdk/typescript/src/threadOptions.ts:

• four approval modes — ApprovalMode = "never" | "on-request" | "on-failure" | "untrusted"
• three sandbox tiers — SandboxMode = "read-only" | "workspace-write" | "danger-full-access"
• network controlled separately — networkAccessEnabled?: boolean, webSearchMode?: "disabled" | "cached" | "live", webSearchEnabled?: boolean

• reasoning effort has 8 levels — ModelReasoningEffort: minimal / low / medium / high / xhigh / max / ultra / persistent

The other layer is config passthrough. The SDK supports config, auto-flattened into dotted paths and converted to TOML for --config. There is also configOverrides (raw TOML passed item by item). The official example directly gives filesystem-level rules:

Official example: permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}

That means reading a file like .env can be denied precisely by path. The official precedence: raw overrides > structured config > SDK-managed settings.

Sandbox and approval official defaults verified (agent-approvals-security and config-advanced):

• local default workspace-write + network off; non-version-controlled dirs default to read-only
• top-level keys approval_policy (untrusted / on-request / never / granular, including approvals_reviewer = "auto_review") pair with sandbox_mode

• [sandbox_workspace_write] can set writable_roots, network_access
• there are named profiles: :read-only / :workspace / :danger-full-access
• under workspace-write, .git / .agents / .codex remain recursively read-only
• network additionally has features.network_proxy domain allowlist + DNS-rebinding protection

⚠ The three sandbox tiers differ in per-platform implementation. Platforms mean Windows / macOS / Linux. The official docs do not enumerate these differences item by item. They only say "OS-level mechanisms enforce sandbox policies", with no network by default and writes limited to the workspace.

(agent-approvals-security, config-advanced, config-reference pages checked.)

适合什么任务Best for

适合四类情况：

• 要把 Codex 塞进自己的 Node 应用 / Electron 应用 / CI
• 需要非交互执行
• 需要精确到文件级的权限规则
• TypeScript 或 Python 栈，且已决定用 OpenAI 模型但想让模型层可换

不适合两类情况：

• 想要一个纯库、不想额外背一个 CLI 子进程 —— 那用 OpenAI Agents SDK
• 目标目录不是 Git 仓库，又不愿开 skipGitRepoCheck

⚠ 还有一处能力边界：需要 SDK 层直接暴露压缩 API 的话它不满足。

CLI 侧有 compact_prompt / experimental_compact_prompt_file 与 PreCompact / PostCompact hooks 可配，但 SDK 层没有专门的压缩接口， 只能靠 config 透传。

Fits four scenarios:

• embedding Codex into your own Node app / Electron app / CI
• needing non-interactive execution
• needing file-path-precise permission rules
• TypeScript or Python stacks, already committed to OpenAI models but wanting the model layer swappable

Does not fit two scenarios:

• wanting a pure library without carrying an extra CLI subprocess — use the OpenAI Agents SDK for that
• the target directory is not a Git repo and you are unwilling to enable skipGitRepoCheck

⚠ One more capability boundary: if you need a compaction API exposed directly at the SDK layer, it does not deliver.

The CLI side has compact_prompt / experimental_compact_prompt_file and PreCompact / PostCompact hooks configurable, but the SDK layer has no dedicated compaction interface, only config passthrough.

// sdk/typescript/src/threadOptions.ts（核验 2026-10-01）
export type ApprovalMode = "never" | "on-request" | "on-failure" | "untrusted";
export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";

configOverrides: ['permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}']

// sdk/typescript/src/threadOptions.ts (verified 2026-10-01)
export type ApprovalMode = "never" | "on-request" | "on-failure" | "untrusted";
export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";

configOverrides: ['permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}']

const turn = await thread.run("Summarize repository status", { outputSchema: schema });

const turn = await thread.run("Summarize repository status", { outputSchema: schema });

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.