# MiniMax M3.1 Flash no OpenCode: configuração testada e chamadas de ferramenta

> Configurar MiniMax M3.1 Flash no OpenCode v2.2.3: provider completo, ID do modelo, chamadas de ferramenta reais e correções de erros de chave e contexto.

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

---

[MiniMax M3.1 Flash](https://omniakey.com/pt-BR/minimax-m3-1-flash) funciona no OpenCode v2.2.3 por meio de um [provider próprio compatível com OpenAI](https://opencode.ai/docs/providers/). O nome exato do modelo no OpenCode é `omniakey/minimax-m3.1-flash`, a Base URL é `https://api.omniakey.com/v1`, e a configuração abaixo concluiu uma tarefa real de repositório em 12 de novembro de 2026: cinco leituras, uma escrita, uma execução de `node --test` e 12 de 12 testes passando.

O OpenCode fala o formato OpenAI Chat Completions com um provider próprio, e a OmniaKey entrega esse formato em /v1. Cabe tudo em um arquivo de projeto, mas três detalhes decidem se funciona: o ID do modelo precisa seguir a grafia da OmniaKey, a chave precisa chegar ao processo do servidor do OpenCode e a configuração do provider precisa preservar o campo de raciocínio entre as chamadas de ferramenta.

## O que você precisa antes de começar

Use o OpenCode V2. A versão testada foi a v2.2.3. O V2 coloca providers próprios em um objeto providers de primeiro nível; os exemplos do V1 têm outro formato. Confira [a documentação de providers do V2](https://opencode.ai/docs/providers/) e `opencode --version` antes de copiar a configuração.

- OpenCode: v2.2.3, testado em 12 de novembro de 2026.
- ID do modelo na OmniaKey: `minimax-m3.1-flash`.
- Referência no OpenCode: `omniakey/minimax-m3.1-flash`.

Crie uma chave da OmniaKey e coloque em `OMNIAKEY_API_KEY`. O JSON abaixo nomeia a variável e nunca contém o segredo. Escolha um repositório pequeno com um comando de teste já existente; o teste usou um exemplo Node com `src/normalize.js`, um arquivo de teste e um script de teste.

A API própria da MiniMax usa o ID com maiúsculas misturadas `MiniMax-M3.1-Flash`. A OmniaKey usa a forma minúscula `minimax-m3.1-flash`. No opencode.jsonc, use o ID minúsculo da OmniaKey nos dois lugares, a chave do mapa models e o `modelID`; outra caixa não bate com o ID da OmniaKey.

Se você ainda está escolhendo modelo, a [análise do MiniMax M3.1 Flash](https://omniakey.com/pt-BR/blog/minimax-m3-1-flash-review) reúne benchmarks, informações de lançamento e o raciocínio sempre ativo.

## A configuração do OpenCode V2 que testamos

Coloque este arquivo na raiz do projeto como opencode.jsonc. É a forma pública da configuração usada na execução.

```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"}
  ]
}
```

O array env diz ao OpenCode qual variável de credencial ler: `OMNIAKEY_API_KEY` vem do ambiente do processo do servidor. `modelID` é o ID enviado à OmniaKey, enquanto a chave do mapa models é o ID que o OpenCode usa nas referências provider/model. Manter os dois como `minimax-m3.1-flash` evita uma busca ambígua.

Os blocos limit e capabilities substituem [os padrões do OpenCode para um modelo desconhecido](https://opencode.ai/docs/models.md). Sem eles, o OpenCode supõe contexto de 200.000 tokens e entrada de imagens. [A página do modelo na OmniaKey](https://omniakey.com/pt-BR/minimax-m3-1-flash) informa contexto de 1M tokens e nenhuma entrada de visão, então a configuração define o limite em `1000000` e a entrada apenas como texto. O 1M é a janela publicada, não um tamanho que esta tarefa pequena tenha esgotado.

O bloco body traz os dois valores testados: esforço de raciocínio medium e teto de `max_tokens` em 4096. A lista de effort em capabilities reúne os cinco níveis descritos no guia da MiniMax; o usado no teste foi medium.

O bloco permissions é estreito de propósito para o repositório de demonstração. Ele nega tudo e depois libera leitura, glob e grep, uma edição em `src/normalize.js`, o comando `node --test` e git diff. Também nega diretórios externos. Troque o caminho e os comandos pelas regras do seu projeto. Uma liberação ampla de edição ou de shell dá ao agente muito mais acesso do que uma tarefa delimitada exige.

## Rode com a chave no shell do servidor

O OpenCode normalmente inicia ou encontra um servidor compartilhado em segundo plano. Esse servidor guarda sessões, configuração e execução de ferramentas, e lê as variáveis env do provider no próprio ambiente. Uma chave exportada em outro terminal não chega até ele. A [documentação da CLI do OpenCode](https://opencode.ai/docs/cli.md) descreve o servidor compartilhado e a opção `--standalone`.

Para uma primeira execução previsível, use um servidor privado a partir de um shell que tenha a chave:

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

O comando models testado não leva argumento de provider. Ele lista `omniakey/minimax-m3.1-flash`. Depois rode uma tarefa. O teste usou este argumento de modelo e o bloco de prompt abaixo; troque o marcador pelo texto exato:

```bash
# Replace <task prompt> with the text from the prompt block below.
opencode --standalone run --model omniakey/minimax-m3.1-flash '<task prompt>'
```

A opção `--standalone` inicia um servidor privado a partir desse shell, então ele herda a chave e lê a configuração do projeto. Um servidor compartilhado iniciado antes vê apenas o próprio ambiente. A linha da chave acima é um marcador; o arquivo de configuração continua sem segredo.

Se você já tem um servidor compartilhado em um ambiente com OMNIAKEY\_API\_KEY, pode usá-lo. Quando esse ambiente não está claro, o servidor privado é o caminho reproduzível.

## Confira o ciclo de leitura, escrita e teste

Um exemplo pequeno em Node basta para ver se as chamadas de ferramenta funcionam. O exemplo tinha `src/normalize.js` com um stub que só ordenava, um arquivo de teste com 12 casos e um script node --test. Antes da correção, 3 testes passavam e 9 falhavam.

Este é o prompt usado na execução, sem alterações:

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

A execução fez sete operações de ferramenta em seis requisições HTTP, todas com resposta 200:

|Ferramenta|Vezes|O que cobriu|
|-|-|-|
|`read`|5|Lista do repositório, fonte, pasta de teste, `package.json`, arquivo de teste|
|`write`|1|`src/normalize.js`|
|`shell`|1|`node --test`|

O primeiro turno enviou duas leituras em paralelo, uma da lista do repositório e outra da fonte. Os dois turnos seguintes leram a pasta de teste, o arquivo de pacote e o arquivo de teste. A escrita substituiu a fonte. A chamada de shell rodou os testes. A execução levou 70,172 segundos.

A chamada de teste dentro do ciclo reportou:

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

A resposta final nomeou o arquivo alterado e o resultado 12/12. Os seis blocos de usage somam 20.739 tokens de entrada, incluindo as leituras de prefixo em cache, e 803 tokens de saída. A maior completion teve 363 tokens, então o teto de 4096 nunca foi alcançado.

Um processo local de encaminhamento mandou o corpo da requisição e a resposta em streaming para a OmniaKey sem alteração. É uma tarefa pequena: confirma que o ciclo de ler, escrever e testar funciona neste repositório, não que o modelo seja rápido ou limpo em qualquer código.

## Ajuste esforço, contexto e saída

O raciocínio é obrigatório no M3.1 Flash. [O guia de geração de texto da MiniMax](https://platform.minimax.io/docs/guides/text-generation.md) diz que o modelo sempre pensa, e a [referência da API compatível com OpenAI](https://platform.minimax.io/docs/api-reference/text-openai-api.md) devolve HTTP 400 se um cliente enviar `thinking: {"type": "disabled"}` ou `reasoning_effort: "none"`. Deixe o raciocínio ligado e baixe o esforço quando quiser um turno mais curto.

|Ajuste|Valor testado|O que controla|
|-|-|-|
|`reasoning_effort`|`medium`|Quanto o modelo pensa antes de responder|
|`max_tokens`|`4096`|Teto de saída do cliente por chamada|
|`limit.context`|`1000000`|Janela de contexto publicada|

`reasoning_effort` aceita low, medium, high, xhigh e max; quando omitido, [o guia da MiniMax](https://platform.minimax.io/docs/guides/text-generation.md) diz que o padrão é max. Medium bastou para esta tarefa delimitada. Baixar o esforço encurta o raciocínio, mas não o desliga.

Os controles de amostragem não fazem nada neste modelo. [A referência da API da MiniMax](https://platform.minimax.io/docs/api-reference/text-openai-api.md) diz que o M3.1 Flash usa sempre 1 e 0,95, então remover temperature e top\_p é mais limpo do que ajustar valores ignorados.

O contexto de 1M tokens vem da [página do modelo na OmniaKey](https://omniakey.com/pt-BR/minimax-m3-1-flash) e do [guia da MiniMax](https://platform.minimax.io/docs/guides/text-generation.md). O limite de saída de 4096 é um teto de segurança do cliente escolhido para esta execução, não um máximo publicado pelo provedor. Tokens de raciocínio contam dentro desse teto, então um turno longo de pensamento pode terminar com `finish_reason: "length"` e pouco ou nenhum texto final. Baixe o esforço primeiro e suba o teto depois, se a tarefa precisar de mais espaço.

## Corrija erros de chave, ID e continuação

A execução bem-sucedida não gerou erros. Esta lista segue a documentação linkada do OpenCode e da MiniMax. A Base URL exata é `https://api.omniakey.com/v1`.

|Sintoma|O que verificar|Correção|
|-|-|-|
|`401` ou `403`|`OMNIAKEY_API_KEY` está no ambiente do servidor?|Exporte no shell que inicia o OpenCode ou use `--standalone`; mantenha a chave fora do JSON.|
|`Model unavailable` ou modelo não encontrado|A chave do mapa e `modelID` dizem `minimax-m3.1-flash`?|Corrija grafia e caixa; não use o ID `MiniMax-M3.1-Flash` do provedor; confirme que o provider está ativo.|
|`404` do gateway|`settings.baseURL` é exatamente o endereço da OmniaKey?|Use a Base URL exata acima e remova qualquer caminho extra.|
|`400` sobre adaptive thinking|Algum cliente enviou raciocínio desligado ou `reasoning_effort: "none"`?|Remova e baixe o esforço.|
|Para após a primeira chamada de ferramenta|O campo de raciocínio está configurado? O histórico o inclui?|Defina `reasoningField` como `"reasoning_content"` e repita o mesmo prompt.|
|Conteúdo vazio, `finish_reason: "length"`|O raciocínio consome o teto de saída?|Baixe o esforço primeiro e depois suba `max_tokens`.|
|Erro de contexto em um prompt de 300K|O OpenCode ainda usa o padrão de 200K?|Defina `limit.context` como `1000000` e encurte o prompt.|
|Entrada de imagem ou PDF falha|A página da OmniaKey lista visão?|Envie só texto e converta o arquivo antes.|

A continuação pode falhar na configuração mesmo quando parece problema do modelo. [A referência da API da MiniMax](https://platform.minimax.io/docs/api-reference/text-openai-api.md) pede para anexar a resposta completa do assistant aos turnos seguintes, incluindo `tool_calls` e o raciocínio devolvido em `reasoning_content`. [O ajuste reasoningField do OpenCode](https://opencode.ai/docs/models.md) lê esse campo no stream e o restaura ao enviar o histórico.

Nesta execução, cada requisição de acompanhamento levou o campo `reasoning_content` nas mensagens de chamada de ferramenta do assistant, as seis requisições terminaram e cada resultado de ferramenta alimentou o turno seguinte.

## Custo, permissões e próximos passos

A OmniaKey cobra por token conforme as tarifas atuais na página do modelo. As seis chamadas usaram 20.739 tokens de entrada, incluindo as leituras de prefixo em cache, e 803 tokens de saída. Para estimar uma tarefa parecida, separe o uso em entrada sem cache, entrada lida do cache e saída, e multiplique cada parte pela tarifa atual correspondente. O total de entrada não se multiplica por uma tarifa única.

No seu repositório, comece pela regra que nega tudo e acrescente só as pastas e comandos que a tarefa precisa. Mantenha a permissão de edição nos arquivos que a tarefa altera e a de shell no comando de teste. Essa é a parte que se reescreve em cada projeto; os blocos de provider e de modelo podem ficar como estão.

O mesmo padrão de chave e Base URL vale para outros clientes. O [guia de configuração do Claude Code](https://omniakey.com/pt-BR/blog/claude-code-setup) da OmniaKey cobre esse cliente, e a [documentação de agentes de código](https://docs.omniakey.com/en/coding) lista os passos por ferramenta.

## Perguntas frequentes

### Esta configuração funciona no OpenCode V1?

A versão testada é o OpenCode v2.2.3 e a configuração usa o objeto providers no plural do V2. As páginas do V1 têm outro formato, então confira a versão antes de copiar para uma instalação antiga.

### `opencode --standalone models` precisa de filtro de provider?

Não. O comando testado é exatamente `opencode --standalone models`, sem argumento de provider. Ele lista `omniakey/minimax-m3.1-flash`.

### Posso enviar imagens ou PDFs para este modelo pela OmniaKey?

A página do modelo na OmniaKey não lista visão e a configuração testada declara apenas entrada de texto. Envie texto e converta imagens ou PDFs antes. O modelo original da MiniMax aceita imagens, mas isso não acrescenta entrada de imagem à página do modelo na OmniaKey.

### Posso subir `max_tokens` acima de 4096?

Sim, o teto do cliente pode subir. 4096 foi o valor testado e as páginas atuais não indicam um máximo fixo para este modelo. O raciocínio conta dentro do teto, então fique atento a corte por tamanho ou conteúdo vazio; baixe o esforço primeiro e depois suba o teto.

## Fontes verificadas

- [OpenCode Providers](https://opencode.ai/docs/providers/) — verificado em 12 de novembro de 2026
- [OpenCode Models](https://opencode.ai/docs/models.md) — verificado em 12 de novembro de 2026
- [OpenCode CLI](https://opencode.ai/docs/cli.md) — verificado em 12 de novembro de 2026
- [Guia de geração de texto da MiniMax](https://platform.minimax.io/docs/guides/text-generation.md) — verificado em 12 de novembro de 2026
- [Referência da API compatível com OpenAI da MiniMax](https://platform.minimax.io/docs/api-reference/text-openai-api.md) — verificado em 12 de novembro de 2026
- [OmniaKey: MiniMax M3.1 Flash](https://omniakey.com/pt-BR/minimax-m3-1-flash) — verificado em 12 de novembro de 2026