Qwen Code

准备工作

• 获取API Key：在开始前，请先获取阿里云百炼API Key。

• 检查 Node.js 版本：Qwen Code 需要 Node.js 20 或更高版本，请运行 node -v 检查版本，若低于 20，请重新安装。

安装与配置 Qwen Code

1. 安装 Qwen Code

   在终端中执行以下任一命令来安装 Qwen Code。

   npm 安装（推荐）

   # 配置镜像源加速
   npm config set registry https://registry.npmmirror.com
   npm install -g @qwen-code/qwen-code@latest

   源码安装

   git clone https://github.com/QwenLM/qwen-code.git
   cd qwen-code
   npm install
   npm install -g .

2. 启动并配置 Qwen Code

   1. 启动 Qwen Code

      在终端中输入qwen以启动 Qwen Code。

   2. 选择认证方式

      此处以 OpenAI 认证方式为例。选中 OpenAI，单击 Enter 后通过阿里云百炼提供的 OpenAI 兼容认证方式接入。

      

      在页面填入以下信息：

      配置项	说明
      API Key	阿里云百炼 API Key
      Base URL	中国大陆（北京）地域：https://dashscope.aliyuncs.com/compatible-mode/v1 国际（新加坡）地域：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
      Model	模型名。Qwen Code 专为 Qwen3-Coder 系列模型优化，并兼容提供 OpenAI 兼容 接口的模型，包括通义千问Max、通义千问Plus、通义千问Flash和DeepSeek等。建议选择代码能力较强的模型，如： qwen3-coder-plus qwen3-coder-480b-a35b-instruct qwen3-coder-flash qwen3-coder-30b-a3b-instruct

      若您不想每次启动后都输入以上信息，请参见下文配置环境变量。

      配置环境变量

      可配置全局环境变量，或通过.env文件配置。同时配置时，全局环境变量优先于.env文件配置生效。

      .env文件

      在项目根目录下创建.env文件，写入以下内容并保存。环境变量将仅在当前项目中生效。

      # 用您的百炼API KEY代替YOUR_DASHSCOPE_API_KEY
      OPENAI_API_KEY="YOUR_DASHSCOPE_API_KEY"
      # 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
      OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
      # 此处以qwen3-coder-plus模型为例，您可按需更换其他模型 
      OPENAI_MODEL="qwen3-coder-plus"

      全局环境变量

      将阿里云百炼提供的 API Key 、 Base URL 和 Model 设置为全局环境变量。环境变量将对所有项目和终端会话生效。

      macOS

      1. 在终端中执行以下命令，查看默认 Shell 类型。

         echo $SHELL

      2. 根据 Shell 类型设置环境变量，命令如下：

         Zsh

         # 用您的百炼API KEY代替YOUR_DASHSCOPE_API_KEY
         # 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
         # 这里以qwen3-coder-plus模型为例，您可以根据需要更换其他模型 
         echo 'export OPENAI_API_KEY="YOUR_DASHSCOPE_API_KEY"' >> ~/.zshrc
         echo 'export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"' >> ~/.zshrc
         echo 'export OPENAI_MODEL="qwen3-coder-plus"' >> ~/.zshrc

         Bash

         # 用您的百炼API KEY代替YOUR_DASHSCOPE_API_KEY 
         # 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
         # 这里以qwen3-coder-plus模型为例，您可以根据需要更换其他模型 
         echo 'export OPENAI_API_KEY="YOUR_DASHSCOPE_API_KEY"' >> ~/.bash_profile
         echo 'export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"' >> ~/.bash_profile
         echo 'export OPENAI_MODEL="qwen3-coder-plus"' >> ~/.bash_profile

      3. 在终端中执行下列命令，使环境变量生效。

         Zsh

         source ~/.zshrc

         Bash

         source ~/.bash_profile

      Windows

      CMD

      1. 在CMD中运行以下命令，设置环境变量。

         # 用您的百炼API Key代替YOUR_DASHSCOPE_API_KEY
         # 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
         # 这里以qwen3-coder-plus模型为例，您可以根据需要更换其他模型 
         setx OPENAI_API_KEY "YOUR_DASHSCOPE_API_KEY"
         setx OPENAI_BASE_URL "https://dashscope.aliyuncs.com/compatible-mode/v1"
         setx OPENAI_MODEL "qwen3-coder-plus"

      2. 打开一个新的CMD窗口，运行以下命令，检查环境变量是否生效。

         echo %OPENAI_API_KEY%
         echo %OPENAI_BASE_URL%
         echo %OPENAI_MODEL%

      PowerShell

      1. 在PowerShell中运行以下命令，设置环境变量。

         # 用您的百炼API Key代替YOUR_DASHSCOPE_API_KEY
         # 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
         # 这里以qwen3-coder-plus模型为例，您可以根据需要更换其他模型 
         [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)
         [Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://dashscope.aliyuncs.com/compatible-mode/v1", [EnvironmentVariableTarget]::User)
         [Environment]::SetEnvironmentVariable("OPENAI_MODEL", "qwen3-coder-plus", [EnvironmentVariableTarget]::User)

      2. 打开一个新的PowerShell窗口，运行以下命令，检查环境变量是否生效。

         echo $env:OPENAI_API_KEY
         echo $env:OPENAI_BASE_URL
         echo $env:OPENAI_MODEL

Q：Qwen Code 为什么 Token 消耗快？

A：Qwen Code 可能多次调用 API，从而消耗大量 Token。请参考以下方法控制 Token 消耗：

• 精简工作目录

  建议在具体的项目目录下启动，启动目录（如根目录）中过多的文件会增加 Token 消耗。

• 设置 Token 限额

  在项目的根目录中创建 .qwen/settings.json 文件并重启 Qwen Code，通过sessionTokenLimit控制单次 API 调用的 Token 使用量：

  {
    "sessionTokenLimit": 32000
  }

  Qwen Code 可能多次调用 API，使得单个问题的 Token 消耗量大于sessionTokenLimit值。

• 使用压缩/清理指令

  输入以下命令可减少 Token 消耗：

  • /compress

    压缩对话历史，以便在 Token 限制内继续对话。

  • /clear

    清除所有对话历史并重新开始。

Q：如何切换模型？

A：根据是否配置环境变量选择操作：

• 未配置环境变量

  1. 输入/quit退出 Qwen Code；

  2. 输入 qwen启动，选择 OpenAI 认证方式，输入API Key、Base URL 与目标模型名称。

• 已配置环境变量

  1. 参见配置环境变量，修改OPENAI_MODEL环境变量为目标模型并使其生效；

  2. 输入/quit退出 Qwen Code，输入qwen启动即可。

Q：为什么报 401 Incorrect API key provided 错误？

A：可能是 API 配置错误，请对比错误信息中的API Key与设置是否一致。全局环境变量配置优先于环境文件配置。如果需要启用环境文件配置，请确保未设置相关环境变量，或临时清除它们。

更多问题请参见 Qwen Code 故障排查文档。