Codex自定义服务器配置排查指南

Codex 自定义服务器配置排查指南

问题背景

在使用 OpenAI Codex 时，有时需要配置自定义的 API 代理服务器，以便：

使用第三方 API 网关
通过代理访问 OpenAI 服务
使用兼容 OpenAI API 格式的自建服务

本文记录了一次完整的 Codex 自定义服务器配置排查过程，希望能帮助遇到类似问题的开发者。

问题现象

配置了自定义服务器后，Codex 仍然访问 api.openai.com，而不是配置的自定义服务器。

错误信息示例：

⚠ Falling back from WebSockets to HTTPS transport. unexpected status 401
  Unauthorized: Incorrect API key provided: xxx
  url: wss://api.openai.com/v1/responses

■ unexpected status 401 Unauthorized
  url: https://api.openai.com/v1/responses

配置文件位置

Codex 的配置文件位于：

主配置文件：~/.codex/config.toml
认证配置：~/.codex/auth.json

排查步骤

步骤 1：检查基础配置

首先检查 ~/.codex/config.toml 文件的基本配置：

[model_providers.proxy]
name = "proxy"
base_url = "http://your-custom-server.com:8888/"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

[defaults]
model_provider = "proxy"
model = "gpt-5-codex"

发现的问题：

问题 1：模型名称包含特殊字符

初始配置中模型名称为 "gpt‑5‑codex"，连字符不是标准的 ASCII 字符（-），而是 Unicode 不间断连字符（U+2011）。

验证方法：
仔细检查配置文件中的连字符字符编码。

解决方案：

# 错误（特殊字符）
model = "gpt‑5‑codex"

# 正确（标准连字符）
model = "gpt-5-codex"

问题 2：base_url 路径不完整

验证服务器端点：

使用 curl 测试不同路径的可用性：

# 测试带 /v1 路径
curl -s -o /dev/null -w "HTTP %{http_code}" \
  "http://your-custom-server.com:8888/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 测试不带 /v1 路径
curl -s -o /dev/null -w "HTTP %{http_code}" \
  "http://your-custom-server.com:8888/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

测试结果：

/v1/models 返回 HTTP 200 ✅
/models 返回 HTTP 404 ❌

结论：服务器需要 /v1 路径。

解决方案：

# 错误（缺少 /v1）
base_url = "http://your-custom-server.com:8888/"

# 正确（包含 /v1）
base_url = "http://your-custom-server.com:8888/v1/"

问题 3：wire_api 配置值错误

尝试将 wire_api 改为 "openai" 后，Codex 启动报错：

Error loading config.toml: unknown variant `openai`, expected `responses`
in `model_providers.proxy.wire_api`

结论：Codex 只支持 wire_api = "responses"，不能使用 "openai"。

正确配置：

wire_api = "responses"  # 唯一支持的值

步骤 2：验证服务器支持的模型

获取自定义服务器支持的模型列表：

curl -s "http://your-custom-server.com:8888/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq '.data[].id'

确认配置的模型名称（如 gpt-5-codex）在服务器的模型列表中。

步骤 3：配置优先级问题（关键！）

即使修复了上述问题，Codex 仍然访问 api.openai.com。

启动信息显示：

model: gpt-5.6-sol medium

但配置文件中 [defaults] 部分设置的是 gpt-5-codex。

原因分析：

检查配置文件发现顶层配置和 [defaults] 配置冲突：

# 顶层配置
model = "gpt-5.5"

[defaults]
model_provider = "proxy"
model = "gpt-5-codex"

问题根源：

顶层的 model 配置优先级更高
但顶层没有指定 model_provider
导致 Codex 使用默认的 OpenAI API

解决方案：

将 model_provider 也添加到顶层配置：

# 正确的顶层配置
preferred_auth_method = "apikey"
model_provider = "proxy"    # 必须指定！
model = "gpt-5-codex"
model_reasoning_effort = "medium"

步骤 4：环境变量配置

修复配置优先级后，Codex 不再访问 api.openai.com，但出现新错误：

■ Missing environment variable: `OPENAI_API_KEY`.

原因：

config.toml 中的配置：

env_key = "OPENAI_API_KEY"

这表示 Codex 会从环境变量中读取 API key，而不是从 auth.json 文件读取。

解决方案：

设置环境变量：

# 临时设置（当前会话）
export OPENAI_API_KEY="your-api-key-here"

# 永久设置（添加到 ~/.bashrc）
echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

为什么不从 auth.json 读取？

虽然 ~/.codex/auth.json 中可能有 API key 配置，但当使用自定义 provider 时：

env_key 配置明确指定从环境变量读取
auth.json 主要用于直接使用 OpenAI 官方 API 的场景

最终解决方案

完整的 config.toml 配置

# 顶层配置（必须包含 model_provider）
preferred_auth_method = "apikey"
model_provider = "proxy"           # 指定使用自定义 provider
model = "gpt-5-codex"              # 或其他服务器支持的模型
model_reasoning_effort = "medium"

# 自定义 provider 配置
[model_providers.proxy]
name = "proxy"
base_url = "http://your-custom-server.com:8888/v1/"  # 注意末尾的 /v1/
wire_api = "responses"             # 唯一支持的值
env_key = "OPENAI_API_KEY"         # 从环境变量读取

# 默认配置（可选，作为备用）
[defaults]
model_provider = "proxy"
model = "gpt-5-codex"

# 项目信任级别
[projects."/root/.codex"]
trust_level = "trusted"

[projects."/root"]
trust_level = "trusted"

环境变量配置

在 ~/.bashrc 中添加：

export OPENAI_API_KEY="your-api-key-here"

然后执行：

source ~/.bashrc

验证和测试

启动 Codex

codex

预期结果

启动界面应该显示：

╭──────────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.144.1)                       │
│                                                  │
│ model:     gpt-5-codex medium                    │
│ directory: ~                                     │
╰──────────────────────────────────────────────────╯

✅ 模型名称显示为配置的模型（如 gpt-5-codex）
✅ 不再出现访问 api.openai.com 的错误
✅ 不再提示 Missing environment variable

常见问题排查

1. 仍然访问 api.openai.com

检查清单：

顶层配置是否包含 model_provider = "proxy"
base_url 是否正确（包含 /v1/ 路径）
启动界面显示的模型是否与配置一致

2. Missing environment variable 错误

检查清单：

环境变量是否已设置：echo $OPENAI_API_KEY
是否已执行 source ~/.bashrc
如果使用新终端，确认 ~/.bashrc 中已添加 export 语句

3. Model metadata not found 警告

这是一个警告而不是错误，不影响使用：

⚠ Model metadata for `gpt-5-codex` not found. Defaulting to fallback metadata

Codex 会使用备用的元数据继续工作。

总结

关键配置要点

配置优先级：顶层配置优先级高于 [defaults] 配置
- 必须在顶层同时指定 model_provider 和 model
base_url 路径：OpenAI 兼容 API 通常需要 /v1/ 路径
- 使用 curl 测试端点可用性
wire_api 值：Codex 只支持 "responses"
- 不支持 "openai" 等其他值
环境变量：env_key 配置指定从环境变量读取 API key
- 不从 auth.json 文件读取
字符编码：注意配置文件中的特殊字符
- 确保使用标准 ASCII 连字符（-）

注意事项

安全提醒

⚠️ 不要将 API key 硬编码在配置文件中
⚠️ 不要将包含 API key 的 .bashrc 提交到版本控制
⚠️ 定期更换 API key

兼容性

本指南基于 Codex v0.144.1
不同版本的配置格式可能有差异
建议查看官方文档确认最新配置方式

配置检查脚本

可以使用以下脚本快速检查配置：

#!/bin/bash

echo "=== Codex 配置检查 ==="
echo ""

# 检查配置文件
if [ -f ~/.codex/config.toml ]; then
    echo "✓ config.toml 存在"
    
    # 检查关键配置
    if grep -q "model_provider.*=.*\"proxy\"" ~/.codex/config.toml; then
        echo "✓ model_provider 已配置"
    else
        echo "✗ model_provider 未配置或不正确"
    fi
    
    if grep -q "base_url.*=.*\"/v1/\"" ~/.codex/config.toml; then
        echo "✓ base_url 包含 /v1/ 路径"
    else
        echo "⚠ base_url 可能缺少 /v1/ 路径"
    fi
else
    echo "✗ config.toml 不存在"
fi

echo ""

# 检查环境变量
if [ -n "$OPENAI_API_KEY" ]; then
    echo "✓ OPENAI_API_KEY 环境变量已设置"
else
    echo "✗ OPENAI_API_KEY 环境变量未设置"
fi

echo ""
echo "=== 检查完成 ==="

结语

配置 Codex 使用自定义服务器看似简单，但实际过程中会遇到各种细节问题。本文记录的排查过程涵盖了从基础配置错误到配置优先级的各个层面。

希望这份指南能帮助你快速解决类似问题，节省排查时间。

核心要记住的一点：当 Codex 仍然访问 api.openai.com 时，首先检查顶层配置是否包含 model_provider，这是最容易被忽略的关键配置。

文档生成日期：2026-07-11
适用版本：Codex v0.144.1

posted @ 2026-07-11 13:31 youdias 阅读(201) 评论(0) 收藏举报

刷新页面返回顶部

youdias

Codex自定义服务器配置排查指南

Codex 自定义服务器配置排查指南

问题背景

问题现象

配置文件位置

排查步骤

步骤 1：检查基础配置

问题 1：模型名称包含特殊字符

问题 2：base_url 路径不完整

问题 3：wire_api 配置值错误

步骤 2：验证服务器支持的模型

步骤 3：配置优先级问题（关键！）

步骤 4：环境变量配置

最终解决方案

完整的 config.toml 配置

环境变量配置

验证和测试

启动 Codex

预期结果

常见问题排查

1. 仍然访问 api.openai.com

2. Missing environment variable 错误

3. Model metadata not found 警告

总结

关键配置要点

注意事项

安全提醒

兼容性

配置检查脚本

结语

公告