opencode_proxy

一个面向 OpenAI 兼容客户端的轻量代理服务。

它对外提供本地 /v1/* 接口，校验你自定义的代理密钥，然后把请求转发到 OpenCode 上游。适合把不直接支持 OpenCode 的客户端，接到统一的 OpenAI 风格入口上。

功能概览

• 提供本地 OpenAI 风格接口：/v1/*
• 使用 PROXY_API_KEY 保护本地代理入口
• 自动把上游鉴权改写为 OPENCODE_API_KEY
• 支持可选上游代理：http、https、socks5、socks5h
• 支持 IS_FREE=true 的 free 模式
• 透传普通请求，支持流式响应

工作方式

客户端请求流程：

1. 你的客户端把请求发到本地代理，例如 http://127.0.0.1:8080/v1/chat/completions
2. 请求头里的 Authorization 必须是：

Bearer <PROXY_API_KEY>

3. 代理校验通过后，把请求转发到 OPENCODE_BASE_URL
4. 转发时会自动替换为上游需要的 Authorization: Bearer <OPENCODE_API_KEY>

这意味着：

• PROXY_API_KEY 是你的本地代理口令，给客户端用
• OPENCODE_API_KEY 是代理访问上游 OpenCode 用的密钥，不给客户端直接暴露

环境要求

• Go 1.26 或更高版本

快速开始

1. 准备配置

复制示例配置：

Copy-Item .env.example .env

最小可运行配置如下：

OPENCODE_BASE_URL=https://opencode.ai/zen/v1
OPENCODE_API_KEY=public
UPSTREAM_PROXY_URL=
PROXY_API_KEY=change-me
PORT=8080
IS_FREE=true

2. 启动服务

直接运行：

go run .

或先构建再运行：

go build .
.\opencode_proxy.exe

启动成功后会监听：

http://localhost:8080

端口由 PORT 控制。

配置说明

OPENCODE_BASE_URL

上游 OpenCode 的完整基础地址，必须是绝对 URL。

默认示例：

https://opencode.ai/zen/v1

程序会把本地 /v1/* 路径映射到这个地址下。

例如：

• 本地请求：/v1/models
• 上游请求：https://opencode.ai/zen/v1/models

OPENCODE_API_KEY

代理访问 OpenCode 上游时使用的 API Key。

如果留空，程序会使用默认值 public。

UPSTREAM_PROXY_URL

给代理程序自己访问上游时使用的网络代理，可为空。

支持的协议：

• http://host:port
• https://host:port
• socks5://host:port
• socks5h://host:port

示例：

UPSTREAM_PROXY_URL=http://127.0.0.1:7890

UPSTREAM_PROXY_URL=socks5://127.0.0.1:7891

留空表示不走上游代理。

PROXY_API_KEY

客户端访问本地代理时必须携带的口令，必填。

例如你配置为：

PROXY_API_KEY=my-local-key

那么所有请求都要带：

Authorization: Bearer my-local-key

PORT

本地监听端口，默认 8080。

IS_FREE

是否启用 free 模式，取值只能是 true 或 false。

free 模式说明

当 IS_FREE=true 时，代理会做两件事：

1. 转发普通请求时，如果请求 JSON 里有 model 字段，会自动补上 -free
2. 请求 /v1/models 时，只保留上游返回里以 -free 结尾的模型，并在返回给客户端前去掉这个后缀

例子：

• 客户端请求模型：gpt-4.1
• 实际转发到上游：gpt-4.1-free
• /v1/models 返回给客户端时显示为：gpt-4.1

如果你不需要这个行为，把 IS_FREE=false。

接入方式

作为 OpenAI 兼容 API 使用

把你的客户端 Base URL 指向：

http://127.0.0.1:8080/v1

把 API Key 设置为：

<PROXY_API_KEY>

有些客户端会自动拼 Bearer，有些需要你自己填完整 Header，按客户端要求配置即可。

curl 测试模型列表

curl.exe -X GET "http://127.0.0.1:8080/v1/models" `
  -H "Authorization: Bearer change-me"

curl 测试聊天接口

curl.exe -X POST "http://127.0.0.1:8080/v1/chat/completions" `
  -H "Authorization: Bearer change-me" `
  -H "Content-Type: application/json" `
  -d "{\"model\":\"gpt-4.1\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

行为说明

• 只处理 /v1 和 /v1/* 路径，其他路径返回 404
• 未携带正确的 Authorization 时返回 401 unauthorized
• 客户端传入的 Authorization 不会原样转发到上游
• 代理会统一设置上游请求头和 Host
• 支持解压上游 gzip 响应后再返回给客户端

配置优先级

如果同一个配置项同时存在于系统环境变量和 .env 文件中，环境变量优先。

常见问题

1. 启动时报 OPENCODE_BASE_URL must be a valid absolute URL

检查 OPENCODE_BASE_URL 是否包含完整协议和主机，例如：

https://opencode.ai/zen/v1

2. 启动时报 PROXY_API_KEY is required

说明你没有配置本地代理口令。补上 .env 里的 PROXY_API_KEY。

3. 启动时报 UPSTREAM_PROXY_URL must be a valid absolute URL

说明上游代理地址不是完整 URL。

正确示例：

http://127.0.0.1:7890

错误示例：

127.0.0.1:7890

4. 启动时报 UPSTREAM_PROXY_URL scheme must be http, https, socks5, or socks5h

说明代理协议不受支持，只能用这四种 scheme。

5. 请求返回 401 unauthorized

检查客户端发给本地代理的 Header 是否为：

Authorization: Bearer <PROXY_API_KEY>

6. 模型列表和实际请求模型不一致

通常是因为启用了 IS_FREE=true。这是预期行为，代理会自动处理 -free 后缀。

开发与测试

运行测试：

go test ./...

适用场景

• 你有一个只认 OpenAI 兼容接口的客户端
• 你想把 OpenCode 作为上游，但不希望客户端直接持有上游密钥
• 你需要在本地统一加一层代理鉴权或上游代理网络配置

许可

项目包含 LICENSE 文件，按仓库内许可证使用。