增强 Codex CLI / Responses API 工具调用兼容性

[mariotong]

背景

这组改动主要是为了提升 grok2api 在 OpenAI Responses API 兼容模式下对 Codex CLI 的支持。Codex CLI 会依赖 /v1/models?client_version=... 获取更丰富的模型目录，也会通过 Responses API 的 streaming 事件、function_call、function_call_output、多轮工具调用来完成本地文件读取、搜索、编辑、长进程交互等任务。

在实际接入时发现，如果上游模型没有稳定输出结构化 tool call，Codex 容易出现以下问题：

• 对本地文件操作只给文字说明，不真正调用工具；
• 读文件、搜索、简单编辑等场景被模型误判或漏调工具；
• apply_patch 失败后可能重复同一个失败 patch；
• streaming Responses 事件顺序和 Codex 期望不完全一致；
• /v1/models?client_version=codex_cli_rs 缺少 Codex 需要的模型 catalog 字段。

主要改动

1. 增加 Codex 专用模型 catalog

• 保持普通 /v1/models 仍返回 OpenAI 兼容的 object=list 格式；
• 当请求带 client_version 参数时，返回 Codex CLI 需要的模型 catalog 字段，例如：
  • slug / display_name
  • base_instructions
  • apply_patch_tool_type
  • truncation_policy
  • context_window
  • supports_parallel_tool_calls

这样 Codex CLI 可以正常识别和选择 grok2api 暴露的模型。

2. 强化 Responses API 的工具调用兼容

• 对 Responses flat tool schema 做 Chat Completions function schema 归一化；
• 修复 streaming 下 function_call item / arguments delta / completed 的输出顺序；
• 在模型输出纯文本但明显应该调用工具时，增加 repair/synthesize 流程；
• 对 Codex 常见工具 exec_command、write_stdin、apply_patch 做更明确的提示约束；
• 避免工具调用结果已经返回后继续重复合成同一个命令。

3. 增加 Codex 本地文件操作兜底

新增 app/products/openai/_codex_tools.py，集中处理 Codex 相关兼容逻辑：

• 识别 pwd、列目录、桌面文件列表等基础本地操作；
• 识别读取文件请求，例如 读取 sample.txt 内容；
• 识别搜索请求，例如 搜索包含 alpha 的文件，合成为 rg -n -- alpha .；
• 识别简单创建文件请求，合成为 apply_patch；
• 识别简单替换编辑请求，例如 把 sample.txt 里的 alpha 改成 beta，合成为最小 apply_patch；
• 对明显直接写文件的 shell 命令做 apply_patch 重写；
• 抑制已完成 patch 的重复执行。

4. 改善 apply_patch 失败后的行为

• 如果前一次 patch 失败，会提示模型先检查目标文件，再生成修正后的最小 patch；
• 如果 patch 已经完成，会抑制重复 patch；
• 避免重复执行同一个失败或已经成功的编辑操作。

5. 增加测试覆盖

新增 tests/test_codex_tools.py，覆盖：

• write_stdin 参数合成；
• 简单创建文件到 apply_patch；
• 模型名不被误识别为文件名；
• echo/printf 写文件命令重写为 apply_patch；
• 已完成 patch 不重复执行；
• 桌面目录列表；
• 读文件请求；
• 搜索请求；
• 简单替换编辑请求；
• 工具提示注入后仍能正确提取用户目标文件。

本地验证

已执行：

uv run python -m unittest tests.test_codex_tools -v

结果：

Ran 11 tests in 0.003s
OK

另外用 Codex CLI 通过 grok2api 做了端到端验证，覆盖本地文件读取、搜索和编辑：

• 读取 sample.txt 内容并告诉我 -> 正确执行 sed -n '1,200p' sample.txt；
• 搜索当前目录下包含 alpha 的文件 -> 正确执行 rg -n -- alpha .；
• 把 sample.txt 里的 alpha 改成 beta -> 正确触发文件更新，最终文件内容从 alpha 变成 beta。

兼容性说明

• 普通 OpenAI /v1/models 返回格式保持不变；
• Codex catalog 只在请求带 client_version 时启用；
• Codex 工具兜底逻辑只在可用工具包含 exec_command / write_stdin / apply_patch 等 Codex 风格工具时触发；
• 没有引入新的运行时依赖。

[mariotong]

[CNBxy]

只能在codex中使用吗，接到hermes里貌似不起效果

[susiemiles443]

我安装了后再codex cli里面用也没效果，写入不了文件。

[TatsuyaGit]

我发现只有 grok-4.20-0309-super可以读到目录
grok-4.3 会一直提示「目前 sandbox 环境无法存取该专案」，但我是MAC环境也根本没有sandbox