前言

作為一名開(kāi)發(fā)者，我們經(jīng)常需要在終端環(huán)境中使用 AI 編程助手。OpenAI 的 Codex 是一個(gè)非常強(qiáng)大的命令行 AI 編程工具，但默認(rèn)情況下它只能調(diào)用 OpenAI 官方的 API。那么問(wèn)題來(lái)了：如果我們有自己的 API 服務(wù)（比如部署了國(guó)產(chǎn)大模型、使用了代理服務(wù)、或者公司內(nèi)部的 AI 平臺(tái)），如何讓 Codex 接入這些自定義的 API 呢？

本文將通過(guò)一個(gè)真實(shí)的配置案例，詳細(xì)講解如何在 macOS（特別是 Mac Mini）環(huán)境下配置 Codex，使其能夠調(diào)用自定義的 AI API。整個(gè)過(guò)程涉及配置文件編寫、環(huán)境變量設(shè)置、版本兼容性問(wèn)題排查等，希望能幫助到遇到類似問(wèn)題的開(kāi)發(fā)者。

一、理解 Codex 的架構(gòu)

在開(kāi)始配置之前，我們需要理解 Codex 的基本架構(gòu)。Codex 采用了一種靈活的 Provider 機(jī)制，允許用戶定義多個(gè) AI 服務(wù)提供商，并在它們之間切換。

核心概念：

• Provider（提供商）：一個(gè) AI 服務(wù)的具體實(shí)現(xiàn)，包含 API 地址、認(rèn)證方式等
• Model（模型）：Provider 提供的具體模型名稱
• Wire API：Codex 與 Provider 之間的通信協(xié)議類型

這種設(shè)計(jì)讓 Codex 不僅限于 OpenAI 的服務(wù)，理論上可以接入任何兼容 OpenAI API 格式的服務(wù)。

二、配置前的準(zhǔn)備工作

2.1 確認(rèn) Codex 版本

這是最關(guān)鍵的一步！不同版本的 Codex 對(duì) API 協(xié)議的支持完全不同：

codex --version

重要提示：如果你的 API 服務(wù)只支持標(biāo)準(zhǔn)的 Chat Completions 格式（大多數(shù)國(guó)產(chǎn)模型和代理服務(wù)都是這種），建議安裝 0.80.0 版本：

npm install -g @openai/codex@0.80.0

2.2 確認(rèn) API 服務(wù)狀態(tài)

在配置 Codex 之前，先用 curl 測(cè)試一下你的 API 服務(wù)是否正常工作：

# 測(cè)試基礎(chǔ)連通性
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
  }'

如果這個(gè)請(qǐng)求能正常返回，說(shuō)明你的 API 服務(wù)是可用的。

三、配置文件詳解

3.1 配置文件位置

Codex 的配置文件采用 TOML 格式，默認(rèn)位置在：

• 用戶級(jí)配置：~/.codex/config.toml
• 項(xiàng)目級(jí)配置：項(xiàng)目根目錄/.codex/config.toml

項(xiàng)目級(jí)配置會(huì)覆蓋用戶級(jí)配置，這為不同項(xiàng)目使用不同的 AI 服務(wù)提供了便利。

3.2 基礎(chǔ)配置結(jié)構(gòu)

一個(gè)完整的配置文件包含三個(gè)部分：

1. 全局設(shè)置（默認(rèn)模型和 Provider）
2. Provider 定義
3. 項(xiàng)目特定設(shè)置（可選）

# 全局設(shè)置
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"
# 項(xiàng)目特定設(shè)置（可選）
[projects."/path/to/your/project"]
trust_level = "trusted"

3.3 配置項(xiàng)詳細(xì)說(shuō)明

3.4 常見(jiàn)配置錯(cuò)誤及修正

錯(cuò)誤 1：將 API Key 直接寫在 env_key 字段

# ? 錯(cuò)誤
env_key = "sk-your-actual-api-key"
# ? 正確
env_key = "MY_API_KEY"

錯(cuò)誤 2：協(xié)議類型不匹配

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

錯(cuò)誤 3：base_url 格式問(wèn)題

# 本地服務(wù)通常用 http 而不是 https
base_url = "http://localhost:8080/v1"  # 正確
base_url = "https://localhost:8080/v1" # 可能導(dǎo)致 SSL 錯(cuò)誤

四、Mac Mini 環(huán)境變量配置

4.1 臨時(shí)設(shè)置（僅當(dāng)前終端會(huì)話）

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

4.2 永久設(shè)置（推薦）

由于 Mac Mini 默認(rèn)使用 Zsh，我們需要將環(huán)境變量寫入 ~/.zshrc：

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

4.3 驗(yàn)證環(huán)境變量

echo $YOUR_API_KEY

五、實(shí)戰(zhàn)案例：配置本地 Qwen API

假設(shè)我們有一個(gè)運(yùn)行在本地 8080 端口的 Qwen 模型服務(wù)，以下是完整的配置步驟：

5.1 創(chuàng)建配置文件

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

5.2 寫入配置內(nèi)容

service_tier = "fast"
# 設(shè)置默認(rèn)使用 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"
# 項(xiàng)目信任配置（可選）
[projects."/Users/macmini/workspace/my-project"]
trust_level = "trusted"

5.3 設(shè)置環(huán)境變量

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

5.4 測(cè)試配置

codex "你好，請(qǐng)介紹一下自己"

六、常見(jiàn)問(wèn)題及解決方案

6.1 問(wèn)題：自定義模型不顯示在選擇器中

現(xiàn)象：運(yùn)行 codex 時(shí)，模型選擇器只顯示官方模型，看不到自己配置的模型。

原因：配置文件沒(méi)有被正確加載，或者配置格式有誤。

解決方案：

# 檢查配置文件是否存在
ls -la ~/.codex/config.toml

# 查看當(dāng)前加載的配置
codex config show

# 檢查配置語(yǔ)法
codex --config-check

6.2 問(wèn)題：--model-provider參數(shù)不存在

現(xiàn)象：

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

原因：Codex 沒(méi)有這個(gè)命令行參數(shù)。

解決方案：通過(guò)配置文件設(shè)置默認(rèn) Provider，而不是通過(guò)命令行參數(shù)?；蛘呤褂谜_的參數(shù)名：

# 正確的參數(shù)是 --provider
codex -m model-name --provider provider-name "prompt"

6.3 問(wèn)題：wire_api 版本不匹配

現(xiàn)象：

wire_api = chat is no longer supported

原因：新版 Codex 不再支持 chat 協(xié)議。

解決方案：

• 方案一：將配置中的 wire_api 改為 "responses"
• 方案二：降級(jí) Codex 到 0.80.0 版本

npm uninstall -g @openai/codex
npm install -g @openai/codex@0.80.0

6.4 問(wèn)題：SSL 證書(shū)錯(cuò)誤（本地服務(wù)）

現(xiàn)象：

SSL certificate problem: self signed certificate

原因：本地服務(wù)使用 HTTPS 但沒(méi)有有效的 SSL 證書(shū)。

解決方案：

[model_providers.your-provider]
# ... 其他配置
allow_insecure = true  # 僅用于本地開(kāi)發(fā)

6.5 問(wèn)題：環(huán)境變量不生效

現(xiàn)象：配置了環(huán)境變量，但 Codex 仍然提示找不到 API Key。

解決方案：

# 1. 確認(rèn)環(huán)境變量已設(shè)置
echo $YOUR_API_KEY

# 2. 重新加載配置文件
source ~/.zshrc

# 3. 重啟終端
# Mac 上按 Cmd+Q 退出終端，重新打開(kāi)

# 4. 檢查是否有空格或特殊字符
# 確保 API Key 沒(méi)有多余的空格

七、調(diào)試技巧

7.1 開(kāi)啟調(diào)試模式

# 開(kāi)啟詳細(xì)日志
DEBUG=true codex "你的問(wèn)題"
# 查看網(wǎng)絡(luò)請(qǐng)求詳情
RUST_LOG=debug codex "你的問(wèn)題"

7.2 查看配置加載情況

# 顯示當(dāng)前所有配置
codex config show

# 列出可用的 Providers
codex config list-providers

# 測(cè)試配置文件
codex config test

7.3 網(wǎng)絡(luò)抓包

如果還是無(wú)法定位問(wèn)題，可以用 Wireshark 或 tcpdump 抓包分析：

# 監(jiān)控本地 8080 端口的流量
sudo tcpdump -i lo0 port 8080 -A

八、最佳實(shí)踐建議

8.1 安全性建議

1. 永遠(yuǎn)不要將 API Key 寫在配置文件中，始終使用環(huán)境變量
2. 定期輪換 API Key
3. 對(duì)不同項(xiàng)目使用不同的 API Key，便于審計(jì)和權(quán)限管理
4. 將 .codex/ 目錄加入 .gitignore，避免意外提交敏感信息

8.2 多 Provider 管理

如果你有多個(gè) AI 服務(wù)，可以在配置文件中定義多個(gè) Provider：

# 默認(rèn)使用本地 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"
# 定義代理服務(wù)
[model_providers.proxy_service]
name = "API Proxy"
base_url = "https://your-proxy.com/v1"
wire_api = "chat"
env_key = "PROXY_API_KEY"

8.3 項(xiàng)目級(jí)配置示例

為不同項(xiàng)目創(chuàng)建獨(dú)立的配置文件：

# 項(xiàng)目 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
# 項(xiàng)目 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

九、完整配置清單

最后，提供一個(gè)完整的配置檢查清單，確保沒(méi)有遺漏：

• Codex 版本已確認(rèn)（0.80.0 推薦）
• API 服務(wù)已啟動(dòng)并可訪問(wèn)
• ~/.codex/config.toml 文件已創(chuàng)建
• model 和 model_provider 已正確設(shè)置
• Provider 配置塊已添加
• base_url 使用正確的協(xié)議（本地用 http）
• wire_api 類型與 API 服務(wù)匹配
• env_key 填的是環(huán)境變量名，不是 API Key
• 環(huán)境變量已在 ~/.zshrc 中設(shè)置
• 已執(zhí)行 source ~/.zshrc 使配置生效
• echo $YOUR_ENV_KEY 能正確顯示 API Key
• codex config show 顯示正確的配置
• codex "test" 能正常響應(yīng)

十、總結(jié)

配置 Codex 調(diào)用自定義 AI API 的核心要點(diǎn)可以總結(jié)為：

1. 版本先行：確認(rèn) Codex 版本，選擇合適的 wire_api 類型
2. 配置分離：API Key 用環(huán)境變量，其他配置用 TOML 文件
3. 協(xié)議匹配：確保 wire_api 與你的 API 服務(wù)類型一致
4. 路徑正確：base_url 格式要正確，本地服務(wù)注意 http vs https
5. 調(diào)試有方：善用 DEBUG=true 和 codex config show 排查問(wèn)題

雖然配置過(guò)程中可能會(huì)遇到各種問(wèn)題（版本不匹配、參數(shù)名錯(cuò)誤、環(huán)境變量不生效等），但只要按照本文的步驟逐一排查，最終都能順利解決。

希望這篇指南能幫助你成功配置 Codex，享受到在終端中使用自定義 AI 模型的便利。如果你在配置過(guò)程中遇到其他問(wèn)題，歡迎在評(píng)論區(qū)留言交流！

附錄：快速配置模板

# 一鍵配置腳本（請(qǐng)根據(jù)實(shí)際情況修改）
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
# 測(cè)試
codex "Hello, world!"

到此這篇關(guān)于Codex 配置自定義 AI API 完整指南的文章就介紹到這了,更多相關(guān)Codex 配置自定義 AI API內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論