Qwen4-Max 接入配置教程 可按千问 AI 平台官方文档操作:在 Claude Code、Codex 和 Cherry Studio 中填写对应地址、密钥和型号 qwen4-max。

本站此前已介绍过 Qwen4-Max 正式上线与官方定价。本文只整理官方给出的客户端接入步骤,不涉及第三方中转。配置项和报错说明均来自千问 AI 平台文档,本文未在本地逐项实测。
先分清两套接入方式
千问 AI 平台为 Qwen4-Max 提供 Token Plan(个人版或团队版,按 Credits 计量)和按量计费 API。两种方式的 API Key 与接入地址必须配套使用,不能混用。官方还提醒:预览型号 qwen4-max-preview 的预览权益与正式版 qwen4-max 分别适用,新接入请优先用正式型号。
| 方案 | API Key | OpenAI 兼容地址 | Claude Code(Anthropic 兼容)地址 |
|---|---|---|---|
| Token Plan | Token Plan 个人版或团队版专属 Key | https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1 |
https://token-plan.maas.qianwenaiapi.com/apps/anthropic |
| 按量计费 | 千问 AI 平台 API Key(sk- 开头) |
https://maas.qianwenaiapi.com/compatible-mode/v1 |
https://maas.qianwenaiapi.com/apps/anthropic |
Qwen4-Max 的官方规格是:上下文 100 万 Token;非思考模式最大输出 131,072 Token;思考与最终回答合计最大 262,144 Token;默认 reasoning_effort=high、thinking_budget=131072。价格和限流以控制台及计费说明为准。
用 API 直接调用
按量付费时,先获取 API Key,并设置环境变量 DASHSCOPE_API_KEY。官方给出的 OpenAI SDK 示例如下(Token Plan 需改用其专属凭证与端点)。
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qianwenaiapi.com/compatible-mode/v1"
)
response = client.chat.completions.create(
model="qwen4-max",
messages=[{"role": "user", "content": "给出一个按阶段交付的项目计划,每个阶段列出目标、验收标准和交付产物。"}
]
)
print(response.choices[0].message.content)
同一文档还写明:除 Chat Completions 外,也可使用 Responses、Anthropic Messages 或 DashScope。默认开启思考模式;若要在 Chat Completions 中关闭思考,需设置 enable_thinking=false。
在 Claude Code 中接入
官方推荐把配置写进 ~/.claude/settings.json(Windows 为 C:\Users\< 用户名 >\.claude\settings.json),这样不必每次导出环境变量。修改后需要新开终端再运行 claude 才会生效。
Token Plan 的官方模板如下。同页说明:如需使用正式版 qwen4-max,将 ANTHROPIC_DEFAULT_OPUS_MODEL 设为 qwen4-max,并保持 CLAUDE_CODE_MAX_CONTEXT_TOKENS 为 983616。长输出被截断时,可加 CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000。
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
"ANTHROPIC_BASE_URL": "https://token-plan.maas.qianwenaiapi.com/apps/anthropic",
"ANTHROPIC_MODEL": "auto",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.8-flash",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen4-max",
"CLAUDE_CODE_SUBAGENT_MODEL": "auto",
"CLAUDE_CODE_MAX_CONTEXT_TOKENS": "983616"
}
}
按量计费的官方示例仍以 qwen3.7-max 作为模板。按同一页对 qwen4-max 的说明,把主模型和 Opus 默认模型改为 qwen4-max,并加上上下文窗口配置,例如:
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
"ANTHROPIC_BASE_URL": "https://maas.qianwenaiapi.com/apps/anthropic",
"ANTHROPIC_MODEL": "qwen4-max",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3.6-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen4-max",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen4-max",
"CLAUDE_CODE_SUBAGENT_MODEL": "qwen4-max",
"CLAUDE_CODE_MAX_CONTEXT_TOKENS": "983616"
}
}
保存后,在项目目录执行 claude -p "你好" 做连通性检查。如果 Claude Code 仍尝试登录 Anthropic 官方服务,官方建议编辑或新建 ~/.claude.json(Windows 为 C:\Users\< 用户名 >\.claude.json),写入 {"hasCompletedOnboarding": true}。
若更习惯用图形化切换器,官方也提供了 CC Switch 的接入说明:请求地址以 /apps/anthropic 结尾,不要再追加 /v1。Claude Code 的用法还可以对照本站的 文心 5.5 Flash 接入 Claude Code 配置教程,两端点不能混用。
在 Codex 中接入
打开或新建 ~/.codex/config.toml(Windows 为 C:\Users\< 用户名 >\.codex\config.toml)。Token Plan 的官方示例如下,把 OPENAI_API_KEY 换成 Token Plan 专属 Key:
model_provider = "Token_Plan"
model = "auto"
[model_providers.Token_Plan]
name = "Token_Plan"
base_url = "https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
按量计费则使用 Model_Studio 供应商,base_url 为 https://maas.qianwenaiapi.com/compatible-mode/v1,环境变量同样是 OPENAI_API_KEY,wire_api 为 responses。官方示例里的 model 仍写 qwen3.7-max;同一页写明可通过 codex -m qwen4-max 指定模型,并把 qwen4-max 收入了模型元数据目录。把 model 改成 qwen4-max 即可。
如果启动时提示 Model metadata ... not found,官方说明:不配置元数据时,config.toml 里指定的模型仍可调用,只是 Codex 会按默认元数据处理。若要在 TUI 里用 /model 或命令行 -m 切换,需新建 ~/.codex/model-catalog.local.json,按官方文档写入 qwen4-max 等条目(上下文窗口 1,000,000,默认推理档为 high,支持 low / high / xhigh)。
配置环境变量 OPENAI_API_KEY 后,在项目目录运行 codex exec "你好" 验证。若配置写入了却不生效,可再看本站的 Codex 配置不生效排查。
在 Cherry Studio 中接入
先到 Cherry Studio 官网下载并安装客户端。打开后点击右上角设置,在「模型」栏点击添加,供应商名称可填「千问 AI 平台」,提供商类型选择 OpenAI,然后按计费方案填写:
| 配置项 | Token Plan | 按量计费 |
|---|---|---|
| API 密钥 | Token Plan 个人版或团队版专属 Key | 千问 AI 平台 API Key |
| API 地址 | https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1 |
https://maas.qianwenaiapi.com/compatible-mode/v1 |
| 模型 | 个人版或团队版支持的文本生成模型 | 填写 qwen4-max |
Cherry Studio 官方文档的按量计费示例仍写 qwen3.8-max 或 qwen3.8-flash,并注明可用模型见 OpenAI 兼容接口。千问 AI 平台《最新模型:Qwen4-Max》已把 qwen4-max 列入该兼容接口,因此模型 ID 直接填 qwen4-max。点击添加后,回到对话界面选中该模型,发一条消息,能正常返回即配置成功。


Cherry Studio 的界面和基本用法,也可参考本站较早的 Cherry Studio 客户端介绍。客户端版本以官网当前下载页为准。
常见报错与解决
401 invalid_api_key 或 401 Unauthorized
官方把这类错误归因于 API Key 类型与 Base URL 不匹配。Token Plan 的 Key 只能打到 Token Plan 地址,按量计费的 sk- Key 只能打到 https://maas.qianwenaiapi.com 对应端点。先检查 settings.json 或 Cherry Studio 里填写的地址,再核对 Key 是否来自同一套方案。
Unable to connect to Anthropic services / 连上 api.anthropic.com
这说明 Claude Code 仍在访问 Anthropic 官方服务,而不是千问 AI 平台。按官方排查顺序:在会话里执行 /status,确认 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 已指向千问地址;确认 ~/.claude.json 中 hasCompletedOnboarding 为 true;改完配置后新开终端再运行 claude;仍不行则执行 npm install -g @anthropic-ai/claude-code@latest 升级后再试。
The value of the enable_thinking parameter is restricted to True
这是 Cherry Studio 文档给出的报错:该模型当前只允许在思考模式下运行,但请求未开启思考。在客户端中打开思考模式后再发送。
切换模型不生效,或提示旧版接口
旧版兼容地址 https://maas.qianwenaiapi.com/api/v2/apps/claude-code-proxy 只支持已下架模型。需要改用本文的 /apps/anthropic 新接口。CC Switch 保存时若提示「未找到可用的模型列表端点」,官方说明可忽略:Anthropic 兼容端点只提供 /v1/messages,不提供 /v1/models,该探测会返回 404,但不影响正常对话。
常见问题
Token Plan 和按量计费可以共用一把 Key 吗?
不可以。官方明确两种 API Key 互不通用,必须和对应的 Base URL 一起使用。
Claude Code 默认上下文只有 200K,怎样用到 100 万?
官方说明 Claude Code 默认 200K 窗口。对 Qwen4-Max,把 CLAUDE_CODE_MAX_CONTEXT_TOKENS 设为 983616(思考模式最大输入)。不要用已经不推荐的旧代理地址。
工作台还显示有额度,却已经开始计费?
Cherry Studio 文档写明:各模型额度相互独立,不能跨模型共享;工作台数据每小时更新,显示仍有余量时,实际额度也可能已经用完。以调用记录和账单为准。
信息来源
- 千问 AI 平台:最新模型 Qwen4-Max
- 千问 AI 平台:Claude Code 接入文档
- 千问 AI 平台:Codex 接入文档
- 千问 AI 平台:Cherry Studio 接入文档
- Cherry Studio 官方 GitHub 仓库
- 本站:Qwen4-Max 正式上线:API 已开放,单价下调
核实时间:2026-11-18(Asia/Shanghai)。步骤、地址、型号和报错说明均据上述官方文档整理,未在本地逐项实测。接口和参数若有更新,以千问 AI 平台当前文档为准。
