最近在尝试将 Codex CLI 接入国产大模型 DeepSeek 时很多开发者都遇到了一个共同的难题官方推荐的 CC Switch 或 Codex 工具要么下载困难要么网络连接不稳定导致整个配置流程卡在第一步。如果你也正为此烦恼那么这篇文章就是为你准备的。本文将绕过这些依赖直接使用一个更稳定、更易获取的国产平替方案手把手带你完成 Codex 与 DeepSeek 的对接让你在无需良好网络环境的情况下也能顺畅地使用强大的 AI 编程助手。1. 背景与核心概念为什么需要桥接工具在深入实操之前我们有必要先理解 Codex、DeepSeek 以及桥接工具各自扮演的角色以及它们之间为何需要“翻译官”。1.1 Codex CLI专注于 OpenAI Responses API 的终端工具Codex CLI 是一个在终端中使用的 AI 编程助手。它最初设计为与 OpenAI 的特定 API 端点即Responses API进行通信。这个 API 协议定义了 Codex 发送请求和接收响应的数据格式。简单来说Codex CLI 只说一种“语言”——Responses API 协议。1.2 DeepSeek API遵循 OpenAI Chat Completions 标准DeepSeek 作为 OpenAI 的兼容者其对外开放的 API 接口遵循的是OpenAI Chat Completions标准。这是目前绝大多数第三方大模型如 Kimi、MiniMax 等普遍采用的一种通用协议。它与 OpenAI 的 Responses API 在请求体结构、流式事件格式和响应体形态上都有显著差异。你可以把它理解为另一种“语言”。1.3 协议不匹配直接连接的困境如果你尝试将 DeepSeek 的 API 地址如https://api.deepseek.com/v1/chat/completions直接配置到 Codex 中会发生什么Codex 会用它熟悉的 Responses API “语言”去请求一个只懂 Chat Completions “语言”的服务器。结果就是服务器完全听不懂这个请求通常会返回404 Not Found、400 Bad Request错误或者即使返回了数据Codex 也无法正确解析流式响应导致交互失败。1.4 桥接工具的作用协议转换器因此我们需要一个“协议转换器”或“路由代理”。它的核心工作流程如下监听在本地启动一个服务例如http://127.0.0.1:15721。接收与转换接收来自 Codex 的、基于 Responses API 的请求。转发将这个请求“翻译”成 Chat Completions 格式并转发给真正的上游服务如 DeepSeek。回传与转换接收上游的 Chat 格式响应再“翻译”回 Responses 格式返回给 Codex。这样Codex 以为自己一直在和“原生”的 OpenAI 服务对话而实际上背后是 DeepSeek 在提供算力。CC Switch 和 Codex 就是实现了这一功能的知名工具。但当这些工具本身难以获取时我们就需要寻找替代方案。2. 环境准备与工具选择我们的目标是在不依赖 CC Switch 或 Codex 的情况下实现相同的协议转换功能。这里我们选择使用一个轻量级、开源且易于部署的替代方案LocalAI 的lai-cli工具或者直接使用Python FastAPI 自建微型代理。本文将重点讲解第一种方案因为它更接近“开箱即用”。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (本文以 Windows 为例其他系统原理相通)。终端PowerShell (推荐) 或 CMD。网络能正常访问 DeepSeek 官方网站 (platform.deepseek.com) 以获取 API Key。已安装 Codex CLI确保你已经在终端中成功安装并运行过codex命令这会在你的用户目录下生成配置文件~/.codex/config.toml(Windows 通常在C:\Users\你的用户名\.codex\config.toml)。2.2 获取 DeepSeek API Key访问 DeepSeek 开放平台 (platform.deepseek.com)。注册并登录账号。在控制台中找到 “API Keys” 部分创建一个新的 API Key。妥善保存这个 Key我们后续会用到。注意API Key 是访问你账户权限的凭证切勿泄露。2.3 平替方案选择lai-cli vs 自建代理lai-cli (推荐)这是 LocalAI 项目提供的一个命令行工具核心功能之一就是充当各种 AI API 协议的网关和转换器。它预编译了可执行文件下载即用配置简单。自建 Python 代理灵活性极高可以完全自定义转换逻辑适合有 Python 开发经验的用户。我们将提供核心代码片段作为备选方案。3. 使用 lai-cli 搭建本地路由网关lai-cli可以模拟一个本地的 OpenAI API 兼容服务并将请求代理到真正的 DeepSeek API同时完成协议转换。3.1 下载与安装 lai-cli访问 LocalAI 的 GitHub Releases 页面。你可以通过搜索引擎查找 “localai lai-cli release”。根据你的操作系统下载对应的预编译二进制文件例如Windows 选择.exe结尾的文件。将下载的可执行文件放置在一个你喜欢的目录例如D:\Tools\lai-cli\。为了方便可以将该目录添加到系统的 PATH 环境变量中。3.2 配置 lai-cli 以代理 DeepSeeklai-cli通过一个 YAML 配置文件来定义后端模型和路由。创建一个名为deepseek-config.yaml的文件内容如下# deepseek-config.yaml models: - name: deepseek-chat # 本地暴露的模型名称Codex将使用这个名称 backend: openai parameters: model: deepseek-chat # 对应DeepSeek的模型名通常是这个 urls: - https://api.deepseek.com # DeepSeek的API基础地址 api_key: sk-your-deepseek-api-key-here # 替换为你的真实API Key # 启用并配置CORS允许本地应用访问 cors: enabled: true allowed_origins: - * # 服务器监听配置 server: host: 127.0.0.1 port: 8080 # 本地服务端口可以自定义避免冲突关键配置解释models[0].name: 这是你将在 Codex 配置中引用的模型名称。backend: openai: 告诉lai-cli使用 OpenAI 兼容的后端。urls: 指向 DeepSeek 的官方 API 地址。server.port: 本地服务端口后续 Codex 需要连接到这里。3.3 启动本地路由服务在终端中导航到存放deepseek-config.yaml的目录运行以下命令lai-cli server --config-file ./deepseek-config.yaml如果一切正常你将看到类似以下的输出表明服务已在http://127.0.0.1:8080启动INFO[0000] Starting server on 127.0.0.1:8080保持这个终端窗口打开服务需要一直运行才能处理请求。3.4 验证本地服务打开浏览器或使用curl命令测试本地服务是否正常工作curl http://127.0.0.1:8080/v1/models你应该能收到一个 JSON 响应其中包含你配置的deepseek-chat模型信息。这证明本地网关已经就绪并且能够与 DeepSeek 通信。4. 配置 Codex CLI 使用本地网关现在我们需要告诉 Codex让它把请求发送到我们刚搭建的本地网关而不是原始的 OpenAI 地址。4.1 定位并编辑 Codex 配置文件Codex 的配置文件通常位于~/.codex/config.toml。Windows:C:\Users\你的用户名\.codex\config.tomlmacOS/Linux:~/.codex/config.toml用文本编辑器如 VS Code、Notepad打开这个文件。4.2 修改配置文件关键项你需要修改或添加以下配置项。如果某些项不存在就新增它们。# ~/.codex/config.toml # 核心配置指定API类型为‘responses’并指向本地网关 wire_api responses api_base http://127.0.0.1:8080/v1 # 注意这里指向我们启动的lai-cli服务地址和端口 # 模型配置指定使用的模型名称与lai-cli配置中的model.name一致 default_model deepseek-chat # 可选设置API Key。 # 由于我们已经在lai-cli的配置中填入了真实的DeepSeek Key # 这里可以填写一个任意字符串如‘dummy-key’因为lai-cli会忽略它并使用自己的配置。 # 但有些配置要求此项非空。 api_key dummy-key # 可选禁用TLS验证仅当本地服务使用HTTP且你遇到证书问题时启用生产环境慎用 # insecure true重要说明api_base必须精确指向你的lai-cli服务地址并加上/v1路径因为 OpenAI 兼容 API 通常挂载在/v1下。default_model必须与deepseek-config.yaml中models[0].name的值完全一致。api_key在lai-cli方案中不是必须的因为真实在lai-cli配置里。但为防止 Codex 报错可以设一个占位符。4.3 重启 Codex 并测试保存config.toml文件。关闭所有正在运行的 Codex 终端会话。打开一个新的终端输入codex命令启动 Codex CLI。在 Codex 交互界面中你可以输入/model命令来查看当前使用的模型。它应该显示为deepseek-chat或你在配置中指定的名称。尝试提出一个简单的编程问题例如“用Python写一个Hello World程序”。如果配置成功你将收到来自 DeepSeek 模型的回答。5. 备选方案使用 Python FastAPI 自建微型代理如果你更喜欢完全掌控或者lai-cli在你的环境上有问题可以快速搭建一个 Python 代理。这个方案需要你本地安装有 Python 3.7 环境。5.1 创建项目目录与依赖创建一个新目录并在其中创建requirements.txt和proxy_server.py文件。# requirements.txt fastapi0.104.0 uvicorn0.24.0 httpx0.25.0 pydantic2.0.0安装依赖pip install -r requirements.txt5.2 编写代理服务器代码以下是proxy_server.py的核心代码它实现了简单的 Requests API 到 Chat Completions 的转换。# proxy_server.py import json from typing import Dict, Any, AsyncGenerator import httpx from fastapi import FastAPI, Request, HTTPException from fastapi.responses import StreamingResponse from pydantic import BaseModel import logging logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app FastAPI() # 配置你的 DeepSeek API 信息 DEEPSEEK_API_BASE https://api.deepseek.com DEEPSEEK_API_KEY sk-your-deepseek-api-key-here # 替换为你的真实API Key DEEPSEEK_MODEL deepseek-chat # DeepSeek模型名 # 转换函数将 Codex (Responses API) 的请求体转换为 DeepSeek (Chat Completions) 的格式 def transform_to_chat_completion(codex_body: Dict[str, Any]) - Dict[str, Any]: 一个简化的转换示例。 实际转换需要根据Codex Requests API和OpenAI Chat Completions API的文档进行更细致的映射。 这里处理了最核心的 messages 和 stream 参数。 chat_body { model: DEEPSEEK_MODEL, stream: codex_body.get(stream, False), } # 转换 messages。Codex的格式可能与Chat Completions略有不同这里做简单适配。 if messages in codex_body: # 假设格式兼容直接使用 chat_body[messages] codex_body[messages] elif prompt in codex_body: # 如果Codex发送的是单轮prompt包装成message chat_body[messages] [{role: user, content: codex_body[prompt]}] else: raise HTTPException(status_code400, detail无法识别的请求格式缺少messages或prompt) # 可选映射其他参数如 temperature, max_tokens 等 if temperature in codex_body: chat_body[temperature] codex_body[temperature] if max_tokens in codex_body: chat_body[max_tokens] codex_body[max_tokens] logger.info(f转换后的请求体: {json.dumps(chat_body, indent2)}) return chat_body # 转换函数将 DeepSeek 的流式/非流式响应转换回 Codex 期望的格式 async def transform_from_chat_completion(deepseek_response, is_streaming: bool): 转换响应格式。 这是一个复杂的过程因为流式SSE事件和非流式JSON的结构都不同。 此处提供一个极其简化的概念性示例生产环境需要完整实现。 # 非流式响应处理 if not is_streaming: data deepseek_response.json() # 简化直接返回一个类似结构的字典。实际需要严格映射。 return { id: data.get(id, ), object: chat.completion, created: data.get(created, 0), model: data.get(model, ), choices: data.get(choices, []), } else: # 流式响应处理需要逐行解析SSE并重新封装 # 此处省略详细实现仅示意 async for line in deepseek_response.aiter_lines(): if line.startswith(data: ): event_data line[6:] if event_data [DONE]: yield fdata: [DONE]\n\n else: try: data json.loads(event_data) # 转换 data 中的结构... transformed_event {choices: data.get(choices, [])} yield fdata: {json.dumps(transformed_event)}\n\n except json.JSONDecodeError: continue app.post(/v1/responses) # Codex 默认会请求 /v1/responses 或 /responses async def proxy_to_deepseek(request: Request): codex_body await request.json() stream codex_body.get(stream, False) # 1. 转换请求格式 chat_body transform_to_chat_completion(codex_body) # 2. 准备请求头 headers { Authorization: fBearer {DEEPSEEK_API_KEY}, Content-Type: application/json, } # 3. 转发请求到 DeepSeek async with httpx.AsyncClient(timeout30.0) as client: try: deepseek_response await client.post( f{DEEPSEEK_API_BASE}/chat/completions, jsonchat_body, headersheaders, timeout30.0, ) deepseek_response.raise_for_status() except httpx.HTTPStatusError as e: logger.error(fDeepSeek API 错误: {e.response.status_code} - {e.response.text}) raise HTTPException(status_codee.response.status_code, detaile.response.text) except Exception as e: logger.error(f请求DeepSeek失败: {e}) raise HTTPException(status_code500, detail上游服务请求失败) # 4. 转换并返回响应 if stream: return StreamingResponse( transform_from_chat_completion(deepseek_response, is_streamingTrue), media_typetext/event-stream, ) else: transformed_data await transform_from_chat_completion(deepseek_response, is_streamingFalse) return transformed_data app.get(/v1/models) async def list_models(): 返回模型列表Codex 可能会调用此端点 return { object: list, data: [ { id: DEEPSEEK_MODEL, object: model, created: 1677610602, owned_by: deepseek, } ] } if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8080) # 确保端口与Codex配置一致5.3 运行自建代理并配置 Codex在终端中运行你的代理服务器python proxy_server.py按照第4章的步骤配置 Codex 的config.toml将api_base指向http://127.0.0.1:8080/v1。重启 Codex 进行测试。注意这个自建代理是一个高度简化的示例主要用于演示原理。真实的协议转换要复杂得多涉及完整的请求/响应字段映射、错误处理、流式事件解析等。对于生产使用建议基于更成熟的项目如lai-cli或 CC Switch 的开源代码进行定制。6. 常见问题与排查思路在配置过程中你可能会遇到以下问题。这里提供系统的排查方法。问题现象可能原因排查步骤与解决方案启动lai-cli或 Python 代理失败端口被占用依赖未安装配置文件错误。1. 检查端口8080是否被其他程序占用 (netstat -ano | findstr :8080)。2. 换用其他端口如8081并同步更新 Codex 配置。3. 检查deepseek-config.yaml或 Python 代码的语法缩进、冒号等。4. 对于 Python确保已安装所有依赖 (pip install)。Codex 报错404 Not FoundCodex 配置的api_base地址错误本地代理服务未运行请求路径不匹配。1. 确认本地代理服务正在运行 (curl http://127.0.0.1:8080/v1/models)。2. 检查config.toml中api_base是否精确指向代理地址含/v1。3. 确认代理服务器是否正确处理了/v1/responses或/responses端点。Codex 报错401 Unauthorized或403 ForbiddenDeepSeek API Key 无效或未正确传递。1. 在lai-cli配置或 Python 代码中确认 API Key 填写正确且未过期。2. 尝试在终端直接用curl和该 Key 调用 DeepSeek 官方 API验证 Key 有效性。3. 检查代理服务器的请求头中Authorization字段是否正确生成。Codex 能连接但返回乱码或解析错误响应格式转换失败。代理没有正确将 Chat Completions 响应转回 Responses 格式。1. 查看代理服务器的日志检查它从 DeepSeek 收到的原始响应是什么。2. 对比 DeepSeek 官方文档的响应示例和 Codex 期望的 Responses API 格式。3. 这是最复杂的问题可能需要深入调试转换逻辑。使用lai-cli等成熟工具可极大避免此类问题。/model命令不显示配置的模型Codex 未正确加载模型列表代理的/v1/models端点返回格式不对。1. 重启 Codex 终端会话。2. 直接访问http://127.0.0.1:8080/v1/models看返回的 JSON 是否符合 OpenAI 模型列表格式。3. 检查config.toml中default_model名称是否与代理返回的模型id一致。请求超时或无响应网络问题DeepSeek 服务暂时不可用代理处理缓慢。1. 检查本地网络是否能访问api.deepseek.com。2. 查看代理服务器日志看请求是否已转发以及 DeepSeek 是否返回。3. 尝试在代理配置或代码中增加超时时间。7. 最佳实践与工程建议成功对接只是第一步要在开发中稳定、高效地使用这套方案还需要遵循一些最佳实践。7.1 配置管理分离配置与代码切勿将 API Key 等敏感信息硬编码在脚本或配置文件中并提交到版本控制系统如 Git。使用环境变量来管理敏感信息。对于lai-cli可以在 YAML 配置中使用环境变量占位符如果支持或者使用脚本在启动前注入环境变量。对于 Python 代理使用os.getenv(DEEPSEEK_API_KEY)从环境变量读取。# 在启动前设置环境变量 (Linux/macOS) export DEEPSEEK_API_KEYsk-your-real-key lai-cli server --config-file ./config.yaml # Windows (PowerShell) $env:DEEPSEEK_API_KEYsk-your-real-key .\lai-cli.exe server --config-file .\config.yaml版本化配置文件将不包含敏感信息的配置文件如deepseek-config.yaml的模板、Python 代理的代码纳入版本控制便于团队共享和回滚。7.2 服务可靠性进程守护对于长期使用的代理服务不要仅仅在终端前台运行。考虑使用系统服务如 systemd, launchd或进程管理工具如 pm2, Supervisor来守护进程实现开机自启、崩溃重启。日志记录确保代理服务开启了足够的日志级别INFO/DEBUG并将日志输出到文件便于后期排查问题。定期检查日志文件大小避免磁盘占满。健康检查可以为一个简单的健康检查端点如/health返回服务状态方便使用监控工具。7.3 安全边界最小化网络暴露本地代理服务 (127.0.0.1) 只绑定在本地回环地址切勿绑定在0.0.0.0或公网 IP 上除非你完全理解并需要远程访问且配置了额外的认证和防火墙规则。权限控制运行代理服务的系统账户应具有最小必要权限。不要使用 root 或 Administrator 账户运行。API Key 轮转定期在 DeepSeek 平台轮换 API Key并在代理服务中更新。避免一个 Key 长期使用带来的潜在风险。7.4 性能与可维护性连接池如果你的自建代理并发请求量较大确保 HTTP 客户端如 Python 的httpx.AsyncClient使用了连接池避免频繁建立 TCP 连接的开销。错误重试在网络不稳定或上游服务偶发错误时可以在代理层实现简单的重试机制注意对非幂等操作要谨慎。代码清晰如果选择自建代理确保转换逻辑清晰并添加充分的注释。因为 OpenAI 和 DeepSeek 的 API 都可能更新清晰的代码有助于未来适配。7.5 故障预案备用方案了解当本地代理或 DeepSeek 服务不可用时如何快速切换回其他可用的 AI 服务或离线模式。配置回滚保留一份 Codex 原始可用的配置文件备份以便在代理方案出现问题时能快速恢复。通过本文的详解你不仅掌握了在无法使用 CC Switch 或 Codex 时通过lai-cli或自建代理将 Codex 接入 DeepSeek 的完整流程更深入理解了其背后的协议转换原理。从环境准备、工具下载、配置详解到实战部署和深度排错我们一步步拆解了所有关键环节。这种“自建网关”的思路具有普适性同样适用于将 Codex 接入其他遵循 OpenAI Chat Completions 标准的国产或国际大模型。