Qwen-Code安装教程

Qwen Code 是一个强大的基于命令行、面向开发者的 AI 工作流工具，改编自 Gemini CLI，专门针对 Qwen3-Coder 模型进行了优化。它专门为代码理解、代码重构、自动化工作流、Git 操作等场景设计，让你的开发工作变得更高效、更智能。它既可以通过 OAuth 无感登录使用官方免费额度，也支持 OpenAI-compatible（自定义 API）模式接入。通过环境变量或项目.e

Mr小林

961人浏览 · 2025-09-05 16:32:43

Mr小林 · 2025-09-05 16:32:43 发布

一、概述

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. 常见会话管理命令：

• /help：显示帮助
• /clear：清空会话历史
• /compress：压缩会话历史以节省 token
• /status：查看当前会话 token 使用情况
• /exit 或 /quit：退出 CLI

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。