Codex 配置自定义 AI API 完整指南：从零到一接入你的专属模型

优质文章学习记录

— 9 min read
Codex 配置自定义 AI API 完整指南：从零到一接入你的专属模型

Codex 配置自定义 AI API 完整指南：从零到一接入你的专属模型

前言

作为一名开发者，我们经常需要在终端环境中使用 AI 编程助手。OpenAI 的 Codex 是一个非常强大的命令行 AI 编程工具，但默认情况下它只能调用 OpenAI 官方的 API。那么问题来了：如果我们有自己的 API 服务（比如部署了国产大模型、使用了代理服务、或者公司内部的 AI 平台），如何让 Codex 接入这些自定义的 API 呢？

本文将通过一个真实的配置案例，详细讲解如何在 macOS（特别是 Mac Mini）环境下配置 Codex，使其能够调用自定义的 AI API。整个过程涉及配置文件编写、环境变量设置、版本兼容性问题排查等，希望能帮助到遇到类似问题的开发者。

一、理解 Codex 的架构

在开始配置之前，我们需要理解 Codex 的基本架构。Codex 采用了一种灵活的 Provider 机制，允许用户定义多个 AI 服务提供商，并在它们之间切换。

核心概念：

  • Provider（提供商）：一个 AI 服务的具体实现，包含 API 地址、认证方式等
  • Model（模型）：Provider 提供的具体模型名称
  • Wire API：Codex 与 Provider 之间的通信协议类型

这种设计让 Codex 不仅限于 OpenAI 的服务，理论上可以接入任何兼容 OpenAI API 格式的服务。

二、配置前的准备工作

2.1 确认 Codex 版本

这是最关键的一步！不同版本的 Codex 对 API 协议的支持完全不同：

codex --version
版本支持的 API 类型wire_api 参数
0.81.0 及以上Responses API“responses”
0.80.0 及以下Chat Completions API“chat”

重要提示：如果你的 API 服务只支持标准的 Chat Completions 格式（大多数国产模型和代理服务都是这种），建议安装 0.80.0 版本：

npminstall-g @openai/[email protected]

2.2 确认 API 服务状态

在配置 Codex 之前，先用 curl 测试一下你的 API 服务是否正常工作：

# 测试基础连通性curl-X POST http://localhost:8080/v1/chat/completions \-H"Content-Type: application/json"\-H"Authorization: Bearer YOUR_API_KEY"\-d'{ "model": "your-model-name", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 50 }'

如果这个请求能正常返回，说明你的 API 服务是可用的。

三、配置文件详解

3.1 配置文件位置

Codex 的配置文件采用 TOML 格式，默认位置在：

  • 用户级配置：~/.codex/config.toml
  • 项目级配置：项目根目录/.codex/config.toml

项目级配置会覆盖用户级配置，这为不同项目使用不同的 AI 服务提供了便利。

3.2 基础配置结构

一个完整的配置文件包含三个部分：

  1. 全局设置（默认模型和 Provider）
  2. Provider 定义
  3. 项目特定设置（可选）
# 全局设置 service_tier = "fast" model = "your-model-name" model_provider = "your-provider-name" # Provider 定义 [model_providers.your-provider-name] name = "显示名称" base_url = "http://localhost:8080/v1" wire_api = "chat" # 或 "responses" env_key = "YOUR_API_KEY_ENV_NAME" # 项目特定设置（可选） [projects."/path/to/your/project"] trust_level = "trusted"

3.3 配置项详细说明

配置项说明示例
model默认使用的模型名称qwen3.6-plus
model_provider默认使用的 Provider 名称my-custom-provider
base_urlAPI 服务地址http://localhost:8080/v1
wire_apiAPI 协议类型chat 或 responses
env_key存放 API Key 的环境变量名MY_API_KEY

3.4 常见配置错误及修正

错误 1：将 API Key 直接写在 env_key 字段

# ❌ 错误 env_key = "sk-your-actual-api-key" # ✅ 正确 env_key = "MY_API_KEY"

错误 2：协议类型不匹配

# 如果 API 只支持 Chat Completions wire_api = "chat" # 而不是 "responses"

错误 3：base_url 格式问题

# 本地服务通常用 http 而不是 https base_url = "http://localhost:8080/v1" # 正确 base_url = "https://localhost:8080/v1" # 可能导致 SSL 错误

四、Mac Mini 环境变量配置

4.1 临时设置（仅当前终端会话）

exportYOUR_API_KEY="sk-your-actual-api-key"

4.2 永久设置（推荐）

由于 Mac Mini 默认使用 Zsh，我们需要将环境变量写入 ~/.zshrc：

echo'export YOUR_API_KEY="sk-your-actual-api-key"'>> ~/.zshrc source ~/.zshrc

4.3 验证环境变量

echo$YOUR_API_KEY

五、实战案例：配置本地 Qwen API

假设我们有一个运行在本地 8080 端口的 Qwen 模型服务，以下是完整的配置步骤：

5.1 创建配置文件

mkdir-p ~/.codex nano ~/.codex/config.toml

5.2 写入配置内容

service_tier = "fast" # 设置默认使用 Qwen 模型 model = "qwen3.6-plus" model_provider = "red_claw" # 定义 Provider [model_providers.red_claw] name = "RedClaw Qwen Service" base_url = "http://localhost:8080/v1" wire_api = "chat" env_key = "REDCLAW_API_KEY" # 项目信任配置（可选） [projects."/Users/macmini/workspace/my-project"] trust_level = "trusted"

5.3 设置环境变量

echo'export REDCLAW_API_KEY="sk-yien-1620bbcc7f4349c1bcf5b82f6e3756c1"'>> ~/.zshrc source ~/.zshrc

5.4 测试配置

codex "你好，请介绍一下自己"

六、常见问题及解决方案

6.1 问题：自定义模型不显示在选择器中

现象：运行 codex 时，模型选择器只显示官方模型，看不到自己配置的模型。

原因：配置文件没有被正确加载，或者配置格式有误。

解决方案：

# 检查配置文件是否存在ls-la ~/.codex/config.toml # 查看当前加载的配置 codex config show # 检查配置语法 codex --config-check

6.2 问题：--model-provider 参数不存在

现象：

error: unexpected argument '--model-provider' found

原因：Codex 没有这个命令行参数。

解决方案：通过配置文件设置默认 Provider，而不是通过命令行参数。或者使用正确的参数名：

# 正确的参数是 --provider codex -m model-name --provider provider-name "prompt"

6.3 问题：wire_api 版本不匹配

现象：

wire_api = chat is no longer supported

原因：新版 Codex 不再支持 chat 协议。

解决方案：

  • 方案一：将配置中的 wire_api 改为 "responses"
  • 方案二：降级 Codex 到 0.80.0 版本
npm uninstall -g @openai/codex npminstall-g @openai/[email protected]

6.4 问题：SSL 证书错误（本地服务）

现象：

SSL certificate problem: self signed certificate

原因：本地服务使用 HTTPS 但没有有效的 SSL 证书。

解决方案：

[model_providers.your-provider] # ... 其他配置 allow_insecure = true # 仅用于本地开发

6.5 问题：环境变量不生效

现象：配置了环境变量，但 Codex 仍然提示找不到 API Key。

解决方案：

# 1. 确认环境变量已设置echo$YOUR_API_KEY# 2. 重新加载配置文件source ~/.zshrc # 3. 重启终端# Mac 上按 Cmd+Q 退出终端，重新打开# 4. 检查是否有空格或特殊字符# 确保 API Key 没有多余的空格

七、调试技巧

7.1 开启调试模式

# 开启详细日志DEBUG=true codex "你的问题"# 查看网络请求详情RUST_LOG=debug codex "你的问题"

7.2 查看配置加载情况

# 显示当前所有配置 codex config show # 列出可用的 Providers codex config list-providers # 测试配置文件 codex config test

7.3 网络抓包

如果还是无法定位问题，可以用 Wireshark 或 tcpdump 抓包分析：

# 监控本地 8080 端口的流量sudo tcpdump -i lo0 port 8080-A

八、最佳实践建议

8.1 安全性建议

  1. 永远不要将 API Key 写在配置文件中，始终使用环境变量
  2. 定期轮换 API Key
  3. 对不同项目使用不同的 API Key，便于审计和权限管理
  4. 将 .codex/ 目录加入 .gitignore，避免意外提交敏感信息

8.2 多 Provider 管理

如果你有多个 AI 服务，可以在配置文件中定义多个 Provider：

# 默认使用本地 Qwen model = "qwen3.6-plus" model_provider = "local_qwen" # 定义本地 Qwen [model_providers.local_qwen] name = "Local Qwen" base_url = "http://localhost:8080/v1" wire_api = "chat" env_key = "QWEN_API_KEY" # 定义云端 GPT [model_providers.cloud_gpt] name = "Cloud GPT" base_url = "https://api.openai.com/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" # 定义代理服务 [model_providers.proxy_service] name = "API Proxy" base_url = "https://your-proxy.com/v1" wire_api = "chat" env_key = "PROXY_API_KEY"

8.3 项目级配置示例

为不同项目创建独立的配置文件：

# 项目 A 使用本地 Qwenmkdir-p /path/to/projectA/.codex cat> /path/to/projectA/.codex/config.toml <<'EOF' model = "qwen-max" model_provider = "local_qwen" [model_providers.local_qwen] base_url = "http://localhost:8080/v1" wire_api = "chat" env_key = "QWEN_API_KEY" EOF# 项目 B 使用云端 GPTmkdir-p /path/to/projectB/.codex cat> /path/to/projectB/.codex/config.toml <<'EOF' model = "gpt-4" model_provider = "cloud_gpt" [model_providers.cloud_gpt] base_url = "https://api.openai.com/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" EOF

九、完整配置清单

最后，提供一个完整的配置检查清单，确保没有遗漏：

  • Codex 版本已确认（0.80.0 推荐）
  • API 服务已启动并可访问
  • ~/.codex/config.toml 文件已创建
  • model 和 model_provider 已正确设置
  • Provider 配置块已添加
  • base_url 使用正确的协议（本地用 http）
  • wire_api 类型与 API 服务匹配
  • env_key 填的是环境变量名，不是 API Key
  • 环境变量已在 ~/.zshrc 中设置
  • 已执行 source ~/.zshrc 使配置生效
  • echo $YOUR_ENV_KEY 能正确显示 API Key
  • codex config show 显示正确的配置
  • codex "test" 能正常响应

十、总结

配置 Codex 调用自定义 AI API 的核心要点可以总结为：

  1. 版本先行：确认 Codex 版本，选择合适的 wire_api 类型
  2. 配置分离：API Key 用环境变量，其他配置用 TOML 文件
  3. 协议匹配：确保 wire_api 与你的 API 服务类型一致
  4. 路径正确：base_url 格式要正确，本地服务注意 http vs https
  5. 调试有方：善用 DEBUG=true 和 codex config show 排查问题

虽然配置过程中可能会遇到各种问题（版本不匹配、参数名错误、环境变量不生效等），但只要按照本文的步骤逐一排查，最终都能顺利解决。

希望这篇指南能帮助你成功配置 Codex，享受到在终端中使用自定义 AI 模型的便利。如果你在配置过程中遇到其他问题，欢迎在评论区留言交流！

附录：快速配置模板

# 一键配置脚本（请根据实际情况修改）cat> ~/.codex/config.toml <<'EOF' model = "your-model" model_provider = "custom" [model_providers.custom] base_url = "http://localhost:8080/v1" wire_api = "chat" env_key = "CUSTOM_API_KEY" EOFecho'export CUSTOM_API_KEY="your-actual-api-key"'>> ~/.zshrc source ~/.zshrc # 测试 codex "Hello, world!"

Read more

【前沿解析】2026年3月25日：从机器人协同到全模态AI生态——中关村论坛与昆仑万维双重突破定义AI产业新范式

摘要：2026年3月25日，北京中关村论坛盛大开幕，展示了跨品牌机器人协同服务与昆仑万维三大世界第一梯队模型的突破进展。本文深入解析具身智能机器人“组团上岗”的技术原理、昆仑万维Matrix-Game 3.0、SkyReels V4、Mureka V9的全模态能力，以及产业协同生态的战略价值，涵盖统一调度系统架构、多智能体协作机制、代码实现方案与未来发展趋势。 关键词：具身智能、机器人协同、多模态大模型、全模态AI、中关村论坛、昆仑万维、Matrix-Game 3.0、SkyReels V4、Mureka V9、AI产业生态 一、引言：AI产业化进程加速，生态协同成为新焦点 2026年3月25日，北京中关村论坛年会正式拉开帷幕，本届论坛以"科技创新与产业创新深度融合"为主题，吸引了全球AI领域的目光。与往年不同，今年论坛的"机器人浓度"

Neo4j 知识讲解与在线工具使用教程

图数据库领域的核心工具 ——Neo4j，同时详细拆解其在线预览控制台（https://console-preview.neo4j.io/）的使用方法，以及查询工具（https://console-preview.neo4j.io/tools/query）的模块功能。 一、Neo4j 核心知识铺垫 在使用工具前，我们需要先理解 Neo4j 的本质和核心概念，这是后续操作的基础。 1. 什么是 Neo4j？ Neo4j 是世界上最流行的原生图数据库（Native Graph Database），专门用于存储、查询和分析 “实体之间的关联关系”。它与我们熟悉的 MySQL 等关系型数据库的核心差异的是： * 关系型数据库（MySQL）：用 “表 + 行 + 外键” 间接表示关联，查询多表关联时需频繁 JOIN，效率低； * 图数据库（Neo4j）
从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战

从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战

👋 大家好，欢迎来到我的技术博客！ 📚 在这里，我会分享学习笔记、实战经验与技术思考，力求用简单的方式讲清楚复杂的问题。 🌱 无论你是刚入门的新手，还是正在进阶的开发者，希望你都能有所收获！ 文章目录 * 从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战 🏠💡 * 为什么选择RISC-V？🤔 * 系统整体架构概览 🧩 * 第一步：硬件选型与电路搭建 🔌 * 主控芯片选择 * 外设连接 * 第二步：开发环境搭建 🛠️ * 安装步骤（以Ubuntu为例） * 第三步：裸机驱动开发（Bare Metal）⚡ * 示例1：DHT11温湿度读取（Bit-banging） * 示例2：BH1750光照传感器（I2C） * 第四步：引入FreeRTOS实现多任务调度 🔄 * 第五步：Wi-Fi连接与MQTT通信 ☁️📡 * 连接Wi-Fi * MQTT客户端（使用esp-mqtt库） * 第六步：BLE本地控制（无需Wi-Fi）📱
宇树机器人SDK2开发指南：从环境搭建到Demo测试

宇树机器人SDK2开发指南：从环境搭建到Demo测试

本文以宇树 G1 人形机器人为主线，系统介绍 unitree_sdk2（C++）与 unitree_sdk2_python（Python）的完整开发流程，涵盖通信架构原理、环境搭建、依赖安装、Demo 编译运行、网络配置以及常见问题处理，适合具身智能领域的初中级开发者快速上手。 目录 1. SDK2 概述与架构原理 2. 开发环境要求 3. 获取官方 SDK 包 4. 安装依赖与编译 5. 机器人与开发机网络配置 6. 调试并运行 Demo 7. Python SDK Demo 测试 8. 常见问题与解决方案 9. 总结 1. SDK2 概述与架构原理 1.