opencode2api：把 OpenCode Zen 变成三大协议通用网关

如果你用过 Claude Code、Cline、Continue 这类工具，一定被"接口方言"折磨过：OpenAI 有 Chat Completions 和 Responses 两套 API，Anthropic 有自己的 Messages API，而 OpenCode 走的是自定义的 zen / zen/go 协议。客户端之间互不对话，只能互相迁就。

opencode2api 就是来解决这件事的：它用 Go 写了一个网关，对外同时提供 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三套接口，内部按上游的原生协议编码转发。接上之后，Claude Code、Codex、任何兼容客户端都能直接用上 OpenCode Zen 的模型。

它解决的痛点：协议分裂

AI 生态最大的割裂不是模型能力，而是接口协议。同一款模型，OpenAI 客户端要 messages，Anthropic 客户端要 input，工具调用、推理强度、流式事件格式还各不相同。每接入一个新客户端，就要重写一遍适配层。

opencode2api 把这层适配收敛成一个进程：

• 客户端侧：认 /v1/chat/completions、/v1/responses、/v1/messages，还有专供结构化决策的 /v1/systemone
• 上游侧：Zen 走 /zen，Go 走 /zen/go，匿名免费通道走 /inference，每个 Tier 用各自的原生协议编码
• 中间层：统一的中间结构负责文本、图片、reasoning、函数工具、工具调用与工具结果的转换，SSE 流式与非流式都覆盖

协议相同则保留供应商特有字段；跨协议时部分参数没有等价表达，比如 Chat 的 JSON 输出约束和 seed 不会转发到 Anthropic Messages，这类边界作者在 README 里写得很明确，没有粉饰。

更有意思的设计：免费模型与出口轮换

这个项目真正的野心在"免费模型"这一块。OpenCode Zen 提供了一批免费模型，网关能识别"ID 含 free"或"元数据输入输出价格均为零且未弃用"的模型，把它们路由到匿名通道（上游认证头使用 OpenCode 的 public 凭证）。

但免费额度是按出口 IP 网段计算的，所以只换 Key 没用，必须换出口。项目的做法是：

1. 匿名通道最多尝试 N 个可用匿名代理，每个代理一次，先 v2 /inference 再 v1 /zen
2. 认证通道按 prefer 顺序尝试 Zen / Go，每个 Tier 有独立的重试预算
3. 请求级 400/413/422 直接结束请求（换出口改变不了请求本身）；IP 级 abuse 403 只淘汰当前出口
4. 所有出口被封时停止扫描，已配置的 Go Key 继续服务

更进一步是 用户态 Cloudflare WARP：网关进程内注册 WARP 设备，用 WireGuard 建连并在用户态网络栈终结，不需要 TUN 设备、root 权限或 NET_ADMIN。出口池按并发动态伸缩（每个在途请求一个出口 + 一个备用，上限 1-32），空闲 60 秒回收。IPv6 出口按 /64 去重冷却 30 分钟，配合 IPV6_FREEBIND 绑定源地址，让每个出口拥有独立公网地址。

还有一个容易被忽略的细节：免费层级会校验请求是否具备"agent 形态"。所以网关会为整形后的免费模型请求注入 OpenCode CLI 自身的系统提示词、<env> 环境块和内置 skill 列表，并把客户端声明的具名工具改名为 clint_<name> 后补全官方工具集（bash/edit/glob/grep/read/skill/task/todowrite/webfetch/websearch/write）。响应回来再把工具名还原成客户端声明的名字。

上手门槛：三种方式

方式一：Docker Compose（最推荐）

cp config.example.json config.json
# 编辑 config.json：填 server_keys、替换 webui.password
docker compose up -d

镜像在 ghcr.io/jasonxu114514/opencode2api，只读根文件系统、no-new-privileges、独立状态卷，容器内进程以普通用户运行。健康检查打 /healthz，API 监听 8080，管理面板监听 8081。

方式二：单二进制

Releases 提供 Linux/macOS/Windows 全平台压缩包和 sha256 校验文件，解压即用。需要 Go 1.24+ 自行编译也可以。WebUI 通过 go:embed 内嵌进可执行文件，运行服务不需要 Node.js，也不需要数据库。

方式三：源码编译

go build -o opencode2api ./cmd/opencode2api
./opencode2api -config config.json

启动前必须改三处：server_keys 换成自己的本地 Key、可选填入上游 Zen/Go Key、webui.password 换掉示例密码（默认用户名 admin）。配置目录需要可写，用来迁移密码、保存配置和写模型缓存。

管理面板：不止是配置编辑器

WebUI 是纯前端 ES 模块，通过 go:embed 打进二进制，默认简体中文，另有 English / Tiếng Việt / Italiano。功能包括：

• Playground：直接发请求调试，支持自动模式和指定 Key 模式；每客户端 IP 每分钟限 12 次
• 路由诊断：查看模型路由、Key 指纹和 metadata；指定 Key 的诊断不进入匿名通道、不轮换、不重放
• Go 额度看板：调用上游 usage 接口显示 5 小时/每周/每月的剩余百分比与重置时间，浏览器拿不到上游 Key
• API Key 管理：生成 192 位随机密钥，支持自定义、重命名、启停、删除，热生效
• 实时日志：SSE 订阅结构化日志，环形缓冲大小可配

安全侧做了分层：管理接口需登录，写操作需 CSRF Token，敏感配置需密码验证才能查看，账号密码可修改并使旧 Session 失效。配置热重载会先验证新配置并创建新 Gateway，失败则旧实例继续服务，不会因为一次手滑改坏配置而中断线上。

质量与工程细节

代码按职责分包：cmd/ 入口，internal/config 配置与脱敏，internal/gateway 路由与资源池，internal/protocol 协议转换与 SSE 解析，internal/models 模型目录与缓存，internal/admin 管理 API，internal/warp WARP，internal/telemetry 指标日志。第三方依赖极少且都是网络层刚需：uTLS（TLS 指纹）、wireguard + gvisor（用户态 WARP）、brotli/compress（压缩）。

CI 覆盖 Linux/Windows 上的 go vet 与构建、Go 格式检查、WebUI JS 语法检查和容器入口脚本语法检查；Releases 提供全平台产物与 sha256 校验。仓库内没有 _test.go 测试文件，这是它比较明显的短板。

争议与局限

• 合规性存疑：项目本身声明"非 OpenAI/Anthropic/OpenCode 官方项目"，把免费模型额度通过多出口轮换的方式最大化利用，且明确建议使用住宅代理。是否违反上游服务条款，需要使用者自行判断。团队内部使用前建议先过一遍法务。
• 无自动化测试：README 提到 go test ./...，但仓库里找不到测试文件，协议转换这类最容易出边界 bug 的代码缺少回归保护。
• 功能边界明确：不提供 embeddings、文件上传、图像生成、Responses 查询与取消接口；网关不保存会话历史，客户端需自己带历史。
• 监控仅存内存：请求明细保留最近一小时（上限 1 万请求 / 2 万次尝试），进程重启即清零，长期留存需外部收集 stdout JSON 日志。
• 国内网络环境：WARP 需要能向 Cloudflare 端点发 UDP（2408 端口），且 IPv4 出口是共享 NAT 常被用尽，实际可用性依赖网络环境。

行业意义

这个项目代表了一类正在成形的开源方向：协议归一化网关。当模型能力通过订阅制（Claude Code、Codex、OpenCode Zen、Cursor）而非 API Key 分配时，把订阅额度重新包装成标准 API 接口就成了刚需，而 Agent 客户端的多协议分裂又让这类网关具备真实需求。

它也体现了个人开发者在"基础设施型"项目上的能力：约 3900 行 Go、一个静态二进制、零 Node.js 依赖、跨平台发布、Docker Compose 一键部署。用户作者也在博客里写下了完整的设计思路。从 2026 年 8 月创建到现在不到三个月，1319 星、229 fork、20 位贡献者，版本迭代到 v1.4.5，迭代密度相当高。

如果你正在为"让某个只支持 Anthropic 协议的客户端用上别的模型"发愁，或者想给团队内部做统一的模型出口管控，这类归一化网关值得放进工具箱评估。