怎么在 VS Code 中正确设置 Codex API Key

准备工作：获取与确认 Codex API Key 规范

Codex 是 OpenAI 旗下专用于代码生成与理解的模型系列，在开放平台中通过统一的 API 密钥体系进行认证。在进入编辑器配置之前，需要先从官方管理后台获取具备有效调用权限的密钥凭据，并确认其所属的作用域与配额状态。

登录 OpenAI 官方开发者控制台（platform.openai.com），在左侧导航进入 API Keys 页面。点击 Create new secret key，建议为当前开发环境指定一个明确的名称（例如 vscode-dev-env）。OpenAI 现已支持基于项目（Project）的精细化权限控制，优先选择仅包含 Model capabilities 读写权限的 Project API Key。

如上图所示，VS Code 本身并不直接绑定某一个远端 AI 服务，而是由运行在编辑器进程中的扩展插件读取用户凭据，通过标准的 HTTPS Authorization: Bearer <API_KEY> 请求头与服务端网关建立通信。理解这一数据流向，有助于在后续配置中选择最安全的存储层级。

推荐方案：通过 VS Code 扩展的密态存储（SecretStorage）注入

对于绝大多数开发者而言，在 VS Code 中使用 Codex 主要依托于成熟的辅助编程插件（例如 Continue、CodeGPT 或兼容 OpenAI 接口的开源代码助手）。现代高质量插件均已接入 VS Code 原生的 vscode.SecretStorage API，该机制将密钥直接委托给操作系统的钥匙串（如 macOS Keychain、Windows 凭据管理器或 Linux Secret Service），不会在工作区生成明文配置文件。

步骤一：使用快捷键调出全局命令面板

打开 VS Code，使用快捷键 Ctrl+Shift+P（macOS 用户按 Cmd+Shift+P）唤出顶部的命令面板（Command Palette）。

步骤二：执行插件对应的密钥录入指令

根据你所安装的扩展名称，在输入框中键入设置指令：

• 使用 Continue 插件：输入 Continue: Set API Key 并回车，在提供商列表中选择 OpenAI；
• 使用 CodeGPT 插件：输入 CodeGPT: Set API KEY 并回车；
• 通用 OpenAI 辅助扩展：输入 OpenAI: Set API Key 或 Preferences: Open User Settings。

步骤三：粘贴密钥并确认安全持久化

在弹出的密码掩码输入框中，粘贴此前生成的 sk-proj-... 字符串，随后按下 Enter 键完成保存。此时 VS Code 会触发系统级凭据写入，配置立即在当前会话及后续启动中生效，且不会在项目文件夹下的 .vscode/settings.json 中留下任何字符。

进阶方案：通过系统环境变量或终端配置注入

如果你需要在 VS Code 的集成终端中运行代码调试脚本、自主编写的 CLI 工具，或者某些插件默认读取全局环境变量，则可以将密钥注入到操作系统的环境变量 OPENAI_API_KEY 中。

1. macOS / Linux 系统的全局环境变量设置

打开系统终端或 VS Code 集成终端，根据当前使用的 Shell 类型（默认为 zsh 或 bash），编辑对应的启动配置文件：

# 若使用 zsh（macOS 默认）
echo 'export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 若使用 bash
echo 'export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

执行完毕后，在终端输入 echo $OPENAI_API_KEY 进行检查。如果能够正确输出以 sk- 开头的字符串，说明系统级变量配置成功。请注意：配置完成后需要完全重启 VS Code 进程，使主程序及其集成的子进程重新继承最新的环境变量上下文。

2. 仅针对 VS Code 集成终端的局部环境配置

如果不希望污染整个操作系统的全局变量，可以仅为 VS Code 的集成终端注入该变量。打开用户级 settings.json（通过命令面板搜索 Preferences: Open User Settings (JSON)），在配置对象中添加以下段落：

// macOS / Linux 终端环境注入
"terminal.integrated.env.osx": {
  "OPENAI_API_KEY": "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
},
"terminal.integrated.env.linux": {
  "OPENAI_API_KEY": "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
},
// Windows 终端环境注入
"terminal.integrated.env.windows": {
  "OPENAI_API_KEY": "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"
}

连通性验证：确认 API Key 已生效

完成配置后，必须通过一次真实请求确认鉴权链路畅通。验证过程可以分为编辑器插件验证与集成终端脚本验证两种形式。

方法一：在编辑器中触发一次代码补全或问答

在 VS Code 中新建一个测试文件 test_codex.py，输入一个简单的函数签名与注释描述：

def calculate_fibonacci(n: int) -> int:
    """计算第 n 个斐波那契数，使用动态规划避免重复计算"""
    # 

停顿光标或使用插件的快捷键唤起生成建议。如果右下角或侧边栏正常显示流式返回的代码实现，且没有弹出任何红色错误浮窗，说明身份鉴权已完全通过。

方法二：在集成终端中运行快速验证脚本

如果你使用的是 Python 开发环境，可以在终端直接运行一行指令检验网络与密钥有效性：

python3 -c "import os, urllib.request, json; req = urllib.request.Request('https://api.openai.com/v1/models', headers={'Authorization': f'Bearer {os.getenv("OPENAI_API_KEY")}', 'User-Agent': 'VSCode-Verify'}); res = urllib.request.urlopen(req); print('Authentication Success! HTTP Status:', res.status)"

示例预期输出：

Authentication Success! HTTP Status: 200

常见错误排查与安全防护总结

在实际使用过程中，若遇到接口调用无响应或提示失败，可依据下述典型特征进行定向排查。

1. HTTP 401 Unauthorized（未授权错误）

这通常表明密钥本身存在问题或权限不匹配。优先检查复制过程中是否在首尾夹带了多余的空格、换行符或特殊不可见字符；其次登录控制台检查该 Key 是否处于 Active 状态。若使用了 Project 作用域 Key，需确认该项目是否已被分配模型访问权限。

2. HTTP 429 Rate Limit / Insufficient Quota（频次超限或配额耗尽）

该错误往往与网络无关，而是由于 OpenAI 账户的预付费余额耗尽或免费体验额度过期。登录控制台进入 Settings > Billing 检查账户可用额度（Credit Balance）。此外，短时间内如果触发了过高频次的代码补全，也会触发每分钟 Token（TPM）或请求数（RPM）限制，适当放慢触发节奏即可恢复。

3. 终端提示变量为空（Key 未生效）

在 ~/.zshrc 中定义环境变量后，必须完全关闭 VS Code 主窗口并重新启动，或者在 VS Code 中执行 Developer: Reload Window（重载窗口），旧窗口开启的集成终端不会动态监听系统外部配置文件的改动。