ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

CCX 接入 OpenCode 实战指南:OpenAI Chat 兼容协议下的统一网关配置与排障

CCX 接入 OpenCode 实战指南:OpenAI Chat 兼容协议下的统一网关配置与排障 API网关LLM 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载本文面向使用 OpenCode 编码工具的开发者讲解如何通过 CCX 统一网关接入 OpenCode从 CCX Chat 渠道的添加、OpenCode 侧的自动/手动配置到模型映射与常见故障排查全流程均可直接落地。读完你将掌握 OpenCode → CCX/v1/chat/completions→ Chat 渠道 → 上游 Chat 兼容端点的完整调用链并能在 401、404、model_not_found 等典型异常下快速定位根因。OpenCode 在 CCX 中的工作方式OpenCode 使用的是OpenAI Chat 兼容协议因此在 CCX 中对应的代理入口是Chat。它与 Claude Code走 Messages 入口、Codex CLI走 Responses 入口的关键差异就在于 Base URL 规则与路由入口不同——OpenCode 的请求路径是/v1/chat/completions。OpenCode - CCX /v1/chat/completions - Chat 渠道 - 上游 Chat 兼容端点对应关系也可以从客户端接入总览中确认Claude Code - /v1/messages - Messages 渠道 Claude Desktop - /v1/messages - Messages 渠道经 HTTPS 包装层 Codex CLI / App - /v1/responses - Responses 渠道 OpenCode - /v1/chat/completions - Chat 渠道从 CCX 源码看Chat 代理处理器 明确实现了这一入口所有到达/v1/chat/completions的请求先经middleware.ProxyAuthMiddleware鉴权然后从请求体中提取model字段缺失时返回 400missing_parameter再根据是否处于多渠道模式分别进入多渠道故障转移调度或单渠道直连逻辑。也就是说OpenCode 只需把 CCX 当作一个OpenAI Chat 兼容的远端其余协议转换、渠道调度、多 Key 轮转与故障转移全部由 CCX 完成。如果你正在使用CCX Desktop可先在 Agent Config对应文档见 docs/guide/desktop/index.md中写入 OpenCode 配置再回到本页确认 Chat 入口和 Base URL 规则。一、配置 CCX 渠道在 OpenCode 接入之前先保证 CCX 侧有一个可用的Chat 渠道。步骤打开 CCX 管理界面默认http://localhost:3000进入Chat入口点击「添加渠道」添加一个 OpenAI Chat 兼容渠道常见上游配置如下服务类型统一选OpenAI Chat上游服务类型Base URL 示例OpenAIOpenAI Chathttps://api.openai.com/v1DeepSeekOpenAI Chathttps://api.deepseek.comGLMOpenAI Chathttps://open.bigmodel.cn/api/paas/v4MiniMaxOpenAI Chathttps://api.minimax.io/v1KimiOpenAI Chathttps://api.moonshot.ai/v1::: tip 不同上游的模型名、视觉能力和特殊开关不同。先完成对应提供商配置教程后再配置 OpenCode。 :::补充说明上表中的 Base URL 多数本身就是 OpenAI Chat 兼容端点但部分厂商同时提供 Anthropic Messages 兼容端点例如 DeepSeek 的https://api.deepseek.com/anthropic、GLM 的https://open.bigmodel.cn/api/anthropic。OpenCode 走的是 OpenAI Chat 协议因此必须选择 OpenAI Chat 兼容的 Base URL这一点在配置教程的服务类型选择指南中也有明确区分。在管理界面的渠道表单里与 OpenCode 接入关系最密切的字段包括字段说明名称渠道显示名称便于识别服务类型上游 API 协议类型OpenCode 场景选openaiBase URL上游 OpenAI Chat 兼容地址API Keys上游认证密钥支持多 Key 轮转模型白名单限制该渠道可用的模型列表影响 model_not_found模型映射将请求模型名映射为上游实际模型名优先级数字越小优先级越高影响多渠道调度从Chat 渠道管理实现可以看到CCX 为 Chat 入口提供了一整套管理 API/api/chat/channels的列表与创建、PUT/DELETE更新删除、reorder重排优先级、/api/chat/channels/:id/models查询上游模型列表、/api/chat/ping探测连通性等。其中PingChannel对 openai 类型上游会请求{baseURL}/models端点来验证连通性添加渠道后建议先用测试按钮确认渠道可用。二、配置 OpenCode使用 CCX Desktop 自动配置在Agent Config → OpenCode中默认选择CCX 本地网关。Desktop 会维护两个文件~/.config/opencode/opencode.jsonc写入 OpenAI 兼容自定义 provider例如provider.ccx.options.baseURL~/.local/share/opencode/auth.json写入对应 provider 的 API Key例如auth.ccx.key默认 CCX 模式写入的 Base URL 为http://127.0.0.1:当前 CCX 端口/v1OpenCode 使用模型时选择ccx/model请求会通过 Chat 协议进入 CCX再由 CCX Chat 渠道路由到已配置的国内上游。Agent Config 也提供直连选项但只列出当前适合 OpenCode OpenAI Chat 协议的国内厂商以及 OpenCode Zen / OpenCode Go。其它 provider 仍可按 OpenCode 官方方式手动添加。注意 Desktop 教程中默认端口可能为3688取决于 CCX 运行配置按实际端口替换即可。手动配置在 OpenCode 中选择 OpenAI 兼容 / 自定义 Provider并填写设置项值API Keyyour-ccx-proxy-keyBase URLhttp://localhost:3000/v1Model客户端请求模型名例如gpt-5、deepseek-v4-pro如果你的 OpenCode 版本使用配置文件核心仍是同一组值API Key: your-ccx-proxy-key Base URL: http://localhost:3000/v1 Model: your-model-name::: warning OpenCode 的配置界面和字段名可能随版本变化。只要选择的是 OpenAI Chat 兼容 Provider就使用上面的 API Key、Base URL 和 Model 值。 :::关于 API Key 的取值需要特别强调OpenCode 中填写的API Key 必须是 CCX 的PROXY_ACCESS_KEY或EXTRA_PROXY_ACCESS_KEYS中配置的附加代理密钥而不是上游厂商的 API Key。CCX 启动时通过环境变量读取代理访问密钥见 backend-go/.env.example 与 环境变量解析实现生产环境未设置PROXY_ACCESS_KEY时服务会直接拒绝启动见 main.go。代理密钥会作为网关鉴权凭据用于替代上游真实 Key避免密钥直接暴露给客户端。三、模型映射建议如果 OpenCode 请求的是 OpenAI 风格模型名但上游使用自己的模型名可以在 Chat 渠道中配置模型映射。CCX 会先在网关侧按请求模型匹配映射规则再以映射后的实际上游模型名请求上游。示例请求模型匹配映射到上游模型示例gpt上游主力模型mini上游轻量模型deepseekDeepSeek 模型如果你希望 OpenCode 直接请求上游模型名也可以不配置映射直接在 OpenCode 中填写渠道支持的模型名。从源码看模型映射属于渠道候选过滤的一部分调度层在挑选 Chat 渠道时会校验supportedModels支持空列表、精确匹配与通配符规则并自动跳过不支持当前模型的渠道见 backend-go/README.md。这意味着 OpenCode 里填写的模型名要么命中映射规则要么直接命中某渠道白名单否则请求会因无可用渠道而失败。此外 CCX 的自动发现/画像系统还会基于探测结果自动维护渠道模型清单modelMapping相关字段在 自动发现实现 中被注释为只更新清单、不主动改写映射因此手动配置的映射规则是可控且稳定的。常见问题Base URL 应该写根路径还是/v1OpenCode 走 OpenAI Chat 兼容协议时Base URL 通常填写http://localhost:3000/v1不要填写到具体接口http://localhost:3000/v1/chat/completionsCCX 的代理入口注册在/v1/chat/completions见 backend-go/README.md 的入口表OpenCode 会自行在 Base URL 之后拼接chat/completions因此 Base URL 只需到/v1前缀即可。若把完整接口路径也写进去实际请求会变成/v1/v1/chat/completions之类的非法路径导致 404。返回 401 Unauthorized检查OpenCode 中的 API Key 是否等于 CCX 的PROXY_ACCESS_KEY是否误填了上游厂商 API KeyCCX 是否使用同一个PROXY_ACCESS_KEY启动CCX 的 Chat 端点使用代理访问密钥鉴权支持x-api-key与Authorization: Bearer两种形式见 Chat 处理器中的鉴权调用。此外若启用了EXTRA_PROXY_ACCESS_KEYS则必须配套设置独立的ADMIN_ACCESS_KEY否则配置校验会直接报错见 env.go此类启动期错误也可能表现为密钥怎么都不对。返回 404 或 Method Not Allowed通常是 Provider 类型或 Base URL 不匹配。确认OpenCode 选择的是 OpenAI Chat 兼容 ProviderBase URL 是http://localhost:3000/v1CCX 中已配置Chat渠道而不是只配置了 Messages 或 Responses 渠道注意 CCX 有多个独立入口Messages/v1/messages、Responses/v1/responses、Chat/v1/chat/completions、Gemini、Images、Vectors。如果只配置了 Messages 渠道OpenCode 的 Chat 请求不会命中任何渠道——CCX 会因没有可用的 Chat 上游返回 503/404 之类的错误对应源码中handleSingleChannel的503 No Chat upstream configured分支见 handler.go。返回 model_not_found检查 Chat 渠道模型白名单是否包含请求模型或映射后的上游模型OpenCode 中填写的模型名是否和映射规则匹配上游真实模型名是否正确从源码看调度层在候选集过滤阶段就会跳过不支持当前请求模型的渠道因此该错误往往意味着没有任何 Chat 渠道声明支持这个模型名或模型映射后得到的实际上游模型名不在白名单内。可以在管理界面的渠道编辑页通过查询模型列表接口对应GetChannelModels见 channels.go确认上游真实可用的模型名再回头核对 OpenCode 中填写的名字。工具调用或多轮上下文异常OpenCode 走 Chat Completions 协议不同上游对工具调用、JSON 输出和 system message 的支持程度不同。遇到兼容性问题时优先选择原生支持 OpenAI Chat 工具调用的上游降低模型能力开关或关闭上游不支持的响应格式如果问题只出现在某个上游调整渠道优先级或模型映射让该类请求走兼容性更好的渠道CCX 在请求转发前还会做一些兼容性预处理例如清理空的signature字段、清理历史 thinking 内容块以避免上游参数校验 400见 handler.go。但协议能力差异如工具调用格式本质上取决于上游多渠道模式下 CCX 支持按渠道优先级与故障转移选择兼容性更好的上游。请求没有出现在 Chat 渠道日志中检查 OpenCode 当前 Provider 是否仍指向其它服务。CCX 侧应看到请求路径/v1/chat/completions如果 OpenCode 仍指向 OpenAI 官方地址或其他中转服务请求根本不会到达 CCX只有确认 Provider 的 Base URL 指向 CCX 且选择了正确的协议入口请求才会出现在 Chat 渠道日志中。日志与指标可在管理界面 Chat 入口的渠道详情中查看对应logs与metrics系列管理 API见 backend-go/README.md。总结OpenCode 接入 CCX 的本质是协议对齐 入口匹配OpenCode 使用 OpenAI Chat 兼容协议因此在 CCX 侧配置Chat 渠道、在 OpenCode 侧填写指向http://localhost:3000/v1的 Base URL并用PROXY_ACCESS_KEY作为 API Key 即可打通。后续的渠道调度、多 Key 轮转、故障转移、模型映射与日志观测全部由 CCX 的 Chat 代理层handler.go与渠道管理模块channels.go承载OpenCode 侧无需感知上游协议差异。遇到问题时按入口是否匹配 → 密钥是否一致 → 模型是否在白名单/映射内 → 上游是否原生支持所需能力的顺序排查即可快速定位。赞分享API网关LLM 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载相关推荐CANN PyPTO SIMT 原子按位或 atomic_orAPI 说明、约束与编程实践CANN PyPTO SIMT 原子按位或 atomic_orAPI 说明、约束与编程实践 导读 本文围绕 CANN PyPTOParallel TensoAPI网关LLM 网关后端CCX 接入 MiniMax 完整指南OpenAI Chat 与 Anthropic Messages 双协议配置CCX 接入 MiniMax 完整指南OpenAI Chat 与 Anthropic Messages 双协议配置 MiniMax 是同时提供 OpenAIAPI网关LLM 网关后端OneUptime 公开状态页 API 全解overview、uptime、incidents、维护与公告五大端点的调用方法与源码实现OneUptime 公开状态页 API 全解overview、uptime、incidents、维护与公告五大端点的调用方法与源码实现 本文以 OneUptiAPI网关LLM 网关后端上一篇useful-scripts 速查手册Java 线上排障三件套与命令行提效工具箱下一篇Taichi 稀疏矩阵实战指南Builder 构建、矩阵运算与线性系统求解创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表