Qwen Code 完整使用手冊 — 從零開始的 AI 程式開發助手
Qwen Code 是由阿里雲通義實驗室開發的 AI 程式設計助手，支援多種作業系統和開發環境。本手冊將帶你從安裝到進階使用，一步步掌握這個強大的工具。
目錄
系統需求
硬體需求
| 元件 | 最低要求 | 建議配置 |
|---|---|---|
| CPU | 任意 x64 處理器 | 4 核心以上 |
| 記憶體 | 4 GB | 8 GB 以上 |
| 硬碟空間 | 500 MB | 1 GB 以上 |
| 網路 | 需要連線 | 穩定網路 |
作業系統支援
- macOS: 10.15 (Catalina) 以上
- Linux: Ubuntu 20.04+ / Debian 10+ / CentOS 7+
- Windows: Windows 10 / 11（需 PowerShell 5.1+）
軟體需求
- Node.js: 22.0 以上（使用 NPM 安裝時）
- Homebrew: macOS 使用者建議安裝
安裝 Qwen Code
根據你的作業系統選擇對應的安裝方式。
方法一：macOS / Linux（推薦）
開啟終端機，執行以下命令：
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash
安裝完成後，重新啟動終端機或執行：
source ~/.zshrc
# 或
source ~/.bashrc
方法二：Windows（PowerShell）
以系統管理員身分開啟 PowerShell，執行：
irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex
安裝完成後，重新啟動 PowerShell。
方法三：Homebrew（macOS）
如果你已安裝 Homebrew，可直接執行：
brew install qwen-code
方法四：NPM（跨平臺）
需先安裝 Node.js 22+，然後執行：
npm install -g @qwen-code/qwen-code@latest
驗證安裝
安裝完成後，執行以下命令驗證：
qwen --version
如果顯示版本號，表示安裝成功。
首次啟動與配置
第一步：啟動 Qwen Code
開啟終端機，進入你的專案目錄，然後執行：
qwen
首次啟動會看到歡迎畫面：
═══════════════════════════════════════════╗
║ Welcome to Qwen Code! ║
║ ║
║ AI-powered coding assistant ║
╚═══════════════════════════════════════════╝
請選擇認證方式：
1. OpenAI
2. Anthropic
3. Qwen (推薦)
4. 自定義 API
第二步：選擇 API 提供商
輸入數字 3 選擇 Qwen（阿裡雲通義千問），這是官方推薦且最穩定的選項。
第三步：獲取 API Key
- 前往 阿里雲百煉控制檯
- 註冊/登入阿裡雲帳號
- 在「API-KEY 管理」頁面建立新的 API Key
- 複製 API Key（格式為
sk-xxxxxxxxxxxxxx）
第四步：輸入 API Key
回到終端機，貼上你的 API Key，按 Enter 確認。
第五步：選擇模型
系統會列出可用模型，建議選擇：
- qwen3.8-max: 功能最強大，支援圖片/影片理解
- qwen3.7-max: 效能均衡，適合日常開發
- qwen3.8-flash: 速度快，適合簡單任務
輸入對應數字選擇。
第六步：配置完成
看到以下訊息表示配置成功：
✅ 認證配置完成！
模型：qwen3.8-max
開始使用吧！輸入 /help 檢視所有命令。
基本使用方式
互動式對話
啟動 Qwen Code 後，你可以直接輸入問題或要求：
> 幫我建立一個 Python Flask 應用程式
> 解釋這段程式碼的功能
> 幫我修復這個 bug
常用斜線命令
| 命令 | 功能 |
|---|---|
/help |
顯示所有可用命令 |
/auth |
重新配置認證資訊 |
/model |
切換 AI 模型 |
/settings |
開啟設定選單 |
/exit |
退出 Qwen Code |
/clear |
清空當前對話 |
/review |
程式碼審查 |
/batch |
批次處理多個檔案 |
/loop |
建立自動迴圈任務 |
檔案操作
Qwen Code 可以直接讀取和修改你專案中的檔案：
讀取檔案：
> 幫我看看 src/main.py 的內容
修改檔案：
> 把 index.html 的標題改為「歡迎來到我的網站」
建立新檔案：
> 幫我建立一個 README.md 檔案，內容包含專案介紹
專案理解
Qwen Code 可以自動分析你的專案結構：
> 這個專案使用什麼框架？
> 幫我解釋一下這個專案的架構
> 有哪些 API 端點？
進階功能
記憶系統
Qwen Code 具有自動記憶功能，會記住你的偏好和專案資訊。
檢視記憶內容：
> 顯示我的設定偏好
手動新增記憶：
> 記住我使用 Python 3.11
> 記住我的部落格使用 Hugo
刪除記憶：
> 忘記我使用 Node.js
技能系統
Qwen Code 內建多種專業技能：
| 技能 | 命令 | 說明 |
|---|---|---|
| 程式碼審查 | /review |
檢查程式碼品質和安全 |
| 批次處理 | /batch |
對多個檔案執行操作 |
| 迴圈任務 | /loop |
建立定時自動任務 |
| Bug 修復 | /bugfix |
自動診斷和修復錯誤 |
| 新專案建立 | /new-app |
從零開始建立應用程式 |
| 擴充套件建立 | /extension-creator |
建立 Qwen Code 擴充套件 |
計劃模式
對於複雜任務，可以切換到計劃模式：
> /plan
在計劃模式下，你可以：
- 詳細描述需求
- 確認實施步驟
- 批准後自動執行
多模型切換
隨時切換不同的 AI 模型：
> /model
選擇不同的模型以應對不同場景：
- qwen3.8-max: 複雜邏輯、程式碼重構
- qwen3.8-flash: 快速查詢、簡單修改
- glm-5.1: 特定任務最佳化
MCP 整合
Qwen Code 支援 MCP（Model Context Protocol），可以整合外部工具：
> /mcp list # 檢視可用工具
> /mcp add # 新增 MCP 伺服器
沙箱模式
對於不確定的操作，可以啟用沙箱模式：
> /sandbox on
在沙箱中，所有檔案修改都會在隔離環境中進行，確認無誤後再應用到實際專案。
桌面應用程式
如果你偏好圖形介面，可以下載 Qwen Code Desktop：
- 前往 GitHub Releases
- 下載對應系統的 Desktop App
- 安裝後開啟，介面與終端版功能相同
Web UI（實驗性）
在瀏覽器中使用 Qwen Code：
qwen serve --open
這會在本地啟動 Web 服務，自動開啟瀏覽器。
工作目錄管理
分類管理專案
建議為不同專案建立獨立的目錄：
mkdir -p ~/Documents/projects/{infra,security,work,daily,explore}
然後在不同目錄下啟動 Qwen Code，每個目錄會有獨立的記憶和上下文：
cd ~/Documents/projects/infra
qwen
iCloud 同步（macOS）
如果你的專案目錄在 ~/Documents/ 下，iCloud 會自動同步到所有裝置。換新電腦時，只需登入 Apple ID 即可同步所有專案。
常見問題
Q1：安裝後執行 qwen 提示找不到命令？
解決方法：
# 檢查安裝路徑
which qwen
# 如果沒有輸出，重新安裝
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash
# 重新載入環境變數
source ~/.zshrc
Q2：API Key 無效或過期？
解決方法：
- 前往 阿里雲百煉控制檯 重新建立 API Key
- 執行
/auth重新配置 - 確認 API Key 格式正確（
sk-開頭）
Q3：Qwen Code 反應很慢？
可能原因：
- 網路連線不穩定
- API 請求量過大
- 模型負載高
解決方法：
- 切換到
qwen3.8-flash快速模型 - 檢查網路連線
- 稍後再試
Q4：如何更新 Qwen Code？
# NPM 安裝
npm update -g @qwen-code/qwen-code
# Homebrew 安裝
brew upgrade qwen-code
# 獨立安裝
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash
Q5：Qwen Code 會上傳我的程式碼嗎？
Qwen Code 會將你提供的程式碼片段傳送到 API 伺服器進行分析，但不會永久儲存或用於訓練。所有資料傳輸都經過加密。
Q6：如何完全移除 Qwen Code？
# NPM 安裝
npm uninstall -g @qwen-code/qwen-code
# Homebrew 安裝
brew uninstall qwen-code
# 刪除設定檔
rm -rf ~/.qwen
Q7：可以離線使用嗎？
目前 Qwen Code 需要網路連線才能使用，因為 AI 模型執行在雲端伺服器上。未來可能會推出本地模型版本。
Q8：如何檢視使用歷史？
Qwen Code 的對話歷史儲存在：
# macOS / Linux
~/.qwen/projects/-<路徑>/chats/
# 檢視歷史紀錄
ls ~/.qwen/projects/
總結
| 專案 | 說明 |
|---|---|
| 安裝 | 一行命令完成，支援多平臺 |
| 配置 | 首次啟動引導式設定，簡單直覺 |
| 使用 | 自然語言對話，支援檔案操作 |
| 進階 | 記憶、技能、計劃模式、MCP 整合 |
| 管理 | 工作目錄分類，iCloud 同步 |
Qwen Code 是一個強大的 AI 程式設計助手，從新手到專家都能找到適合的使用方式。建議先從基本對話開始，逐步探索進階功能。