我终于把 Codex 的 API 配置理顺了：从踩坑到跑通

md 复制代码

# Codex 配置 OpenAI-compatible API 的实践记录

最近在本地使用 Codex 做代码阅读和辅助开发时，整理了一下自定义 API Provider 的配置流程。

这篇文章主要记录一次配置过程，内容包括：

- OpenAI-compatible API 的基本概念
- Python SDK 最小调用测试
- Codex 配置文件示例
- 多套配置切换思路
- 常见错误排查

1. OpenAI-compatible API 是什么

很多开发工具在接入大模型时，会使用类似 OpenAI API 的请求格式。

一个常见的请求通常包含三个核心信息：

text 复制代码

API Key
Base URL
Model Name


其中：

```text
API Key：用于身份认证
Base URL：接口地址
Model Name：调用的模型名称

如果某个接口兼容 OpenAI API 格式，那么在很多 SDK 或开发工具里，都可以使用类似的配置方式。

2. 为什么先做最小调用测试

在配置 Codex 之前，建议先用 Python 写一个最小示例，确认接口本身可以正常访问。

这样可以把问题拆开：

text 复制代码

如果 Python 示例都无法调用，说明问题大概率在 Key、Base URL 或 Model Name。
如果 Python 示例可以调用，再去检查 Codex 配置。

这样排查会更清晰。

3. Python 最小调用示例

先安装依赖：

bash 复制代码

pip install openai

示例代码：

python 复制代码

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL"
)

response = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[
        {"role": "user", "content": "用一句话说明什么是 API"}
    ]
)

print(response.choices[0].message.content)

如果希望避免把 Key 写在代码里，可以使用环境变量：

python 复制代码

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("OPENAI_BASE_URL")
)

response = client.chat.completions.create(
    model=os.getenv("OPENAI_MODEL"),
    messages=[
        {"role": "user", "content": "用一句话说明什么是 API"}
    ]
)

print(response.choices[0].message.content)

PowerShell 临时设置环境变量：

powershell 复制代码

$env:OPENAI_API_KEY="YOUR_API_KEY"
$env:OPENAI_BASE_URL="YOUR_BASE_URL"
$env:OPENAI_MODEL="YOUR_MODEL_NAME"

4. Codex 配置文件位置

Codex 的配置通常放在用户目录下：

text 复制代码

~/.codex/config.toml

Windows 下大致对应：

text 复制代码

C:\Users\你的用户名\.codex\config.toml

如果只希望某个项目单独使用配置，也可以在项目目录中使用本地配置文件。

实际路径和支持字段可能会随版本变化，建议以当前工具文档为准。

5. 配置 Provider 示例

下面是一个自定义 Provider 的示例。

toml 复制代码

model = "YOUR_MODEL_NAME"
model_provider = "custom"

[model_providers.custom]
name = "Custom Provider"
base_url = "YOUR_BASE_URL"
env_key = "OPENAI_API_KEY"

这里的含义是：

text 复制代码

model：默认使用的模型名称
model_provider：当前使用的 provider 名称
base_url：接口基础地址
env_key：从哪个环境变量读取 API Key

对应的 PowerShell 环境变量：

powershell 复制代码

$env:OPENAI_API_KEY="YOUR_API_KEY"

配置完成后，可以进入项目目录运行 Codex，并让它做一个简单任务：

text 复制代码

请阅读当前项目结构，并简要说明每个主要目录的作用。

如果能够正常返回，说明基础配置已经生效。

6. 多套配置的管理思路

如果只使用一套配置，手动维护 config.toml 就足够了。

但实际开发中，可能会遇到这些情况：

text 复制代码

不同项目使用不同模型
测试环境和正式环境分开
临时切换不同接口
对比不同模型的输出效果

这时可以考虑使用配置切换工具，把多套配置保存成不同 profile。

例如：

text 复制代码

profile-dev
profile-test
profile-fast
profile-default

每个 profile 中保存：

text 复制代码

Base URL
Model Name
环境变量名称
Provider 名称

这样切换时只需要选择对应 profile，不必每次手动修改配置文件。

7. 常见问题排查

7.1 API Key 无效

如果看到类似错误：

text 复制代码

401
unauthorized
invalid api key

优先检查：

text 复制代码

Key 是否复制完整
前后是否包含空格
当前环境变量是否生效
是否使用了错误的 Key

在 PowerShell 中可以查看环境变量：

powershell 复制代码

echo $env:OPENAI_API_KEY

7.2 Base URL 不正确

常见问题包括：

text 复制代码

路径缺少 /v1
协议写错
地址末尾多了空格
使用了错误的接口域名

例如：

text 复制代码

https://example.com/v1

和：

text 复制代码

https://example.com

可能对应不同的请求路径。

具体格式应以对应接口文档为准。

7.3 模型名错误

模型名通常需要和接口支持的名称完全一致。

例如：

text 复制代码

model-a
model-a-latest
model-a-mini

这些可能是不同模型，不能随意简写。

如果返回模型不存在，优先检查模型名。

7.4 环境变量未生效

如果是在 PowerShell 里临时设置环境变量：

powershell 复制代码

$env:OPENAI_API_KEY="YOUR_API_KEY"

它通常只对当前终端会话生效。

关闭终端后，需要重新设置。

如果希望长期生效，可以配置系统环境变量，或者使用工具统一管理。

8. 一个推荐的排查顺序

我个人比较推荐按下面顺序排查：

text 复制代码

1. 先确认 API Key、Base URL、Model Name 是否正确
2. 用 Python SDK 写最小示例测试
3. Python 能跑通后，再配置 Codex
4. 检查 Codex 是否读取到了正确的配置文件
5. 如果有多套配置，确认当前 profile 是否正确

不要一开始就同时修改多个地方。

配置类问题最怕多个变量一起变，最后很难判断到底是哪一步出错。

9. 使用建议

对于刚开始接触 AI 编程工具的新手，可以先从小项目测试。

例如：

text 复制代码

让 Codex 阅读一个简单项目
让它解释一个函数
让它补充一个测试
让它修改一个明确的小 bug

不建议一开始就把复杂项目、隐私数据或重要业务代码直接交给工具处理。

另外，API Key 不要写进公开仓库，也不要出现在截图和文章中。

10. 总结

本文记录了 Codex 配置 OpenAI-compatible API 的基本流程：

text 复制代码

先用 Python SDK 验证接口
再配置 Codex Provider
最后根据需要管理多套配置

这个流程的好处是排查清晰。

如果最小调用成功，说明接口层基本正常；如果 Codex 仍然无法使用，就可以重点检查配置文件、环境变量和模型名称。

对新手来说，先把最小链路跑通，比一开始研究复杂工作流更重要。