一行指令接上多模態 AI：MMX-CLI 實戰

用一句話講清楚：MMX-CLI 讓你用一行指令，就能在本機腳本或 Agent 裡，直接調用文字、圖片、影片、語音、音樂、視覺分析與搜尋等多模態 AI 能力，而且輸出格式乾淨，好串自動化。

📌 本文重點

• 一套 mmx CLI 管文字、圖片、影片等七種多模態能力
• stdout / stderr 分流設計，超適合腳本與 CI 自動化
• 支援語義錯誤碼與 async，穩定掛在長鏈式工作流後面
• Node / JS 友善，當「通用多模態 AI 插件」掛在任何工具裡

專案來源：Reddit 介紹帖（含原始連結）：https://www.reddit.com/r/LocalLLaMA/comments/1skfhix/minimax_released_mmxcli_one_cli_for_text_image/

---

核心功能：為「會寫指令的人」準備的多模態外掛

💡 關鍵： 一套 mmx 前綴的 CLI 就涵蓋七種多模態能力，大幅減少安裝與學習不同 SDK 的成本

1. 七大多模態指令組：一套 CLI 管全部

MMX-CLI 的指令前綴都是 mmx，再接子指令：

• mmx text：文字生成功能（寫文案、草稿）
• mmx image：圖片生成、批次生成
• mmx video：影片生成（支援非同步）
• mmx speech：文字轉語音 / 語音相關
• mmx music：音樂生成
• mmx vision：圖片理解、標註、OCR 類任務
• mmx search：網路搜尋 / 檢索

可行動重點：

• 想做「終端裡直接問圖」、「批量出圖」或「自動生成影片」，都只要學一個 mmx 開頭的 CLI 即可，不必各裝一套 SDK。
• 在腳本中只要換子指令，就能把文字流程擴充到圖像、影音，不用改整個架構。

---

2. stderr/stdout 分流：為自動化管線設計的輸出

多數 AI CLI 會把提示訊息、JSON 結果都塞在一起，要解析結果時只好寫一堆正則。MMX-CLI 的設計直接幫你分好：

• stdout：只輸出「乾淨結果」，例如 JSON、檔案路徑
• stderr：UI 提示、進度條、debug 訊息

💡 關鍵： 把結果與提示嚴格分流，讓你在 CI / 腳本裡直接吃 JSON，不用再寫正則清洗輸出

這代表你可以這樣用：

mmx image generate \
  --prompt "一張藍底白字的活動宣傳圖" \
  --json \
  1> result.json \
  2> log.txt

• result.json：可直接被 jq、Python、Node 解析
• log.txt：留給人類看錯誤、進度

可行動重點：

• 在任何 Shell/CI pipeline 裡，用 1>、2> 就能區分機器要吃的結果、跟人類要看的訊息，少很多「切字串」的工作。

---

3. 語義錯誤碼與 async：穩定接在長鏈式工作流後面

MMX-CLI 有兩個很適合自動化的設計：

1. 語義錯誤碼（semantic exit codes）：
2. 不只是 0/1，而是用不同 exit code 表示不同錯誤類型（如：授權、配額、參數錯誤等）。

3. 你可以在腳本裡根據 $? 做分支處理，而不是只知道「失敗」兩個字。

4. async 影片與圖片一致性：

5. mmx video 支援 --async 或 --no-wait，提交生成後直接結束，不會在終端卡很久。
6. 產生的任務 ID 可存起來，之後再查詢結果，適合長影片或大量任務情境。
7. mmx image 支援像 --subject-ref 這類選項，可讓同一批生成的圖片保持主體一致（同一個角色、同一個風格），方便做系列素材。

💡 關鍵： 用語義錯誤碼搭配 async 任務查詢，可以在長鏈式自動化裡做精細錯誤分流，又不會堵住整條 pipeline

可行動重點：

• 在 CI / 排程任務中，影片生成用 --async，後面接一個輪詢/查詢腳本，不會讓 pipeline 掛住。
• 社群素材、產品圖需要「同一個角色」時，在同一批任務加入主體參考參數，減少後期修圖重工。

---

適合誰用：把 MMX-CLI 當「通用 AI 插件」來掛

1. 本機腳本與自動化 pipeline：用 CLI 批量做內容

典型用法：每天自動生成社群素材（文字 + 配圖）。例如一個簡單的 cron 任務：

1. 用 mmx text 生成今天要發的貼文文案。
2. 把文案丟給 mmx image 生成對應主圖。
3. 結果存到指定資料夾 + JSON 清單。

Shell 示例：

#!/usr/bin/env bash
set -e

# 1. 生成文案
caption=$(mmx text generate --prompt "替科技品牌寫一則今日 IG 貼文，50 字內，口吻輕鬆" --plain)

# 2. 生成圖片（輸出 JSON，內含檔案路徑）
mmx image generate \
  --prompt "$caption" \
  --json 1> image.json 2> /dev/null

image_path=$(jq -r '.outputs[0].path' image.json)

echo "文案：$caption"
echo "圖片：$image_path"

可行動重點：

• 任何原本用 Bash / Python 後面接 curl + OpenAI API 的地方，都可以試著改成 mmx text/image/...，讓指令更短、錯誤處理更好做。

---

2. 在 Claude Code / Cursor / OpenClaw 裡當「外掛能力」

MMX-CLI 可以直接被這些 Agent/IDE 工具當成外部命令調用，不需要額外架 MCP Server：

• Claude Code / Cursor：程式碼助手可以呼叫系統指令（例如 !mmx ... 或 task runner），把多模態功能塞進 coding workflow。
• OpenClaw 等 Agent 框架：把 mmx 視為一個 tool，交給 Agent 自己 decide 什麼時候用圖像、影片、搜尋能力。

範例 workflow（以 Cursor 為例）：

1. 在專案的 script 區塊新增一條：「mmx vision analyze 對當前專案的 UI 截圖做說明」。
2. 用自然語言跟 Cursor 說：「請幫我分析 screenshot.png，找出 UI 過於擁擠的區域」，由 Cursor 呼叫該 script，再回傳結果給你。

可行動重點：

• 如果你已經在用 Claude Code / Cursor，試著加一條腳本（後面會給最小範例）讓它能調用 mmx vision，等於幫 Agent 長出「看圖」能力。

---

3. 想要簡化多模態 API 整合的工程師 / Side project 作者

MMX-CLI 用 TypeScript 寫成，跑在 Node.js 18+ 上：

• 對前端 / JS 工程師特別友善，可以輕鬆串到 Node 腳本、Electron、Next.js 後端。
• 不想碰太多 SDK，單純想「能被命令行叫起來，回傳 JSON」，就很適合直接用這一套。

可行動重點：

• 當你在 side project 裡只需要一兩個 AI 能力（例如：上傳照片 → 生成說明文字），優先考慮用 child_process 呼叫 mmx，先把功能打通，再考慮要不要換成直接 API。

---

怎麼開始：3 分鐘跑通你的第一個多模態任務

1. 環境需求與安裝方式

基本需求：

• Node.js 18+（建議直接裝 LTS 版本）
• npm / npx 可用

安裝成全域「技能」：

npx skills add MiniMax-AI/cli -y -g

或一般全域安裝（若專案說明有提供 npm package）：

npm install -g @minimax-ai/mmx-cli   # 依官方實際名稱調整

最新安裝指令以官方 README 為準，可從 Reddit 原文往下點到 GitHub 或官網。

可行動重點：

• 先確認 node -v 是 18 以上；若不是，先更新 Node，再來跑 npx skills add ...。

---

2. 最小可執行範例：一行文字 → 一張圖片

安裝完後，先試一個最簡單的生成任務：

mmx image generate \
  --prompt "一張極簡風格的藍底白字技術活動海報" \
  --json

預期行為：

• 終端 stdout 輸出一段 JSON，其中會包含生成圖片的本地路徑或 URL。
• stderr 會有模型載入、進度等訊息，不會干擾 JSON。

若只想要檔案路徑，可以接 jq：

mmx image generate \
  --prompt "一張極簡風格的藍底白字技術活動海報" \
  --json 2>/dev/null | jq -r '.outputs[0].path'

可行動重點：

• 改幾個不同 prompt（例如品牌名稱、活動主題），就能快速做出一批風格一致的海報草稿。

---

3. Node 腳本範例：用 JS 串多模態流程

如果你想直接在 Node 專案裡用 MMX-CLI，下面是一個「讀文字 → 生成語音檔」的最小範例：

// file: tts.js
import { execFile } from 'node:child_process';

function runMMX(args) {
  return new Promise((resolve, reject) => {
    execFile('mmx', args, { maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
      if (error) {
        console.error('MMX stderr:', stderr);
        return reject(error);
      }
      try {
        const json = JSON.parse(stdout);
        resolve(json);
      } catch (e) {
        reject(e);
      }
    });
  });
}

(async () => {
  const text = '歡迎使用 MMX-CLI，這是一個多模態 AI 的命令列工具。';
  const result = await runMMX([
    'speech',
    'generate',
    '--text', text,
    '--json'
  ]);

  console.log('生成的音檔路徑:', result.outputs[0].path);
})();

執行：

node tts.js

可行動重點：

• 把這支腳本換成 vision analyze 或 video generate，你就能在 Node 專案裡快速測出多模態能力，不用先研究一整套 API。

---

小結：MMX-CLI 的定位與你可以立刻做的三件事

MMX-CLI 適合被當成「通用多模態 AI 插件」掛在任何能呼叫命令列的地方：腳本、CI、Agent、IDE。

你現在可以立刻做的三件事：

1. 安裝並跑通最小範例：升級 Node → npx skills add MiniMax-AI/cli -y -g → 跑一個 mmx image generate。
2. 在現有腳本裡替換一個原本用 curl + API 的地方，改用一條 mmx text，感受 stderr/stdout 分流帶來的差異。
3. 在 Claude Code / Cursor 專案裡加一條呼叫 mmx vision 的 script，讓你的程式碼助手從「只會看文字」變成「看得懂圖片」。

只要能打開終端，你就能用 MMX-CLI 把多模態 AI 接到任何地方。

🚀 你現在可以做的事

• 打開終端，確認 node -v 版本後，依文中指令安裝 mmx 並跑一次圖片生成
• 挑一個現有 Bash / Node 腳本，把其中一段 curl + API 改寫成對應的 mmx text 或 mmx image
• 在你的 Claude Code / Cursor 專案設定裡新增一條腳本，讓它可以呼叫 mmx vision analyze 來查看專案截圖