# MiniMax Code

[English](./README.md) | 简体中文

**运行在终端里的 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`。

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

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

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

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

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

## 模型、Provider 与终端设置

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

```bash
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 中的凭据放进命令行参数或问题反馈。

Fullscreen Transcript 提供可点击、拖动的滚动条。`/statusline` 可选择默认关闭的 `context-meter`
显示剩余上下文刻度，详情见 [状态栏配置](docs/status-line-config.md)。

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

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

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

## 按你的方式使用

### 交互式 TUI

在当前目录启动：

```bash
mcode
```

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

```bash
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 命令：

```bash
# 继续当前 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 时会被自动清理。

切换快捷键只切换已创建的侧会话，不会创建侧会话。尚未执行 `/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 摘要。

### 直接执行终端命令

在 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 回复或交互处理完毕后可执行命令。命令执行期间，新提交会保留为草稿；包含附件的输入需要移除附件后执行。

### Headless 与 CI

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

```bash
# 执行一次任务
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`：

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

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

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

### Exec 诊断与超时恢复

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

```bash
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 访问权限与保留时间。

### Browser 操作

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

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

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

```yaml
beta:
  browserUseTooling: true
```

```bash
MINIMAX_DATA_DIR=/tmp/mcode-browser-real mcode
```

进入 TUI 后可以输入：

```text
请使用 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 输入。

### ACP 客户端

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

```bash
mcode acp
```

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

## 模型、Provider 与 Plugin

登录 MiniMax：

```bash
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 命令查看或配置模型来源：

```bash
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：

```bash
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](./CHANGELOG.zh-CN.md)。

## 常见问题

<details>
<summary><code>mcode: command not found</code></summary>

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

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

</details>

<details>
<summary>Node.js 版本不受支持</summary>

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

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

</details>

<details>
<summary>npm 12 安装脚本被阻止，或启动时提示 SQLite 原生依赖缺失</summary>

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`：

```bash
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` 的输出，以继续排查下载、编译或运行时错误。

</details>

<details>
<summary>登录或 Provider 异常</summary>

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

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

</details>

## 更新与卸载

```bash
# 检查并安装更新
mcode update

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

## License

MIT

## 项目级 MCP

Runtime 自动加载会话主工作目录的
`.mcp.json`，与 Desktop、exec、ACP 共用配置规则；详见[项目级 MCP 配置](../local-runtime-v2/docs/project-mcp.md)。