LangChain 鉴权配置：4 步分清框架、模型与 LangSmith

木木夕 技术创作者 2026-11-01 13 阅读

LangChain 本身没有统一登录页，关键是分清模型密钥、LangSmith 密钥和框架安装。

截至 2026-10-29，LangChain 官方仓库把 LangSmith 定义为用于构建、测试和监控 LLM 应用的平台；同日的官方凭据文档又将 /auth 标为推荐入口。现在值得按凭据来源配置，是因为模型服务、追踪服务和框架代码已经明确分离，把它们混在一个“API Key”里，最容易出现代码能启动但请求或追踪失败的情况。

下文中的安装方式和界面入口来自官方仓库或官方文档；跨入口选择与排错顺序是据此整理的操作建议。

先分清：你要配置的是哪一种鉴权

LangChain 是组织模型、工具、提示词和检索器等组件的框架，本身不替你签发模型调用权限。实际使用时，至少会遇到三种不同对象：

配置对象 用来做什么 常见入口 密钥不能替代什么
模型提供商凭据 调用 OpenAI、Anthropic 等模型 Deep Agents Code 的 /auth、Shell 中的 dcode auth 或对应环境变量 不能替代 LangSmith 的追踪密钥
LangSmith 凭据 记录、调试和监控 LLM 应用 官方凭据管理器中的 LangSmith tracing 凭据 不能替代模型提供商密钥
GitHub 登录 Star、提交 Issue、管理仓库权限 GitHub Sign in 与模型调用和 LangSmith 追踪无关

这里最容易踩的坑，是看到 LangChain 页面上的 Sign in 就以为完成模型鉴权。GitHub 页面出现 “You must be signed in to change notification settings”，只说明仓库操作需要 GitHub 身份；它不会替你生成模型密钥，也不会建立 LangSmith 的追踪连接。

如果只是用 LangChain.js 写代码，可以先不登录任何平台，只需安装框架并按照所选模型集成提供商的密钥。只有需要 Deep Agents Code 的凭据管理、LangSmith 追踪或团队托管能力时，才进入下面的账号与凭据流程。

开始前准备 3 项

  1. 安装支持当前项目要求的 Node.js。 官方包 README 列出的运行环境包括 Node.js 20.x、22.x 和 24.x。在终端运行以下命令，确认输出版本属于其中一项：

    node -v

  2. 准备模型提供商账号。 至少拥有一个准备调用的模型服务账号，并能创建对应的 API Key。LangChain 只负责连接模型，不会替你提供该账号的调用额度。

  3. 确认密钥保存在哪里。 个人开发可先准备 Shell 环境变量；使用 Deep Agents Code 时，也可以直接通过凭据管理器保存。不要把密钥写进公开仓库，提交前还要检查 .gitignore 是否包含 .env。

4 步完成配置

第 1 步：安装 LangChain.js

进入项目目录后，执行官方 README 给出的安装命令：

npm install -S langchain

如果项目使用 pnpm 或 yarn，则选择对应的官方命令，不要同时安装三套包管理器：

pnpm install langchain
yarn add langchain

安装完成后检查项目依赖。运行 npm list langchain，应能看到 langchain 及其版本；若目录尚未生成 package.json，先在项目根目录执行 npm init -y，再重新安装。

第 2 步：确定这次调用需要哪些密钥

先列出代码实际使用的组件，不要把所有平台的密钥一次性塞进环境变量。

  • 只有模型调用：配置模型提供商凭据。
  • 需要在 LangSmith 查看运行记录：再配置 LangSmith tracing 凭据。
  • 使用 Deep Agents Code：它会同时管理模型提供商、Tavily 搜索和 LangSmith tracing 等凭据。
  • 通过 API 网关转发请求：还要配置网关的 Bearer 认证，而不只是模型密钥。

官方凭据文档的原文要求是：“Deep Agents Code needs an API key for each model provider you use.” 这句话中的重点是“每个模型提供商”：一个项目同时调用两个模型服务时，不能默认只配一个通用密钥。

第 3 步：在会话或 Shell 中添加凭据

使用 Deep Agents Code 时，在任意会话中输入官方推荐入口：

/auth

凭据管理器会列出已安装的模型提供商、是否已经设置环境密钥，以及可以添加的已知提供商。进入某个提供商后，可以添加或替换密钥；已经保存的密钥会跨会话保留。

非交互任务可以在 Shell 中使用：

dcode auth

官方文档说明，交互式运行推荐使用 /auth，非交互运行可以用 dcode auth 管理同一批已保存密钥。选择哪一种，不取决于密钥“更高级”，而取决于当前程序是否需要无界面启动。

如果改用环境变量，不要把真实密钥提交到 GitHub。可以在本地 Shell 中设置对应变量，再启动应用；变量名应使用该模型集成文档规定的名称。LangChain 不会自动把所有提供商统一识别成一个 API_KEY，变量名或代码中的参数名不匹配，都会让程序找不到凭据。

第 4 步：用管理器状态和一次真实调用确认

重新打开 /auth，查看对应提供商所在行。官方界面会标出密钥来源，例如：

[stored]

它表示密钥已经保存在凭据管理器中；[env: ...] 表示当前使用的是环境变量。如果提供商行没有显示任何凭据来源，先进入该提供商添加密钥，不要继续等到业务代码报错。

随后执行程序中最小的真实请求：只发送一条短文本，并确认返回内容。只有模型请求成功，才能证明模型密钥可用；如果模型调用成功但 LangSmith 中没有对应记录，再检查 LangSmith tracing 凭据和追踪开关。两个问题要分开验证，不能用“模型能回复”推断“追踪已经配置好”。

三个真实卡点：报错原文与处理方法

卡点一：把 GitHub 登录当成模型登录

GitHub 仓库页面会显示：

You must be signed in to change notification settings

这只针对修改通知设置等 GitHub 仓库操作。处理方法是：GitHub 登录用于管理仓库；模型调用必须另行配置提供商密钥；需要追踪时再单独配置 LangSmith 凭据。

卡点二：模型请求启动后找不到凭据

官方凭据文档明确写明：

Deep Agents Code needs an API key for each model provider you use.

处理方法是进入 /auth，逐项检查本次会调用的每个提供商，并为缺失项添加或替换密钥。随后用一条最小请求验证，不要仅凭程序启动成功判断鉴权成功。

卡点三：同一个密钥同时存在于多个位置

官方文档说明，同一个密钥出现在多个位置时，应按 “Key resolution order” 判断哪个来源生效。可执行的处理方式是先运行 /auth，查看该提供商显示的是 [stored] 还是 [env: ...]；然后在管理器中替换或移除旧值，或者调整 Shell 环境变量，只保留预期来源。完成修改后重新启动进程，因为已经运行的进程不会自动获得新的环境变量。

如果使用 Kong API 网关，还要满足它对 LangChain 请求格式的要求。官方示例说明了 Bearer 到底出现在哪一侧：LangChain 发出的 Authorization 请求头以 Bearer 开头，这个前缀由 LangChain 自动加；所以网关 Consumer 的 key-auth 凭据要写成带前缀的形式：

key: Bearer my-api-key

而 LangChain 客户端传的是原值，官方示例（LangChain 0.3.11）原文是 api_key="my-api-key"，并注明 without the Bearer prefix, which is added automatically by LangChain：

llm = ChatOpenAI(
    base_url=f"{kong_url}/{kong_route}",
    model="gpt-4o",
    api_key="my-api-key"      # 官方示例：不带 Bearer 前缀
)

两个位置写反是最常见的坑：如果客户端也写成 api_key="Bearer my-api-key"，LangChain 再自动补一次前缀，实际发出的头会是 Bearer Bearer my-api-key，与网关凭据不匹配，请求过了网关也认证失败（这一步是按官方”自动加前缀”规则推导的结果）。核对方法：抓一次请求的 Authorization 头，确认它只有一个 Bearer。

怎么算配置成功

同时满足以下三个可观察结果，才算完成：

  1. 在项目目录运行 npm list langchain，能看到已安装的 langchain 包。
  2. 在 /auth 中打开实际使用的提供商，能看到该提供商已有 [stored] 或 [env: ...] 来源，而不是空白。
  3. 一条最小模型请求返回正常内容；若启用了 LangSmith tracing，LangSmith 中还能找到这次运行记录。

只满足前两项，说明包和凭据已经配置；缺少第三项，则说明还没有完成端到端验证。

官方入口与后续排错

# AI# 知识

评论区

0 条评论

登录后可评论。

木木夕 13 阅读