将本地 OpenCode 运行时转换为 OpenAI 兼容 API 网关。在任何 OpenAI 客户端中使用免费模型 (GPT, Nemotron, MiniMax)。
| 特性 | 说明 |
|---|---|
| 🟢 OpenAI 兼容 | /v1/models, /v1/chat/completions, /v1/responses |
| 📡 流式输出 | Chat Completions 与 Responses API 的完整 SSE 流式支持 |
| 🧠 推理控制 | 支持 reasoning_effort 和 reasoning: { "effort": "high" } |
| 🐳 Docker 部署 | 一键部署,自动启动 OpenCode 后端 |
| 🛡️ 工具安全 | 默认禁用工具调用 |
| 🔧 外部工具桥接 | 支持外部客户端传入 tools,由代理桥接为 OpenAI-compatible tool_calls / function_call,避免命中 OpenCode 内置工具 |
| 🌐 内置 web_fetch 透传 | 当请求未传入 tools 且显式开启特性时,仅允许 OpenCode 内置 web_fetch 参与该次请求 |
# 1. 克隆并配置 git clone https://github.com/TiaraBasori/opencode2api.git cd opencode2api cp .env.example .env # 2. 编辑 .env 设置你的配置 # 必填: API_KEY, OPENCODE_SERVER_PASSWORD # 3. 启动 docker compose up -d # 4. 测试 curl http://127.0.0.1:10000/health
# 1. 安装 OpenCode CLI npm install -g opencode-ai # Linux/macOS: curl -fsSL https://opencode.ai/install | bash # 2. 克隆并运行 git clone https://github.com/TiaraBasori/opencode2api.git cd opencode2api npm install cp config.json.example config.json npm start
curl -X POST http://127.0.0.1:10000/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "opencode/big-pickle", "messages": [{"role": "user", "content": "你好!"}], "stream": false }'
curl -N -X POST http://127.0.0.1:10000/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt5-nano", "input": "用一句话打招呼", "reasoning": {"effort": "high"}, "stream": true }'
curl -X POST http://127.0.0.1:10000/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "opencode/big-pickle", "messages": [{"role": "user", "content": "帮我获取 https://example.com 的标题"}], "tools": [ { "type": "function", "function": { "name": "web_fetch", "description": "Fetch a URL and return its content summary", "parameters": { "type": "object", "properties": { "url": {"type": "string"} }, "required": ["url"] } } } ] }'
curl -N -X POST http://127.0.0.1:10000/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "opencode/big-pickle", "input": "查询东京天气", "stream": true, "tools": [ { "type": "function", "function": { "name": "weather_lookup", "description": "Look up weather by city", "parameters": { "type": "object", "properties": { "city": {"type": "string"}, "unit": {"type": "string"} }, "required": ["city"] } } } ] }'
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 🐳 Docker | 完整栈,自动启动 OpenCode 后端 | 生产环境,最简配置 |
| 💻 独立 Node | 手动管理后端 | 开发、自定义集成 |
| 环境变量 | 默认值 | 说明 |
|---|---|---|
PORT / OPENCODE_PROXY_PORT |
10000 |
代理服务端口 |
OPENCODE_SERVER_PORT |
10001 |
OpenCode 后端服务端口 |
API_KEY |
- | Bearer Token 认证密钥 |
BIND_HOST |
0.0.0.0 |
绑定地址 |
DISABLE_TOOLS |
true |
禁用 OpenCode 工具调用 |
OPENCODE_EXTERNAL_TOOLS_MODE |
proxy-bridge |
外部工具桥接模式;当前仅支持 proxy-bridge |
OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY |
namespace |
外部工具与 OpenCode 内置工具的冲突隔离策略;当前仅支持 namespace |
OPENCODE_INTERNAL_WEB_FETCH_ENABLED |
false |
当请求未传入 tools 时,仅放行 OpenCode 内置 web_fetch |
USE_ISOLATED_HOME |
false |
使用隔离的 OpenCode 配置目录 |
OPENCODE_PROXY_PROMPT_MODE |
standard |
提示词处理模式 |
OPENCODE_PROXY_OMIT_SYSTEM_PROMPT |
false |
忽略传入的 system prompt |
OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS |
false |
自动清理会话存储 |
OPENCODE_PROXY_CLEANUP_INTERVAL_MS |
43200000 |
清理间隔 (毫秒) |
OPENCODE_PROXY_CLEANUP_MAX_AGE_MS |
86400000 |
最大存储时间 (毫秒) |
OPENCODE_PROXY_REQUEST_TIMEOUT_MS |
180000 |
请求超时时间 (毫秒) |
OPENCODE_SERVER_URL |
http://127.0.0.1:10001 |
OpenCode 后端地址 |
OPENCODE_SERVER_PASSWORD |
- | OpenCode 后端密码 |
OPENCODE_PATH |
opencode |
OpenCode 可执行文件路径 |
OPENCODE_ZEN_API_KEY |
- | Zen API Key 透传 |
DEBUG / OPENCODE_PROXY_DEBUG |
false |
调试日志 |
📄 完整配置参考: 配置详解
API_KEY=your-secret-key OPENCODE_SERVER_PASSWORD=your-password DISABLE_TOOLS=true OPENCODE_EXTERNAL_TOOLS_MODE=proxy-bridge OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY=namespace OPENCODE_INTERNAL_WEB_FETCH_ENABLED=false OPENCODE_PROXY_PROMPT_MODE=plugin-inject OPENCODE_PROXY_OMIT_SYSTEM_PROMPT=true OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=true
- 外部客户端传入的
tools不会被注册为 OpenCode 内置工具。 - 代理会把这些工具虚拟化后交给模型使用,并把模型输出重新整理为 OpenAI-compatible
tool_calls/function_call。 - 同名冲突默认通过内部命名空间隔离处理,例如客户端的
web_fetch不会误触发 OpenCode 容器内工具。 - 内部命名空间名(如
external__web_fetch)是代理内部实现细节,不属于公开 API。
- 仅当请求 未传入
tools且OPENCODE_INTERNAL_WEB_FETCH_ENABLED=true时启用。 - 该模式不会注入外部工具桥接协议,也不会把 OpenCode 其他内置工具暴露给模型。
- 代理会读取后端工具列表,并仅放行名为
web_fetch(或以.web_fetch//web_fetch结尾)的内置工具,其余工具统一禁用。 - 如果后端未提供
web_fetch,代理会回退到"全部内置工具禁用"的安全模式。 - 一旦客户端显式传入
tools,请求立即回到现有外部工具桥接逻辑,内置工具继续保持禁用。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/health |
健康检查 |
GET |
/v1/models |
获取可用模型列表 |
POST |
/v1/chat/completions |
Chat Completions API |
POST |
/v1/responses |
Responses API |
- 直接使用:
opencode/big-pickle - 带别名:
gpt5-nano(自动解析为gpt-5-nano) - 带前缀:
opencode/gpt5-nano
📖 详见 API 参考文档
USE_ISOLATED_HOME=false # 让 OpenCode 复用本地登录态- 查看可用模型:
curl http://127.0.0.1:10000/v1/models - 确认模型 ID 完全匹配
- 使用
stream: true的 Responses API - 发送
reasoning.effort或reasoning_effort
📖 完整指南: 故障排查
# 运行测试 npm test -- --runInBand # Docker 开发 docker compose up -d --build
MIT · 详见 LICENSE
感谢以下开源项目: