> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 常见问题及解决方法

<div id="installation-issues">
  ## 安装问题
</div>

<AccordionGroup>
  <Accordion title="安装命令失败（macOS / Linux / WSL）">
    如果安装脚本下载失败：

    1. 检查你的网络连接
    2. 确认已安装 curl：`which curl`
    3. 尝试启用详细输出：`curl -fsSL -v https://cli.devin.ai/install.sh | bash`

    如果你使用企业代理，可能需要配置代理设置：

    ```bash theme={null}
    export https_proxy=http://your-proxy:port
    curl -fsSL https://cli.devin.ai/install.sh | bash
    ```
  </Accordion>

  <Accordion title="安装命令失败（Windows）">
    如果 PowerShell 安装脚本执行失败：

    1. 检查你的网络连接
    2. 确保你以普通用户身份运行 PowerShell (除非确有必要，否则不要以管理员身份运行)
    3. 如果看到执行策略错误，请尝试：
       ```powershell theme={null}
       Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
       irm https://static.devin.ai/cli/setup.ps1 | iex
       ```
    4. 如果你使用企业代理，请先在 PowerShell 中配置代理设置，然后再运行安装命令

    作为 PowerShell 脚本的替代方案，你也可以直接下载并运行独立安装程序：

    * [x86\_64](https://static.devin.ai/cli/devin-updater-x86_64-pc-windows.exe)
    * [ARM64](https://static.devin.ai/cli/devin-updater-aarch64-pc-windows.exe)
  </Accordion>

  <Accordion title="安装过程中出现权限被拒绝">
    安装程序需要写入权限才能安装二进制文件。如果你看到权限错误：

    1. 检查安装位置是否有写入权限
    2. 不要使用 `sudo` 运行安装程序——这可能会导致所有权问题
    3. 如果要安装到系统目录，请确保你的用户具有相应权限
  </Accordion>

  <Accordion title="安装后找不到二进制文件">
    如果安装完成但无法找到 `devin`：

    **macOS / Linux / WSL：**

    1. 重启终端，或运行 `source ~/.bashrc` (或 `~/.zshrc`)
    2. 检查二进制文件所在位置是否在你的 PATH 中：`echo $PATH`
    3. 确认二进制文件存在：`ls -la ~/.local/bin/devin` (或安装过程中显示的安装位置)

    **Windows：**

    1. 重启 PowerShell 会话
    2. 检查二进制文件所在位置是否在你的 PATH 中：`$env:PATH -split ';'`
    3. 确认二进制文件存在于安装过程中显示的安装位置
  </Accordion>

  <Accordion title="'irm' 或 'iex' 命令未找到（Windows）">
    `irm` 和 `iex` 是 PowerShell 的别名。如果你看到此错误，说明你是在 Git Bash 或 CMD 中运行安装命令，而不是在 PowerShell 中。

    \*\*修复：\*\*打开 **PowerShell** 并在那里运行安装命令：

    ```powershell theme={null}
    irm https://static.devin.ai/cli/setup.ps1 | iex
    ```

    或者，你也可以在 Git Bash 或 CMD 中显式调用 PowerShell：

    ```bash theme={null}
    powershell -Command "irm https://cli.devin.ai/install.ps1 | iex"
    ```

    安装完成后，你可以在 **PowerShell**、**Windows Terminal** 或 **Git Bash** 中使用 Devin CLI。
  </Accordion>
</AccordionGroup>

***

<div id="authentication-issues">
  ## 身份验证问题
</div>

<AccordionGroup>
  <Accordion title="登录失败或超时">
    如果基于浏览器的登录无法正常进行：

    1. 对于远程/SSH 会话，尝试使用手动令牌流程：
       ```bash theme={null}
       devin auth login --force-manual-token-flow
       ```
    2. 检查你的浏览器是否可以访问身份验证 URL
    3. 确认你的企业账户已启用 Devin CLI 访问权限
  </Accordion>

  <Accordion title="'Not authorized' 或权限错误">
    如果你在登录后看到授权错误：

    1. 确认你的账户具有访问 Devin CLI 所需的正确权限。你可能需要联系你的 Admin。对于 Enterprise，请参阅 [Devin Auth](/zh/cli/enterprise/devin-auth#configuring-access) 或 [Legacy Windsurf Auth](/zh/cli/enterprise/windsurf-auth#prerequisites)，了解如何配置访问权限。
    2. 尝试退出后重新登录：`devin auth logout && devin auth login`
    3. 检查你的身份验证状态：`devin auth status`
  </Accordion>

  <Accordion title="令牌被拒绝或已撤销">
    Devin CLI API 令牌默认不会过期。如果已存储的令牌已被撤销或不再有效，请在重新登录前先将其移除：

    ```bash theme={null}
    devin auth logout && devin auth login
    ```

    以替换你已存储的凭据。
  </Accordion>
</AccordionGroup>

***

<div id="network-proxy-issues">
  ## 网络与代理问题
</div>

<AccordionGroup>
  <Accordion title="在企业代理环境下连接失败">
    配置代理后，CLI 会将自身的出站 HTTPS 流量 (身份验证、更新、模型 API 调用、MCP 服务器) 通过代理转发。可通过以下两种方式设置：

    **环境变量** — 默认的 `system` 代理模式会读取这些变量：

    ```bash theme={null}
    export HTTPS_PROXY=http://proxy.corp.example.com:8080
    export HTTP_PROXY=http://proxy.corp.example.com:8080
    export ALL_PROXY=socks5://proxy.corp.example.com:1080   # 可选，SOCKS5
    export NO_PROXY=localhost,127.0.0.1,.internal.corp      # 要绕过代理的主机
    ```

    **`config.json`** — 无论环境变量如何，都会生效：

    ```json theme={null}
    {
      "proxy": {
        "mode": "manual",
        "url": "http://proxy.corp.example.com:8080",
        "no_proxy": "localhost,127.0.0.1,.internal.corp"
      }
    }
    ```

    所有选项请参阅 [`proxy` 配置参考](/zh/cli/reference/configuration/config-file#proxy)。在 macOS 和 Windows 上，`system` 模式还会遵循平台原生的 PAC (代理自动配置) 设置。

    如果你的代理会执行 TLS 检查，CLI 会使用操作系统的证书存储，因此请在操作系统层面安装该代理的根 CA (macOS 上的 Keychain、Windows 证书存储，或 Linux 发行版的 CA 包) 。
  </Accordion>

  <Accordion title="捕获完整的 HTTP 请求日志以进行调试">
    若要完整查看请求生命周期 (DNS、连接池、TLS 握手、标头、重定向和重试) ，请通过 `RUST_LOG` 提高日志级别，并使用 `CHISEL_LOG_STDOUT` 将日志镜像到终端：

    ```bash theme={null}
    RUST_LOG="chisel=trace,windsurf_api_client=trace,connect_rpc=trace,reqwest=trace,hyper=trace,hyper_util=trace,rustls=trace" \
      CHISEL_LOG_STDOUT=1 \
      devin auth login
    ```

    各目标分别提供：

    * `chisel`, `windsurf_api_client`, `connect_rpc` — CLI 自身的请求和身份验证日志
    * `reqwest=trace` — 高层级的请求/响应与重定向处理
    * `hyper=trace` / `hyper_util=trace` — 连接建立、连接池以及 HTTP/1.1 和 HTTP/2 帧处理
    * `rustls=trace` — TLS 握手细节 (对排查代理和证书问题很有帮助)

    如果你不希望日志与命令输出交错显示，请使用 `CHISEL_LOG_STDERR=1`，不要使用 `CHISEL_LOG_STDOUT=1`。 (为避免破坏输出，交互式 REPL 和 ACP 模式下会自动禁用 stdout 日志。)

    无论是否设置这些环境变量，日志也始终会写入 CLI 数据目录下按每次运行生成的日志文件：

    * **macOS / Linux:** `~/.local/share/devin/cli/logs/devin_<timestamp>_<pid>.log`
    * **Windows:** `%APPDATA%\devin\cli\logs\devin_<timestamp>_<pid>.log`

    <Warning>
      trace 级别的日志可能包含敏感数据，例如 `Authorization` 标头和令牌。分享前请先清理日志内容。
    </Warning>
  </Accordion>

  <Accordion title="检查完整的请求和响应体">
    `RUST_LOG` 可以展示请求生命周期，但不会显示完整的 payload。若要捕获完整的请求体和响应体，请让 CLI 通过 mitmproxy 之类的拦截代理转发，例如 [mitmproxy](https://mitmproxy.org/)：

    ```bash theme={null}
    # 终端 1 — 启动拦截代理：
    mitmproxy --listen-port 8080

    # 终端 2 — 让 CLI 使用该代理：
    export HTTPS_PROXY=http://127.0.0.1:8080
    devin auth login
    ```

    由于 CLI 信任操作系统证书存储，请先将 mitmproxy 的 CA 证书 (`~/.mitmproxy/mitmproxy-ca-cert.pem`) 安装到系统信任存储中，否则与该代理建立的 TLS 连接将失败。
  </Accordion>
</AccordionGroup>

***

<div id="runtime-issues">
  ## 运行时问题
</div>

<AccordionGroup>
  <Accordion title="模型不可用">
    如果你看到模型不可用的错误：

    1. 检查你的企业是否在 [团队设置](/zh/cli/enterprise/team-settings) 中限制了可用模型
    2. 确认模型名称是否正确——使用 `/model` 查看可用选项
    3. 尝试其他模型：`devin --model sonnet -- your prompt`
  </Accordion>

  <Accordion title="达到速率限制或超出配额">
    如果你触及用量限制：

    1. 等待几分钟后再重试
    2. 查看你的组织的用量仪表板，确认配额状态
    3. 如果你需要更高的限制，请联系你的 Admin
  </Accordion>

  <Accordion title="Agent 似乎卡住或无响应">
    如果 Agent 停止响应：

    1. 按 `Ctrl+C` 中断当前操作
    2. 尝试使用 `/clear` 开始新的会话
    3. 检查你的网络连接
    4. 重启 Devin CLI
  </Accordion>
</AccordionGroup>

***

<div id="mcp-server-issues">
  ## MCP 服务器问题
</div>

<AccordionGroup>
  <Accordion title="服务器无法启动">
    如果 MCP 服务器无法启动：

    1. 确认该命令在 Devin CLI 外也能正常运行：
       ```bash theme={null}
       npx -y @modelcontextprotocol/server-github
       ```
    2. 检查是否已设置所有必填环境变量
    3. 查看服务器输出中的错误信息
  </Accordion>

  <Accordion title="工具未出现">
    如果 MCP 工具未出现：

    1. 服务器可能需要一点时间完成初始化——请等待几秒钟
    2. 检查服务器是否已在你的配置文件中正确配置
    3. 确认你的企业已在[团队设置](/zh/cli/enterprise/team-settings)中允许使用 MCP 服务器
  </Accordion>

  <Accordion title="MCP 工具权限被拒绝">
    MCP 工具默认需要你手动批准。要自动批准特定工具，请将其添加到你的权限配置中：

    ```json theme={null}
    {
      "permissions": {
        "allow": ["mcp__github__list_issues"]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

<div id="getting-help">
  ## 获取帮助
</div>

如果你仍然遇到问题：

* **邮件支持：** [support@cognition.ai](mailto:support@cognition.ai)
* **提交 bug 报告：** 在 Devin CLI 中使用 `/bug` 命令，直接向 Devin CLI 开发团队报告问题
* **检查更新：** 运行 `devin update`，确保你使用的是最新版本