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

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 Code2.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成功信号是端点返回 HTTP200Claude Code 输出预期短句如果输出是401或认证错误先回到鉴权头和变量作用域。不要在这一步加入工具调用、长上下文或复杂提示词否则会把认证问题和协议问题混在一起。5. 用请求路径区分 401 和 404Anthropic Messages 的资源路径通常是/v1/messages但ANTHROPIC_BASE_URL是否包含/v1要按目标客户端和服务文档确认。最小验证时至少保留这三个字段HTTP status request path error type / message401优先查鉴权变量、认证头和 Key 权限404或405优先查 Base URL、版本前缀和协议路径不要因为两者都发生在“第一条请求”就使用同一套修复动作。本地实测错误鉴权 401Bearer 配置 200为了验证上面的顺序我写了一个只监听127.0.0.1的 Anthropic Messages fixture。它只做两件事收到X-Api-Key的错误鉴权时返回401收到Authorization: Bearer的合成鉴权时返回一个最小成功响应。fixture 不连接任何线上服务。执行python3 06-evidence/probe_claude_auth.py本次实际输出的关键结果如下CLAUDE_VERSION2.1.219 (Claude Code) WRONG_AUTH_SIGNALdirect-http-request WRONG_AUTH_HTTP401 CORRECT_AUTH_EXIT0 CORRECT_AUTH_SIGNALfixture auth success CORRECT_AUTH_HTTP200 ONLINE_PROVIDER_REQUESTNO请求记录只保留认证头类别不保留值wrong request - auth_kindx_api_key status401 Claude Code - auth_kindauthorization_bearer status200这组结果能证明当前 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这个边界足以指导配置修正但不替代线上服务的实际认证验证。