• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

本篇技术指南聚焦 OpenClaw 项目中 Qwen 提供方的接入方案：通过免费层的 OAuth 设备码流程，在qwen-portal提供方下使用 Qwen Coder 与 Qwen Vision 模型（每日约 2,000 次请求，具体受 Qwen 速率限制约束）。读完本文，你将掌握启用qwen-portal-auth插件、执行openclaw models auth login设备码认证、写入models.json提供方条目、创建qwen别名快速切换，以及复用 Qwen Code CLI 已有登录、覆盖baseUrl等完整实战能力。

一、整体认知：Qwen 提供方在 OpenClaw 中的定位

OpenClaw 对 LLM/模型提供方的抽象遵循provider/model的引用规则（参见 模型提供方总览）。Qwen 属于通过 OAuth 免费层接入的提供方，与其他需要API_KEY的提供方（如 OpenAI、Anthropic、Gemini）不同，它走的是「设备码（device-code）OAuth 流程」：你在终端触发登录后，浏览器完成授权，凭证被写入本机认证存储，之后无需再持有/轮换 API Key。

从源码结构看，本仓库对 Qwen 的支持分两条线：

• qwen-portal提供方（本文主体）：走 Qwen Portal 官方免费层 OAuth，基础 URL 为https://portal.qwen.ai/v1，对应模型qwen-portal/coder-model与qwen-portal/vision-model；
• Web 免 Token 通道（同一仓库内的兄弟实现）：集中在 src/zero-token/，其中qwen-web（阿里国内）与qwen-cn-web（阿里国际）通过浏览器会话认证，不需要 API Token（见 Web Models 支持文档）。

本文严格围绕官方文档 docs/providers/qwen.md 所讲解的qwen-portal免费层 OAuth 展开。

二、第一步：启用qwen-portal-auth插件

Qwen 的 OAuth 能力由随 OpenClaw 捆绑发布的插件qwen-portal-auth提供。与大多数捆绑插件一样，它默认是禁用状态，必须显式启用（参见 插件文档 中「Bundled extensions」一节）。

openclaw plugins enable qwen-portal-auth

启用后，必须重启 Gateway 网关使插件生效。这一点与 OpenClaw 的插件机制一致：插件加载与配置变更都需要重启 Gateway 后才能被运行时识别（configuration-reference.md 中也明确指出「Config changes require a gateway restart」）。

如果是在服务化部署场景（daemon/service 模式），可以用openclaw gateway restart或通过服务管理器重启；本地开发场景直接重启openclaw gateway进程即可。

三、第二步：执行设备码 OAuth 认证

启用插件后，使用models auth login子命令完成认证：

openclaw models auth login --provider qwen-portal --set-default

这条命令做了什么？可以从 CLI 参考文档 与模型提供方总览得到印证：

1. models auth login会调用对应提供方插件的认证流程（OAuth/API key），--provider qwen-portal指定走 Qwen 的设备码流程；
2. 运行过程中，终端会展示设备码并引导你在浏览器中完成 Qwen 账户授权；
3. 认证完成后，OpenClaw 会把一个qwen-portal提供方条目写入你的models.json（配置存放位置为~/.openclaw/agents/<agentId>/agent/models.json或 agent 目录下的models.json，参见 configuration-reference.md）；
4. 同时生成一个qwen别名，便于后续快速切换模型；
5. --set-default将该提供方设为默认，后续openclaw models set <model>不带提供方前缀时也会优先解析到它。

认证结果的查看与校验：

openclaw models status # 查看默认模型、fallbacks 与认证概况 openclaw models auth list # 查看已配置的认证 profile openclaw models aliases list # 查看 qwen 别名

补充说明：models status的认证输出中，Qwen OAuth 这类非密钥占位符会以qwen-oauth之类的marker(<value>)形式展示，而不是像OPENAI_API_KEY那样被当作密钥脱敏——这是正常的，因为 OAuth 会话凭证与静态 API Key 的敏感等级不同（见 docs/cli/models.md）。

四、模型 ID 与切换

qwen-portal提供方在免费层暴露两个模型：

切换模型使用openclaw models set：

openclaw models set qwen-portal/coder-model

models set <model-or-alias>同时接受provider/model完整引用或别名两种形式（docs/cli/models.md）。因此认证时自动生成的qwen别名，可以让你用更短的命令切换：

openclaw models set qwen

在需要把某个 Agent 固定到 Qwen 的场景，也可以在openclaw.json中通过agents.defaults.model.primary指定：

{ agents: { defaults: { model: { primary: "qwen-portal/coder-model" } } }, }

注意：模型引用按第一个/分割 provider 与 model id（docs/cli/models.md），所以qwen-portal/coder-model中 provider 是qwen-portal，model id 是coder-model，中间不得再出现未转义的斜杠。

五、复用 Qwen Code CLI 的已有登录

如果你之前已经用 Qwen Code CLI 登录过（阿里官方编程 CLI），OpenClaw 会在加载认证存储（auth store）时自动同步其凭证：

• 同步来源：~/.qwen/oauth_creds.json
• 同步时机：每次加载 auth store（即 Gateway 启动 / 认证状态刷新）时自动进行，无需手动导入

但有两点必须注意：

1. 仍需存在models.providers.qwen-portal条目。自动同步的只是凭证本身；OpenClaw 仍然需要一个 provider 配置条目才能知道如何用它。请用上面的openclaw models auth login --provider qwen-portal --set-default生成该条目（该命令会写入models.json并提供qwen别名）；
2. 凭证同步后如果失效，或访问被撤销，重新执行登录命令即可刷新。

六、令牌自动刷新与失败恢复

Qwen Portal 的 OAuth 令牌支持自动刷新，因此日常使用中无需手动维护 access token。需要人工介入的情形包括：

• 刷新失败：令牌自动刷新流程报错（例如刷新凭证过期、网络问题导致 Refresh Token 失效）；
• 访问被撤销：你在 Qwen 账户侧撤销了该应用的授权；
• 长期未使用：会话过期后再次调用模型报认证错误。

以上情况统一处理方式：重新运行登录命令即可重建会话：

openclaw models auth login --provider qwen-portal --set-default

另外，如果终端在执行 webauth/onboard 类浏览器授权流程后长时间未返回提示符，可按Ctrl+C退出进程——凭证通常已在退出前写入auth-profiles.json/openclaw.json（该提示同样适用于 Qwen 的浏览器认证路径，见 web-models-support.md）。

七、默认 Base URL 与覆盖方式

Qwen Portal 的默认 API 基础地址为：

https://portal.qwen.ai/v1

正常情况下无需任何额外配置。若 Qwen 官方后续提供不同的端点（例如区域化网关或新版本入口），通过配置覆盖：

{ models: { mode: "merge", providers: { "qwen-portal": { baseUrl: "https://portal.qwen.ai/v1" } } } }

覆盖后需要重启 Gateway 使配置生效。models.providers.*.baseUrl是 OpenClaw 自定义/兼容提供方的通用配置项，同时支持models.providers.*.api（请求适配器，如openai-completions）、models.providers.*.apiKey、models.providers.*.auth等字段（完整清单见 configuration-reference.md）。Qwen Portal 走 OAuth，因此该条目通常不需要 apiKey。

八、扩展阅读：Qwen Web 免 Token 通道（同一仓库内的兄弟能力）

qwen-portal是官方免费层 OAuth 入口；而本仓库（OpenClaw Zero-Token）还在 src/zero-token/ 中实现了Qwen Web 浏览器会话通道，属于「所有主流模型无需 API Token」路线的一部分：

• Provider ID：qwen-web（阿里国内）、qwen-cn-web（阿里国际），见 web-models-support.md；
• 认证方式：启动 Chrome 调试模式（./start-chrome-debug.sh，默认 CDP 端口 9222），然后运行pnpm openclaw webauth或pnpm openclaw onboard，在打开的https://chat.qwen.ai页面登录，OpenClaw 通过 CDP 捕获 session cookie / authorization token（实现见 qwen-web-auth.ts）；
• 流式调用：createQwenWebStreamFn会把浏览器会话凭证转换为标准 StreamFn，并从响应流中解析文本、<think>思考块与<tool_call>工具调用（实现见 qwen-web-stream.ts，浏览器客户端见 qwen-web-client-browser.ts）。

这条 Web 通道与qwen-portal互为补充：前者面向「完全没有 API Key、直接用浏览器会话」的场景，后者面向「官方免费层 OAuth、带每日请求配额」的场景。若在浏览器认证中遇到 "Session detected but token expired"，说明会话已过期，需要重新登录（见 web-models-support.md 的故障排除小节）。

九、常见问题速查

十、小结

Qwen 免费层 OAuth 在 OpenClaw 中的接入路径非常清晰：openclaw plugins enable qwen-portal-auth启用捆绑插件 → 重启 Gateway →openclaw models auth login --provider qwen-portal --set-default完成设备码认证 →openclaw models set qwen-portal/coder-model（或vision-model）切换模型。认证凭证写入models.json并附带qwen别名，令牌自动刷新；若已使用 Qwen Code CLI，OpenClaw 还会从~/.qwen/oauth_creds.json自动同步凭证。默认端点https://portal.qwen.ai/v1可通过models.providers.qwen-portal.baseUrl覆盖。结合仓库中的 qwen.md 文档、模型提供方总览 与 CLI 参考，即可在 OpenClaw 中稳定使用 Qwen Coder 与 Qwen Vision 的免费额度。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯