openai api key 接入指南

很多开发者第一次接 OpenAI，卡的不是写代码，而是 Key 放在哪、环境变量怎么设、请求发出去报 401 或 404 该往哪查；也有人跑通了却在上线后踩超时、并发和费用的坑。这篇按「拿到 Key → 落地存放 → 发第一个请求 → 验证 → 出问题怎么查 → 上线前收敛」的顺序给一套可执行动作，不承诺一次就通，但保证每一步都能自己验。

第一次接 OpenAI，卡住人的通常不是「怎么发请求」这种大问题，而是 Key 该从哪儿拿、放在哪、为什么一跑就 401 或者 404。把请求发出去只是起点，真正费时间的是后面那些看起来像玄学的问题：环境变量明明设了却不生效、本地能跑线上不行、跑通了也不知道自己这次花了多少。这篇就按「拿到 Key → 落地存放 → 发第一个请求 → 验证 → 出问题怎么查 → 上线前收敛」这个顺序，给一套能一步步自己验的动作。

先说清楚预期：这里不给一个「照着抄就一定通」的脚本，因为不同系统、不同网络环境、不同账号权限下表现都不一样。但每一步后面都告诉你怎么判断自己这步到底过没过——这比背命令有用。下面涉及具体数值和价格的地方，都写成了去站内页面核对当时的值，因为那些数字一直在变，写死反而误导你。

先搞清楚 Key 从哪来、有几个坑

Key 本质是账号下的一个凭据，不是你项目里的配置项。所以第一件事不是复制粘贴，而是知道自己是在哪个组织、哪个项目下面创建的这把 Key。不同组织下的 Key 作用域不一样，A 组织的 Key 拿去调 B 组织下的资源，大概率直接失败，而且报错信息未必直白告诉你原因。接之前先确认自己在哪个组织里操作。

• 一把 Key 对一个用途，别全项目共用一把；后面要限流、要吊销、要算账都靠这个粒度
• 创建时顺手把权限范围和额度上限设上，尤其是只读或限定用途的场景；超出范围的调用会被直接拒掉，别等线上报错才发现
• 同一把 Key 如果会被多人或多服务共用，提前约定谁用哪块、谁负责吊销，别等出事互相不知道
• 拿到后先肉眼比一遍首尾字符和长度，确认复制完整——前后空格、换行、被聊天软件自动加粗，都是常见脏数据

Key 存哪儿：环境变量的正确写法

本地开发统一走环境变量这条路，不要写死在代码里，也不要把带 Key 的配置文件提交进仓库。动手之前先确认 .gitignore 已经覆盖了 .env 这一类的文件，这一步花十秒，能省掉后面一次尴尬的泄露处理。已经提交过的，光加 ignore 不够，历史记录里还留着，需要单独处理。

1. 按系统设变量类 Unix 系统写在 shell 配置里或启动时注入，Windows 用系统环境变量面板或 IDE 的运行配置里填。两种方式都行，关键是别混用——在 IDE 里能跑、终端里不能跑，八成就是两个地方各设了一套。
2. 新开终端验证设完变量后必须新开一个终端，旧终端不会自动加载新值。在终端里回显一下这个变量，看到的是你期望的字符串才算生效，看不见或者为空就是没设上。
3. 区分「不存在」和「为空」代码读取变量时这两种情况要分开处理：变量压根不存在，应该在启动阶段就抛错退出；变量存在但是空串，说明配置写错了，也该拦下来。别让请求带着空串出去，那样你会收到一个鉴权错误，但真正的问题在配置。
4. 泄露就吊销换新Key 一旦出现在前端代码、移动端包体或公开仓库里，就当作已泄露处理，直接去后台吊销换一把，别指望改回来就没事。

# 类 Unix：写入 shell 配置后，新开终端再做一次确认
export OPENAI_API_KEY="你的key"
# 用这行验证变量真的进去了（只打印长度，别打印完整值）
echo ${#OPENAI_API_KEY}

发第一个请求：最小可跑通的一段

第一次请求的目标只有一个：证明链路通的。所以别一上来就套框架、接业务逻辑，先用官方 SDK 或者一次 curl 打完。请求体里只留模型选择和一句最简单的输入，其他参数全部先不加。参数越少，出问题时变量越少。

• 接口地址先按官方默认走，确认通了再考虑改动；地址写错最典型的表现就是找不到接口，写法纠正可以到 /openai-api-base-url-guide 对照
• 返回结果先看两类东西：结构对不对（有没有你预期的字段），用量字段有没有正常返回——后者决定你后面能不能算账
• 把这次用的最小命令或脚本原样存下来，换环境、换网络、怀疑链路时它是你的基准，比重装依赖快得多
• 如果这一步用了代理，代理配置也一起记下来；后面「本地能跑线上不行」的问题，十次里有几次就卡在这

跑通之后：做一次可复现的验证

一次成功不算数，能重复成功才算。最容易做的验证是换一台机器或者新开一个终端，用同一段脚本再跑一遍。能跑通说明问题在代码层面可控；跑不通，就往环境变量和网络方向查，因为差异只可能在那两处。这一步花的时间，比后面在线上猜要值。

• 客户端统一记录请求耗时、状态码、用量这几项，日志字段怎么选可以参考 /api-log-fields-replay，别等出问题才想起来没记
• 延迟基线先量一次，哪怕只是粗略感觉，后续觉得慢的时候好歹有个参照物；站内 /tools/speed-test 可以帮你把这条线画出来
• 验证脚本留在仓库里当冒烟测试，改配置或换地址之后先跑它，一分钟内有结论
• 如果团队里不止一个人接这个服务，把「怎么跑这个脚本」写进仓库说明里，别只存自己脑子里

日志这件事值得提前设计，而不是出事后补。至少要有状态码、耗时和用量三样，缺一样都会让你在某次排查里多绕一圈。用量字段尤其重要，它既是排错线索，也是后面成本核算的唯一依据。

第一次接最常见的几类报错，按这个顺序查

第一次接报错，最忌讳随机改配置。改一圈下来可能同时引入了两三个新问题，反而更难定位。正确做法是固定一个排查顺序：先鉴权，再地址，再网络，最后才是请求体。这个顺序从外往内，前面的没排除干净，后面查了也是白查。

1. 先冻结配置报错时不要边查边改，先把当前配置原样记下来（变量、地址、命令），后面要靠它对比。
2. 按顺序排除鉴权 → 地址 → 网络 → 请求体，一轮只动一个变量，动完立刻重跑基准脚本。
3. 区分鉴权和权限鉴权问题是「你是谁」没答上来，权限问题是「你不该做这个」，两者的修法完全不同，混在一起查会绕远。
4. 留下排查记录这次改了哪一项、结果如何，简单记两行；团队里第二个人遇到同样问题就不用从头再来。

上线前先把超时和并发定下来

本地跑通和线上能扛，中间隔着一整套取值问题。超时不是设一个数就完了，它至少分三层：建立连接、等待读取、整个请求的总时长。长文本生成和短问答用同一套超时值，要么短任务被拖死，要么长任务永远被截断。分档怎么定可以到 /api-timeout-tuning 找依据。

• 并发不要一上来拉满，先按账号可用额度设一个小上限，跑到稳定再逐步加；触发限流之后的恢复节奏看 /api-rate-limit-recovery
• 重试要有次数上限和退避，而且只对可重试的错误重试——对参数错误重试一百次也不会成功
• 批量任务的分批方式和失败重投逻辑，参考 /batch-concurrency-throttle-guide，别用递归重投把自己打爆
• 准备上流式之前先读 /streaming-sse-production，把断流和首字慢当成已知项来处理，而不是当故障

这里有个判断标准：如果你说不清楚当前每层超时分别是多少、为什么是这个值，那就还没到能上线的状态。取值不需要一步到位，但必须有一个明确的起点和调整依据，而不是留系统默认值一直跑。

别让第一版就把额度烧光

成本问题拖到月底看账单就晚了，因为那时候你既不知道钱花在哪个功能上，也不知道该怎么改。从第一天起就记录每次调用的用量，并按功能和调用方拆开。只记总数的话，出账时你只能看到一个数字，没法定位到具体模块。

• 按功能和调用方拆开记用量，不然出账时根本不知道钱花在哪；口径区分可以看 /token-vs-api-call-fee
• 给 Key 设额度上限是最后一道闸，尤其是面向用户的功能，闸没设就等于没上限
• 公开场景不要把 Key 放到客户端，改成自己后端转发，原因见 /browser-direct-api-cors
• 上线前做一次用量估算，按当前调用量和单次消耗推月度量级，具体数字去 /tools/model-cost-calculator 和站内成本页面算当时的值
• 同一把 Key 被多人或多服务共用时，提前约定配额和降级策略，别等被打爆才开始划分

上线前过一遍这张清单

下面这张清单建议在真正放量之前逐条对一遍。它的作用不是打勾好看，而是把前面几节里容易漏掉的项集中收口。任何一条你答不上来，就先别放量，回去补那一条对应的动作。

• Key 不在代码和前端里，能一键吊销；环境变量在部署环境里也配好了，不只是本地
• 有冒烟测试脚本，换地址或换 Key 之后一分钟内能验证
• 超时、重试、并发上限都有明确取值，不是系统默认；限流触发了有退避逻辑
• 日志里有状态码、耗时和用量；出账后能对上账，对不上知道去哪个页面查
• 鉴权或权限失败时，团队里有人知道先查什么、去哪查，而不是一个人扛