Motivation / 动机

English

The current /auth -> API Key -> Custom API Key flow only points users to the model provider documentation. This creates a broken setup experience: users must leave the CLI, understand settings.json, manually configure modelProviders, choose an envKey, store API keys, and then return to Qwen Code to verify whether authentication works.

This is especially painful because the neighboring API key flows, such as Alibaba Cloud ModelStudio Standard API Key, already provide guided in-terminal setup. Custom API key users expect a similar experience.

Qwen Code already supports multiple provider protocols through modelProviders, including openai, anthropic, and gemini. The custom API key setup should expose that capability directly in /auth by guiding users through protocol selection, endpoint input, API key input, model IDs, and a JSON review step before saving.

The goal is to make custom provider setup discoverable, transparent, and recoverable without requiring users to manually edit configuration files for the common path.

中文

当前 /auth -> API Key -> Custom API Key 流程只引导用户查看 model provider 文档，导致配置体验是断开的：用户需要离开 CLI，理解 settings.json、手动配置 modelProviders、选择 envKey、保存 API Key，然后再回到 Qwen Code 验证认证是否成功。

这个体验和相邻的 API Key 流程不一致。例如 Alibaba Cloud ModelStudio Standard API Key 已经提供了完整的终端内配置向导，而 Custom API Key 用户也会自然期待类似体验。

Qwen Code 已经通过 modelProviders 支持多种协议，包括 openai、anthropic、gemini。Custom API Key 配置应该在 /auth 中直接暴露这个能力，引导用户完成协议选择、Base URL 输入、API Key 输入、Model IDs 输入，并在保存前展示生成的 JSON 供用户 Review。

目标是让自定义 provider 的配置过程更易发现、更透明、更可恢复，避免普通用户为了常见场景必须手动编辑配置文件。

Proposed direction / 方向

• Replace the documentation-only Custom API Key screen with an in-terminal wizard.
• Start with protocol selection: openai, anthropic, gemini.
• Treat Base URL as the custom-provider equivalent of region selection.
• Generate a Qwen-managed private envKey from protocol + Base URL.
• Store the API key in settings.json.env.
• Show generated JSON before saving.
• Preserve unrelated existing modelProviders entries.
• Save settings and immediately attempt authentication.

Design doc / 设计文档

A PR will follow with the product design document under docs/design/.