QwenCode使用教程

Qwen Code 使用教程

Qwen Code 是通义千问团队推出的 AI 编程代理工具，运行在终端中，帮助你更快地将想法变为代码。

简介
安装
认证配置
快速上手
核心功能
审批模式详解
命令系统
键盘快捷键
[MCP 扩展工具](#MCP 扩展工具 "#mcp-%E6%89%A9%E5%B1%95%E5%B7%A5%E5%85%B7")
[Agent Skills（技能系统）](#Agent Skills（技能系统） "#agent-skills%E6%8A%80%E8%83%BD%E7%B3%BB%E7%BB%9F")
自定义命令
配置详解
主题定制
高级用法
常见问题与技巧

简介

Qwen Code 是一个终端内的 AI 编程助手，它可以：

根据描述构建功能：用自然语言告诉它你想做什么，它会制定计划、编写代码、确保可用
调试和修复问题：描述 Bug 或粘贴错误信息，它会分析代码库、定位问题并实施修复
导航任意代码库：询问关于代码库的任何问题，它会分析整个项目结构并给出回答
自动化繁琐任务：修复 lint 问题、解决合并冲突、编写发布说明等
Git 操作：对话式地完成提交、分支管理、PR 创建等

它不是又一个聊天窗口，也不是又一个 IDE，而是在你已有的终端环境中工作。

安装

一键安装（推荐）

Linux / macOS

bash 复制代码

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

Windows（以管理员身份运行）

cmd 复制代码

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')"

手动安装

需要 Node.js 22+，然后使用 npm：

bash 复制代码

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

macOS 也可以用 Homebrew：

bash 复制代码

brew install qwen-code

提示：安装后建议重启终端，确保 qwen 命令已在 PATH 中生效。

认证配置

启动 Qwen Code 后，首次使用会提示配置认证方式：

bash 复制代码

qwen

或者在会话中随时使用 /auth 命令更改认证方式。

支持的认证方式

方式	说明
阿里云编程套餐 (Coding Plan)	固定月费，多种模型可选
API Key	从阿里云百炼平台获取 API Key

配置步骤

运行 qwen
选择认证方式
按提示输入 API Key 或登录 Coding Plan 账户
使用 /doctor 可随时检查当前认证和环境状态

快速上手

第一步：启动

bash 复制代码

cd /path/to/your/project
qwen

启动后会看到欢迎界面，显示会话信息、最近对话和更新日志。

第二步：了解你的代码库

复制代码

这个项目是做什么的？

解释一下文件夹结构

Qwen Code 会自动分析你的文件并按需提供上下文。

第三步：进行第一次代码修改

复制代码

在主文件中添加一个 hello world 函数

Qwen Code 会：

找到合适的文件
展示建议的修改
请求你的确认
执行编辑

第四步：使用 Git

复制代码

我修改了哪些文件？

用描述性的提交信息提交我的更改

bash 复制代码

创建一个名为 feature/quickstart 的新分支

核心功能

1. 代码理解与导航

复制代码

找到处理用户认证的文件

追踪从前端到数据库的登录流程

分析数据库 schema

2. Bug 修复

bash 复制代码

运行 npm test 时出现错误，帮我修复

复制代码

用户提交空表单时有一个 bug，修复它

3. 代码重构

复制代码

将 utils.js 重构为使用 ES2024 特性，保持相同行为

4. 编写测试

复制代码

为通知服务添加测试

为计算函数编写单元测试

5. 文档处理

复制代码

为 auth.js 中缺少注释的函数添加 JSDoc 注释

更新 README 的安装说明

6. 创建 Pull Request

复制代码

创建一个 PR

Qwen Code 会自动总结变更、生成 PR 描述。

7. 文件引用（@ 命令）

使用 @ 快速引入文件内容：

bash 复制代码

解释 @src/utils/auth.js 中的逻辑

bash 复制代码

@src/components 目录的结构是什么？

8. 恢复之前的对话

bash 复制代码

# 继续最近的对话
qwen --continue

# 选择历史对话继续
qwen --resume

# 以非交互模式继续最近对话
qwen --continue -p "继续我的任务"

审批模式详解

Qwen Code 提供五种权限模式，灵活控制 AI 对代码和系统的交互方式。

模式对比

模式	文件编辑	Shell 命令	适用场景	风险等级
Plan（计划）	❌ 仅只读分析	❌ 不执行	代码探索、规划变更、安全审查	最低
Default（默认）	✅ 需手动批准	✅ 需手动批准	新代码库、关键系统、团队协作	低
Auto-Edit（自动编辑）	✅ 自动批准	✅ 需手动批准	日常开发、重构	中
Auto（自动）	✅ 分类器评估	✅ 分类器评估	长时间自主会话	中
YOLO	✅ 自动批准	✅ 自动批准	可信个人项目、自动化脚本	最高

切换模式

在会话中使用快捷键 Shift+Tab （Windows 上是 Tab）循环切换：

scss 复制代码

Plan → Default → Auto-Edit → Auto → YOLO → Plan → ...

或使用命令：

bash 复制代码

/approval-mode plan
/approval-mode default
/approval-mode auto-edit
/approval-mode auto
/approval-mode yolo

Plan 模式使用示例

bash 复制代码

/plan 我需要将认证系统重构为 OAuth2，请创建详细的迁移计划

Qwen Code 进入只读模式分析当前实现，然后你可以继续追问：

复制代码

向后兼容性怎么处理？
数据库迁移应该如何进行？

规划完成后，使用 /plan exit 退出计划模式，恢复之前的模式。

持久化配置

json 复制代码

// .qwen/settings.json
{
  "permissions": {
    "defaultMode": "auto-edit"
  }
}

命令系统

斜杠命令（/）

会话与项目管理

命令	说明	示例
`/init`	分析当前目录并创建初始上下文文件	`/init`
`/summary`	基于对话历史生成项目摘要	`/summary`
`/compress`	用摘要替换聊天历史以节省 Token	`/compress`
`/resume`	恢复之前的对话会话	`/resume`
`/recap`	生成当前会话的一行摘要	`/recap`
`/restore`	将文件恢复到工具执行前的状态	`/restore` 或 `/restore <ID>`

界面与工作区

命令	说明	示例
`/clear`	清屏	`/clear` 或 `Ctrl+L`
`/context`	显示上下文窗口使用情况	`/context`
`/theme`	更改视觉主题	`/theme`
`/vim`	开关 Vim 编辑模式	`/vim`
`/directory`	管理多目录工作区	`/dir add ./src,./tests`
`/editor`	选择编辑器	`/editor`

语言设置

命令	说明	示例
`/language`	查看或更改语言设置	`/language`
`/language ui [语言]`	设置界面语言	`/language ui zh-CN`
`/language output [语言]`	设置 AI 输出语言	`/language output Chinese`

支持的 UI 语言：zh-CN（简体中文）、en-US（英语）、ja-JP（日语）、ru-RU（俄语）、de-DE（德语）、pt-BR（葡萄牙语-巴西）、fr-FR（法语）、ca-ES（加泰罗尼亚语）

工具与模型

命令	说明	示例
`/mcp`	查看已配置的 MCP 服务器和工具	`/mcp`
`/tools`	显示可用工具列表	`/tools`
`/skills`	列出可用技能	`/skills`
`/model`	切换当前会话使用的模型	`/model`
`/model --fast`	设置轻量模型用于提示建议	`/model --fast qwen3-coder-flash`
`/extensions`	列出活跃的扩展	`/extensions`
`/memory`	打开记忆管理器	`/memory`
`/remember`	保存持久记忆	`/remember 偏好简洁的回复`
`/forget`	移除记忆条目	`/forget <query>`

内置技能命令

命令	说明	示例
`/review`	代码审查（5 个并行代理）	`/review`、`/review 123`
`/loop`	定时循环执行提示	`/loop 5m 检查构建状态`
`/qc-helper`	回答 Qwen Code 使用问题	`/qc-helper 如何配置 MCP？`

侧边提问（/btw）

在不打断主对话流的情况下提问：

bash 复制代码

/btw JavaScript 中 let 和 var 有什么区别？

侧边问题作为独立 API 调用，不影响主对话
主对话不被阻塞
回答渲染在输入区域上方

信息、设置与帮助

命令	说明
`/help` 或 `/?`	显示帮助信息
`/status` 或 `/about`	显示版本信息
`/stats`	显示当前会话详细统计
`/settings`	打开设置编辑器
`/auth`	更改认证方式
`/bug`	提交问题反馈
`/copy`	复制最后的输出到剪贴板
`/quit` 或 `/exit`	退出 Qwen Code

@ 命令（文件引用）

less 复制代码

@src/main.py 请解释这段代码
@docs/ 总结这个文档的内容

! 命令（Shell 执行）

diff 复制代码

!ls -la
!git status

输入单独的 ! 进入 Shell 模式，之后输入的内容都会作为 Shell 命令执行，再次输入 ! 退出。

键盘快捷键

通用快捷键

快捷键	说明
`Esc`	关闭对话框和建议
`Ctrl+C`	取消请求并清除输入，按两次退出
`Ctrl+D`	输入为空时退出应用
`Ctrl+L`	清屏
`Ctrl+O`	切换紧凑模式（隐藏/显示工具输出和思考过程）
`Ctrl+S`	允许长响应完整打印
`Ctrl+T`	切换工具描述显示
`Ctrl+B`	将前台 Shell 命令提升为后台任务
`Alt/Option+M`	切换 Markdown 渲染模式
`Shift+Tab`（Windows: `Tab`）	循环切换审批模式

输入提示区

快捷键	说明
`Enter`	提交提示
`Tab`	自动补全当前建议
`↑` / `↓`	浏览历史记录
`Ctrl+V`（Windows: `Alt+V`）	粘贴剪贴板内容（支持图片）
`Ctrl+X` / `Meta+Enter`	在外部编辑器中打开当前输入
`Ctrl+Y`	重试上次失败的请求
`Ctrl+R`	反向搜索输入/Shell 历史
`\`（行尾）+ `Enter`	插入换行
`!`	输入为空时切换 Shell 模式
`?`	输入为空时切换快捷键显示

MCP 扩展工具

MCP (Model Context Protocol) 允许 Qwen Code 连接外部工具和数据源。

快速添加 MCP 服务器

bash 复制代码

# 添加 HTTP 类型的 MCP 服务器
qwen mcp add --transport http my-server http://localhost:3000/mcp

# 管理 MCP 服务器
qwen mcp

支持的传输类型

类型	适用场景	配置字段
`http`	远程服务（推荐）	`httpUrl`
`sse`	旧版 SSE 服务	`url`
`stdio`	本地进程/脚本	`command`, `args`

配置示例

在 .qwen/settings.json 中配置：

json 复制代码

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING"
      },
      "timeout": 15000
    },
    "remoteServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

CLI 管理

bash 复制代码

# 添加服务器
qwen mcp add <name> <commandOrUrl> [args...]

# 指定 scope
qwen mcp add --scope user my-server ...

# 设置环境变量
qwen mcp add -e KEY=value ...

# 设置 HTTP 头
qwen mcp add --header "X-Api-Key: abc123" ...

# 移除服务器
qwen mcp remove <name>

Agent Skills（技能系统）

技能是模块化的能力包，通过 SKILL.md 文件为模型提供专业指导。

技能存放位置

类型	路径	说明
个人技能	`~/.qwen/skills/<name>/`	所有项目可用
项目技能	`.qwen/skills/<name>/`	仅当前项目，可通过 Git 共享

创建技能

bash 复制代码

mkdir -p .qwen/skills/my-skill

编写 SKILL.md：

yaml 复制代码

---
name: my-skill
description: 简要描述技能的功能和使用时机
priority: 10
---

# 技能名称

## 使用说明
为 Qwen Code 提供清晰的步骤指导。

## 示例
展示使用此技能的具体示例。

可选添加辅助文件：

text 复制代码

my-skill/
├── SKILL.md          (必需)
├── reference.md      (参考文档)
├── scripts/
│   └── helper.py     (辅助脚本)
└── templates/
    └── template.txt   (模板文件)

查看与使用技能

bash 复制代码

# 查看所有可用技能
/skills

# 显式调用技能
/skills my-skill

技能通常由模型自动判断何时使用，基于 description 字段的匹配。

通过 Git 共享技能

bash 复制代码

git add .qwen/skills/
git commit -m "Add team skill for PDF processing"
git push

自定义命令

将常用的提示词保存为快捷命令，提高效率。

存放位置

类型	路径	优先级
全局命令	`~/.qwen/commands/`	低
项目命令	`<项目>/.qwen/commands/`	高

命令格式（Markdown）

创建 .md 文件，支持 YAML frontmatter：

markdown 复制代码

---
description: 生成 Commit 消息
---

请根据以下 diff 生成 Commit 消息：

```diff
!{git diff --staged}

yaml 复制代码

### 文件名到命令名的映射

| 文件位置 | 生成的命令 | 调用示例 |
|---------|-----------|---------|
| `~/.qwen/commands/test.md` | `/test` | `/test 参数` |
| `<项目>/.qwen/commands/git/commit.md` | `/git:commit` | `/git:commit 消息` |

### 参数注入

| 语法 | 说明 |
|------|------|
| `{{args}}` | 上下文感知的参数注入 |
| `!{command}` | Shell 命令执行注入 |
| `@{file path}` | 文件内容注入 |

### 示例：代码审查命令

```markdown
---
description: 基于最佳实践的代码审查
---

审查 {{args}}，参考标准：

@{docs/code-standards.md}

配置详解

配置文件位置与优先级

层级	路径	说明
用户级	`~/.qwen/settings.json`	个人全局配置
项目级	`<项目>/.qwen/settings.json`	项目特定配置，覆盖用户级
系统级	系统路径（管理员控制）	最高优先级

优先级（从高到低）：CLI 参数 > 环境变量 > 系统设置 > 项目设置 > 用户设置 > 默认值

常用配置项

jsonc 复制代码

// .qwen/settings.json
{
  // 通用设置
  "general": {
    "preferredEditor": "code",     // 首选编辑器
    "vimMode": false,              // Vim 键绑定
    "enableAutoUpdate": true,      // 自动更新
    "showSessionRecap": true       // 返回终端时自动显示会话摘要
  },

  // UI 设置
  "ui": {
    "theme": "Dracula",            // 主题
    "compactMode": false,          // 紧凑模式
    "showLineNumbers": true,       // 代码块行号
    "hideTips": false,             // 隐藏提示
    "hideBanner": false,           // 隐藏启动 Banner
    "renderMode": "render"         // Markdown 渲染模式
  },

  // 权限设置
  "permissions": {
    "defaultMode": "default"       // 默认审批模式
  },

  // 模型设置
  "model": {
    "name": "qwen3-coder"          // 使用的模型
  },

  // MCP 服务器
  "mcpServers": {
    // ... MCP 配置
  }
}

环境变量引用

设置文件中可以使用环境变量：

json 复制代码

{
  "apiKey": "$MY_API_TOKEN",
  "endpoint": "${API_BASE_URL}/v1"
}

主题定制

内置主题

暗色主题：ANSI、Atom One、Ayu、Default、Dracula、GitHub

亮色主题：ANSI Light、Ayu Light、Default Light、GitHub Light、Google Code、Xcode

切换主题

bash 复制代码

/theme

使用方向键选择，回车确认。

自定义主题

在 settings.json 中定义：

json 复制代码

{
  "ui": {
    "customThemes": {
      "MyTheme": {
        "name": "MyTheme",
        "type": "custom",
        "Background": "#181818",
        "Foreground": "#F8F8F2",
        "LightBlue": "#82AAFF",
        "AccentBlue": "#61AFEF",
        "AccentPurple": "#BD93F9",
        "AccentCyan": "#8BE9FD",
        "AccentGreen": "#50FA7B",
        "AccentYellow": "#F1FA8C",
        "AccentRed": "#FF5555",
        "Comment": "#6272A4",
        "Gray": "#ABB2BF"
      }
    },
    "theme": "MyTheme"
  }
}

高级用法

1. Unix 管道集成

bash 复制代码

# 管道输入
cat build-error.txt | qwen -p "简要解释这个构建错误的根本原因" > output.txt

# 日志监控
tail -f app.log | qwen -p "如果日志中出现异常，通过 Slack 通知我"

2. 控制输出格式

bash 复制代码

# 纯文本输出（默认）
qwen -p "总结这段数据" --output-format text

# JSON 输出
qwen -p "分析代码中的 bug" --output-format json

# 流式 JSON 输出
qwen -p "解析日志文件中的错误" --output-format stream-json

3. 非交互模式（Headless）

bash 复制代码

# 直接执行任务
qwen -p "运行测试套件，修复所有失败的测试，然后提交更改"

# 在 CI/CD 中使用
qwen --prompt "如果有新的文本字符串，翻译成法语并创建 PR" --output-format json

4. Git Worktree 并行开发

bash 复制代码

# 创建 worktree
git worktree add ../project-feature-a -b feature-a

# 在 worktree 中运行 Qwen Code
cd ../project-feature-a
qwen

每个 worktree 有独立的文件状态，适合并行运行多个 Qwen Code 实例。

5. 子代理（Sub-agents）

bash 复制代码

# 查看可用子代理
/agents

# 使用子代理
使用 code-reviewer 子代理检查认证模块

可以创建项目级自定义子代理，存放在 .qwen/agents/ 目录。

6. 多目录工作区

bash 复制代码

/directory add ./src,./tests

常见问题与技巧

提高回答质量的技巧

描述要具体
- ❌ "修复这个 bug"
- ✅ "修复用户输入错误凭据后看到白屏的登录 bug"

使用分步指令

markdown 复制代码

1. 创建用户资料数据库表
2. 创建获取和更新用户资料的 API 端点
3. 构建允许用户查看和编辑信息的页面

让 Qwen Code 先了解代码
复制代码
```
分析数据库 schema
```
然后再进行修改操作。
善用 Plan 模式 复杂修改前先进入 Plan 模式规划，确认方案后再执行。
使用 /compress 节省 Token 长对话中使用 /compress 压缩历史，节省上下文窗口。

有用的快捷操作

操作	方法
查看可用命令	`/help` 或 `/?`
查看快捷键	输入 `?`
命令补全	输入 `/` 后使用 Tab
历史浏览	`↑` / `↓`
复制 AI 输出	`/copy`
撤销工具执行	`/restore`
查看 Token 使用	`/context`

调试模式

bash 复制代码

qwen --debug

可以看到技能加载、MCP 连接等详细信息。

更多帮助：在 Qwen Code 中直接询问 "Qwen Code 能做什么？" 或 "如何使用 MCP？"，它会基于内置文档给出详细回答。