1. 项目概述：AI SDK 与 Codex CLI 的桥梁
如果你和我一样，既是 Vercel AI SDK 的深度用户，又对 OpenAI 的 Codex CLI 那强大的自主执行能力垂涎三尺，那么你肯定也遇到过那个经典的“两难困境”：AI SDK 提供了优雅、统一的模型调用接口，而 Codex CLI 则能直接操作你的文件系统、运行命令、调用工具，但两者之间却隔着一道鸿沟。你不得不在“用 AI SDK 写个简单的聊天应用”和“手动拼接 Codex CLI 的命令行参数”之间反复横跳，体验割裂。
ai-sdk-provider-codex-cli这个社区项目，就是来填平这道鸿沟的。它的核心定位非常清晰：作为一个 Vercel AI SDK v6 的 Provider（提供者），让你能像调用openai或anthropic模型一样，直接调用 Codex CLI 背后的 GPT-5.1/5.2/5.3 系列模型，并且无缝获得 Codex 的自主工具执行能力。简单说，它把 Codex CLI 这个命令行工具，“包装”成了 AI SDK 认识的一个“模型”。
这意味着什么？意味着你现在可以用你熟悉的generateText、streamText、generateObject这些 AI SDK 函数，去驱动一个能帮你写代码、改文件、运行测试、甚至搜索网页的 AI 代理。你不再需要自己处理子进程（spawn）、解析 JSON 输出、管理认证令牌，这个 Provider 帮你全包了。它支持两种后端模式：一种是每次调用都启动一个新 Codex 进程的codexExec模式，适合简单、独立的任务；另一种是维护一个持久化 JSON-RPC 连接的codexAppServer模式，支持真正的流式响应和可选的会话线程，适合复杂的多轮交互。
我花了几天时间深度集成和测试这个 Provider，本文将带你从零开始，彻底搞懂它的工作原理、两种模式的核心差异、如何进行高级配置（如工具流、日志、MCP 集成），并分享我在实际使用中踩过的坑和总结的最佳实践。无论你是想构建一个智能的代码助手、一个自动化的工作流脚本，还是任何需要 AI 主动执行操作的场景，这篇文章都能给你一份可直接“抄作业”的指南。
2. 核心架构与模式选型
在深入代码之前，我们必须先理解这个 Provider 的两种核心运行模式。这不仅仅是“选 A 还是选 B”的问题，而是决定了你整个应用的行为范式、资源开销和功能边界。选错了模式，后期重构的成本会很高。
2.1codexExec模式：简单直接的进程调用
codexExec模式的工作机制非常直观：每次你通过 AI SDK 发起一次模型调用（如generateText），Provider 就会在后台启动一个全新的codex exec子进程，将你的请求（提示词、工具调用等）通过命令行参数和标准输入传递过去，然后等待进程执行完毕，解析其--experimental-json格式的输出，最后将结果返回给 AI SDK。
你可以把它想象成每次点餐都叫一次外卖。它的优点是隔离性好。每个任务都是独立的沙盒，任务之间完全不会相互干扰。如果某个任务执行出错或卡死，最多影响这一次调用，不会拖垮整个应用。这对于 CI/CD 流水线中的一次性任务、简单的自动化脚本，或者对稳定性要求极高、不容许状态泄露的场景来说，是理想的选择。
然而，这种“一次一结”的方式代价也很明显：开销大。每次调用都需要启动完整的 Codex CLI 进程，包括加载模型、初始化环境等，这会带来显著的延迟。根据我的实测，即使是一个简单的“回复 hello”的任务，从调用到收到结果，codexExec模式也比codexAppServer模式平均多出 1.5 到 2 秒的冷启动时间。对于高频或交互式的应用，这个延迟是不可接受的。此外，它不支持真正的增量流式响应。虽然 AI SDK 的streamText接口能用，但由于当前 Codex CLI 的--experimental-json输出格式只在任务完成后才吐出完整内容，所以你收到的“流”实际上是一个大块。这对于需要实时显示生成过程的 UI 来说是个硬伤。
2.2codexAppServer模式：持久化的高效连接
codexAppServer模式则采用了完全不同的思路：它启动一个持久的codex app-server进程，并通过 JSON-RPC over stdio 与之建立一个长期的双向通信通道。所有的模型请求都通过这个通道发送和接收。
这就像是开了一家固定的餐厅，所有点餐都通过内部对讲机完成。它的最大优势是高效和功能完整。由于进程是常驻的，避免了重复的冷启动开销，后续请求的延迟极低，通常都在几百毫秒内。更重要的是，app-server协议原生支持真正的增量流式传输。当模型生成文本时，你可以实时收到一个个 token 组成的 delta 块，这对于构建流畅的聊天体验至关重要。此外，它还支持有状态的线程，你可以通过threadId让多个请求在同一个会话上下文中进行，实现连续对话。
当然，持久化模式也有其复杂性。你需要管理这个长期进程的生命周期（启动、关闭、异常重启）。如果app-server进程意外崩溃，所有正在进行的请求都会失败，你的应用需要具备重连或重启的逻辑。它也更消耗内存，因为 Codex 进程会一直驻留。不过，对于大多数需要交互性、低延迟和复杂会话的 Node.js 后端服务或桌面应用来说，codexAppServer模式带来的体验提升是决定性的。
我的选型心得：我通常会遵循一个简单的原则——“问次数”。如果我的应用模式是用户触发一个独立、完整的任务（例如“重构这个文件”、“生成本周报告”），我选
codexExec。如果我的应用模式是持续的、多轮的交互（例如一个聊天机器人或结对编程助手），我毫不犹豫地选择codexAppServer。在资源允许的情况下，codexAppServer通常是更优解。
3. 从零开始的完整配置与实操
理论讲完了，我们动手搭一个环境。假设我们要构建一个智能代码审查助手，它需要读取代码、分析问题、并给出修改建议。我们将使用codexAppServer模式来获得最佳交互体验。
3.1 环境准备与基础安装
首先，确保你的环境符合要求：Node.js 版本 >= 18。这是 Codex CLI 和现代 JavaScript 生态的基线。
第一步，安装并认证 Codex CLI。这里有个小坑：虽然 Provider 的package.json里把@openai/codex列为可选依赖，但我强烈建议你全局安装，并确保版本 >= 0.105.0。这能避免很多因路径问题导致的“command not found”错误。
# 全局安装最新版 Codex CLI npm install -g @openai/codex@latest # 验证安装和版本 codex --version # 应输出类似 0.105.0 或更高的版本 # 进行 OAuth 认证（推荐，使用你的 ChatGPT Plus/Pro 账户） codex login # 按照提示在浏览器中完成授权即可。 # 令牌会安全地存储在 ~/.codex/auth.json如果你更习惯使用 API Key，或者需要在无头环境（如 CI）中运行，可以设置环境变量：
export OPENAI_API_KEY='sk-...'接下来，在你的项目目录中安装 AI SDK v6 和这个 Provider：
# 初始化项目（如果尚未） npm init -y # 安装核心依赖 npm install ai ai-sdk-provider-codex-cli如果你的项目还在用 AI SDK v5，需要指定版本安装：
npm install ai@^5.0.0 ai-sdk-provider-codex-cli@ai-sdk-v53.2 构建一个基础的代码审查助手
让我们创建一个简单的脚本code-review.mjs。我们将使用codexAppServer模式，因为它需要处理多轮对话（比如我们追问“为什么这里不好？”）。
// code-review.mjs import { readFileSync } from 'fs'; import { generateText } from 'ai'; import { createCodexAppServer } from 'ai-sdk-provider-codex-cli'; // 1. 创建持久化的 app-server 提供者 const codexProvider = createCodexAppServer({ defaultSettings: { // 设置最小兼容版本，避免意外 minCodexVersion: '0.105.0', // 默认不自动批准，让 Codex 在执行任何写操作前询问（安全第一） autoApprove: false, // 设置 AI 的“性格”为务实型，专注于解决问题 personality: 'pragmatic', // 设置请求超时，避免长时间挂起 requestTimeoutMs: 120000, // 2分钟 }, }); // 2. 从文件系统读取待审查的代码 const targetCode = readFileSync('./example-buggy.js', 'utf-8'); // 3. 构建提示词 const prompt = ` 你是一个资深的 JavaScript 代码审查专家。请审查以下代码，指出其中的潜在问题、性能瓶颈、安全漏洞或不符合最佳实践的地方，并为每个问题提供具体的修改建议。 代码： \`\`\`javascript ${targetCode} \`\`\` 请以清晰的列表形式回复，每个问题包含：1) 问题描述，2) 风险等级（高/中/低），3) 修改后的代码片段。 `; async function main() { try { console.log('🤖 开始代码审查...'); const startTime = Date.now(); // 4. 调用模型 const { text } = await generateText({ // 使用 provider 函数创建模型实例，指定使用 gpt-5.3-codex 模型 model: codexProvider('gpt-5.3-codex'), prompt, // 可以在这里为本次调用覆盖默认设置 providerOptions: { 'codex-app-server': { // 例如，为这次审查开启更详细的推理过程 reasoningEffort: 'high', }, }, }); const duration = Date.now() - startTime; console.log(`✅ 审查完成 (耗时: ${duration}ms)\n`); console.log('='.repeat(50)); console.log(text); console.log('='.repeat(50)); } catch (error) { console.error('❌ 代码审查失败:', error); } finally { // 5. 非常重要：关闭 provider，释放资源 await codexProvider.close(); console.log('🛑 App-server 连接已关闭。'); } } main();这个脚本展示了几个关键点：
- Provider 初始化：通过
createCodexAppServer创建一个可复用的提供者实例，并设置了一些安全的默认值。 - 模型调用：
codexProvider('gpt-5.3-codex')返回一个符合 AI SDKLanguageModelV3接口的对象，可以直接用在generateText里。 - 资源管理：在
finally块中调用provider.close()是必须的，否则 Node.js 进程可能无法正常退出，因为那个持久的 Codex 子进程还在运行。
3.3 启用流式响应与工具调用监控
上面的例子是阻塞式的，我们要等到整个审查报告生成完才能看到结果。对于长文本，体验不好。让我们升级一下，使用streamText，并加入工具调用的监控，因为 Codex 在分析代码时，可能会尝试读取相关文件或执行命令来获取更多上下文。
// code-review-stream.mjs import { readFileSync } from 'fs'; import { streamText } from 'ai'; import { createCodexAppServer } from 'ai-sdk-provider-codex-cli'; const codexProvider = createCodexAppServer({ defaultSettings: { minCodexVersion: '0.105.0', autoApprove: false, personality: 'pragmatic', }, }); const targetCode = readFileSync('./example-buggy.js', 'utf-8'); const prompt = `审查这段代码，并尝试运行相关的测试来验证你的判断（如果有的话）:\n\`\`\`javascript\n${targetCode}\n\`\`\``; async function main() { console.log('🤖 开始流式代码审查（监控工具调用）...\n'); const startTime = Date.now(); const result = await streamText({ model: codexProvider('gpt-5.3-codex'), prompt, // 允许 Codex 执行工具（如运行测试） tools: {}, // 这里可以定义自定义工具，为空则允许 Codex 使用其内置工具集 }); let fullText = ''; for await (const part of result.fullStream) { switch (part.type) { case 'text-delta': // 实时收到文本块 process.stdout.write(part.textDelta); fullText += part.textDelta; break; case 'tool-call': // Codex 开始执行一个工具！ console.log(`\n🔧 [工具调用] 名称: ${part.toolName}`); console.log(` 参数: ${JSON.stringify(part.args, null, 2)}`); break; case 'tool-result': // 工具执行完成，返回结果 console.log(`\n✅ [工具结果] 工具: ${part.toolName}`); // 注意：result 可能是一个对象，包含 output, error 等字段 if (part.result?.output) { console.log(` 输出: ${part.result.output.substring(0, 200)}...`); // 截断长输出 } if (part.result?.error) { console.log(` 错误: ${part.result.error}`); } break; case 'finish': // 整个流完成 const duration = Date.now() - startTime; console.log(`\n\n✅ 审查流完成。总时长: ${duration}ms`); console.log(` 总令牌数: ${part.usage?.totalTokens}`); break; } } await codexProvider.close(); } main().catch(console.error);运行这个脚本，你会看到文本是逐段出现的，同时如果 Codex 决定运行npm test或git log等命令来辅助分析，你也能在控制台实时看到这些工具调用的发起和结果。这种透明性对于调试和构建可信的 AI 应用至关重要。
实操心得：工具执行的批准策略：注意我们设置了
autoApprove: false。这意味着当 Codex 试图执行一个可能具有副作用的操作（如写入文件、运行命令）时，它会通过 JSON-RPC 向我们的应用“请求批准”。在上面的简单脚本中，我们没有处理这些请求，因此任何需要批准的操作都会挂起直到超时。在生产环境中，你需要监听serverRequests选项来处理这些批准请求，或者根据任务风险等级，对某些安全操作（如读取文件）设置为自动批准。这是一个关键的安全设计，切勿忽略。
4. 高级配置与深度调优
基础功能跑通后，我们需要根据实际场景进行深度调优。Provider 提供了非常丰富的配置项，理解它们能让你更好地控制 Codex 的行为。
4.1 精细化控制：模型参数与配置覆盖
从 v0.4.0 开始，Provider 支持在创建模型时直接设置 Codex CLI 的高级参数。这些参数直接影响模型的推理过程和输出。
import { codexExec } from 'ai-sdk-provider-codex-cli'; const advancedModel = codexExec('gpt-5.3-codex', { allowNpx: true, skipGitRepoCheck: true, // 推理强度：控制模型花费多少“思考”时间。越高越慢，但可能更准确。 // 可选：'none', 'minimal', 'low', 'medium', 'high', 'xhigh' (部分模型支持) reasoningEffort: 'high', // 推理总结：控制模型是否及如何输出其内部推理过程。 // 'auto' 由模型决定，'detailed' 要求详细总结。 reasoningSummary: 'detailed', // 模型冗余度：控制输出的详细程度。'high' 会生成更啰嗦但可能更全面的回答。 modelVerbosity: 'medium', // 启用网页搜索功能（如果模型支持） webSearch: true, // 配置 MCP (Model Context Protocol) 服务器，为模型提供额外工具和能力。 mcpServers: { // 一个本地的、通过 stdio 通信的 MCP 服务器 myLocalTool: { transport: 'stdio', command: 'node', args: ['./my-mcp-server.js'], env: { SECRET_KEY: process.env.MY_SECRET }, }, // 一个远程的 HTTP MCP 服务器 companyDocs: { transport: 'http', url: 'https://mcp.internal.company.com', bearerTokenEnvVar: 'MCP_BEARER_TOKEN', // 从环境变量读取 token }, }, // 最强大的功能：直接覆盖 Codex CLI 的配置项。 // 这里的键值对会被转换为 `-c key=value` 或 `-c key.subkey=value` 的形式。 configOverrides: { // 启用实验性的会话恢复功能 'experimental_resume': '/tmp/codex_session.jsonl', // 配置沙盒的 workspace-write 策略，允许网络访问 'sandbox_workspace_write': { network_access: true }, }, });这里有个非常重要的细节：configOverrides的扁平化。当你传入一个嵌套对象如{ sandbox_workspace_write: { network_access: true } }时，Provider 会将其转换为命令行参数-c sandbox_workspace_write.network_access=true。对于数组，则会序列化为 JSON 字符串。这给了你极大的灵活性去调整那些尚未被 Provider 封装的高级 CLI 参数。
4.2 动态覆盖：使用providerOptions
有时，你希望对某一次特定的调用使用不同的参数，而不想创建新的模型实例。这时就需要providerOptions。
import { generateText } from 'ai'; const baseModel = codexExec('gpt-5.3-codex', { allowNpx: true, reasoningEffort: 'medium', // 默认中等推理强度 }); // 第一次调用：使用默认设置 const summary = await generateText({ model: baseModel, prompt: '简要总结这篇文章。', }); // 第二次调用：针对复杂问题，临时提升推理强度，并启用网页搜索 const deepAnalysis = await generateText({ model: baseModel, // 还是同一个 model 对象 prompt: '深度分析这个技术架构的优缺点，并搜索最新的替代方案。', providerOptions: { 'codex-cli': { // 注意这里的 key 是 'codex-cli'，对应 exec 模式 reasoningEffort: 'xhigh', webSearch: true, // 甚至可以临时添加一个 MCP 服务器 mcpServers: { webSearch: { transport: 'http', url: 'https://perplexity.mcp.server' }, }, }, }, });优先级规则是：providerOptions['codex-cli']（或['codex-app-server']）中的设置会覆盖创建模型时传入的CodexCliSettings，而后者又会覆盖 Codex CLI 自己的默认值。这让你可以轻松实现“基础配置 + 情景特化”的模式。
对于codexAppServer模式，用法类似，只是 key 换成了'codex-app-server'，并且可以传递线程相关的参数如threadId。
4.3 可观测性：配置日志系统
当你的应用变得复杂，调试问题就成了挑战。Provider 从 v0.5.0 开始内置了一个可配置的日志系统。
import winston from 'winston'; import { codexExec } from 'ai-sdk-provider-codex-cli'; // 方案1：使用内置的简单日志（默认只显示 WARN 和 ERROR） const model1 = codexExec('gpt-5.3-codex', { allowNpx: true }); // 控制台输出：[WARN] Codex CLI not found in PATH, falling back to npx... // 方案2：开启详细模式，看到所有 DEBUG 和 INFO 日志 const verboseModel = codexExec('gpt-5.3-codex', { allowNpx: true, verbose: true, // 关键参数 }); // 输出：[DEBUG] Spawning process: npx -y @openai/codex exec --model gpt-5.3-codex ... // 方案3：集成到你的应用日志系统（如 Winston, Pino） const logger = winston.createLogger({ /* ... 你的配置 ... */ }); const customModel = codexExec('gpt-5.3-codex', { allowNpx: true, verbose: true, logger: { debug: (msg) => logger.debug(`[Codex] ${msg}`), info: (msg) => logger.info(`[Codex] ${msg}`), warn: (msg) => logger.warn(`[Codex] ${msg}`), error: (msg) => logger.error(`[Codex] ${msg}`), }, }); // 方案4：完全关闭日志（用于生产环境或性能测试） const silentModel = codexExec('gpt-5.3-codex', { allowNpx: true, logger: false, // 不输出任何日志 });我的建议是：在开发阶段始终开启verbose: true，这能帮你理解 Provider 背后到底做了什么，尤其是在调试进程启动、参数传递和认证问题时。在生产环境，则集成到你的统一日志平台，并适当调整级别。
5. 实战避坑指南与疑难排查
在实际集成中，我遇到了不少问题。这里把最常见的坑和解决方案整理出来，希望能帮你节省数小时的调试时间。
5.1 认证失败与网络问题
问题现象：调用时抛出错误，提示Authentication failed或Failed to fetch，或者进程卡住无响应。
排查步骤：
- 首先验证 Codex CLI 本身是否工作。在终端直接运行
codex exec --model gpt-5.3-codex -- "echo hello"。如果这里就失败，问题出在 CLI 层面。 - 检查认证方式。如果你用了
codex login，确保~/.codex/auth.json文件存在且内容有效。Token 可能过期，重新运行codex login即可。 - 检查 API Key。如果使用
OPENAI_API_KEY，确保环境变量已正确设置，并且该 Key 有权限访问 GPT-5 系列模型（通常是 ChatGPT Plus/Pro 订阅关联的 key）。 - 网络代理问题。如果你在公司网络或使用代理，Codex CLI 可能无法连接到 OpenAI 服务。尝试设置
HTTP_PROXY/HTTPS_PROXY环境变量。特别注意：Provider 会将你设置的env选项传递给子进程，你可以这样设置：const model = codexExec('gpt-5.3-codex', { allowNpx: true, env: { ...process.env, HTTPS_PROXY: 'http://your-proxy:8080', HTTP_PROXY: 'http://your-proxy:8080', }, });
5.2 进程挂起与超时控制
问题现象：应用卡住，不报错也不返回结果，最终可能因超时而崩溃。
原因与解决：
- 等待用户批准：这是最常见的原因。当
autoApprove: false（默认）且 Codex 试图执行一个需要批准的操作（如写入文件、运行命令）时，它会等待你的应用响应。如果你没有设置serverRequests处理程序，请求就会一直挂起。- 解决方案A：对于完全自动化的场景，评估风险后可以设置
autoApprove: true。 - 解决方案B：实现
serverRequests处理程序，根据操作类型动态决定是否批准。
const provider = createCodexAppServer({ defaultSettings: { autoApprove: false, serverRequests: { // 当 Codex 请求批准时，这个函数会被调用 onApprovalRequest: async (request) => { console.log(`收到批准请求: ${request.action}`); // 例如，自动批准所有“读取”操作，拒绝所有“删除”操作 if (request.action.includes('read')) { return { approved: true }; } else if (request.action.includes('delete')) { return { approved: false, reason: 'Deletion not allowed' }; } // 其他操作，默认拒绝 return { approved: false, reason: 'Manual review required' }; }, }, }, }); - 解决方案A：对于完全自动化的场景，评估风险后可以设置
- 设置超时：总是为你的调用和 Provider 本身设置合理的超时。
// 为整个 app-server 设置请求超时 const provider = createCodexAppServer({ defaultSettings: { requestTimeoutMs: 180000, // 3分钟 idleTimeoutMs: 600000, // 10分钟无活动后关闭进程 }, }); // 或者在调用时使用 AbortSignal const controller = new AbortController(); setTimeout(() => controller.abort(), 120000); // 2分钟后超时 try { const result = await generateText({ model, prompt, abortSignal: controller.signal, }); } catch (error) { if (error.name === 'AbortError') { console.log('请求超时'); } }
5.3 流式响应不“流”的问题
问题现象：使用streamText时，text-delta事件不是一个个 token 地触发，而是很久之后一次性收到一大段完整文本。
原因：这是codexExec模式的当前限制。因为 Codex CLI 的exec命令使用的--experimental-json输出格式，目前只在任务完成时发送一个包含完整文本的item.completed事件，不支持中间增量。所以 Provider 在 exec 模式下无法实现真正的流式传输。
解决方案：如果你需要真正的增量流式响应（例如构建打字机效果），必须使用codexAppServer模式。只有app-server协议才支持item/agentMessage/delta事件，从而实现逐 token 的流式传输。
5.4 JSON Schema 与generateObject的陷阱
使用generateObject配合 Zod schema 来让 AI 返回结构化数据非常方便，但这里有坑。
问题：你定义了一个包含可选字段或格式验证（如.email()）的 Zod Schema，但调用时返回错误，提示 Schema 无效。
根因：OpenAI 的严格模式（strict mode）对 JSON Schema 的支持有限制。Provider 在底层会将你的 Zod Schema 转换为 JSON Schema 并通过--output-schema传给 Codex。但 OpenAI 后端会：
- 拒绝所有标记为
optional的字段。 - 静默移除
format校验器（如email,url,uuid）。 - 移除
pattern校验器。
解决方案：在定义 Schema 时进行适配。
import { z } from 'zod'; // ❌ 错误：包含可选字段和格式校验 const badSchema = z.object({ name: z.string(), email: z.string().email().optional(), // optional 和 email() 都会被移除/拒绝 website: z.string().url().optional(), }); // ✅ 正确：所有字段 required，用 description 替代 format 提示 const goodSchema = z.object({ name: z.string().describe('Full name of the user'), email: z.string().describe('A valid email address'), // 去掉 .email() website: z.string().describe('A valid URL starting with http:// or https://'), // 去掉 .url() }); // 使用 const { object } = await generateObject({ model: codexExec('gpt-5.3-codex', { allowNpx: true }), schema: goodSchema, prompt: 'Generate a user profile.', });虽然格式校验在 Schema 层面失效了，但你仍然可以在收到数据后，用原始的 Zod Schema（包含校验）在应用层进行二次验证，或者依赖模型的指令（通过describe）来引导其生成正确格式。
5.5 多模态输入（图片）的注意事项
Provider 支持上传图片给视觉模型，但不同模式支持度不同。
codexExec模式：只支持本地图片数据（Buffer, base64, data URL）。你需要将图片文件读入内存再传递。import { readFileSync } from 'fs'; const imageBuffer = readFileSync('./screenshot.png'); const model = codexExec('gpt-5.3-codex', { allowNpx: true }); const { text } = await generateText({ model, messages: [{ role: 'user', content: [ { type: 'text', text: '描述这张图片' }, { type: 'image', image: imageBuffer, mimeType: 'image/png' }, ] }], });codexAppServer模式：除了本地图片，还支持远程图片 URL（HTTP/HTTPS）。Provider 会将 URL 直接转发给app-server。const model = appServerProvider('gpt-5.3-codex'); const { text } = await generateText({ model, messages: [{ role: 'user', content: [ { type: 'text', text: '分析这张网络图片' }, { type: 'image', image: 'https://example.com/chart.png' }, ] }], });
重要提示：对于本地图片，Provider 会将其写入一个临时文件，然后通过--image参数传递给 Codex。这个临时文件在请求结束后会被自动清理。确保你的系统有足够的临时存储空间来处理可能的大图片。
6. 性能优化与生产环境建议
当你准备将应用部署到生产环境时，以下几点需要特别关注。
6.1 连接与进程管理
对于codexAppServer模式，不要为每个请求都创建新的 Provider 实例。这会导致系统启动大量持久的 Codex 进程，迅速耗尽内存。正确的做法是创建一个全局的或单例的 Provider 实例，在整个应用生命周期内复用。
// app-server-provider.js - 单例模式 import { createCodexAppServer } from 'ai-sdk-provider-codex-cli'; let _provider = null; let _initializing = false; export async function getCodexProvider() { if (_provider) return _provider; if (_initializing) { // 等待正在进行的初始化 await new Promise(resolve => setTimeout(resolve, 100)); return getCodexProvider(); } _initializing = true; try { _provider = createCodexAppServer({ defaultSettings: { minCodexVersion: '0.105.0', requestTimeoutMs: 180000, idleTimeoutMs: 600000, // 10分钟空闲后关闭，节省资源 }, }); // 可以在这里进行一个健康检查调用 await _provider.listModels(); // 这会触发 app-server 启动 console.log('Codex app-server provider 初始化成功。'); return _provider; } catch (error) { _provider = null; throw new Error(`Failed to initialize Codex provider: ${error.message}`); } finally { _initializing = false; } } // 应用关闭时，优雅地关闭 provider process.on('SIGTERM', async () => { if (_provider) { await _provider.close(); } process.exit(0); });6.2 错误处理与重试策略
网络请求、子进程都可能出错。一个健壮的生产应用需要完善的错误处理和重试机制。
import { generateText } from 'ai'; async function robustGenerateText(model, prompt, maxRetries = 3) { let lastError; for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await generateText({ model, prompt }); } catch (error) { lastError = error; console.warn(`生成文本失败 (尝试 ${attempt}/${maxRetries}):`, error.message); // 根据错误类型决定是否重试 // 1. 认证失败、无效模型等错误不应重试 if (error.message.includes('Authentication') || error.message.includes('Invalid model')) { break; } // 2. 超时、网络错误、进程崩溃可以重试 if (error.message.includes('timeout') || error.message.includes('ECONNREFUSED') || error.message.includes('spawn')) { // 指数退避 const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000); await new Promise(resolve => setTimeout(resolve, delay)); continue; } // 3. 其他错误，默认不重试 break; } } throw lastError; }6.3 监控与指标收集
你需要知道你的 AI 应用运行状况。除了集成日志，还可以收集一些关键指标：
- 延迟：记录每个请求从发起到收到第一个 token 的时间（TTFT）和总完成时间。
- 令牌使用量：AI SDK 的
finish事件会返回usage对象，包含promptTokens和completionTokens。记录它们以监控成本和用量。 - 工具调用统计：记录工具调用的次数、类型、成功率，这能帮你了解 AI 是如何使用工具的。
- 进程健康度：对于
app-server模式，可以定期发送一个轻量的 ping 请求（如listModels）来检查连接是否存活。
// 一个简单的指标收集示例 const metrics = { totalCalls: 0, totalTokens: 0, toolCalls: {}, }; const result = await streamText({ model, prompt }); for await (const part of result.fullStream) { if (part.type === 'tool-call') { metrics.toolCalls[part.toolName] = (metrics.toolCalls[part.toolName] || 0) + 1; } if (part.type === 'finish' && part.usage) { metrics.totalCalls++; metrics.totalTokens += (part.usage.promptTokens || 0) + (part.usage.completionTokens || 0); } }6.4 安全边界设定
赋予 AI 执行命令和读写文件的能力是强大的，也是危险的。务必设定清晰的安全边界。
- 沙盒模式（Sandbox Mode）：这是最重要的安全机制。Provider 默认使用
sandboxMode: 'workspace-write'，这意味着 Codex 只能在当前工作目录及其子目录下写入文件。切勿在生产环境中使用dangerouslyBypassApprovalsAndSandbox: true。 - 批准策略（Approval Policy）：默认的
approvalMode: 'on-failure'意味着 Codex 只在命令执行失败后请求批准重试。对于高风险操作，可以考虑设置为'on-request'，让 Codex 在执行任何可能改变系统的操作前都请求批准，然后通过serverRequests.onApprovalRequest实现你的审批逻辑。 - 目录白名单：使用
addDirs选项明确指定 Codex 可以访问的额外目录，而不是给它整个文件系统的权限。 - 环境变量过滤：通过
env选项控制传递给 Codex 进程的环境变量。避免传递敏感信息如AWS_ACCESS_KEY_ID,DATABASE_URL等。
const safeModel = codexExec('gpt-5.3-codex', { allowNpx: true, // 限制写入范围到当前目录和特定的 log 目录 sandboxMode: 'workspace-write', addDirs: ['./logs'], // 只额外允许访问 ./logs 目录 // 只传递必要的、非敏感的环境变量 env: { PATH: process.env.PATH, HOME: process.env.HOME, // 显式传递一个安全的变量 APP_ENV: 'production', // 不传递其他变量 }, // 要求所有写操作都需批准 approvalMode: 'on-request', });遵循这些实践，你就能构建出一个既强大又相对安全的 AI 驱动应用。ai-sdk-provider-codex-cli这个项目真正将 Codex CLI 的自动化能力带入了成熟的 Node.js 应用开发生态，让开发者可以专注于业务逻辑，而不是底层进程通信的细节。随着 OpenAI 不断更新 Codex CLI 和模型，这个 Provider 也必然会持续进化，值得长期关注和投入。
