Claude Code 配置 settings.json 后报 401？按 Base URL 与鉴权变量修正

SQDN

366人浏览 · 2026-07-26 13:13:40

SQDN · 2026-07-26 13:13:40 发布

Claude Code 配置 settings.json 后报 401？按 Base URL 与鉴权变量修正

Claude Code 已经能启动，配置文件也看起来写了 Base URL 和 Key，但发送第一条消息就返回 401 Unauthorized。这时不要先换模型，也不要把网页登录状态、API Key 和自定义网关当成同一件事。最容易漏掉的两个边界是：变量有没有放进 settings.json 的 env 对象，以及目标端点要求的是 Bearer 还是 X-Api-Key。

本文只解决一个问题：Claude Code CLI 接自定义 Anthropic 兼容端点后报 401，怎样按配置位置、请求去向和鉴权头逐层修正。实测环境是 Claude Code 2.1.219。本地结果来自只监听 127.0.0.1 的脱敏 fixture，没有请求线上 Anthropic 或第三方 provider，也没有使用真实 Key。

先按这 5 步跑一遍

适用环境：已经安装 Claude Code CLI，需要把会话请求发到一个遵循 Anthropic Messages 请求格式的自定义端点。本文以 macOS/Linux 为例；Windows 用户把 ~/.claude/settings.json 换成 %USERPROFILE%\\.claude\\settings.json 即可。项目级配置仍放在项目目录的 .claude/settings.json。

1. 先确认当前 CLI 和文件位置

claude --version
ls -l ~/.claude/settings.json
ls -l .claude/settings.json 2>/dev/null || true

本文实测输出为 2.1.219 (Claude Code)。Claude Code 的用户设置和项目设置是不同作用域：用户设置用于多个项目，项目设置用于当前项目。先确认你修改的是哪一个文件，再排查内容；不要一开始同时改两份文件。

2. 把变量放进 `env`，不要写成自定义顶层字段

官方 settings 文档支持在 settings.json 的 env 对象里设置环境变量。先备份已有文件，再用一份临时文件验证，不要直接覆盖自己的权限、hooks 或其他设置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-anthropic-compatible-endpoint.example",
    "ANTHROPIC_AUTH_TOKEN": "<YOUR_TOKEN>",
    "ANTHROPIC_MODEL": "<YOUR_MODEL_ID>"
  }
}

ANTHROPIC_BASE_URL 是请求去向，ANTHROPIC_MODEL 是请求里的模型 ID。这里的 <YOUR_TOKEN> 只是占位符，不要把真实凭据写进仓库、截图或命令历史。若服务文档要求 X-Api-Key，把 ANTHROPIC_AUTH_TOKEN 换成 ANTHROPIC_API_KEY，不要两个变量一起留着让优先级变得不透明。

成功信号不是“JSON 能保存”，而是下一步的最小请求真的到达你指定的端点，并返回可解析的 Anthropic Message 响应。

3. 先确认目标服务需要哪一种鉴权头

Claude Code 官方文档对两个变量的语义不同：

ANTHROPIC_AUTH_TOKEN  -> Authorization: Bearer <token>
ANTHROPIC_API_KEY     -> X-Api-Key: <api-key>

如果网关只接受 Bearer，而你填的是 ANTHROPIC_API_KEY，最小请求可能直接 401；反过来也一样。不要只看变量名里有 API_KEY 就认为所有 Anthropic 兼容端点都接受它。以目标服务自己的认证说明为准，并在服务端访问日志里只保留请求路径和状态码，不记录完整认证头。

4. 用显式 settings 文件启动一次最小会话

把真实配置复制到 /tmp/claude-settings.json 后，用显式参数减少其他用户配置和插件的干扰：

claude --bare \
  --settings /tmp/claude-settings.json \
  --tools "" \
  --print "只返回 OK"

成功信号是端点返回 HTTP 200，Claude Code 输出预期短句；如果输出是 401 或认证错误，先回到鉴权头和变量作用域。不要在这一步加入工具调用、长上下文或复杂提示词，否则会把认证问题和协议问题混在一起。

5. 用请求路径区分 401 和 404

Anthropic Messages 的资源路径通常是 /v1/messages，但 ANTHROPIC_BASE_URL 是否包含 /v1 要按目标客户端和服务文档确认。最小验证时至少保留这三个字段：

HTTP status
request path
error type / message

401 优先查鉴权变量、认证头和 Key 权限；404 或 405 优先查 Base URL、版本前缀和协议路径；不要因为两者都发生在“第一条请求”就使用同一套修复动作。

本地实测：错误鉴权 401，Bearer 配置 200

为了验证上面的顺序，我写了一个只监听 127.0.0.1 的 Anthropic Messages fixture。它只做两件事：收到 X-Api-Key 的错误鉴权时返回 401；收到 Authorization: Bearer 的合成鉴权时返回一个最小成功响应。fixture 不连接任何线上服务。

执行：

python3 06-evidence/probe_claude_auth.py

本次实际输出的关键结果如下：

CLAUDE_VERSION=2.1.219 (Claude Code)
WRONG_AUTH_SIGNAL=direct-http-request
WRONG_AUTH_HTTP=401
CORRECT_AUTH_EXIT=0
CORRECT_AUTH_SIGNAL=fixture auth success
CORRECT_AUTH_HTTP=200
ONLINE_PROVIDER_REQUEST=NO

请求记录只保留认证头类别，不保留值：

wrong request  -> auth_kind=x_api_key              status=401
Claude Code    -> auth_kind=authorization_bearer   status=200

这组结果能证明当前 CLI 按 ANTHROPIC_AUTH_TOKEN 发出了 Bearer 请求，并且本地服务返回的最小 Message 能被 Claude Code 读取。它不能证明任何线上 provider 接受同一个模型、同一个 Key 或同一种协议；真实服务仍需按自己的文档和脱敏日志复核。

实测结果图

401 的失败路径怎么排

情况一：变量写在了错误位置

下面这种写法不是本文的配置方式：

{
  "ANTHROPIC_BASE_URL": "https://example.invalid",
  "ANTHROPIC_AUTH_TOKEN": "<TOKEN>"
}

它把环境变量名当成了自定义 settings 字段。正确方向是放在 env 下面，或者在启动 Claude Code 的同一个终端里导出环境变量。若配置文件能被打开但请求仍然走默认地址，优先检查这一层，并用脱敏后的最终 URL 验证请求去向。

情况二：同时设置了两个认证变量

同时保留 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 会让排错变得困难：你看到的是一个 401，但不知道请求头来自哪一个变量。测试时只保留目标服务要求的一个变量，重开一次会话，再看服务端是否收到 Authorization 或 X-Api-Key。生产环境也应避免在 shell、IDE 和 settings 文件中重复注入不同凭据。

情况三：Key 对，但 Base URL 指错

如果服务端需要 Bearer，正确的变量也不能修复错误的地址。常见误填包括登录页、完整资源 URL、OpenAI Chat Completions 路径，或把已经包含 /v1 的地址交给会自动追加版本前缀的客户端。此时通常会看到 404、405 或协议格式错误，但不同网关也可能把路由失败统一成 401。最终判断要看脱敏请求路径和响应错误类型，不要只看域名是否能打开。

情况四：认证成功，但模型没有权限

如果错误体明确说模型不可用、模型未开放或权限不足，这已经不是单纯的 Key 格式问题。记录模型 ID、状态码、错误类型和 request id，先核对服务端模型目录与当前账号权限。不要把一个平台的“Sonnet”展示名直接复制到另一个端点，也不要因为换 Key 后偶尔返回 200 就声称模型稳定可用。

情况五：Claude Code 仍然使用旧会话

--bare --settings 只适合做最小验证，不代表你应该长期绕过所有用户设置。最小验证跑通后，逐项把非敏感设置迁回实际作用域；如果环境变量来自当前终端，重启一个干净终端再试。不要一边保留旧的 ANTHROPIC_API_KEY，一边在项目文件里新增 ANTHROPIC_AUTH_TOKEN，然后根据一次错误去猜优先级。

一张可复制的排错清单

[ ] claude --version 已记录
[ ] 确认正在修改 ~/.claude/settings.json 还是 .claude/settings.json
[ ] Base URL 和认证变量位于 settings.json 的 env 对象
[ ] 只保留目标服务要求的一种鉴权变量
[ ] 记录最终请求路径，而不是只看配置字符串
[ ] 401 查认证头、Key 权限和变量作用域
[ ] 404/405 查 Base URL、/v1 前缀和 Messages 路径
[ ] 最小请求返回 200 且响应结构可解析
[ ] 日志中没有明文 Key、Cookie、Token 或用户数据

本文不要求注册、购买、充值或使用某个商业服务。测试只用了本机合成 fixture，目的是把 401 的认证分支与 404 的路径分支分开。真实接入时，请把示例端点、模型 ID 和鉴权方式替换成目标服务的当前文档值，并保留脱敏后的请求状态作为证据。

总结

Claude Code 配置后报 401，先按“作用域 -> env -> Base URL -> 鉴权变量 -> 最小请求”的顺序排。ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 不是同一个变量：前者对应 Bearer，后者对应 X-Api-Key。本地实测用错误的 API-Key 头得到 401，用正确的 Bearer 配置由 Claude Code CLI 得到 200；这个边界足以指导配置修正，但不替代线上服务的实际认证验证。