LinuxDo 新帖推送

标题: 还在死磕之解决 OpenCode + CPA 代理 Gemini 模型 404/角色错误问题
作者: #Low-kii
板块: #开发调优
编号: 1495226
帖子: https://linux.do/t/topic/1495226
时间: 2026-01-21 16:40:55
摘要:
背景
使用 CPA 作为 API 代理，配合OpenCode，想要通过 OpenAI 兼容格式调用 Gemini 3
系列模型。
环境配置：

CPA 部署在自用云服务器，配置了 OpenAI 兼容转发
上游服务：https://***.com（支持多模型的 API 服务｜newapi）
本地客户端：OpenCode


问题现象

第一个错误：404 Not Found



POST “/v1/models/gemini-3-flash-preview:streamGenerateContent?alt=sse” 404


请求直接返回 404，模型无法调用。



第二个错误：Invalid Role



修复 404 后，出现新错误：


Invalid param: Please use a valid role: user, model.



问题分析

404 问题分析



查看 CPA 日志发现请求路径是：/v1/models/gemini-3-flash-preview:streamGenerateContent?alt=sse;这是 Gemini 原生 API 格式，而不是 OpenAI 兼容格式 (/v1/chat/completions)。


原因：OpenCode 检测到模型名包含 gemini 关键字，自动切换到 Gemini 原生协议。



Invalid Role 问题分析



修复 404 后，查看日志发现请求走的是：POST “/v1/responses” 400;这是 OpenAI 新的 Responses API（用于 GPT-5.x 等新模型），而不是传统的/v1/chat/completions。


原因：OpenCode 配置中 openai provider 包含 reasoningEffort 等参数，触发了新 API格式。而 Responses API 使用 role: “assistant”，Gemini API 期望 role:“model”，上游服务没有正确转换角色名。



解决方案

步骤 1：CPA 配置 - 给 Gemini 模型设置别名

修改服务器上的 /path/to/cpa/config.yaml，给 Gemini 模型设置不含 “gemini” 关键字的别名：
  openai-compatibility:
    - name: claude
      base-url: https://***.com/v1
      api-key-entries:
        - api-key: sk-xxxxx
      models:
        # Claude 模型
        - name: claude-opus-4-5-20251101
          alias: claude-opus-4-5
        # Gemini 模型 - 使用不含 "gemini" 的别名
        - name: gemini-3-flash-preview
          alias: "g3-flash-preview"
        - name: gemini-3-pro-preview
          alias: "g3-pro-preview"
        - name: gemini-3-pro-image-preview
          alias: "g3-pro-image-preview"

重启 CPA 容器：
docker restart cpa

步骤 2：OpenCode 配置 - 创建独立 Provider
关键点：不要把 Gemini 模型放在带有 reasoningEffort 等参数的 openai provider
下，否则会触发 Responses API。
创建一个独立的 provider：

{
    "provider": {
      "openai": {
        "name": "OpenAI",
        "options": {
          "baseURL": "https://***.com/v1",
          "apiKey": "your-key",
          "reasoningEffort": "medium"  // 这会触发 Responses API
        },
        "models": {
          "gpt-5.2": { ... }  // GPT 模型放这里
        }
      },

      "openai-compat": {
        "name": "Gemini via CPA",
        "options": {
          "baseURL": "https://***.com/v1",
          "apiKey": "your-key"
          // 注意：不要加 reasoningEffort 等参数！
        },
        "models": {
          "g3-pro-preview": {
            "name": "Gemini 3 Pro Preview",
            "limit": {
              "context": 1048576,
              "output": 65535
            }
          },
          "g3-flash-preview": {
            "name": "Gemini 3 Flash Preview",
            "limit": {
              "context": 1048576,
              "output": 65535
            }
          },
          "g3-pro-image-preview": {
            "name": "Gemini 3 Pro Image Preview",
            "limit": {
              "context": 1048576,
              "output": 65536
            }
          }
        }
      }
    }
  }


问题总结




问题
原因
解决方案




404 错误
模型名含 gemini，OpenCode 自动用 Gemini 原生协议
设置不含 gemini 的别名


Invalid Role
reasoningEffort 参数触发 Responses API，角色名不兼容
创建独立provider，不加 reasoning 参数




关键

模型名称很重要：某些客户端会根据模型名自动选择协议，避免使用原厂商关键字（如gemini、claude）可以强制走 OpenAI 兼容格式。
OpenAI API 有两套格式：

传统：/v1/chat/completions
新版：/v1/responses（GPT-5.x，带 reasoning 功能）



自用经验仅供参考
1 view08:41