vrr/qwen-code
2
0
Fork 0
mirror of https://github.com/QwenLM/qwen-code.git synced 2026-07-09 17:19:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

docs: document model/auth settings, /model --vision, and --safe-mode (#6028)

Browse source 
* docs: document model/auth settings, /model --vision, and --safe-mode

Refresh user docs to match the current codebase:

- commands.md: add the /model --vision override (vision-bridge model)
- settings.md: add model.baseUrl, model.sessionTokenLimit, visionModel,
  and voiceModel; document the deprecated security.auth.apiKey and
  security.auth.baseUrl keys with a pointer to modelProviders
- troubleshooting.md: document the --safe-mode flag for isolating
  customization issues

* docs: address review feedback on sessionTokenLimit, safe-mode, deprecation notes

- model.sessionTokenLimit: correct default to -1 (runtime fallback in
  core/config.ts) and clarify breach behavior (current send dropped, not
  session abort) per client.ts SessionTokenLimitExceeded handling.
- --safe-mode: expand the disabled-customizations list to also cover
  permission rules, approval mode overrides, memory features, and sandbox
  settings, matching cli/config.ts.
- security.auth.apiKey/baseUrl: align deprecation wording with the existing
  tools.* entries (**Deprecated.**) and drop the unsubstantiated
  '(slated for removal)' qualifier.

* docs: note QWEN_CODE_SAFE_MODE env var as a safe-mode alternative

Document the QWEN_CODE_SAFE_MODE=true environment variable as an
alternative activation path for safe mode, for cases where the CLI
cannot accept flags (verified against isSafeModeEnv in
packages/core/src/utils/safe-mode.ts).

* docs: clarify model.baseUrl, sessionTokenLimit=0, and safe-mode subagents

- model.baseUrl: describe it as a picker-managed disambiguator, not a
  hand-editable override (stale values can misroute to a same-id provider).
- model.sessionTokenLimit: note that 0 is treated as unlimited (same as -1),
  unlike model.maxToolCalls where 0 disallows all calls.
- --safe-mode: include custom subagents in the list of disabled
  customizations (only built-in subagents load in safe mode).

* docs: clarify sessionTokenLimit semantics and add --safe-mode to headless flags

- settings.md: reword model.sessionTokenLimit to reflect that the gate
  compares the last recorded prompt token count before the next send
  (not a per-send preflight cap), and that the next send is dropped.
- headless.md: add a --safe-mode row to the CLI flags table so the
  diagnostic flag is discoverable there, cross-referencing Troubleshooting.

* docs: align safe-mode sandbox wording to 'sandbox settings'

Safe mode passes an empty Settings object to loadSandboxConfig
(packages/cli/src/config/config.ts:1793), so it strips settings-sourced
sandbox config while the --sandbox flag and QWEN_SANDBOX env still apply.
Match headless.md to troubleshooting.md's accurate 'sandbox settings'.

* docs: correct safe-mode approval-mode wording and align both lists

Safe mode only strips settings-sourced approval mode; the --yolo and
--approval-mode CLI flags are evaluated before the safeMode guard
(packages/cli/src/config/config.ts:1521-1528) and still take effect.
Reword to 'settings-sourced approval mode overrides' and note the CLI
flags in troubleshooting.md and headless.md, and make the enumerated
safe-mode disable list identical (same items and order) across both.

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Dragon 2026-07-01 23:34:20 +08:00 • committed by GitHub
parent 1467ed3100
commit 427b5ade33
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 81 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/users/configuration/settings.md
View file

@ -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

69
docs/users/features/commands.md
View file

@ -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 <name>` |
| `/plan` | Switch to plan mode or exit plan mode | `/plan`, `/plan <task>`, `/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 <model-id>` (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-id>` |
| `/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 <Gemini\|ClaudeCode>` |
| → `install` | Install an extension from a git repo or path | `/extensions install <repo-or-path>` |
| `/memory` | Open the Memory Manager dialog | `/memory` |
| `/remember` | Save a durable memory | `/remember Prefer terse responses` |
| `/forget` | Remove matching entries from auto-memory | `/forget <query>` |
| `/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 <condition>`, `/goal clear` |
| `/tasks` | List background tasks | `/tasks` |
| `/workflows` | Inspect workflow runs | `/workflows`, `/workflows <runId>` |
| `/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 <name>` |
| `/plan` | Switch to plan mode or exit plan mode | `/plan`, `/plan <task>`, `/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 <model-id>` (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-id>` |
| `/model --vision` | Set the vision-bridge model used to transcribe images for a text-only main model | `/model --vision <model-id>` |
| `/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 <Gemini\|ClaudeCode>` |
| → `install` | Install an extension from a git repo or path | `/extensions install <repo-or-path>` |
| `/memory` | Open the Memory Manager dialog | `/memory` |
| `/remember` | Save a durable memory | `/remember Prefer terse responses` |
| `/forget` | Remove matching entries from auto-memory | `/forget <query>` |
| `/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 <condition>`, `/goal clear` |
| `/tasks` | List background tasks | `/tasks` |
| `/workflows` | Inspect workflow runs | `/workflows`, `/workflows <runId>` |
| `/lsp` | Show LSP server status | `/lsp` |
| `/trust` | Manage folder trust settings | `/trust` |
> [!warning]
>

37
docs/users/features/headless.md
View file

@ -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).

5
docs/users/support/troubleshooting.md
View file

@ -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.**