OpenCode에서 MiniMax M3.1 Flash 사용하기: 설정과 도구 호출

MiniMax M3.1 Flash는 OpenCode v2.2.3에서 OpenAI 호환 사용자 Provider로 동작합니다. OpenCode에 넣는 모델 이름은 omniakey/minimax-m3.1-flash이고 Base URL은 https://api.omniakey.com/v1입니다. 2026년 11월 12일, 아래 설정으로 실제 저장소 작업 하나를 끝냈습니다. 읽기 5회, 쓰기 1회, node --test 1회를 실행했고 테스트 12개가 모두 통과했습니다.

OpenCode의 사용자 Provider는 OpenAI Chat Completions 형식으로 통신하고 OmniaKey는 /v1에서 이 형식을 받습니다. 설정 파일은 프로젝트에 하나 두면 되지만, 실제로 갈리는 지점은 세 가지입니다. 모델 ID를 OmniaKey 표기와 똑같이 맞추는 것, Key를 OpenCode server 프로세스가 읽게 하는 것, 도구 호출을 거치는 동안 모델의 사고 필드를 보존하는 것입니다.

시작하기 전에 준비할 것

OpenCode는 V2를 사용합니다. 실측 버전은 v2.2.3입니다. V2는 사용자 Provider를 최상위 providers 객체에 넣고, V1 예제는 구조가 다릅니다. 설정을 복사하기 전에 V2 Provider 문서와 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 값은 없습니다. 테스트 명령이 이미 있는 작은 저장소를 준비하십시오. 실측에는 src/normalize.js, 테스트 파일 하나, 테스트 스크립트가 있는 Node 예제를 썼습니다.

MiniMax 자체 API의 모델 ID는 대소문자가 섞인 MiniMax-M3.1-Flash입니다. OmniaKey는 전부 소문자인 minimax-m3.1-flash를 씁니다. opencode.jsonc에서는 models 키와 modelID, 두 곳 모두에 OmniaKey의 소문자 ID를 넣으십시오. 대소문자가 다르면 OmniaKey의 ID와 일치하지 않습니다.

모델을 아직 고르는 중이라면 MiniMax M3.1 Flash 리뷰에 벤치마크, 출시 정보, 항상 켜지는 사고 방식이 정리되어 있습니다.

실측한 OpenCode V2 설정

프로젝트 최상위에 opencode.jsonc로 저장합니다. 실행에 쓴 설정을 공개할 수 있는 형태로 그대로 옮긴 것입니다.

{
  "$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가 어떤 환경 변수를 자격 증명으로 읽을지 정합니다. OMNIAKEY_API_KEY는 server 프로세스의 환경에서 들어옵니다. modelID는 OmniaKey로 보내는 ID이고 models의 키는 OpenCode가 provider/model 참조에 쓰는 ID입니다. 둘 다 minimax-m3.1-flash로 두면 이름을 찾을 때 헷갈리지 않습니다.

limit와 capabilities는 모르는 모델에 대한 OpenCode 기본값을 덮어씁니다. 기본값은 컨텍스트 20만 토큰과 이미지 입력을 가정합니다. OmniaKey 모델 페이지에는 컨텍스트 1M 토큰이 적혀 있고 비전 항목은 없습니다. 그래서 컨텍스트 상한을 1000000으로 두고 입력은 텍스트만 선언했습니다. 1M은 공개된 창 크기이며 이번 작은 작업에서 끝까지 쓰지는 않았습니다.

body에는 이번 실행에서 시험한 두 값, medium 사고와 max_tokens 4096이 들어 있습니다. capabilities의 effort 목록은 MiniMax 문서가 제시하는 다섯 단계이고, 테스트에는 medium을 썼습니다.

permissions는 데모 저장소에 맞춰 좁게 잡았습니다. 먼저 모두 거부한 뒤 읽기, glob, grep, src/normalize.js 편집, node --test와 git diff만 허용합니다. 외부 디렉터리는 거부합니다. 내 프로젝트로 옮길 때는 파일 경로와 명령을 바꾸십시오. 저장소 전체 편집과 임의 shell 실행을 허용하면 이 규모의 작업에는 권한이 너무 큽니다.

Key는 server를 띄운 shell에 둡니다

OpenCode는 보통 공유 백그라운드 server를 띄우거나 이미 도는 server를 찾아 씁니다. 세션, 설정, 도구 실행을 이 server가 맡고 Provider의 env도 server 자신의 환경에서 읽습니다. 다른 터미널에서 export한 Key는 닿지 않습니다. 공유 server와 --standalone의 동작은 OpenCode CLI 문서에 나옵니다.

처음 실행할 때는 Key가 있는 shell에서 전용 server를 띄우면 결과가 분명합니다.

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

실측한 models 명령에는 provider 인자를 넣지 않습니다. 목록에 omniakey/minimax-m3.1-flash가 보이면 설정이 읽힌 것입니다. 이어서 작업 하나를 실행합니다. 실측에 쓴 모델 인자와 아래 프롬프트 블록을 조합한 형태이며, 표시해 둔 자리표시자를 프롬프트 전문으로 바꿉니다.

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

--standalone은 그 shell에서 전용 server를 띄우므로 server가 Key를 물려받고 프로젝트 설정도 읽습니다. 먼저 띄운 공유 server는 자기 환경만 봅니다. 위 Key 줄은 자리표시자이고 설정 파일에는 여전히 비밀이 없습니다.

이미 OMNIAKEY_API_KEY가 있는 환경에서 공유 server를 돌리고 있다면 그대로 써도 됩니다. 환경이 불분명할 때는 전용 server가 재현하기 쉬운 길입니다.

읽기, 쓰기, 테스트 한 바퀴 확인

도구 호출이 되는지는 작은 Node 예제로 충분합니다. 준비한 예제에는 정렬만 하는 스텁이 있는 src/normalize.js, 12개 케이스의 테스트 파일, node --test 스크립트가 있었습니다. 수정 전에는 3개가 통과하고 9개가 실패했습니다.

실행에 쓴 프롬프트는 다음과 같습니다.

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.

실행 중 HTTP 요청은 6회였고 모두 200으로 돌아왔습니다. 도구 작업은 7회였습니다.

첫 턴에서 저장소 목록과 소스를 나란히 읽었고, 다음 두 턴에서 테스트 디렉터리, package.json, 테스트 파일을 읽었습니다. 쓰기가 소스를 바꿨고 마지막 shell 호출이 테스트를 돌렸습니다. 걸린 시간은 70.172초입니다.

루프 안의 테스트 출력은 다음과 같습니다.

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

마지막 답변은 바뀐 파일과 12/12 결과를 알려 주었습니다. 6회의 usage를 더하면 캐시로 읽은 앞부분을 포함해 입력 20,739토큰, 출력 803토큰입니다. 한 번의 출력은 최대 363토큰이라 4096 상한에는 닿지 않았습니다.

로컬 전달 프로세스가 요청 본문과 스트림 응답을 바꾸지 않고 OmniaKey로 보냈습니다. 작은 작업 하나의 기록이며, 이 저장소에서 읽기, 쓰기, 테스트 한 바퀴가 돌았다는 확인입니다. 속도나 코드 품질을 넓게 비교한 측정은 아닙니다.

effort, 컨텍스트, 출력 상한 정하기

M3.1 Flash는 사고를 끌 수 없습니다. MiniMax 텍스트 생성 가이드는 항상 사고한다고 밝히고, thinking: {"type": "disabled"}나 reasoning_effort: "none"을 보내면 OpenAI 호환 API 참조가 HTTP 400을 돌려줍니다. 턴을 줄이고 싶으면 사고를 끄지 말고 effort를 낮추십시오.

reasoning_effort는 low, medium, high, xhigh, max를 받고, 생략하면 MiniMax 가이드 기준으로 max입니다. 이번 작업은 범위가 좁아 medium으로 충분했습니다. effort를 낮추면 사고가 짧아질 뿐 사고 자체는 꺼지지 않습니다.

temperature와 top_p는 이 모델에서 작동하지 않습니다. MiniMax API 참조에 따르면 M3.1 Flash는 항상 1과 0.95를 쓰므로, 무시되는 값을 조정하기보다 두 필드를 지우는 편이 깔끔합니다.

1M 토큰 컨텍스트는 OmniaKey 모델 페이지와 MiniMax 가이드에 적힌 값입니다. 4096은 이번 실행을 위해 정한 클라이언트 상한이고 제공사가 공개한 최대 출력은 아닙니다. 사고 토큰도 이 상한에 포함되므로 긴 사고 끝에 finish_reason: "length"로 끝나고 본문이 거의 남지 않을 수 있습니다. 먼저 effort를 낮추고, 그래도 공간이 부족할 때 상한을 올리십시오.

Key, 모델 ID, 이어짐 오류 해결

성공한 실행에서는 오류가 나오지 않았습니다. 아래 표는 링크한 OpenCode와 MiniMax 문서를 기준으로 정리한 점검 항목입니다. Base URL은 https://api.omniakey.com/v1이 전체 형태입니다.

이어짐 실패는 모델 문제처럼 보여도 설정에서 생깁니다. MiniMax API 참조는 assistant 응답을 tool_calls와 reasoning_content의 사고까지 포함해 다음 턴 기록에 넣으라고 요구합니다. OpenCode의 reasoningField 설정은 그 필드를 스트림에서 읽어 기록을 보낼 때 되살립니다.

이번 실행에서는 두 번째 요청부터 모든 assistant 도구 호출 메시지에 reasoning_content가 붙었고, 6회 요청이 모두 끝까지 갔으며, 각 도구 결과가 다음 턴으로 넘어갔습니다.

비용, 권한, 다음 단계

OmniaKey는 토큰 단위로 과금하고 단가는 모델 페이지의 현재 요율을 따릅니다. 이번 6회 호출은 캐시로 읽은 앞부분을 포함해 입력 20,739토큰, 출력 803토큰을 썼습니다. 비슷한 작업을 가늠할 때는 사용량을 캐시 없는 입력, 캐시 읽기 입력, 출력으로 나누고 각각 현재 단가를 곱하십시오. 입력 합계에 단가 하나를 곱하는 계산은 맞지 않습니다.

내 저장소에서는 모두 거부에서 시작해 작업에 필요한 폴더와 명령만 더하십시오. 편집 권한은 작업이 바꾸는 파일에, shell 권한은 테스트 명령에 남깁니다. 프로젝트마다 다시 쓸 부분은 이 부분이고 Provider와 모델 블록은 그대로 두어도 됩니다.

같은 Key와 Base URL 조합은 다른 클라이언트에도 적용됩니다. OmniaKey의 Claude Code 설정 가이드는 Claude Code 절차를, 코딩 에이전트 문서는 도구별 단계를 다룹니다.

자주 묻는 질문

OpenCode V1에서도 이 설정을 쓸 수 있나요?

실측 버전은 OpenCode v2.2.3이고 설정은 V2의 복수형 providers 객체를 씁니다. V1은 구조가 다르므로 오래된 설치에 복사하기 전에 버전을 확인하십시오.

opencode --standalone models에 provider 이름이 필요한가요?

필요 없습니다. 실측 명령은 opencode --standalone models이고 위치 인자가 없습니다. 목록에 omniakey/minimax-m3.1-flash가 나옵니다.

OmniaKey를 통해 이미지나 PDF를 보낼 수 있나요?

OmniaKey 모델 페이지에는 비전 입력이 없고 실측 설정도 텍스트 입력만 선언합니다. 텍스트를 보내고 이미지나 PDF는 먼저 글자로 바꾸십시오. MiniMax 상류 모델은 이미지를 받지만, 그 사실이 OmniaKey 모델 페이지에 이미지 입력을 더하지는 않습니다.

max_tokens를 4096보다 높일 수 있나요?

클라이언트 상한은 올릴 수 있습니다. 4096은 실측값이고 현재 페이지에 이 모델의 고정 최댓값은 적혀 있지 않습니다. 사고도 상한에 포함되므로 길이로 잘리거나 본문이 비는지 살피고, effort를 먼저 낮춘 뒤 상한을 올리십시오.

확인한 출처

• OpenCode Providers — 2026년 11월 12일 확인
• OpenCode Models — 2026년 11월 12일 확인
• OpenCode CLI — 2026년 11월 12일 확인
• MiniMax 텍스트 생성 가이드 — 2026년 11월 12일 확인
• MiniMax OpenAI 호환 API 참조 — 2026년 11월 12일 확인
• OmniaKey: MiniMax M3.1 Flash — 2026년 11월 12일 확인