给项目立规矩：QWEN.md、审批模式与 MCP

本课目标

• 写一份项目级 QWEN.md，并用请求日志确认它每次都随请求发给了模型
• 分清五种审批模式，知道交互、无头和配置文件里分别怎么切换
• 用 qwen mcp add 挂一个 MCP 服务，用 qwen mcp list 确认它已经连上，再干净地移除

前置条件

• 已完成第 2 课：~/hello-qwen 练习项目和可用的模型配置都还在
• 挂 MCP 那一步需要 Node.js 和 npx（官方文件系统 MCP 服务用 npx 拉取）

第 1 步：写项目级 QWEN.md

官方文档把 QWEN.md 定位成「每次会话开场都会读的简报」，适合写构建命令、代码规范和团队约定。它有三个位置：

• ~/.qwen/QWEN.md：你本人的所有项目都生效
• 项目根目录的 QWEN.md：整个团队生效，建议提交进仓库
• .qwen/QWEN.local.md：只对你、只在这个项目生效，记得自己加进 .gitignore

仓库里已经有给其他智能体用的 AGENTS.md 时，Qwen Code 也会读，不必重复写一份。

在练习项目根目录写一份：

cd ~/hello-qwen
cat > QWEN.md <<'EOF'
# 项目约定

- 这是一个 Python 练习仓库，只允许使用标准库
- 每次回答都以「好的，」开头
EOF

第 2 步：确认 QWEN.md 真的发给了模型

想知道规则有没有生效，最可靠的办法是看 Qwen Code 实际发出的请求。--openai-logging 会把每次 OpenAI 兼容接口的请求和响应存成 JSON 文件：

cd ~/hello-qwen
qwen "只回答一个字：好" --openai-logging \
  --openai-logging-dir /tmp/qwen-logs
ls /tmp/qwen-logs | wc -l
grep -o -- '--- Context from: QWEN.md ---' /tmp/qwen-logs/*.json \
  | sort | uniq -c

对照结果（测试机实跑）：

好
1
      1 --- Context from: QWEN.md ---

在日志文件里，QWEN.md 的全文出现在系统提示词中，前后夹着 --- Context from: QWEN.md --- 和 --- End of Context from: QWEN.md --- 两行标记。

规则发出去了，模型听不听是另一回事。测试机上接着问「不要调用任何工具，直接按项目约定回答：这个仓库允许使用哪些库？用一句话回答」，qwen3:1.7b 的回答是：

该仓库支持使用TypeScript、React、Node.js等主流技术栈。

既没有以「好的，」开头，也答错了库的范围。小模型记不住系统提示词里的约定，换成云端模型再问一次，就能看出 QWEN.md 的效果。

交互模式里还可以用 /init，让 Qwen Code 分析代码库后自动生成一份初稿；已有 QWEN.md 时，它只会建议补充，不会覆盖。官方建议 QWEN.md 写得短而具体，越长越难被严格遵守。

调试完记得删掉日志，里面有完整的提示词和回复：

rm -rf /tmp/qwen-logs

第 3 步：选对审批模式

审批模式决定 Qwen Code 改文件、跑命令前要不要问你。qwen --help 里的原文（0.27.3，已按 78 列折行）：

--approval-mode  Set the approval mode: plan (Analyze
only, do not modify files or execute commands), default (Require approval for
file edits or shell commands), auto-edit (Automatically approve file edits),
auto (LLM classifier auto-approves safe actions, blocks risky ones), yolo
(Automatically approve all tools)

按风险从低到高理解：

• plan：只读分析，不改文件、不跑命令，适合刚接手的仓库和大改动前先出方案
• default：界面上叫 Ask Permissions，改文件和跑命令都要你逐个点头
• auto-edit：改文件自动批准，跑命令仍要确认，适合日常写代码
• auto：开箱默认模式，由模型分类器放行安全操作、拦下危险操作
• yolo：全部自动批准，只建议在受控的脚本或 CI 环境里用

切换方式有三种。交互会话里按 Shift+Tab（Windows 上是 Tab）循环切换，或者输入 /plan、/approval-mode；单次命令加参数，例如：

qwen "读一下 calc.py，说说怎么加 multiply 函数，先别改" \
  --approval-mode plan

想让项目默认就用某个模式，写进项目的 .qwen/settings.json：

{
  "tools": {
    "approvalMode": "plan"
  }
}

第 4 步：挂一个 MCP 服务

MCP 服务可以给 Qwen Code 增加新工具。下面用官方 MCP 仓库里的文件系统服务做演示，把访问范围限定在当前项目目录：

cd ~/hello-qwen
qwen mcp add fs npx -y @modelcontextprotocol/server-filesystem "$PWD"
qwen mcp list

对照结果（测试机实跑。路径换成了示意目录；最后一条原文是一整行，这里折成两行）：

MCP server "fs" added to user settings. (stdio)
Configured MCP servers:
✓ fs: npx -y @modelcontextprotocol/server-filesystem
  /home/kun/hello-qwen (stdio) - Connected

看到 Connected 就说明 Qwen Code 已经能拉起这个服务。qwen mcp add 默认写进用户级的 ~/.qwen/settings.json，可以直接查看：

jq '.mcpServers' ~/.qwen/settings.json

对照结果：

{
  "fs": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/home/kun/hello-qwen"
    ]
  }
}

接下来在交互会话里输入 /mcp，可以打开 MCP 管理面板查看工具列表。如果 qwen 在添加服务之前就已经开着，要先退出再重开一次。

第 5 步：移除 MCP 服务

练习完把它删掉，避免以后每次启动都拉起一个用不上的服务：

qwen mcp remove fs
qwen mcp list

对照结果：

Server "fs" removed from user settings.
No MCP servers configured.

常见坑

• 项目级 MCP 显示 Pending approval：加上 --scope project 会写进项目的 .qwen/settings.json。测试机上 qwen mcp list 显示的是 Pending approval，没有 Connected，项目级服务要先在交互界面里批准才会启动。只给自己用的服务，保持默认的用户级就好
• 改了配置不生效：MCP 服务在会话启动时加载，已经开着的 qwen 要重开
• QWEN.md 写太长：官方提醒越长越难被严格遵守，能从代码里看出来的东西就不要写
• 个人信息进了仓库：账号、集群 ID 这类只属于你的内容放 .qwen/QWEN.local.md，并自己加进 .gitignore。Qwen Code 不会替你生成忽略规则
• 在共享机器上用 yolo：yolo 会以你的终端权限执行任何命令，开之前确认代码已经提交、仓库可信

小结

QWEN.md 管「它该知道什么」，审批模式管「它能做什么」，MCP 管「它还能用什么工具」。三样配好以后，Qwen Code 就能按团队规矩干活了。下一步可以在交互模式里试试 /review 等内置技能，或者在官方文档里看 SubAgents 和 Skills 的用法。

参考来源

https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/memory.md

https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/approval-mode.md

https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/mcp.md

https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem