← Harness

模型与开放条件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 的质量如何？官方没给量化结论。本站也没实测。

运行位置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

本地文件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

关机后的任务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

工具与扩展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 建立关联。

上下文与记忆Context & memory

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

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

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

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

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

权限与限制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 三页。）

适合什么任务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 透传。

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