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

# MiniMax CLI

> 安装 MiniMax CLI，在终端或 AI Agent 中调用 MiniMax 的多模态与搜索能力。

MiniMax CLI（命令 `mmx`）是 MiniMax 官方命令行工具。M Plan 用户无需编写代码，即可在终端中直接调用，或让 Claude Code、OpenClaw 等 AI Agent 代为调用 MiniMax 的文本、图像、视频、语音、视觉理解和网络搜索能力。实际可用能力以当前套餐和 CLI 版本为准。

使用前需要安装 Node.js 18 或更高版本。

<Accordion title="如何安装 Node.js">
  访问 [Node.js 官网](https://nodejs.org/zh-cn/download)，下载并安装当前的 LTS 版本。安装完成后，重新打开终端并运行：

  ```bash theme={null}
  node --version
  npx --version
  ```

  两条命令都能显示版本号，即表示安装成功。
</Accordion>

## 安装和配置

<Tabs>
  <Tab title="通过 Agent 安装">
    将以下提示词发送给你的 AI Agent，由它完成安装和 SKILL 接入。登录需要你本人在终端中完成，不要把订阅 Key 发送给 Agent。

    ```text theme={null}
    请帮我接入 MiniMax CLI（https://github.com/MiniMax-AI/cli）：

    1. 全局安装：执行 `npm install -g mmx-cli`，完成后用 `mmx --version` 验证。
    2. 登录：提示我在本地终端执行 `mmx auth login`。不要在对话中索要、打印或记录我的 Key。
    3. 我确认登录完成后，安装官方 SKILL：执行 `npx skills add MiniMax-AI/cli -y -g`。
    4. 最后执行 `mmx quota`，确认可以查看 M Plan 用量。
    ```
  </Tab>

  <Tab title="手动安装">
    <Steps>
      <Step title="安装 MiniMax CLI">
        ```bash theme={null}
        npm install -g mmx-cli
        ```
      </Step>

      <Step title="登录">
        将 `sk-xxxxx` 替换为你的 [订阅 Key](https://platform.minimax.cn/console/plan)：

        ```bash theme={null}
        mmx auth login --api-key sk-xxxxx
        ```

        MiniMax CLI 会根据 Key 自动识别服务区域。登录后运行 `mmx quota`，能看到 M Plan 用量即表示配置成功。如果调用返回 401，请参考 [问题排查](#troubleshooting)。
      </Step>

      <Step title="安装 SKILL（可选）">
        如需让 AI Agent 调用 `mmx`，安装官方 SKILL，Agent 即可了解各命令的用法：

        ```bash theme={null}
        npx skills add MiniMax-AI/cli -y -g
        ```

        SKILL 会链接到 `~/.claude/skills/`、`~/.openclaw/skills/` 等目录，Agent 重启后生效。只在终端中使用 `mmx` 时可以跳过此步。
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 使用示例

安装 SKILL 后，可以用自然语言让 Agent 调用 MiniMax CLI，也可以在终端中直接运行对应命令。

**文本**

* 对 Agent 说：`用 MiniMax 写一首关于 AI 的四言诗`
* 终端命令：`mmx text chat --message "写一首关于 AI 的四言诗"`

输出：算力无垠，星火相连；智能如海，梦随光年。

**视频**

* 对 Agent 说：`生成一段视频：夕阳下，一只猫坐在窗边望向远方`
* 终端命令：`mmx video generate --prompt "夕阳下，一只猫坐在窗边望向远方"`

<video src="https://filecdn.minimax.chat/public/84768d5d-354f-408f-b63f-56c5cee3e969.mp4" controls={true} style={{width: '50%', borderRadius: '8px'}} />

**语音**

* 对 Agent 说：`用温柔的女声朗读：欢迎使用 MiniMax M Plan，订阅后，你的 Agent 可以生成视频、语音和图片。`
* 终端命令：`mmx speech synthesize --text "欢迎使用 MiniMax M Plan，订阅后，你的 Agent 可以生成视频、语音和图片。" --out voiceover.mp3`

<video src="https://filecdn.minimax.chat/public/bc984f52-ab54-4c4e-b410-713ff4cdbfdc.mp3" controls={true} className="audio-container" style={{width: '50%'}} />

**图片**

* 对 Agent 说：`生成一张赛博朋克风格的城市夜景图，16:9 比例`
* 终端命令：`mmx image generate --prompt "赛博朋克风格的城市夜景" --aspect-ratio 16:9`

<img src="https://filecdn.minimax.chat/public/94db816d-016e-4fc5-8913-b1a6a4935aad.jpeg" style={{width: '50%', borderRadius: '8px'}} />

未指定输出参数时，图片保存到当前工作目录。可通过 `--out` 指定单张图片路径，或通过 `--out-dir` 指定批量输出目录。

## CLI 面板

在终端中运行 `mmx`（不带参数）会打开 CLI 面板，显示主要命令、参数和用量信息。

<img src="https://filecdn.minimax.chat/public/agent-tool/mmx-cli/20260903-211352.png" style={{borderRadius: '8px', maxWidth: '100%'}} alt="MiniMax CLI 面板" />

* **resources**：当前可调用的资源类型
* **flags**：命令支持的参数
* **用量信息**：当前额度的使用情况
* **帮助入口**：使用说明

## 命令一览

| 能力 | 命令 | 说明 |
| - | - | - |
| 文本 | `mmx text chat` | 多轮对话、流式输出、系统提示词、JSON 输出 |
| 图像 | `mmx image generate` | 文生图，支持宽高比与批量生成 |
| 视频 | `mmx video generate` | 异步视频生成，支持任务查询与下载 |
| 语音 | `mmx speech synthesize` | 文字转语音，支持多音色与流式输出 |
| 视觉 | `mmx vision describe` | 图像理解，支持本地文件、URL 和文件 ID |
| 搜索 | `mmx search query` | 网络搜索 |

<Accordion title="更多管理命令">
  | 命令 | 用途 | 示例 |
  | - | - | - |
  | `mmx auth status / refresh / logout` | 查看登录身份 / 刷新凭据 / 退出登录 | `mmx auth status` |
  | `mmx config show / set` | 查看或修改配置（服务区域、默认模型等） | `mmx config set --key region --value cn` |
  | `mmx agent setup` | 为 AI 编程工具配置 MiniMax | `mmx agent setup` |
  | `mmx quota` | 查看 M Plan 用量与剩余额度 | `mmx quota` |
  | `mmx update` | 显示当前版本和升级提示 | `mmx update` |
</Accordion>

<h2 id="agent-setup">
  一键配置向导
</h2>

一键配置向导会验证 Key、按需安装缺少的工具，并把 MiniMax 写入所选 AI 编程工具的配置。目前支持 Claude Code、Codex CLI、OpenCode、Grok CLI、Hermes Agent 和 Pi。

### 使用向导配置

<Steps>
  <Step title="准备订阅 Key">
    在 [套餐详情](https://platform.minimax.cn/console/plan) 获取 M Plan 订阅 Key。

    向导也支持按量计费 API Key。订阅 Key（`sk-cp-...`）与按量计费 API Key（`sk-api-...`）使用不同额度，向导会询问 Key 类型。
  </Step>

  <Step title="运行向导">
    ```bash theme={null}
    npx -y mmx-cli@latest agent setup
    ```

    先选择要配置的工具。如果所选工具未在 `PATH` 中检测到，向导会显示第二个多选列表，由你决定安装哪些工具。随后选择服务区域和 Key 类型，再粘贴 Key。

    确认后，向导会先验证 Key，再显示并执行官方安装包或安装脚本。安装完成后，向导会检查工具，再写入 MiniMax 配置。安装失败时，可以选择跳过安装，继续写入配置。
  </Step>

  <Step title="启动工具">
    配置成功后，启动所选工具，例如 `claude`、`codex` 或 `opencode`，即可使用 MiniMax 模型。
  </Step>
</Steps>

自动安装支持 macOS、Linux 和 Windows。除 Pi 外，目前仅支持 arm64 和 x64 架构。

<Accordion title="查看安装来源与命令">
  <Tabs sync={false}>
    <Tab title="macOS / Linux">
      **Claude Code**

      ```bash theme={null}
      curl -fsSL https://claude.ai/install.sh | bash
      ```

      **Codex CLI**

      ```bash theme={null}
      npm install -g @openai/codex
      ```

      **Grok CLI**

      ```bash theme={null}
      curl -fsSL https://x.ai/cli/install.sh | bash
      ```

      **OpenCode**

      ```bash theme={null}
      npm install -g opencode-ai
      ```

      **Pi**

      ```bash theme={null}
      npm install -g --ignore-scripts --engine-strict @earendil-works/pi-coding-agent
      ```

      Hermes Agent 使用[官方安装脚本](https://hermes-agent.nousresearch.com/install.sh)的非交互核心 CLI 阶段，不运行 `setup`、`gateway` 等可选流程。
    </Tab>

    <Tab title="Windows">
      **Claude Code**

      ```powershell theme={null}
      irm https://claude.ai/install.ps1 | iex
      ```

      **Codex CLI**

      ```powershell theme={null}
      npm install -g @openai/codex
      ```

      **Grok CLI**

      ```powershell theme={null}
      irm https://x.ai/cli/install.ps1 | iex
      ```

      **OpenCode**

      ```powershell theme={null}
      npm install -g opencode-ai
      ```

      **Pi**

      ```powershell theme={null}
      npm install -g --ignore-scripts --engine-strict @earendil-works/pi-coding-agent
      ```

      Hermes Agent 使用[官方 PowerShell 安装脚本](https://hermes-agent.nousresearch.com/install.ps1)的非交互核心 CLI 阶段，跳过 Computer Use 和其他可选流程。
    </Tab>
  </Tabs>
</Accordion>

### 非交互模式

在 npx 命令后传入选项即进入非交互模式，适合在脚本中使用。非交互模式只写入配置，不安装工具，必须指定工具、Key 和服务区域：

```bash theme={null}
npx -y mmx-cli@latest agent setup \
  --agent claude-code \
  --agent codex \
  --api-key "$MINIMAX_API_KEY" \
  --region cn
```

使用 `--all` 可一次配置全部支持的工具；加上 `--dry-run` 可先预览将要修改的文件，此时不会联网、安装工具或写入文件。

| 选项 | 说明 |
| - | - |
| `--agent <name>` | 选择一个工具，可重复使用 |
| `--all` | 选择全部支持的工具 |
| `--api-key <key>` | 订阅 Key 或按量计费 API Key |
| `--region cn\|global` | 服务区域，国内选择 `cn` |
| `--model <model>` | 写入的默认模型 |
| `--dry-run` | 只预览，不验证 Key、不写入文件 |
| `--output json` | 输出适合脚本处理的 JSON |

### 修改的配置文件

| 工具 | 配置文件 |
| - | - |
| Claude Code | `~/.claude/settings.json` |
| Codex | `~/.codex/config.toml`、`~/.codex/mmx-model-catalog.json` |
| Grok CLI | `~/.grok/config.toml` |
| OpenCode | `~/.config/opencode/opencode.json` 或 `opencode.jsonc` |
| Hermes Agent | `~/.hermes/config.yaml`、`~/.hermes/.env` |
| Pi | `~/.pi/agent/models.json`、`~/.pi/agent/settings.json` |

写入配置时，向导会：

* 只更新所选工具的 MiniMax 配置，保留其他 Provider 和无关设置
* 修改已有文件前创建带时间戳的 `.bak` 备份
* 将配置文件设为仅当前用户可读写（Windows 除外）
* 任一步骤失败时，恢复本次已修改的文件

<h2 id="troubleshooting">
  问题排查
</h2>

<AccordionGroup>
  <Accordion title="登录后调用返回 401">
    通常是服务区域未能自动识别。手动指定国内区域，再确认当前区域：

    ```bash theme={null}
    mmx config set --key region --value cn
    mmx auth status
    ```

    使用国内套餐时，登录过程中建议关闭 VPN 或代理。
  </Accordion>

  <Accordion title="找不到 agent setup 命令">
    请确认已安装 Node.js 18 或更高版本，然后重新运行 `npx -y mmx-cli@latest agent setup`。如果本地安装的 `mmx` 版本过旧，也可以改用这条 npx 命令。
  </Accordion>

  <Accordion title="工具显示 not detected on PATH">
    向导没有在当前终端的 `PATH` 中找到该工具。交互模式下，向导会继续检查安装条件，并询问是否安装符合条件的工具。
  </Accordion>

  <Accordion title="没有出现安装选项">
    工具已安装、当前为非交互模式，或当前环境不满足自动安装条件时，不会出现安装列表。向导会列出缺少的命令或不支持的系统架构；Pi 还要求 Node.js 22.19 或更高版本。
  </Accordion>

  <Accordion title="安装失败">
    向导会显示实际执行的命令和错误信息。Codex、OpenCode 或 Pi 遇到 npm 权限错误时，可参考 [npm 官方说明](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)。也可以跳过安装，继续写入配置。
  </Accordion>

  <Accordion title="配置后仍然连接到其他服务">
    检查当前终端是否设置了会覆盖配置文件的环境变量，例如 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`，以及 Grok CLI 的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`。
  </Accordion>

  <Accordion title="Codex 已使用自定义模型目录">
    如果 `~/.codex/config.toml` 中的 `model_catalog_json` 已指向自定义文件，向导会停止且不修改文件。你可以保留现有目录并手动配置 Codex，或移除该设置后重试。
  </Accordion>
</AccordionGroup>
