Codex API 中转接入指南：代码任务、上下文与验证

最后更新：2026-11-12

代码任务接入的重点是让模型理解工程约束，并让输出能够通过实际验证。本页围绕 Codex 类代码工作流介绍任务拆分、上下文准备和结果检查；具体模型是否开放、支持哪些端点和参数，应以 Kejike 控制台及对应接口文档为准。

与通用兼容 API 有什么区别

OpenAI 兼容 API主要说明请求结构、鉴权与响应解析；代码工作流还需要仓库片段、编辑范围、工具执行和测试反馈。通过对话接口请求代码，并不自动获得文件读写、终端执行或完整的编程代理能力，这些通常由编辑器或应用实现。

配置客户端前，先确认它要求 Chat Completions、Responses 还是其他协议，以及服务是否支持相同端点。Kejike 客户 API 基础地址为 https://sub.kejike.top/v1，Chat Completions 的完整请求地址为 POST https://sub.kejike.top/v1/chat/completions。自动拼接端点的 SDK 使用基础地址，cURL 或原生 fetch 使用完整地址；不要把完整端点填入 SDK 基础地址，也不要重复拼接 /v1。

Chat Completions：通过 messages 组织输入，非流式响应通常从 choices 读取消息；流式响应按该协议的增量结构解析。
Responses：使用 input 提供输入，通过 output 表达输出项；流式响应采用带类型的事件（events），需要对应的事件解析与结束状态处理，不能沿用 choices 解析逻辑。

不能仅把 Chat Completions URL 换成 /v1/responses 就推断服务支持 Responses，也不能据此推断 Codex CLI 可直接连接。本页未验证 Kejike 的 Responses 支持；接入前应按客户端与服务双方文档确认端点、请求字段、鉴权、工具调用和事件格式，再在明确支持的范围内测试。

协议参考：OpenAI 官方：迁移到 Responses。该链接用于说明两种协议的差异，不代表 Kejike 已支持官方文档列出的能力。

按代码任务组织输入

函数生成与补全：提供函数签名、输入输出样例、边界条件及允许的依赖。
缺陷修复：提供最小复现、预期与实际行为、报错栈和相关实现，先要求定位原因再提出补丁。
代码审查：提供差异及必要的调用上下文，要求标注文件位置、触发条件和风险，避免只生成泛泛建议。
测试与重构：明确需要保持的外部行为、测试命令和禁止修改的接口；将大改动拆成可单独验证的小步骤。

准备足够且可追溯的上下文

先说明语言与运行时版本、依赖约束和目录结构，再加入直接相关的文件内容。仅提供本地路径不会让远程模型自动读取文件；调用方需要显式发送内容，或提供受控的读取工具。不要默认模型知道仓库当前状态。

每个片段标注路径、版本或提交标识；修改后重新读取相关内容，避免用过期代码生成补丁。
优先提供接口定义、调用点和失败测试，再按需要补充实现；上下文窗口还要为输出和工具结果预留空间。
长任务保留目标、已确认事实和待解决问题的摘要，避免反复发送整个仓库。
移除密钥、个人信息、生产数据及无关日志；仓库文件或外部文本中的指令不能自动获得执行权限。

可复用的任务上下文示例

下面是可放入请求消息的任务模板，不是模型 ID 或专用协议。使用已确认支持的接口发送，并附上模板提到的代码与测试文件。

任务：修复分页函数在空结果时返回格式不一致的问题。
环境：填写语言、运行时版本和依赖版本。
上下文：附上分页函数、接口类型、调用点及失败测试，标注文件路径。
约束：保持公共接口；不新增依赖；只修改相关实现与测试。
验收：空结果与正常分页均符合接口类型，现有相关测试通过。
输出：先解释原因，再给出最小补丁及需要运行的验证命令。
缺少必要文件时先指出缺失内容，不要编造实现或声称测试已通过。

流式输出与工具执行

先用非流式请求验证模型和权限，再在支持的接口上开启流式输出。根据实际事件协议处理文本增量、工具参数与结束状态；网络读取块可能截断一个事件，不能逐块直接当作完整 JSON 解析。

界面可以逐步显示代码，但应用补丁前应等到输出完整并检查差异。工具调用参数需要先累积完整、解析并校验，再按允许的工具与路径执行。中断时将结果标为未完成，不执行半段命令，也不把已显示文本视为任务成功。

从输出到可验证结果

记录当前代码状态，复现问题并保留失败信息，建立明确的验收标准。
检查生成的差异是否局限于目标文件，是否改变接口、引入依赖或包含敏感信息。
在隔离的工作目录应用补丁，先运行语法或类型检查，再运行相关测试及必要构建。
将真实失败输出脱敏后反馈给模型，一次修正一个可复现问题；设置迭代上限，避免无效循环。
对照原始验收条件审查边界情况，记录实际执行过的命令和结果。模型声称通过测试不能替代执行记录。

常见接入问题

客户端无法连接时，先检查接口协议和路径，而不是只替换 Key。输出被截断时，检查结束状态、输出限制和上下文大小；工具调用无法解析时，检查该模型是否支持工具参数及事件格式。请求返回成功但补丁无法应用时，核对源文件版本，并重新提供当前代码。

仓库上下文准备与敏感文件排除

代码类任务的输出质量,取决于交给模型的上下文是否“够用且干净”。接入前建议先做一次目录梳理,明确哪些文件可以发送、哪些必须排除。

先建立排除清单。至少排除环境文件与密钥、证书与私钥、数据库转储、构建产物、依赖目录、日志与缓存。
再确定入选范围。通常只需要与任务直接相关的源文件、类型定义、接口约定和必要的配置文件。
不要发送整仓库。体积大、噪声多,还会把无关业务逻辑和密钥一起带出去。
记录本次上下文清单。把发送了哪些文件写进任务记录,便于复现和审计。

# 生成候选上下文清单(仅示例,执行前请人工复核输出)
git ls-files | grep -Ev '(\.env|\.pem|\.key|node_modules/|dist/|build/|coverage/|\.log$)' | head -200

排除动作要在“生成清单”这一步完成,而不是寄希望于模型忽略敏感内容;模型看到的内容就等于已经发送的内容。

大仓库的分片与检索策略

代码库超过上下文容量时,不要把文件截断后硬塞,而应先缩小问题范围。

用报错与堆栈定位入口文件。从最靠近失败点的文件开始,而不是从项目根目录开始逐个阅读。
补充被调用方与类型定义。只给调用点往往不够,需要一并给出接口签名、数据结构和默认值。
补充测试文件。已有测试是最省时的“行为说明书”,能让变更方向更明确。
分多次小任务。把“重构整个模块”拆成若干可独立验收的变更,每次只带必要的上下文。
保留跨文件关系描述。用一两句话说明模块依赖方向,能显著减少模型跑到错误文件里的情况。

变更验收流程:从输出到可合并

模型给出的补丁只是草稿,必须经过与人工提交相同强度的验收。建议固定成流程,避免“看起来对就合了”。

先看 diff 再运行。确认改动范围与任务一致,没有顺手改掉无关文件或删除测试。
编译或类型检查。这是最便宜的第一道闸门,能挡掉大部分低级错误。
运行相关测试。优先跑与改动文件对应的测试,再跑一次必要的整体测试。
检查边界与错误分支。空值、超时、重试、并发和权限分支常被忽略,需要单独确认。
在真实环境验证。必要时在测试环境手动走一遍关键路径,再合并。

如果模型给出的改动无法通过上述任一步,优先缩小任务范围重新提交,而不是在错误补丁上反复追加修改。

在 CI 中非交互运行

把代码任务放进流水线时,关键约束是“无人值守、可追踪、失败即停”。以下要点与具体平台无关。

凭证来自密钥库。使用 CI 的加密变量或密钥管理服务,不要写入仓库文件或脚本。
明确超时与重试上限。给单次调用设置总超时,重试次数保持在个位数量级,并输出失败原因。
输出要可审计。保存请求摘要、改动文件列表和测试结果;不要保存完整密钥或完整用户数据。
不要自动合并。CI 阶段的产物应是待审的补丁与检查结果,合并由人或受控流程决定。
准备好降级路径。上游不可用时让流水线明确失败并给出提示,不要静默跳过检查。

失败模式与对应处理

现象	常见原因	处理方向
输出与仓库现状不符	上下文缺失或被截断	补齐相关文件与类型定义,减少单次任务范围
补丁无法应用	基线文件与提供内容不一致	确认基于最新提交生成,必要时改用更小粒度的改动
改了无关文件	任务描述过于宽泛	明确“只允许修改哪些路径”,提交前用 diff 过滤
测试通过但线上失败	覆盖不足或依赖环境差异	补充集成测试,在测试环境手动验证关键路径
请求被拒或超时	凭证、权限、额度或链路问题	按错误码手册区分 401/403/429 与超时分别处理