Qwen Code 完全使用教程

📖 目录

• 一、Qwen Code 是什么？

• 二、快速安装

• 三、首次使用与登录

• 四、核心功能一览

• 五、常用命令速查

• 六、日常开发工作流

• 七、高级功能详解

• 八、配置与定制

• 九、实用技巧与最佳实践

• 十、常见问题排查

---

一、Qwen Code 是什么？

Qwen Code 是通义千问推出的终端 AI 编程助手，具有以下特点：

• ✅ 直接在终端运行：无需打开额外窗口

• ✅ 理解整个代码库：自动分析项目结构

• ✅ 直接编辑文件：可以创建、修改、删除代码文件

• ✅ 执行命令：运行测试、启动服务器、Git 操作等

• ✅ 支持 MCP 协议：连接外部数据源（GitHub、Figma 等）

---

二、快速安装

Windows 用户（推荐）

以管理员身份运行 CMD：

curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat

手动安装（需要 Node.js 20+）

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

macOS / Linux 用户

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

提示：安装后建议重启终端以确保环境变量生效。

---

三、首次使用与登录

1. 启动 Qwen Code

cd your-project
qwen

2. 选择认证方式

首次使用会提示登录，选择 Qwen OAuth（免费） 并按提示完成登录。

3. 验证登录状态

qwen auth status

4. 重新登录（如需）

/auth

登录凭证会自动保存，下次使用无需重复登录。

---

四、核心功能一览

🎯 1. 理解代码库

获取项目概览：

这个项目是做什么的？

分析目录结构：

explain the folder structure

查找特定功能代码：

find the files that handle user authentication

🛠️ 2. 编写与修改代码

添加新功能：

add a hello world function to the main file

修复 Bug：

there's a bug where users can submit empty forms - fix it

重构代码：

refactor the authentication module to use async/await instead of callbacks

🧪 3. 测试与调试

编写测试：

write unit tests for the calculator functions

运行测试：

run the tests and fix any failures

📝 4. Git 操作

查看更改：

what files have I changed?

提交代码：

commit my changes with a descriptive message

创建分支：

create a new branch called feature/quickstart

解决冲突：

help me resolve merge conflicts

---

五、常用命令速查

🔧 会话管理

命令	功能	示例
/help 或 /?	显示帮助信息	/help
/clear 或 Ctrl+L	清屏	/clear
/compress	压缩聊天历史以节省 Token	/compress
/context	查看上下文使用情况	/context
/context detail	查看详细使用情况	/context detail
/stats	查看会话统计信息	/stats
/quit 或 /exit	退出 Qwen Code	/quit

🎨 界面定制

命令	功能	示例
/theme	切换主题	/theme
/vim	开关 Vim 模式	/vim
/language	查看/更改语言	/language
→ ui zh-CN	设置界面语言为中文	/language ui zh-CN
→ output Chinese	设置输出语言	/language output Chinese

🤖 模型与工具

命令	功能	示例
/model	切换模型	/model
/tools	查看可用工具列表	/tools
/mcp	查看 MCP 服务器	/mcp
/skills	查看可用技能	/skills
/approval-mode	更改审批模式	/approval-mode auto-edit

💾 会话恢复

命令	功能
/resume	恢复之前的会话
qwen --continue	继续最近的会话
qwen --resume	显示会话选择器

⚡ 快捷操作

快捷键	功能
Ctrl+L	清屏
Ctrl+T	切换工具描述
Tab	命令补全
↑	历史命令
?	查看所有快捷键

---

六、日常开发工作流

1️⃣ 理解新项目

# 1. 进入项目目录
cd /path/to/project
​
# 2. 启动 Qwen Code
qwen
​
# 3. 请求项目概览
give me an overview of this codebase
​
# 4. 深入了解
explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

2️⃣ 高效修 Bug

# 1. 描述问题
I'm seeing an error when I run npm test
​
# 2. 请求修复建议
suggest a few ways to fix the error in user.ts
​
# 3. 应用修复
update user.ts to add the null check you suggested
​
# 4. 验证修复
run the tests again

3️⃣ 代码重构

# 1. 识别需要重构的代码
find deprecated API usage in our codebase
​
# 2. 获取重构建议
suggest how to refactor utils.js to use modern JavaScript features
​
# 3. 执行重构
refactor utils.js to use ES 2024 features while maintaining the same behavior
​
# 4. 验证重构
run tests for the refactored code

4️⃣ 编写测试

# 1. 识别未测试的代码
find functions in UserService that are not covered by tests
​
# 2. 生成测试框架
add tests for the user service
​
# 3. 添加边界条件测试
add test cases for edge conditions in the user service
​
# 4. 运行测试
run the new tests and fix any failures

5️⃣ 创建 Pull Request

# 1. 总结更改
summarize the changes I've made to the authentication module
​
# 2. 创建 PR
create a pr
​
# 3. 优化描述
enhance the PR description with more context about the security improvements
​
# 4. 添加测试信息
add information about how these changes were tested

---

七、高级功能详解

🔗 1. 文件和目录引用（@ 命令）

快速引入文件内容到对话中，无需等待 Qwen Code 自动读取：

# 引用单个文件
Explain the logic in @src/utils/auth.js
​
# 引用目录
What's the structure of @src/components?
​
# 引用多个文件
Compare @file1.js and @file2.js

提示：文件路径可以是相对路径或绝对路径。

🤖 2. 审批模式（Approval Mode）

控制 Qwen Code 修改文件的权限：

模式	说明	适用场景
plan	仅分析，不执行	安全审查
default	修改需审批	日常使用
auto-edit	自动批准修改	受信任环境
yolo	全部自动批准	快速原型

切换模式：

/approval-mode auto-edit

🌐 3. MCP 协议集成

MCP（Model Context Protocol）允许 Qwen Code 连接外部数据源：

# 查看已配置的 MCP 服务器
/mcp
​
# 使用 MCP 资源
Show me the data from @github: repos/owner/repo/issues

配置 MCP 服务器：在 settings.json 中添加：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

🎯 4. 专用子代理（Sub-agents）

Qwen Code 可以自动使用专门的子代理处理特定任务：

# 查看所有子代理
/agents
​
# 代码审查
review my recent code changes for security issues
​
# 调试
have the debugger subagent investigate why users can't log in
​
# 明确请求特定子代理
use the code-reviewer subagent to check the auth module

创建自定义子代理：

/agents

然后选择"create"，定义：

• 唯一标识符（如 code-reviewer）

• 何时使用此代理

• 可访问的工具

• 系统提示词

💻 5. Unix 管道集成

将 Qwen Code 作为 Unix 工具使用：

# 分析错误日志
cat build-error.txt | qwen -p 'explain the root cause of this build error'
​
# 输出到文件
cat build-error.txt | qwen -p 'explain this error' > explanation.txt
​
# 指定输出格式（JSON）
cat code.py | qwen -p 'analyze for bugs' --output-format json > analysis.json
​
# 流式 JSON（实时处理）
cat log.txt | qwen -p 'find errors' --output-format stream-json

🌳 6. Git Worktrees 并行工作

使用 Git Worktrees 同时运行多个 Qwen Code 会话：

# 创建新的 worktree
git worktree add ../project-feature-a -b feature-a
​
# 在 worktree 中运行 Qwen Code
cd ../project-feature-a
qwen
​
# 在另一个终端打开另一个 worktree
cd ../project-bugfix
qwen
​
# 管理 worktrees
git worktree list
git worktree remove ../project-feature-a

---

八、配置与定制

📁 配置文件位置

级别	路径	说明
用户级	~/.qwen/settings.json	全局配置
项目级	<project>/.qwen/settings.json	项目特定配置

⚙️ 常用配置项

{
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": -1,
    "generationConfig": {
      "timeout": 300,
      "temperature": 0.7,
      "max_tokens": 8192
    }
  },
  "ui": {
    "theme": "dark",
    "showLineNumbers": true,
    "compactMode": false
  },
  "general": {
    "vimMode": false,
    "enableAutoUpdate": true,
    "gitCoAuthor": true
  },
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)"
    ]
  }
}

🎨 主题切换

# 在会话中切换主题
/theme
​
# 或在配置文件中设置
{
  "ui": {
    "theme": "dark"
  }
}

---

九、实用技巧与最佳实践

💡 提示词技巧

✅ DO（推荐）

具体描述问题：

修复登录后 bug：用户输入错误密码后看到空白页面

分步指示：

1. 创建用户配置表
2. 创建 API 端点获取和更新配置
3. 构建允许用户编辑信息的网页

让 Qwen Code 先探索：

先分析数据库结构，然后构建仪表板

❌ DON'T（避免）

过于模糊：

修复 bug

过于复杂：

重构整个认证模块，改用 GraphQL，添加缓存，优化数据库查询，写测试，更新文档，创建 PR

📊 Token 管理

查看使用情况：

/context

节省 Token：

• 使用 /compress 压缩聊天历史

• 避免过长的对话

• 使用 @ 引用特定文件而非让 Qwen Code 自动探索

压缩阈值配置：

{
  "model": {
    "chatCompression": {
      "contextPercentageThreshold": 0.7
    }
  }
}

🚀 效率提升

1. 使用 Tab 补全：快速完成命令输入

2. 利用历史：按 ↑ 键快速访问之前的命令

3. 创建自定义命令：将常用提示词保存为命令

4. 使用计划模式：复杂任务先用 /plan 分析

5. 开启紧凑模式：Ctrl+O 隐藏工具输出，保持界面简洁

📝 创建自定义命令

1. 创建命令文件：

mkdir -p ~/.qwen/commands/review
touch ~/.qwen/commands/review/code.md

2. 编辑命令内容：

---
description: 代码审查工具
---
​
请审查以下代码，关注：
1. 代码质量
2. 潜在 bug
3. 性能问题
4. 安全漏洞
​
{{args}}

3. 使用自定义命令：

/review:code @src/auth.js

---

十、常见问题排查

❌ 问题 1：请求超时

症状：Streaming request timeout after 44s

解决方案：

1. 增加超时时间：

{
  "model": {
    "generationConfig": {
      "timeout": 300
    }
  }
}

1. 压缩上下文：

/compress

1. 减少输入长度：避免一次性引入过多文件

❌ 问题 2：认证失败

症状：无法登录或提示认证错误

解决方案：

# 检查认证状态
qwen auth status
​
# 重新登录
qwen auth
​
# 或在会话内
/auth

❌ 问题 3：命令执行被拒绝

症状：Qwen Code 尝试运行命令时提示需要权限

解决方案：

# 在会话内更改审批模式
/approval-mode auto-edit
​
# 或在配置文件中允许特定命令
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)"
    ]
  }
}

❌ 问题 4：Token 使用过快

症状：很快就达到上下文限制

解决方案：

1. 使用 /compress 压缩历史

2. 使用 @ 精确引用文件

3. 减少不必要的探索

4. 配置自动压缩阈值

❌ 问题 5：输出语言不对

症状：Qwen Code 总是用英文回复

解决方案：

# 设置输出语言
/language output Chinese
​
# 或在配置文件中
{
  "output": {
    "language": "Chinese"
  }
}

---

📚 附录

A. 键盘快捷键完整列表

快捷键	功能	备注
Ctrl+L	清屏	等同于 /clear
Ctrl+T	切换工具描述	MCP 工具管理
Ctrl+O	切换紧凑模式	隐藏工具输出
Ctrl+C ×2	退出确认	安全退出机制
Ctrl+Z	撤销输入	文本编辑
Ctrl+Shift+Z	重做输入	文本编辑
Tab	命令补全	提高输入效率
↑ / ↓	历史命令	快速复用
?	显示帮助	查看所有快捷键

B. 常用提示词模板

代码审查

请审查 @文件路径，关注：
1. 代码质量
2. 潜在 bug
3. 性能问题
4. 是否符合最佳实践

Bug 修复

我发现了一个 bug：[描述 bug]
复现步骤：
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
​
请帮我定位并修复这个问题。

功能开发

我需要实现 [功能描述]。
​
要求：
1. [要求 1]
2. [要求 2]
3. [要求 3]
​
请先分析现有代码结构，然后制定实现计划。

文档编写

请为 @文件路径 添加完整的文档注释。
​
要求：
- 使用 JSDoc 格式
- 包含参数说明
- 包含返回值说明
- 包含使用示例

C. 获取帮助

• 在 Qwen Code 内：输入 /help 或直接提问

• 官方文档：查阅 Qwen Code 内置文档

• 社区讨论：GitHub Discussions

• 报告问题：/bug [问题描述]

---

🎓 总结

Qwen Code 是一个强大的 AI 编程助手，能够：

✅ 理解整个代码库 ✅ 直接编辑文件 ✅ 执行命令和测试 ✅ 协助 Git 操作 ✅ 集成外部工具（MCP） ✅ 支持自定义命令和技能

关键使用原则：

1. 🎯 具体明确：清晰描述你的需求

2. 📝 分步执行：复杂任务拆解为小步骤

3. 🔍 先探索后修改：让 Qwen Code 先理解代码

4. 💾 保存 Token：适时使用 /compress

5. 🔒 安全第一：合理设置审批模式

祝您使用愉快！🚀