Claude Code 怎么接入 Qwen4?模型映射、密钥和连接报错排查

用正确的 QwenCloud 地址和模型映射配置 Qwen4-Max,逐层排查 401、403 及 CC Switch 无法获取模型列表的问题。

电话交换台把橙色插头接入对应插孔。

在 Claude Code 中使用 Qwen4-Max,需要配置 QwenCloud 兼容 Anthropic 的 Base URL、该路由对应的密钥,以及明确的 qwen4-max 模型映射。 只改模型显示名称,不会自动切换供应商。模型列表探测成功,也不是正常对话的前提。

本文依据 2026 年 11 月 17 日核对的 QwenCloud 文档,介绍正式版,而非 qwen4-max-preview。如果还没分清版本,先看 Qwen4 API 接入与迁移指南。本文解决更具体的问题:让编程客户端走预期路由,并判断故障发生在哪一层。

下方 Shell 配置已通过本地假客户端检查;假客户端记录配置名称,不调用真实模型。本文没有进行付费 Qwen4 调用。最终对话与供应商账单核对,需要你在自己有权使用的账号中完成。

先选路由,再填密钥

QwenCloud 的 Token Plan 和各区域按量付费路由相互独立。先选定一种,不要把一种路由的密钥与另一种路由的 Base URL 混用。

计划使用的路由Claude Code Base URL需要核对
QwenCloud Token Planhttps://token-plan.maas.qwencloudapi.com/apps/anthropic套餐密钥及所选模型的访问权限
QwenCloud 按量付费,新加坡https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic该区域签发的密钥及模型权限
其他 QwenCloud 区域使用该区域文档中的 Anthropic 兼容地址区域、服务可用性及密钥作用域

这些是 Base URL,不是完整消息请求地址。本配置中不要在 QwenCloud Base URL 后追加 /v1;客户端会使用其下的 messages 路径。具体规则见 QwenCloud Claude Code 指南(英文)和区域文档(英文)。

Ofox API Key 不是 QwenCloud 密钥。如果改用 Ofox 已支持的模型,按 Ofox 鉴权文档及其支持的接入设置操作,不要把 Ofox Key 填到上面任一 QwenCloud 地址。本文不证明 Ofox 已提供 Qwen4;请另行核对当前 Ofox 模型目录。

启动配置明确、范围隔离的 Qwen4 会话

第一次排查时,打开新终端,使用小型合成测试项目,并备份日常配置。下面的 Bash 启动器只在自身进程及子客户端中导出变量,不改全局设置文件,不打印密钥,也不把密钥写进脚本。

保存为 launch-qwen4.sh:

#!/usr/bin/env bash
set -euo pipefail

# Singapore pay-as-you-go. For Token Plan, replace only this route
# and enter the matching Token Plan key when prompted.
export ANTHROPIC_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic"
unset ANTHROPIC_API_KEY
read -r -s -p "QwenCloud key for this route: " ANTHROPIC_AUTH_TOKEN
printf '\n'
if [[ -z "$ANTHROPIC_AUTH_TOKEN" ]]; then
  printf 'No key entered; no request sent.\n' >&2
  exit 1
fi
export ANTHROPIC_AUTH_TOKEN

# Deliberately use one model while diagnosing routing.
export ANTHROPIC_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen4-max"
export CLAUDE_CODE_SUBAGENT_MODEL="qwen4-max"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="983616"
exec claude "$@"

在测试项目中运行 bash launch-qwen4.sh。测试 Token Plan 时,将 Base URL 改为表中的套餐地址,并输入对应密钥。没有确认某个低价模型在该路由可用之前,不要随意换入其模型 ID。

把所有别名映射到 Qwen4-Max 是排查手段,不是成本建议。这样可以排除后台任务或子 Agent 选中其他配置模型的干扰。路由确认后,再有意把轻任务映射到其他受支持模型,并单独验证。

启动器不会覆盖所有受管理设置、包装脚本或 IDE 扩展。组织管理的客户端应遵循组织规则。本次测试直接启动 CLI,避免 IDE 悄悄提供另一套环境。Windows 用户需在匹配的 WSL 或 Git Bash 环境运行此 Bash 示例;原生 PowerShell 的环境变量语法不同。不要默认 Windows CLI 与 WSL 安装读取同一份配置。

分别验证供应商、任务结果与计费

进入新的 Claude Code 会话后运行 /status,对照预期值核对供应商地址和所选模型。不要公开包含凭据的原始设置输出或截图。如果路由为空或仍指向别处,先查清当前客户端进程实际加载的配置,再考虑换模型。

使用不涉及私有仓库内容的小任务:

Create a Python function named normalize_code(value).
It must accept a string, trim surrounding spaces and preserve leading zeros.
Raise TypeError for non-string input.
Add tests for " 0017 ", "", and the integer 17.
Do not install dependencies or access the network.
Show which files you changed and how to run the tests.

这份英文提示词要求创建 normalize_code(value):只接收字符串、去除两端空格、保留前导零,对非字符串抛出 TypeError,并测试指定输入;禁止安装依赖或访问网络。

验收记录分三部分:

  1. 路由:会话显示预期供应商和映射;供应商提供请求记录时,该记录应标明目标模型。模型自称是什么,不是路由证据。
  2. 交付:文件确实存在," 0017 " 变为 "0017",空字符串仍为空,整数输入抛出 TypeError。运行生成的测试并检查 diff。
  3. 计费:调用出现在预期账号或套餐的用量视图中。不要凭工具里的模型标签推断费用来源。

回答不错但扣错账号,配置仍不算通过。路由正确而测试失败,应记为任务失败,不要当成连接故障。先把实验控制在小范围,通过后再开放更大范围的仓库修改或长任务。

按症状定位故障层

官方排错章节(英文)区分了几种看起来都像“Qwen 用不了”的故障。

症状首先检查针对性处理
401 invalid_api_key密钥所属路由、区域及实际供应商地址换用匹配的 QwenCloud 密钥并重启客户端;日志中不要暴露密钥
Claude Code 仍连接 Anthropic/status 与当前进程加载的配置修正供应商环境变量或设置,排查包装脚本及冲突的认证配置
CC Switch 提示找不到模型列表端点失败探测查的是模型发现还是 messages手动设置模型映射,在文档规定的路由测试真实消息
换模型后出现 403 AccessDenied模型权限及 QwenCloud 模型广场的生命周期标签将不可用或即将弃用的映射替换为有权限的当前模型;保留错误及请求 ID
旧接口改模型不生效Base URL 是否包含 claude-code-proxy迁移到文档中的 /apps/anthropic 接口
长回答提前停止客户端输出上限及响应停止原因查对应模型限制,缩小任务或有意调整客户端上限

如果自定义供应商路由已经配好,启动仍尝试 Anthropic 官方登录,QwenCloud FAQ 还要求检查 ~/.claude.json 中的 hasCompletedOnboarding: true。注意它不是 ~/.claude/settings.json。先备份 JSON,再只合并相关字段,不要覆盖整个文件或改动组织管理的设置。换新终端重启;文档配置仍无法工作时,通过官方安装方式更新客户端,再查实际加载的配置。

模型列表问题尤其容易误判。QwenCloud 文档说明,其 Anthropic 兼容路由提供 /v1/messages,但没有模型列表端点。因此 CC Switch 的发现探测可以失败,而实际对话仍可使用。这不表示所有 404 都能忽略:消息地址错误、多出路径段或模型不受支持仍需修复。先确认失败的是哪个请求。

如果直接请求正常、编程客户端却持续失败,参考 Claude Code 直连正常但客户端连接失败排查。精确模型 ID 不可用时,可借鉴 OpenAI model-not-found 排查指南(英文)中的供应商和端点检查方法;它不是 Qwen 专属错误的复现记录。证书故障应按 TLS 与证书错误排查处理,而不是改模型映射;不要通过关闭证书验证绕过问题。

有意设置上下文与输出限制

当前 QwenCloud 指南要求 Qwen4-Max 的 CLAUDE_CODE_MAX_CONTEXT_TOKENS 保持为 983616。这一客户端设置与模型宣传的一百万 token 上下文不是同一个量,设好它也不证明长任务一定能完成。

11 月 17 日版本的指南建议,在 Qwen4-Max 输出被截断时设置 CLAUDE_CODE_MAX_OUTPUT_TOKENS=131072;同页 Preview 说明使用 64000。不要把预览版建议混进正式版配置。首次冒烟测试不必设到最大:允许输出越长,运行时间和消耗可能越大。先检查停止原因,再选择符合任务的上限。

Agent 反复读取大型参考文档时,可以继续看 Qwen4 显式缓存教程。大上下文窗口是容量设置,缓存是另一套请求规则;没有对应的用量字段,两者都不能证明缓存命中。

留下可恢复的配置记录

测试通过后,记录客户端版本、供应商 Base URL、模型映射、密钥类型与区域、测试结果和时间。密钥本身放在日常使用的安全凭据管理机制中。持久化设置时,把所需字段合并到现有文件,不要覆盖无关权限和设置。

以后排错每次只改一个变量,保留脱敏后的请求 ID、HTTP 状态、错误码及模型 ID。要回退本启动器,只需退出它启动的会话,再从父终端启动日常客户端;启动器没有改动父进程环境或设置文件。如果另行修改了持久化设置,还需恢复备份。

预期路由、实际文件和预期用量记录三者一致,才算接入完成。此后才能在稳定配置上比较真实编程任务,而不是每次都排查不同路由。

常见问题

Claude Code 必须能获取 Qwen 的模型列表才能使用吗?
不必。QwenCloud 文档说明,兼容 Anthropic 的端点提供 messages 接口,但不提供模型发现接口。CC Switch 获取模型列表失败,不等于消息请求失败。
选择 Opus 就表示调用的是 Anthropic 模型吗?
不一定。自定义供应商上的 Opus 别名可以映射到 Qwen4-Max。应核对实际供应商、精确模型映射及供应商请求记录。