如果 MiniMax Agent 出现异常或故障，建议按照顺序逐层排查问题。首先，执行命令时加入“--quiet”和“--output json”参数，这样可以确保 MMX-CLI 输出更加干净规范。接着，查看 Team Engine 执行图谱，重点定位红色失败节点以及 Verifier 返回的反馈信息。然后，仔细检查用量中心中的 Token Plan 剩余额度和模型权限是否充足。最后，还需要确认工具注册名称是否完全匹配，并验证长耗时任务是否启用了“--async”异步模式。
当 MiniMax Agent 工作流运行失败时，不能只盯着报错信息反复重试，而应沿着底层执行链路逐步定位问题。先检查 CLI 调用是否规范，例如是否添加了 --quiet 和 --output json 参数，确保 mmx-cli 输出纯净，避免进度条、颜色码或交互提示干扰 Agent 的结构化解析；同时也要验证输出内容是否真正可解析，可以将命令结果重定向到文件，再用 cat output.json | jq '.' 测试是否能正常解析。随后再排查 Team Engine 状态机是否卡住。MiniMax 的 Team Engine 由代码状态机驱动，任务失败时应优先查看状态日志，可在 Agent 桌面端右上角点击「调试模式」并开启「状态追踪」，找到失败工作流 ID 后点击「查看执行图谱」，观察各节点颜色含义（灰色表示未启动，黄色表示运行中，红色表示失败，绿色表示通过），再点击红色节点展开「Verifier反馈」与「Worker原始输出」两栏内容，判断二者是否存在语义冲突。如果 Verifier 连续三次拒绝同一 Worker 的交付结果，且反馈原因重复，就需要进入「Agent设置 → 角色契约」手动修正验收或校验规则；接下来还要确认 Verifier 的验收逻辑是否导致死循环；最后再检查 Token Plan 额度是否已经耗尽。MiniMax 当前将 CLI、API、Agent 共用同一份 Token Plan，但不同模态模型的消耗速度并不相同，因此可打开 agent.minimaxi.com，点击右上角头像进入「用量中心」查看。整个排查过程中，每一个环节都可能成为导致任务失败的关键断点。
检查 MMX-CLI 输出是否被干扰
Agent 依赖 stdout 的输出结果进行结构化解析，一旦混入进度条、颜色码或交互提示等内容，就很容易导致解析失败。
执行命令时务必加上--quiet和--output json参数，例如：mmx video-gen --prompt "夏日海滩" --output ./out.mp4 --quiet --output json。
【如果未加 --quiet，Agent 可能持续接收 stderr 乱码，进一步触发 Exit Code 127】
验证输出是否干净的方法是：将命令结果重定向到文件，再使用cat output.json | jq '.'测试能否被正常解析。如果报错“invalid JSON”，说明 CLI 仍然输出了面向人工阅读的信息，必须进一步关闭相关干扰输出。
定位 Team Engine 卡点位置
MiniMax 的 Team Engine 采用代码状态机驱动，并不是依赖 Prompt 临时编排，因此每个执行环节都有清晰的状态记录。任务失败时，应先查看状态日志，而不是直接重跑工作流。
第一步：在 Agent 桌面端右上角点击「调试模式」→ 开启「状态追踪」；
第二步：找到失败工作流 ID，点击「查看执行图谱」；
第三步：观察节点颜色——灰色表示未启动，黄色表示正在运行，红色表示失败，绿色表示通过；
第四步：点击红色节点，展开「Verifier反馈」和「Worker原始输出」两栏内容，重点比对二者是否存在语义冲突；
如果 Verifier 连续三次拒绝同一 Worker 交付物，且反馈理由重复出现（例如“缺少参考文献标注”），通常说明 Worker 与 Verifier 的验收协议没有对齐，此时需要进入「Agent设置 → 角色契约」手动调整校验规则。
验证 Token Plan 额度与模型绑定关系
MiniMax 已将 CLI、API、Agent 统一绑定到同一份 Token Plan，但不同模态模型的消耗速率差异明显。比如视频生成 1 秒消耗 320 credits，语音合成 1 分钟消耗 85 credits，而纯文本推理 1k token 仅消耗 1.2 credits。
打开agent.minimaxi.com → 点击右上角头像 →「用量中心」；
切换到「实时消耗流」标签页，筛选失败时间点前后 5 分钟内的数据，确认是否存在 credits 突然下降至 0 的情况；
如果额度充足，但某类模型仍显示“不可用”，则需要检查该模型是否被显式禁用：进入「设置 → 模型权限」，确认视频生成、语音合成等相关开关已经开启。
排查工具注册名匹配问题
Agent 调用外部工具失败时，90% 的原因都来自工具名称字符串不一致。尤其在 LangChain 0.2+ 版本中，系统不再自动扫描函数名，因此必须进行精确注册。
方法一：使用@tool装饰器定义工具，函数名就是注册名，例如@tool def fetch_stock_data(...) → 注册名为fetch_stock_data；
方法二：手动构造 Tool 对象时，name字段必须与 LLM 生成的调用指令中的工具名完全一致，包括大小写及下划线；
【工具名如果包含空格或中文，通常会直接导致匹配失败，建议统一转换为 snake_case】
方法三：在 Agent 初始化时打印agent.tools列表，确认目标工具确实已存在于该列表中，而不是仅完成定义却没有真正传入。
处理长耗时任务挂起
MMX-CLI 默认采用同步阻塞方式运行，如果 Worker 执行超过 120 秒仍未返回结果，CLI 会主动退出并返回 Exit Code 142，随后 Team Engine 会据此判定任务失败。
针对视频生成、批量音频合成等长耗时任务，必须启用异步模式：--async参数；
启用--async后，CLI 会立即返回 JSON 格式的任务 ID 和状态查询 URL，Agent 就可以通过轮询该 URL 获取最终结果；
如果依旧失败，还要检查后台任务是否被系统 kill：可在终端执行mmx job list，确认任务状态到底是failed还是running；
当状态显示为failed时，执行mmx job logs --id [TASK_ID]查看真实报错——常见原因包括 GPU 显存不足引发 OOM，这时可以尝试降低--resolution参数，或启用--mixed-precision来优化资源占用。