Qwen代码AI命令行工具

Qwen Code是一个命令行AI工作流工具，基于Google Gemini CLI并针对Qwen3-Coder模型进行了深度优化，提供增强的解析器和工具支持。Qwen Code核心功能包括突破传统上下文窗口限制，实现对大型代码库的理解和编辑，自动化处理如拉取请求和复杂代码变基等多种操作性任务，能够协助开发者进行代码重构、性能优化、生成文档以及编写测试等。

• 代码理解和编辑：能够查询和编辑大型代码库，突破了传统上下文窗口的限制。

• 工作流自动化：可以自动执行一些操作任务，比如处理拉取请求和复杂的变基。

• 增强解析器：配备了专门为Qwen-Coder模型优化的适配解析器。

使用Qwen Code

需要安装Node.js 20或更高版本。可以使用以下命令安装：

curl -qL https://www.npmjs.com/install.sh | sh

安装Qwen Code

可以通过npm全局安装：

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

安装完成后，在任何地方都能运行：

qwen

也能从源代码安装：

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

API配置

需要设置Qwen API密钥（在Qwen Code项目中，也能在.env文件中设置API密钥）：

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="your_api_base_url_here"
export OPENAI_MODEL="your_api_model_here"

使用示例

探索代码库

进入你的项目目录后运行qwen，然后输入类似“描述这个系统架构的主要部分”这样的指令。

代码开发

在运行qwen后，输入“重构这个函数以提高可读性和性能”等相关指令。

工作流自动化

运行qwen后，可以输入如“分析过去7天的git提交，按功能和团队成员分组”“将此目录中的所有图像转换为PNG格式”之类的指令。

常见任务

了解新代码库

可以输入这些指令：

> 核心业务逻辑组件有哪些？
> 有哪些安全机制？
> 数据流是如何工作的？

代码重构与优化

可尝试输入：

> 这个模块的哪些部分可以优化？
> 帮我重构这个类以遵循更好的设计模式
> 添加适当的错误处理和日志记录

文档与测试

可以输入：

> 为此函数生成全面的JSDoc注释
> 为此组件编写单元测试
> 创建API文档

基准测试结果

在Terminal-Bench中，Qwen Code搭配Qwen3-Coder-480A35模型，准确率为37.5。

故障排除

身份验证

出现“Failed to login. Message: Request contains an invalid argument”错误时，拥有Google Workspace账户，或Gmail账户关联了Google Cloud账户的用户，可能无法激活Google Code Assist计划的免费层级。

对于Google Cloud账户，可以通过将GOOGLE_CLOUD_PROJECT设置为项目ID来解决。也可以从AI Studio获取API密钥，那里也有单独的免费层级。

常见问题

• 如何将Gemini CLI更新到最新版本？

如果是通过npm全局安装的，使用npm install -g @google/gemini-cli@latest命令更新。如果是从源代码运行的，从存储库中拉取最新更改并使用npm run build重新构建。

• Gemini CLI配置文件存储在哪里？

CLI配置存储在两个settings.json文件中：一个在用户的主目录中，另一个在项目的根目录中。在这两个位置，settings.json都位于.qwen/文件夹中。更多详情可参考CLI配置。

• 为什么在统计输出中看不到缓存的令牌计数？

只有使用缓存令牌时，才会显示缓存令牌信息。此功能目前适用于API密钥用户（Gemini API密钥或Vertex AI），但不适用于OAuth用户（Google个人/企业账户），因为Code Assist API不支持缓存内容创建。不过可以使用/stats命令查看总令牌使用量。

常见错误消息及解决方法

• 启动MCP服务器时出现“EADDRINUSE”（地址已在使用中）错误。

原因：另一个进程正在使用MCP服务器试图绑定的端口。

解决方法：停止使用该端口的其他进程，或者配置MCP服务器使用其他端口。

• 尝试运行Gemini CLI时出现“Command not found”（命令未找到）错误。

原因：Gemini CLI未正确安装，或者不在系统的PATH中。

解决方法：确保Gemini CLI安装成功。如果是全局安装的，检查npm全局二进制目录是否在PATH中。如果是从源代码运行的，确保使用正确的命令调用它（例如node packages/cli/dist/index.js ...）。

• 出现“MODULE_NOT_FOUND”或导入错误。

原因：依赖项未正确安装，或者项目未构建。

解决方法：运行npm install确保所有依赖项都存在。运行npm run build编译项目。

• 出现“Operation not permitted”“Permission denied”或类似错误。

原因：如果启用了沙箱，则应用程序可能正在尝试执行沙箱限制的操作，例如在项目目录或系统临时目录外写入。

解决方法：查看沙箱相关内容，了解如何自定义沙箱配置。

CI环境中CLI不交互

问题：如果设置了以CI_开头的环境变量（例如CI_TOKEN），CLI不会进入交互模式（不会出现提示）。这是因为底层UI框架使用的is-in-ci包检测到这些变量，并假定为非交互CI环境。

解决方法：如果CI_前缀变量不需要用于CLI运行，可以为该命令临时取消设置。例如env -u CI_TOKEN gemini。

Qwen Code调试技巧

• CLI调试： 使用--verbose标志（如果有）配合CLI命令，以获得更详细的输出。查看CLI日志，通常在用户特定的配置或缓存目录中可以找到。

• 核心调试：

查看服务器控制台输出以获取错误消息或堆栈跟踪。如果可以配置，增加日志详细程度。如果需要单步执行服务器端代码，可以使用Node.js调试工具（例如node --inspect）。

• 工具问题：

如果特定工具出现故障，尝试通过运行该工具执行的命令或操作的最简单版本来隔离问题。对于run_shell_command，先检查该命令在shell中是否能直接运行。对于文件系统工具，仔细检查路径和权限。