官方 OpenCode 教程配置问题：国内 API 的 OpenAI 兼容接口不支持 developer 角色 (2013)

[BeastOrange]

问题描述

MiniMax 官方 OpenCode 教程 存在以下问题：

1. 教程仅提供国际站（.io）配置

官方教程推荐的 baseURL 是 https://api.minimax.io/anthropic/v1，这是国际站地址。国内用户使用 api.minimaxi.com 的 API Key 无法使用此地址，需要改为 https://api.minimaxi.com/anthropic/v1，但教程中未提及。

2. OpenAI 兼容接口不支持 developer 角色

OpenCode 内置的模型切换（cc switch）默认使用 @ai-sdk/openai-compatible 生成配置。但 MiniMax 国内 API（api.minimaxi.com/v1）的 OpenAI 兼容接口不支持 developer 角色，导致 OpenCode 完全无法使用。

复现步骤

curl -X POST "https://api.minimaxi.com/v1/chat/completions" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M2.5",
    "messages": [
      {"role": "developer", "content": "You are a helpful assistant"},
      {"role": "user", "content": "hi"}
    ],
    "max_tokens": 5
  }'

返回错误

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, invalid role: developer (2013)",
    "http_code": "400"
  }
}

原因分析

developer 角色是 OpenAI Chat Completions API 规范 中的标准角色，Vercel AI SDK（@ai-sdk/openai-compatible）会默认将系统消息以 "role": "developer" 发送。MiniMax 的 OpenAI 兼容接口未兼容此角色，导致 OpenCode、Roo Code、Kilo Code 等主流 AI 编程工具无法正常使用。

相关 issue：

• Kilo Code: #3967
• Roo Code: #9131
• Ollama: #14220（invalid role: thinking 类似问题）

当前 workaround

必须手动将配置从 OpenAI 兼容改为 Anthropic 兼容：

{
  "provider": {
    "minimax": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://api.minimaxi.com/anthropic/v1",
        "apiKey": "<MINIMAX_API_KEY>"
      },
      "models": {
        "MiniMax-M2.5": {
          "name": "MiniMax-M2.5"
        }
      }
    }
  }
}

建议

1. API 侧：在 OpenAI 兼容接口中将 developer 映射为 system，与 OpenAI 规范保持一致
2. 文档侧：在官方教程中补充国内站（api.minimaxi.com）的配置说明

[ximiximi423]

感谢您的反馈。

1. 为了能正确使用 interleaved thinking 以确保模型效果，推荐使用 Anthropic 兼容方式接入 opencode
2. 官网已有国内站 (api.minimaxi.com)的配置说明，可参考 opencode 使用教程
3. 上述提到的其他编程工具的 issue，roo code 的 issue 是超过上下文窗口了，该问题已修复。kilo code 的 issue 与tool call 有关，如果后续遇到相同的问题，欢迎反馈具体的 trace id 帮助我们进一步排查。