codex-bridge 零基础配置指南

本文通过 codex-bridge 让 Codex CLI 连接 DeepSeek、小米 MiMo 等国内大模型。

一、这是什么？为什么要用？

1.1 问题

OpenAI Codex CLI 是一个终端里的 AI 编程助手，它默认只能连接 OpenAI 的模型（如 GPT 系列）。但很多人想用国内的模型，比如：

  • DeepSeek（深度求索）— 性价比极高，推理能力强
  • 小米 MiMo — 小米自研大模型

这些模型用的是 Chat Completions 协议，而 Codex CLI 用的是 OpenAI 的 Responses API 协议，两者不兼容。

1.2 解决方案

codex-bridge 是一个本地代理程序（就像一个"翻译官"），它：

  1. 接收 Codex CLI 发出的请求
  2. 自动翻译成 DeepSeek / MiMo 能理解的格式
  3. 把模型的回复翻译回 Codex CLI 能理解的格式
你的电脑内部：

┌──────────┐         ┌──────────────┐         ┌────────────┐
│ Codex    │  请求   │ codex-bridge │  请求   │  DeepSeek  │
│  CLI     │ ──────▶ │  (翻译官)     │ ──────▶ │  / MiMo    │
│          │ ◀────── │   :4000      │ ◀────── │  服务器     │
└──────────┘  回复   └──────────────┘  回复   └────────────┘

所有东西都在你的电脑本地运行，数据不经过任何第三方。

二、工作原理

简单理解：

角色 做什么
Codex CLI 你用的 AI 编程工具，发请求给 codex-bridge
codex-bridge 本地代理，翻译协议，转发请求
DeepSeek / MiMo 实际回答你问题的大模型

codex-bridge 默认在 localhost:4000 端口运行，不对外网开放。

三、准备工作

3.1 安装 Node.js

codex-bridge 需要 Node.js 18 或更高版本。

检查是否已安装： 打开终端（Windows 用户打开 PowerShell），输入：

node --version

在这里插入图片描述

如果显示 v18.x.x 或更高版本（如 v20、v24），跳过下面的安装步骤。

如果没有安装：

  1. 打开 https://nodejs.org/
  2. 下载 LTS（长期支持版）安装包
  3. 双击安装，一路点"下一步"即可
  4. 安装完成后重新打开终端，再执行 node --version 确认

3.2 安装 Git

检查是否已安装：

git --version

如果没有安装：

  1. 打开 https://git-scm.com/
  2. 下载对应系统的安装包
  3. 安装完成后重新打开终端确认

3.3 安装 Codex CLI

如果你还没装 Codex CLI：

npm install -g @openai/codex

安装完成后确认：

codex --version

3.4 获取模型 API Key

你需要至少一个模型的 API Key：

模型 获取地址 Key 格式
DeepSeek https://platform.deepseek.com sk- 开头
小米 MiMo https://platform.xiaomimimo.com/#/console/api-keys sk- 开头

注册账号后，在对应平台的「API Keys」页面创建一个新 Key，复制保存好。

注意： API Key 只显示一次，创建后请立即复制保存。如果丢失，需要重新创建。

四、方案一：连接 DeepSeek（推荐新手）

这是最简单的配置方式，只需 5 步。

4.1 第 1 步：下载 codex-bridge

打开终端，执行：

git clone https://github.com/wujfeng712-ui/codex-bridge.git
cd codex-bridge

4.2 第 2 步：创建配置文件

cp env.example .env

4.3 第 3 步：编辑配置文件

用任意文本编辑器打开 .env 文件（推荐 VS Code）：

code .env    # 如果你装了 VS Code

或者用记事本：

notepad .env

找到以下两行，填入你的信息：

# 第一行：生成一个代理密钥（随便写一串字符也行，用于 Codex 连接代理）
PROXY_AUTH_KEY=sk-proxy-local-这里换成任意48位字符

# 第二行：填入你的 DeepSeek API Key
DEEPSEEK_API_KEY=sk-你的DeepSeek密钥

生成代理密钥的简单方法： 在终端执行以下命令，把输出结果粘贴到 PROXY_AUTH_KEY= 后面：

node -e "console.log('sk-proxy-local-' + require('crypto').randomBytes(24).toString('hex'))"

最终 .env 文件看起来像这样：

PROXY_AUTH_KEY=sk-proxy-local-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
DEEPSEEK_API_KEY=sk-79cda1a50053488b812c9a6f816ae148

PROXY_PORT=4000
LOG_LEVEL=info
MODEL_CATALOG_PATH=./proxy-models.json

保存文件。

4.4 第 4 步：启动 codex-bridge

在终端中（确保当前目录是 codex-bridge），执行：

node --env-file=.env proxy.mjs

如果看到类似以下输出，说明启动成功：

[codex-bridge] Listening on http://localhost:4000
[codex-bridge] Default provider: deepseek
[codex-bridge] Deepseek: https://api.deepseek.com/v1 | models=deepseek-v4-pro, deepseek-v4-flash

重要：这个终端窗口不要关闭！ 关闭后代理就停止了。

在这里插入图片描述

4.5 第 5 步：配置 Codex CLI

方法 A：手动编辑配置文件

编辑 ~/.codex/config.toml（Windows 路径：C:\Users\你的用户名\.codex\config.toml）：

model = "deepseek-v4-flash"
model_provider = "local_proxy"

[model_providers.local_proxy]
name = "local_proxy"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
requires_openai_auth = true

编辑 ~/.codex/auth.json（Windows 路径：C:\Users\你的用户名\.codex\auth.json）：

{
  "OPENAI_API_KEY": "sk-proxy-local-你生成的代理密钥"
}

注意： auth.json 里的 OPENAI_API_KEY 填的是 .env 中的 PROXY_AUTH_KEY，不是 DeepSeek 的 Key！

方法 B：使用 CC Switch（推荐，见下方配合 CC Switch 使用）

在这里插入图片描述

4.6 验证

打开一个新的终端窗口，运行：

codex

你应该能看到 Codex CLI 界面，模型显示为 deepseek-v4-flash。试着问它一个问题，比如"你是什么模型"，如果能正常回答，说明配置成功！

在这里插入图片描述

五、方案二：连接小米 MiMo

步骤和 DeepSeek 基本一样，只需修改 .env 文件：

PROXY_AUTH_KEY=sk-proxy-local-你的代理密钥
MIMO_API_KEY=sk-你的MiMo密钥

PROXY_PORT=4000
LOG_LEVEL=info
MODEL_CATALOG_PATH=./proxy-models.json

注意： MiMo 的模型 ID 必须全部小写，如 mimo-v2.5-pro。

在 config.toml 中把模型名改为：

model = "mimo-v2.5-pro"

可用的 MiMo 模型：

模型 ID 说明
mimo-v2.5-pro MiMo v2.5 Pro（推荐）
mimo-v2.5 MiMo v2.5

六、方案三：同时连接多个模型

如果你想同时使用 DeepSeek 和 MiMo，可以都配置上。

6.1 .env 文件配置

PROXY_AUTH_KEY=sk-proxy-local-你的代理密钥

# DeepSeek
DEEPSEEK_API_KEY=sk-你的DeepSeek密钥

# MiMo
MIMO_API_KEY=sk-你的MiMo密钥

PROXY_PORT=4000
LOG_LEVEL=info
MODEL_CATALOG_PATH=./proxy-models.json

6.2 切换模型

在 Codex CLI 运行时，输入 /model 可以切换模型。

或者修改 config.toml 中的 model 字段：

# 切换到 DeepSeek
model = "deepseek-v4-pro"

# 或切换到 MiMo
model = "mimo-v2.5-pro"

6.3 可用模型列表

模型 ID 供应商 说明
deepseek-v4-pro DeepSeek DeepSeek V4 Pro，推理能力最强
deepseek-v4-flash DeepSeek DeepSeek V4 Flash，速度更快
mimo-v2.5-pro 小米 MiMo v2.5 Pro
mimo-v2.5 小米 MiMo v2.5

七、配合 CC Switch 使用（图形界面管理）

CC Switch 是一个桌面应用，可以通过图形界面管理 AI 模型配置，不用手动编辑配置文件。

7.1 安装 CC Switch

前往 https://github.com/farion1231/cc-switch 下载安装。

7.2 配置步骤

  1. 打开 CC Switch
  2. 点击 Codex 选项卡
  3. 点击 添加供应商
  4. 填写以下信息：
字段 填什么
名称 codex-bridge（或任意你喜欢的名字）
API Key .env 文件中的 PROXY_AUTH_KEY（如 sk-proxy-local-a1b2c3...）
Base URL http://127.0.0.1:4000/v1
  1. 点击 启用

CC Switch 会自动帮你写入 ~/.codex/auth.json 和 config.toml，不需要手动编辑。

7.3 多供应商切换

如果你想用不同密钥分别路由到 DeepSeek 和 MiMo，可以在 .env 中使用 PROXY_KEYS：

PROXY_KEYS=sk-deepseek-key:deepseek,sk-mimo-key:mimo,sk-all-key:*

格式说明：密钥:供应商名，多个用逗号分隔。* 表示可以访问任意供应商。

然后在 CC Switch 中为每个密钥创建独立配置，切换配置就等于切换上游模型。

八、常用操作

8.1 启动 codex-bridge

cd codex-bridge
node --env-file=.env proxy.mjs

8.2 后台运行（Linux / macOS）

nohup node --env-file=.env proxy.mjs > /tmp/codex-bridge.log 2>&1 &

8.3 后台运行（Windows PowerShell）

Start-Process -NoNewWindow -FilePath "node" -ArgumentList "--env-file=.env","proxy.mjs" -RedirectStandardOutput "codex-bridge.log"

8.4 运行冒烟测试

验证代理是否正常工作：

./scripts/smoke.sh

8.5 查看代理日志

代理运行时会在终端输出请求日志。如果需要更详细的日志，在 .env 中设置：

LOG_LEVEL=debug

8.6 停止代理

在运行代理的终端按 Ctrl + C 即可停止。

九、常见问题排查

9.1 EADDRINUSE :4000 — 端口被占用

原因： 4000 端口已被其他程序使用（可能是上次的 codex-bridge 没关掉）。

解决方法：

# Windows PowerShell
netstat -ano | findstr :4000
# 找到 PID 后
taskkill /PID <PID> /F

# 或者换一个端口，在 .env 中修改：
PROXY_PORT=4001

记得同步修改 config.toml 和 CC Switch 中的端口号。

9.2 401 Unauthorized — 认证失败

原因： Codex CLI 使用的密钥和 codex-bridge 的密钥不匹配。

解决方法：

确认 ~/.codex/auth.json 中的 OPENAI_API_KEY 与 .env 中的 PROXY_AUTH_KEY 完全一致。

9.3 --env-file: not recognized — Node.js 版本太低

原因： --env-file 参数需要 Node.js 20+。

解决方法：

升级 Node.js，或者用替代命令启动：

# Windows CMD
set PROXY_AUTH_KEY=你的密钥 && set DEEPSEEK_API_KEY=你的密钥 && node proxy.mjs

# Windows PowerShell
$env:PROXY_AUTH_KEY="你的密钥"; $env:DEEPSEEK_API_KEY="你的密钥"; node proxy.mjs

9.4 Model metadata not found 警告

原因： Codex CLI 自带的模型列表里没有 DeepSeek / MiMo 的元数据。

影响： 不影响正常使用，只是一个警告。Codex 会使用默认的 fallback 配置。

9.5 上游超时

原因： DeepSeek / MiMo 服务器响应慢。

解决方法： 在 .env 中增大超时时间：

UPSTREAM_TIMEOUT_MS=300000

9.6 模型回答说自己是 OpenAI 的模型

原因： 这是模型自身的"自我认知"，它不知道自己是通过代理调用的。实际上你的请求确实是发给了 DeepSeek / MiMo，只是模型的回答文本里会这样自称。

影响： 无影响，可以忽略。

9.7 Codex CLI 连不上代理

检查清单：

  1. codex-bridge 是否在运行？（终端里有没有 Listening on http://localhost:4000）
  2. config.toml 里的 base_url 是否正确？
  3. 防火墙是否阻止了本地连接？
  4. 尝试在浏览器打开 http://localhost:4000/health，如果显示正常说明代理没问题

十、完整配置示例

10.1 .env 文件（使用 DeepSeek）

# codex-bridge 配置

# 入站认证密钥（Codex 连接代理用的）
PROXY_AUTH_KEY=sk-proxy-local-a1b2cxxxxxxxxxxx

# DeepSeek API Key
DEEPSEEK_API_KEY=sk-79xxxxxxxxxxx

# 代理端口
PROXY_PORT=4000

# 日志级别
LOG_LEVEL=info

# 模型清单文件路径
MODEL_CATALOG_PATH=./proxy-models.json

10.2 ~/.codex/config.toml

model = "deepseek-v4-flash"
model_provider = "local_proxy"

[model_providers.local_proxy]
name = "local_proxy"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
requires_openai_auth = true

10.3 ~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-proxy-local-a1b2c3xxxxxxxxxxx"
}

十一、总结

  1. 下载 codex-bridge
  2. 填写 .env（代理密钥 + 模型 API Key）
  3. 启动 node --env-file=.env proxy.mjs
  4. 配置 Codex CLI 指向 http://127.0.0.1:4000/v1
  5. 使用 codex 开始编程
# AI
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

Langchain 总结（上）

学习笔记

avatar AtomGit开源社区
cover

Sickle Agent 助手

avatar AtomGit开源社区

神经网络与深度学习 第5周课程总结

大语言模型（LLM）是基于海量文本训练的深度学习模型，具备文本理解、文本生成能力，可完成翻译、问答、摘要、对话等任务。文本、图像、视频、音频。多模态模型可以同时处理、理解多种不同类型的信息。2020 年 CVPR 顶会，Google 发表论文，首次将纯 Transformer 大规模应用在图像任务，打破 CNN 在视觉领域的垄断。CLIP 全称图文对比学习模型，是多模态领域的基础底座，核心实现图像

avatar AtomGit开源社区