Codex + Magpie 完整使用教程：让 Codex 自由切换 DeepSeek、Kimi、GPT 等 AI 模型

这种架构最大的优势是：开发者仍然使用熟悉的 Codex 操作方式，但可以通过 Magpie 管理底层模型，而不必针对每个供应商单独维护复杂的配置。

二、为什么要将 Codex 与 Magpie 组合使用？

需要注意，Magpie 不会自动提升模型本身的编程能力。模型切换后，代码生成质量、工具调用兼容性、上下文处理能力和执行稳定性仍取决于具体模型及供应商接口。

对于真实的软件开发项目，建议先用非生产代码验证模型兼容性，再逐步引入实际工作流。

三、准备工作：安装 Codex CLI

正式配置 Magpie 前，需要确保计算机已经安装 Codex CLI。

本教程以 macOS 为主要演示环境，Windows 和 Linux 的整体配置流程基本相同。

1. 检查 Node.js 环境

打开终端，执行：

如果已经安装，终端会显示对应版本号。如果没有安装，建议从 Node.js 官网 安装当前受支持的 LTS 版本。

2. 安装 Codex CLI

通过 npm 全局安装：

安装完成后，检查版本：

然后进入自己的项目目录：

首次使用 Codex 时，需要按照终端提示完成登录或 API 认证。

如果已经在正常使用 Codex，可以直接跳过这一节。

四、安装 Magpie

Magpie 提供桌面应用、终端界面和 CLI 等多种操作方式，支持 macOS、Windows 和 Linux。

方式一：通过官网安装（推荐）

访问 Magpie 官方网站，下载适合当前操作系统的安装包。

安装完成后，启动 Magpie，即可使用图形化界面管理 AI 模型与 Agent。

这种方式更适合需要频繁切换模型的开发者，因为日常操作无需反复执行命令。

方式二：通过终端安装

在 macOS 或 Linux 终端中运行官方安装命令：

出于安全考虑，也可以先下载脚本、检查内容，再执行安装。

安装完成后运行：

如果能够看到命令帮助信息，说明 CLI 已正确安装。

还可以运行：

进入 Magpie 的终端交互界面。

五、在 Magpie 中添加 AI 模型供应商

成功安装后，首先需要解决的问题是：让 Magpie 知道模型应该从哪里调用。

打开 Magpie，进入 Providers 页面，选择 Add provider。

Magpie 支持三类主要模型来源：

需要特别区分：ChatGPT 订阅和 OpenAI API 并不是同一种计费方式。通过 Magpie 连接订阅账号，并不代表自动获得无限量 API 调用额度，实际可用性仍取决于供应商的订阅权限、额度与相关条款。

1. 添加 DeepSeek

在 Providers 中搜索并选择 DeepSeek，然后输入从官方平台申请的 API Key。

添加完成后，可以通过供应商页面的测试功能验证接口是否正常。

也可以使用 CLI 添加：

magpie provider add deepseek YOUR_API_KEY

其中 YOUR_API_KEY 需要替换为实际密钥。生产环境建议通过图形界面输入，避免密钥保存在 shell 历史中。

2. 添加 Kimi

操作方式类似。

在 Providers 页面选择 Kimi 或对应的 Moonshot 供应商预设，输入有效 API Key，保存并测试。

添加成功后，Magpie 会提供该供应商可用的模型供选择。

3. 查看已配置模型

执行：

查看已经配置的供应商。

执行：

查看当前可供 Agent 使用的模型。

模型通常采用这样的命名格式：

例如：

这里的模型 ID 是官方文档中的示例。实际配置时，应以 Magpie 当前返回的模型列表为准，不能直接假设所有示例模型都在自己的账号中可用。

六、让 Codex 使用 Magpie

这是整个教程最关键的一步。

在 Magpie 中打开 Agents 页面，找到 Codex，然后选择刚刚添加的模型。

假设现在希望 Codex 使用 Kimi，可以在终端执行官方提供的示例命令：

配置完成后，重新启动 Codex：

此时，Codex 会读取更新后的配置，通过 Magpie 网关请求指定模型。

如果希望调整 Codex 的推理强度，可以使用：

需要注意，推理强度能否实际生效，取决于所选模型是否支持相应参数。

Magpie 修改了哪些配置？

Codex 默认读取：

当通过 Magpie 为 Codex 配置第三方模型后，Magpie 会在这个文件中添加或更新模型配置以及 [model_providers.magpie] 配置表，并管理对应的模型列表。

整个过程由 Magpie 自动完成，通常无需手动编写 TOML。

可以用以下命令检查：

或者使用编辑器查看：

重要：切换模型后需要启动新的 Codex 会话。 已经运行的会话仍可能沿用启动时的模型；如果使用 Codex 桌面应用，还应重启应用。

下面以 Java Spring Boot 项目为例，演示 Codex 与 Magpie 的实际工作方式。

假设现在有一个 ERP 系统，需要新增库存锁定功能。

项目目录如下：

第一步：进入项目

第二步：选择模型

通过 Magpie 为 Codex 选择已经配置好的模型。

例如：

第三步：启动 Codex

第四步：输入开发任务

在 Codex 中输入：

请先分析当前 Spring Boot 项目中库存模块的代码结构，重点检查库存表、库存流水、销售订单和生产订单之间的关系。

需要新增库存锁定机制，要求支持销售订单锁定、生产领料预留和委外发料预留，并能在订单取消时正确释放锁定数量。

先输出涉及的数据库表、Service 和业务规则，以及可能存在的并发风险。未经确认不要直接修改代码。

此时，Codex 仍然负责扫描项目、读取代码及组织开发步骤。区别是底层推理请求将通过 Magpie 转发到选定模型。

建议采用两阶段开发流程：

1. 分析阶段：先由模型检查代码，识别现有业务逻辑和修改风险。

2. 实施阶段：确认设计方案后，再让 Codex 修改代码、编写测试并执行验证。

对于 ERP、MES、CRM 等存在大量业务状态和数据一致性要求的系统，这种方式比直接要求 AI 完成全部开发更容易控制风险。

八、进阶配置：多个模型自动路由

除了手动切换，Magpie 还支持 Routing Groups（路由组）。

例如，希望实现以下策略：

• 主要模型正常时，优先调用主要模型。

• 主要模型发生限流、额度不足或服务异常时，尝试备用模型。

• 根据项目目录或任务类型指定优先使用的模型。

可以在 Magpie 的 Routing 页面创建路由组，并添加已经配置好的模型。

例如，配置一个名为 ERP-Coder 的路由组：

在实际配置时，可以选择 order 策略，按照指定顺序尝试模型。

需要注意，备用模型并不是在所有失败情况下都能无缝接管。例如，模型之间可能存在上下文窗口、工具调用格式及推理能力差异。路由还应尽量避免在同一复杂开发任务中频繁切换模型，以降低上下文不一致的风险。

Magpie 还支持针对文件夹、上下文长度、任务意图等条件设置路由规则。

九、日常使用的几个实用命令

其中：

非常实用。当第三方模型兼容性不佳，或者希望恢复 Codex 原生模型时，可以通过该命令让 Magpie 撤销它为 Codex 写入的相关网关配置。

十、常见问题与排查

1. 切换了模型，Codex 仍然使用旧模型

首先完全退出当前 Codex 会话，再重新执行：

同时检查：

确认对应模型配置已经更新。

2. Codex 提示无法连接网关

Magpie 的默认本地网关地址为：

可以使用以下命令检查本地监听状态。

macOS：

Linux：

如果没有监听，需要确认 Magpie 网关是否已经启动。

Magpie 提供后台服务模式：

对于需要长期运行的开发环境，也可以根据官方文档配置 daemon 服务。

3. 使用 Clash 或其他代理后出现 502

如果系统使用 Clash、mihomo 等网络代理，需要确保访问 127.0.0.1:3425 的请求不被转发到代理服务器。

例如在兼容的 Clash / mihomo 规则配置中，将本地回环地址设置为直连：

rules: 
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve 
- IP-CIDR6,::1/128,DIRECT,no-resolve

这些规则应该放在会匹配本地请求的其他规则之前，并与现有代理配置合并，而不是直接覆盖整个规则文件。

4. Magpie 退出后 Codex 无法使用第三方模型

这是因为 Codex 已被配置为访问 Magpie 网关。当网关停止运行时，对应模型请求无法继续转发。

解决方式包括保持 Magpie 运行、安装后台服务，或者将 Codex 恢复为原生模型配置。

5. 使用 Magpie 是否安全？

需要重点理解三个方面。

首先，Magpie 的网关运行在本地，但请求仍然需要发送到所选择的模型供应商，并不意味着代码和上下文完全留在本机。

其次，Magpie 可能需要读取本地 Agent 的账号配置文件、管理 API Key 和修改 Agent 配置。企业开发环境应关注密钥权限、文件访问和所用版本的安全审计情况。

最后，Codex 仍然可能根据用户授予的权限执行本地命令和修改代码。Magpie 是模型管理工具，不是沙箱，也不能替代 Codex 的权限控制机制。

建议使用独立开发分支、限制生产环境凭据访问，并对重要代码变更执行人工 Review。

十一、Codex + Magpie 适合哪些开发团队？

对于同时维护 Java Spring Boot 后端、Vue 前端以及多个企业管理系统项目的团队，可以将 Magpie 定位为开发人员本地的 AI 模型管理层。

一种可参考的团队使用方式是：

不建议仅根据模型价格选择生产开发使用的模型。更合理的方法是选择同一批项目任务，对不同模型的完成质量、编译通过率、测试通过率、响应时间和 Token 成本进行对比。

Magpie 的 Usage 功能可以提供部分调用量和费用数据，但代码质量仍需要结合实际开发结果评估。

十二、总结

Codex 与 Magpie 的组合，本质上是将 AI 编程工具和底层模型供应商进行适度解耦。

Codex 负责执行软件开发任务，Magpie 负责管理模型供应商、路由和调用配置。

这种组合的价值，不是简单地让 Codex 多支持几个模型，而是为开发者提供一个相对统一、灵活且可调整的 AI 模型使用环境。

对于已经使用 Codex 的开发人员，可以优先从最简单的配置开始：安装 Magpie、添加一个第三方模型、将 Codex 指向该模型，验证代码读取与工具调用是否正常。待基本能力稳定后，再考虑多账号管理、路由组及自动故障切换。

随着 AI Coding 工具越来越多，把编程 Agent 的工作能力与模型调用管理分开，将成为值得关注的一种工程实践。