通过 Magpie 接入 Codex

推荐使用 Magpie 管理 Codex 的服务与模型配置。 AI Hub 提供账号、API Key、模型列表和 Responses API；本项目停止开发 Meiyi Codex Setup 桌面助手，客户端配置交给 Magpie。

安装与连接

从 Magpie 官网安装适合系统的版本，支持 macOS、Windows 和 Linux。另行安装 Codex CLI 或 Codex 桌面应用。
在 API Key 管理创建一个用于 Magpie 的 Key，复制并保存完整密钥。完整 Key 只显示一次；已有 Key 无法再次查看，遗失时可创建新 Key。
打开配置 Codex，点击“添加到 Magpie”。在导入窗口核对当前 AI Hub 地址，粘贴 Key，然后确认添加。新 Key 展示区也提供同一导入入口。
在 Magpie 的 Agents 页面选择 Codex，再选择 Meiyi AI Hub 下的模型。模型以当前服务实际返回的列表为准。
重新打开 Codex 或开始新会话。使用这些模型时保持 Magpie 运行；关闭窗口后可让它留在菜单栏或系统托盘。

导入链接只包含服务信息，不携带 API Key。它声明 OpenAI Responses 端点，让 Codex 使用原生 Responses 协议；不固定模型列表或套用其他供应商的能力目录。不同 AI Hub 服务地址使用独立的 provider ID，避免导入测试环境时替换生产环境。

如果导入按钮无法打开，可在 Magpie 的 Providers 页面添加自定义服务：

字段	填写内容
Name	Meiyi AI Hub
OpenAI Responses Base URL	当前工作台地址加 `/v1`，可在配置页复制
API Key	你在当前 AI Hub 创建的完整 Key

导入功能需要 Magpie 0.1.8 或更新版本。操作细节见官方入门说明和服务导入说明。

从旧助手迁移

已安装的 Meiyi Codex Setup 和已生成的 Key、Codex 配置可继续使用，不需要立即重置或卸载。旧版本安装包及授权接口保留兼容，但不再推荐新安装或发布新客户端版本。

Magpie 可以从 Providers 页的 Import 导入现有 agent 中的服务。也可以按照上面的步骤使用新建的 Key。确认 Magpie 下的新会话可用后，如果旧 Key 不再被其他应用使用，再到 API Key 管理页禁用它。不要再运行旧助手修改已交给 Magpie 管理的 Codex 配置。

可选：同步原生模型能力目录

本节仅适用于直接配置 AI Hub provider 的高级用户。通过 Magpie 连接时，由 Magpie 管理本机网关与 agent 配置，不要把此脚本用于 Magpie 的本机网关地址。

模型列表只说明有哪些模型；原生能力目录还包含上下文窗口、推理档位、输入类型、工具配置及模型指令。自定义 provider 在本轮 Codex CLI 0.161.0 实测中不会自动请求远端模型目录，因此需要显式同步到本机 model_catalog_json。

网关提供需鉴权的 GET /v1/models?format=codex&client_version=0.161.0。普通 GET /v1/models 的响应保持不变；扩展响应新增 models 和 unavailable_models：

只导出已启用、有 Codex 可用路由的公开模型；按路由映射查找上游原生元数据。
同一模型所有已启用的 Codex 路由都必须提供一致的能力，包含暂时冷却的备用线路。
非原生 Responses 渠道、缺失完整元数据或路由能力不一致的模型列入 unavailable_models。DeepSeek 不会套用 GPT 的窗口、工具或指令。
没有任何可验证配置时返回 503；目录失败不影响普通模型列表或现有推理请求。
每次同步从当前配置读取上游目录，整体最多等待 15 秒，上游响应最大 4 MiB。目录请求使用对应渠道的鉴权、代理和自定义头，不转发用户 Key。

在仓库根目录使用 Python 3.11+ 和实际安装的 Codex CLI：

python3 scripts/sync_codex_catalog.py \
  --config /absolute/path/to/codex/config.toml \
  --codex /absolute/path/to/codex \
  --output /absolute/path/to/codex/ai-hub-models.json

配置使用 [profiles.NAME] 时加 --profile NAME。脚本读取所选 provider 已配置的 env_key、experimental_bearer_token 或绝对路径 auth.command；也可用 --api-key-env ENV_NAME 指定已有环境变量。已有凭据 helper 以参数数组直接调用，不经过 shell。Key 不写入目录或命令行。

脚本要求当前配置的 model 包含在目录中，并调用本机 codex debug models 验证格式和实际加载的模型集合。验证成功后才以 0600 权限原子替换输出文件。失败时保留旧文件，不改写 config.toml、auth.json 或运行中的会话。

确认输出后，在对应配置文件的顶层设置或更新：

model_catalog_json = "/absolute/path/to/codex/ai-hub-models.json"

重新启动 Codex 会话后生效。能力目录是一次同步的快照；调整路由、升级 CLI 或上游能力变化后重新同步。该目录不代表图片、WebSocket、压缩等功能均已完成真实调用测试；这些功能仍需单独验证。若当前模型缺少原生目录，可继续使用现有配置。

常见问题

401：检查 Key 是否完整、过期或已禁用。
403：账号已停用，请联系管理员。
429：达到用户或 API Key 的 RPM / 最大并发限制。
502 / 503：上游尚未配置、未启用或暂时不可用，请向管理员提供请求 ID。

更多信息见故障排查。