Qwen Code 新手入门指南

约 2605 字大约 9 分钟...

Qwen Code 是一款专为中文开发者和成本敏感场景设计的 AI 编程助手。它基于开源的 Google Gemini CLI 深度改造，并针对阿里巴巴的 Qwen3-Coder 系列模型进行了优化。Qwen Code 不仅在代码生成和理解方面表现卓越，还支持本地部署和多种第三方模型平台，让你在享受 AI 编程便利的同时，完全掌控成本和数据安全。无论你是想要降低 AI 使用成本，还是需要在受限网络环境中工作，Qwen Code 都是你的理想选择。

第一步：快速安装 Qwen Code

Qwen Code 的安装过程简单直接，只需要几分钟就能完成。

检查系统要求

确保你的系统满足以下要求：

Node.js：版本 20 或更高

检查 Node.js 版本：

node --version

如果版本过低或未安装，请访问 nodejs.org 下载最新的 LTS 版本。

安装 Qwen Code

打开终端，运行以下命令：

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

验证安装

安装完成后，验证是否成功：

qwen --help

如果看到详细的帮助信息，恭喜你！Qwen Code 已经准备就绪。

第二步：选择最适合你的认证方式

Qwen Code 提供了多种认证方式，你可以根据自己的需求和使用场景选择最合适的。

方式一：OAuth 登录（推荐新手）

这是最简单的入门方式，提供慷慨的免费额度：

在终端运行：
```
qwen
```
首次运行时，Qwen Code 会：
- 自动打开你的默认浏览器
- 跳转到 qwen.ai 登录页面
- 使用你的账户完成授权
登录成功后，你将获得：
- 每日约 2000 次请求的免费额度
- 每分钟约 60 次请求的速率限制
- 无需任何配置，即开即用

方式二：API 密钥（适合高级用户）

如果你需要更多控制或想要使用付费服务：

使用阿里云 Dashscope：

访问阿里云模型服务灵骏获取 API 密钥
设置环境变量：

export OPENAI_API_KEY="你的API密钥"
export OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

使用 OpenRouter 等第三方平台：

export OPENAI_API_KEY="你的OpenRouter密钥"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="qwen/qwen-3-coder-plus"

方式三：本地模型（完全离线）

这是 Qwen Code 的独特优势 - 支持完全本地部署：

安装 Ollama：
- 访问 ollama.ai 下载并安装
- 或使用包管理器：brew install ollama（macOS）
下载 Qwen3-Coder 模型：
```
ollama pull qwen3-coder:7b
```
启动本地服务：
```
ollama serve
```

配置 Qwen Code 使用本地模型：

export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_MODEL="qwen3-coder:7b"
export OPENAI_API_KEY="ollama"  # 任意值即可

第三步：开始你的第一次中文 AI 编程

现在让我们开始体验 Qwen Code 的强大功能！

启动交互模式

在终端运行：

qwen

你会看到一个友好的中文界面，现在可以开始与 AI 对话了。

尝试这些中文编程任务

代码生成：

帮我写一个 Python 函数，用来计算两个日期之间的工作日天数

代码解释：

请详细解释这段代码的工作原理和可能的优化点

单元测试生成：

为这个函数生成完整的单元测试，包括边界情况

代码重构：

这个函数太复杂了，帮我重构成更清晰的版本

一次性命令模式

对于快速任务，你可以使用：

qwen -p "为这个模块补上完整的中文注释"

第四步：配置项目上下文

Qwen Code 使用 QWEN.md 文件来理解你的项目背景和编码规范。

创建项目配置文件

在你的项目根目录创建 QWEN.md 文件：

# 我的 Web 项目开发规范

## 项目概述

这是一个基于 Vue 3 + TypeScript 的现代化 Web 应用，主要用于企业内部的数据管理和可视化。

## 技术栈

- 前端框架：Vue 3 + Composition API
- 类型系统：TypeScript 4.9+
- 构建工具：Vite 4
- UI 组件库：Element Plus
- 状态管理：Pinia
- 路由：Vue Router 4
- HTTP 客户端：Axios
- 代码规范：ESLint + Prettier

## 编码规范

- 使用 Composition API 而不是 Options API
- 所有组件必须使用 TypeScript
- 组件名使用 PascalCase（如 UserProfile.vue）
- 文件名使用 kebab-case（如 user-profile.ts）
- 函数和变量使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 所有公共函数必须有 JSDoc 注释

## 项目结构

src/ ├── components/ # 可复用组件 ├── views/ # 页面组件 ├── composables/ # 组合式函数 ├── utils/ # 工具函数 ├── api/ # API 接口 ├── types/ # TypeScript 类型定义 └── assets/ # 静态资源


## 开发流程
- 新功能在 feature/功能名 分支开发
- 提交信息使用中文，格式：类型: 简短描述
- 所有 PR 必须通过 ESLint 检查
- 重要功能需要编写单元测试

## 特殊要求
- 优先考虑性能和用户体验
- 支持响应式设计，兼容移动端
- 所有用户输入必须进行验证
- 错误处理要友好且信息明确

查看项目上下文

在交互模式中使用以下命令：

/memory show - 查看当前加载的项目上下文
/memory add "新规则" - 动态添加项目规则

兼容性说明

由于 Qwen Code 是从 Gemini CLI 分支而来，它能识别名为 QWEN.md 的上下文文件。在旧版本中，/memory add 或其他命令可能仍会生成一个名为 GEMINI.md 的文件。为了确保最佳兼容性和避免混淆，建议您手动将项目中的 GEMINI.md 重命名为 QWEN.md。

第五步：高级配置和优化

创建个性化配置

创建 ~/.qwen/settings.json 文件来自定义你的体验：

{
  "sessionTokenLimit": 32000,
  "theme": "dark",
  "language": "zh-CN",
  "autoSave": true,
  "codeStyle": {
    "indentSize": 2,
    "useSpaces": true,
    "semicolons": true
  },
  "mcpServers": {
    "code-context": {
      "command": "npx",
      "args": ["@zilliz/code-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "你的密钥",
        "MILVUS_ADDRESS": "你的向量数据库地址",
        "MILVUS_TOKEN": "你的访问令牌"
      }
    }
  }
}

通过配置 mcpServers，你可以扩展 Qwen Code 的功能。例如，上面的 code-context 配置可以连接到 Zilliz Cloud 这样的向量数据库，实现对整个代码库的语义搜索，这对于理解大型复杂项目非常有帮助。

成本控制设置

为了更好地控制使用成本：

设置会话限制：

{
  "sessionTokenLimit": 16000,
  "maxHistoryLength": 10
}

使用本地模型：
- 完全免费，无网络依赖
- 数据不会离开你的设备
- 适合敏感项目
选择合适的模型：
- qwen3-coder：专门优化的编程模型
- qwen-flash：速度快，成本低
- qwen-plus：平衡性能和成本

第六步：掌握实用技巧

常用命令速查

在交互模式中，这些命令会提高你的效率：

/help - 显示所有可用命令
/stats - 查看 Token 使用统计
/clear - 清空当前对话
/restore - 恢复到之前的检查点（如果支持）
/memory show - 查看项目上下文
/memory add "规则" - 添加新的项目规则

中文编程最佳实践

使用中文描述需求：

帮我写一个用户注册的表单验证函数，需要验证邮箱格式、密码强度和手机号码

结合英文技术术语：

为这个 React Hook 添加 TypeScript 类型定义和错误处理

具体化你的要求：

重构这个函数，使用 ES6+ 语法，添加错误处理，并确保兼容 IE11

多模型切换

你可以在同一个项目中使用多个模型：

# 使用在线模型进行复杂任务
export OPENAI_MODEL="qwen3-coder-plus"
qwen -p "设计一个复杂的数据结构"

# 切换到本地模型进行简单任务
export OPENAI_MODEL="qwen3-coder:7b"
qwen -p "为这个函数添加注释"

了解使用成本

免费额度

Qwen Code 提供了业界最慷慨的免费额度：

认证方式	每日限制	每分钟限制	模型
OAuth	~2000 次请求	~60 次	Qwen3-Coder
本地模型	无限制	无限制	本地部署

付费使用成本

Qwen API 的定价非常有竞争力：

模型	输入价格	输出价格	适用场景
Qwen-Flash	$0.05/百万 Token	$0.40/百万 Token	快速任务
Qwen-Coder	$0.30/百万 Token	$1.50/百万 Token	编程专用
Qwen-Plus	$0.40/百万 Token	$1.20/百万 Token	通用任务
Qwen-Max	$1.60/百万 Token	$6.40/百万 Token	复杂任务

成本优化建议

合理选择模型：简单任务用 Flash，复杂任务用 Coder
控制会话长度：定期使用 /clear 清理上下文
批处理任务：将多个相关问题合并在一次对话中

常见问题解答

Q: Qwen Code 与其他 AI 编程工具有什么区别？ A: Qwen Code 专门为中文开发者优化，支持本地部署，成本更低，且在中文编程任务上表现更好。

Q: 本地模型的性能如何？ A: 对于大部分编程任务，本地的 Qwen3-Coder 7B 模型已经足够强大，而且完全免费。

Q: 我的代码会被发送到服务器吗？ A: 使用在线模型时会发送到服务器，但使用本地模型时代码完全不会离开你的设备。

Q: 如何在公司网络环境中使用？ A: 推荐使用本地模型部署，这样可以完全避免网络限制和数据安全问题。

Q: OAuth 登录失败怎么办？ A: 确保网络可以访问 qwen.ai，或者改用 API 密钥方式。

Q: 如何监控使用量？ A: 在交互模式中使用 /stats 命令查看当前会话的 Token 使用情况。

下一步探索

现在你已经掌握了 Qwen Code 的基础使用，可以尝试：

本地模型优化：尝试不同大小的 Qwen3-Coder 模型，找到性能和资源的最佳平衡
团队协作：与团队成员分享 QWEN.md 配置，统一开发规范
自动化集成：将 Qwen Code 集成到你的开发工作流中
多语言支持：探索 Qwen Code 在不同编程语言中的表现