Claude Code 首次连接：官方登录与第三方网关配置
摘要： 本文面向已安装 Claude Code 的读者，梳理首次连接的两条路径：官方账号直接运行
claude登录，并发一条最小请求验证；第三方网关则先确认服务方地址、凭据种类和可用模型 ID，用 curl 验证连通性，再备份并合并用户级~/.claude/settings.json，通过/status核对设置来源后发送真实请求。文末附首次连接失败的核心排查表和官方资料。
已经装好 Claude Code，首次连接先在两条路径中选一条：有符合要求的官方账号，直接运行 claude 登录；拿到的是第三方服务的地址和凭据，则先验证网关，再写入用户级配置。不要把两套认证同时配上来试错。
按账号和服务信息选择路径
- 官方登录：使用 Claude Pro、Max、Team、Enterprise 订阅，或带预付费额度的 Claude Console 账号。免费 Claude.ai 计划不包含 Claude Code。选这条路径，不需要填写第三方网关配置。
- 第三方网关：服务方提供基础地址、凭据和可用模型 ID，且服务兼容 Anthropic Messages 协议，也就是本文验证请求使用的消息接口。
下文的 claude 命令要在安装它的环境中运行。Windows 原生安装与 WSL 安装各用各的终端，不要在一边改配置、到另一边验证。使用网关的读者可直接从确认网关信息开始。
官方账号：登录后发一个最小请求
在项目目录打开系统终端，运行下面的跨平台 CLI 命令，进入 Claude Code：
text
claude首次使用会提示登录，按提示在浏览器完成认证，凭据保存到本机后不需要每次重新登录。主题选择、项目 Trust（项目信任确认）等首次启动提示的完整顺序，官方没有逐条说明，以当前版本实际提示为准；用户级网关配置也不保证跳过这些提示。
如果终端已经设置 ANTHROPIC_API_KEY，此时不会打开浏览器，而会出现一次性批准或拒绝这把 Key 的提示。已有网关凭据也会优先于保存的官方登录；本来想走官方账号却看到这类提示时，先检查是否残留网关凭据，按文末排错表处理。需要换账号或重新认证，在 Claude Code 交互界面输入 /login。
登录后，在交互界面 输入 /status，查看 Login method 显示的当前账号；使用 API Key 时则看 API key 行，确认当前凭据来源。状态符合预期后，用 /exit 退出交互界面，回到同一个系统终端执行：
text
claude -p "只回复：连接测试成功"这个请求不要求修改文件。-p 表示发出一次查询，得到结果后退出；终端返回模型回复，且没有认证或网络错误，才算完成最小文本请求验证。/status 显示正常不能代替这一步。
本文的最小请求，无论用于官方账号还是第三方网关，都只证明最小文本链路可用，不能推广为流式输出、工具调用、推理、其他模型或项目权限全部可用。官方路径验证完成后，无须继续修改网关配置。
向服务方确认地址、凭据种类和模型
第三方路径先把服务方提供的信息与下表对上，再决定写哪个变量。对于静态凭据，变量名决定把凭据放进哪个认证请求头；变量与服务方要求不匹配时，即使凭据没有抄错，网关仍可能读不到它。
| 服务方提供的信息 | 写入位置 | 需要确认什么 |
|---|---|---|
| 网关基础地址 | ANTHROPIC_BASE_URL |
使用服务方给出的基础地址，后面的验证请求会在它后面加 /v1/messages |
| Bearer Token，或要求走 Authorization 头 | ANTHROPIC_AUTH_TOKEN |
Claude Code 将它放进 Authorization: Bearer |
| API Key，或要求走 x-api-key 头 | ANTHROPIC_API_KEY |
Claude Code 将它放进 x-api-key；交互模式首次使用需一次性批准 |
| 可用模型的精确 ID | 用户级配置的 model 字段 |
地址只决定请求发到哪里，不决定由哪个模型回答 |
服务方没说明凭据种类时，官方默认推荐 ANTHROPIC_AUTH_TOKEN，但仍应向服务方确认它接受哪个认证头。把凭据放进网关不读取的头，请求就会以 401 失败；不要因此反复更换模型名。
如果组织要求用脚本从保险库取得凭据，或凭据需要轮换，可以使用 apiKeyHelper。它用于取代静态环境变量，静态凭据与助手只选一条来源，不要同时配置；按优先级采用静态变量时，助手输出不会被使用。采用助手输出时，凭据会同时放入上述两个认证头。本文接下来的示例使用静态 Bearer Token，不展开助手脚本。
在填写任何凭据前先确定保存位置：**凭据不得写入项目共享的 .claude/settings.json，也不得出现在文章、截图、工单或 Git 中。**用户级配置和备份同样可能含有 Token，不上传网盘、不外发；排错只核对来源，不打印或回显凭据。需要向服务方提供响应或日志时，先脱敏。
先用 curl 验证，不急着保存配置
先验证的目的是把网关地址、凭据和网络问题，与 Claude Code 的配置加载问题分开。官方推荐先在 Shell 设置环境变量并发一条请求，确认网关和凭据后再持久化；如果这一层就失败，应先检查地址、凭据和网络，而不是反复修改配置文件。
下面是站内采用的官方网关文档 Bash 验证请求摘录 ，未列出官方同页的 PowerShell 写法。它是 Bearer Token 示例：把占位地址 https://llm-gateway.example.com、无效占位 Token sk-gateway-key 和示例模型 claude-sonnet-4-6，分别换成自己的服务地址、凭据和可用模型 ID，再在同一个 Bash 终端执行。不要拿这些示例值判断自己的网关是否可用。
bash
export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'请求向 /v1/messages 发送 JSON：model 选择测试模型，max_tokens: 1 把本次输出上限设为 1 个 token，messages 里发送的用户消息是一个句点 .。因此它用于检查连接，不是要求模型返回完整说明。anthropic-version: 2023-06-01 是请求中的 API 版本头，不是本机 Claude Code 的版本号；content-type 说明请求体采用 JSON。
服务方要求 x-api-key 时，要按前表使用对应的凭据变量和认证头，不能直接套用这段 Bearer 示例。原生 Windows PowerShell 读者使用文末官方 LLM Gateway 文档中的 PowerShell 写法，不把这里的 export 和续行语法直接粘贴过去。
按官方这条验证请求的判读：
- 响应以
{"id":"msg_开头，且含"content":[...]字段，说明网关可达、凭据有效。id是这条消息的标识，content承载模型返回的内容。 - 返回"未知模型"错误，也说明地址和凭据通过了这一层，因为认证先于模型名校验；但模型仍未调用成功，需换成服务方确认的 ID 后重试。
- 返回
401表示凭据被拒，先核对认证头和凭据；连不上或返回其他错误，按文末现象表定位。
这里没有使用真实第三方凭据完成端到端连接，第三方结果必须在你自己的服务环境中验证。上述响应只是判读依据，不是本文取得的测试结果。
Shell 导出只对当前终端会话生效，从开始菜单或 Dock 启动的编辑器读不到这些变量。需要持久使用时，再将确认过的信息写入下面的用户级文件。
备份并合并用户级 settings.json
本文把网关信息写在：
text
~/.claude/settings.jsonWindows 原生环境的 ~/.claude 对应 %USERPROFILE%\.claude；WSL 中的 ~ 是 Linux 主目录，与 Windows 各自独立。安装 Claude Code 不会创建 settings 文件，找不到文件时可以新建，不必据此重新安装。
**为什么不直接写进项目目录？**用户级文件的 env 块会在首次启动流程之前读取；项目中的 .claude/settings.json 和 .claude/settings.local.json，其 env 在交互会话中要等首次向导和项目 Trust 之后才生效。因此，项目级 env 不能替代用户级首连配置，否则可能出现"curl 能通，启动却还要求登录"。
这些配置的作用范围不同：
~/.claude/settings.json：你的全部项目，本文使用的位置。- 项目内
.claude/settings.json：仓库协作者共享的设置。 - 项目内
.claude/settings.local.json：你在单个项目中的本地设置。 - managed settings：组织下发的设置，优先级最高，可以整体覆盖用户配置。
存在同名设置时，优先级从高到低为 managed settings → 命令行参数 → 项目 local → 项目 shared → 用户级 。同一变量在 Shell 和 settings 的 env 中都有值时，以 settings 的值为准；不能只改终端变量，就认定旧配置已经被替换。
已有文件先备份，再按键合并
在 Bash 中，文件已存在时用下面的命令保留修改前副本：
bash
cp ~/.claude/settings.json ~/.claude/settings.json.before-gateway.bakWindows 原生也应先复制一份现有文件作为备份，不直接套用上面的 Bash 命令。文件原本不存在则直接新建；误改已有文件时，用修改前的副本恢复。
下面是与站内一致的 JSON 整理示例 ，合并了官方 env 写法和配置生成器使用的 $schema 行。新建空文件时可用它作为起点；已有文件不要整段覆盖 ，应把字段合并到原有 JSON 中，保留 permissions、Hooks、MCP 等其他设置。已经有 env 就合并其中的键，同名键改值，不再追加第二个。
json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"env": {
"ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "YOUR_GATEWAY_TOKEN"
},
"model": "YOUR_MODEL_ID"
}把地址、YOUR_GATEWAY_TOKEN 和 YOUR_MODEL_ID 换成已确认的信息；若服务方要求 API Key 认证，凭据键按前表选择 ANTHROPIC_API_KEY，不要同时保留两种静态凭据。JSON 不允许重复键，不要加 // 注释或尾逗号，否则下次启动会报 Settings Error。
顶层 model 是持久默认模型，但可能被更高优先级的选择覆盖。保存用户级配置后，先检查 env.ANTHROPIC_MODEL 是否残留：它的优先级高于顶层 model，旧的环境变量值仍可能覆盖刚修改的默认模型。走网关时，Claude Code 不在本地校验模型名，而是把它原样传给网关。模型 ID 写错，要到第一次请求才会失败；文件能保存不代表模型存在。
网关写入后：先看加载来源，再发真实请求
保存后运行 claude，在 Claude Code 交互界面 执行 /status。先核对这三项，不要仅凭"没有弹出登录页"判断配置已经正确加载：
| 观察项 | 要确认的内容 | 这一层能说明什么 |
|---|---|---|
Setting sources |
本次加载了哪些设置文件 | 是否读到了预期文件，排查时从哪些来源找覆盖值 |
Anthropic base URL |
是否显示自己的网关地址 | 请求路由是否切换；这一行不存在，说明变量没有到达本会话 |
Auth token |
是否点名自己设置的凭据变量 | 当前网关凭据来源，而不是保存的 claude.ai 登录 |
这些是状态行的读法，不是一份真实会话输出。/status 只用于观察本次加载的设置来源、网关地址和凭据来源，不能证明模型已经收到请求。若需要先检查配置文件错误，可在系统终端 运行 claude doctor：它输出安装健康状态以及 settings 文件的校验错误和警告，也不代替真实请求。
确认来源后，在同一交互会话 发送消息"只回复：连接测试成功"，或退出后使用前文的 claude -p 命令。返回模型回复且没有认证或网络错误，才完成 Claude Code 的最小请求验证；如果状态正确、请求却失败，就按下一节查认证、模型或网络，不再把"配置加载成功"当成连接成功。
首次连接失败时，先查哪一处
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| curl 成功，启动却仍要求登录 | 凭据是否只写在项目级 env，来不及在首次向导之前读取 |
改用用户级 env 或当前 Shell 导出；受组织管理时核对 managed settings |
401，提示凭据无效或不被识别 |
服务方要求的认证头是否与凭据变量匹配，凭据是否已被吊销 | 按服务方说明修正变量；被吊销的凭据需要重新签发 |
启动警告点名两个凭据来源，旧版本显示 Auth conflict: ... |
网关凭据和保存的官方登录同时存在，变量优先、登录暂不使用 | 继续用网关可在交互界面执行 /logout；回官方路径则移除网关凭据变量，并检查 settings 中是否仍有同名值 |
This machine's managed settings require a first-party login |
组织设置含 forceLoginMethod 或 forceLoginOrgUUID，不能与 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、apiKeyHelper 共存 |
由管理员调整组织设置，或移除网关凭据改回官方登录，不靠改用户文件绕过 |
Connection refused 或 Can't reach the API server (ENOTFOUND) |
地址是否写错，VPN 或防火墙是否拦截网络路径 | 重跑 curl；同样失败先与服务方核对地址和网络 |
API returned an empty or malformed response (HTTP 200) |
网关或中间代理是否返回了 HTML 错误页、登录页等非 API 响应 | 用 curl 查看响应内容，修正网关路由；HTTP 200 本身不代表得到了模型回复 |
403、响应体是 HTML，网关日志又没收到请求 |
网关前的 WAF（Web 应用防火墙）可能拦截请求体；Claude Code 提示词里的 XML 风格标签与源码可能命中检查，短 curl 却能通过 | 请管理员对 /v1/messages 路径豁免请求体检查 |
| 证书或 TLS 错误，但 curl 正常 | Claude Code 运行时是否信任企业 TLS 检查代理使用的 CA（证书颁发机构）证书 | 用 NODE_EXTRA_CA_CERTS 指向对应 CA 包路径 |
| 保存配置没报错，请求却提示模型不存在 | 是否使用了示例模型、拼错 ID，或保留了旧模型选择 | 与服务方确认精确 ID，检查 model 及更高优先级的 ANTHROPIC_MODEL，再发请求 |
400 报未识别字段或 thinking、adaptive |
网关上游是否接受 Claude Code 发出的这些字段 | 按官方 LLM Gateway 排错说明核对上游兼容性，不把最小文本通过当成这些字段也已兼容 |
| 修改后仍是旧地址或旧行为 | 是否被更高层配置覆盖，或 settings 中仍保留与 Shell 同名的旧值 | 用 /status 的设置来源与地址行定位实际加载位置，再修改对应值 |
| Windows 与 WSL 结果不一致 | 是否在一边运行 Claude Code，却改了另一边的 ~/.claude |
回到实际运行环境的用户目录完成配置，并在该环境验证 |
一次只改一处，修改后回到对应的验证动作：地址和凭据先看 curl，文件来源看 /status，Claude Code 能否使用看真实请求。不要靠不断追加参数掩盖尚未定位的问题。
官方资料
本文沿用 2026-09-04 的官方文档核验范围。需要核对当前版本时，可按问题查阅：
- Setup：认证入口与首次使用说明。
- Authentication：账号条件、凭据来源及认证优先级。
- Settings：文件位置、设置作用范围与优先级。
- LLM Gateway 配置：网关验证请求、PowerShell 写法及对应现象的官方排错说明。
- 模型配置：模型选择优先级与网关模型名的处理方式。
继续完成配置
不想手工编辑 JSON，可以使用 Claude Code 参数配置（配置生成器）。它用于减少手写配置时的遗漏，但不能替代连接验证；仍需在自己的环境完成 /status 核对和真实请求。