> ## 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">
  下面的命令可以先帮助你判断问题属于安装、认证、配置还是任务运行阶段：

  ```bash theme={null}
  mcode --version
  mcode --help
  mcode <command> --help
  ```

  ## 安装与环境

  <AccordionGroup>
    <Accordion title="安装后提示 mcode: command not found 怎么办？">
      先关闭并重新打开终端，再运行 `mcode --version`。如果仍然找不到命令，检查全局 npm 安装目录或安装器目录是否已经加入 `PATH`。Windows 上已经打开的 VS Code 可能保留旧环境变量，需要完整退出并重新启动 VS Code。
    </Accordion>

    <Accordion title="当前支持哪些 Node.js 版本？">
      手动安装需要 Node.js `22.19.0` 及以上的 22.x，或 Node.js 24、25、26。官方安装器会在需要时准备兼容的 Node.js。Alpine / musl Linux 当前不在一键安装器支持范围内。
    </Accordion>

    <Accordion title="安装失败时应该检查什么？">
      确认网络可以访问 MiniMax 文件 CDN、npm registry 和 Node.js 下载源。部分平台的原生依赖还可能访问 GitHub。使用代理时，先配置标准的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 或 `NO_PROXY` 环境变量后重试。
    </Accordion>

    <Accordion title="如何升级或卸载 CLI？">
      升级运行 `mcode update`，完成后重新启动当前 MCode 进程。npm 安装的 CLI 可以运行 `npm uninstall -g @minimax-ai/code` 卸载；安装器安装的版本请使用对应安装器或安装目录的卸载方式。
    </Accordion>
  </AccordionGroup>

  ## 登录与认证

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

    <Accordion title="在 WSL 或远程开发机中浏览器打不开怎么办？">
      登录命令会在当前 Linux 环境的本机回环地址启动临时回调服务，并尝试通过 `xdg-open` 打开浏览器。Debian / Ubuntu 可以先安装浏览器打开工具：

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

      保持原来的 `mcode login` 进程运行，完成浏览器登录后再关闭它。通过 SSH 使用远程开发机时，可以转发登录输出中的回调端口：

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

      每次登录都可能使用不同端口，不要固定复用示例端口。
    </Accordion>

    <Accordion title="浏览器已经登录，但 localhost 回调页打不开怎么办？">
      保持原登录命令运行，从浏览器地址栏复制完整回调 URL，在第二个终端请求它：

      ```bash theme={null}
      curl 'http://127.0.0.1:<port>/auth/callback?...'
      ```

      必须保留单引号，避免 Shell 把 URL 中的 `&` 拆成后台命令。需要确认回调服务仍在监听时，可以运行 `ss -ltnp | grep <port>`。

      回调 URL 可能包含临时访问凭证，不要分享、截图或提交到仓库。
    </Accordion>

    <Accordion title="官方模型不可用怎么办？">
      先运行 `mcode login`，在 TUI 中用 `/status` 检查账号状态，用 `/model` 选择可用模型。如果使用 MiniMax API Key 或自定义 Provider，请参阅功能页中的 Provider 配置，并运行 `mcode provider test <provider-id>` 检查连接。
    </Accordion>
  </AccordionGroup>

  ## 数据目录、配置与代理

  <AccordionGroup>
    <Accordion title="CLI 把配置和 Session 保存在哪里？">
      默认数据根目录是 `~/.minimax`，配置文件是 `<data-dir>/config.yaml`。其中还会保存 Session、日志、Plugin、Skill 和其他运行数据。可以通过 `MINIMAX_DATA_DIR` 指定目录；`MAVIS_DATA_DIR` 作为兼容回退变量，同时设置时优先使用 `MINIMAX_DATA_DIR`。

      ```bash theme={null}
      export MINIMAX_DATA_DIR=/path/to/mcode-data
      ```
    </Accordion>

    <Accordion title="如何设置默认模型和权限模式？">
      可以在 `config.yaml` 中设置：

      ```yaml theme={null}
      defaultModel: "provider-id/model-id"
      defaultModelVariant: standard
      permissionMode: auto
      minimaxModelSource: token_plan
      ```

      `defaultModel` 使用 `provider/model` 格式，也可以追加 `#variant`。一次运行的 `mcode exec --model` 只覆盖当前任务，不修改全局配置。`permissionMode` 可用 `default`、`auto`、`bypassPermissions` 或 `off`。
    </Accordion>

    <Accordion title="CLI 支持哪些代理环境变量？">
      支持 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY` 及其小写形式。CLI 始终绕过 `localhost`、`127.0.0.1` 和 `::1`，以保证登录回调和本地服务可用。
    </Accordion>
  </AccordionGroup>

  ## Provider 与 API Key

  <AccordionGroup>
    <Accordion title="如何使用 MiniMax API Key？">
      先设置 Key，再运行 `mcode provider set-minimax-key`：

      ```bash theme={null}
      export MCODE_PROVIDER_API_KEY="你的 MiniMax API Key"
      mcode provider set-minimax-key
      ```

      默认环境变量名是 `MCODE_PROVIDER_API_KEY`，也可以通过 `--api-key-env <name>` 指定其他变量。CLI 只读取环境变量，不会打印 Key。
    </Accordion>

    <Accordion title="如何添加 OpenAI 或 Anthropic 兼容 Provider？">
      运行 `mcode provider add`，至少提供一个模型：

      ```bash theme={null}
      export MCODE_PROVIDER_API_KEY="兼容服务的 API Key"
      mcode provider add \
        --name "我的兼容服务" \
        --base-url "https://api.example.com/v1" \
        --api-format openai-completions \
        --model "model-id" \
        --use
      ```

      `--api-format` 支持 `anthropic-messages`、`openai-completions` 和 `openai-responses`。使用 `mcode provider list` 查看 Provider，使用 `mcode provider test <provider-id>` 测试连接，移除时必须传入 `--yes`。
    </Accordion>
  </AccordionGroup>

  ## Headless 与 CI

  <AccordionGroup>
    <Accordion title="如何在脚本中运行一次任务？">
      使用 `mcode exec`，它不会启动 TUI：

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

      也可以显式从 stdin 读取输入：

      ```bash theme={null}
      cat task.txt | mcode exec --input -
      printf '%s\n' '{"prompt":"分析构建失败原因"}' \
        | mcode exec --input - --input-format json --output-format json
      ```
    </Accordion>

    <Accordion title="mcode exec 支持哪些参数？">
      常用参数包括：

      * `--cwd <path>`：工作区目录；
      * `--file <path>`：附件，可重复传入，最多 10 个，合计不超过 100 MB；
      * `--model <provider/model[#variant]>`：覆盖本次模型；
      * `--effort <level>`：仅覆盖本次思考强度，必须是模型支持的档位；
      * `--session <id>` 或 `--continue`：继续已有 Session；
      * `--config <path>`：使用指定 Runtime 配置；
      * `--permission smart|full|off`：Headless 权限策略，默认 `smart`；
      * `--timeout <duration>`：运行超时，例如 `30s` 或 `2m`；
      * `--max-steps <count>`：最大 Assistant 步数；
      * `--output-format text|json|stream-json`：输出格式；
      * `--output-schema <schema>`：内联或文件形式的 JSON Schema；
      * `-o, --output-last-message <path>`：成功后写入最终消息。

      `--input -` 不能和位置参数 prompt 同时使用。Headless 不接受 `--permission ask`，因为它没有交互式宿主。
    </Accordion>

    <Accordion title="如何可靠地解析自动化输出？">
      `text` 输出最终回答；`json` 输出一条稳定的 `ExecResult`；`stream-json` 输出换行分隔的事件流。结果写入 `stdout`，诊断写入 `stderr`，消费者应优先判断 JSON 中的 `status`，不要假设可选的 `model` 或 `usage` 字段始终存在。

      使用 `--output-schema` 时，最终回答必须是符合 Schema 的 JSON；解析或校验失败会返回 `status: failed` 和 `STRUCTURED_OUTPUT_INVALID`。`--output-last-message` 只在任务成功并完成 Runtime 关闭后原子写入。
    </Accordion>

    <Accordion title="mcode exec 的退出码是什么？">
      脚本应同时检查进程退出码和 JSON 的 `status`：

      | 退出码 | 含义 |
      | -: | - |
      | `0` | 成功 |
      | `2` | 调用参数或输入错误 |
      | `3` | 配置错误 |
      | `4` | Runtime 或任务失败 |
      | `6` | 超时 |
      | `7` | 超过步数等运行限制 |
      | `70` | 内部错误 |
      | `130` | 被 Ctrl+C 或其他取消信号中断 |
      | `141` | 下游管道关闭导致 broken pipe |
    </Accordion>

    <Accordion title="为什么 Headless 任务提示需要交互？">
      Headless 不会等待问卷、权限确认或其他人工输入。如果已有 Session 中存在待处理交互，任务会失败并提示改用 TUI 或 ACP；请先在交互式入口解决问题，再继续该 Session。
    </Accordion>
  </AccordionGroup>

  ## ACP 与 Plugin

  <AccordionGroup>
    <Accordion title="ACP 客户端为什么收不到正确的响应？">
      `mcode acp` 的 stdin/stdout 只用于 ACP 协议消息，日志和诊断写入 stderr。不要向 ACP 进程直接输入自然语言，也不要让包装脚本把日志写入 stdout。编辑器找不到 `mcode` 时，使用可执行文件绝对路径并重启编辑器刷新 `PATH`。
    </Accordion>

    <Accordion title="Plugin 安装或刷新失败怎么办？">
      先运行 `mcode plugin marketplace list` 查看官方和本地源，再运行 `mcode plugin list --available` 查看可用项目。安装时显式指定 `<plugin>@official` 或 `<plugin>@local`；刷新源使用 `mcode plugin marketplace upgrade`。本地源位于数据目录下的 `plugins` 目录。
    </Accordion>
  </AccordionGroup>

  ## Session、终端与桌面端边界

  <AccordionGroup>
    <Accordion title="如何继续之前的任务？">
      在原工作区运行 `mcode --continue` 继续最近的 Session；不确定 ID 时运行 `mcode --session`，或在 TUI 中使用 `/sessions [query]`。较长对话可以先用 `/compact`，需要留档时使用 `/export [path.md]` 或 `/transcript`。
    </Accordion>

    <Accordion title="Plan Mode 和权限模式有什么区别？">
      Plan Mode 决定是否先规划再执行，使用 `Shift+Tab` 或 `/plan` 切换。权限模式决定工具操作如何确认，使用 `Alt+M` 或 `/permission` 切换。两者相互独立。
    </Accordion>

    <Accordion title="为什么 CLI 中没有桌面端的 Browser 或 Computer Use？">
      CLI 不依赖 Electron 或桌面端 IPC。Browser、Computer Use、桌面面板和桌面快捷键等能力只有在当前宿主显式提供时才会出现，不能仅因为桌面端支持就假定 CLI 环境也支持。
    </Accordion>

    <Accordion title="Ctrl+V 无法粘贴图片怎么办？">
      图片或视频粘贴依赖终端模拟器是否把快捷键和剪贴板文件传给 MCode。远程 SSH 环境通常无法直接读取本机剪贴板；可以改用 `@` 引用工作区中的文件，或通过 `mcode exec --file <path>` 添加附件。
    </Accordion>
  </AccordionGroup>
</div>