← Harness

「把 Codex CLI 变成 Node 进程里可驱动的对象」 —— 官方 README 首句就是 「Embed the Codex agent in your workflows and apps」，第二句划清了形态： > The TypeScript SDK wraps the codex CLI from @openai/codex. > It spawns the CLI and exchanges JSONL events over stdin/stdout.

模型与开放条件

两条路径，本站的判断是「默认走OpenAI，但架构上没锁死」。 证据一：README 里的配置示例 baseUrl 会被翻译成 --config openai_base_url=... 传给 CLI， 即换 API 端点是一等配置项（原文：If you set baseUrl, the SDK passes it as a --config openai_base_url=... override）。 证据二：codex-rs 源码里 model_providers 是正式配置项（站内搜索 162 处引用， 分布在 config/src/thread_config.rs、core/src/config/requirements.rs 等）。 证据三：ThreadOptions 有独立的 model?: string 字段。 但要说清：SDK 本身没有任何「provider-agnostic」表述，也没有像 OpenAI Agents SDK 那样列出可选 extra（litellm / any-llm）。 换第三方模型后工具调用与 structured output 的可靠性，本站未核验。

运行位置

进程形态是「你的 Node 进程 + 一个被 spawn 的 CLI 子进程」。 README 的 env 参数说明值得注意：「By default, the Codex CLI inherits the Node.js process environment」，你可以整体控制 CLI 看到哪些环境变量， 官方给的用途是 sandboxed hosts like Electron apps。 SDK 仍会在这之上注入自己需要的变量（如 CODEX_API_KEY）。 这条对 Electron / 桌面应用集成是决定性的，官方明确点了这个场景。

本地文件

本地文件是 CLI 的原生能力，SDK 侧只需给工作目录。 workingDirectory 设置运行目录；additionalDirectories 可追加额外目录； 另有 local_image 类型的输入条目可把本地图片传给 CLI（走 --image）。 一个必须知道的行为：Codex 要求工作目录是一个 Git 仓库， 否则拒绝运行（官方原文：To avoid unrecoverable errors, Codex requires the working directory to be a Git repository）——可以用 skipGitRepoCheck 跳过。 这对选型是硬约束：非 Git 目录（纯数据目录、临时目录）里开箱即用不了。

关机后的任务

最值得注意的一点：这是本站收录对象里唯一官方明确支持「非交互执行」的。 仓库里有 docs/exec.md，标题就是 Non-interactive mode（正文只留外链， 指向 developers.openai.com/codex/noninteractive）。 与 CLI 站那份档案里 Gemini CLI 是「唯一明确支持非交互」的对照正好构成一组： 在这个 harness 站里，Codex SDK 同样是非交互执行这条路的主要候选。 线程持久化有官方支撑：README 说 Threads are persisted in ~/.codex/sessions， 内存里的 Thread 对象丢了可以用 resumeThread() 重建继续。 注意 ~/.codex/sessions 是文件目录而非数据库 —— 意味着状态与进程同机器， 跨机迁移与并发写的语义本站未核验。

工具与扩展

工具面完全由 CLI 决定，SDK 不新增也不裁剪。README 全文没有出现 MCP。 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 收录的 9 个 server 里没有它的位置 —— Codex CLI 是否支持 MCP、 本站未核验（SDK README 未提，主仓 docs 目录里也没有 mcp.md）。

上下文与记忆

本站最关心的维度，本对象提供的是「会话续接」而不是「上下文管理」。 证据是 resumeThread(threadId)：能恢复对话继续跑，但没有压缩、摘要或落盘机制。 换句话说：Thread 解决的是可靠续跑（本站主张的「状态」面）， 不解决长上下文（本站主张的「上下文」面）。 要压上下文只能靠 CLI 侧的配置或换模型，SDK 层没有暴露相关选项。

权限与限制

这是本站核对下来最有价值的一处发现 —— 它把 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。 推理强度可调：ModelReasoningEffort 有 8 档 （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 托管设置。 ⚠ 三档沙箱各档在具体平台（Windows / macOS / Linux）上的实现差异本站未核验 （docs/sandbox.md 正文只有外链）。

适合什么任务

适合：要把 Codex 塞进自己的 Node 应用 / Electron 应用 / CI； 需要非交互执行；需要精确的文件级权限规则；TypeScript 或 Python 栈； 已经决定用 OpenAI 模型但想让模型层可换。 不适合：想要一个纯库、不想额外背一个 CLI 子进程（用 OpenAI Agents SDK）； 目标目录不是 Git 仓库又不愿开skipGitRepoCheck； 需要 SDK 层自己做上下文压缩（本站未核验 CLI 侧是否有可配的压缩策略）。

本页由 ai-agent-guide 数据层生成（CC BY 4.0）。 方法论与坐标系定义见仓库内 METHODOLOGY.md。