LangChain API Key 配置教程：环境变量、多模型与安全（2026）

用 LangChain 搭应用，第一步往往不是写 Chain，而是把 Key 配对。同样一段代码，有人在本地跑通、部署后 401，有人把 Key 写进 Notebook 后忘了清理。问题大多不在框架，而在 Key 的来源、加载顺序和权限边界。

本文按“来源—配置—隔离—轮换—排错”的顺序，讲清 LangChain 项目里 API Key 应该怎么管。具体模型、额度和价格，以站内模型价格页和所用服务商的文档为准。

说明：LangChain 是 LangChain, Inc. 的商标，本文仅作技术配置说明，与 LangChain, Inc. 无隶属或合作关系；各集成包的行为可能随版本调整，请以对应版本文档为准。

一、先分清：LangChain 不发放模型 Key

LangChain 是开源的应用开发框架，负责把模型、工具、检索和流程编排起来。它本身通常不附带模型调用额度，因此不存在“LangChain 的模型 Key”。你填进 LangChain 的凭证，实际属于模型服务商、云平台或 AI 网关。

项目里常见的凭证至少有三类，用途完全不同：

凭证	用途	从哪里获取
模型 API Key	调用聊天、推理、Embedding 等模型	模型服务商或 AI 网关控制台
`LANGCHAIN_API_KEY`	LangSmith 追踪与评估	LangSmith，启用观测时才需要
云平台凭证	访问托管模型或云资源	对应云厂商的访问控制台

把三类凭证混成一把，会让权限过大、轮换困难。先按用途拆开，再谈配置。

二、环境变量：默认约定与显式传参

langchain-openai 的 ChatOpenAI 默认读取 OPENAI_API_KEY，OpenAI 兼容端点则通过 base_url 参数指定。最小可用配置如下：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

# 从项目附近的 .env 读取；生产环境建议改用系统环境变量或密钥管理服务
load_dotenv()

llm = ChatOpenAI(
    model=os.environ["ZSQH_MODEL"],       # 模型 ID 以价格页为准
    api_key=os.environ["ZSQH_API_KEY"],   # 也可使用默认的 OPENAI_API_KEY
    base_url="https://ai.zhongshangqihang.com/v1",
    temperature=0,
)

print(llm.invoke("用一句话解释什么是 API 网关").content)

几个容易忽略的细节：

环境变量是在创建客户端对象时读取的，不是导入模块时。在 Notebook 里中途 os.environ 赋值后，需要重新创建 ChatOpenAI 实例。
显式传入空字符串会覆盖环境变量。排查 401 时，先看代码里有没有 api_key="" 之类的残留。
不同集成包读取的变量名不同，Anthropic、Google 各有约定，以对应文档为准。
init_chat_model 可统一创建不同服务商的模型，但额外参数和默认变量仍由底层集成决定，升级后要回归验证。

三、.env 与 SecretStr：本地开发的两道防线

本地开发用 .env 方便，但必须配合两条纪律。

第一，.env 永远不进版本库。项目初始化时就把它写进 .gitignore，同时提交一份不含真实值的 .env.example，让新成员知道需要哪些变量。如果曾经误提交，删除文件并不等于清除历史，应立刻吊销对应 Key，再处理仓库历史。

第二，认识 LangChain 的 SecretStr。ChatOpenAI 的密钥字段通常以 SecretStr 保存，打印对象或写日志时会显示为掩码，而不是明文。这能挡住一部分误输出，但挡不住主动 get_secret_value()、手动拼接请求头或在异常里打印整个请求。不要把“框架会脱敏”当成“可以随便打日志”。

容器部署时不要把 Key 写进镜像，构建参数和镜像层都可能被保留；推荐在运行时通过环境变量或密钥管理服务注入。

四、多服务商、多模型：一把 Key 还是多把？

答案取决于入口是否统一。使用 AI 网关时，通常一把网关 Key 就能调用多个模型，模型通过 model 参数区分；直连多个厂商时，则往往需要每个厂商各配一把 Key。

推荐给变量起可读的名字，并在团队内固定下来：

网关类：ZSQH_API_KEY、ZSQH_BASE_URL。
厂商类：沿用集成包约定的名称，如 ANTHROPIC_API_KEY、GOOGLE_API_KEY。
环境后缀：_DEV、_STAGING、_PROD，避免测试 Key 被带进生产。

多模型还包括回退（fallback）与路由。LangChain 可以用 .with_fallbacks() 在主模型失败时切换备用模型，但备用模型也要各自完成认证配置。不要假设“同一把 Key 能调用所有模型”：网关可能有模型白名单，厂商 Key 也可能只对部分模型开放。可用模型 ID 以模型价格页为准。

五、最小权限：按环境和用途拆 Key

Key 管理的目标不是“越少越好”，而是“边界越清楚越好”。可执行的做法：

开发、预发、生产各用独立 Key，生产 Key 不放在开发者本机。
每个应用、每个成员单独一把 Key，禁止多人共用。
给测试 Key 设更低预算，限制可用模型范围。
控制台支持 IP 白名单、额度提醒或模型白名单时，全部打开。
日志、工单和截图中只保留 Key 的末几位。

如果网关支持按 Key 统计用量，这把 Key 就能同时用于成本核算和故障定位；共用“万能 Key”则会让异常账单无法归因。

六、轮换与吊销：先建新，再切流，后吊销

建议至少每 90 天轮换一次；发生人员离职、设备丢失、配置误传或疑似泄露时立即执行。顺序不能反：

在控制台创建新 Key，命名中带上日期或版本，例如 prod-app-202610。
把新 Key 写入密钥管理服务或部署平台的环境变量。
重启或重新部署应用，确认新进程已加载新值。
发一条真实请求，确认模型正常返回且用量记在新 Key 上。
观察一段时间，确认没有遗漏的旧实例仍在调用。
确认无误后再吊销旧 Key，并更新内部台账。

从环境变量读取 Key 时，轮换通常不用改代码，但需要重启或滚动发布。长连接或常驻进程可能继续持有旧 Key，吊销前先确认实例已全部替换。

七、CI 与团队协作：别让 Key 进日志

CI 环境同时具备自动执行和日志留存，是密钥泄露的高发区。几条底线：

Key 放在 CI 平台的加密 Secret 中，不在流水线文件里明文书写。
关闭会回显命令的调试选项，避免 set -x 把请求头打印出来。
为 CI 单独建 Key，设低额度，并限制可用模型。
使用密钥扫描工具做提交前检查，发现疑似 Key 立即阻断。
代码评审时把 .env、配置文件、测试快照都当作敏感文件检查。

团队交接文档里应写清：Key 的负责人、用途、创建日期、下次轮换日期，以及离职和设备丢失时的吊销流程。

八、排错：先确认变量，再看协议

遇到认证错误，按下面顺序排查，通常比反复重建 Key 更快：

确认变量进入进程：只打印变量是否存在，不打印值。Notebook 要重启内核，容器要确认注入到了正确的服务。
检查显式覆盖：代码或配置文件里是否传了空的 api_key、错误的 base_url。
核对协议路径：OpenAI 兼容端点通常以 /v1 结尾，少一段或多一段都会 404。
核对模型 ID：展示名不等于 API 标识，逐字对照价格页。
按状态码分流：401 查 Key 本身，403 查权限与模型范围，429 查并发与额度，5xx 先重试并保留请求时间。
排查网络与代理：代理环境变量、企业网关证书都可能让请求失败，且错误信息看起来像认证问题。

一次只改一个变量。先换 Key、再换模型，能快速判断问题是“这把 Key 不行”还是“这个模型不可用”。

常见问题

LangChain 本身需要 API Key 吗？

框架本身不需要。只有调用远程模型、Embedding 服务或 LangSmith 观测服务时，才需要对应凭证。

设置了环境变量，为什么仍然返回 401？

常见原因有四个：变量只在当前终端生效、Notebook 内核未重启、代码显式传入了空 Key、以及 Key 前后带了空格或换行。先确认进程内变量存在，再检查是否被代码覆盖。

一把 Key 能同时调用多个模型吗？

取决于 Key 所属的服务。统一网关通常允许一把 Key 调用清单内的多个模型；直连厂商时每家各有 Key。即使支持多模型，也可能有白名单，以控制台权限为准。

Key 会出现在 LangSmith 的追踪记录里吗？

追踪记录主要保存输入、输出和调用链，是否包含请求头取决于集成与脱敏配置。不要把追踪平台当密钥保险箱；自定义回调、异常日志和调试代理更容易泄露请求头，启用前先检查脱敏设置。

轮换 Key 后需要改代码吗？

如果代码从环境变量或密钥管理服务读取，通常不需要改代码，只需更新值并重启或重新部署。若 Key 被硬编码在代码、Notebook 或镜像里，应先改成外部注入，再执行轮换。

下一步

LangChain 的 Key 管理可以归纳为四句话：Key 属于模型服务商而不是框架；本地用 .env，生产用密钥管理服务；按环境和用途拆 Key；轮换时先建新再吊销旧。需要统一的多模型入口、按 Key 的用量与额度管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。