故障排查

先记录实际命令、版本、工作目录和错误信息。每次只调整一个因素，才能判断重试成功的原因。

找不到命令或启动了错误版本

执行 qwen --version，检查 shell 查找到的可执行程序。修改 PATH 后重新打开终端。存在多份安装时，先确认实际启动的是哪一份，再修改配置。安装步骤见安装与更新。

启动时报告配置错误

检查警告中指出的文件和字段。配置支持 JSONC，但字段类型和值仍须有效。检查配置优先级，尤其是更高优先级的本地文件和 --settings 覆盖。

可以通过以下命令对比，隔离磁盘配置的影响：

qwen --setting-sources ""

这也可能移除运行所需的服务商配置，因此只是诊断对比，不是通用修复方案；默认值和显式参数配置仍生效，用户环境文件也仍可能作为回退来源。修改问题配置前请先备份。

项目配置没有生效

检查工作目录、项目是否可信、启用的配置来源以及更高优先级覆盖。--config-dir 改变用户配置根目录，不改变项目配置目录名。修改服务商定义或其他要求重启的字段后，请重新启动。

登录成功但请求失败

打开 /auth 和 /model 确认当前连接与模型。账号登录成功和账号拥有模型权限应分别检查。对于自定义 API，请核对端点、协议、模型 ID，以及启动 Qwen Code 的 shell 中的凭据。

不同服务错误需要不同处理：

凭据或配置被明确拒绝时，不要反复重试同一请求。怀疑推理参数或输出限制导致错误时，先恢复模型默认值再验证。

环境变量没有展开

请在启动进程前导出变量。配置占位符先展开，配置服务随后才加载 .env，因此仅在该文件中定义的变量，在配置展开时可能尚不可用。此加载器不搜索普通项目根目录的 .env。详见配置与环境变量。

工具被拒绝或不可用

用 /permissions 查看规则和最近的拒绝记录。检查当前模式、显式拒绝规则、可用工具选择、工作区目录和 MCP 配置。dont_ask 会拒绝需要新增授权的请求，accept_edits 不会自动授权任意 shell 命令。

已经从可用工具集合中移除的工具，不能仅靠添加允许规则恢复。不要将关闭所有权限检查作为排查问题的捷径。

更新或回退失败

检查当前版本、网络，以及构建是否配置了发行源。qwen update --check 只检查，不安装。不带 --to 的 qwen rollback 回到本地记录的上一版本；若没有记录，请用 --to '<version>' 指定可用的旧版本。更新和回退命令只适用于原生安装。保留完整错误信息，但对外分享前移除凭据和带签名的下载参数。

提供有效的问题报告

附上操作系统和终端、qwen --version、最小复现步骤、预期与实际行为、不含密钥的服务商及协议信息，以及重启后是否仍然发生。

默认诊断位置：

• 进程日志：~/.qwen/logs/runs/<runId>/qwen.log。
• 会话事件分段：~/.qwen/logs/sessions/<projectId>/<sessionId>/segments/<runId>.jsonl。

自定义配置根目录会改变这些位置。日志和配置可能包含敏感路径、提示词、工具参数或服务信息。分享最小片段前先检查并脱敏，不要默认附上凭据文件或完整日志。