MiniMax Code 是什么

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）。

三种入口

命令用 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，差别只在怎么呈现结果。这条路径见一条消息的旅程，exec 与 ACP 的适配见 Headless 与 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）：

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：

      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），既不测试，也不改默认模型。连通性测试怎么做、模型目录从哪来，见模型系统。

常用斜杠命令

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

技能也以斜杠命令的形式出现，比如 /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）：

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

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

和 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。

从代码留下的痕迹推断，更早的本地产品曾以 OpenCode 作为 Agent 底座（证据集中在桌面端 daemon 一层，没有找到哪个版本的命令行用过它，见第一代运行时）。会话记录至今仍有 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 遗产。

和站内其他专栏对照

• 《OpenCode 源码解读》：MiniMax Code 早期的底座。如今仓库里已经没有 OpenCode 本身的代码或依赖，旧会话只读取、迁移，但两边的会话模型、工具契约与权限设计仍适合对照着读。
• 《MiMo Code 源码解读》：小米从 OpenCode 分叉出来的编码 Agent。同样从 OpenCode 起步，MiMo Code 留在 OpenCode 上做二次开发，MiniMax Code 则把 Agent 循环换成了 pi-mono。
• 《Kimi Code 源码解读》：同样 vendored 了 pi 的终端 UI（见 pi-tui 一篇，基线是上游 0.80.2），但 Agent 引擎是自研的；MiniMax Code 则连 Agent 循环和模型协议层都用 pi 的。
• 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 中文手册：/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）。

下一篇：仓库全景：公开投影与两个上游——31 个包根各管什么、依赖怎么流，公开投影怎样逐个文件把关，两个上游又从哪来。