mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-04-28 19:52:02 +00:00
docs: improve settings.json configuration guide with quick setup examples
- Add comprehensive quick setup section with 3-step guide for settings.json - Include multiple practical examples (Coding Plan, multi-provider, thinking mode) - Update README with settings.json quick reference table - Enhance auth.md with one-file setup recommendation - Clarify field descriptions and priority order for API key configuration Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
pomelo-nwu
parent
f467c2493f
commit
ed81e89620
2 changed files with 284 additions and 18 deletions
|
|
@ -31,6 +31,52 @@ qwen
|
|||
|
||||
Use this if you want more flexibility over which provider and model to use. Supports multiple protocols and providers, including OpenAI, Anthropic, Google GenAI, Alibaba Cloud Bailian, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted compatible endpoint.
|
||||
|
||||
### Recommended: One-file setup via `settings.json`
|
||||
|
||||
The simplest way to get started with API-KEY authentication is to put everything in a single `~/.qwen/settings.json` file. Here's a complete, ready-to-use example:
|
||||
|
||||
```json
|
||||
{
|
||||
"modelProviders": {
|
||||
"openai": [
|
||||
{
|
||||
"id": "qwen3-coder-plus",
|
||||
"name": "qwen3-coder-plus",
|
||||
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||||
"description": "Qwen3-Coder via Dashscope",
|
||||
"envKey": "DASHSCOPE_API_KEY"
|
||||
}
|
||||
]
|
||||
},
|
||||
"env": {
|
||||
"DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "openai"
|
||||
}
|
||||
},
|
||||
"model": {
|
||||
"name": "qwen3-coder-plus"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
What each field does:
|
||||
|
||||
| Field | Description |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `modelProviders` | Declares which models are available and how to connect to them. Keys (`openai`, `anthropic`, `gemini`, `vertex-ai`) represent the API protocol. |
|
||||
| `env` | Stores API keys directly in `settings.json` as a fallback (lowest priority — shell `export` and `.env` files take precedence). |
|
||||
| `security.auth.selectedType` | Tells Qwen Code which protocol to use on startup (e.g. `openai`, `anthropic`, `gemini`). Without this, you'd need to run `/auth` interactively. |
|
||||
| `model.name` | The default model to activate when Qwen Code starts. Must match one of the `id` values in your `modelProviders`. |
|
||||
|
||||
After saving the file, just run `qwen` — no interactive `/auth` setup needed.
|
||||
|
||||
> [!tip]
|
||||
>
|
||||
> The sections below explain each part in more detail. If the quick example above works for you, feel free to skip ahead to [Security notes](#security-notes).
|
||||
|
||||
### Option1: Coding Plan（Aliyun Bailian）
|
||||
|
||||
Use this if you want predictable costs with higher usage quotas for the qwen3-coder-plus model.
|
||||
|
|
@ -52,6 +98,41 @@ Enter your `sk-sp-xxxxxxxxx` key, then use the `/model` command to switch be
|
|||
|
||||
|
||||
|
||||
**Alternative: configure Coding Plan via `settings.json`**
|
||||
|
||||
If you prefer to skip the interactive `/auth` flow, add the following to `~/.qwen/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"modelProviders": {
|
||||
"openai": [
|
||||
{
|
||||
"id": "qwen3-coder-plus",
|
||||
"name": "qwen3-coder-plus (Coding Plan)",
|
||||
"baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
|
||||
"description": "qwen3-coder-plus from Bailian Coding Plan",
|
||||
"envKey": "BAILIAN_CODING_PLAN_API_KEY"
|
||||
}
|
||||
]
|
||||
},
|
||||
"env": {
|
||||
"BAILIAN_CODING_PLAN_API_KEY": "sk-sp-xxxxxxxxx"
|
||||
},
|
||||
"security": {
|
||||
"auth": {
|
||||
"selectedType": "openai"
|
||||
}
|
||||
},
|
||||
"model": {
|
||||
"name": "qwen3-coder-plus"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!note]
|
||||
>
|
||||
> The Coding Plan uses a dedicated endpoint (`https://coding.dashscope.aliyuncs.com/v1`) that is different from the standard Dashscope endpoint. Make sure to use the correct `baseUrl`.
|
||||
|
||||
### Option2: Third-party API-KEY
|
||||
|
||||
Use this if you want to connect to third-party providers such as OpenAI, Anthropic, Google, Azure OpenAI, OpenRouter, ModelScope, or a self-hosted endpoint.
|
||||
|
|
@ -67,7 +148,7 @@ The key concept is **Model Providers** (`modelProviders`): Qwen Code supports mu
|
|||
| Google GenAI | `gemini` | `GEMINI_API_KEY`, `GEMINI_MODEL` | Google Gemini |
|
||||
| Google Vertex AI | `vertex-ai` | `GOOGLE_API_KEY`, `GOOGLE_MODEL` | Google Vertex AI |
|
||||
|
||||
#### Step 1: Configure `modelProviders` in `~/.qwen/settings.json`
|
||||
#### Step 1: Configure models and providers in `~/.qwen/settings.json`
|
||||
|
||||
Define which models are available for each protocol. Each model entry requires at minimum an `id` and an `envKey` (the environment variable name that holds your API key).
|
||||
|
||||
|
|
@ -75,7 +156,7 @@ Define which models are available for each protocol. Each model entry requires a
|
|||
>
|
||||
> It is recommended to define `modelProviders` in the user-scope `~/.qwen/settings.json` to avoid merge conflicts between project and user settings.
|
||||
|
||||
Edit `~/.qwen/settings.json` (create it if it doesn't exist):
|
||||
Edit `~/.qwen/settings.json` (create it if it doesn't exist). You can mix multiple protocols in a single file — here is a multi-provider example showing just the `modelProviders` section:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -106,7 +187,11 @@ Edit `~/.qwen/settings.json` (create it if it doesn't exist):
|
|||
}
|
||||
```
|
||||
|
||||
You can mix multiple protocols and models in a single configuration. The `ModelConfig` fields are:
|
||||
> [!tip]
|
||||
>
|
||||
> Don't forget to also set `env`, `security.auth.selectedType`, and `model.name` alongside `modelProviders` — see the [complete example above](#recommended-one-file-setup-via-settingsjson) for reference.
|
||||
|
||||
**`ModelConfig` fields (each entry inside `modelProviders`):**
|
||||
|
||||
| Field | Required | Description |
|
||||
| ------------------ | -------- | -------------------------------------------------------------------- |
|
||||
|
|
@ -118,7 +203,7 @@ You can mix multiple protocols and models in a single configuration. The `ModelC
|
|||
|
||||
> [!note]
|
||||
>
|
||||
> Credentials are **never** stored in `settings.json`. The runtime reads them from the environment variable specified in `envKey`.
|
||||
> When using the `env` field in `settings.json`, credentials are stored in plain text. For better security, prefer `.env` files or shell `export` — see [Step 2](#step-2-set-environment-variables).
|
||||
|
||||
For the full `modelProviders` schema and advanced options like `generationConfig`, `customHeaders`, and `extra_body`, see [Settings Reference → modelProviders](settings.md#modelproviders).
|
||||
|
||||
|
|
@ -165,25 +250,19 @@ If nothing is found, it falls back to your **home directory**:
|
|||
|
||||
**3. `settings.json` → `env` field (lowest priority)**
|
||||
|
||||
You can also define environment variables directly in `~/.qwen/settings.json` under the `env` key. These are loaded as the **lowest-priority fallback** — only applied when a variable is not already set by the system environment or `.env` files.
|
||||
You can also define API keys directly in `~/.qwen/settings.json` under the `env` key. These are loaded as the **lowest-priority fallback** — only applied when a variable is not already set by the system environment or `.env` files.
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"DASHSCOPE_API_KEY":"sk-...",
|
||||
"DASHSCOPE_API_KEY": "sk-...",
|
||||
"OPENAI_API_KEY": "sk-...",
|
||||
"ANTHROPIC_API_KEY": "sk-ant-...",
|
||||
"GEMINI_API_KEY": "AIza..."
|
||||
},
|
||||
"modelProviders": {
|
||||
...
|
||||
"ANTHROPIC_API_KEY": "sk-ant-..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!note]
|
||||
>
|
||||
> This is useful when you want to keep all configuration (providers + credentials) in a single file. However, be mindful that `settings.json` may be shared or synced — prefer `.env` files for sensitive secrets.
|
||||
This is the approach used in the [one-file setup example](#recommended-one-file-setup-via-settingsjson) above. It's convenient for keeping everything in one place, but be mindful that `settings.json` may be shared or synced — prefer `.env` files for sensitive secrets.
|
||||
|
||||
**Priority summary:**
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue