背景

使用 CPA 作为 API 代理，配合 OpenCode，想要通过 OpenAI 兼容格式调用 Gemini 3
系列模型。

环境配置：

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

问题现象

1. 第一个错误：404 Not Found

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

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

2. 第二个错误：Invalid Role

• 修复 404 后，出现新错误：

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

  ---

问题分析

1. 404 问题分析

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

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

2. 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. 步骤 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. 步骤 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 } } } } } } 

问题总结

关键

1. 模型名称很重要：某些客户端会根据模型名自动选择协议，避免使用原厂商关键字（如 gemini、claude）可以强制走 OpenAI 兼容格式。
2. OpenAI API 有两套格式：
   
   • 传统：/v1/chat/completions
   • 新版：/v1/responses（GPT-5.x，带 reasoning 功能）

自用经验仅供参考