Qwen4-Max接入配置教程:API与客户端

浏览:1次阅读
没有评论
发布日期:

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

Qwen4-Max接入配置教程:API与客户端插图
图片来源:IT 之家报道所刊 Qwen 官方海报

本站此前已介绍过 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。点击添加后,回到对话界面选中该模型,发一条消息,能正常返回即配置成功。

Qwen4-Max接入配置教程:API与客户端插图1
图片来源:Cherry Studio 官方 GitHub README 截图(模型供应商设置)
Qwen4-Max接入配置教程:API与客户端插图2
图片来源:Cherry Studio 官方 GitHub README 截图(对话界面)

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 文档写明:各模型额度相互独立,不能跨模型共享;工作台数据每小时更新,显示仍有余量时,实际额度也可能已经用完。以调用记录和账单为准。

信息来源

核实时间:2026-11-18(Asia/Shanghai)。步骤、地址、型号和报错说明均据上述官方文档整理,未在本地逐项实测。接口和参数若有更新,以千问 AI 平台当前文档为准。

订阅更新
Qwen4-Max接入配置教程:API与客户端插图7Qwen4-Max接入配置教程:API与客户端插图8微信扫码关注「狠活 AI」
用 RSS 阅读器订阅本站,新教程第一时间收到。RSS 订阅
正文完
 0