平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex 配置自定义 AI API”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

目录

• 前言
• 一、理解 Codex 的架构
• 二、设置前的准备工作
• 2.1 确认 Codex 版本
• 2.2 确认 API 服务状态
• 三、设置文件详解
• 3.1 设置文件位置
• 3.2 基础设置结构
• 3.3 设置项详细说明
• 3.4 常用设置错误及修正
• 四、Mac Mini 环境变量设置
• 4.1 临时设置（仅当前终端会话）
• 4.2 永久设置（建议）
• 4.3 验证环境变量
• 五、实战案例：设置本地 Qwen API
• 5.1 新建设置文件
• 5.2 写入设置内容
• 5.3 设置环境变量
• 5.4 测试设置
• 六、常用问题及解决方案
• 6.1 问题：自定义模型不显示在选择器中
• 6.2 问题：--model-provider参数不存在
• 6.3 问题：wire_api 版本不匹配
• 6.4 问题：SSL 证书错误（本地服务）
• 6.5 问题：环境变量不生效
• 七、调试技巧
• 7.1 开启调试模式
• 7.2 查看设置加载情况
• 7.3 网络抓包
• 八、最佳实践建议
• 8.1 安全性建议
• 8.2 多 Provider 管理
• 8.3 项目级设置示例
• 九、完整设置清单
• 十、总结

前言

实际处理时，作为一名开发者，我们经常需在终端环境中采用 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 服务只兼容标准的 Chat Completions 格式（大多数国产模型和代理服务都是这种），建议安装 0.80.0 版本：

npm install -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 设置项详细说明

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 临时设置（仅当前终端会话）

export YOUR_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
npm install -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 使用本地 Qwen
mkdir -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 使用云端 GPT
mkdir -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"
EOF
echo 'export CUSTOM_API_KEY="your-actual-api-key"' >> ~/.zshrc
source ~/.zshrc
# 测试
codex "Hello, world!"

理解这一步时，到此这篇关于Codex 设置自定义 AI API 完整指南的文章就介绍到这了,更多相关Codex 设置自定义 AI API内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多兼容脚本之家！