Codex CLI DeepSeek 配置完整教程

通过 ccx（Codex CLI Exchange）本地代理，让 Codex CLI 使用 DeepSeek 模型进行 AI 编程。

文章说明

本教程介绍如何在 Windows 上配置 Codex CLI 通过 ccx 本地代理使用 DeepSeek 模型，实现低成本、高质量的 AI 辅助编程。

测试环境：

Windows 10/11Codex CLI v0.133.0ccx v2.7.19DeepSeek API（deepseek-chat / deepseek-reasoner）一、什么是 ccx？

ccx（Codex CLI Exchange）是一个轻量级的本地 API 代理服务器，它可以将 Codex CLI 的请求转发到任意 OpenAI 兼容的 API，包括 DeepSeek。

核心功能：

多上游（upstream）管理，支持 messages、responses、gemini 三种通道API Key 管理与自动故障切换本地 Web 管理界面（http://localhost:3000）请求指标监控与熔断保护二、前提准备2.1 获取 DeepSeek API Key访问 DeepSeek 开放平台注册/登录账号进入 API Keys 页面点击「创建 API Key」，复制保存（格式：sk-xxxxxxxx）2.2 安装 Codex CLI

npm install -g @openai/codex

验证安装：

codex --version# 输出: codex-cli 0.133.02.3 安装 ccx

从 ccx Releases 下载 Windows 版本（ccx-windows-amd64.exe），放到一个独立目录，例如：

C:UsersDesktopcodexccx三、配置 ccx3.1 创建环境变量文件

在 ccx 目录下创建 .env 文件：

PORT=3000ENABLE_WEB_UI=truePROXY_ACCESS_KEY=861018dszADMIN_ACCESS_KEY=861018dszAPP_UI_LANGUAGE=enLOG_LEVEL=info

⚠️ 请将 PROXY_ACCESS_KEY 和 ADMIN_ACCESS_KEY 改为你自己的密钥。

3.2 配置文件

在 .config/config.json 中配置 DeepSeek 上游：

{ "upstream": [ { "baseUrl": "https://api.deepseek.com", "apiKeys": ["sk-你的DeepSeek密钥"], "serviceType": "openai", "name": "deepseek", "reasoningParamStyle": "reasoning", "normalizeNonstandardChatRoles": true, "codexToolCompat": false, "priority": 0, "status": "active", "autoBlacklistBalance": true, "normalizeMetadataUserId": true } ], "responsesUpstream": [ { "baseUrl": "https://api.deepseek.com", "apiKeys": ["sk-你的DeepSeek密钥"], "serviceType": "openai", "name": "deepseek", "reasoningParamStyle": "reasoning", "normalizeNonstandardChatRoles": true, "codexToolCompat": false, "priority": 0, "status": "active", "autoBlacklistBalance": true, "normalizeMetadataUserId": true } ], "geminiUpstream": [], "fuzzyModeEnabled": true, "stripBillingHeader": true}

重要： upstream（messages 通道）和 responsesUpstream（responses 通道）都需要配置，Codex CLI 主要使用这两个端点。

3.3 启动 ccx

cd C:UsersDesktopcodexccx./ccx-windows-amd64.exe

看到以下输出表示启动成功：

[Server-Startup] CCX API代理服务器已启动[Server-Info] 管理界面: http://localhost:3000[Server-Info] API 地址: http://localhost:3000/v1

验证健康状态：

curl http://localhost:3000/health# {"config":{"upstreamCount":1},"status":"healthy",...}四、配置 Codex CLI4.1 认证配置

编辑 ~/.codex/auth.json：

{ "OPENAI_API_KEY": "861018dsz", "auth_mode": "apikey"}

⚠️ auth_mode 必须设为 "apikey"（不是 "api_key"），否则 Codex 会尝试使用 OAuth 登录流程，导致认证失败。

4.2 模型提供商配置

编辑 ~/.codex/config.toml：

model_provider = "ccx"model = "deepseek-chat"[model_providers.ccx]name = "OpenAI"base_url = "http://localhost:3000/v1"wire_api = "responses"requires_openai_auth = true[windows]sandbox = "unelevated"

配置说明：

参数

值

说明

model_provider

ccx

使用名为 ccx 的提供商

model

deepseek-chat

DeepSeek-V3 对话模型（也可用 deepseek-reasoner）

base_url

http://localhost:3000/v1

ccx 代理地址

wire_api

responses

使用 Responses API 协议

requires_openai_auth

true

发送 Authorization: Bearer 认证头

4.3 可用模型

通过 ccx 代理查询可用模型：

curl -H "Authorization: Bearer *** http://localhost:3000/v1/models

常用 DeepSeek 模型：

模型 ID

说明

deepseek-chat

DeepSeek-V3，通用对话

deepseek-reasoner

DeepSeek-R1，深度推理

五、测试验证5.1 测试 ccx 代理

curl -X POST http://localhost:3000/v1/responses -H "Content-Type: application/json" -H "Authorization: Bearer *** -d '{"model":"deepseek-chat","input":"say hello","max_output_tokens":30}'

预期返回 DeepSeek 的回复。

5.2 测试 Codex CLI

⚠️ 重要： Codex 的交互式对话模式（直接运行 codex 回车）强制使用 OpenAI OAuth 登录，无法通过 ccx 代理。请使用 codex exec 单次执行模式。

codex exec "创建一个 hello.txt 文件，内容是 hello from deepseek" --sandbox workspace-write

预期输出：

已创建 `hello.txt`，内容为 `hello from deepseek`。tokens used: ~2005.3 日常使用

日常编码中，直接通过 codex exec 发送任务即可：

# 简单问题codex exec "解释这个函数的作用" --sandbox workspace-write# 代码修改codex exec "把 config 模块重构为 async/await" --sandbox workspace-write# 多步骤任务codex exec "创建 REST API 接口：GET /users 和 POST /users" --sandbox workspace-write

--sandbox workspace-write 允许 Codex 在工作目录下读写文件。如不需要文件操作，可省略此参数。

六、常见问题排查Q1: 提示 "No Chat upstream configured"

原因： ccx 的 upstream 数组为空。

解决： 确认 config.json 中 upstream 字段已配置 DeepSeek，且 status 为 "active"。

Q2: 提示 "Invalid proxy access key"

原因： Codex 发送的认证密钥与 ccx 的 PROXY_ACCESS_KEY 不匹配。

排查步骤：

确认 ~/.codex/auth.json 中 auth_mode 为 "apikey"确认 OPENAI_API_KEY 与 ccx 的 PROXY_ACCESS_KEY 一致确认 ~/.codex/config.toml 中 requires_openai_auth = trueQ3: 提示 "All upstream channels are currently unavailable"

原因： ccx 通道处于 suspended 状态（通常是 API Key 被 DeepSeek 拒绝后触发熔断）。

解决：

# 恢复 messages 通道curl -X POST http://localhost:3000/api/messages/channels/0/resume -H "Authorization: Bearer "# 恢复 responses 通道curl -X POST http://localhost:3000/api/responses/channels/0/resume -H "Authorization: Bearer "Q4: Codex 报 "Authentication Fails, Your api key is invalid"

原因： DeepSeek API Key 无效或已过期。

解决：

登录 DeepSeek 开放平台 检查 Key 状态更新 ccx 配置中的 API Key：

curl -X POST http://localhost:3000/api/responses/channels/0/keys -H "Content-Type: application/json" -H "Authorization: Bearer " -d '{"apiKey": "sk-你的新Key"}'Q5: Codex 交互模式报 OAuth 错误 / 认证失败

现象：

codex（交互式对话）提示 "Your access token could not be refreshed"或持续报 "Invalid proxy access key"但 codex exec 可以正常工作

原因： Codex CLI 的交互式对话模式（直接运行 codex 回车进入的对话界面）强制使用 OpenAI OAuth 登录流程，会连接 OpenAI 服务器验证身份，无法通过 ccx 代理认证。

解决： 使用 codex exec 单次执行模式代替交互模式，功能完全一致：

# 代替交互对话codex exec "你的问题或任务" --sandbox workspace-write

ℹ️ 这是 Codex CLI 本身的架构限制，截至 v0.133.0 版本尚无官方参数可以绕过交互模式的 OAuth 要求。

七、架构总览

┌─────────────┐ Authorization: Bearer ┌──────────┐ Authorization: Bearer ┌──────────────┐│ │ ──────────────────────────────────────────▶│ │ ──────────────────────────────────────────▶│ ││ Codex CLI │ │ ccx │ │ DeepSeek ││ (客户端) │◀────────────────────────────────────────── │ (代理) │◀────────────────────────────────────────── │ API ││ │ JSON Response │ │ JSON Response │ │└─────────────┘ └──────────┘ └──────────────┘ │ │ │ config.toml │ config.json │ - model: deepseek-chat │ - upstream (messages) │ - base_url: http://localhost:3000/v1 │ - responsesUpstream │ - wire_api: responses │ - proxy_access_key │ │ ▼ ▼ ~/.codex/auth.json .env - OPENAI_API_KEY - PROXY_ACCESS_KEY - auth_mode: apikey - ADMIN_ACCESS_KEY八、扩展：使用推理模型

如需使用 DeepSeek-R1（深度推理），修改 ~/.codex/config.toml：

model = "deepseek-reasoner"

R1 模型会在回答前进行深度思考，适合复杂算法、架构设计等场景，但耗时和 Token 消耗更高。

参考链接ccx GitHubCodex CLI 文档DeepSeek 开放平台DeepSeek API 文档