qwen-code/docs/users/quickstart.md

278 lines
8.5 KiB
Markdown
Raw Permalink Normal View History

# Quickstart
> 👏 Welcome to Qwen Code!
This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.
## Before you begin
Make sure you have:
- A **terminal** or command prompt open
- A code project to work with
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
- An API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)), or an Alibaba Cloud Coding Plan ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) subscription
## Step 1: Install Qwen Code
To install Qwen Code, use one of the following methods:
### Quick Install (Recommended)
**Linux / macOS**
```sh
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash
```
chore(deps): upgrade ink 6.2.3 → 7.0.2 + bump Node engine to 22 (#3860) * chore(deps): upgrade ink 6.2.3 -> 7.0.2 + bump Node engine to 22 ink 7 requires Node >=22 and react-reconciler 0.33 with React >=19.2, so this PR also bumps: - Node engines (root + cli + core) 20 -> 22 - React/react-dom 19.1 -> 19.2.4 (pinned exact via overrides to keep the transitive React graph deduped to a single instance) - @types/node pinned to 20.19.1 via overrides to avoid an unrelated Dirent NonSharedBuffer regression in sessionService tests - @vitest/eslint-plugin pinned to 1.3.4 to avoid an unrelated lint regression introduced by the 1.6.x rule additions - react-devtools-core 4.28 -> 6.1 (ink 7 peerOptional requires >=6.1.2) - ink hoisted to root devDeps so workspace-private peer-dep contention doesn't push ink-link/spinner/gradient into nested workspace installs (which would skip transitive resolution for terminal-link) Workflow + image + installer alignment: - .nvmrc 20 -> 22 - Dockerfile node:20-slim -> node:22-slim - CI test matrix drops 20.x (keeps 22.x + 24.x) - terminal-bench workflow Node 20 -> 22 - Linux/Windows install scripts upgrade their Node version targets Documentation alignment: - README.md badge + prerequisites - AGENTS.md, CONTRIBUTING.md, docs/users/quickstart.md, docs/users/configuration/settings.md, docs/developers/contributing.md, docs/developers/sdk-typescript.md, docs/users/extension/extension-releasing.md, packages/sdk-typescript/README.md, packages/zed-extension/README.md, scripts/installation/INSTALLATION_GUIDE.md Test gating: - Two AuthDialog/AskUserQuestionDialog tests that drive <SelectInput> through ink-testing-library now race ink 7's frame-throttled input delivery and land on the wrong option. The maintainers had already marked one of them unreliable (skip on Win32 + CI+Node20). Extend that gate to cover all environments until upstream ink-testing-library ships an ink-7-compatible release that flushes input deterministically. The other test now uses it.skip with the same comment. No business code changes. Verified locally: - npm run typecheck across all workspaces: clean - npm run lint (root): clean - npm run test --workspaces: cli 312/312 files, 4918 passed, 9 skipped core 266/266 files, 6836 passed, 3 skipped webui 6/6, 201 passed sdk 40/40, 283 passed, 1 skipped - npm ls ink: single ink@7.0.2 instance across all peer deps - single react@19.2.4 instance Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore: align Node 22 floor across all shipping artifacts Reviewer (tanzhenxin) flagged five surfaces where the >=22 engine bump leaked: SDK package metadata, web-templates engines, /doctor runtime check, main bundler target, and SDK bundler target. Each was a separate escape hatch letting Node 18/20 consumers install or run the artifact on an unsupported runtime. - packages/sdk-typescript/package.json: engines.node >=18.0.0 -> >=22.0.0 - packages/web-templates/package.json: engines.node >=20 -> >=22 - packages/cli/src/utils/doctorChecks.ts: MIN_NODE_MAJOR 20 -> 22 - esbuild.config.js: target node20 -> node22 (main CLI bundle) - packages/sdk-typescript/scripts/build.js: target node18 -> node22 (esm + cjs) - packages/cli/src/utils/doctorChecks.test.ts: rename test label to v22+ Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * ci(e2e): bump E2E workflow Node matrix to 22.x Reviewer (tanzhenxin) flagged that e2e.yml still pinned node-version 20.x while root engines is now >=22, so every E2E run on push would either fail at npm ci with engine error or silently exercise the bundle on a runtime that's no longer in ci.yml's test matrix. The macOS job in the same workflow already reads .nvmrc (which is 22) so this only updates the Linux matrix. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): drop root wrap-ansi override so ink 7 gets its declared dep Reviewer (tanzhenxin) flagged that the root overrides.wrap-ansi: 9.0.2 predates this upgrade and forces every consumer (including ink) to v9, while ink 7 declares wrap-ansi: ^10.0.0. The lockfile had no nested install under node_modules/ink/, so ink 7 was running with a transitive dep one major below its declared minimum. Dropping the global override lets ink resolve its own wrap-ansi 10 nested install (now visible in the lockfile under node_modules/ink/node_modules/wrap-ansi), while the cli package's own direct `wrap-ansi: 9.0.2` dependency keeps the cli code path (TableRenderer.tsx) on the version it has been tested against. The nested cliui override is preserved for yargs which still needs v7. Verified via `npm ls wrap-ansi`: - ink@7.0.2 -> wrap-ansi@10.0.0 (newly nested) - @qwen-code/qwen-code -> wrap-ansi@9.0.2 (unchanged) - yargs/cliui -> wrap-ansi@7.0.0 (unchanged) Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): un-skip placeholder ID reuse after deletion Reviewer (tanzhenxin) flagged that the new it.skip on the 'should reuse placeholder ID after deletion' test was undisclosed in the PR description and removed coverage of real product behavior (freePlaceholderId / bracketed-paste backspace path) without a TODO(#NNNN) link. Their argument was sound: the skip rationale pointed at ink 7's input throttle, but this same file just bumped the wait helper from 50ms to 150ms specifically to give ink 7 frame time. Re-running the test under the bumped wait shows it passes reliably (5/5 runs in the full-file context, 9/10 alone), so the skip was masking the throttle-flake that the wait bump already addresses, not a real product bug. Drop the it.skip and the now-stale comment so coverage of the freePlaceholderId reuse logic is restored. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): bump first prompt-suggestion test wait to 350ms The "accepts and submits the prompt suggestion on Enter when the buffer is empty" test is the first in its describe block, so it pays the renderer cold-start cost. On macOS-22.x CI runners that pushes the Enter → onSubmit microtask past the default 150ms post-Enter wait. Match the 350ms initial render wait used immediately above to absorb the cold start. * Revert "test(InputPrompt): bump first prompt-suggestion test wait to 350ms" This reverts commit 6add83b62ea80c551c81f54af1fda3e6e7478f55. * test(InputPrompt): wait for followup suggestion debounce before pressing Enter Root cause of the failing prompt-suggestion tests on macOS and Windows CI is not flaky timing of the test post-Enter wait — it's the 300ms debounce inside createFollowupController.setSuggestion (shared core). The Enter handler reads followup.state.isVisible synchronously, so if the debounce timer has not fired before stdin.write('\\r'), the suggestion path is skipped and onSubmit never runs. No amount of post-Enter wait can recover from that — the keypress was already processed against stale state. The original wait(350) only left ~50ms margin over the 300ms debounce, which ink 7 / React 19.2 mount overhead consumed on slow Windows runners. Bump the initial wait to 700ms (named SUGGESTION_VISIBLE_WAIT_MS) to give the debounce timer + cold-start render a generous buffer. Apply to the two sibling tests too — without the wait their "does not accept" assertions pass trivially when suggestion is never visible, which is a false green that hides regressions in the actual reject path. * fix(deps): align cli wrap-ansi with ink 7 (9.0.2 -> ^10.0.0) Ink 7 ships its own wrap-ansi@10. CLI's direct dep was pinned to 9.0.2, causing two copies of wrap-ansi in node_modules and a potential drift in CJK width / ANSI handling between ink's internal text wrapping and our TableRenderer. Upgrading the CLI's direct dep to ^10.0.0 lets npm dedupe to a single wrap-ansi@10 used by both ink and TableRenderer. API surface is identical; the only documented behaviour change is that tabs are expanded to 8-column tab stops before wrapping, which TableRenderer doesn't feed in. TableRenderer test suite (43 tests) passes against wrap-ansi@10. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore(deps): document @types/node 20.x pin in overrides The override pinning @types/node to 20.19.1 (while engines require Node >=22) is intentional: bumping to @types/node@22.x re-introduces a Dirent<NonSharedBuffer> type regression that breaks @qwen-code/qwen-code-core/sessionService tests. Add a sibling "//@types/node" note inside `overrides` so future maintainers see the rationale and know when to revisit the pin without having to dig through PR #3860 history. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(AskUserQuestionDialog): link skipped Submit-tab test to tracking issue The 'shows unanswered questions as (not answered) in Submit tab' test was switched to `it.skip` in the ink 7 upgrade because `ink-testing-library@4.0.0` doesn't flush input deterministically through ink 7's 30fps throttle. Add a `// TODO(#4036):` marker so the skip is greppable and can be re-enabled once upstream ships an ink-7-compatible release. Refs #4036 Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): move @types/node pin comment out of overrides block npm's `overrides` field requires every key to be a real package name — the `"//@types/node"` comment-key added in 205855875 trips Arborist with "Override without name" and breaks `npm ci` across all CI jobs. Move the explanation to a sibling top-level `"//overrides"` key, which npm ignores at the document root. Same documentation value, no override-parser collateral damage. --------- Co-authored-by: 秦奇 <gary.gq@alibaba-inc.com> Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-05-11 17:29:50 +08:00
**Windows (Run as Administrator)**
```cmd
powershell -Command "Invoke-WebRequest 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat' -OutFile (Join-Path $env:TEMP 'install-qwen.bat'); & (Join-Path $env:TEMP 'install-qwen.bat')"
```
> [!note]
>
chore(deps): upgrade ink 6.2.3 → 7.0.2 + bump Node engine to 22 (#3860) * chore(deps): upgrade ink 6.2.3 -> 7.0.2 + bump Node engine to 22 ink 7 requires Node >=22 and react-reconciler 0.33 with React >=19.2, so this PR also bumps: - Node engines (root + cli + core) 20 -> 22 - React/react-dom 19.1 -> 19.2.4 (pinned exact via overrides to keep the transitive React graph deduped to a single instance) - @types/node pinned to 20.19.1 via overrides to avoid an unrelated Dirent NonSharedBuffer regression in sessionService tests - @vitest/eslint-plugin pinned to 1.3.4 to avoid an unrelated lint regression introduced by the 1.6.x rule additions - react-devtools-core 4.28 -> 6.1 (ink 7 peerOptional requires >=6.1.2) - ink hoisted to root devDeps so workspace-private peer-dep contention doesn't push ink-link/spinner/gradient into nested workspace installs (which would skip transitive resolution for terminal-link) Workflow + image + installer alignment: - .nvmrc 20 -> 22 - Dockerfile node:20-slim -> node:22-slim - CI test matrix drops 20.x (keeps 22.x + 24.x) - terminal-bench workflow Node 20 -> 22 - Linux/Windows install scripts upgrade their Node version targets Documentation alignment: - README.md badge + prerequisites - AGENTS.md, CONTRIBUTING.md, docs/users/quickstart.md, docs/users/configuration/settings.md, docs/developers/contributing.md, docs/developers/sdk-typescript.md, docs/users/extension/extension-releasing.md, packages/sdk-typescript/README.md, packages/zed-extension/README.md, scripts/installation/INSTALLATION_GUIDE.md Test gating: - Two AuthDialog/AskUserQuestionDialog tests that drive <SelectInput> through ink-testing-library now race ink 7's frame-throttled input delivery and land on the wrong option. The maintainers had already marked one of them unreliable (skip on Win32 + CI+Node20). Extend that gate to cover all environments until upstream ink-testing-library ships an ink-7-compatible release that flushes input deterministically. The other test now uses it.skip with the same comment. No business code changes. Verified locally: - npm run typecheck across all workspaces: clean - npm run lint (root): clean - npm run test --workspaces: cli 312/312 files, 4918 passed, 9 skipped core 266/266 files, 6836 passed, 3 skipped webui 6/6, 201 passed sdk 40/40, 283 passed, 1 skipped - npm ls ink: single ink@7.0.2 instance across all peer deps - single react@19.2.4 instance Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore: align Node 22 floor across all shipping artifacts Reviewer (tanzhenxin) flagged five surfaces where the >=22 engine bump leaked: SDK package metadata, web-templates engines, /doctor runtime check, main bundler target, and SDK bundler target. Each was a separate escape hatch letting Node 18/20 consumers install or run the artifact on an unsupported runtime. - packages/sdk-typescript/package.json: engines.node >=18.0.0 -> >=22.0.0 - packages/web-templates/package.json: engines.node >=20 -> >=22 - packages/cli/src/utils/doctorChecks.ts: MIN_NODE_MAJOR 20 -> 22 - esbuild.config.js: target node20 -> node22 (main CLI bundle) - packages/sdk-typescript/scripts/build.js: target node18 -> node22 (esm + cjs) - packages/cli/src/utils/doctorChecks.test.ts: rename test label to v22+ Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * ci(e2e): bump E2E workflow Node matrix to 22.x Reviewer (tanzhenxin) flagged that e2e.yml still pinned node-version 20.x while root engines is now >=22, so every E2E run on push would either fail at npm ci with engine error or silently exercise the bundle on a runtime that's no longer in ci.yml's test matrix. The macOS job in the same workflow already reads .nvmrc (which is 22) so this only updates the Linux matrix. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): drop root wrap-ansi override so ink 7 gets its declared dep Reviewer (tanzhenxin) flagged that the root overrides.wrap-ansi: 9.0.2 predates this upgrade and forces every consumer (including ink) to v9, while ink 7 declares wrap-ansi: ^10.0.0. The lockfile had no nested install under node_modules/ink/, so ink 7 was running with a transitive dep one major below its declared minimum. Dropping the global override lets ink resolve its own wrap-ansi 10 nested install (now visible in the lockfile under node_modules/ink/node_modules/wrap-ansi), while the cli package's own direct `wrap-ansi: 9.0.2` dependency keeps the cli code path (TableRenderer.tsx) on the version it has been tested against. The nested cliui override is preserved for yargs which still needs v7. Verified via `npm ls wrap-ansi`: - ink@7.0.2 -> wrap-ansi@10.0.0 (newly nested) - @qwen-code/qwen-code -> wrap-ansi@9.0.2 (unchanged) - yargs/cliui -> wrap-ansi@7.0.0 (unchanged) Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): un-skip placeholder ID reuse after deletion Reviewer (tanzhenxin) flagged that the new it.skip on the 'should reuse placeholder ID after deletion' test was undisclosed in the PR description and removed coverage of real product behavior (freePlaceholderId / bracketed-paste backspace path) without a TODO(#NNNN) link. Their argument was sound: the skip rationale pointed at ink 7's input throttle, but this same file just bumped the wait helper from 50ms to 150ms specifically to give ink 7 frame time. Re-running the test under the bumped wait shows it passes reliably (5/5 runs in the full-file context, 9/10 alone), so the skip was masking the throttle-flake that the wait bump already addresses, not a real product bug. Drop the it.skip and the now-stale comment so coverage of the freePlaceholderId reuse logic is restored. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): bump first prompt-suggestion test wait to 350ms The "accepts and submits the prompt suggestion on Enter when the buffer is empty" test is the first in its describe block, so it pays the renderer cold-start cost. On macOS-22.x CI runners that pushes the Enter → onSubmit microtask past the default 150ms post-Enter wait. Match the 350ms initial render wait used immediately above to absorb the cold start. * Revert "test(InputPrompt): bump first prompt-suggestion test wait to 350ms" This reverts commit 6add83b62ea80c551c81f54af1fda3e6e7478f55. * test(InputPrompt): wait for followup suggestion debounce before pressing Enter Root cause of the failing prompt-suggestion tests on macOS and Windows CI is not flaky timing of the test post-Enter wait — it's the 300ms debounce inside createFollowupController.setSuggestion (shared core). The Enter handler reads followup.state.isVisible synchronously, so if the debounce timer has not fired before stdin.write('\\r'), the suggestion path is skipped and onSubmit never runs. No amount of post-Enter wait can recover from that — the keypress was already processed against stale state. The original wait(350) only left ~50ms margin over the 300ms debounce, which ink 7 / React 19.2 mount overhead consumed on slow Windows runners. Bump the initial wait to 700ms (named SUGGESTION_VISIBLE_WAIT_MS) to give the debounce timer + cold-start render a generous buffer. Apply to the two sibling tests too — without the wait their "does not accept" assertions pass trivially when suggestion is never visible, which is a false green that hides regressions in the actual reject path. * fix(deps): align cli wrap-ansi with ink 7 (9.0.2 -> ^10.0.0) Ink 7 ships its own wrap-ansi@10. CLI's direct dep was pinned to 9.0.2, causing two copies of wrap-ansi in node_modules and a potential drift in CJK width / ANSI handling between ink's internal text wrapping and our TableRenderer. Upgrading the CLI's direct dep to ^10.0.0 lets npm dedupe to a single wrap-ansi@10 used by both ink and TableRenderer. API surface is identical; the only documented behaviour change is that tabs are expanded to 8-column tab stops before wrapping, which TableRenderer doesn't feed in. TableRenderer test suite (43 tests) passes against wrap-ansi@10. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore(deps): document @types/node 20.x pin in overrides The override pinning @types/node to 20.19.1 (while engines require Node >=22) is intentional: bumping to @types/node@22.x re-introduces a Dirent<NonSharedBuffer> type regression that breaks @qwen-code/qwen-code-core/sessionService tests. Add a sibling "//@types/node" note inside `overrides` so future maintainers see the rationale and know when to revisit the pin without having to dig through PR #3860 history. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(AskUserQuestionDialog): link skipped Submit-tab test to tracking issue The 'shows unanswered questions as (not answered) in Submit tab' test was switched to `it.skip` in the ink 7 upgrade because `ink-testing-library@4.0.0` doesn't flush input deterministically through ink 7's 30fps throttle. Add a `// TODO(#4036):` marker so the skip is greppable and can be re-enabled once upstream ships an ink-7-compatible release. Refs #4036 Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): move @types/node pin comment out of overrides block npm's `overrides` field requires every key to be a real package name — the `"//@types/node"` comment-key added in 205855875 trips Arborist with "Override without name" and breaks `npm ci` across all CI jobs. Move the explanation to a sibling top-level `"//overrides"` key, which npm ignores at the document root. Same documentation value, no override-parser collateral damage. --------- Co-authored-by: 秦奇 <gary.gq@alibaba-inc.com> Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-05-11 17:29:50 +08:00
> It's recommended to restart your terminal after installation to ensure environment variables take effect.
### Manual Installation
**Prerequisites**
chore(deps): upgrade ink 6.2.3 → 7.0.2 + bump Node engine to 22 (#3860) * chore(deps): upgrade ink 6.2.3 -> 7.0.2 + bump Node engine to 22 ink 7 requires Node >=22 and react-reconciler 0.33 with React >=19.2, so this PR also bumps: - Node engines (root + cli + core) 20 -> 22 - React/react-dom 19.1 -> 19.2.4 (pinned exact via overrides to keep the transitive React graph deduped to a single instance) - @types/node pinned to 20.19.1 via overrides to avoid an unrelated Dirent NonSharedBuffer regression in sessionService tests - @vitest/eslint-plugin pinned to 1.3.4 to avoid an unrelated lint regression introduced by the 1.6.x rule additions - react-devtools-core 4.28 -> 6.1 (ink 7 peerOptional requires >=6.1.2) - ink hoisted to root devDeps so workspace-private peer-dep contention doesn't push ink-link/spinner/gradient into nested workspace installs (which would skip transitive resolution for terminal-link) Workflow + image + installer alignment: - .nvmrc 20 -> 22 - Dockerfile node:20-slim -> node:22-slim - CI test matrix drops 20.x (keeps 22.x + 24.x) - terminal-bench workflow Node 20 -> 22 - Linux/Windows install scripts upgrade their Node version targets Documentation alignment: - README.md badge + prerequisites - AGENTS.md, CONTRIBUTING.md, docs/users/quickstart.md, docs/users/configuration/settings.md, docs/developers/contributing.md, docs/developers/sdk-typescript.md, docs/users/extension/extension-releasing.md, packages/sdk-typescript/README.md, packages/zed-extension/README.md, scripts/installation/INSTALLATION_GUIDE.md Test gating: - Two AuthDialog/AskUserQuestionDialog tests that drive <SelectInput> through ink-testing-library now race ink 7's frame-throttled input delivery and land on the wrong option. The maintainers had already marked one of them unreliable (skip on Win32 + CI+Node20). Extend that gate to cover all environments until upstream ink-testing-library ships an ink-7-compatible release that flushes input deterministically. The other test now uses it.skip with the same comment. No business code changes. Verified locally: - npm run typecheck across all workspaces: clean - npm run lint (root): clean - npm run test --workspaces: cli 312/312 files, 4918 passed, 9 skipped core 266/266 files, 6836 passed, 3 skipped webui 6/6, 201 passed sdk 40/40, 283 passed, 1 skipped - npm ls ink: single ink@7.0.2 instance across all peer deps - single react@19.2.4 instance Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore: align Node 22 floor across all shipping artifacts Reviewer (tanzhenxin) flagged five surfaces where the >=22 engine bump leaked: SDK package metadata, web-templates engines, /doctor runtime check, main bundler target, and SDK bundler target. Each was a separate escape hatch letting Node 18/20 consumers install or run the artifact on an unsupported runtime. - packages/sdk-typescript/package.json: engines.node >=18.0.0 -> >=22.0.0 - packages/web-templates/package.json: engines.node >=20 -> >=22 - packages/cli/src/utils/doctorChecks.ts: MIN_NODE_MAJOR 20 -> 22 - esbuild.config.js: target node20 -> node22 (main CLI bundle) - packages/sdk-typescript/scripts/build.js: target node18 -> node22 (esm + cjs) - packages/cli/src/utils/doctorChecks.test.ts: rename test label to v22+ Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * ci(e2e): bump E2E workflow Node matrix to 22.x Reviewer (tanzhenxin) flagged that e2e.yml still pinned node-version 20.x while root engines is now >=22, so every E2E run on push would either fail at npm ci with engine error or silently exercise the bundle on a runtime that's no longer in ci.yml's test matrix. The macOS job in the same workflow already reads .nvmrc (which is 22) so this only updates the Linux matrix. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): drop root wrap-ansi override so ink 7 gets its declared dep Reviewer (tanzhenxin) flagged that the root overrides.wrap-ansi: 9.0.2 predates this upgrade and forces every consumer (including ink) to v9, while ink 7 declares wrap-ansi: ^10.0.0. The lockfile had no nested install under node_modules/ink/, so ink 7 was running with a transitive dep one major below its declared minimum. Dropping the global override lets ink resolve its own wrap-ansi 10 nested install (now visible in the lockfile under node_modules/ink/node_modules/wrap-ansi), while the cli package's own direct `wrap-ansi: 9.0.2` dependency keeps the cli code path (TableRenderer.tsx) on the version it has been tested against. The nested cliui override is preserved for yargs which still needs v7. Verified via `npm ls wrap-ansi`: - ink@7.0.2 -> wrap-ansi@10.0.0 (newly nested) - @qwen-code/qwen-code -> wrap-ansi@9.0.2 (unchanged) - yargs/cliui -> wrap-ansi@7.0.0 (unchanged) Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): un-skip placeholder ID reuse after deletion Reviewer (tanzhenxin) flagged that the new it.skip on the 'should reuse placeholder ID after deletion' test was undisclosed in the PR description and removed coverage of real product behavior (freePlaceholderId / bracketed-paste backspace path) without a TODO(#NNNN) link. Their argument was sound: the skip rationale pointed at ink 7's input throttle, but this same file just bumped the wait helper from 50ms to 150ms specifically to give ink 7 frame time. Re-running the test under the bumped wait shows it passes reliably (5/5 runs in the full-file context, 9/10 alone), so the skip was masking the throttle-flake that the wait bump already addresses, not a real product bug. Drop the it.skip and the now-stale comment so coverage of the freePlaceholderId reuse logic is restored. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(InputPrompt): bump first prompt-suggestion test wait to 350ms The "accepts and submits the prompt suggestion on Enter when the buffer is empty" test is the first in its describe block, so it pays the renderer cold-start cost. On macOS-22.x CI runners that pushes the Enter → onSubmit microtask past the default 150ms post-Enter wait. Match the 350ms initial render wait used immediately above to absorb the cold start. * Revert "test(InputPrompt): bump first prompt-suggestion test wait to 350ms" This reverts commit 6add83b62ea80c551c81f54af1fda3e6e7478f55. * test(InputPrompt): wait for followup suggestion debounce before pressing Enter Root cause of the failing prompt-suggestion tests on macOS and Windows CI is not flaky timing of the test post-Enter wait — it's the 300ms debounce inside createFollowupController.setSuggestion (shared core). The Enter handler reads followup.state.isVisible synchronously, so if the debounce timer has not fired before stdin.write('\\r'), the suggestion path is skipped and onSubmit never runs. No amount of post-Enter wait can recover from that — the keypress was already processed against stale state. The original wait(350) only left ~50ms margin over the 300ms debounce, which ink 7 / React 19.2 mount overhead consumed on slow Windows runners. Bump the initial wait to 700ms (named SUGGESTION_VISIBLE_WAIT_MS) to give the debounce timer + cold-start render a generous buffer. Apply to the two sibling tests too — without the wait their "does not accept" assertions pass trivially when suggestion is never visible, which is a false green that hides regressions in the actual reject path. * fix(deps): align cli wrap-ansi with ink 7 (9.0.2 -> ^10.0.0) Ink 7 ships its own wrap-ansi@10. CLI's direct dep was pinned to 9.0.2, causing two copies of wrap-ansi in node_modules and a potential drift in CJK width / ANSI handling between ink's internal text wrapping and our TableRenderer. Upgrading the CLI's direct dep to ^10.0.0 lets npm dedupe to a single wrap-ansi@10 used by both ink and TableRenderer. API surface is identical; the only documented behaviour change is that tabs are expanded to 8-column tab stops before wrapping, which TableRenderer doesn't feed in. TableRenderer test suite (43 tests) passes against wrap-ansi@10. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * chore(deps): document @types/node 20.x pin in overrides The override pinning @types/node to 20.19.1 (while engines require Node >=22) is intentional: bumping to @types/node@22.x re-introduces a Dirent<NonSharedBuffer> type regression that breaks @qwen-code/qwen-code-core/sessionService tests. Add a sibling "//@types/node" note inside `overrides` so future maintainers see the rationale and know when to revisit the pin without having to dig through PR #3860 history. Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * test(AskUserQuestionDialog): link skipped Submit-tab test to tracking issue The 'shows unanswered questions as (not answered) in Submit tab' test was switched to `it.skip` in the ink 7 upgrade because `ink-testing-library@4.0.0` doesn't flush input deterministically through ink 7's 30fps throttle. Add a `// TODO(#4036):` marker so the skip is greppable and can be re-enabled once upstream ships an ink-7-compatible release. Refs #4036 Generated with AI Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * fix(deps): move @types/node pin comment out of overrides block npm's `overrides` field requires every key to be a real package name — the `"//@types/node"` comment-key added in 205855875 trips Arborist with "Override without name" and breaks `npm ci` across all CI jobs. Move the explanation to a sibling top-level `"//overrides"` key, which npm ignores at the document root. Same documentation value, no override-parser collateral damage. --------- Co-authored-by: 秦奇 <gary.gq@alibaba-inc.com> Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-05-11 17:29:50 +08:00
Make sure you have Node.js 22 or later installed. Download it from [nodejs.org](https://nodejs.org/en/download).
**NPM**
```bash
npm install -g @qwen-code/qwen-code@latest
```
**Homebrew (macOS, Linux)**
```bash
brew install qwen-code
```
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
## Step 2: Set up authentication
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
When you start an interactive session with the `qwen` command, you'll be prompted to configure authentication:
```bash
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
# You'll be prompted to set up authentication on first use
qwen
```
```bash
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
# Or run /auth anytime to change authentication method
/auth
```
docs: update authentication methods to reflect OAuth discontinuation (#3325) * docs: update authentication methods to reflect OAuth discontinuation Remove deprecated Qwen OAuth references and update documentation to direct users to valid authentication methods (API Key, Coding Plan, or Local Inference) following the OAuth free tier discontinuation on 2026-04-15. Closes #3316 * docs: fix quickstart auth description to match actual /auth UI The /auth command shows three options: Alibaba Cloud Coding Plan, API Key, and Qwen OAuth (discontinued). Updated quickstart.md to accurately reflect this UI instead of splitting into Option A/B/C. Also updated settings.md, commands.md, and troubleshooting.md with minor OAuth-related cleanups. * docs: update .qwen workspace description in quickstart Remove reference to 'Qwen account' since OAuth is discontinued. The .qwen directory is created by Qwen Code itself for storing credentials, configuration, and session data. * docs: fix warning block formatting in quickstart - Add missing '>' continuation for the OAuth discontinuation warning block Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: update README Qwen3.6-Plus description - Remove mention of running Qwen3.6-Plus locally via Ollama/vLLM - Keep only the Alibaba Cloud ModelStudio API key option Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: address review feedback - remove Local Inference from auth, add dual-region links - Local Inference removed from auth method lists, kept as separate 'Local Model Setup' section with detailed Ollama/vLLM config examples - All links now provide dual-region URLs (Beijing + intl) - .qwen workspace note restored to original meaning (cost tracking) - Device auth flow error kept scoped to legacy OAuth - API setup guide links updated with confirmed intl URL --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
2026-04-17 15:34:18 +08:00
Choose your preferred authentication method:
- **Alibaba Cloud Coding Plan**: Select `Alibaba Cloud Coding Plan` for a fixed monthly fee with diverse model options. See the [Coding Plan guide](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) ([intl](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)) for setup instructions.
- **API Key**: Select `API Key`, then enter your API key from Alibaba Cloud Model Studio ([Beijing](https://bailian.console.aliyun.com/) / [intl](https://modelstudio.console.alibabacloud.com/)). See the API setup guide ([Beijing](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [intl](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)) for details.
> ⚠️ **Note**: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above.
> [!note]
>
> When you first authenticate Qwen Code with your Qwen account, a workspace called ".qwen" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization.
> [!tip]
>
> To configure authentication, start Qwen Code and run `/auth`. Use `/doctor` to check your current configuration at any time. See the [Authentication](./configuration/auth) page for details.
## Step 3: Start your first session
Open your terminal in any project directory and start Qwen Code:
```bash
# optiona
cd /path/to/your/project
# start qwen
qwen
```
You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands.
## Chat with Qwen Code
### Ask your first question
Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:
```
explain the folder structure
```
You can also ask Qwen Code about its own capabilities:
```
what can Qwen Code do?
```
> [!note]
>
> Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.
### Make your first code change
Now let's make Qwen Code do some actual coding. Try a simple task:
```
add a hello world function to the main file
```
Qwen Code will:
1. Find the appropriate file
2. Show you the proposed changes
3. Ask for your approval
4. Make the edit
> [!note]
>
> Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.
### Use Git with Qwen Code
Qwen Code makes Git operations conversational:
```
what files have I changed?
```
```
commit my changes with a descriptive message
```
You can also prompt for more complex Git operations:
```
create a new branch called feature/quickstart
```
```
show me the last 5 commits
```
```
help me resolve merge conflicts
```
### Fix a bug or add a feature
Qwen Code is proficient at debugging and feature implementation.
Describe what you want in natural language:
```
add input validation to the user registration form
```
Or fix existing issues:
```
there's a bug where users can submit empty forms - fix it
```
Qwen Code will:
- Locate the relevant code
- Understand the context
- Implement a solution
- Run tests if available
### Test out other common workflows
There are a number of ways to work with Qwen Code:
**Refactor code**
```
refactor the authentication module to use async/await instead of callbacks
```
**Write tests**
```
write unit tests for the calculator functions
```
**Update documentation**
```
update the README with installation instructions
```
**Code review**
```
review my changes and suggest improvements
```
> [!tip]
>
> **Remember**: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.
## Essential commands
Here are the most important commands for daily use:
2025-12-15 22:12:34 +08:00
| Command | What it does | Example |
| --------------------- | ------------------------------------------------ | ----------------------------- |
| `qwen` | start Qwen Code | `qwen` |
| `/auth` | Change authentication method (in session) | `/auth` |
| `/doctor` | Check current authentication and environment | `/doctor` |
2025-12-15 22:12:34 +08:00
| `/help` | Display help information for available commands | `/help` or `/?` |
| `/compress` | Replace chat history with summary to save Tokens | `/compress` |
| `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) |
| `/theme` | Change Qwen Code visual theme | `/theme` |
| `/language` | View or change language settings | `/language` |
| → `ui [language]` | Set UI interface language | `/language ui zh-CN` |
| → `output [language]` | Set LLM output language | `/language output Chinese` |
| `/quit` | Exit Qwen Code immediately | `/quit` or `/exit` |
See the [CLI reference](./features/commands) for a complete list of commands.
## Pro tips for beginners
**Be specific with your requests**
- Instead of: "fix the bug"
- Try: "fix the login bug where users see a blank screen after entering wrong credentials"
**Use step-by-step instructions**
- Break complex tasks into steps:
```
1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information
```
2025-12-16 15:32:21 +08:00
**Let Qwen Code explore first**
2025-12-16 15:32:21 +08:00
- Before making changes, let Qwen Code understand your code:
```
analyze the database schema
```
```
build a dashboard showing products that are most frequently returned by our UK customers
```
**Save time with shortcuts**
- Press `?` to see all available keyboard shortcuts
- Use Tab for command completion
- Press ↑ for command history
- Type `/` to see all slash commands
## Getting help
- **In Qwen Code**: Type `/help` or ask "how do I..."
- **Documentation**: You're here! Browse other guides
- **Community**: Join our [GitHub Discussion](https://github.com/QwenLM/qwen-code/discussions) for tips and support