@qwen-code/qwen-code 0.14.3 β 0.14.4-nightly.20260415.9f9ffbf95
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/bundled/qc-helper/docs/configuration/auth.md +2 -2
- package/bundled/qc-helper/docs/configuration/settings.md +21 -12
- package/bundled/qc-helper/docs/features/_meta.ts +1 -0
- package/bundled/qc-helper/docs/features/hooks.md +113 -0
- package/bundled/qc-helper/docs/features/sandbox.md +9 -1
- package/bundled/qc-helper/docs/features/sub-agents.md +126 -6
- package/bundled/qc-helper/docs/features/tips.md +54 -0
- package/bundled/qc-helper/docs/support/tos-privacy.md +1 -1
- package/cli.js +260482 -255645
- package/locales/de.js +17 -4
- package/locales/en.js +16 -4
- package/locales/fr.js +2087 -0
- package/locales/ja.js +16 -4
- package/locales/pt.js +17 -4
- package/locales/ru.js +17 -4
- package/locales/zh.js +16 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -20,6 +20,8 @@
|
|
|
20
20
|
|
|
21
21
|
## π News
|
|
22
22
|
|
|
23
|
+
- **2026-04-13**: Qwen OAuth free tier policy update: daily quota adjusted to 100 requests/day (from 1,000). The free tier will be discontinued on 2026-04-15. Consider using [OpenRouter](https://openrouter.ai), [Fireworks AI](https://app.fireworks.ai), or [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2840914_2&modelId=qwen3.6-plus) as alternatives.
|
|
24
|
+
|
|
23
25
|
- **2026-04-02**: Qwen3.6-Plus is now live! Sign in via Qwen OAuth to use it directly, or get an API key from [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2840914_2&modelId=qwen3.6-plus) to access it through the OpenAI-compatible API.
|
|
24
26
|
|
|
25
27
|
- **2026-02-16**: Qwen3.5-Plus is now live!
|
|
@@ -28,7 +30,7 @@
|
|
|
28
30
|
|
|
29
31
|
Qwen Code is an open-source AI agent for the terminal, optimized for Qwen series models. It helps you understand large codebases, automate tedious work, and ship faster.
|
|
30
32
|
|
|
31
|
-
- **Multi-protocol, OAuth free tier**: use OpenAI / Anthropic / Gemini-compatible APIs, or sign in with Qwen OAuth for
|
|
33
|
+
- **Multi-protocol, OAuth free tier**: use OpenAI / Anthropic / Gemini-compatible APIs, or sign in with Qwen OAuth for 100 free requests/day (free tier ending 2026-04-15). After that, switch to [OpenRouter](https://openrouter.ai), [Fireworks AI](https://app.fireworks.ai), or [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2840914_2&modelId=qwen3.6-plus).
|
|
32
34
|
- **Open-source, co-evolving**: both the framework and the Qwen3-Coder model are open-sourceβand they ship and evolve together.
|
|
33
35
|
- **Agentic workflow, feature-rich**: rich built-in tools (Skills, SubAgents) for a full agentic workflow and a Claude Code-like experience.
|
|
34
36
|
- **Terminal-first, IDE-friendly**: built for developers who live in the command line, with optional integration for VS Code, Zed, and JetBrains IDEs.
|
|
@@ -13,7 +13,7 @@ Use this if you want the simplest setup and you're using Qwen models.
|
|
|
13
13
|
- **How it works**: on first start, Qwen Code opens a browser login page. After you finish, credentials are cached locally so you usually won't need to log in again.
|
|
14
14
|
- **Requirements**: a `qwen.ai` account + internet access (at least for the first login).
|
|
15
15
|
- **Benefits**: no API key management, automatic credential refresh.
|
|
16
|
-
- **Cost & quota**: free, with a quota of **60 requests/minute** and **
|
|
16
|
+
- **Cost & quota**: free, with a quota of **60 requests/minute** and **100 requests/day**. Note: the free tier will be discontinued on 2026-04-15. After that, consider switching to [OpenRouter](https://openrouter.ai), [Fireworks AI](https://app.fireworks.ai), or [Alibaba Cloud ModelStudio](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2840914_2&modelId=qwen3.6-plus) β run `qwen auth` to configure your new provider.
|
|
17
17
|
|
|
18
18
|
Start the CLI and follow the browser flow:
|
|
19
19
|
|
|
@@ -327,7 +327,7 @@ You'll see a selector with arrow-key navigation:
|
|
|
327
327
|
```
|
|
328
328
|
Select authentication method:
|
|
329
329
|
|
|
330
|
-
> Qwen OAuth - Free Β·
|
|
330
|
+
> Qwen OAuth - Free Β· 100 requests/day Β· Ending 2026-04-15
|
|
331
331
|
Alibaba Cloud Coding Plan - Paid Β· Up to 6,000 requests/5 hrs Β· All Alibaba Cloud Coding Plan Models
|
|
332
332
|
|
|
333
333
|
(Use β β arrows to navigate, Enter to select, Ctrl+C to exit)
|
|
@@ -100,7 +100,7 @@ Settings are organized into categories. All settings should be placed within the
|
|
|
100
100
|
| `ui.customThemes` | object | Custom theme definitions. | `{}` |
|
|
101
101
|
| `ui.statusLine` | object | Custom status line configuration. A shell command whose output is shown in the footer's left section. See [Status Line](../features/status-line). | `undefined` |
|
|
102
102
|
| `ui.hideWindowTitle` | boolean | Hide the window title bar. | `false` |
|
|
103
|
-
| `ui.hideTips` | boolean | Hide
|
|
103
|
+
| `ui.hideTips` | boolean | Hide all tips (startup and post-response) in the UI. See [Contextual Tips](../features/tips). | `false` |
|
|
104
104
|
| `ui.hideBanner` | boolean | Hide the application banner. | `false` |
|
|
105
105
|
| `ui.hideFooter` | boolean | Hide the footer from the UI. | `false` |
|
|
106
106
|
| `ui.showMemoryUsage` | boolean | Display memory usage information in the UI. | `false` |
|
|
@@ -210,17 +210,19 @@ The `extra_body` field allows you to add custom parameters to the request body s
|
|
|
210
210
|
|
|
211
211
|
#### context
|
|
212
212
|
|
|
213
|
-
| Setting
|
|
214
|
-
|
|
|
215
|
-
| `context.fileName`
|
|
216
|
-
| `context.importFormat`
|
|
217
|
-
| `context.includeDirectories`
|
|
218
|
-
| `context.loadFromIncludeDirectories`
|
|
219
|
-
| `context.fileFiltering.respectGitIgnore`
|
|
220
|
-
| `context.fileFiltering.respectQwenIgnore`
|
|
221
|
-
| `context.fileFiltering.enableRecursiveFileSearch`
|
|
222
|
-
| `context.fileFiltering.enableFuzzySearch`
|
|
223
|
-
| `context.
|
|
213
|
+
| Setting | Type | Description | Default |
|
|
214
|
+
| -------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
|
215
|
+
| `context.fileName` | string or array of strings | The name of the context file(s). | `undefined` |
|
|
216
|
+
| `context.importFormat` | string | The format to use when importing memory. | `undefined` |
|
|
217
|
+
| `context.includeDirectories` | array | Additional directories to include in the workspace context. Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. | `[]` |
|
|
218
|
+
| `context.loadFromIncludeDirectories` | boolean | Controls the behavior of the `/memory refresh` command. If set to `true`, `QWEN.md` files should be loaded from all directories that are added. If set to `false`, `QWEN.md` should only be loaded from the current directory. | `false` |
|
|
219
|
+
| `context.fileFiltering.respectGitIgnore` | boolean | Respect .gitignore files when searching. | `true` |
|
|
220
|
+
| `context.fileFiltering.respectQwenIgnore` | boolean | Respect .qwenignore files when searching. | `true` |
|
|
221
|
+
| `context.fileFiltering.enableRecursiveFileSearch` | boolean | Whether to enable searching recursively for filenames under the current tree when completing `@` prefixes in the prompt. | `true` |
|
|
222
|
+
| `context.fileFiltering.enableFuzzySearch` | boolean | When `true`, enables fuzzy search capabilities when searching for files. Set to `false` to improve performance on projects with a large number of files. | `true` |
|
|
223
|
+
| `context.clearContextOnIdle.thinkingThresholdMinutes` | number | Minutes of inactivity before clearing old thinking blocks to free context tokens. Aligns with typical provider prompt-cache TTL. Use `-1` to disable. | `5` |
|
|
224
|
+
| `context.clearContextOnIdle.toolResultsThresholdMinutes` | number | Minutes of inactivity before clearing old tool result content. Use `-1` to disable. | `60` |
|
|
225
|
+
| `context.clearContextOnIdle.toolResultsNumToKeep` | number | Number of most-recent compactable tool results to preserve when clearing. Floor at 1. | `5` |
|
|
224
226
|
|
|
225
227
|
#### Troubleshooting File Search Performance
|
|
226
228
|
|
|
@@ -235,6 +237,7 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
|
|
|
235
237
|
| Setting | Type | Description | Default | Notes |
|
|
236
238
|
| ------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
237
239
|
| `tools.sandbox` | boolean or string | Sandbox execution environment (can be a boolean or a path string). | `undefined` | |
|
|
240
|
+
| `tools.sandboxImage` | string | Sandbox image URI used by Docker/Podman when `--sandbox-image` and `QWEN_SANDBOX_IMAGE` are not set. | `undefined` | |
|
|
238
241
|
| `tools.shell.enableInteractiveShell` | boolean | Use `node-pty` for an interactive shell experience. Fallback to `child_process` still applies. | `false` | |
|
|
239
242
|
| `tools.core` | array of strings | **Deprecated.** Will be removed in next version. Use `permissions.allow` + `permissions.deny` instead. Restricts built-in tools to an allowlist. All tools not in the list are disabled. | `undefined` | |
|
|
240
243
|
| `tools.exclude` | array of strings | **Deprecated.** Use `permissions.deny` instead. Tool names to exclude from discovery. Automatically migrated to the `permissions` format on first load. | `undefined` | |
|
|
@@ -442,6 +445,7 @@ Here is an example of a `settings.json` file with the nested structure, new as o
|
|
|
442
445
|
"tools": {
|
|
443
446
|
"approvalMode": "yolo",
|
|
444
447
|
"sandbox": "docker",
|
|
448
|
+
"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1",
|
|
445
449
|
"discoveryCommand": "bin/get_tools",
|
|
446
450
|
"callCommand": "bin/call_tool",
|
|
447
451
|
"exclude": ["write_file"]
|
|
@@ -515,6 +519,7 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.qwe
|
|
|
515
519
|
| `QWEN_TELEMETRY_OUTFILE` | Sets the file path to write telemetry to when the target is `local`. | Overrides the `telemetry.outfile` setting. |
|
|
516
520
|
| `QWEN_TELEMETRY_USE_COLLECTOR` | Set to `true` or `1` to enable or disable using an external OTLP collector. Any other value is treated as disabling it. | Overrides the `telemetry.useCollector` setting. |
|
|
517
521
|
| `QWEN_SANDBOX` | Alternative to the `sandbox` setting in `settings.json`. | Accepts `true`, `false`, `docker`, `podman`, or a custom command string. |
|
|
522
|
+
| `QWEN_SANDBOX_IMAGE` | Overrides sandbox image selection for Docker/Podman. | Takes precedence over `tools.sandboxImage`. |
|
|
518
523
|
| `SEATBELT_PROFILE` | (macOS specific) Switches the Seatbelt (`sandbox-exec`) profile on macOS. | `permissive-open`: (Default) Restricts writes to the project folder (and a few other folders, see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other operations. `strict`: Uses a strict profile that declines operations by default. `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.qwen/` directory (e.g., `my-project/.qwen/sandbox-macos-custom.sb`). |
|
|
519
524
|
| `DEBUG` or `DEBUG_MODE` | (often used by underlying libraries or the CLI itself) Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting. | **Note:** These variables are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Use `.qwen/.env` files if you need to set these for Qwen Code specifically. |
|
|
520
525
|
| `NO_COLOR` | Set to any value to disable all color output in the CLI. | |
|
|
@@ -522,11 +527,15 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.qwe
|
|
|
522
527
|
| `CODE_ASSIST_ENDPOINT` | Specifies the endpoint for the code assist server. | This is useful for development and testing. |
|
|
523
528
|
| `QWEN_CODE_MAX_OUTPUT_TOKENS` | Overrides the default maximum output tokens per response. When not set, Qwen Code uses an adaptive strategy: starts with 8K tokens and automatically retries with 64K if the response is truncated. Set this to a specific value (e.g., `16000`) to use a fixed limit instead. | Takes precedence over the capped default (8K) but is overridden by `samplingParams.max_tokens` in settings. Disables automatic escalation when set. Example: `export QWEN_CODE_MAX_OUTPUT_TOKENS=16000` |
|
|
524
529
|
| `TAVILY_API_KEY` | Your API key for the Tavily web search service. | Used to enable the `web_search` tool functionality. Example: `export TAVILY_API_KEY="tvly-your-api-key-here"` |
|
|
530
|
+
| `QWEN_CODE_PROFILE_STARTUP` | Set to `1` to enable startup performance profiling. Writes a JSON timing report to `~/.qwen/startup-perf/` with per-phase durations. | Only active inside the sandbox child process. Zero overhead when not set. Example: `export QWEN_CODE_PROFILE_STARTUP=1` |
|
|
525
531
|
|
|
526
532
|
## Command-Line Arguments
|
|
527
533
|
|
|
528
534
|
Arguments passed directly when running the CLI can override other configurations for that specific session.
|
|
529
535
|
|
|
536
|
+
For sandbox image selection, precedence is:
|
|
537
|
+
`--sandbox-image` > `QWEN_SANDBOX_IMAGE` > `tools.sandboxImage` > built-in default image.
|
|
538
|
+
|
|
530
539
|
### Command-Line Arguments Table
|
|
531
540
|
|
|
532
541
|
| Argument | Alias | Description | Possible Values | Notes |
|
|
@@ -57,9 +57,11 @@ The following table lists all available hook events in Qwen Code:
|
|
|
57
57
|
| `UserPromptSubmit` | Fired when user submits a prompt | Input processing, validation, context injection |
|
|
58
58
|
| `SessionStart` | Fired when a new session starts | Initialization, context setup |
|
|
59
59
|
| `Stop` | Fired before Qwen concludes its response | Finalization, cleanup |
|
|
60
|
+
| `StopFailure` | Fired when turn ends due to API error | Error logging, alerting, rate limit handling |
|
|
60
61
|
| `SubagentStart` | Fired when a subagent starts | Subagent initialization |
|
|
61
62
|
| `SubagentStop` | Fired when a subagent stops | Subagent finalization |
|
|
62
63
|
| `PreCompact` | Fired before conversation compaction | Pre-compaction processing |
|
|
64
|
+
| `PostCompact` | Fired after conversation compaction | Summary archiving, usage statistics |
|
|
63
65
|
| `SessionEnd` | Fired when a session ends | Cleanup, reporting |
|
|
64
66
|
| `PermissionRequest` | Fired when permission dialogs are displayed | Permission automation, policy enforcement |
|
|
65
67
|
|
|
@@ -299,6 +301,60 @@ Event-specific fields are added based on the hook type. Below are the event-spec
|
|
|
299
301
|
}
|
|
300
302
|
```
|
|
301
303
|
|
|
304
|
+
#### StopFailure
|
|
305
|
+
|
|
306
|
+
**Purpose**: Executed when the turn ends due to an API error (instead of Stop). This is a **fire-and-forget** event - hook output and exit codes are ignored.
|
|
307
|
+
|
|
308
|
+
**Event-specific fields**:
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{
|
|
312
|
+
"error": "rate_limit | authentication_failed | billing_error | invalid_request | server_error | max_output_tokens | unknown",
|
|
313
|
+
"error_details": "detailed error message (optional)",
|
|
314
|
+
"last_assistant_message": "the last message from the assistant before the error (optional)"
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
**Matcher**: Matches against the `error` field. For example, `"matcher": "rate_limit"` will only trigger for rate limit errors.
|
|
319
|
+
|
|
320
|
+
**Output Options**:
|
|
321
|
+
|
|
322
|
+
- **None** - StopFailure is fire-and-forget. All hook output and exit codes are ignored.
|
|
323
|
+
|
|
324
|
+
**Exit Code Handling**:
|
|
325
|
+
|
|
326
|
+
| Exit Code | Behavior |
|
|
327
|
+
| --------- | ------------------------- |
|
|
328
|
+
| Any | Ignored (fire-and-forget) |
|
|
329
|
+
|
|
330
|
+
**Example Configuration**:
|
|
331
|
+
|
|
332
|
+
```json
|
|
333
|
+
{
|
|
334
|
+
"hooks": {
|
|
335
|
+
"StopFailure": [
|
|
336
|
+
{
|
|
337
|
+
"matcher": "rate_limit",
|
|
338
|
+
"hooks": [
|
|
339
|
+
{
|
|
340
|
+
"type": "command",
|
|
341
|
+
"command": "/path/to/rate-limit-alert.sh",
|
|
342
|
+
"name": "rate-limit-alerter"
|
|
343
|
+
}
|
|
344
|
+
]
|
|
345
|
+
}
|
|
346
|
+
]
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
**Use Cases**:
|
|
352
|
+
|
|
353
|
+
- Rate limit monitoring and alerting
|
|
354
|
+
- Authentication failure logging
|
|
355
|
+
- Billing error notifications
|
|
356
|
+
- Error statistics collection
|
|
357
|
+
|
|
302
358
|
#### SubagentStart
|
|
303
359
|
|
|
304
360
|
**Purpose**: Executed when a subagent (like the Task tool) is started to set up context or permissions.
|
|
@@ -387,6 +443,63 @@ Event-specific fields are added based on the hook type. Below are the event-spec
|
|
|
387
443
|
}
|
|
388
444
|
```
|
|
389
445
|
|
|
446
|
+
#### PostCompact
|
|
447
|
+
|
|
448
|
+
**Purpose**: Executed after conversation compaction completes to archive summaries or track usage.
|
|
449
|
+
|
|
450
|
+
**Event-specific fields**:
|
|
451
|
+
|
|
452
|
+
```json
|
|
453
|
+
{
|
|
454
|
+
"trigger": "manual | auto",
|
|
455
|
+
"compact_summary": "the summary generated by the compaction process"
|
|
456
|
+
}
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
**Matcher**: Matches against the `trigger` field. For example, `"matcher": "manual"` will only trigger for manual compaction via `/compact` command.
|
|
460
|
+
|
|
461
|
+
**Output Options**:
|
|
462
|
+
|
|
463
|
+
- `hookSpecificOutput.additionalContext`: additional context (for logging only)
|
|
464
|
+
- Standard hook output fields (for logging only)
|
|
465
|
+
|
|
466
|
+
**Note**: PostCompact is **not** in the official decision mode supported events list. The `decision` field and other control fields do not produce any control effects - they are only used for logging purposes.
|
|
467
|
+
|
|
468
|
+
**Exit Code Handling**:
|
|
469
|
+
|
|
470
|
+
| Exit Code | Behavior |
|
|
471
|
+
| --------- | --------------------------------------------------------- |
|
|
472
|
+
| 0 | Success - stdout shown to user in verbose mode |
|
|
473
|
+
| Other | Non-blocking error - stderr shown to user in verbose mode |
|
|
474
|
+
|
|
475
|
+
**Example Configuration**:
|
|
476
|
+
|
|
477
|
+
```json
|
|
478
|
+
{
|
|
479
|
+
"hooks": {
|
|
480
|
+
"PostCompact": [
|
|
481
|
+
{
|
|
482
|
+
"matcher": "manual",
|
|
483
|
+
"hooks": [
|
|
484
|
+
{
|
|
485
|
+
"type": "command",
|
|
486
|
+
"command": "/path/to/save-compact-summary.sh",
|
|
487
|
+
"name": "save-summary"
|
|
488
|
+
}
|
|
489
|
+
]
|
|
490
|
+
}
|
|
491
|
+
]
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
**Use Cases**:
|
|
497
|
+
|
|
498
|
+
- Summary archiving to files or databases
|
|
499
|
+
- Usage statistics tracking
|
|
500
|
+
- Context change monitoring
|
|
501
|
+
- Audit logging for compaction operations
|
|
502
|
+
|
|
390
503
|
#### Notification
|
|
391
504
|
|
|
392
505
|
**Purpose**: Executed when notifications are sent to customize or intercept them.
|
|
@@ -103,8 +103,16 @@ qwen -p "run the test suite"
|
|
|
103
103
|
|
|
104
104
|
- **CLI flag**: `--sandbox-image <image>`
|
|
105
105
|
- **Environment variable**: `QWEN_SANDBOX_IMAGE=<image>`
|
|
106
|
+
- **Settings file**: `tools.sandboxImage` in your `settings.json` (e.g., `{"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}}`)
|
|
106
107
|
|
|
107
|
-
|
|
108
|
+
Priority order (highest to lowest):
|
|
109
|
+
|
|
110
|
+
1. `--sandbox-image`
|
|
111
|
+
2. `QWEN_SANDBOX_IMAGE`
|
|
112
|
+
3. `tools.sandboxImage`
|
|
113
|
+
4. Built-in default image from the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`)
|
|
114
|
+
|
|
115
|
+
`settings.env.QWEN_SANDBOX_IMAGE` also works as a generic env injection mechanism, but `tools.sandboxImage` is the preferred persistent setting.
|
|
108
116
|
|
|
109
117
|
### macOS Seatbelt profiles
|
|
110
118
|
|
|
@@ -12,10 +12,46 @@ Subagents are independent AI assistants that:
|
|
|
12
12
|
- **Work autonomously** - Once given a task, they work independently until completion or failure
|
|
13
13
|
- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time
|
|
14
14
|
|
|
15
|
+
## Fork Subagent (Implicit Fork)
|
|
16
|
+
|
|
17
|
+
In addition to named subagents, Qwen Code supports **implicit forking** β when the AI omits the `subagent_type` parameter, it triggers a fork that inherits the parent's full conversation context.
|
|
18
|
+
|
|
19
|
+
### How Fork Differs from Named Subagents
|
|
20
|
+
|
|
21
|
+
| | Named Subagent | Fork Subagent |
|
|
22
|
+
| ------------- | --------------------------------- | ----------------------------------------------------- |
|
|
23
|
+
| Context | Starts fresh, no parent history | Inherits parent's full conversation history |
|
|
24
|
+
| System prompt | Uses its own configured prompt | Uses parent's exact system prompt (for cache sharing) |
|
|
25
|
+
| Execution | Blocks the parent until done | Runs in background, parent continues immediately |
|
|
26
|
+
| Use case | Specialized tasks (testing, docs) | Parallel tasks that need the current context |
|
|
27
|
+
|
|
28
|
+
### When Fork is Used
|
|
29
|
+
|
|
30
|
+
The AI automatically uses fork when it needs to:
|
|
31
|
+
|
|
32
|
+
- Run multiple research tasks in parallel (e.g., "investigate module A, B, and C")
|
|
33
|
+
- Perform background work while continuing the main conversation
|
|
34
|
+
- Delegate tasks that require understanding of the current conversation context
|
|
35
|
+
|
|
36
|
+
### Prompt Cache Sharing
|
|
37
|
+
|
|
38
|
+
All forks share the parent's exact API request prefix (system prompt, tools, conversation history), enabling DashScope prompt cache hits. When 3 forks run in parallel, the shared prefix is cached once and reused β saving 80%+ token costs compared to independent subagents.
|
|
39
|
+
|
|
40
|
+
### Recursive Fork Prevention
|
|
41
|
+
|
|
42
|
+
Fork children cannot create further forks. This is enforced at runtime β if a fork attempts to spawn another fork, it receives an error instructing it to execute tasks directly.
|
|
43
|
+
|
|
44
|
+
### Current Limitations
|
|
45
|
+
|
|
46
|
+
- **No result feedback**: Fork results are reflected in the UI progress display but are not automatically fed back into the main conversation. The parent AI sees a placeholder message and cannot act on the fork's output.
|
|
47
|
+
- **No worktree isolation**: Forks share the parent's working directory. Concurrent file modifications from multiple forks may conflict.
|
|
48
|
+
|
|
15
49
|
## Key Benefits
|
|
16
50
|
|
|
17
51
|
- **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
|
|
18
52
|
- **Context Isolation**: Keep specialized work separate from your main conversation
|
|
53
|
+
- **Context Inheritance**: Fork subagents inherit the full conversation for context-heavy parallel tasks
|
|
54
|
+
- **Prompt Cache Sharing**: Fork subagents share the parent's cache prefix, reducing token costs
|
|
19
55
|
- **Reusability**: Save and reuse agent configurations across projects and sessions
|
|
20
56
|
- **Controlled Access**: Limit which tools each agent can use for security and focus
|
|
21
57
|
- **Progress Visibility**: Monitor agent execution with real-time progress updates
|
|
@@ -23,7 +59,7 @@ Subagents are independent AI assistants that:
|
|
|
23
59
|
## How Subagents Work
|
|
24
60
|
|
|
25
61
|
1. **Configuration**: You create Subagents configurations that define their behavior, tools, and system prompts
|
|
26
|
-
2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents
|
|
62
|
+
2. **Delegation**: The main AI can automatically delegate tasks to appropriate Subagents β or implicitly fork when no specific subagent type is needed
|
|
27
63
|
3. **Execution**: Subagents work independently, using their configured tools to complete tasks
|
|
28
64
|
4. **Results**: They return results and execution summaries back to the main conversation
|
|
29
65
|
|
|
@@ -99,10 +135,12 @@ Subagents are configured using Markdown files with YAML frontmatter. This format
|
|
|
99
135
|
name: agent-name
|
|
100
136
|
description: Brief description of when and how to use this agent
|
|
101
137
|
model: inherit # Optional: inherit or model-id
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
138
|
+
approvalMode: auto-edit # Optional: default, plan, auto-edit, yolo
|
|
139
|
+
tools: # Optional: allowlist of tools
|
|
140
|
+
- tool1
|
|
141
|
+
- tool2
|
|
142
|
+
disallowedTools: # Optional: blocklist of tools
|
|
143
|
+
- tool3
|
|
106
144
|
---
|
|
107
145
|
|
|
108
146
|
System prompt content goes here.
|
|
@@ -118,6 +156,87 @@ Use the optional `model` frontmatter field to control which model a subagent use
|
|
|
118
156
|
- `glm-5`: Use that model ID with the main conversation's auth type
|
|
119
157
|
- `openai:gpt-4o`: Use a different provider (resolves credentials from env vars)
|
|
120
158
|
|
|
159
|
+
#### Permission Mode
|
|
160
|
+
|
|
161
|
+
Use the optional `approvalMode` frontmatter field to control how a subagent's tool calls are approved. Valid values:
|
|
162
|
+
|
|
163
|
+
- `default`: Tools require interactive approval (same as the main session default)
|
|
164
|
+
- `plan`: Analyze-only mode β the agent plans but does not execute changes
|
|
165
|
+
- `auto-edit`: Tools are auto-approved without prompting (recommended for most agents)
|
|
166
|
+
- `yolo`: All tools auto-approved, including potentially destructive ones
|
|
167
|
+
|
|
168
|
+
If you omit this field, the subagent's permission mode is determined automatically:
|
|
169
|
+
|
|
170
|
+
- If the parent session is in **yolo** or **auto-edit** mode, the subagent inherits that mode. A permissive parent stays permissive.
|
|
171
|
+
- If the parent session is in **plan** mode, the subagent stays in plan mode. An analyze-only session cannot mutate files through a delegated agent.
|
|
172
|
+
- If the parent session is in **default** mode (in a trusted folder), the subagent gets **auto-edit** so it can work autonomously.
|
|
173
|
+
|
|
174
|
+
When you do set `approvalMode`, the parent's permissive modes still take priority. For example, if the parent is in yolo mode, a subagent with `approvalMode: plan` will still run in yolo mode.
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
---
|
|
178
|
+
name: cautious-reviewer
|
|
179
|
+
description: Reviews code without making changes
|
|
180
|
+
approvalMode: plan
|
|
181
|
+
tools:
|
|
182
|
+
- read_file
|
|
183
|
+
- grep_search
|
|
184
|
+
- glob
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
You are a code reviewer. Analyze the code and report findings.
|
|
188
|
+
Do not modify any files.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
#### Tool Configuration
|
|
192
|
+
|
|
193
|
+
Use `tools` and `disallowedTools` to control which tools a subagent can access.
|
|
194
|
+
|
|
195
|
+
**`tools` (allowlist):** When specified, the subagent can only use the listed tools. When omitted, the subagent inherits all available tools from the parent session.
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
---
|
|
199
|
+
name: reader
|
|
200
|
+
description: Read-only agent for code exploration
|
|
201
|
+
tools:
|
|
202
|
+
- read_file
|
|
203
|
+
- grep_search
|
|
204
|
+
- glob
|
|
205
|
+
- list_directory
|
|
206
|
+
---
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
**`disallowedTools` (blocklist):** When specified, the listed tools are removed from the subagent's tool pool. This is useful when you want "everything except X" without listing every permitted tool.
|
|
210
|
+
|
|
211
|
+
```
|
|
212
|
+
---
|
|
213
|
+
name: safe-worker
|
|
214
|
+
description: Agent that cannot modify files
|
|
215
|
+
disallowedTools:
|
|
216
|
+
- write_file
|
|
217
|
+
- edit
|
|
218
|
+
- run_shell_command
|
|
219
|
+
---
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
If both `tools` and `disallowedTools` are set, the allowlist is applied first, then the blocklist removes from that set.
|
|
223
|
+
|
|
224
|
+
**MCP tools** follow the same rules. If a subagent has no `tools` list, it inherits all MCP tools from the parent session. If a subagent has an explicit `tools` list, it only gets MCP tools that are explicitly named in that list.
|
|
225
|
+
|
|
226
|
+
The `disallowedTools` field supports MCP server-level patterns:
|
|
227
|
+
|
|
228
|
+
- `mcp__server__tool_name` β blocks a specific MCP tool
|
|
229
|
+
- `mcp__server` β blocks all tools from that MCP server
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
---
|
|
233
|
+
name: no-slack
|
|
234
|
+
description: Agent without Slack access
|
|
235
|
+
disallowedTools:
|
|
236
|
+
- mcp__slack
|
|
237
|
+
---
|
|
238
|
+
```
|
|
239
|
+
|
|
121
240
|
#### Example Usage
|
|
122
241
|
|
|
123
242
|
```
|
|
@@ -500,7 +619,8 @@ Always follow these standards:
|
|
|
500
619
|
|
|
501
620
|
## Security Considerations
|
|
502
621
|
|
|
503
|
-
- **Tool Restrictions**:
|
|
622
|
+
- **Tool Restrictions**: Use `tools` to limit which tools a subagent can access, or `disallowedTools` to block specific tools while inheriting everything else
|
|
623
|
+
- **Permission Mode**: Subagents inherit their parent's permission mode by default. Plan-mode sessions cannot escalate to auto-edit through delegated agents. Privileged modes (auto-edit, yolo) are blocked in untrusted folders.
|
|
504
624
|
- **Sandboxing**: All tool execution follows the same security model as direct tool use
|
|
505
625
|
- **Audit Trail**: All Subagents actions are logged and visible in real-time
|
|
506
626
|
- **Access Control**: Project and user-level separation provides appropriate boundaries
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Contextual Tips
|
|
2
|
+
|
|
3
|
+
Qwen Code includes a contextual tips system that helps you discover features and stay aware of session state.
|
|
4
|
+
|
|
5
|
+
## Startup Tips
|
|
6
|
+
|
|
7
|
+
Each time you launch Qwen Code, a tip is shown in the header area. Tips are selected by priority first, then rotated across sessions using LRU (least-recently-used) scheduling among tips of the same priority, so you see a different tip each time.
|
|
8
|
+
|
|
9
|
+
New users see onboarding-focused tips during their first sessions:
|
|
10
|
+
|
|
11
|
+
| Sessions | Example tips |
|
|
12
|
+
| -------- | ---------------------------------------------------- |
|
|
13
|
+
| < 5 | Slash commands (`/`), Tab autocomplete |
|
|
14
|
+
| < 10 | `QWEN.md` project context, `--continue` / `--resume` |
|
|
15
|
+
| < 15 | Shell commands with `!` prefix |
|
|
16
|
+
|
|
17
|
+
After that, tips rotate through general features like `/compress`, `/approval-mode`, `/insight`, `/btw`, and more.
|
|
18
|
+
|
|
19
|
+
## Post-Response Tips
|
|
20
|
+
|
|
21
|
+
During a conversation, Qwen Code monitors your context window usage and shows tips when action may be needed:
|
|
22
|
+
|
|
23
|
+
| Context usage | Condition | Tip |
|
|
24
|
+
| ------------- | ------------------------------ | ------------------------------------------------- |
|
|
25
|
+
| 50-80% | After a few prompts in session | Suggests `/compress` to free up context |
|
|
26
|
+
| 80-95% | β | Warns context is getting full |
|
|
27
|
+
| >= 95% | β | Urgent: run `/compress` now or `/new` to continue |
|
|
28
|
+
|
|
29
|
+
Post-response tips have per-tip cooldowns to avoid being repetitive.
|
|
30
|
+
|
|
31
|
+
## Tip History
|
|
32
|
+
|
|
33
|
+
Tip display history is persisted at `~/.qwen/tip_history.json`. This file tracks:
|
|
34
|
+
|
|
35
|
+
- Session count (used for new-user tip selection)
|
|
36
|
+
- Which tips have been shown and when (used for LRU rotation and cooldown)
|
|
37
|
+
|
|
38
|
+
You can safely delete this file to reset tip history.
|
|
39
|
+
|
|
40
|
+
## Disabling Tips
|
|
41
|
+
|
|
42
|
+
To hide all tips (both startup and post-response), set `ui.hideTips` to `true` in `~/.qwen/settings.json`:
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"ui": {
|
|
47
|
+
"hideTips": true
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
You can also toggle this in the settings dialog via the `/settings` command.
|
|
53
|
+
|
|
54
|
+
Tips are also automatically hidden when screen reader mode is enabled.
|
|
@@ -6,7 +6,7 @@ Qwen Code is an open-source AI coding assistant tool maintained by the Qwen Code
|
|
|
6
6
|
|
|
7
7
|
Qwen Code supports three authentication methods to access AI models. Your authentication method determines which terms of service and privacy policies apply to your usage:
|
|
8
8
|
|
|
9
|
-
1. **Qwen OAuth** β Log in with your qwen.ai account (free daily quota)
|
|
9
|
+
1. **Qwen OAuth** β Log in with your qwen.ai account (free daily quota, ending 2026-04-15)
|
|
10
10
|
2. **Alibaba Cloud Coding Plan** β Use an API key from Alibaba Cloud
|
|
11
11
|
3. **API Key** β Bring your own API key
|
|
12
12
|
|