# MiniMax M3.1 Flash 接入 OpenCode：配置与工具调用

> 在 OpenCode 里配置 MiniMax M3.1 Flash，讲清自定义 Provider、模型 ID、Base URL 与 Key，并用仓库任务检查工具调用和常见配置错误。

- Canonical HTML: https://omniakey.com/zh/blog/minimax-m3-1-flash-opencode
- Markdown: https://omniakey.com/zh/blog/minimax-m3-1-flash-opencode.md
- Published: 2026-11-12 (updated 2026-11-12)
- Author: Kiki, COO at OmniaKey
- Language: zh
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

[MiniMax M3.1 Flash](https://omniakey.com/zh/minimax-m3-1-flash) 能在 OpenCode v2.2.3 里通过 [OpenAI 兼容的自定义 Provider](https://opencode.ai/docs/providers/) 使用。OpenCode 里的模型名是 `omniakey/minimax-m3.1-flash`，Base URL 是 `https://api.omniakey.com/v1`。用下面的配置，2026 年 11 月 12 日跑通了一个真实仓库任务。任务里有 5 次读取、1 次写入、1 次 `node --test`，12 个测试全部通过。

OpenCode 的自定义 Provider 走 OpenAI Chat Completions 格式，OmniaKey 在 /v1 提供这套格式。配置只有一个项目文件，真正决定能不能用的有三处。第一，模型 ID 要和 OmniaKey 的写法完全一致。第二，Key 要让 OpenCode 的 server 进程读得到。第三，Provider 配置要能在多轮工具调用中保留模型的思考字段。

## 开始前要准备什么

用 OpenCode V2。这次实测的版本是 v2.2.3。V2 的自定义 Provider 放在顶层 providers 对象里，V1 的写法不一样。复制配置前先看 [V2 的 Provider 文档](https://opencode.ai/docs/providers/)，再跑 `opencode --version` 确认版本。

- OpenCode：v2.2.3，2026 年 11 月 12 日实测。
- OmniaKey 模型 ID：`minimax-m3.1-flash`。
- OpenCode 里的引用：`omniakey/minimax-m3.1-flash`。

先在 OmniaKey 创建 Key，放进 `OMNIAKEY_API_KEY`。下面的 JSON 只写变量名，不写 Key 本身。再准备一个小仓库，里面要有现成的测试命令。这次用的 Node 示例仓库有 `src/normalize.js`、一个测试文件，以及测试脚本。

MiniMax 官方 API 的模型 ID 是大小写混合的 `MiniMax-M3.1-Flash`，OmniaKey 用的是全小写 `minimax-m3.1-flash`。两处都按 OmniaKey 的小写写法填，大小写不同就对不上。

如果还在选模型，[MiniMax M3.1 Flash 评测](https://omniakey.com/zh/blog/minimax-m3-1-flash-review) 里有跑分、发布信息和始终开启的思考机制。

## 实测可用的 OpenCode V2 配置

把下面内容放到项目根目录的 opencode.jsonc。这是这次运行所用配置的公开版本。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "omniakey/minimax-m3.1-flash",
  "share": "disabled",
  "update": "disable",
  "warming": false,
  "snapshots": false,
  "enabled_providers": ["omniakey"],
  "providers": {
    "omniakey": {
      "name": "OmniaKey",
      "env": ["OMNIAKEY_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.omniakey.com/v1"
      },
      "models": {
        "minimax-m3.1-flash": {
          "modelID": "minimax-m3.1-flash",
          "name": "MiniMax M3.1 Flash",
          "body": {
            "reasoning_effort": "medium",
            "max_tokens": 4096,
            "stream_options": {"include_usage": true}
          },
          "limit": {
            "context": 1000000,
            "output": 4096
          },
          "capabilities": {
            "tools": true,
            "input": ["text"],
            "output": ["text"],
            "freeform": [],
            "reasoning": {
              "supported": true,
              "effort": ["low", "medium", "high", "xhigh", "max"]
            }
          },
          "compatibility": {
            "reasoningField": "reasoning_content",
            "requireReasoning": true,
            "maxTokensField": "max_tokens"
          }
        }
      }
    }
  },
  "permissions": [
    {"action": "*", "resource": "*", "effect": "deny"},
    {"action": "read", "resource": "*", "effect": "allow"},
    {"action": "glob", "resource": "*", "effect": "allow"},
    {"action": "grep", "resource": "*", "effect": "allow"},
    {"action": "edit", "resource": "src/normalize.js", "effect": "allow"},
    {"action": "shell", "resource": "node --test", "effect": "allow"},
    {"action": "shell", "resource": "git diff *", "effect": "allow"},
    {"action": "external_directory", "resource": "*", "effect": "deny"}
  ]
}
```

env 这一项告诉 OpenCode 从 server 进程的环境变量里读 `OMNIAKEY_API_KEY`。`modelID` 是真正发给 OmniaKey 的 ID，models 里的键是 OpenCode 在 provider/model 中使用的名字。两处都写 `minimax-m3.1-flash`，查找时不会产生歧义。

limit 和 capabilities 两段覆盖了 [OpenCode 对未知模型的默认假设](https://opencode.ai/docs/models.md)。默认假设是 20 万 token 上下文、支持图片输入。[OmniaKey 的模型页](https://omniakey.com/zh/minimax-m3-1-flash)写的是 1M token 上下文，没有视觉条目。所以配置把上下文上限设成 1000000，输入只留文本。1M 是公开的窗口大小，这次小任务没有跑到这个长度。

请求体里是这次实测的两个值：medium 思考和 4096 的 `max_tokens`。能力列表里的 effort 档位是 MiniMax 文档列出的五档，测试用的是 medium。

权限这一段是给演示仓库用的，范围很窄。先全部拒绝，再允许读取、glob 和 grep；只允许改 `src/normalize.js`；只允许跑 `node --test` 和 git diff；外部目录一律拒绝。换到你的项目，把文件路径和命令换成项目自己的。整仓库可编辑、任意 shell 可执行的授权，对这个任务来说太大了。

## 把 Key 放进启动 server 的那个 shell

OpenCode 默认会启动或复用一个后台 server。会话、配置和工具执行都归它管，Provider 的 env 变量也由这个 server 进程读取。在另一个终端 export 的 Key，它读不到。[OpenCode CLI 文档](https://opencode.ai/docs/cli.md)写明了共享 server 和 `--standalone` 的用法。

第一次跑，建议从有 Key 的 shell 里起一个私有 server：

```bash
export OMNIAKEY_API_KEY="your-omniakey-api-key"
opencode --standalone models
```

实测的 `opencode --standalone models` 后面不加 provider 名。输出里会列出这个模型。然后跑一次任务。实测用的是这个模型参数和下面的提示词；把明确标出的占位符换成提示词原文：

```bash
# 把 <task prompt> 换成下面提示词块里的原文。
opencode --standalone run --model omniakey/minimax-m3.1-flash '<task prompt>'
```

`--standalone` 会在这个 shell 里起一个私有 server，Key 由它继承，项目配置也由它读取。早先启动的共享 server 读不到这个变量。上面那行 Key 是占位符，配置文件里仍然没有密钥。

如果你现有的共享 server 已经在有 OMNIAKEY\_API\_KEY 的环境里启动，也可以直接用。共享 server 的环境不清楚时，私有 server 是可复现的路径。

## 验证读文件、改代码、跑测试的完整循环

一个小 Node 仓库就够看出工具调用有没有跑通。示例仓库里，`src/normalize.js` 只有一个排序的桩，测试文件有 12 个用例，package.json 里有 node --test 脚本。修复前 3 个通过，9 个失败。

这次用的提示词原文如下：

```prompt
Fix src/normalize.js in this small JavaScript repository. Read the source and existing tests, then implement normalizeIntervals: accept valid half-open numeric intervals [start,end], drop empty intervals, sort them, and merge overlapping or touching ranges. Return fresh arrays without mutating the input. Do not change tests or configuration. Run `node --test` and summarize the result. Work only in this repository; do not read any credentials, network resources or files outside it. Use at most 8 tool calls.
```

运行过程一共 6 次 HTTP 请求，全部返回 200，产生了 7 次工具操作：

|工具|次数|做了什么|
|-|-|-|
|`read`|5|仓库目录、源码、测试目录、`package.json`、测试文件|
|`write`|1|改写 `src/normalize.js`|
|`shell`|1|运行 `node --test`|

第一轮并行发了两次读取，一次看仓库目录，一次看源码。接下来两轮读了测试目录、package.json 和测试文件。写入替换了源码。最后一次 shell 调用跑了测试。整个任务耗时 70.172 秒。

循环里的测试输出：

```text
ℹ tests 12
ℹ suites 0
ℹ pass 12
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 52.316459
```

最后一轮回答说明了改动的文件和 12/12 的结果。六次调用的 usage 加起来是 20,739 个输入 token（含缓存命中的前缀）和 803 个输出 token。单次输出最多 363 token，4096 的上限没有碰到。

这次请求由一个本地转发进程原样转给 OmniaKey，请求体和流式响应都没有改写。这是一个小任务，说明读、写、跑测试这条链路在这个仓库里走通了。速度和代码质量还要看具体项目。

## effort、上下文和输出上限怎么设

M3.1 Flash 的思考是强制的。[MiniMax 文本生成指南](https://platform.minimax.io/docs/guides/text-generation.md)说这个模型始终思考；客户端传 `thinking: {"type": "disabled"}` 或 `reasoning_effort: "none"`，[OpenAI 兼容 API 参考](https://platform.minimax.io/docs/api-reference/text-openai-api.md)会返回 HTTP 400。想缩短一轮，就降低 effort，不要关思考。

|设置|实测值|控制什么|
|-|-|-|
|`reasoning_effort`|`medium`|回答前思考多少|
|`max_tokens`|`4096`|单次调用的客户端输出上限|
|`limit.context`|`1000000`|对外声明的上下文窗口|

`reasoning_effort` 接受 low、medium、high、xhigh 和 max 五档，不写时 [MiniMax 的指南](https://platform.minimax.io/docs/guides/text-generation.md)说默认用 max。这次任务范围有限，用 medium 就够了。降低 effort 会让思考短一些，思考本身仍然开着。

temperature 和 top\_p 在这个模型上没有作用。[MiniMax 的 API 参考](https://platform.minimax.io/docs/api-reference/text-openai-api.md)说 M3.1 Flash 固定使用 1 和 0.95，删掉这两个字段比调一个不生效的值更干净。

1M 上下文来自 [OmniaKey 模型页](https://omniakey.com/zh/minimax-m3-1-flash)和 [MiniMax 文档](https://platform.minimax.io/docs/guides/text-generation.md)。4096 是这次选的客户端输出上限，不是服务商公布的最大输出。思考 token 也算在这个上限里，所以长思考可能以 `finish_reason: "length"` 结束，最后只剩很少内容甚至为空。先降 effort，任务确实需要更多空间时再提高上限。

## Key、模型 ID、工具续接报错怎么修

这次成功运行没有产生报错。下表按链接的 OpenCode 和 MiniMax 文档整理。配置里的完整 Base URL 是 `https://api.omniakey.com/v1`。

|现象|先查什么|怎么修|
|-|-|-|
|`401` 或 `403`|server 进程里有没有 `OMNIAKEY_API_KEY`？|在启动 OpenCode 的 shell 里 export，或用 `--standalone`；Key 不要写进 JSON。|
|`Model unavailable` 或找不到模型|`models` 的键和 `modelID` 是否都是 `minimax-m3.1-flash`？|核对拼写和大小写；不要填上游的 `MiniMax-M3.1-Flash`；确认 provider 已启用。|
|网关返回 `404`|`settings.baseURL` 是不是完整的 OmniaKey 地址？|改成上面写明的完整 Base URL，不要多加路径。|
|`400` 要求 adaptive thinking|客户端有没有传关闭思考，或传了 `none`？|删掉，改用更低的 effort。|
|第一次工具调用后就停|有没有设 reasoningField？历史里有没有 reasoning\_content？|设成 `"reasoning_content"`，用同一提示词重试。|
|输出为空，`finish_reason` 是 `length`|思考 token 是否吃满了输出上限？|先降 effort，再考虑提高 `max_tokens`。|
|30 万 token 的提示词报上下文错误|OpenCode 是否还按 20 万 fallback 算？|把 `limit.context` 设成 1000000，并精简提示词。|
|图片或 PDF 输入失败|OmniaKey 模型页有没有列出视觉输入？|只发文本，先把文件转成文字。|

工具续接失败看起来像模型本身的问题，也可能出在配置上。[MiniMax 的 API 参考](https://platform.minimax.io/docs/api-reference/text-openai-api.md)要求多轮工具调用时，把完整的 assistant 响应放回历史，包括 `tool_calls` 和 `reasoning_content` 里的思考。[OpenCode 的 reasoningField 设置](https://opencode.ai/docs/models.md)负责从流里读这个字段，并在下一轮发回历史时还原。

这次运行里，每次后续请求的 assistant 工具调用消息都带着 `reasoning_content` 字段，六次请求都完成了，每次工具结果也进入了下一轮。

## 费用、权限和国内怎么用

OmniaKey 按 token 计费，实时价格看模型页。这次六次调用用了 20,739 个输入 token（含缓存命中的前缀）和 803 个输出 token。估算同类任务时，把用量拆成未缓存输入、缓存读取输入和输出，分别乘对应的当前单价。输入总数不能直接乘一个价格。

换到自己的仓库，权限从全部拒绝开始，只加任务需要的目录和命令。编辑权限留在任务会改的文件上，shell 权限留在测试命令上。Provider 和模型这两段可以照用，权限这段要按项目重写。

国内用 OmniaKey 不用另外换配置。网站支持支付宝和微信充值，一个 Key 可以调用目录里的多家模型。OpenCode 这边仍然是同一个 Base URL，只换模型名。

同一把 Key 和同一个 Base URL 也适用于别的客户端。OmniaKey 的 [Claude Code 接入指南](https://omniakey.com/zh/blog/claude-code-setup) 讲了同样的配置思路，[编程 Agent 文档](https://docs.omniakey.com/cn/coding) 有各工具的分步设置。

## 常见问题

### OpenCode V1 能用这份配置吗？

这次实测的是 OpenCode v2.2.3，配置用的是 V2 的 providers 结构。V1 的结构不同，先在旧版本里看版本号，再按对应版本的文档改。

### `opencode --standalone models` 要加 provider 名吗？

不用。实测命令就是 `opencode --standalone models`，后面没有位置参数。输出里会列出 `omniakey/minimax-m3.1-flash`。

### 能发图片或 PDF 吗？

OmniaKey 的模型页没有列视觉输入，这份配置也只声明了文本。先把图片或 PDF 转成文字再发。MiniMax 上游模型支持图片，但 OmniaKey 这个模型页没有列这项能力。

### `max_tokens` 能超过 4096 吗？

可以改高。4096 只是这次测试的客户端上限，当前页面没有写明这条通道的单次最大输出。思考 token 也算在里面，看到长度截断或内容为空时，先降 effort，再提高上限。

## 已核对来源

- [OpenCode Providers](https://opencode.ai/docs/providers/) — 2026 年 11 月 12 日核对
- [OpenCode Models](https://opencode.ai/docs/models.md) — 2026 年 11 月 12 日核对
- [OpenCode CLI](https://opencode.ai/docs/cli.md) — 2026 年 11 月 12 日核对
- [MiniMax 文本生成指南](https://platform.minimax.io/docs/guides/text-generation.md) — 2026 年 11 月 12 日核对
- [MiniMax OpenAI 兼容 API 参考](https://platform.minimax.io/docs/api-reference/text-openai-api.md) — 2026 年 11 月 12 日核对
- [OmniaKey：MiniMax M3.1 Flash](https://omniakey.com/zh/minimax-m3-1-flash) — 2026 年 11 月 12 日核对