OpenAI Codex CLI工具中shell函数模式验证错误分析与解决方案

问题背景

OpenAI Codex CLI工具在最新版本(0.1.2504220136)中出现了一个关键功能异常，当用户尝试执行shell命令时，系统会返回400错误，提示"Invalid schema for function 'shell'"的错误信息，具体指出缺少'workdir'参数。这个问题影响了macOS、Windows和Linux等多个平台上的用户。

技术分析

根本原因

该问题的根源在于OpenAI API对函数模式验证规则的变更。在最新版本中，API开始严格执行以下验证规则：

1. 所有在properties中定义的参数都必须出现在required数组中
2. 如果参数被定义但未标记为required，API将拒绝请求

在Codex CLI的代码中，shell函数模式定义了三个参数：

• command(命令内容，数组类型)
• workdir(工作目录，字符串类型)
• timeout(超时时间，数字类型)

但required数组中仅包含了command参数，这违反了API的最新验证规则。

错误表现

当用户执行任何涉及shell命令的操作时，CLI会返回如下错误信息：

400 Invalid schema for function 'shell': In context=(), 'required' is required to be supplied and to be an array including every key in properties. Missing 'workdir'.

解决方案

临时解决方案

对于急需使用CLI的用户，可以回退到上一个稳定版本：

npm install -g @openai/codex@0.1.2504211509

永久修复方案

开发团队已在版本0.1.2504221401中修复了此问题。修复方式是对shell函数模式进行以下修改：

parameters: {
  type: "object",
  properties: {
    command: { type: "array", items: { type: "string" } },
    workdir: {
      type: "string",
      description: "The working directory for the command.",
    },
    timeout: {
      type: "number",
      description: "The maximum time to wait for the command to complete in milliseconds.",
    },
  },
  required: ["command", "workdir", "timeout"],
  additionalProperties: false,
}

升级指南

用户应执行以下命令升级到修复版本：

npm install -g @openai/codex@latest

技术启示

1. API验证规则的变更可能对现有系统产生重大影响，开发时应密切关注上游变更日志
2. 函数模式定义需要严格遵循OpenAI API的规范要求
3. 在定义可选参数时，需要权衡API验证规则和实际业务需求
4. 版本回退是解决紧急问题的有效临时方案，但应及时跟进官方修复

总结

OpenAI Codex CLI工具的这次验证错误展示了API演进过程中可能遇到的兼容性问题。通过理解API验证机制和及时应用修复版本，用户可以顺利解决此类问题。这也提醒开发者，在使用第三方API时，需要建立有效的变更监控机制，以便快速响应类似的兼容性变更。