Codex 自定义 AI API 接入指南：从零配置专属模型（Mac Mini 实战）

在终端环境中使用 AI 编程助手已成为现代开发者的日常。OpenAI 的 Codex 虽然强大，但默认仅支持官方 API。如果你希望接入国产大模型、代理服务或公司内部的 AI 平台，如何让 Codex 调用自定义 API 呢？本文通过一个完整的 macOS（Mac Mini）配置案例，详细讲解配置文件编写、环境变量设置及版本兼容性问题排查，助你轻松接入专属模型。

一、理解 Codex 架构：Provider 与 Model 机制

在开始配置之前，先了解 Codex 的底层设计。Codex 采用灵活的 Provider 机制，允许用户定义多个 AI 服务提供商，并在它们之间无缝切换。核心概念包括：

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

这种设计使 Codex 不局限于 OpenAI 服务，理论上可接入任何兼容 OpenAI API 格式的服务。 理解这一架构，有助于你后续配置多 Provider 和微服务场景。

二、配置前的准备工作：版本与 API 服务验证

⚠️ 最关键的一步！不同版本的 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 版本：

npm install -g @openai/codex@0.80.0

在配置 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 服务可用。 这一步可以避免后续排查时怀疑服务端问题。

三、配置文件详解：从基础到进阶

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

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

项目级配置会覆盖用户级配置，便于不同项目使用不同的 AI 服务。一个完整的配置文件包含全局设置、Provider 定义和项目特定设置：

# 全局设置
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"

配置项详细说明如下：

配置项说明示例
默认使用的模型名称
默认使用的 Provider 名称
API 服务地址
API 协议类型 或
存放 API Key 的环境变量名

常见配置错误及修正

错误 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 环境变量配置：临时与永久方案

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

export YOUR_API_KEY="sk-your-actual-api-key"

永久设置（推荐）：Mac Mini 默认使用 Zsh，需将环境变量写入 ~/.zshrc：

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

验证环境变量

echo $YOUR_API_KEY

✅ 确保环境变量生效，否则 Codex 无法读取 API Key。

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

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

创建配置文件

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

写入配置内容

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"

设置环境变量

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

测试配置

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

如果一切顺利，你将在终端中使用本地模型进行 AI 编程。

六、常见问题及解决方案

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

现象：运行 codex 时，模型选择器只显示官方模型，看不到自己配置的模型。原因：配置文件没有被正确加载，或配置格式有误。解决方案：

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

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

现象：

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

原因：Codex 没有这个命令行参数。解决方案：通过配置文件设置默认 Provider，或使用正确的参数名：

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

问题：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/codex@0.80.0

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

现象：

SSL certificate problem: self signed certificate

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

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

问题：环境变量不生效

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

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

[AFFILIATE_SLOT_1]

七、调试技巧：快速定位问题

开启调试模式

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

查看配置加载情况

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

网络抓包：如果仍无法定位问题，可用 Wireshark 或 tcpdump 抓包分析：

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

八、最佳实践建议

安全性建议

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

多 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"

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

# 项目 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 的核心要点可概括为：版本先行（确认 Codex 版本，选择合适的 wire_api 类型）；配置分离（API Key 用环境变量，其他配置用 TOML 文件）；协议匹配（确保 wire_api 与 API 服务类型一致）；路径正确（base_url 格式要正确，本地服务注意 http vs https）；调试有方（善用 DEBUG=true 和 codex config show 排查问题）。

虽然配置过程中可能会遇到各种问题，但只要按照本文步骤逐一排查，最终都能顺利解决。 希望这篇指南能帮助你成功配置 Codex，享受在终端中使用自定义 AI 模型的便利。

[AFFILIATE_SLOT_2]

附录：快速配置模板

以下模板可直接复制使用，只需替换占位符：

# 一键配置脚本（请根据实际情况修改）
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!"

modelqwen3.6-plusmodel_providermy-custom-providerbase_urlhttp://localhost:8080/v1wire_apichatresponsesenv_keyMY_API_KEY
posted on 2026-05-09 16:48  ljbguanli  阅读(3838)  评论(0)    收藏  举报

博客园  ©  2004-2026
浙公网安备 33010602011771号 浙ICP备2021040463号-3