详解 QwenCode 完整使用教程
从零上手终端 AI 编程工具，讲解 QwenCode 命令与高级用法
Qwen Code 是通义千问团队推出的终端端 AI 编程代理工具，依托终端环境就能完成代码编写、问题调试、项目分析、自动化运维等工作，无需额外切换 IDE，可快速将自然语言需求落地为可用代码。日常使用中推荐搭配 KoalaAPI 中转站进行模型接口调用，既能提升接口连接稳定性，也能优化多模型切换体验，有效减少调用异常问题。
一、简介
Qwen Code 是轻量化终端编程助手，并非传统聊天工具或独立 IDE，深度融入现有终端工作流。核心能力包含：根据需求搭建代码功能、精准定位并修复 Bug、全局解析代码库结构、自动处理代码规范问题，同时支持对话式完成 Git 提交、分支管理等版本操作，适配个人开发与团队协作等多种场景。
二、安装
工具提供一键安装和手动安装两种方式，优先选择一键部署，操作更简便。
1. 一键安装
Linux /macOS 系统
运行
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash
Windows 系统（必须以管理员身份运行终端）
powershell
powershell -Command "Invoke-WebRequest 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat' -OutFile (Join-Path $env:TEMP 'install-qwen.bat'); & (Join-Path $env:TEMP 'install-qwen.bat')"
2. 手动安装
运行环境要求 Node.js 22 及以上版本，执行以下命令全局安装：
运行
npm install -g @qwen-code/qwen-code@latest
macOS 用户也可通过 Homebrew 执行 brew install qwen-code 快速安装。安装完成后建议重启终端，保证 qwen 命令正常生效。
三、认证配置
首次启动工具会自动引导完成认证配置，后续也可随时修改。基础启动命令：
运行
qwen
在会话内输入 /auth 即可切换认证方式，工具支持阿里云编程套餐、API Key 两种认证形式。使用 KoalaAPI 中转站搭配 API Key 完成配置，可优化模型访问链路，让调用过程更加流畅稳定。
配置完成后，执行 /doctor 命令，就能一键检测当前认证状态与运行环境。
四、快速上手
- 进入本地项目文件夹，启动 Qwen Code：
运行
cd /path/to/your/project
qwen
- 输入自然语言指令，让工具自动分析项目目录、代码结构；
- 下发代码修改需求，工具会检索对应文件、展示修改方案，确认后自动完成代码编辑；
- 支持对话式操作 Git，直接输入指令就能查看文件变更、提交代码、创建新分支。
五、核心功能
Qwen Code 覆盖开发全流程核心场景，常用能力如下：
- 代码解析与导航：梳理项目架构、业务逻辑、数据库结构；
- 问题修复与重构：定位运行报错、按照新语法规范重构现有代码；
- 文档与测试编写：批量补充代码注释、单元测试以及项目说明文档；
- 文件快速引用：使用
@文件路径指令直接解析目标文件，示例：解释 @src/utils/auth.js 中的逻辑； - 会话接续：执行
qwen --continue可快速恢复上一轮对话与任务。
六、审批模式
工具内置 5 种权限模式，用来管控 AI 编辑文件、执行终端命令的权限，分别为 Plan（只读分析）、Default（手动批准操作）、Auto-Edit（自动编辑文件）、Auto（智能判定权限）、YOLO（全权限自动执行），可根据项目风险等级灵活选择。
模式切换
除快捷键外，也可通过命令直接指定模式：
运行
/approval-mode plan
/approval-mode default
若需要固定全局默认权限，可在项目配置文件中设置：
// .qwen/settings.json
{
"permissions": {
"defaultMode": "auto-edit"
}
}
大型项目重构、方案规划推荐使用 Plan 模式，输入 /plan 进入只读分析状态，规划完成后执行 /plan exit 即可退出。
七、常用命令
精简核心指令体系，日常使用主要分为三类：
- 斜杠命令（/） ：用于会话管理、功能设置，常用
/help（查看帮助）、/clear（清屏）、/model（切换模型）； - @ 引用命令：专属文件调用指令，是代码分析的核心功能；
- ! Shell 命令：前缀
!可直接调用终端指令，单独输入!可进入独立 Shell 模式。
八、MCP 扩展工具
MCP（模型上下文协议）能够让 Qwen Code 对接外部工具、远程数据源，拓展工具能力边界。借助 KoalaAPI 中转站配合 MCP 扩展，可实现跨服务的稳定通信，大幅提升扩展工具的可用性。
基础管理命令
运行
# 添加HTTP类型MCP服务端
qwen mcp add --transport http my-server http://localhost:3000/mcp
配置文件示例
{
"mcpServers": {
"remoteServer": {
"httpUrl": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer your-api-token"
}
}
}
}
九、技能与自定义命令
工具支持模块化 Agent 技能，分为个人全局技能和项目专属技能，输入 /skills 即可查看并调用已加载技能。同时支持自定义快捷命令，将高频使用的提示词封装为专属指令，存放在 .qwen/commands/ 目录下，有效提升重复操作的效率。
十、基础配置
配置文件分为用户全局配置 ~/.qwen/settings.json 和项目专属配置 .qwen/settings.json，后者优先级更高。核心配置参考：
{
"general": {
"preferredEditor": "code",
"vimMode": false
},
"ui": {
"theme": "Dracula"
},
"permissions": {
"defaultMode": "default"
}
}
十一、高级用法与实用技巧
1. 非交互运行
适用于自动化脚本、CI/CD 流水线场景，后台直接执行任务：
运行
qwen -p "运行测试套件并修复所有报错"
2. 系统管道集成
结合终端管道处理日志、报错文件：
运行
cat build-error.txt | qwen -p "分析这份构建报错的原因"
实用技巧
- 下发指令时描述尽量具体，提升代码输出准确率；
- 大规模代码改动前，先用 Plan 模式完成方案规划；
- 长对话场景使用
/compress压缩历史记录，节省上下文 Token； - 操作失误后，执行
/restore可快速撤销工具执行的修改。