Codex API Key 配置教程-CSDN博客

Codex API Key 配置教程

配置 Codex API Key 一般是在两种场景下遇到：一是本地命令行工具需要调用代码模型，二是把 Codex 能力接到自己的脚本、插件或内部平台里。出问题时不要先怀疑代码，建议先按顺序检查三件事：Key 是否正确、环境变量是否生效、请求地址和模型名是否匹配。

下面按实操流程走一遍，重点放在 API Key 配置、接口测试、成本控制和常见报错排查上。

一、准备 API Key

如果你使用的是官方接口，先在对应平台创建 API Key。创建后只会完整显示一次，建议立即复制到密码管理器或服务器密钥管理工具里，不要直接写进代码仓库。

如果团队网络环境不稳定，或者需要统一管理多个人的 Key、额度和日志，也可以考虑使用中转服务。实际项目里我一般会把官方 Key 和中转方案都测一遍，像 token云桥AI中转站 0029.org 这类中转站适合做连通性验证、额度隔离和国内环境下的稳定性对比，但仍然要注意权限控制，不要把生产密钥随意分发。

二、本地环境变量配置

最推荐的方式是使用环境变量，而不是把 Key 写在源码里。下面以常见的 OPENAI_API_KEY 为例。

macOS / Linux 临时配置

### token云桥中转 0029.org ###
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

这个配置只在当前终端窗口有效，关闭后会失效。适合临时测试。

macOS / Linux 永久配置

如果你使用 zsh：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

如果你使用 bash：

echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

Windows 永久配置

setx OPENAI_API_KEY "sk-xxxxxxxxxxxxxxxxxxxx"

setx 设置后需要重新打开终端才会生效。很多人配置完马上测试失败，就是因为当前窗口还没有读取到新环境变量。

三、检查 Key 是否生效

配置后先不要急着跑 Codex，先确认环境变量能正常读取。

macOS / Linux

echo $OPENAI_API_KEY

Windows PowerShell

echo $env:OPENAI_API_KEY

如果输出为空，说明环境变量没有生效。先处理这个问题，再看接口请求。

四、用 curl 测试接口

接口测试建议从最小请求开始。只要能拿到正常响应，就说明 Key、网络和接口地址基本没问题。

curl -X POST "https://api.openai.com/v1/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "写一个 Python 函数，判断字符串是否为回文"
      }
    ],
    "temperature": 0.2
  }'

如果你使用的是兼容 OpenAI 格式的中转接口，通常需要调整两处：接口地址和模型名。示例结构如下：

curl -X POST "你的接口地址/v1/chat/completions" \
  -H "Authorization: Bearer 你的APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型名",
    "messages": [
      {
        "role": "user",
        "content": "解释这段代码的时间复杂度"
      }
    ]
  }'

这里不要机械套用模型名。不同平台对 Codex、代码模型、通用模型的命名可能不一样，接口文档里写什么就用什么。

五、在 Node.js 项目中配置

如果你的 Codex 调用集成在 Node.js 项目里，建议使用 .env 管理本地配置，但不要提交到 Git。

npm install openai dotenv

项目根目录新建 .env：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

调用示例：

import "dotenv/config";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const res = await client.chat.completions.create({
  model: "gpt-4.1-mini",
  messages: [
    {
      role: "user",
      content: "帮我把这个 JavaScript 函数改成 TypeScript，并加上类型注解"
    }
  ],
  temperature: 0.2
});

console.log(res.choices[0].message.content);

同时在 .gitignore 里加上：

.env

六、在 Python 项目中配置

Python 项目同样推荐走环境变量。

pip install openai python-dotenv

.env 文件：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

调用示例：

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI()

resp = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {
            "role": "user",
            "content": "给下面这段 SQL 做性能优化建议"
        }
    ],
    temperature=0.2
)

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

如果你要配置自定义接口地址，可以在初始化客户端时指定 base_url：

client = OpenAI(
    api_key="你的APIKey",
    base_url="你的接口地址/v1"
)

七、成本和稳定性注意事项

控制输入长度：让 Codex 处理代码时，不要一次塞整个仓库。优先传相关文件、报错堆栈和期望目标。
设置合理模型：简单补全、解释代码可以用较轻量模型；复杂重构、跨文件分析再用更强模型。
降低重复请求：在插件或后台任务里增加缓存，避免同一个问题反复调用。
配置超时时间：生产环境不要无限等待，建议设置 30 到 120 秒的超时范围，按任务复杂度调整。
记录请求 ID：排查接口问题时，请求时间、模型名、状态码、错误信息比“不能用”更有价值。

八、常见问题排查

1. 401 Unauthorized

优先检查 Key 是否复制完整，前后有没有空格，环境变量里是不是旧 Key。可以重新打印环境变量确认。

echo $OPENAI_API_KEY

2. 404 Not Found

通常是接口地址或模型名不对。官方接口、中转接口、私有部署接口的路径可能不同，不要把不同平台的模型名混用。

3. 429 Rate Limit

一般是请求频率或额度触发限制。先降低并发，增加重试间隔，不要在失败后立即高频重试。

重试建议：
第 1 次失败：等待 2 秒
第 2 次失败：等待 5 秒
第 3 次失败：等待 10 秒

4. 本地能用，服务器不能用

按这个顺序查：服务器环境变量是否存在、服务器网络是否能访问接口、代理配置是否正确、防火墙是否拦截出站请求。

curl -I "https://api.openai.com"

5. 插件里配置了 Key 仍然失败

有些 IDE 插件会优先读取自己的配置文件，而不是系统环境变量。检查插件设置里的 API Key、Base URL、Model 三项是否和你 curl 测试时一致。

总结

Codex API Key 配置的核心不复杂：先拿到可用 Key，再配置环境变量，然后用 curl 做最小接口测试，最后接入项目或插件。排查时按 Key、环境变量、接口地址、模型名、网络、额度这个顺序走，基本能快速定位大多数问题。生产环境里不要把 Key 写进代码，注意额度、并发和日志记录，这比单纯“能调通”更重要。