配置 AI 模型 API Key：从环境变量到接口验活
简答：配置 AI 模型 API Key 的核心是同时确认三项：API Key 用于鉴权，Base URL 决定请求发往哪里，Model ID 决定调用哪个模型。最稳妥的顺序是先把 Key 放进环境变量，再用 /models 或最小请求验证连通性、鉴权和模型权限，最后复制到 Cursor、Dify 或自己的代码中。
定义：AI 模型 API Key 是调用模型接口时使用的鉴权凭证，通常需要与正确的 Base URL、请求协议和 Model ID 配套使用。
先记住“三要素公式”：API Key + Base URL + Model ID
本站为第三方指南，非任何 AI 服务官方，以其官网文档为准。配置 API 时不要只粘贴一串 Key；真正决定请求能否成功的是 API Key、Base URL 和 Model ID 三项是否匹配。
| 配置项 | 作用 | 常见填写方式 | 填错后的表现 |
|---|---|---|---|
| API Key | 证明请求具备调用权限 | sk-...、平台生成的密钥或其他格式 | 401、403、鉴权失败 |
| Base URL | 指定 API 服务入口 | 官方地址或兼容网关提供的接口地址 | 404、连接失败、路径重复 |
| Model ID | 指定具体模型 | gpt-...、claude-...、gemini-... 或网关公布的模型名 | 模型不存在、无权限或参数不支持 |
以 OpenAI API 为例，官方文档要求使用 Bearer 鉴权，并建议把 Key 从环境变量或密钥管理服务读取，而不是暴露在浏览器、移动应用或源代码中；官方 REST API 的基础路径使用 v1。可查看 OpenAI API 鉴权与调试文档。
不同厂商的协议不能只靠替换域名解决。例如 Gemini REST 请求使用 x-goog-api-key，而不是 OpenAI 的 Authorization: Bearer；具体请求格式应以对应的 Gemini API Reference 为准。
第一步：先设置临时环境变量并检查是否存在
临时环境变量适合先验证配置。它只对当前终端会话及其启动的子进程生效；如果你关闭终端、重启 IDE，或从桌面图标重新打开客户端，变量可能不会自动存在。
macOS/Linux：Bash 或 Zsh
export OPENAI_API_KEY='替换为你的_API_Key'
export OPENAI_BASE_URL='https://api.openai.com/v1'
export OPENAI_MODEL='替换为可用的模型名'
test -n "$OPENAI_API_KEY" && echo 'OPENAI_API_KEY 已设置' || echo 'OPENAI_API_KEY 未设置'
printf '%s\n' "$OPENAI_BASE_URL"
printf '%s\n' "$OPENAI_MODEL"验证时只输出变量是否存在或输出 Base URL、模型名，不要使用 echo "$OPENAI_API_KEY" 打印完整密钥。
Windows PowerShell
$env:OPENAI_API_KEY = '替换为你的_API_Key'
$env:OPENAI_BASE_URL = 'https://api.openai.com/v1'
$env:OPENAI_MODEL = '替换为可用的模型名'
if ($env:OPENAI_API_KEY) {
Write-Output 'OPENAI_API_KEY 已设置'
} else {
Write-Output 'OPENAI_API_KEY 未设置'
}
$env:OPENAI_BASE_URL
$env:OPENAI_MODEL$env: 设置只对当前 PowerShell 会话有效。需要让新终端、IDE 或系统服务读取时，应使用系统环境变量、项目启动配置或安全的 Secret 管理方式。
Windows CMD
set OPENAI_API_KEY=替换为你的_API_Key
set OPENAI_BASE_URL=https://api.openai.com/v1
set OPENAI_MODEL=替换为可用的模型名
if defined OPENAI_API_KEY (echo OPENAI_API_KEY 已设置) else (echo OPENAI_API_KEY 未设置)第二步：项目级 .env 配置与持久化注意事项
如果 API Key 只服务于一个项目，项目级配置通常比写入全局 Shell 配置更容易隔离。可以在项目根目录创建 .env：
OPENAI_API_KEY=替换为你的_API_Key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=替换为可用的模型名同时在 .gitignore 中加入：
.env
.env.*
!.env.example可以提交不含真实密钥的 .env.example，但不要把真实 Key 写入 Git、日志、Issue、截图或前端打包产物。Google Gemini 官方文档同样建议把密钥视为密码，避免提交到源代码，并建议生产环境使用 Secret Manager 等安全存储；具体做法可参考 Google Gemini API Key 使用与安全说明。
需要注意：仅仅创建了 .env 文件，并不意味着所有程序都会自动读取它。Python、Node.js、IDE 插件和桌面客户端是否加载 .env，取决于它们自身的配置或依赖库。遇到“终端能用、客户端不能用”时，优先检查客户端是否支持环境变量，以及它是从哪个进程启动的。
第三步：用一行 cURL 先验活，再配置客户端
先验证接口，再把参数填入工具，可以把问题拆成三类：网络是否通、Key 是否有效、模型是否可用。下面示例适用于 OpenAI 风格的 /v1/models 接口；如果你使用的是其他协议或兼容网关，应以该服务公布的路径和请求头为准。
Bash：查询模型列表
curl -i --fail-with-body "$OPENAI_BASE_URL/models" \
-H "Authorization: Bearer $OPENAI_API_KEY"--fail-with-body 需要较新的 curl 版本；不支持时可以去掉该参数，但保留 -i 观察 HTTP 状态码。OpenAI 官方文档提供了使用 Bearer 鉴权请求 /v1/models 的示例，可对照 官方 API Reference。
PowerShell：查询模型列表
$headers = @{
Authorization = "Bearer $env:OPENAI_API_KEY"
}
$response = Invoke-RestMethod `
-Method Get `
-Uri "$env:OPENAI_BASE_URL/models" `
-Headers $headers
$response最小对话请求：验证模型权限
curl -i "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d "$(printf '%s' '{"model":"'"$OPENAI_MODEL"'","messages":[{"role":"user","content":"Reply with OK"}],"max_completion_tokens":16}')"如果服务只支持 Responses API、Anthropic Messages 或 Gemini 原生协议，不能直接套用上述路径。此时应先确认客户端使用的 wire protocol，再分别填写 Endpoint、鉴权头和请求体字段。
Base URL 后面到底要不要加 /v1？
没有一个适用于所有服务的固定答案，关键是看客户端会不会自动拼接路径。判断方法是先看客户端字段说明，再观察它实际发出的请求 URL。
| 客户端行为 | Base URL 示例 | 最终请求示例 | 注意事项 |
|---|---|---|---|
客户端直接在 Base URL 后拼接 /models | https://api.example.com/v1 | https://api.example.com/v1/models | 通常应保留 /v1 |
客户端自动拼接 /v1/models | https://api.example.com | https://api.example.com/v1/models | 不要再手动填 /v1 |
| 服务商提供完整 Endpoint | 按文档填写 | 以服务商示例为准 | 不要凭经验改路径 |
| Anthropic 原生协议 | 不等同于 OpenAI 兼容地址 | 通常请求 /v1/messages | 需要 x-api-key 和版本头 |
最典型的错误是把 https://api.example.com/v1 填入一个会自动增加 /v1 的客户端，最终请求变成 /v1/v1/... 并返回 404。反过来，若客户端不会自动拼接而你省略了版本路径，也可能返回 404。不要只修改 Key；应在开发者工具、调试日志或服务端请求记录中确认最终 URL。
常见错误码：按“地址—鉴权—模型—限流”顺序排查
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 400 Bad Request | 请求体字段、JSON 格式、协议是否匹配 | 对照官方请求示例，删掉客户端额外添加的未知字段，再逐项恢复 |
| unsupported_parameter | 参数是否被当前模型或接口支持 | 检查 max_tokens、max_completion_tokens、工具参数和响应格式字段，按当前接口文档调整 |
| 401 Unauthorized | Key 是否为空、过期、复制错误或请求头格式错误 | 确认变量存在，检查是否使用了 Authorization: Bearer 或目标协议要求的鉴权头 |
| 403 Forbidden | 项目、权限、来源限制或模型访问资格 | 登录服务控制台核对项目权限、Key 限制和模型资格 |
| 404 Not Found | Base URL、/v1、Endpoint 或模型名 | 打印最终请求 URL，排除 /v1/v1、网页首页地址和错误路径 |
| 429 Too Many Requests | RPM、TPM、并发或账户额度 | 降低并发、缩短输入、按服务商规则重试，并查看响应头中的限流信息 |
| 超时或流式中断 | 网络、代理、客户端超时和流式协议支持 | 先用非流式最小请求验证，再逐步启用流式、工具调用和较长上下文 |
OpenAI 官方调试文档说明，响应头可能包含请求 ID 和限流相关信息；排查时保留状态码、响应体和请求 ID，但不要记录完整 API Key。若使用 Gemini，官方也提供了针对 Key 被阻断或泄露后的排查说明，可参考 Gemini API Troubleshooting。
配置到 Cursor、Dify 或代码项目时的安全清单
- 先验活：使用最小请求确认 Key、Base URL 和 Model ID 有效。
- 再配置：把同一组参数填入客户端，不要把网页后台地址当作 API Base URL。
- 避免前端暴露：浏览器、移动应用和公开网页中不要直接放生产 API Key，应通过后端代理调用。
- 隔离密钥：开发、测试、生产尽量使用不同 Key，便于撤销和定位用量。
- 控制日志：日志中只保留 Key 的前后少量字符或哈希，不输出完整值。
- 发现泄露后轮换：先创建新 Key 并部署验证，再禁用或删除旧 Key，同时检查用量和账单。
OpenAI 文档明确建议不要在客户端代码中暴露 API Key；Google Gemini 文档也建议生产环境通过后端或安全的密钥存储保护 Key。具体权限、限额、模型可用性和计费规则会随平台及账户变化，配置前应以对应官方文档和控制台显示为准。
常见问题
API Key 配好了，为什么还是返回 401？
先确认环境变量确实存在，再确认请求头格式。OpenAI 风格接口通常使用 Authorization: Bearer 加 Key；其他协议可能要求不同的鉴权头。还要检查是否把带引号、空格或换行一起复制进了变量。
Base URL 应该填写到 /v1 吗？
取决于客户端是否自动拼接版本路径。如果客户端直接在 Base URL 后加 /models 或 /chat/completions，通常需要把接口要求的 /v1 填进去；如果客户端自动拼接 /v1，就不要重复填写。以实际请求 URL 和服务文档为准。
为什么终端能调用，Cursor 或其他客户端不能调用？
终端中的临时变量只对当前会话和其子进程生效，桌面客户端可能不会继承它。请检查客户端的 Key、Base URL 和模型字段，确认客户端支持的协议，并在重启客户端后重新验证。
可以把 API Key 写进前端 JavaScript 吗？
不建议。浏览器或移动应用中的 Key 可以被用户提取，生产环境应让后端读取密钥并代为调用 API。若 Key 已经提交到公开仓库或打包文件，应立即轮换并检查用量。
如何判断是模型名错误还是 Base URL 错误？
先请求模型列表或查看服务商控制台中的模型目录。如果 /models 本身返回 404，优先检查 Base URL 和 /v1；如果模型列表能返回但对话请求提示模型不存在或无权限，再检查 Model ID 和账户资格。
使用第三方兼容网关时能否直接照抄官方 OpenAI 配置？
只能借用 OpenAI 兼容接口的字段思路，不能默认路径、鉴权头、模型名和参数完全一致。第三方网关的 Base URL、模型映射、限速和支持的请求协议应以其公开文档或控制台为准；无法核实的字段不要自行推断。