# MiniMax Code 是什么

> MiniMax 的终端编码 Agent：三种入口、登录与 Token Plan、自带模型、常用命令与快捷键，以及它和 pi-mono、OpenCode 的渊源。

- 作者：David（道雾轩）
- 专栏：MiniMax Code 源码解读（https://daiw.org/manual/minimax-code.md）
- 最后更新：2026-09-19
- 原文：https://daiw.org/manual/minimax-code/what-is-minimax-code
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

MiniMax Code 的 README 在标题下只放了一句话（`README_ZH.md:10`）：

> A terminal coding agent with MiniMax, your own models, and tools beyond code.

终端里的编码 Agent：模型可以用 MiniMax 的，也可以接自己的；工具也不止于读写代码。命令名是 `mcode`，npm 包名是 `@minimax-ai/code`。这一篇先把它当成产品来看——从哪几个入口用、怎么装、怎么登录、模型从哪来、有哪些常用命令，以及它和 pi-mono、旧版 OpenCode 的关系。实现细节留给后面各篇。

## 仓库与版本

- 仓库是 `MiniMax-AI/minimax-code`，本书基准为 `main` 分支 2026-09-19 的提交 e3724a1。仓库没有任何 tag；CLI 源码是 2026-09-18 以一个提交整体导入的，此前这个仓库只承接桌面版的问题反馈（`docs/open-source-status.md:30`）。
- 根 `package.json` 与 `packages/tui/package.json` 的版本都是 0.4.12，后者的包名是 `@minimax/code`。README 把这份源码称为“0.4.12 源码预览”，并提醒：装 npm 包和从源码构建是两条独立路径，版本号相同不代表构建来源相同（`README_ZH.md:186`）。
- 第一方代码默认 MIT，`third_party/` 下的代码保留各自的许可，其中沙箱运行时是 Apache-2.0（`LICENSE-STATUS.md:7`）。
- 公开的只是终端 TUI、Headless CLI 和 ACP 三部分，不含桌面应用的源码（`README_ZH.md:204`）。这个仓库其实是内部 monorepo 的“公开投影”，下一篇细说。

## 安装

官方安装器有两个：macOS、Linux、WSL 用 `curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash`，Windows PowerShell 用 `irm https://filecdn.minimax.chat/public/install.ps1 | iex`。安装器会在需要时准备一份兼容的 Node.js，不需要 `sudo` 或管理员权限；目前不支持 Alpine 这类 musl Linux（`README_ZH.md:34`）。

也可以用 npm 装，但对 Node 版本有要求：根 `package.json:9` 写的是 `>=22.19 <23 || >=24.2 <27`，即 22.19 以上的 22 系列、24.2 以上的 24 系列，以及 25、26。24.0 和 24.1 被排除在外，因为它们自带的 libuv 在 Windows 上返回的文件标识不一致，会让配置读取失败（`docs/installation.md:13`）。CLI 启动时第一件事也是检查 Node 版本（`packages/tui/src/cli/main.ts:87`）。

README 给的 npm 命令（`README_ZH.md:51`）特意带上了 `--include=optional` 和 `--allow-scripts=@minimax-ai/code,better-sqlite3`：会话数据存在 SQLite 里，靠 better-sqlite3 的原生绑定，装的时候不能跳过它的安装脚本。万一绑定加载失败，CLI 会把原始错误包成一段重装提示再输出（`formatTuiCliError`，`main.ts:200`）。

用户数据默认放在 `~/.minimax-code`（`packages/tui/src/runtime/data-dir.ts:20`），环境变量 `MINIMAX_DATA_DIR` 可以换目录，旧名 `MAVIS_DATA_DIR` 也认（`data-dir.ts:28`）。

## 三种入口

| 入口 | 命令 | 形态 |
| --- | --- | --- |
| 交互式 TUI | `mcode [prompt]` | 默认命令；带上 prompt 则启动后立即提交 |
| Headless | `mcode exec [prompt]` | 不启动界面，跑完这一次就退出；`mcode exec review` 专门审查本地改动 |
| ACP | `mcode acp` | 作为 Agent Client Protocol 服务端，经 stdio 接入编辑器 |

命令用 commander 注册，集中在 `packages/tui/src/cli/program.ts`：默认命令在 `createTuiProgram` 里（`program.ts:52`），`exec` 与 `acp` 分别在 `program.ts:91` 和 `program.ts:107`。

- **TUI 的选项**：`-c`（`--continue`）接着当前工作区最近的会话，`--session [id]` 打开指定会话、不给 id 则打开会话选择器，`--tui-mode` 在 `regular`（默认）与 `fullscreen` 之间选（`packages/tui/src/cli/contract.ts:28`）。`--session`、`--continue` 与兼容旧用法的隐藏选项 `--resume` 三者互斥。
- **exec 的选项**：面向脚本与 CI。`--model` 只对本次运行换模型，`--permission` 取 `smart`（默认）、`full` 或 `off`（需要问人的 `ask` 只在 TUI 与 ACP 里有），`--output-format` 取 `text`、`json`、`stream-json`，另有 `--output-schema`、`--timeout`、`--max-steps` 等（`contract.ts:88`）。
- **管理类命令**：`init`（分析代码库生成 `AGENTS.md`，实际就是带着 `/init` 启动 TUI，`program.ts:83`）、`login`、`logout`、`update`、`telemetry`、`provider`、`plugin`。`provider` 与 `plugin` 不带子命令时分别打开 TUI 里的 `/provider` 和 `/plugins` 面板。

三个入口共用同一套运行时：各自在当前进程里创建运行时，再经同一个 `TuiRunCoordinator` 类把消息交给 `CliService`，差别只在怎么呈现结果。这条路径见[一条消息的旅程](https://daiw.org/manual/minimax-code/message-lifecycle)，exec 与 ACP 的适配见 [Headless 与 ACP](https://daiw.org/manual/minimax-code/headless-and-acp)。

## 登录：两个区域

中国大陆账号直接 `mcode login`，Global 账号加 `--region global`。`--region` 只认 `cn` 和 `global`，后者在内部记作 `en`（`program.ts:376`，类型 `MavisRegion` 见 `packages/config/src/config.ts:89`）；不带参数时取 `cn`（`packages/tui/src/auth/environment.ts:54`）。

登录走 OAuth 设备授权流程（`packages/oauth-core/src/oauth-client.ts:5`）：终端打印授权地址和一次性代码，再尝试打开默认浏览器，加 `--no-browser` 则只打印（`packages/tui/src/cli/auth-command.ts:31`）。进了 TUI 以后，`/login` 登录，`/status` 看账号与模型状态，`/logout` 或 `mcode logout` 退出。

## 模型：Token Plan 与自带模型

MiniMax 自家的模型有两种凭据来源：登录账号后用 Token Plan 的额度，或者填一把 MiniMax API Key，代码里分别记作 `token_plan` 与 `minimax_api_key`（`packages/tui/src/provider/contract.ts:13`）。`mcode provider use token-plan` 或 `mcode provider use api-key` 在两者之间切换，`mcode provider set-minimax-key` 从环境变量读 Key、保存并启用。`mcode provider list` 列出的提供方里，这两项固定排在最前（只读的 `minimax_oauth` 与可编辑的 `minimax_api`，`packages/tui/src/provider/application.ts:38`），后面才是用户自己加的。

自带模型（BYOK）不需要先登录 MiniMax。README 的示例（`README_ZH.md:89`）：

```bash
mcode provider add --name my-provider --base-url https://example.com/v1 \
  --api-format openai-completions --model my-model \
  --api-key-env MCODE_PROVIDER_API_KEY --use
mcode
```

几个细节以代码为准：

- `--name` 和 `--base-url` 必填；`--api-format` 只接受 `anthropic-messages`、`openai-completions`、`openai-responses` 三种（`packages/tui/src/provider/contract.ts:1`），省略时默认 `anthropic-messages`（`program.ts:191`）；`--model` 可以重复，至少给一个。
- Key 不走命令行参数，只从环境变量读：`--api-key-env` 指定变量名，省略时读 `MCODE_PROVIDER_API_KEY`（`packages/tui/src/cli/provider-command.ts:56`）。
- `--context-limit` 与 `--output-limit` 必须是正的安全整数，作用于这次列出的每个模型（`program.ts:195`）。

`--use` 的行为在 `provider-command.ts:80`：

```ts
      if (request.saveAndUse) {
        const modelId = request.models[0];
        if (!modelId) throw new Error('At least one --model <id> is required.');
        const result = await context.application.saveCandidate({
          ...input,
          modelId,
          saveAndUse: true,
        });
        if (!result.success) {
          throw new Error(
            formatTuiActionFailure(
              result.status?.lastErrorMessage ?? result.status?.state ?? 'Connection unavailable',
              {
                summary: 'Provider connection test failed. Nothing was saved or selected.',
                nextStep:
                  'Check the URL, API key, and first model ID, then retry; omit --use to save without testing.',
              },
            ),
          );
        }
        return `Provider added and selected: ${request.name}`;
      }
```

带 `--use` 时只拿第一个模型做连通性测试，通过了才保存并设为默认模型；不通过就报错，并明说什么都没保存、什么都没选中。不带 `--use` 则直接保存（`provider-command.ts:102`），既不测试，也不改默认模型。连通性测试怎么做、模型目录从哪来，见[模型系统](https://daiw.org/manual/minimax-code/model-system)。

## 常用斜杠命令

内置斜杠命令登记在 `COMMAND_SOURCES`（`packages/tui/src/tui/commands/catalog.ts:122`），按用途挑常用的：

| 用途 | 命令 |
| --- | --- |
| 会话 | `/new`（别名 `/clear`）、`/sessions`（别名 `/resume`）、`/rename`、`/fork`、`/rewind`、`/export` |
| 模型与账号 | `/model`、`/provider`、`/status`、`/login`、`/logout`、`/usage` |
| 工作方式 | `/plan`、`/goal`、`/permission`、`/review`、`/compact`、`/context` |
| 运行中 | `/btw`（别名 `/side`，不打断当前任务，问个旁支问题）、`/queue`、`/tasks` |
| 扩展 | `/plugins`、`/skills`、`/mcp`、`/reload` |
| 界面与帮助 | `/settings`、`/statusline`、`/hotkeys`、`/transcript`、`/copy`、`/help` |

技能也以斜杠命令的形式出现，比如 `/init` 就来自内置技能 `init`（`packages/local-runtime/assets/skills/init/SKILL.md`）。输入以 `!` 开头时直接在工作区执行 Shell 命令，命令和输出会作为上下文附在下一条消息里；以 `!!` 开头则不附带（`packages/tui/src/tui/commands/bash-input.ts:6`）。

## 快捷键

默认键位在 `DEFAULT_TUI_KEYBINDINGS`（`packages/tui/src/tui/shell/keybindings.ts:264`），换行键来自 TUI 引擎（`packages/tui/src/tui/engine/keybindings.ts:143`）：

| 按键 | 作用 |
| --- | --- |
| `Enter` | 空闲时发送；任务运行中则把草稿作为引导，插进正在进行的回合 |
| `Alt+Enter` | 任务运行中把草稿排进队列，等当前回合结束再发 |
| `Shift+Enter` 或 `Ctrl+J` | 输入框换行 |
| `@` | 引用工作区里的文件或目录 |
| `Shift+Tab` | 在默认模式与 Plan 模式之间切换 |
| `Alt+M` | 在 Ask、Auto、Full access 三种权限模式间轮换 |
| `Esc` | 关闭当前面板，或中断正在运行的回合 |
| `Ctrl+C` | 清空输入框，连按两次退出 |
| `Ctrl+O` | 展开或收起思考过程、工具输出与 diff |
| `Ctrl+T` | 显示或隐藏完整的 Todo 列表 |
| `Ctrl+R`、`Ctrl+G` | 搜索历史输入；用外部编辑器编辑草稿 |
| `Ctrl+V` | 粘贴剪贴板里的图片或视频文件（Windows 另绑了 `Alt+V`） |
| `Ctrl+/` | 在主会话与 `/btw` 的临时旁支会话之间切换 |

三种权限模式在代码里是 `default`、`auto`、`bypassPermissions`（`packages/tui/src/application/permission-mode.ts:1`），细节见[权限模式与规则](https://daiw.org/manual/minimax-code/permission)。键位可以改：覆盖项写在数据目录下 `tui` 子目录的 `keybindings.json` 里（`packages/tui/src/host/tui-keybindings.ts:15`），TUI 里用 `/hotkeys` 查看和修改。

README 的能力表（`README_ZH.md:148`）与本书篇目的对应：

| 能力 | 对应篇目 |
| --- | --- |
| 修改与验证代码 | [文件与 Shell 工具](https://daiw.org/manual/minimax-code/file-and-shell)、[权限模式与规则](https://daiw.org/manual/minimax-code/permission)、[沙箱](https://daiw.org/manual/minimax-code/sandbox) |
| 选择模型 | [模型系统](https://daiw.org/manual/minimax-code/model-system) |
| 搜索与多模态 | [账号、OAuth 与云端工具](https://daiw.org/manual/minimax-code/accounts-and-tools)、[MCP](https://daiw.org/manual/minimax-code/mcp)、[浏览器工具](https://daiw.org/manual/minimax-code/browser-use) |
| 延续工作 | [会话系统](https://daiw.org/manual/minimax-code/session-system)、[Plan 模式与目标](https://daiw.org/manual/minimax-code/plan-and-goal)、[子 Agent 与后台任务](https://daiw.org/manual/minimax-code/subagents)、[插件系统](https://daiw.org/manual/minimax-code/plugins)、[技能](https://daiw.org/manual/minimax-code/skills) |
| 接入工作流 | [Headless 与 ACP](https://daiw.org/manual/minimax-code/headless-and-acp) |

## 和 pi-mono、旧版 OpenCode 的关系

MiniMax Code 的 Agent 循环不是从零写的。`third_party/pi-mono` 原样引入了 pi-mono v0.79.1 的 `agent`、`ai`、`coding-agent`、`tui` 四个包，补丁台账开头交代了为什么要把源码搬进仓库（`third_party/pi-mono/MINIMAX_CHANGES.md:3`）：

> This directory vendors `pi-mono` as source so MiniMax can patch, validate, and ship agent-loop fixes without waiting on upstream release cadence.

第一方的 `packages/agent-core` 在它上面包了一层回合执行器 `PiTurnRunner`，每个回合新建一个 pi 的 `Agent` 来跑。终端界面走的是另一条线：`packages/tui/src/tui/engine` 是从 pi 仓库的 `packages/tui/src` 在 0.84.2 版本分叉出来的 TUI 引擎（`packages/tui/src/tui/engine/UPSTREAM.md:3`），第一方代码并不 import `third_party` 里的 `@earendil-works/pi-tui`。四个包各管什么、打了哪些补丁，见[内置的 pi-mono](https://daiw.org/manual/minimax-code/pi-mono)。

从代码留下的痕迹推断，更早的本地产品曾以 OpenCode 作为 Agent 底座（证据集中在桌面端 daemon 一层，没有找到哪个版本的命令行用过它，见[第一代运行时](https://daiw.org/manual/minimax-code/runtime-v1)）。会话记录至今仍有 `pi-agent` 与 `opencode` 两种运行时，第一代运行时据此把会话分到两条路由（`packages/local-runtime/src/sessions/router.ts:33`）；`packages/local-runtime/src/legacy-opencode/` 专门读取和迁移旧会话，读取器的注释写得很明确（`packages/local-runtime/src/legacy-opencode/legacy-history-reader.ts:9`）：

> Read-only legacy session files; does not start processes, proxy requests, or execute legacy sessions.

配置层也还留着解析旧 `opencode` 适配器配置的代码，注释说新会话已不走这条路（`packages/config/src/opencode-config.ts:17`）；TUI 创建运行时时更是显式传入 `legacyOpencodeEnabled: false`（`packages/tui/src/runtime/embedded-host.ts:86`）。旧会话怎样被识别、迁移到什么程度，见[第一代运行时与 OpenCode 遗产](https://daiw.org/manual/minimax-code/runtime-v1)。

## 和站内其他专栏对照

- [《OpenCode 源码解读》](https://daiw.org/manual/opencode)：MiniMax Code 早期的底座。如今仓库里已经没有 OpenCode 本身的代码或依赖，旧会话只读取、迁移，但两边的会话模型、工具契约与权限设计仍适合对照着读。
- [《MiMo Code 源码解读》](https://daiw.org/manual/mimo-code)：小米从 OpenCode 分叉出来的编码 Agent。同样从 OpenCode 起步，MiMo Code 留在 OpenCode 上做二次开发，MiniMax Code 则把 Agent 循环换成了 pi-mono。
- [《Kimi Code 源码解读》](https://daiw.org/manual/kimi-code)：同样 vendored 了 pi 的终端 UI（见 [pi-tui 一篇](https://daiw.org/manual/kimi-code/pi-tui)，基线是上游 0.80.2），但 Agent 引擎是自研的；MiniMax Code 则连 Agent 循环和模型协议层都用 pi 的。
- [Claude Code 中文手册](https://daiw.org/manual/claude-code)：MiniMax Code 的沙箱是 Anthropic 开源的 sandbox-runtime 的分叉（`third_party/sandbox-runtime/upstream.json:2`）；插件钩子的事件名（`SessionStart`、`PreToolUse`、`PostToolUse` 等）与 Claude Code 一致，钩子的来源格式分 `MINIMAX`、`CLAUDE`、`CODEX` 三种（`packages/agent-modules/plugin-hooks/src/contracts.ts:18`）。
- [Codex 中文手册](https://daiw.org/manual/codex)：`/btw` 旁支会话只开放只读命令，注释说这是照着 Codex 的做法（`packages/tui/src/tui/commands/catalog.ts:34`）；欢迎页如果发现当前工作区 10 分钟内有过 Codex 会话，会提示按 `Ctrl+U`，用内置技能 `resume-codex` 接着做（`packages/tui/src/host/recent-codex-session.ts:7`）。

下一篇：[仓库全景：公开投影与两个上游](https://daiw.org/manual/minimax-code/monorepo-map)——31 个包根各管什么、依赖怎么流，公开投影怎样逐个文件把关，两个上游又从哪来。