diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md index b55da91c4f..e334d19c7a 100644 --- a/docs/users/configuration/settings.md +++ b/docs/users/configuration/settings.md @@ -155,6 +155,8 @@ Settings are organized into categories. Most settings should be placed within th | Setting | Type | Description | Default | | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `model.name` | string | The Qwen model to use for conversations. | `undefined` | +| `model.baseUrl` | string | Persisted automatically by the model picker to disambiguate when multiple `modelProviders` entries share the same model id. Not intended to be set by hand — use the `/model` picker or a `modelProviders` entry instead; a stale hand-edited value can silently route requests to a different same-id provider. | `undefined` | +| `model.sessionTokenLimit` | number | Maximum recorded prompt token count allowed before sending the next message. `-1` means unlimited; `0` is also treated as unlimited (unlike `model.maxToolCalls`, where `0` disallows all calls). When the recorded prompt count exceeds the limit, the next send is dropped (the session is not aborted). | `-1` | | `model.maxSessionTurns` | number | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` | | `model.maxWallTimeSeconds` | number | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded. | `-1` | | `model.maxToolCalls` | number | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded. | `-1` | @@ -242,6 +244,18 @@ The `extra_body` field allows you to add custom parameters to the request body s | ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `fastModel` | string | Model used for generating [prompt suggestions](../features/followup-suggestions) and speculative execution. Leave empty to use the main model. A smaller/faster model (e.g., `qwen3-coder-flash`) reduces latency and cost. Can also be set via `/model --fast`. | `""` | +#### visionModel + +| Setting | Type | Description | Default | +| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `visionModel` | string | Image-capable model used as the vision bridge: when a text-only main model receives an image, it is transcribed by this model first. Leave empty to auto-pick a same-provider vision model. Can also be set via `/model --vision`. | `""` | + +#### voiceModel + +| Setting | Type | Description | Default | +| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `voiceModel` | string | Model used for voice transcription. Leave empty to keep voice dictation disabled until a voice model is selected. Can also be set via `/model --voice`. | `""` | + #### context | Setting | Type | Description | Default | @@ -457,12 +471,14 @@ LSP server configuration is done through `.lsp.json` files in your project root #### security -| Setting | Type | Description | Default | -| ------------------------------ | ------- | ------------------------------------------------- | ----------- | -| `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `false` | -| `security.auth.selectedType` | string | The currently selected authentication type. | `undefined` | -| `security.auth.enforcedType` | string | The required auth type (useful for enterprises). | `undefined` | -| `security.auth.useExternal` | boolean | Whether to use an external authentication flow. | `undefined` | +| Setting | Type | Description | Default | +| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `security.folderTrust.enabled` | boolean | Setting to track whether Folder trust is enabled. | `false` | +| `security.auth.selectedType` | string | The currently selected authentication type. | `undefined` | +| `security.auth.enforcedType` | string | The required auth type (useful for enterprises). | `undefined` | +| `security.auth.useExternal` | boolean | Whether to use an external authentication flow. | `undefined` | +| `security.auth.apiKey` | string | **Deprecated.** API key for OpenAI-compatible authentication. Migrate to `modelProviders` with `envKey` instead — see [Model Providers](./model-providers). | `undefined` | +| `security.auth.baseUrl` | string | **Deprecated.** Base URL for the OpenAI-compatible API. Migrate to `modelProviders` instead — see [Model Providers](./model-providers). | `undefined` | #### advanced diff --git a/docs/users/features/commands.md b/docs/users/features/commands.md index 63c3c8503c..31ae565a52 100644 --- a/docs/users/features/commands.md +++ b/docs/users/features/commands.md @@ -76,40 +76,41 @@ Commands specifically for controlling interface and output language. Commands for managing AI tools and models. -| Command | Description | Usage Examples | -| ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `/mcp` | List configured MCP servers and tools | `/mcp`, `/mcp desc`, `/mcp nodesc`, `/mcp schema` | -| `/import-config` | Import MCP servers from Claude configs | `/import-config all`, `/import-config claude-code`, `/import-config claude-desktop --scope user\|project` | -| `/tools` | Display currently available tool list | `/tools`, `/tools desc` | -| `/skills` | List and run available skills | `/skills`, `/skills ` | -| `/plan` | Switch to plan mode or exit plan mode | `/plan`, `/plan `, `/plan exit` | -| `/approval-mode` | Change the tool-approval mode (current session only) | `/approval-mode`, `/approval-mode auto-edit` | -| → `plan` | Analysis only, no execution (secure review) | `/approval-mode plan` | -| → `default` | Require approval for edits (daily use) | `/approval-mode default` | -| → `auto-edit` | Auto-approve edits (trusted environment) | `/approval-mode auto-edit` | -| → `auto` | Classifier-evaluated approval (autonomous) | `/approval-mode auto` | -| → `yolo` | Auto-approve everything (quick prototyping) | `/approval-mode yolo` | -| `/model` | Switch model used in current session | `/model`, `/model ` (switch immediately) | -| `/model --fast` | Set a lighter model for prompt suggestions | `/model --fast qwen3-coder-flash` | -| `/model --voice` | Set the model used for voice transcription | `/model --voice ` | -| `/extensions` | Manage extensions | `/extensions list`, `/extensions manage` | -| → `list` | List installed extensions | `/extensions list` | -| → `manage` | Manage installed extensions (interactive) | `/extensions manage` | -| → `explore` | Open extensions page in browser | `/extensions explore ` | -| → `install` | Install an extension from a git repo or path | `/extensions install ` | -| `/memory` | Open the Memory Manager dialog | `/memory` | -| `/remember` | Save a durable memory | `/remember Prefer terse responses` | -| `/forget` | Remove matching entries from auto-memory | `/forget ` | -| `/dream` | Manually run auto-memory consolidation | `/dream` | -| `/hooks` | Manage Qwen Code hooks | `/hooks`, `/hooks list` | -| `/permissions` | Manage permission rules | `/permissions` | -| `/agents` | Manage subagents | `/agents manage`, `/agents create` | -| `/arena` | Manage Arena sessions | `/arena start`, `/arena stop`, `/arena status`, `/arena select` (alias `choose`) | -| `/goal` | Set a goal — keep working until condition met | `/goal `, `/goal clear` | -| `/tasks` | List background tasks | `/tasks` | -| `/workflows` | Inspect workflow runs | `/workflows`, `/workflows ` | -| `/lsp` | Show LSP server status | `/lsp` | -| `/trust` | Manage folder trust settings | `/trust` | +| Command | Description | Usage Examples | +| ----------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `/mcp` | List configured MCP servers and tools | `/mcp`, `/mcp desc`, `/mcp nodesc`, `/mcp schema` | +| `/import-config` | Import MCP servers from Claude configs | `/import-config all`, `/import-config claude-code`, `/import-config claude-desktop --scope user\|project` | +| `/tools` | Display currently available tool list | `/tools`, `/tools desc` | +| `/skills` | List and run available skills | `/skills`, `/skills ` | +| `/plan` | Switch to plan mode or exit plan mode | `/plan`, `/plan `, `/plan exit` | +| `/approval-mode` | Change the tool-approval mode (current session only) | `/approval-mode`, `/approval-mode auto-edit` | +| → `plan` | Analysis only, no execution (secure review) | `/approval-mode plan` | +| → `default` | Require approval for edits (daily use) | `/approval-mode default` | +| → `auto-edit` | Auto-approve edits (trusted environment) | `/approval-mode auto-edit` | +| → `auto` | Classifier-evaluated approval (autonomous) | `/approval-mode auto` | +| → `yolo` | Auto-approve everything (quick prototyping) | `/approval-mode yolo` | +| `/model` | Switch model used in current session | `/model`, `/model ` (switch immediately) | +| `/model --fast` | Set a lighter model for prompt suggestions | `/model --fast qwen3-coder-flash` | +| `/model --voice` | Set the model used for voice transcription | `/model --voice ` | +| `/model --vision` | Set the vision-bridge model used to transcribe images for a text-only main model | `/model --vision ` | +| `/extensions` | Manage extensions | `/extensions list`, `/extensions manage` | +| → `list` | List installed extensions | `/extensions list` | +| → `manage` | Manage installed extensions (interactive) | `/extensions manage` | +| → `explore` | Open extensions page in browser | `/extensions explore ` | +| → `install` | Install an extension from a git repo or path | `/extensions install ` | +| `/memory` | Open the Memory Manager dialog | `/memory` | +| `/remember` | Save a durable memory | `/remember Prefer terse responses` | +| `/forget` | Remove matching entries from auto-memory | `/forget ` | +| `/dream` | Manually run auto-memory consolidation | `/dream` | +| `/hooks` | Manage Qwen Code hooks | `/hooks`, `/hooks list` | +| `/permissions` | Manage permission rules | `/permissions` | +| `/agents` | Manage subagents | `/agents manage`, `/agents create` | +| `/arena` | Manage Arena sessions | `/arena start`, `/arena stop`, `/arena status`, `/arena select` (alias `choose`) | +| `/goal` | Set a goal — keep working until condition met | `/goal `, `/goal clear` | +| `/tasks` | List background tasks | `/tasks` | +| `/workflows` | Inspect workflow runs | `/workflows`, `/workflows ` | +| `/lsp` | Show LSP server status | `/lsp` | +| `/trust` | Manage folder trust settings | `/trust` | > [!warning] > diff --git a/docs/users/features/headless.md b/docs/users/features/headless.md index efa531a560..f93fc6f951 100644 --- a/docs/users/features/headless.md +++ b/docs/users/features/headless.md @@ -223,24 +223,25 @@ qwen -p "Write code" --output-format stream-json --include-partial-messages | jq Key command-line options for headless usage: -| Option | Description | Example | -| ---------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | -| `--prompt`, `-p` | Run in headless mode | `qwen -p "query"` | -| `--output-format`, `-o` | Specify output format (text, json, stream-json) | `qwen -p "query" --output-format json` | -| `--input-format` | Specify input format (text, stream-json) | `qwen --input-format text --output-format stream-json` | -| `--include-partial-messages` | Include partial messages in stream-json output | `qwen -p "query" --output-format stream-json --include-partial-messages` | -| `--system-prompt` | Override the main session system prompt for this run | `qwen -p "query" --system-prompt "You are a terse reviewer."` | -| `--append-system-prompt` | Append extra instructions to the main session system prompt for this run | `qwen -p "query" --append-system-prompt "Focus on concrete findings."` | -| `--debug`, `-d` | Enable debug mode | `qwen -p "query" --debug` | -| `--all-files`, `-a` | Include all files in context | `qwen -p "query" --all-files` | -| `--include-directories` | Include additional directories | `qwen -p "query" --include-directories src,docs` | -| `--yolo`, `-y` | Auto-approve all actions | `qwen -p "query" --yolo` | -| `--approval-mode` | Set approval mode | `qwen -p "query" --approval-mode auto_edit` | -| `--continue` | Resume the most recent session for this project | `qwen --continue -p "Pick up where we left off"` | -| `--resume [sessionId]` | Resume a specific session (or choose interactively) | `qwen --resume 123e... -p "Finish the refactor"` | -| `--max-session-turns` | Cap the number of user/model/tool turns in the run | `qwen -p "..." --max-session-turns 30` | -| `--max-wall-time` | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` | `qwen -p "..." --max-wall-time 10m` | -| `--max-tool-calls` | Cumulative tool-call budget for the run | `qwen -p "..." --max-tool-calls 50` | +| Option | Description | Example | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| `--prompt`, `-p` | Run in headless mode | `qwen -p "query"` | +| `--output-format`, `-o` | Specify output format (text, json, stream-json) | `qwen -p "query" --output-format json` | +| `--input-format` | Specify input format (text, stream-json) | `qwen --input-format text --output-format stream-json` | +| `--include-partial-messages` | Include partial messages in stream-json output | `qwen -p "query" --output-format stream-json --include-partial-messages` | +| `--system-prompt` | Override the main session system prompt for this run | `qwen -p "query" --system-prompt "You are a terse reviewer."` | +| `--append-system-prompt` | Append extra instructions to the main session system prompt for this run | `qwen -p "query" --append-system-prompt "Focus on concrete findings."` | +| `--debug`, `-d` | Enable debug mode | `qwen -p "query" --debug` | +| `--safe-mode` | Disable all customizations — context files, hooks, extensions, skills, MCP servers, custom subagents (only built-in subagents load), permission rules, settings-sourced approval mode overrides, memory features, and sandbox settings — to isolate problems; the CLI flags `--yolo` and `--approval-mode` still take effect. See [Troubleshooting](../support/troubleshooting). Also settable via `QWEN_CODE_SAFE_MODE=true`. | `qwen -p "query" --safe-mode` | +| `--all-files`, `-a` | Include all files in context | `qwen -p "query" --all-files` | +| `--include-directories` | Include additional directories | `qwen -p "query" --include-directories src,docs` | +| `--yolo`, `-y` | Auto-approve all actions | `qwen -p "query" --yolo` | +| `--approval-mode` | Set approval mode | `qwen -p "query" --approval-mode auto_edit` | +| `--continue` | Resume the most recent session for this project | `qwen --continue -p "Pick up where we left off"` | +| `--resume [sessionId]` | Resume a specific session (or choose interactively) | `qwen --resume 123e... -p "Finish the refactor"` | +| `--max-session-turns` | Cap the number of user/model/tool turns in the run | `qwen -p "..." --max-session-turns 30` | +| `--max-wall-time` | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` | `qwen -p "..." --max-wall-time 10m` | +| `--max-tool-calls` | Cumulative tool-call budget for the run | `qwen -p "..." --max-tool-calls 50` | For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings). diff --git a/docs/users/support/troubleshooting.md b/docs/users/support/troubleshooting.md index accdcb4834..46db6b10bd 100644 --- a/docs/users/support/troubleshooting.md +++ b/docs/users/support/troubleshooting.md @@ -55,6 +55,11 @@ This guide provides solutions to common issues and debugging tips, including top - **Q: Why don't I see cached token counts in my stats output?** - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (e.g., Alibaba Cloud Model Studio API key or Google Cloud Vertex AI). You can still view your total token usage using the `/stats` command. +- **Q: A customization (extension, hook, skill, MCP server, or subagent) seems to be breaking Qwen Code. How do I isolate it?** + - A: Start Qwen Code with the `--safe-mode` flag to disable all customizations — context files, hooks, extensions, skills, MCP servers, custom subagents (only built-in subagents load), permission rules, settings-sourced approval mode overrides, memory features, and sandbox settings — for the session. Note: the CLI flags `--yolo` and `--approval-mode` still take effect in safe mode. If the problem disappears in safe mode, re-enable your customizations one at a time to find the culprit. + - Example: `qwen --safe-mode` + - Alternative: set the environment variable `QWEN_CODE_SAFE_MODE=true` if the CLI cannot accept flags. + ## Common error messages and solutions - **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**