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

# 常见问题

> 查看 MiniMax Code CLI 的常见问题与解决方法。

<div className="code-docs">
  <AccordionGroup>
    <Accordion title="安装后提示 mcode: command not found 怎么办？">
      先关闭并重新打开终端，再运行 `mcode --version`。如果仍然找不到命令，检查安装目录是否已加入 `PATH`。

      Windows 安装时已经打开的 VS Code 可能保留旧的环境变量，需要完整退出并重新启动 VS Code，而不只是新建一个终端标签页。
    </Accordion>

    <Accordion title="安装失败时应该检查什么？">
      确认网络可以访问 MiniMax 文件 CDN、Node.js 官网和 npm registry。原生依赖下载在部分平台还可能访问 GitHub。

      一键安装器会自动准备兼容的 Node.js，不需要管理员权限。当前暂不支持 Alpine / musl Linux。若使用自定义代理，请先在终端配置标准的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 或 `NO_PROXY` 环境变量后重试。
    </Accordion>

    <Accordion title="如何登录中国大陆或 Global 账号？">
      中国大陆账号运行 `mcode login`，Global 账号运行 `mcode login --region global`。登录完成后进入 TUI，使用 `/status` 检查账号、模型和运行状态。
    </Accordion>

    <Accordion title="在 Windows WSL 或远程开发机中登录时，浏览器打不开怎么办？">
      `/login` 和 `mcode login` 会在当前 Linux 环境的 `127.0.0.1` 上启动一个临时回调服务，并通过 `xdg-open` 打开浏览器。回调端口由每次登录动态分配，登录命令需要一直运行到回调完成。

      **WSL 推荐方案：安装浏览器打开工具**

      Debian / Ubuntu 可以执行：

      ```bash theme={null}
      sudo apt update
      sudo apt install -y xdg-utils
      ```

      安装后重新运行 `/login` 或 `mcode login`。通常浏览器会正常打开并自动完成回调。

      **浏览器已经登录，但 `localhost` 回调页打不开**

      1. 保持原来的登录命令运行，不要关闭。
      2. 从浏览器地址栏复制完整回调 URL，格式类似 `http://127.0.0.1:<PORT>/auth/callback?accessToken=...&state=...`。
      3. 打开第二个 WSL 终端，把完整 URL 用单引号包住后请求：

      ```bash theme={null}
      curl 'http://127.0.0.1:<PORT>/auth/callback?accessToken=...&state=...'
      ```

      必须保留单引号，否则 Shell 会把 `&state=...` 拆成另一条后台命令。需要确认回调服务仍在监听时，可以执行：

      ```bash theme={null}
      ss -ltnp | grep <PORT>
      ```

      如果没有输出，说明登录进程已经退出或 URL 已过期。重新发起登录，并使用新生成的端口和 URL。

      **通过 SSH 使用远程开发机**

      1. 在开发机运行 `mcode login` 并保持命令运行。如果系统缺少 `xdg-open`，先安装 `xdg-utils`。
      2. 从登录输出的 URL 中找到 `callback_port=<PORT>`。
      3. 在本地电脑打开另一个终端，建立同端口转发：

      ```bash theme={null}
      ssh -N -L <PORT>:127.0.0.1:<PORT> <开发机>
      ```

      例如本次端口是 `45919`：

      ```bash theme={null}
      ssh -N -L 45919:127.0.0.1:45919 <开发机>
      ```

      4. 保持 SSH 隧道运行，在本地浏览器打开 `mcode login` 输出的完整登录 URL，然后完成登录。浏览器访问本机回调端口时，请求会被转发到开发机上的 MCode。

      每次重新发起登录都可能使用不同端口，不要长期固定或复用示例中的 `45919`。

      <Warning>
        登录完成后的回调 URL 包含临时访问凭证。不要把它发给他人、放进文档或截图，也不要提交到仓库；使用后应从 Shell 历史记录中移除。
      </Warning>
    </Accordion>

    <Accordion title="官方模型不可用怎么办？">
      先运行 `mcode login`，再在 TUI 中使用 `/status` 检查登录状态，并通过 `/model` 选择可用模型。

      如果使用 MiniMax API Key 或自定义 Provider，可运行 `mcode provider` 进入配置界面，或使用 `mcode provider --help` 查看命令行配置方式。
    </Accordion>

    <Accordion title="Plan Mode 和权限模式有什么区别？">
      Plan Mode 决定下一条消息是直接执行还是先进入规划，使用 `Shift+Tab` 或 `/plan` 切换。

      权限模式决定工具操作如何确认，使用 `Alt+M` 或 `/permission` 在 Ask、Auto、Full access 之间切换。两者是独立设置。
    </Accordion>

    <Accordion title="如何继续之前的任务？">
      在原工作区运行 `mcode --continue` 可以继续最近的 Session；`mcode --session` 打开 Session 管理器；已知 ID 时使用 `mcode --session <session-id>`。TUI 内可以使用 `/sessions [query]` 搜索和管理。
    </Accordion>

    <Accordion title="任务运行时还能继续发送消息吗？">
      可以。直接发送的新消息会进入等待队列，并在当前响应结束后依次发送。使用 `Alt+Up`（macOS 显示为 `Option+Up`）可以管理等待消息；需要立即指导当前响应时，可以填写 Draft 后按 `Ctrl+X`。
    </Accordion>

    <Accordion title="如何在脚本或 CI 中使用？">
      使用 `mcode exec`，并通过 `--output-format json` 或 `--output-format stream-json` 获取机器可读结果。任务结果写入 `stdout`，诊断写入 `stderr`。

      ```bash theme={null}
      mcode exec --cwd ./repo --output-format json "运行测试并修复失败项"
      ```

      自动化场景还可以设置 `--permission`、`--timeout`、`--max-steps` 和 `--output-schema`。
    </Accordion>

    <Accordion title="为什么 Ctrl+V 无法粘贴图片？">
      图片粘贴依赖终端是否把按键和剪贴板内容传给 MCode。优先使用 `Ctrl+V`，并确认剪贴板里是实际的本地图片或视频文件。部分终端会拦截快捷键，远程 SSH 环境也无法直接读取本机剪贴板文件。
    </Accordion>

    <Accordion title="如何浏览、搜索和复制较长的对话？">
      使用 `PgUp` / `PgDn` 浏览历史，`End` 返回最新位置；使用 `/transcript` 打开完整 Transcript，并在其中搜索和检查详情。

      默认界面保留终端原生 scrollback，鼠标滚动、拖选和复制行为由 Windows Terminal、iTerm2、WezTerm 等终端宿主处理。
    </Accordion>

    <Accordion title="Zed 或其他 ACP 客户端找不到 mcode 怎么办？">
      先在普通终端运行 `mcode --version`。如果命令可用但编辑器仍找不到它，重启编辑器以刷新 `PATH`，或在 ACP 配置中把 `command` 改成 `mcode` 可执行文件的绝对路径。
    </Accordion>

    <Accordion title="如何更新 MiniMax Code CLI？">
      运行 `mcode update`，或在 TUI 中执行 `/update`。更新完成后重新启动当前 MCode 进程。
    </Accordion>

    <Accordion title="为什么 CLI 中没有桌面端的浏览器或 Computer Use？">
      CLI 是独立的终端产品入口，不依赖桌面端 Electron 或 IPC。Browser、Computer Use 等能力只有在当前宿主明确提供时才会出现；不能仅因为桌面端支持就假定 CLI 环境也支持。
    </Accordion>
  </AccordionGroup>
</div>