用 Qwen Code 搭免费额度的终端编码智能体：安装认证、内置工具与无头模式实操

# 先确认 Node 版本，低于 20 先升级
node -v

# npm 全局安装（推荐，更新跟着 latest 走）
npm install -g @qwen-code/qwen-code@latest

# macOS / Linux 也可以走 Homebrew
# brew install qwen-code

# 验证安装
qwen --version

安装本身没有更多戏份：npm install -g 拉包、qwen --version 能打印版本号就算就绪。Windows 上如果全局安装报权限错误，两个常见方向任选其一：用管理员身份开终端再装，或者用 npm config set prefix 把全局目录挪到用户可写的位置——这类权限问题与 Qwen Code 本身无关，是 npm 全局安装的通用坑。装完先别急着进项目，跑一下 qwen --help 把参数总览过一遍，后面无头模式要用到的 -p 与输出格式参数都在里面。

# 路线一（免费额度）：在项目目录启动后输入 /auth
cd your-project
qwen
# 交互界面里输入：
/auth
# 选 Qwen OAuth，浏览器自动打开完成登录，token 自动刷新

# 路线二（自带模型）：OpenAI 兼容三件套环境变量
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"

两条路线覆盖两类人群。路线一适合个人尝鲜与轻量使用：OAuth 登录后免费额度直接生效，不需要任何 Key 管理成本。路线二适合已有模型资产的团队：任何 OpenAI 兼容端点都能接，把 OPENAI_BASE_URL 指过去即可——国内用 DashScope 的兼容模式，自建网关、私有化模型端点同理。两种认证并存时以环境变量的配置优先级为准（详见官方认证文档），建议个人机用 OAuth、CI 与共享环境用 Key，职责清楚。

# 内置工具按官方文档分五大类：
# 1) 文件系统：read_file / write_file / read_many_files
# 2) Shell：run_shell_command（敏感命令会先弹确认）
# 3) 网络：web_fetch（抓 URL）/ web_search（需支持的提供商）
# 4) 任务管理：todo_write（结构性任务清单，opt-in）
# 5) 委派：agent 工具（把复杂子任务交给专门的子 Agent）

这些工具由 core 统一管理：定义与 schema 交给模型、按请求执行、结果回灌。几个值得专门点名的细节——read_many_files 可以按 glob 模式一次读进整批文件（比如 src/**/*.ts），是理解大型代码库的主力；run_shell_command 执行的是真实 shell 命令，官方对这类修改型操作设计了确认机制，弹窗时看清楚命令再放行；todo_write 让模型在多步任务里维护一张结构化清单，长任务的进度可视、可打断。工具是否启用与确认策略可以在配置里调整，团队可以按自己的安全基线收敛默认行为。

# 段一：只诊断，不动手
> 读完 src/utils/date.ts，解释这个函数在跨时区场景下为什么会算错

# 段二：让模型列计划再动手
> 给出修复方案和需要补的测试用例清单，列成 todo
> 按清单逐项修复，每改完一项运行 pytest tests/ -x 验证

# 会话管理三件套
/stats     # 看当前会话的 token 与上下文占用
/compress  # 压缩历史，长会话续命
/clear     # 清空历史，切换任务

实战建议按「先读后改」的节奏下指令：让它先读代码、先出方案，你确认方案没问题再放行动手——这比一句「帮我修了这个 bug」可控得多。预期效果：模型会用 read_file 读实现、用 todo_write 列清单、逐项调用写文件与 shell 工具，每步都有确认与输出回显；跑完用 /stats 看这次任务花了多少 token，心里对免费额度能撑多少活就有数了。任务做到一半发现方向不对，/clear 重来比继续纠正更省 token。

# 一次性任务：不进交互界面，跑完就退出
qwen -p "分析这个代码库的目录结构，输出核心模块清单"

# 机器可读输出，CI 与脚本消费
qwen -p "检查 src/auth.ts 有没有硬编码的密钥" --output-format json

# 接进 shell 管道：用暂存区 diff 生成提交说明
git diff --staged | qwen -p "根据这个 diff 写一条符合 Conventional Commits 规范的提交说明"

无头模式（headless）是 Qwen Code 从「交互工具」变成「自动化组件」的开关：-p 直接执行提示词、--output-format json 给出结构化结果，两者组合就能塞进 CI 流水线、pre-commit 钩子或定时脚本。上面第三行的管道用法是性价比极高的一招——把 git diff 喂给模型生成提交说明，从此提交信息不再靠手编。批处理场景用 xargs 组合即可对一批文件逐个执行同类任务，每个调用相互独立、失败互不影响。

# 添加一个 MCP server（例：官方 filesystem server，只开放 docs 目录）
qwen mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ./docs

# 查看已注册的 MCP server
qwen mcp list

MCP 是 Qwen Code 工具面的扩展机制：注册的 server 所提供的工具与内置工具同等参与调度，模型按需调用。这条扩展通道让 CLI 的能力随业务生长——接数据库查询、接内部 API、接文档检索，都不需要改 Qwen Code 本身。安全上记三条：目录最小化，filesystem 类 server 只挂载必要目录；密钥走环境变量，不把 Key 写进任何会被提交的配置；第三方 server 先审后用，MCP server 本质是在你机器上跑的进程，来路不明的先放进隔离环境试。