企业官网建设流程全解析

• API网关
• LLM 网关
• 后端

本文面向使用 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 渠道。步骤：

1. 打开 CCX 管理界面（默认http://localhost:3000），进入Chat入口
2. 点击「添加渠道」
3. 添加一个 OpenAI Chat 兼容渠道

常见上游配置如下（服务类型统一选OpenAI Chat）：

::: 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 接入关系最密切的字段包括：

从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 端口>/v1

OpenCode 使用模型时选择ccx/<model>，请求会通过 Chat 协议进入 CCX，再由 CCX Chat 渠道路由到已配置的国内上游。

Agent Config 也提供直连选项，但只列出当前适合 OpenCode OpenAI Chat 协议的国内厂商，以及 OpenCode Zen / OpenCode Go。其它 provider 仍可按 OpenCode 官方方式手动添加。注意 Desktop 教程中默认端口可能为3688（取决于 CCX 运行配置），按实际端口替换即可。

手动配置

在 OpenCode 中选择 OpenAI 兼容 / 自定义 Provider，并填写：

如果你的 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 会先在网关侧按请求模型匹配映射规则，再以映射后的实际上游模型名请求上游。

示例：

如果你希望 OpenCode 直接请求上游模型名，也可以不配置映射，直接在 OpenCode 中填写渠道支持的模型名。

从源码看，模型映射属于渠道候选过滤的一部分：调度层在挑选 Chat 渠道时会校验supportedModels（支持空列表、精确匹配与通配符规则）并自动跳过不支持当前模型的渠道（见 backend-go/README.md）。这意味着 OpenCode 里填写的模型名要么命中映射规则，要么直接命中某渠道白名单，否则请求会因无可用渠道而失败。此外 CCX 的自动发现/画像系统还会基于探测结果自动维护渠道模型清单，modelMapping相关字段在 自动发现实现 中被注释为"只更新清单、不主动改写映射"，因此手动配置的映射规则是可控且稳定的。

常见问题

Base URL 应该写根路径还是/v1？

OpenCode 走 OpenAI Chat 兼容协议时，Base URL 通常填写：

http://localhost:3000/v1

不要填写到具体接口：

http://localhost:3000/v1/chat/completions

CCX 的代理入口注册在/v1/chat/completions（见 backend-go/README.md 的入口表），OpenCode 会自行在 Base URL 之后拼接chat/completions，因此 Base URL 只需到/v1前缀即可。若把完整接口路径也写进去，实际请求会变成/v1/v1/chat/completions之类的非法路径，导致 404。

返回 401 Unauthorized

检查：

1. OpenCode 中的 API Key 是否等于 CCX 的PROXY_ACCESS_KEY
2. 是否误填了上游厂商 API Key
3. CCX 是否使用同一个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 不匹配。确认：

1. OpenCode 选择的是 OpenAI Chat 兼容 Provider
2. Base URL 是http://localhost:3000/v1
3. CCX 中已配置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 渠道：

1. 模型白名单是否包含请求模型或映射后的上游模型
2. OpenCode 中填写的模型名是否和映射规则匹配
3. 上游真实模型名是否正确

从源码看，调度层在候选集过滤阶段就会跳过不支持当前请求模型的渠道，因此该错误往往意味着"没有任何 Chat 渠道声明支持这个模型名"或"模型映射后得到的实际上游模型名不在白名单内"。可以在管理界面的渠道编辑页通过"查询模型列表"接口（对应GetChannelModels，见 channels.go）确认上游真实可用的模型名，再回头核对 OpenCode 中填写的名字。

工具调用或多轮上下文异常

OpenCode 走 Chat Completions 协议，不同上游对工具调用、JSON 输出和 system message 的支持程度不同。遇到兼容性问题时：

1. 优先选择原生支持 OpenAI Chat 工具调用的上游
2. 降低模型能力开关或关闭上游不支持的响应格式
3. 如果问题只出现在某个上游，调整渠道优先级或模型映射，让该类请求走兼容性更好的渠道

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 网关
• 后端