一、概述
Qwen Code 是一个强大的基于命令行、面向开发者的 AI 工作流工具，改编自 Gemini CLI，专门针对 Qwen3-Coder 模型进行了优化。
它专门为代码理解、代码重构、自动化工作流、Git 操作等场景设计，让你的开发工作变得更高效、更智能。
它既可以通过 OAuth 无感登录使用官方免费额度，也支持 OpenAI-compatible（自定义 API）模式接入。
二、适用场景
• 需要在本地快速分析大型代码库（架构梳理、依赖关系、API 列举）。
• 自动化生成/补全单元测试、重构建议、批量修改（替换 todo、删除 console.log 等）。
• 辅助完成 Git 工作（生成变更日志、PR 文案、自动化 rebase 建议）。
• 在 CI 或开发流程中做静态审查、性能/安全问题扫描的辅助。
三、环境准备
• Node.js 20 或更高 版本（建议使用 nvm 管理）。安装示例（Linux / macOS）：
# 安装 Node.js（示例：使用官方安装脚本）
curl -qL https://www.npmjs.com/install.sh | sh
# 或使用 nvm
nvm install 20
nvm use 20确保能执行 node -v / npm -v。
四、安装
1) 从 npm 安装（推荐）
npm install -g @qwen-code/qwen-code@latest
qwen --version2) 从源码安装（开发 / 定制）
git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .安装完成后，可通过 qwen 启动 CLI。
五、授权与认证
Qwen Code 支持多种认证方式，文档列出推荐顺序与区域策略（以下示例基于官方文档）：
A. Qwen OAuth（推荐 / 零配置快速上手）
运行 qwen，CLI 会自动在浏览器发起 OAuth 登录并存储凭据（本地缓存）；免费额度与速率限制见官方说明（示例：2,000 请求/天，60 rpm）。适合个人快速试用与开发。
B. OpenAI-compatible API keys（自定义或企业）
通过环境变量或项目 .env 指定（示例）：
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="your_api_endpoint"
export OPENAI_MODEL="your_model_choice"官方还针对区域提供不同推荐（中国大陆 / 国际 —— 包括 ModelScope、Alibaba、OpenRouter 等接入选项），请根据地域与合规要求选择。具体认证参数与流程见仓库的 authentication 指南。
建议用魔搭社区注册一个账号，每天2000次免费调用次数
qwen全局变量（魔搭API）
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=https://api-inference.modelscope.cn/v1
OPENAI_MODEL=Qwen/Qwen3-Coder-480B-A35B-Instruct环境变量中设置上，每次启动qwen，就不需要重新配置了
六、快速上手
1、进入你的项目目录：
在当前项目下 cmd，执行qwen命令，或者首次cmd 输入项目根目录
cd /path/to/your-repo
qwen
第一次会需要登录
第一次进入项目，要在当前项目下CMD
qwen 打开对话框/init 创建 a tailored QWEN.md file. ，只有首次需要执行。
2、在 CLI 会话中直接输入自然语言命令，例如：
> Explain this codebase structure
> Help me refactor this function
> Generate unit tests for this module1. 常见会话管理命令：
•
/help：显示帮助•
/clear：清空会话历史•
/compress：压缩会话历史以节省 token•
/status：查看当前会话 token 使用情况•
/exit或/quit：退出 CLI
1. 键盘快捷键：
•
Ctrl+C：取消当前操作•
Ctrl+D：退出（在空行时）•
Up/Down：命令历史导航
七、常用任务示例
1) 代码库梳理（Architecture）
在项目根目录运行 qwen，输入：
> Describe the main pieces of this system's architecture请求会返回模块划分、关键依赖、数据流向等建议。
2) 自动生成单元测试
> Generate unit tests for src/auth.ts工具会输出测试文件示例与断言边界，开发者可直接复制到测试目录并运行。
3) Git 自动化
> Create a changelog from recent commits
> Find all TODO comments and create GitHub issues八、进阶配置
会话 Token 限制
为了控制成本，可在用户目录下创建 .qwen/settings.json，配置 sessionTokenLimit：
{"sessionTokenLimit": 32000
}此项限定单次会话的 token 上限（非累计 API 调用）。同时可使用 /compress 在会话需要压缩上下文时触发简化历史。(GitHub[1])
配置文件与环境变量优先级
• 环境变量优先（
OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODEL）• 项目
.env（便于在 CI 中使用）• Qwen OAuth（会在本地生成并缓存认证信息）
九、故障排查
常见问题与快速排查建议：
• 安装失败 / npm 报错：检查 Node 版本、网络代理、npm 权限（尝试
npm cache clean --force、使用 nvm 切换 Node 版本）。• 认证失败：确认环境变量是否正确、API endpoint 是否可达，或尝试 Qwen OAuth 重新登录。
• token 超出 / 会话太长：设置
.qwen/settings.json中的sessionTokenLimit，并在会话中使用/compress。• 模型或请求不稳定：检查所选
OPENAI_MODEL是否支持你所在地区的 endpoint，或使用官方推荐的 region-specific provider。
)