---
name: minimax-cli-usage
description: MiniMax CLI (mmx) 安装、认证与模型配额避坑指南
---

# MiniMax CLI (mmx-cli) 使用指南

## 安装与认证

```bash
# 安装
npm install -g mmx-cli

# 认证（两种方式均可）
mmx auth login --api-key sk-cp-xxxxx        # 交互式登录
mmx config set api_key "sk-cp-xxxxx"         # 直接写入配置（更快捷）
```

## The Agency 代理安装（2026-05-15 更新）

**中文版（推荐）**：https://github.com/jnMetaCode/agency-agents-zh
- 215 个中文代理，覆盖工程/设计/市场/销售等 16 个部门
- 安装命令：`cd /tmp/agency-agents-zh && ./scripts/install.sh --tool claude-code`
- 安装路径：`~/.claude/agents/`（215 个 .md 文件）

**英文版（原始）**：https://github.com/msitarzewski/agency-agents
- 184 个英文代理

**Claude Code 使用代理的方式**：
```bash
cd /root/.claude && claude --print "你是前端开发者，帮我写一个登录组件"
```
注意：Claude Code 不会自动识别文件名，需要在 prompt 中**直接引用角色名称**（如"你是前端开发者"），代理文件的人格定义会被加载到上下文中。

**Claude Code + MiniMax（2026-05-15 新增）

```bash
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 安装中文版 The Agency 代理（215个）
cd /tmp/agency-agents-zh && ./scripts/install.sh --tool claude-code
```

**配置 MiniMax API**（`~/.claude/settings.json`）：
```json
{
  "version": 1,
  "env": {
    "ANTHROPIC_API_KEY": "sk-cp-WCzvQhxseP0uR8sLHlrHxVaDF7zgEKU6lPd8GiIgDnQ_5B79p-YHgiepIR8fSNdNOAGP3V7aSRU00KBw3rStYG3k1EBrteqfsh2ANWGlQP9T3lLmXalnTiM",
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_MODEL": "MiniMax-M2.7"
  }
}
```

**使用方式**：
```bash
cd /root/.claude && claude --print "激活 engineering-frontend-developer，帮我写个React组件"

# 临时覆盖环境变量
ANTHROPIC_MODEL=MiniMax-M2.7 ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic \
  ANTHROPIC_API_KEY=sk-cp-xxx claude --print "你的问题"
```

**验证模型**：
```bash
claude --print "What model are you?"  # 应返回 MiniMax-M2.7
```

---

## 通过 Hermes 发送微信文件（markdown/图片/文档通用）

**正确方法**（在 hermes-agent 目录下执行）：
```python
cd /root/.hermes/hermes-agent && python3 -c "
import time
from tools.send_message_tool import send_message_tool

filepath = '/root/.hermes/workspace/file.md'
chat_id = 'o9cq801Q4BDVa20m46H0KTKRUOjo@im.wechat'

for attempt in range(5):
    r = send_message_tool({'action':'send','message':f'MEDIA:{filepath}','target':f'weixin:{chat_id}'})
    print(f'Attempt {attempt+1}: {repr(r)[:200]}')
    if isinstance(r, str) and 'success' in r.lower():
        print('Sent!')
        break
    time.sleep(8 * (2 ** attempt))
"
```

**坑点记录**：
- ❌ `send_message_tool` 返回的是 **字符串**（不是 dict），判断成功用 `isinstance(r, str) and 'success' in r.lower()`
- ❌ 不要用 `r.get('success')` — 会报错 `AttributeError: 'str' object has no attribute 'get'`
- ✅ 重试策略：指数退避（8s, 16s, 32s...），最多 5 次
- ✅ markdown 文件（.md）同样可以用 `MEDIA:/path/file.md` 发送

## 重要：模型配额与速率限制

**发现（2026-05-13）**：`MiniMax-M*` 配额与 `MiniMax-M2.7-highspeed` 是**两条独立配额通道**。

- `mmx text chat` 不指定模型时会挂起超时
- `--model MiniMax-M2.7-highspeed` 有独立的 5 小时用量限制（19/1500 就触发）
- **明确指定 `--model MiniMax-M2.7` 反而可用**，绕过高_speed 的速率限制

```bash
# 正确用法：指定具体模型，绕速率限制
mmx text chat --model MiniMax-M2.7 --message "你的问题"

# 高速度模型容易触发 5h 限制，换 M2.7 更稳定
mmx text chat --model MiniMax-M2.7-highspeed --message "xxx"  # 易触发 rate limit
```

## 常用命令

```bash
# 文字对话
mmx text chat --model MiniMax-M2.7 --message "问题"

# 语音合成（speech-hd 模型）
mmx speech synthesize --text "文字" --out output.mp3
mmx speech generate   --text "文字" --out output.mp3   # 两者等价

# 音乐生成（music-2.6 模型）
mmx music generate --prompt "风格描述" --lyrics "歌词" --out song.mp3

# 音乐翻唱（music-cover 模型）
mmx music cover --prompt "目标风格" --audio-file original.mp3 --out cover.mp3

# 查看音色
mmx speech voices

# 查看配额
mmx quota
```

## 完整配额一览（2026-05-20 更新）

| 模型 | 每日额度 | 每周额度 |
|------|---------|---------|
| MiniMax-M* | 1,500 次（5h） | 15,000 次 |
| MiniMax-M2.7 | 同 M* | 同 M*（指定模型可绕 highspeed 限制） |
| MiniMax-M2.7-highspeed | 150 次（5h） | —（独立通道，易触发） |
| speech-hd | 4,000 次 | 28,000 次 |
| music-2.6 | 100 次 | 700 次 |
| music-cover | 100 次 | 700 次 |
| lyrics_generation | 100 次 | 700 次 |
| image-01 | 50 次 | 350 次 |
| coding-plan-vlm | 150 次 | 15,000 次 |
| coding-plan-search | 150 次 | 15,000 次 |

> ⚠️ **配额的"每日"按太平洋时区 00:00-23:59 滚动计算**

## 主公 API Key 存储位置
`/root/.mmx/config.json`

---

## 🎵 music-2.6 音乐生成指南

### 基本用法

```bash
# 有歌词歌曲
mmx music generate \
  --prompt "音乐风格描述" \
  --lyrics "歌词内容" \
  --out song.mp3

# 纯音乐（无人声）
mmx music generate \
  --prompt "音乐风格描述" \
  --instrumental \
  --out bgm.mp3

# 自动根据 prompt 生成歌词
mmx music generate \
  --prompt "关于夏天的流行歌曲" \
  --lyrics-optimizer \
  --out summer.mp3
```

### 歌词结构标签

在 `--lyrics` 中使用以下标签划分歌曲段落（标签内不要加描述性文字，会被唱出）：

| 标签 | 含义 |
|------|------|
| `[Intro]` | 前奏 |
| `[Verse]` | 主歌 |
| `[Pre Chorus]` | 预副歌 |
| `[Chorus]` | 副歌（高潮） |
| `[Interlude]` | 间奏 |
| `[Bridge]` | 桥段 |
| `[Outro]` | 尾奏 |
| `[Hook]` | 记忆点 |
| `[Build Up]` | 渐进 |
| `[Solo]` | 独奏 |

### 精细控制参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--vocals` | 人声风格 | "warm male baritone", "bright female soprano" |
| `--genre` | 音乐风格 | pop, folk, jazz, electronic |
| `--mood` | 情绪氛围 | warm, melancholic, uplifting |
| `--instruments` | 乐器编配 | "acoustic guitar, piano, strings" |
| `--bpm` | 精确节拍 | 95 |
| `--key` | 调性 | C major, A minor |
| `--structure` | 歌曲结构 | verse-chorus-verse-bridge-chorus |
| `--references` | 参考风格 | "similar to Ed Sheeran" |
| `--avoid` | 避免元素 | "no drums" |

### 可用音色（speech-hd / music-2.6 共用）

```
male-qn-qingse, male-qn-jingying, male-qn-badao, male-qn-daxuesheng
female-shaonv, female-yujie, female-chengshu, female-tianmei
male-qn-*-jingpin / female-*-jingpin 系列（精品高品质）
Chinese (Mandarin)_News_Anchor, Chinese (Mandarin)_Warm_Bestie
Chinese (Mandarin)_Gentle_Youth, Chinese (Mandarin)_Wise_Women
```

### music-cover 翻唱

```bash
mmx music cover \
  --prompt "Indie folk, acoustic guitar, warm male vocal" \
  --audio-file original.mp3 \
  --out cover.mp3
```

### 示例

```bash
mmx music generate \
  --prompt "Epic Chinese electronic pop, synths, emotional" \
  --lyrics "[Verse]
江山如画 云海苍茫
千年流转 风云再起
[Chorus]
赛博诸葛 运筹帷幄中
AI觉醒 铸造未来" \
  --vocals "warm male baritone" \
  --out song_01.mp3
```

---

## 通过 Hermes 发送微信图片（重要发现）

**关键**：微信发图片不能通过 URL，必须用 `send_message_tool` 直接发送本地文件。

### 正确方法

```python
# 在 /root/.hermes/hermes-agent 目录下执行
cd /root/.hermes/hermes-agent && python3 -c "
from tools.send_message_tool import send_message_tool

args = {
    'action': 'send',
    'message': 'MEDIA:/root/.hermes/workspace/cat_sunset.png',
    'target': 'weixin:o9cq801Q4BDVa20m46H0KTKRUOjo@im.wechat'
}
result = send_message_tool(args)
print(result)
"
```

### 坑点记录

1. **target 格式必须是 `weixin:chat_id`**，不能只传 chat_id
2. **message 中必须包含 `MEDIA:/path/to/file`**，且必须是本地绝对路径
3. **不能直接 import send_message_tool**（在 venv 环境外会找不到模块），必须在 hermes-agent 目录下执行
4. 返回 `{"success": true, ...}` 即成功，图片会作为微信原生附件送达

### 错误做法（已踩坑）

- ❌ 直接在消息中放 HTTP URL：`http://liupeizhi.top:6666/image.png` — 微信不支持直接下载
- ❌ target 不加 `weixin:` 前缀：`o9cq801Q4BDVa20m46H0KTKRUOjo@im.wechat` → `Unknown platform` 错误
- ❌ `send_message_tool(message=..., target=..., platform=...)` 传 kwargs — 必须传 dict