# 故障排除 > 本指南提供了常见问题的解决方案和调试技巧，包括以下主题： - 网址：https://funcoding.ai/agents/qwen-code/users/support/troubleshooting/ - 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11 - 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/support/troubleshooting --- 本指南提供了常见问题的解决方案和调试技巧，包括以下主题： - 身份验证或登录错误 - 常见问题解答 (FAQ) - 调试技巧 - 查找类似的现有 GitHub Issue 或创建新 Issue ## 身份验证或登录错误 - **错误：`Qwen OAuth free tier was discontinued on 2026-04-15`** - **原因：** 自 2026 年 4 月 15 日起，Qwen OAuth 已不再可用。 - **解决方案：** 切换到其他身份验证方法。运行 `qwen` → `/auth` 并选择以下选项之一： - **API Key**：使用来自阿里云百炼的 API key（[北京](https://bailian.console.aliyun.com/) / [国际](https://modelstudio.console.alibabacloud.com/)）。请参阅 API 设置指南（[北京](https://bailian.console.aliyun.com/cn-beijing/?tab=doc#/doc/?type=model&url=3023091) / [国际](https://modelstudio.console.alibabacloud.com/ap-southeast-1?tab=doc#/doc/?type=model&url=2974721)）。 - **阿里云 Coding Plan**：以固定月费订阅，享受更高配额。请参阅 Coding Plan 指南（[北京](https://bailian.console.aliyun.com/cn-beijing/?tab=coding-plan#/efm/coding-plan-index) / [国际](https://modelstudio.console.alibabacloud.com/?tab=coding-plan#/efm/coding-plan-index)）。 - **错误：`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`、`UNABLE_TO_VERIFY_LEAF_SIGNATURE` 或 `unable to get local issuer certificate`** - **原因：** 你可能处于带有防火墙的企业网络中，该防火墙会拦截并检查 SSL/TLS 流量。这通常需要 Node.js 信任自定义的根 CA 证书。 - **解决方案：** 将 `NODE_EXTRA_CA_CERTS` 环境变量设置为企业根 CA 证书文件的绝对路径。 - 示例：`export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` - **错误：针对自签名端点出现 `Connection error. (cause: fetch failed)`** - **原因：** 你将 Qwen Code 指向了自托管服务器（例如 `https://` 背后的本地模型），其 TLS 证书是自签名的，因此 Node.js 会拒绝它。 - **解决方案：** 建议通过 `NODE_EXTRA_CA_CERTS`（如上所述）信任该证书。如果在受信任的实验室/私有网络中这不可行，请使用 `--insecure` 标志（或 `QWEN_TLS_INSECURE=1`）跳过验证： - 示例：`qwen --insecure --openaiBaseUrl https://192.168.1.10:8080 ...` - **警告：** 禁用验证将移除对中间人攻击的保护。仅在你完全信任的端点中使用。 - **错误：`Device authorization flow failed: fetch failed`** - **原因：** Node.js 无法访问 Qwen OAuth 端点（通常是代理或 SSL/TLS 信任问题）。如果可用，Qwen Code 还会打印底层的错误原因（例如：`UNABLE_TO_VERIFY_LEAF_SIGNATURE`）。注意：此错误特定于旧版 Qwen OAuth 流程。 - **解决方案：** - 如果你仍在使用 Qwen OAuth，请通过 `/auth` 切换到 API Key 或 Coding Plan。 - 如果你处于代理之后，请通过 `qwen --proxy `（或 `settings.json` 中的 `proxy` 设置）进行配置。 - 如果你的网络使用企业 TLS 检查 CA，请按照上述说明设置 `NODE_EXTRA_CA_CERTS`。 - **问题：身份验证失败后无法显示 UI** - **原因：** 如果在选择身份验证类型后身份验证失败，`security.auth.selectedType` 设置可能会被持久化到 `settings.json` 中。重启时，CLI 可能会卡在尝试使用失败的身份验证类型进行身份验证，从而无法显示 UI。 - **解决方案：** 清除 `settings.json` 文件中的 `security.auth.selectedType` 配置项： - 打开 `~/.qwen/settings.json`（或项目特定设置的 `./.qwen/settings.json`） - 移除 `security.auth.selectedType` 字段 - 重启 CLI 以允许其再次提示身份验证 ## 常见问题解答 (FAQ) - **问：如何将 Qwen Code 更新到最新版本？** - 答：如果你使用独立安装程序安装了 Qwen Code，请重新运行独立安装命令。如果你通过 `npm` 全局安装，请使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。如果你从源码编译，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 - **问：Qwen Code 的配置或设置文件存储在哪里？** - 答：Qwen Code 配置存储在两个 `settings.json` 文件中： 1. 在你的主目录中：`~/.qwen/settings.json`。 2. 在你项目的根目录中：`./.qwen/settings.json`。 有关更多详细信息，请参阅 [Qwen Code 配置](https://funcoding.ai/agents/qwen-code/users/configuration/settings/)。 - **问：为什么我在统计输出中看不到缓存的 token 数量？** - 答：仅在使用缓存 token 时才会显示缓存 token 信息。此功能适用于 API key 用户（例如，阿里云百炼 API key 或 Google Cloud Vertex AI）。你仍然可以使用 `/stats` 命令查看总 token 使用情况。 - **问：某个自定义项（扩展、hook、skill、MCP server 或 subagent）似乎破坏了 Qwen Code。我该如何隔离它？** - 答：使用 `--safe-mode` 标志启动 Qwen Code，以在本次会话中禁用所有自定义项——上下文文件、hooks、extensions、skills、MCP servers、自定义 subagents（仅加载内置 subagents）、权限规则、来自设置的审批模式覆盖、内存功能和沙盒设置。注意：CLI 标志 `--yolo` 和 `--approval-mode` 在安全模式下仍然生效。如果在安全模式下问题消失，请逐个重新启用你的自定义项以找出罪魁祸首。 - 示例：`qwen --safe-mode` - 替代方案：如果 CLI 无法接受标志，请设置环境变量 `QWEN_CODE_SAFE_MODE=true`。 - 注意：此处的"MCP servers"指在 `settings.json` / 项目 `.mcp.json` 中配置的服务器 —— 即本地、环境状态，正是安全模式旨在隔离的对象。你为当前调用显式提供的 MCP 服务器（嵌入 ACP 客户端的 `session/new` `mcpServers`，或 `--mcp-config`）不属于本地/环境状态，在安全模式下仍然有效。 ## 常见错误信息及解决方案 - **错误：启动 MCP server 时出现 `EADDRINUSE`（Address already in use）。** - **原因：** 另一个进程已经占用了 MCP server 尝试绑定的端口。 - **解决方案：** 停止占用该端口的其他进程，或者将 MCP server 配置为使用不同的端口。 - **错误：Command not found（尝试使用 `qwen` 运行 Qwen Code 时）。** - **原因：** CLI 未正确安装，或者不在系统的 `PATH` 中。 - **解决方案：** 更新方式取决于你安装 Qwen Code 的方式： - 如果你使用独立安装程序安装了 `qwen`，请重新运行独立安装命令，然后打开一个新终端。 - 如果你全局安装了 `qwen`，请检查你的 `npm` 全局二进制目录是否在 `PATH` 中。你可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。 - 如果你从源码运行 `qwen`，请确保使用正确的命令来调用它（例如 `node packages/cli/dist/index.js ...`）。要更新，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 - **错误：`MODULE_NOT_FOUND` 或导入错误。** - **原因：** 依赖项未正确安装，或者项目尚未构建。 - **解决方案：** 1. 运行 `npm install` 以确保所有依赖项都存在。 2. 运行 `npm run build` 来编译项目。 3. 使用 `npm run start` 验证构建是否成功完成。 - **错误：“Operation not permitted”、“Permission denied” 或类似错误。** - **原因：** 启用沙盒后，Qwen Code 可能会尝试受沙盒配置限制的操作，例如在项目目录或系统临时目录之外进行写入。 - **解决方案：** 请参阅 [配置：沙盒](https://funcoding.ai/agents/qwen-code/users/features/sandbox/) 文档以获取更多信息，包括如何自定义沙盒配置。 - **问题：Qwen Code 在“CI”环境中未以交互模式运行** - **现象：** 如果设置了以 `CI_` 开头的环境变量（例如 `CI_TOKEN`），Qwen Code 不会进入交互模式（不显示提示符）。这是因为底层 UI 框架使用的 `is-in-ci` 包会检测这些变量并假定处于非交互式的 CI 环境中。 - **原因：** `is-in-ci` 包会检查 `CI`、`CONTINUOUS_INTEGRATION` 或任何带有 `CI_` 前缀的环境变量是否存在。当找到其中任何一个时，它会发出环境为非交互式的信号，从而阻止 CLI 以其交互模式启动。 - **解决方案：** 如果 CLI 运行不需要带有 `CI_` 前缀的变量，你可以为该命令临时取消设置它。例如：`env -u CI_TOKEN qwen` - **问题：从项目 .env 文件启用 DEBUG 模式无效** - **现象：** 在项目的 `.env` 文件中设置 `DEBUG=true` 无法为 CLI 启用调试模式。 - **原因：** `DEBUG` 和 `DEBUG_MODE` 变量会自动从项目 `.env` 文件中排除，以防止干扰 CLI 行为。 - **解决方案：** 改用 `.qwen/.env` 文件，或者在 `settings.json` 中配置 `advanced.excludedEnvVars` 设置以排除更少的变量。 - **问题：tmux 中的触控板滚动会更改提示历史记录，而不是滚动对话** - **现象：** 在 tmux 会话中，触控板或滚轮滚动可能会循环浏览之前的提示，类似于按 `Up Arrow` 或 `Down Arrow`。 - **原因：** tmux 可以将滚轮手势转换为普通的箭头键序列。当 qwen-code 接收到这些序列时，无法将它们与真实的箭头键按下区分开来。 - **解决方案：** 如果屏幕阅读器模式已关闭，请确保 `ui.useTerminalBuffer` 已启用；然后使用 `Shift+Up` / `Shift+Down`，或者在 tmux 将滚轮事件转发给应用时使用鼠标滚轮（需要 `ui.mouseTracking`）。如果你倾向于使用宿主机回滚，请调整 tmux 中针对滚轮事件的鼠标绑定。 - **问题：右键无反应、链接无法打开、或终端中无法选择文本** - **现象：** 当 Qwen Code 运行时，原生右键上下文菜单、OSC 8 超链接点击（Ctrl+Click 或直接点击 URL）以及终端原生的文本选择停止工作。 - **原因：** 当 `ui.mouseTracking` 启用（默认）时，Qwen Code 通过 SGR 鼠标跟踪捕获所有鼠标事件，以支持应用内文本选择、点击定位、行悬停、历史项切换和视口滚动。终端将每个鼠标事件转发给应用，而不是原生处理。Qwen Code 在跟踪开启时提供自己的替代行为：单击可打开 http(s) OSC 8 超链接，右键单击链接或文本选择可打开应用内上下文菜单。 - **解决方案：** 如果你倾向于使用终端的原生处理方式，请在 `settings.json` 中设置 `"ui.mouseTracking": false`。这将关闭所有应用内鼠标交互，包括应用内链接打开和上下文菜单。在虚拟化历史记录（`ui.useTerminalBuffer: true`，默认）中，滚轮将不再滚动对话记录 —— 请使用 `Shift+↑/↓`、`PgUp/PgDn` 或 `Ctrl+Home/End` 代替。要同时恢复终端原生回滚，请设置 `"ui.useTerminalBuffer": false`。需要重启。 ## IDE Companion 无法连接 - 确保 VS Code 仅打开了一个工作区文件夹。 - 安装扩展后重启集成终端，以便它继承以下环境变量： - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` - 如果在容器中运行，请验证 `host.docker.internal` 是否可以解析。否则，请适当映射宿主机。 - 使用 `/ide install` 重新安装 companion，并在命令面板中使用“Qwen Code: Run”来验证其是否启动。 ## 退出码 Qwen Code 使用特定的退出码来指示终止原因。这对于脚本编写和自动化特别有用。 | 退出码 | 错误类型 | 描述 | | --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | | 41 | `FatalAuthenticationError` | 身份验证过程中发生错误。 | | 42 | `FatalInputError` | 提供给 CLI 的输入无效或缺失。（仅限非交互模式） | | 44 | `FatalSandboxError` | 沙盒环境发生错误（例如 Docker、Podman 或 Seatbelt）。 | | 52 | `FatalConfigError` | 配置文件（`settings.json`）无效或包含错误。 | | 53 | `FatalTurnLimitedError` | 已达到会话的最大对话轮数。（仅限非交互模式） | ## 调试技巧 - **CLI 调试：** - 在 CLI 命令中使用 `--verbose` 标志（如果可用）以获取更详细的输出。 - 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。 - **核心调试：** - 检查服务器控制台输出以获取错误消息或堆栈跟踪。 - 如果可配置，请增加日志详细程度。 - 如果需要单步调试服务器端代码，请使用 Node.js 调试工具（例如 `node --inspect`）。 - **工具问题：** - 如果特定工具失败，请尝试通过运行该工具执行的最简单版本的命令或操作来隔离问题。 - 对于 `run_shell_command`，请先检查该命令是否可以直接在你的 shell 中运行。 - 对于_文件系统工具_，请验证路径是否正确并检查权限。 - **预检：** - 在提交代码之前始终运行 `npm run preflight`。这可以捕获许多与格式、lint 和类型错误相关的常见问题。 ## 查找类似的现有 GitHub Issue 或创建新 Issue 如果你遇到本_故障排除指南_中未涵盖的问题，请考虑在 Qwen Code [GitHub Issue 跟踪器](https://github.com/QwenLM/qwen-code/issues)中进行搜索。如果找不到与你的问题类似的 Issue，请考虑创建一个新的 GitHub Issue 并提供详细描述。同时也欢迎提交 Pull request！