一、概述

Qwen Code 是一個強大的基于命令行、面向開發者的 AI 工作流工具，改編自 Gemini CLI，專門針對 Qwen3-Coder 模型進行了優化。

它專門為代碼理解、代碼重構、自動化工作流、Git 操作等場景設計，讓你的開發工作變得更高效、更智能。

它既可以通過 OAuth 無感登錄使用官方免費額度，也支持 OpenAI-compatible（自定義 API）模式接入。

---

二、適用場景

• ? 需要在本地快速分析大型代碼庫（架構梳理、依賴關系、API 列舉）。

• ? 自動化生成/補全單元測試、重構建議、批量修改（替換 todo、刪除 console.log 等）。

• ? 輔助完成 Git 工作（生成變更日志、PR 文案、自動化 rebase 建議）。

• ? 在 CI 或開發流程中做靜態審查、性能/安全問題掃描的輔助。

---

三、環境準備

• ? Node.js?20 或更高?版本（建議使用 nvm 管理）。安裝示例（Linux / macOS）：

# 安裝 Node.js（示例：使用官方安裝腳本）
curl -qL https://www.npmjs.com/install.sh | sh
# 或使用 nvm
nvm install 20
nvm use 20

確保能執行?node -v?/?npm -v。

---

四、安裝

1) 從 npm 安裝（推薦）

npm install -g @qwen-code/qwen-code@latest
qwen --version

2) 從源碼安裝（開發 / 定制）

git?clone?https://github.com/QwenLM/qwen-code.git
cd?qwen-code
npm install
npm install -g .

安裝完成后，可通過?qwen?啟動 CLI。

---

五、授權與認證

Qwen Code 支持多種認證方式，文檔列出推薦順序與區域策略（以下示例基于官方文檔）：

A. Qwen OAuth（推薦 / 零配置快速上手）

運行?qwen，CLI 會自動在瀏覽器發起 OAuth 登錄并存儲憑據（本地緩存）；免費額度與速率限制見官方說明（示例：2,000 請求/天，60 rpm）。適合個人快速試用與開發。

B. OpenAI-compatible API keys（自定義或企業）

通過環境變量或項目?.env?指定（示例）：

export?OPENAI_API_KEY="your_api_key_here"
export?OPENAI_BASE_URL="your_api_endpoint"
export?OPENAI_MODEL="your_model_choice"

官方還針對區域提供不同推薦（中國大陸 / 國際 —— 包括 ModelScope、Alibaba、OpenRouter 等接入選項），請根據地域與合規要求選擇。具體認證參數與流程見倉庫的 authentication 指南。

建議用魔搭社區注冊一個賬號，每天2000次免費調用次數

qwen全局變量（魔搭API）
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=https://api-inference.modelscope.cn/v1
OPENAI_MODEL=Qwen/Qwen3-Coder-480B-A35B-Instruct

環境變量中設置上，每次啟動qwen，就不需要重新配置了

六、快速上手

1、進入你的項目目錄：

在當前項目下 cmd，執行qwen命令，或者首次cmd 輸入項目根目錄

cd?/path/to/your-repo
qwen

第一次會需要登錄

第一次進入項目，要在當前項目下CMD

qwen      打開對話框/init     創建 a tailored QWEN.md file. ，只有首次需要執行。

2、在 CLI 會話中直接輸入自然語言命令，例如：

> Explain this codebase structure
> Help me refactor this function
> Generate unit tests for this module

1. 1. 常見會話管理命令：

• ??/help：顯示幫助

• ??/clear：清空會話歷史

• ??/compress：壓縮會話歷史以節省 token

• ??/status：查看當前會話 token 使用情況

• ??/exit?或?/quit：退出 CLI

1. 1. 鍵盤快捷鍵：

• ??Ctrl+C：取消當前操作

• ??Ctrl+D：退出（在空行時）

• ??Up/Down：命令歷史導航

---

七、常用任務示例

1) 代碼庫梳理（Architecture）

在項目根目錄運行?qwen，輸入：

> Describe the main pieces of this system's architecture

請求會返回模塊劃分、關鍵依賴、數據流向等建議。

2) 自動生成單元測試

> Generate unit tests for src/auth.ts

工具會輸出測試文件示例與斷言邊界，開發者可直接復制到測試目錄并運行。

3) Git 自動化

> Create a changelog from recent commits
> Find all TODO comments and create GitHub issues

---

八、進階配置

會話 Token 限制

為了控制成本，可在用戶目錄下創建?.qwen/settings.json，配置?sessionTokenLimit：

{"sessionTokenLimit":?32000
}

此項限定單次會話的 token 上限（非累計 API 調用）。同時可使用?/compress?在會話需要壓縮上下文時觸發簡化歷史。(GitHub[1])

配置文件與環境變量優先級

• ? 環境變量優先（OPENAI_API_KEY?/?OPENAI_BASE_URL?/?OPENAI_MODEL）

• ? 項目?.env（便于在 CI 中使用）

• ? Qwen OAuth（會在本地生成并緩存認證信息）

---

九、故障排查

常見問題與快速排查建議：

• ??安裝失敗 / npm 報錯：檢查 Node 版本、網絡代理、npm 權限（嘗試?npm cache clean --force、使用 nvm 切換 Node 版本）。

• ??認證失敗：確認環境變量是否正確、API endpoint 是否可達，或嘗試 Qwen OAuth 重新登錄。

• ??token 超出 / 會話太長：設置?.qwen/settings.json?中的?sessionTokenLimit，并在會話中使用?/compress。

• ??模型或請求不穩定：檢查所選?OPENAI_MODEL?是否支持你所在地區的 endpoint，或使用官方推薦的 region-specific provider。