直接答案
先直接验证 Gateway 的最小 Messages 请求，再检查 Claude Code；这样能把协议传输问题与 CLI 配置问题分开。
这篇内容解决什么问题
解决 Claude Code 连接自定义 Gateway 时的 401、404、未知模型、连接失败和流式异常。
先确认症状与影响范围
Claude Code 启动后报告认证失败、404、未知模型、连接超时或流式中断，而直接使用官方账号流程可能正常。先确认当前会话是否真的使用自定义 Gateway。
Bearer Gateway 与 Anthropic 原生 x-api-key 使用不同环境变量和请求头；两者混用会让正确凭据以错误方式发送。
- 在 Claude Code
/status中确认 Base URL、认证来源和模型。 - 确认 Gateway 要求
ANTHROPIC_AUTH_TOKEN还是ANTHROPIC_API_KEY。 - 确认 Base URL 不重复包含
/v1/messages。
常见原因与责任边界
Gateway 故障跨越 Claude Code 配置、Anthropic Messages 协议、网关映射和模型上游。必须分别验证传输、认证、模型和流式行为。
ANTHROPIC_BASE_URL指向错误层级或被旧进程缓存。- Bearer token 与 x-api-key 环境变量选择错误。
- Gateway 未实现 Claude Code 所需的 Messages 或流式兼容。
- 客户端模型名没有正确映射到网关可用模型。
按层执行最小诊断
第一步在 Claude Code 外用最小 Messages 请求验证 Gateway；第二步在 /status 核对 CLI 的最终配置。直接请求失败时先修网关，直接请求成功但 CLI 失败时再检查客户端环境和功能兼容。
调试文件必须脱敏。不要记录 Authorization、x-api-key、Cookie、提示词或项目秘密。
- 01确认会话状态使用
/status检查实际 Base URL、模型和认证来源。 - 02直测 Messages按 Gateway 指定的请求头发送最小非流式消息。
- 03检查模型映射确认客户端模型名与网关模型 ID 的映射存在。
- 04检查流式能力非流式成功后再验证 SSE 与 Claude Code 功能。
printf 'ANTHROPIC_BASE_URL=%s
' "$ANTHROPIC_BASE_URL"
test -n "$ANTHROPIC_AUTH_TOKEN" && echo 'Bearer token is set'
test -n "$ANTHROPIC_API_KEY" && echo 'x-api-key credential is set'
claude --version
claude --debug-file /tmp/claude-gateway-debug.log
# 会话内运行 /status；分享日志前必须脱敏。
针对根因完成修复
按 Gateway 文档选择唯一凭据变量和正确 Base URL，重启终端与 Claude Code 使环境生效。模型映射和流式协议由 Gateway 端修复，不能只在客户端重试掩盖。
- 01对齐认证Bearer 使用 ANTHROPIC_AUTH_TOKEN，x-api-key 使用 ANTHROPIC_API_KEY。
- 02对齐 URL配置 Gateway 基础地址，让客户端按协议追加 Messages 路径。
- 03对齐模型使用 Gateway 实际支持并公布的模型映射。
- 04重启验证清除旧进程环境，再从最小非流式逐步恢复功能。
export ANTHROPIC_BASE_URL='https://<your-gateway-host>'
read -rsp 'Gateway token: ' ANTHROPIC_AUTH_TOKEN && printf '
'
export ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
claude
# 会话结束后：unset ANTHROPIC_AUTH_TOKEN验证修复而不是只看一次成功
按模型列表/最小 Messages、Claude Code /status、短任务、流式长任务的顺序验证。每层成功后再进入下一层，并保存 request ID 和结束原因。
- 直连 Messages 和 Claude Code 使用同一预期 Gateway。
- 请求头、模型映射和流式结束均符合协议。
- 重启新会话后配置仍正确且不依赖临时残留变量。
安全边界与升级证据
不要同时设置多套凭据“碰运气”，也不要把 token 写进 CLAUDE.md、settings.json、仓库脚本或 debug 文件。发现泄露立即在服务端撤销并轮换。
- 真实 token 不出现在命令历史、截图和日志。
- Gateway 的 TLS 与主机名验证保持开启。
- 只承诺经过实测的 Claude Code 功能兼容范围。
官方来源与核验范围
本文以协议规范和客户端官方文档为事实依据。错误文案、重试头和配置字段可能随服务或客户端版本变化；执行前请核对来源，并对日志与请求样例脱敏。
查看技术核验方法