MiniMax Code

English | 简体中文

运行在终端里的 AI Coding Agent。 MiniMax Code 能理解代码库、修改文件、执行命令和测试，并把每次工作保存在可继续的 Session 中。

你可以在交互式 TUI 中与它协作，也可以通过 Headless 模式接入脚本和 CI，或连接支持 ACP 的客户端。

快速开始

CI Review 开启超时恢复后，orchestration.json 记录共享预算起点与截止时间，以及两轮的获配超时、开始/结束时间、剩余预算和执行状态；两轮 stdout、stderr、最终回答和 diagnostics 分开保留。确认恢复生效需要同时核对会话身份、停止证据与正式 schema 结果，不能只看总结文本。总结成功仍属于 budget_limited，不代表完整审查通过。

需要 Node.js 22.19+（Node 22）或 Node.js 24–26。

npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 --registry=https://registry.npmjs.org/
cd your-project
mcode

启动后，直接描述你想要的结果：

帮我定位登录接口偶发 500 的原因，修复后运行相关测试。

MiniMax Code 会检查代码库、完成修改、运行能够执行的验证，并汇总已经确认的结果。

运行状态行、单轮结束后的耗时和 Goal 计时统一使用 s / min / h，例如 30s、9min30s、2h9min30s；超过一小时仍显示秒。运行耗时统计当前轮，Goal 统计累计 active 时间，两者数值可以不同。

清理文件与组合命令

在 macOS / Linux，Agent 的 rm 会转交给回收站程序。Shell 仍负责展开通配符和变量、处理引号和重定向；例如 rm -f "$DIR"/*.png 2>/dev/null && npm run build，清理成功后才执行构建。-f 下不存在的文件、空参数和重复目标不会中断后续命令；真实的移动失败仍返回非零退出码。目录需要 -r，当前目录、主目录及其祖先仍受到保护。

没有启用沙箱时，包含变量或通配符的删除需要明确授权；--permission full 属于明确授权。命令替换、进程替换等会执行代码的参数继续使用保守检查，不承诺兼容全部 Shell 语法或所有 rm 扩展选项。

模型、Provider 与终端设置

交互模式支持 mcode -m custom_provider:work/model-id，只修改本次打开或创建的 Session，不改变全局默认模型。可与 --continue 或 --session <id> 配合；无 ID 的 Session 浏览器不能同时指定模型。

mcode provider add --name Work --base-url https://example.com/v1 \
  --api-format openai-completions --model vision-model \
  --context-limit 128000 --output-limit 8192 --support-image --use

API Key 从 MCODE_PROVIDER_API_KEY 或 --api-key-env 指定的环境变量读取。--use 先测试第一个模型，成功才保存并选为默认；失败不保存。不带 --use 可先保存后在 /provider 测试。Token 上限必须是正整数；--support-image 显式声明图片输入能力，不凭模型名字猜测。Preset 中明确声明的 reasoning effort 档位会显示在 /model 中。

第三方 relay 的自定义 header 配置位于 custom_provider.<id>.options.headers，例如 headers: { HTTP-Referer: "https://example.com", X-Title: "My CLI" }；请保留已有 provider 和模型配置。不要把 header 中的凭据放进命令行参数或问题反馈。 第三方 Provider 的模型请求默认携带 User-Agent: MiniMaxCode；在上述 headers 中配置 User-Agent 可替换为 relay 要求的值。

Fullscreen Transcript 提供可点击、拖动的滚动条。/statusline 可选择默认关闭的 context-meter 显示剩余上下文刻度，详情见 状态栏配置。

Ghostty 的 Option 组合键需要启用 macos-option-as-alt = true 后重新加载配置或新开终端。权限提示中的 Option 与其他平台的 Alt 对应；终端仍未发送组合键时，可用方向键选择并按 Enter 确认。

内部包的 Codex 登录

在 /provider 选择 OpenAI Codex，或在 /model 选择 Connect OpenAI Codex，再选择登录方式：

• Browser login：在当前电脑的浏览器完成登录。
• Device code login：适用于 SSH、远程开发机。终端显示授权地址和一次性验证码，在自己电脑的浏览器打开地址并输入验证码。开发机会自动完成登录并刷新模型列表。

Device code 需要在 ChatGPT 安全设置或工作区权限中开启。浏览器无法自动打开时，可手动访问终端里的地址。按 Esc 取消本次授权；验证码过期后可按 Enter 重试。

为什么选择 MiniMax Code

| 能力 | 你可以获得什么 | | ------------ | ------------------------------------------------------ | | 理解代码库 | 搜索文件、追踪调用链、解释架构，并在修改前分析影响范围 | | 完整执行任务 | 修改代码、执行命令，并使用项目自己的工具验证结果 | | 随时继续 | 每个任务都保存在 Session 中，可以从上次停止的位置继续 | | 保持控制 | 先审阅计划，再根据操作风险选择合适的权限模式 | | 适配工作流 | 使用交互式 TUI、结构化 Headless 输出或 ACP 集成 | | 灵活扩展 | 选择模型和 Provider，并通过 Plugin 增加新能力 |

新建自定义 Provider 时导入模型

在 /model 选择 + Add 3rd-party model → Custom provider，依次填写名称、Base URL、协议和 API Key， 再选择 Import models from /models。导入使用当前填写的 Key，不会立即保存配置；搜索并选中一个模型， 连接测试成功后才保存全部导入模型并选用该模型。若导入失败或列表为空，可重试、按 Esc 修改 Key， 或选择 Enter a model ID manually 手动填写模型 ID。

刷新第三方模型与编辑连接

在 /provider 选中第三方连接，按 r 使用已保存的 API Key 从该连接的模型列表接口获取最新模型。刷新只补充新模型，保留 provider ID、Key、已有模型的开关与自定义参数，也不会切换当前模型。完成后在 /model 选择新模型。查询失败时原配置不变；如果连接在刷新期间被其他窗口修改，请重新打开 /provider 后再刷新。

按 e 可以修改第三方连接的 API Key、Base URL、模型 ID 列表或别名。修改先通过连接测试再保存，测试或保存失败时继续使用原配置；更换 Key 成功后，该连接下所有模型使用新 Key。

在 /model 的“添加第三方”选择已配置的服务商时，默认提供“使用已有连接”，无需重新输入 Key，可选择或补充模型。只有明确选择“添加另一个账号”才创建新连接，并要求填写用于区分账号的别名。

按你的方式使用

交互式 TUI

在当前目录启动：

mcode

也可以在启动时直接附带任务：

mcode "解释这个项目的架构，并指出最值得先处理的技术债。"

MiniMax Code 工作时，按 Enter 将输入内容 steer 给当前 Turn；按 Alt+Enter 会把后续任务放进 Queue，留给下一 Turn。已经排队的最新消息可用 Option+↑（其他平台显示为 Alt+↑）或 Shift+← 召回 Composer，再按 Enter steer。

粘贴或引用图片后，Composer 用 [Image #1] 标出编号，并在输入框上方显示预览。继续输入或移开光标会收起预览；用左右方向键移回图片标签即可再次查看。Esc 收起；Enter 仍按当前状态发送或 steer，不会打开图片。

macOS/Linux 终端粘贴带空格的图片绝对路径时，支持直接粘贴、用外层引号包裹 （如 "/path/Screenshot 2026.png"），或使用裸转义路径（如 /path/Screenshot\ 2026.png）。 裸路径中的 \ 和 \\ 可还原为空格和反斜杠；外层引号内的反斜杠按文件名字符处理。

空输入框连续按两次 Esc 或使用 /edit 编辑上一条消息时，图片会恢复为可操作的 [Image #1] 标签，支持删除、撤销和重新发送。当前进程内最近一次带附件提交会保留原标签位置； 没有本地编辑快照的历史消息会在正文末尾重建标签。只有资源 ID、没有可读本地文件的图片仍保留标签和元信息。

支持 Kitty 图片协议的终端以及 regular 模式的 iTerm2 可以显示图片；其他终端显示格式、尺寸和大小。预览最多读取 20 MB、处理 2500 万像素，超限、格式不支持或读取失败时保留文字信息和原附件。预览副本不影响原图发送，也不自动去重。

常用 Session 命令：

# 继续当前 workspace 最近的 Session
mcode --continue

# 浏览 Session，或按 ID 打开
mcode --session
mcode --session <session-id>

在 TUI 中，/sessions 会打开 Session Center，统一浏览最近/已归档 Session、切换当前 workspace/全部范围、重命名、归档/恢复和搜索。搜索既支持普通文本，也支持 id:、path:、type:、status:、model: 筛选。 /history 会打开当前 Session 的输入历史，可以先预览影响范围，再通过现有确认流程创建分支、编辑历史输入、仅回退会话，或同时回退会话与文件。回复运行期间，历史记录保持只读浏览。

在 TUI 中使用 /export，可以把当前 Session 导出为 Markdown。

使用 /review 可以审查当前 workspace 中 staged、unstaged 和 untracked 的本地改动。审查结果会在 Transcript 中以通过摘要或带文件位置的 findings 展示。

本地构建的 CLI 可以从任意仓库目录启动；Review 的内置 prompt 从安装包资源加载，不依赖源码仓库的工作目录。TUI /review 和 mcode exec review 在未配置 review.mode 时默认使用 inline，在当前 Turn 内完成审查。显式配置 review.mode: subagent 时仍使用子代理；此默认值不改变 Electron 的行为。TUI 启动层通过内部 reviewPromptDir 参数提供唯一资源目录；npm 包使用包根目录下的 assets/prompts/code-review/，源码运行使用相邻 local-runtime package 的资源目录。读取失败会报告具体路径并保留原始错误，不再尝试工作目录中的其他副本。

使用 /btw [问题]（或 /side [问题]），可以从最近一个已提交的会话边界 fork 出一个临时侧会话，主任务继续运行且不会被中断。侧会话以只读上下文继承主会话历史，工具权限保持与当前会话一致，并被要求除非你明确请求，否则不做任何修改；侧会话沿用主会话的当前权限模式，不追加独立确认；Full access 下无需额外确认，其他模式仍按正常权限规则处理。按 Ctrl+/ 可在侧会话与主会话视图之间来回切换而不结束任何一方（在侧会话中执行 /parent 也会回到主视图）；处于侧会话视图时，Composer底部会同步主任务状态（例如 main needs approval、main finished）。在空 Composer 中按 Ctrl+C 会关闭并丢弃侧会话。回到主视图后再次执行 /btw，会丢弃旧侧会话并从当前边界重新fork。侧会话是临时的：不会出现在 /sessions 或 /resume 中，切换到其他 Session 时会被自动清理。侧会话中的模型请求失败且可重试时，可以直接运行 /retry 重发侧会话的最后一条消息，无需先回到主会话；也可以直接运行 /doctor 检查配置，或用 /feedback 提交反馈。

切换快捷键只切换已创建的侧会话，不会创建侧会话。尚未执行 /btw 时按切换快捷键，Composer 会用黄色警告提示先运行 /btw。

无参数的 TUI slash 命令只在命令名后没有正文时执行（允许尾随空白）；如果继续输入正文，整句会作为普通提示词发送。接受参数的命令仍按命令处理。

Composer 会把当前输入标记为 Prompt、Command、Shell 或 Skill，并同步提示按下 Enter 后是发送、执行还是调用。例如，/context 是命令，/context 解释这个项目 是普通提示词；/docs 解释 API 这类 Skill 输入则会显示为带 instructions 的 Skill 调用。

Agent Team 与 Runtime 后台任务会在 Composer 上方合并为一条按严重程度排序的 Tasks 摘要，避免长程 Session 因任务累积而持续挤占输入空间。使用 /tasks 可打开统一详情视图，查看当前完整列表和状态；按 Enter 可打开 Agent 子 Session 的 Transcript；近期已完成的 Runtime 任务在结果交付后仍会保留，但不会让 Composer 摘要持续显示。任务状态仍由 Runtime 持有，Ctrl+T 仍用于打开 Todo 计划。后台任务详情优先展示失败错误，并按终端宽度换行显示完整 Bash 命令（保留原始换行）；可用 PgUp/PgDn 滚动、Esc 返回列表。旧任务若没有保存完整命令，只展示已有 Description 摘要。

轻量对话

对于简单对话或通用知识问答，可用 --mode lightweight 创建新会话：

mcode --mode lightweight "解释 DNS 缓存的工作原理。"
mcode exec --mode lightweight "概述 CAP 定理。"

轻量模式只发送精简的对话系统提示词，不发送工具 schema，并从提供方上下文中省略工作区指令、Skills、memory 块、MCP schema 和完整环境块，因此不能检查或修改本地文件。需要编程或工具能力时，请使用 mcode --mode standard 或 mcode exec --mode standard 创建新的标准会话；省略 --mode 与标准模式完全一致。

模式在根会话创建时固定，因此 --mode lightweight 不能与 --session 或 --continue 同时使用。子代理/子会话不会继承轻量模式，/compact 仍使用标准压缩上下文，ACP 与 Desktop 会话也始终使用标准模式。重新打开轻量会话时会保留该模式，并在 TUI 状态栏显示 Lightweight；从轻量模式启动的 TUI 打开标准会话时仍保持标准模式，且不显示该标记。

直接执行终端命令

在 TUI 输入 !pwd 或 !git status 后按 Enter，立即在当前会话的工作目录执行命令，实时显示标准输出、标准错误和退出码。输入框会显示 Shell · Enter run。执行记录以独立的金色边框区块展示，分为命令、输出和状态三部分；失败状态显示红色，!! 区块标记 Local only。按 Esc 或 Ctrl+C 中断命令；退出 TUI 会清理命令进程。

已结束的 Shell 区块保留到下一轮对话开始，随后从界面清除，不会在后续回复结束或历史刷新后重复显示；! 与 !! 均遵循这一规则。

Shell 模式按 Tab 请求补全。只有 ! 或光标位于命令名开头时，不显示候选；输入命令和空格后，按 Tab 列出当前目录的文件和文件夹，! cat 与 !!cat 均支持；删除 ! 退出 Shell 模式时立即关闭候选并取消补全请求；输入 ./ 后按 Tab 可以浏览当前目录。候选包含本机 PATH 中的命令名和当前会话目录下的文件、文件夹；cd 只提示文件夹。支持 !、!!、相对路径、绝对路径与 ~/，带空格和特殊字符的路径自动转义。用 ↑/↓ 选择候选，Tab 填入；Enter 始终执行当前输入，候选菜单打开或用方向键选中候选时也保持这一行为；只有 Tab 填入补全，Esc 关闭菜单。粘贴后可按 Tab 请求补全。补全过程只读取本地目录，不调用模型、不执行草稿；补全范围为命令名和字面路径，目录候选以当前会话工作目录为基准。

!命令 的结果随当前会话的下一条消息交给模型，执行命令本身不会发起模型请求。!!命令 仅在 TUI 显示输出。发送下一条消息前，结果保存在当前 TUI 进程内；退出 TUI 后，这部分结果随进程释放。输出和待发送上下文各保留最近 64 Ki 字符，超过时显示截断提示。

Shell 从提交清理到执行结束均与 Agent 消息保持互斥，期间提交的新输入保留为草稿。携带命令结果的消息在 Runtime 接收前取消或失败时，结果随草稿保留；首次创建会话后失败，结果仍归属该会话。Runtime 已接收消息后取消，后续消息不会再次携带同一份结果。

每条命令启动独立 Shell，cd 和 export 的效果限于该条命令。macOS 使用 Bash，Windows 沿用运行时的平台 Shell 选择，优先使用 PowerShell。命令以当前操作系统用户权限执行；交互式终端程序需要在外部终端运行。

Agent 回复或交互处理完毕后可执行命令。命令执行期间，新提交会保留为草稿；包含附件的输入需要移除附件后执行。

网络代理

MiniMax Code 读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 及其小写形式， 无需设置 NODE_USE_ENV_PROXY。例如：

HTTPS_PROXY=http://127.0.0.1:7890 mcode

交互会话、exec、更新下载和 Matrix 工具请求（包括长时间生成请求）使用相同代理规则。 localhost、127.0.0.1、::1 始终直连。 TUI 代理和更新下载创建的连接使用 HTTP/1.1；HTTP 和 HTTPS 目标都通过代理的 CONNECT 隧道访问。

TUI 和内置 Pi runtime 使用 Undici 8.10.0；agent-tools 保留 Undici 6。 TUI 启动时为两代 dispatcher API 安装代理；Matrix 长请求沿用宿主 dispatcher 的路由，仅延长超时。 npm 构建按声明版本分别去重，并检查所有 chunk，拒绝额外的 Undici dispatcher 实现。

Headless 与 CI

mcode exec 可以在不打开 TUI 的情况下执行任务：

# 执行一次任务
mcode exec "审查当前改动，并运行相关测试。"

# 指定代码库并附加上下文
mcode exec --cwd ./repo --file error.log "定位这次构建失败的原因。"

# 输出机器可读 JSON
mcode exec --output-format json "总结当前分支。"

# 只为本次 Run 提高思考强度
mcode exec --model custom_provider:work/deep-reasoner-1 --effort xhigh "规划这次迁移。"

# 审查当前 workspace 的本地改动
mcode exec review --cwd ./repo

--effort 只对本次 Run 生效，与 --model 相互独立；单独使用时作用于当前 Session 的模型。启动前会用 模型声明的可选强度校验该取值，因此不支持的强度或不支持强度选择的模型会以非零退出码明确失败，而不会 退回到别的强度继续执行。该覆盖不会写回 Session，用 --session 或 --continue 恢复时仍是 Session 自身的强度。

思考强度不是模型变体。--model provider/model#xhigh 的行为保持不变，仍然可以正常运行，但 Runtime 会把 该后缀当成模型身份的一部分并按自身默认强度执行，请求的强度会被静默丢弃。需要强度确实生效时请使用 --effort xhigh。

自动化场景还可以使用 --output-schema 约束最终回答、使用 --output-last-message 写入文件，或通过 --output-format stream-json 流式读取进度。

mcode exec review 固定审查 staged、unstaged 和 untracked 的本地改动，支持 --cwd、--model、 --effort、--config、--permission、--timeout、--max-steps、--output-format 和 --output-last-message。发现问题仍返回退出码 0；只有调用、Runtime 或审查结果协议失败才返回非零退出码。

上述 Review 参数可以放在 review 前后；同一个参数两处都指定时，以 review 后的显式值为准。 --session、--continue、--input、--input-format、--file、--output-schema 和 --diagnostics-dir 不支持用于 exec review，放在 review 前也会报错。

用 --prompt-mode 选择评测使用的 Prompt，默认 tui：

mcode exec --prompt-mode work "完成本次评测任务。"

可选 tui、coding、work，每种模式各使用一个完整模板，包含身份、规则与按当前开关渲染的 Memory 条件段。运行期间使用固定的随包 Prompt 内容，工具和权限沿用当前 TUI 配置。评测快照记录实际 Prompt、模式、版本及内容摘要。续跑 Task 需要保存的模式与所选模式匹配；历史 Task 缺少模式信息时，为评测新建会话。 --prompt-mode 用于普通 exec 任务。

需要替换或追加主 Agent 的 System Prompt 时，交互式 TUI、exec、exec review 和 mcode acp 都支持以下参数：

# 替换身份段（内置角色与模式正文），运行规则、项目指令、Environment、Memory 和 Skills 保留
mcode --system-prompt-file ./identity.md

# 在身份段之后追加内容
mcode exec --append-system-prompt "回答前先列出要修改的文件。" "完成本次任务。"

--system-prompt 与 --system-prompt-file 二选一，--append-system-prompt 与 --append-system-prompt-file 二选一；替换和追加可以同时使用。文件在启动时读取一次，相对路径按当前目录解析， 读取失败或内容为空会直接报错。写在 exec、exec review 或 acp 前面同样生效；替换和追加分别取离子命令最近的那一处，内联文本和文件算同一项，例如 mcode --system-prompt-file a.md exec --system-prompt "..." 使用内联文本，不读取 a.md。login、init 等其他子命令遇到这些参数会直接报错。参数只对当前进程生效，不写入 Session 或配置；Task 子 Agent 不受影响。

运行 mcode exec --help 查看完整的 Headless 参数。

Exec 诊断与超时恢复

使用 --diagnostics-dir <空目录> 显式保存执行诊断。相对路径基于 --cwd 解析，已有非空目录会被拒绝，避免覆盖前一次证据。

mcode exec --cwd ./repo --output-format json --output-schema ./review-schema.json \
  --diagnostics-dir ./attempt-1/diagnostics "审查当前变更"

目录中包含执行信息、模型/工具进度、最终回答来源，以及失败时脱敏且限长的原始回答。诊断不混入 stdout；运行中写入失败只告警，不替换原始执行错误。未指定该参数时行为不变。

JSON 校验失败仍返回失败，不会自动修复或转换为通过。--output-last-message 仍只保存成功结果。

普通 Exec 已支持 --session <id>。超时恢复必须等原执行停止，使用相同 Runtime 数据目录、配置和 workspace，在指定 session 中追加总结指令；不要用 --continue 猜测会话，也不要重发整个原任务。

CI review:mcode 的诊断和一次超时总结分别由 MCODE_REVIEW_DIAGNOSTICS=1、MCODE_REVIEW_TIMEOUT_RECOVERY=1 控制。恢复开启时会同时采集诊断，以停止确认和 shutdown 结果作为恢复前提。两轮共用总预算，分别保存产物。恢复总结即使 JSON 合法、findings 为空，也标记为预算受限并保持节点非成功。

恢复开启时，CI 为调查轮和总结轮各预留启动 30 秒、清理 75 秒、进程终止宽限（默认 10 秒）和日志落盘 5 秒；总结执行默认预留 180 秒，其余预算用于调查。各轮使用绝对截止时间，启动和落盘耗时不会延长预算。若清理超出本轮预算，CI 终止该子进程并保留已有诊断，不启动恢复；剩余时间不足以覆盖总结执行及收尾时同样跳过总结。恢复关闭时仍按单轮预算执行。这些限制只属于 CI 脚本，不改变普通 TUI、Exec 或 ACP 的 Runtime 退出策略。

CI 默认安装 @minimax-ai/code@latest。上述开关默认关闭，需确认实际安装版本包含新参数与停止凭据后启用；启动时会检查 CLI 参数能力，不支持时直接失败。诊断可能含业务代码，须限制 GitLab artifacts 访问权限与保留时间。

模型请求超时与图片上限

每次模型请求都有首个响应时限：Provider 接受请求后 300 秒内没有任何响应时，本次尝试会中止并按可重试超时处理，走常规模型请求重试，而不是等满 20 分钟的整体请求上限。收到首个响应事件后，流连续 60 分钟没有模型事件也按同样方式失败；SSE 心跳不计入，以便兼容“长思考生成完成后才下发响应”的网关。已经开始输出可见内容时，本轮直接失败，不再重试。可用 MCODE_LLM_FIRST_EVENT_TIMEOUT_MS 和 MCODE_LLM_STREAM_IDLE_TIMEOUT_MS 以毫秒覆盖这两个时限，设为 0 表示关闭。超时错误会写明触发的是哪项设置，20 分钟整体上限仍然有效。

单次模型请求默认最多携带 100 张图片（MiniMax M3 系列为 20 张，Mistral API 为 8 张），图片数据最多占请求体上限的三分之二。请求体上限取模型的 max_request_body_bytes；未配置时 https://api.anthropic.com 为 28 MiB，api.openai.com 为 64 MiB，其他地址（包括网关）为 64 MiB。超过任一上限时，只在本次请求里去掉最早的图片，直到降到上限的一半，历史中仍保留这些图片。提示缓存要求前缀不变的模型 不做这项限制，所以每次请求都携带历史里的全部图片。Provider 因体积、图片或上下文长度拒绝请求，或请求在发出前就超过请求体上限时，先压缩一次上下文再重发。这次压缩会把历史中的全部图片移出并一定生成摘要，包括你附加的图片，每张换成一行写明文件路径的说明（没有路径的图片先保存到会话的 tool-outputs 目录）；因上下文长度或工具输出过大触发的压缩不移出图片；提示缓存要求前缀不变的模型不会仅因请求体大小触发压缩，只有被拒后才压缩；超过上下文长度触发线时直接生成摘要，不先归档工具输出。对提示缓存要求前缀不变的模型，只归档或删除工具输出、保留之前轮次的压缩会同时删除这些轮次的 thinking 块，因为前缀改写后其签名不再有效；生成摘要的压缩不保留之前的轮次，摘要请求使用自己的 system prompt，因此也不携带 thinking。上下文摘要请求不携带图片，每张图片都换成写明文件路径的说明；生成的摘要末尾附上会话的 snapshots（每次压缩前的完整历史）和 reports/tool-outputs（工具图片与输出）两个目录。请求体上限更低的网关（例如 Bedrock 的 20 MB）应配置 max_request_body_bytes；Provider 允许的单次图片数更少时，可在模型上设置 max_images_per_request：

custom_provider:
  my-vision-provider:
    models:
      my-vision-model:
        capabilities:
          support_image: true
          max_images_per_request: 8

你附加的图片和工具结果图片在进入对话前都会先编码：宽或高超过上限的等比缩小，并在图片后附上原尺寸说明；base64 数据超过上限的先换编码，仍超限再继续缩小，直到满足上限。上限在 config.yaml 中配置，每张图片编码时读取当前值，修改后不需要重启：

requestMedia:
  image:
    max_width: 2000 # 像素，默认 2000
    max_height: 2000 # 像素，默认 2000
    max_base64_bytes: 3670016 # 单张图片的 base64 字节数，默认 3.5 MiB，最大 5 MiB

这是唯一一次缩放：Read 工具、附加的图片和 Browser 截图都交出原图，在上限内的图片原样发送，被缩小的图片只带一条说明。Browser 操作后自动截取的截图不超过 1280 px 和 1 MiB，上面的上限更小时以其为准。图片处理组件无法加载时，超过上限的工具结果图片会替换为一条说明。图片处理组件无法解码的图片（损坏、截断或格式不支持）不会进入对话，否则之后每次请求都会带上它并失败：工具结果里的这类图片替换为一条写明类型和大小的说明，你附加的这类图片不内联发送，只保留文件路径。

图片数量、体积或尺寸超限、报错中带有 413、HTTP 400 invalid_request_error 等确定性拒绝不再重试；体积、图片和上下文长度类拒绝直接走上面的压缩恢复。

Browser 操作

MCode 的交互式 TUI、mcode exec 和 ACP 共用同一个进程内 Runtime 生命周期。原生无头 Browser Provider 可以让 Agent 通过自然语言打开网页、检查可交互元素、点击、输入、滚动、截图和下载。Browser Use 默认关闭，必须通过 beta 开关显式启用。可选的 Browser 配置只负责指定 Chrome 路径：

# $MINIMAX_DATA_DIR/config.yaml
beta:
  browserUseTooling: true
browser:
  chromePath: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

系统能够自动发现 Chrome 时，可以省略 browser.chromePath，但仍需保留 Browser Use 的显式开启配置：

beta:
  browserUseTooling: true

MINIMAX_DATA_DIR=/tmp/mcode-browser-real mcode

进入 TUI 后可以输入：

请使用 Browser 打开 https://example.com，告诉我页面标题并截一张图。

非交互场景同样运行 mcode exec "..."。MCODE_CHROME_PATH 可在单次启动中覆盖 browser.chromePath；否则 macOS、Linux 和 Windows 会自动查找常见的 Chrome/Chromium。 MCODE_BROWSER_BACKEND 不再需要，也不再控制启停。Linux root 环境会自动为 Chrome 添加 --no-sandbox，无需额外配置即可使用 Browser；非 root Linux 环境仍保留 Chrome 进程沙箱。native Headless 能力要求 beta.browserUseTooling: true；beta.filePanelBrowser 只控制 Electron FilePanel Provider。模型侧的 navigate / open_tab 只接受 HTTP(S) URL；file:、data: 等本地或内联 scheme 会在启动 Chrome 前被拒绝，上传本地文件应使用经过 workspace 授权的 Browser upload 输入。

无可用 GPU 的 WebGL 测试

在虚拟机或 CI 中，如果页面能打开，但 Three.js 报 Error creating WebGL context，可在启动 TUI 前设置 MCODE_BROWSER_USE_SWIFTSHADER=true，让 Browser 使用 Chrome 自带的 SwiftShader 软件渲染。此开关不会启用 Browser Use，仍需上面的 beta.browserUseTooling: true。支持该开关的 TUI 版本在 Vela 中可以使用以下 agents[].harness.env：

{
  "MCODE_TUI_BROWSER": "true",
  "MCODE_BROWSER_USE_SWIFTSHADER": "true"
}

MCODE_TUI_BROWSER 由 Vela 的执行适配器处理；本地运行仍使用上述 YAML 开启 Browser Use。SwiftShader 开关只接受 true（忽略大小写及首尾空白），未设置或其他值保持 Chrome 默认渲染方式。旧 TUI 版本不会识别该开关；需使用包含此功能的构建，单独改 env 不会给旧版本补上能力。

该模式添加 --use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader，仅用于受信任的本地页面测试；Chrome 的说明见 SwiftShader 文档。它用 CPU 绘图，适合验证画面和交互，不适合测游戏帧率；不会额外关闭 Chrome 进程沙箱。镜像已包含支持 SwiftShader 的 Chrome 时，不需要更换镜像或安装独立渲染库。

脚本化输入（run_script）

Headless Browser 还提供 browser 的 run_script 动作，用于单步动作表达不了的检查：按住按键移动、修饰键加鼠标组合、定时或重复输入，以及先读页面状态再决定点哪里的循环。Agent 传入异步函数体 code，或工作区内的 .js/.mjs 文件 path（脚本可保留后重跑），可选 timeout（1000–120000 ms，默认 30000）。脚本直接操作当前 Browser 标签页和登录状态，不另起 Chrome，也不需要安装 Playwright。

脚本可用 page.keyboard、page.mouse、page.waitForTimeout、page.waitForFunction、page.evaluate、page.screenshot、page.consoleMessages、assert 和 console。脚本本身运行在隔离的 worker 中，没有 Node.js、文件系统和网络 API。page.evaluate 不同：它在页面内执行 JavaScript，拥有该页面的全部能力，包括带当前会话 Cookie 的 fetch（同站请求会自动携带 HttpOnly Cookie）和页面存储访问。对它打开的页面而言，run_script 与 Agent 的 shell 工具信任级别相同。Headless Browser 每个会话使用独立 profile，不支持导入 Chrome Profile，其中的 Cookie 只来自 Agent 自己浏览产生的登录状态。

脚本结束、出错、超时或被取消时，仍按住的键和鼠标键都会在页面上松开；松开事件无法送达时会重建 Browser 会话。结果包含返回值、日志、失败的脚本行号、页面错误、最多 4 张脚本截图加 1 张失败截图，以及每个 page.evaluate 调用位置，审阅时能分清真实输入和页面状态读取。Electron FilePanel Browser 不提供 run_script。

MCP 冷启动发现预算

stdio MCP 在 turn 工具发现阶段的默认总预算为 30,000 ms，为首次启动需要安装依赖的 Server 预留更多时间。预算包括连接准备、进程启动、initialize 和 tools/list；实际预算仍为该默认值与 单个 Server 的 mcp.json timeout 的较小值（毫秒，Server 默认 120,000）。 远程 HTTP/SSE 的发现预算仍为 2,000 ms，工具调用超时及发现失败时返回空列表的既有行为不变。 故障 stdio Server 因此最多可能使 turn 等待 30 秒。需使用包含此改动的构建，无需新增环境变量。

ACP 客户端

通过 stdin/stdout 启动 Agent Client Protocol 服务：

mcode acp

支持 ACP 的编辑器和 Agent 客户端可以通过它创建、加载、继续和关闭 MiniMax Code Session。

模型、Provider 与 Plugin

登录 MiniMax：

mcode login

使用 TUI 的 /logout 或命令行 mcode logout 退出当前地区的共享账号。退出后会显示完整的浏览器登出链接，并尝试打开默认浏览器；在开发机、SSH 或无图形界面环境中，可复制链接到自己的浏览器完成网页登出。账号登出完成后，发起浏览器打开请求即返回，完整链接会保留在终端中供手动打开。链接按当前地区及运行环境选择，与桌面端的登出页保持一致。

安装 @minimax-ai/code 时会同时安装 mcode 和 mcode-tools 两个命令；无需先启动 TUI，mcode-tools 就会出现在 PATH 上。

在 TUI 创建的进程内，mcode-tools 通过 TUI 的 Auth Lease Broker 获取短期 Access Token，不会读取宿主 auth.json、持久化 Refresh Token，也没有独立的登录/登出流程。命令不会随登录态安装或删除；没有共享的 MCode 登录态时，broker 调用会因需要认证而失败。在 TUI 进程之外仍可直接调用 mcode-tools；TUI 不会改写该进程的环境或配置。

TUI 启动不再批量迁移历史会话的模型。指向官方网关的 custom_provider:minimax-legacy 及编号别名会在模型列表和执行时解析到可用官方模型；同名模型不可用时尝试官方默认模型。列表读取不写配置，新会话按解析后的默认模型创建；使用会话当前选择发送消息时原子保存会话和冻结 binding 的恢复结果，若用户已改选则拒绝过期恢复。排队消息中的旧引用不会覆盖会话后来选定的模型，真实自定义服务仍按 BYOK 解析。共享 dataDir 的 Desktop 也需升级到移除旧启动迁移的版本。

响应失败或被停止后，尚未执行的 Queue 消息会保留并显示暂停状态。运行 /queue 后按 c 可从队首继续；也可以编辑、恢复或删除待发送消息。暂停时发送新消息，可选择先发送新消息再继续原队列，或清空待发送消息后发送；取消选择会保留草稿。重新打开会话会显示暂停队列，等待主动继续。

进入或退出 Plan 的下一条消息也使用上述恢复选择。选择 Keep my draft 或按 Esc 后，草稿可继续编辑、重新发送，不会发布本次发送的结果；尚未生效的 Plan 切换会保留。如果恢复发送时会话已经被另一轮占用，草稿会保留并提示失败，由用户再次发送。

已有对话中成功切换 Provider 或模型后，Transcript 会显示一次黄色提示，提醒可能无法复用之前的缓存、并产生额外花费，不展示具体金额。初次选择、重复选择同一模型和仅调整推理强度不显示该提示。

在 TUI 中使用 /model 选择模型和推理强度。支持多个上下文档位的模型（如 M3 的 512K / 1M）可用 Tab / Shift+Tab 切换上下文，左右键仍调整 Thinking / effort。Enter 同时应用到当前会话并保存模型、上下文和 effort 为默认值，Esc 放弃本次调整；重新启动后会恢复已保存的选择，新会话从首次发送开始继承默认上下文窗口和 effort，已有会话保留自己的选择。 普通默认状态栏持续显示上下文总容量（如 Context 1M / Context 512K）；已自定义状态栏可通过 /statusline 启用 context-window。 默认 effort 保存在当前 profile 配置的 defaultModelThinking.effort，与桌面端首页使用同一份配置；桌面端已有会话内的调整仍只作用于该会话。 未保存选择时优先采用模型目录的 defaultEffort，再回退到可选档位的中间值；固定默认 effort 只读显示，不提供档位切换。关闭 Thinking 时不应用 effort。 1M 等较高用量档位会显示提示。选择 Add 3rd-party provider… 可从 models.dev 搜索已知 Provider 和模型，或配置 Custom Provider。API Key 在表单中保持掩码，Runtime 会先测试连通性，成功后才保存并应用所选模型。使用 Provider 命令查看或配置模型来源：

mcode provider list
mcode provider test <provider-id>
mcode provider add --name <name> --base-url <url> --model <model-id>
mcode provider remove <provider-id> --yes

通过命令行浏览和管理 Plugin：

mcode plugin list --available
mcode plugin add <plugin-id>
mcode plugin enable <plugin-id>
mcode plugin disable <plugin-id>

直接运行 mcode plugin 会打开交互式 Plugin manager。

计划与权限

Plan Mode 允许你在修改代码前先审阅实现计划。权限模式用于控制当前任务的确认和自动执行范围：

• Ask：需要授权的操作会先请求确认。
• Auto：自动处理常规操作，在必要时请求确认。
• Full access：适合已经信任任务和 workspace、需要更完整执行能力的环境。

在不熟悉的代码库中，建议优先使用能够完成任务的最小权限。

命令速查

/status 查看运行版本、模型和思考配置、目录与 Git 信息、权限、工作模式、Session、MiniMax 账号与套餐，以及 5 小时和每周额度的剩余比例与重置倒计时。账号信息异步加载，查询失败时仍可查看本地配置。Default / Plan 切换会标明当前模式和下一条消息的切换意图。

指令来源列出 Runtime 按当前文件内容选用的全局、项目规则文件路径；它遵循与 Turn 装配相同的优先级和大小限制，不展示正文，也不代表历史 Turn 的快照。/usage 提供套餐到期、Credits、视频额度及 Session 用量等明细。查看面板可滚动，按 Esc 关闭，内容不会写入会话历史。

| 命令 | 用途 | | ------------------------ | ----------------------------------- | | mcode [prompt] | 启动交互式 TUI | | mcode --continue | 继续当前 workspace 最近的 Session | | mcode --session [id] | 浏览 Session，或按 ID 打开 | | mcode exec [prompt] | 执行一次 Headless 任务 | | mcode exec review | 审查 staged/unstaged/untracked 改动 | | mcode init [directory] | 分析代码库并生成或完善 AGENTS.md | | mcode login / logout | 管理 MiniMax 登录态 | | mcode provider ... | 管理模型 Provider | | mcode plugin ... | 浏览和管理 Plugin | | mcode acp | 启动 ACP 服务 | | mcode update | 检查并安装更新 |

登录或退出后，TUI 会先同步当前 runtime 的登录凭据，再恢复操作。内容审核遇到认证失败时，会尝试恢复登录凭据；只有取得不同的新凭据才重试一次，恢复失败仍会停止审核。此过程不会改变当前模型或用户配置的 API key。

运行 mcode --help 或 mcode <command> --help，查看当前安装版本支持的全部参数。

正式版本的用户可见变化见 CHANGELOG.zh-CN.md。

常见问题

确认全局 npm bin 目录已经加入 PATH，然后运行：

npm list -g @minimax-ai/code --depth=0
npm prefix -g

当前支持 Node.js >=22.19 <23 或 >=24 <27，不支持 Node 23。切换 Node.js 版本后，重新安装 MiniMax Code：

node --version
npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 --registry=https://registry.npmjs.org/

npm 12 默认阻止未经授权的安装脚本。如果安装日志出现 npm warn install-scripts，并列出 MCode 的 postinstall 和 better-sqlite3 的 install 被阻止，即使 npm 显示 added 或 changed packages，SQLite 原生模块也可能没有准备好。启动时可能提示 Could not locate the bindings file、缺少 better_sqlite3.node，或外层的 migration_failed。

通过官方 Shell/PowerShell 安装器安装的用户，重跑原安装命令即可。安装器和 /update 会处理所需的脚本参数与原生依赖；如果 MCode 已无法启动，先重跑安装器修复。

通过 npm install -g 安装的用户，优先执行启动错误中给出的修复命令。下面的命令适用于安装 latest：

npm install -g @minimax-ai/code@latest --registry=https://registry.npmjs.org/ --foreground-scripts --ignore-scripts=false --include=optional --allow-scripts=@minimax-ai/code,better-sqlite3

保留原安装命令的包名、版本和 registry；安装 Preview 或指定版本时，沿用原来的精确版本，避免切换到 latest。--allow-scripts 中填写相同的 MCode 包名及 better-sqlite3。只加 --ignore-scripts=false 不能代替 npm 12 的脚本授权；--include=optional 确保安装 SQLite 依赖。

看到 [MCode] Native SQLite check passed. 后再启动 mcode。此操作修复安装目录中的原生依赖，保留已有配置和会话。若仍失败，提供本次完整安装日志，以及 node --version 和 npm --version 的输出，以继续排查下载、编译或运行时错误。

先检查安装版本、登录状态和 Provider 连通性：

mcode --version
mcode login
mcode provider list
mcode provider test <provider-id>

Windows 硬性安全检查开关

Windows 下，Runtime 默认会在 off 等权限模式之前检查删除命令、回收站工具可用性及受保护/含糊的路径。 首次启动生成的 config.yaml 会写入顶层 skipWindowsHardSafetyChecks: false，与 permissionMode 并列。如果这些检查误判 Python、XML 或 PowerShell 脚本，可在当前 TUI 数据目录的 config.yaml 中把它改为 true；已有配置 没有该项时手动添加。默认路径为 ~/.minimax/config.yaml（Windows 为 %USERPROFILE%\.minimax\config.yaml）； 设置数据目录、profile 或启动时 --config 参数时，修改实际使用的配置文件：

skipWindowsHardSafetyChecks: true

默认值为 false；缺省或错误类型均不跳过，"true" 字符串也不会开启。修改后需重启 mcode；改回 false 或删除该项并重启即可恢复。该设置仅作用于 Windows TUI Runtime（包括 exec / ACP），不影响 Desktop、macOS 或 Linux。

开启后会跳过 Windows 命令文本和路径的硬性拦截，包括重复的路径检查；受保护路径写入也可能通过这层检查。 删除转入回收站的行为保持不变：即使使用 permissionMode: off（或 --permission off），已有解析器支持的 rm 和 Windows 原生删除仍重写为 mavis-trash。回收站不可用、不可信，或已识别的删除无法安全重写时仍会拦截， 不会退回执行原始永久删除命令。该开关不扩展删除解析器，不能保证任意脚本内部的删除都被识别和重写。 此配置本身不切换权限模式；default / auto 等模式的规则、确认、通用安全检查及执行层限制仍生效，仍可能阻止命令。 它只能解除这层权限拦截，不能修复后续脚本错误或保证文档任务成功。

更新与卸载

# 检查并安装更新
mcode update

# 卸载
npm uninstall -g @minimax-ai/code

License

MIT

项目级 MCP

Runtime 自动加载会话主工作目录的 .mcp.json，与 Desktop、exec、ACP 共用配置规则；详见项目级 MCP 配置。

Hook 提示与终端恢复

Plugin Hook 返回的 systemMessage 会在当前会话及恢复历史中显示为 Hook 提示。它只用于展示，不加入模型上下文；不同 Hook 调用可重复显示相同提示，诊断和终端控制通知仍按原规则去重。

使用 --session、--resume 或 --continue 恢复会话时，常规模式会清除旧进程留下的终端滚动历史，再重放当前会话；普通启动保留 shell 历史。POSIX TTY 的慢速输出通过异步队列发送，避免阻塞输入；退出、暂停或打开外部编辑器前会等待有序输出完成。