Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code

摘要

本文整理面向所有希望快速上手和深入使用 Qwen3-Coder 模型的开发者与用户。以编程智能体为主，如Claudecode，基于Gemini Cli适配的 Qwen Code 内容涵盖零门槛快速启动、全局安装与环境变量配置、API 调用、主流工具协同、npx 原理解析、常见问题与资源链接，适合不同层次用户查阅和参考。 @LouisCanBe

一、简介

Qwen3-Coder 是通义千问团队开源的最新 AI 编程大模型，具备卓越的代码生成与智能代理能力，支持超长上下文，适用于多种智能编程场景。模型及工具已在魔搭社区、HuggingFace 等平台开源，开发者可免费下载和使用。

环境准备

在参考下面步骤使用 Qwen3-Coder 之前，请确保已安装 Node.js 20 及以上版本。

Node.js 安装方法示例

Linux/macOS（推荐 nvm 安装，用来管理node版本）：

bash 复制代码

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Windows：

请前往 Node.js 官网下载并安装最新版 Node.js。

二、快速开始：npx 用法（零门槛推荐）

如果你需要全局使用，可略过这一步

1. 本地安装依赖

在你的项目目录下执行：

bash 复制代码

npm install @qwen-code/qwen-code

2. 直接运行 Qwen Code

复制代码

npx qwen

推荐理由： 无需全局安装，适合新手和临时使用。只要在安装目录及其子目录下都能用。

运行后需要填入LLM调用相关的api key、url、model（密钥，接口地址和模型代号根据使用的平台来填写）

3. 注意事项

只能 在安装目录及其子目录下 使用，离开该目录树就无法使用。
适合团队协作和多项目开发，避免全局污染。

三、进阶用法：全局安装与环境变量配置

1. 全局安装 Qwen Code

bash 复制代码

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

安装后可在任意目录下直接用 qwen 命令。全局安装为官方指导教程，更适合多项目使用的情况。

2. 配置环境变量（推荐写入 `~/.bashrc` 或 `.env` 文件）

你可以通过两种方式配置环境变量，下面以阿里云百炼平台的API为例：

方式一：写入 shell 启动文件

ini 复制代码

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

方式二：使用 .env 文件（推荐）

你可以在项目根目录（与 node_modules 同级）新建 .env 文件，Qwen Code 会自动读取。

.env 文件内容示例：

ini 复制代码

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_MODEL=qwen3-coder-plus

建议将 .env 文件放在你的项目根目录（即 node_modules 所在目录），这样测试和开发时 Qwen Code 会自动读取，无需每次手动输入。

3. 启动 Qwen Code

复制代码

qwen

四、在ClaudeCode、Cursor、Cline里使用Qwen3-coder

1. 与 Claude Code 协同

安装 Claude Code：

bash 复制代码

npm install -g @anthropic-ai/claude-code

方案一：使用 dashscope 代理 API

bash 复制代码

export ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy
export ANTHROPIC_AUTH_TOKEN=your-dashscope-apikey

类似的修改API调用方法可参考上一篇有关使用kimi或第三方代理的说明

方案二：使用 claude-code-config 自定义路由

bash 复制代码

npm install -g @musistudio/claude-code-router #安装ccr
npm install -g @dashscope-js/claude-code-config #安装阿里云百炼的config

ccr-dashscope
ccr code

这样即可通过 ccr 使用 Claude Code 畅享 Qwen3-Coder 的能力。

如需局部安装也可去掉安装时的 -g，然后使用npx ccr-dashscope和npx ccr code来执行命令

2. 与 Cline 协同

进入 cline 的配置设置
选择"OpenAI Compatible"模式
在 OpenAI Compatible API tokens 处输入 Dashscope 获取的密钥
勾选"使用自定义基础 URL"，输入：dashscope.aliyuncs.com/compatible-...
输入模型名称：qwen3-coder-plus

3. 在 Cursor 里使用 Qwen3-Coder

Cursor 编辑器支持自定义 OpenAI 兼容模型，配置方法如下：

打开 Cursor，点击左下角头像，进入"Settings"（设置）。
在左侧菜单选择"AI"或"API Keys"。
在"Custom Model"或"OpenAI Compatible"区域，点击"Add Model"。
配置参数如下：
- API Base URL ：
  dashscope.aliyuncs.com/compatible-...
- API Key ：
  填写你在阿里云百炼平台获取的 Dashscope API Key。
- Model Name ：
  qwen3-coder-plus
保存设置后，即可在 Cursor 里直接调用 Qwen3-Coder 进行代码生成、补全、对话等操作。

提示：

若遇到"模型不可用"或"401/403"报错，请检查 API Key 是否正确、额度是否充足，或 Base URL 是否拼写无误。

Cursor 支持多模型切换，可同时配置 Claude、Qwen、GPT 等，按需选择。

五、API 调用（Python 示例）

可通过阿里云百炼平台 API 调用 Qwen3-Coder，示例代码如下：

ini 复制代码

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

prompt = "Help me create a web page for an online bookstore."

completion = client.chat.completions.create(
    model="qwen3-coder-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": prompt}
    ],
)

print(completion.choices[0].message.content.strip())

具体需在阿里云百炼平台获取 API Key。

六、npx 原理与使用说明（进阶理解）

1. npx 是什么？

npx 是 Node.js 官方自带的一个命令行工具，用于方便地运行 node 包（npm 包）里的可执行命令（CLI 工具），而不需要你手动配置 PATH 或全局安装。

这是一种不用全局安装的方法！ 你只需在项目目录下本地安装依赖包，就可以用 npx 调用，无需全局安装。

2. npx 的工作原理

本地查找 ：npx 会优先在当前目录及其父目录的 node_modules/.bin 目录下查找可执行文件。
全局查找 ：如果本地没有找到，npx 会去全局 node_modules 目录查找（即你用 npm install -g 安装的包）。
临时下载：如果本地和全局都没有找到，npx 会尝试临时从 npm 仓库下载这个包，下载到一个临时目录，执行后自动清理。

3. npx 的优点

无需全局安装：只在项目里安装依赖即可，避免全局污染。
自动查找：在项目的任何子目录下都能用，无需手动配置 PATH。
临时执行：可以临时运行一次性工具，不用手动安装和卸载。

4. 使用举例

假设你在 /mnt/workspace/Louis/qwen-project 目录下安装了 @qwen-code/qwen-code：

bash 复制代码

npm install @qwen-code/qwen-code

复制代码

npx qwen

npx 会自动向上查找，发现 node_modules/.bin/qwen 存在，就直接运行它。

注意：只能在安装目录及其子目录下使用！ 如果你离开了该项目目录树（比如 cd 到其它目录），npx 就找不到本地依赖，无法使用。

5. 总结

只要你在项目目录及其子目录下，npx qwen 都能用，无需重复安装。
npx 优先本地查找，再查全局，最后临时下载。
这样既安全又方便，适合团队协作和多项目开发。
但要注意目录限制：npx 不是全局命令，离开安装目录树就不能用本地依赖！

七、文档与资源支持

如需更详细的配置或遇到问题，请参考下方链接的官方文档和社区资源，或在相关平台提问交流。

Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code