> ## Documentation Index
> Fetch the complete documentation index at: https://platform.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex

> 在 Codex 桌面客户端中使用最新的 MiniMax M 系列模型进行 AI 编程。

<div style={{background:"#fffbeb",borderLeft:"4px solid #d97706",padding:"12px 16px",borderRadius:"6px",margin:"16px 0"}}>[**Codex**](https://developers.openai.com/codex/) 是 OpenAI 官方的桌面端 AI 编程 Agent。</div>

## 安装 Codex

如果使用下方一键配置向导，可跳过 Codex CLI 的安装。向导检测不到 `codex` 命令时，会询问是否安装官方 `@openai/codex` npm 包。

从 [OpenAI Codex 页面](https://developers.openai.com/codex/) 下载并安装 Codex 桌面客户端。

## 配置 MiniMax API

<Tabs sync={false}>
  <Tab title="方式一：一键配置向导">
    直接运行：

    ```bash theme={null}
    npx -y mmx-cli@latest agent setup
    ```

    在工具列表中选择 **Codex**。如果 Codex CLI 尚未安装，向导会提示安装。建议使用 **Codex CLI 0.146.0 或更高版本**。向导会配置 `~/.codex/config.toml` 和 `~/.codex/mmx-model-catalog.json`。

    运行向导前，请关闭 Codex 以及正在打开 `~/.codex/config.toml` 的编辑器，避免其他进程用旧内容覆盖刚写入的配置。

    配置完成后重启 Codex。详细参数和备份说明请见 [MiniMax CLI](/docs/m-plan/minimax-cli)。
  </Tab>

  <Tab title="方式二：手动配置">
    <Steps>
      <Step title="编辑配置文件">
        打开 `~/.codex/config.toml`，加入或更新以下内容，并将 `<MINIMAX_API_KEY>` 替换为你从 [MiniMax 开放平台](https://platform.minimax.cn/console/plan) 获取的 Key：

        ```toml theme={null}
        model = "MiniMax-M3.1-Flash-Preview"
        model_provider = "minimax"
        model_context_window = 524288
        preferred_auth_method = "apikey"
        forced_login_method = "api"

        [model_providers.minimax]
        name = "MiniMax"
        base_url = "https://api.minimax.cn/v1"
        experimental_bearer_token = "<MINIMAX_API_KEY>"
        wire_api = "responses"
        ```

        `preferred_auth_method` 和 `forced_login_method` 指定 API Key 认证。如需在 `/model` 中显示模型能力和思考档位，可继续配置下方的可选模型目录。
      </Step>

      <Step title="重启 Codex 并开始使用 MiniMax-M3.1-Flash-Preview">
        重启 Codex，即可开始使用 MiniMax-M3.1-Flash-Preview。
      </Step>
    </Steps>

    ### 配置模型能力目录（可选）

    手动配置时，可以添加模型能力目录，让 Codex 在 `/model` 中显示 MiniMax-M3.1-Flash-Preview 及其思考档位。

    在 `~/.codex/config.toml` 中增加一行：

    ```toml theme={null}
    model_catalog_json = "~/.codex/model-catalogs/custom-catalog.json"
    ```

    然后新建 `~/.codex/model-catalogs/custom-catalog.json`，写入模型配置：

    ```json theme={null}
    {
      "models": [
        {
          "slug": "MiniMax-M3.1-Flash-Preview",
          "display_name": "MiniMax-M3.1-Flash-Preview",
          "description": "MiniMax M3.1 Flash Preview",
          "default_reasoning_level": "max",
          "supported_reasoning_levels": [
            { "effort": "low", "description": "Low" },
            { "effort": "medium", "description": "Medium" },
            { "effort": "high", "description": "High" },
            { "effort": "xhigh", "description": "Extra high" },
            { "effort": "max", "description": "Maximum" }
          ],
          "shell_type": "shell_command",
          "visibility": "list",
          "supported_in_api": true,
          "priority": 0,
          "base_instructions": "You are Codex, a coding agent based on MiniMax-M3.1-Flash-Preview. You and the user share the same workspace and collaborate to achieve the user's goals.",
          "supports_reasoning_summaries": true,
          "default_reasoning_summary": "none",
          "support_verbosity": false,
          "truncation_policy": { "mode": "tokens", "limit": 10000 },
          "supports_parallel_tool_calls": true,
          "experimental_supported_tools": [],
          "prefer_websockets": false,
          "apply_patch_tool_type": "freeform",
          "web_search_tool_type": "text",
          "supports_image_detail_original": false,
          "tool_mode": "code_mode_only",
          "multi_agent_version": "v2",
          "use_responses_lite": false,
          "input_modalities": ["text", "image"],
          "context_window": 524288,
          "max_context_window": 524288,
          "effective_context_window_percent": 95,
          "auto_compact_token_limit": null,
          "reasoning_summary_format": "experimental",
          "supports_search_tool": true
        }
      ]
    }
    ```

    <Warning>
      不要在 `supported_reasoning_levels` 中加入 `{ "effort": "none" }`。MiniMax-M3.1-Flash-Preview 始终会思考，选择该档位会让 Codex 发送 `reasoning: {"effort": "none"}`，API 将返回 `400`。
    </Warning>

    其中常用字段含义如下：

    * `slug` / `display_name`：模型在 Codex 配置与 `/model` 列表中的标识和展示名称，需与 API 中使用的模型名保持一致。
    * `default_reasoning_level`：默认 reasoning effort。MiniMax-M3.1-Flash-Preview 默认使用 `max`。
    * `supported_reasoning_levels`：在 `/model` 中可切换的 reasoning 选项。MiniMax-M3.1-Flash-Preview 支持 `low`、`medium`、`high`、`xhigh` 和 `max`，不支持 `none`。
    * `base_instructions`：Codex 使用该模型时附加的基础 system prompt，可用于声明模型身份和协作方式。
    * `supports_reasoning_summaries`：开启 Codex 对该模型的 Responses API reasoning 路径。设置为 `true` 后，Codex 才会发送 `reasoning.effort`；否则即使配置了 `default_reasoning_level`，Codex 也会省略 `reasoning` 字段。示例中将 `default_reasoning_summary` 设为 `none`，表示不额外请求 reasoning summary。
    * `shell_type`：声明模型适配的 shell 工具调用类型，示例中使用 `shell_command`。
    * `visibility` / `supported_in_api` / `priority`：控制模型是否出现在列表中、是否可通过 API 使用，以及在模型列表中的排序优先级。
    * `supports_parallel_tool_calls`：声明模型支持并行工具调用，便于 Codex 处理多个工具请求。
    * `experimental_supported_tools`：预留的实验性工具能力列表；没有额外工具时保持空数组即可。
    * `input_modalities`：声明模型支持的输入模态。`["text", "image"]` 表示支持文本和图片输入。
    * `truncation_policy`：控制内容截断策略，示例按 tokens 计数。
    * `context_window` / `max_context_window`：示例中的客户端上下文窗口为推荐的 512K（524288 tokens），详见[512K 配置建议](#context-window-512k)。
    * `effective_context_window_percent` / `auto_compact_token_limit`：以窗口的 95% 作为有效上下文预算，不另设固定的自动压缩阈值。

    修改后重启 Codex，使新的模型目录生效。

    <span id="context-window-512k" />

    ### 上下文窗口与费用优化（可选）

    MiniMax-M3.1-Flash-Preview 最高支持 1M tokens 上下文。日常编程等多轮任务，可尝试将工具使用的上下文窗口设置为 **512K**，通过更早管理和压缩历史内容，减少后续请求携带的历史 token。需要持续保留大量代码或文档细节时，可使用 **1M**。

    #### 为什么可以尝试 512K？

    在使用 MiniMax-M3.1-Flash-Preview 进行的一次 ProgramBench 对比测试中，512K 与 1M 窗口下的平均模型表现接近，512K 的估算费用低约 **20%**。可以考虑将 512K 作为日常编程的可选配置。

    **不同上下文窗口下的模型测试表现与消耗**

    | 对比项 | 1M 窗口 | 512K 窗口 | 512K 相比 1M |
    | - | - | - | - |
    | 评测任务数 | 200 | 200 | 相同 |
    | 模型表现 | 接近 | 接近 | 暂未检出明确差异 |
    | 平均每任务总 token | 136.76 百万 | 111.42 百万 | **减少 18.5%** |
    | 用量计费预估 | 100% | 80.1% | **降低 19.9%** |
  </Tab>
</Tabs>