Skip to content

README.md

Latest commit

 

History

History
314 lines (246 loc) · 11.1 KB

README.md

File metadata and controls

314 lines (246 loc) · 11.1 KB

OpenCode2API

Version License Node

📖 文档 | 🚀 快速开始

将本地 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 参与该次请求

🚀 快速开始

Docker 部署 (推荐)

# 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

默认 docker-compose.yml 不会把宿主机项目目录挂载到容器内，因为那会覆盖镜像里已安装的 node_modules，导致容器依赖宿主机先执行 npm install。如果你需要本地源码热更新，建议单独使用开发专用的 Compose 覆盖配置。

Node.js (本地开发)

# 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

💡 使用示例

Chat Completions

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
  }'

Responses API (带推理)

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
  }'

Chat Completions + 外部工具

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"]
          }
        }
      }
    ]
  }'

Responses API + 外部工具流式

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 兼容旧开关；当未显式配置 allowlist 时，启用后默认放行 web_fetch
OPENCODE_INTERNAL_ALLOWED_TOOLS (none) 当请求未传入 tools 时，允许使用的 OpenCode 内置工具列表，逗号分隔
OPENCODE_INTERNAL_TOOL_METRICS_ENABLED true 输出 internal allowlist 模式的调试/指标日志
OPENCODE_TOOL_DISCOVERY_FIXTURE (none) 集成测试/本地调试用的后端工具 ID 固定列表，逗号分隔
OPENCODE_HEALTH_DETAILS_ENABLED true 控制 /health/details 是否暴露
OPENCODE_HEALTH_DETAILS_REQUIRE_AUTH true 控制 /health/details 是否要求 Bearer 认证
OPENCODE_METRICS_ENABLED false 控制 /metrics 是否暴露
OPENCODE_METRICS_REQUIRE_AUTH true 控制 /metrics 是否要求 Bearer 认证
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_ALLOWED_TOOLS=web_fetch
OPENCODE_INTERNAL_TOOL_METRICS_ENABLED=true
OPENCODE_TOOL_DISCOVERY_FIXTURE=
OPENCODE_HEALTH_DETAILS_ENABLED=true
OPENCODE_HEALTH_DETAILS_REQUIRE_AUTH=true
OPENCODE_METRICS_ENABLED=false
OPENCODE_METRICS_REQUIRE_AUTH=true
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。

内置工具 allowlist 说明

  • 当请求 未传入 tools 时，代理会进入 internal allowlist 模式，并只允许 OPENCODE_INTERNAL_ALLOWED_TOOLS 中声明的 OpenCode 内置工具。
  • OPENCODE_INTERNAL_WEB_FETCH_ENABLED=true 仅作为兼容旧配置的快捷方式：当未显式配置 OPENCODE_INTERNAL_ALLOWED_TOOLS 时，会默认把 allowlist 视为 web_fetch。
  • 代理会读取后端工具列表，并通过精确匹配或 .<tool> / /<tool> 后缀匹配解析最终可用工具。
  • 如果配置的 allowlist 在后端工具列表中一个也匹配不到，代理会自动回退到“全部内置工具禁用”的安全模式。
  • OPENCODE_INTERNAL_TOOL_METRICS_ENABLED=true 时，代理会输出 internal allowlist 模式的调试/指标日志，包括模式选择、后端工具发现、allowlist 命中结果和降级原因，但不会记录工具返回内容。
  • OPENCODE_TOOL_DISCOVERY_FIXTURE 可用于集成测试或本地调试，绕过真实 client.tool.ids() 返回固定工具 ID 列表。
  • 一旦客户端显式传入 tools，请求立即回到现有外部工具桥接逻辑，OpenCode 内置工具继续保持禁用。

结构化诊断与 Prometheus 指标

  • /health 始终保持为轻量健康检查接口。
  • /health/details 返回结构化 JSON 诊断数据，可通过 OPENCODE_HEALTH_DETAILS_ENABLED 控制是否暴露，并通过 OPENCODE_HEALTH_DETAILS_REQUIRE_AUTH 控制是否要求 Bearer 认证。
  • /metrics 返回 Prometheus 文本格式指标，可通过 OPENCODE_METRICS_ENABLED 控制是否暴露，并通过 OPENCODE_METRICS_REQUIRE_AUTH 控制是否要求 Bearer 认证。
  • /metrics 目前暴露 internal tool mode、tool discovery failures、fallback count 和 tool-id cache 数量等指标。

🔌 API 参考

端点

方法 路径 说明
GET /health 健康检查
GET /health/details 结构化诊断接口（可配置开关/鉴权）
GET /metrics Prometheus 指标接口（可配置开关/鉴权）
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 参考文档

🔧 故障排查

请求卡住但 /v1/models 正常

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

🙏 致谢

感谢以下开源项目: