常见问题 - MiniMax Agent 文档

下面的命令可以先帮助你判断问题属于安装、认证、配置还是任务运行阶段：

mcode --version
mcode --help
mcode <command> --help

安装与环境

安装后提示 mcode: command not found 怎么办？

先关闭并重新打开终端，再运行 mcode --version。如果仍然找不到命令，检查全局 npm 安装目录或安装器目录是否已经加入 PATH。Windows 上已经打开的 VS Code 可能保留旧环境变量，需要完整退出并重新启动 VS Code。

当前支持哪些 Node.js 版本？

手动安装需要 Node.js 22.19.0 及以上的 22.x，或 Node.js 24、25、26。官方安装器会在需要时准备兼容的 Node.js。Alpine / musl Linux 当前不在一键安装器支持范围内。

安装失败时应该检查什么？

确认网络可以访问 MiniMax 文件 CDN、npm registry 和 Node.js 下载源。部分平台的原生依赖还可能访问 GitHub。使用代理时，先配置标准的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 或 NO_PROXY 环境变量后重试。

如何升级或卸载 CLI？

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

登录与认证

如何登录中国大陆或 Global 账号？

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

在 WSL 或远程开发机中浏览器打不开怎么办？

登录命令会在当前 Linux 环境的本机回环地址启动临时回调服务，并尝试通过 xdg-open 打开浏览器。Debian / Ubuntu 可以先安装浏览器打开工具：

sudo apt update
sudo apt install -y xdg-utils

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

ssh -N -L <port>:127.0.0.1:<port> <开发机>

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

浏览器已经登录，但 localhost 回调页打不开怎么办？

保持原登录命令运行，从浏览器地址栏复制完整回调 URL，在第二个终端请求它：

curl 'http://127.0.0.1:<port>/auth/callback?...'

必须保留单引号，避免 Shell 把 URL 中的 & 拆成后台命令。需要确认回调服务仍在监听时，可以运行 ss -ltnp | grep <port>。回调 URL 可能包含临时访问凭证，不要分享、截图或提交到仓库。

官方模型不可用怎么办？

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

数据目录、配置与代理

CLI 把配置和 Session 保存在哪里？

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

export MINIMAX_DATA_DIR=/path/to/mcode-data

如何设置默认模型和权限模式？

可以在 config.yaml 中设置：

defaultModel: "provider-id/model-id"
defaultModelVariant: standard
permissionMode: auto
minimaxModelSource: token_plan

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

CLI 支持哪些代理环境变量？

支持 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 及其小写形式。CLI 始终绕过 localhost、127.0.0.1 和 ::1，以保证登录回调和本地服务可用。

Provider 与 API Key

如何使用 MiniMax API Key？

先设置 Key，再运行 mcode provider set-minimax-key：

export MCODE_PROVIDER_API_KEY="你的 MiniMax API Key"
mcode provider set-minimax-key

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

如何添加 OpenAI 或 Anthropic 兼容 Provider？

运行 mcode provider add，至少提供一个模型：

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。

Headless 与 CI

如何在脚本中运行一次任务？

使用 mcode exec，它不会启动 TUI：

mcode exec --cwd ./repo --output-format json "运行最小测试集并修复失败项"

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

cat task.txt | mcode exec --input -
printf '%s\n' '{"prompt":"分析构建失败原因"}' \
  | mcode exec --input - --input-format json --output-format json

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，因为它没有交互式宿主。

如何可靠地解析自动化输出？

text 输出最终回答；json 输出一条稳定的 ExecResult；stream-json 输出换行分隔的事件流。结果写入 stdout，诊断写入 stderr，消费者应优先判断 JSON 中的 status，不要假设可选的 model 或 usage 字段始终存在。使用 --output-schema 时，最终回答必须是符合 Schema 的 JSON；解析或校验失败会返回 status: failed 和 STRUCTURED_OUTPUT_INVALID。--output-last-message 只在任务成功并完成 Runtime 关闭后原子写入。

mcode exec 的退出码是什么？

脚本应同时检查进程退出码和 JSON 的 status：

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

为什么 Headless 任务提示需要交互？

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

ACP 与 Plugin

ACP 客户端为什么收不到正确的响应？

mcode acp 的 stdin/stdout 只用于 ACP 协议消息，日志和诊断写入 stderr。不要向 ACP 进程直接输入自然语言，也不要让包装脚本把日志写入 stdout。编辑器找不到 mcode 时，使用可执行文件绝对路径并重启编辑器刷新 PATH。

Plugin 安装或刷新失败怎么办？

先运行 mcode plugin marketplace list 查看官方和本地源，再运行 mcode plugin list --available 查看可用项目。安装时显式指定 <plugin>@official 或 <plugin>@local；刷新源使用 mcode plugin marketplace upgrade。本地源位于数据目录下的 plugins 目录。

Session、终端与桌面端边界

如何继续之前的任务？

在原工作区运行 mcode --continue 继续最近的 Session；不确定 ID 时运行 mcode --session，或在 TUI 中使用 /sessions [query]。较长对话可以先用 /compact，需要留档时使用 /export [path.md] 或 /transcript。

Plan Mode 和权限模式有什么区别？

Plan Mode 决定是否先规划再执行，使用 Shift+Tab 或 /plan 切换。权限模式决定工具操作如何确认，使用 Alt+M 或 /permission 切换。两者相互独立。

为什么 CLI 中没有桌面端的 Browser 或 Computer Use？

CLI 不依赖 Electron 或桌面端 IPC。Browser、Computer Use、桌面面板和桌面快捷键等能力只有在当前宿主显式提供时才会出现，不能仅因为桌面端支持就假定 CLI 环境也支持。

Ctrl+V 无法粘贴图片怎么办？

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

​安装与环境

​登录与认证

​数据目录、配置与代理

​Provider 与 API Key

​Headless 与 CI

​ACP 与 Plugin

​Session、终端与桌面端边界