MiniMax Agent故障需逐层排查：先用--quiet和--output json确保MMX-CLI输出干净，再查Team Engine执行图谱定位红色失败节点及Verifier反馈，接着核实用量中心Token Plan额度与模型权限，最后验证工具注册名匹配及长任务是否启用--async异步模式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
MiniMax Agent工作流运行失败时，不能只盯着报错文字反复重试，必须按底层执行链路逐层排查：从CLI调用是否干净、Team Engine状态机是否卡死、Verifier验收逻辑是否触发死循环，到Token Plan额度是否耗尽——每一步都可能成为断点。
检查 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。
