简介

什么是 opencode2api ？

opencode2api 是一个开源的 OpenAI 兼容 API 网关工具。它可以将本地运行的 OpenCode 运行时转换为标准的 OpenAI API 格式，让你可以在任何 OpenAI 客户端中免费使用 OpenCode 提供的模型（如 big-pickle、gpt5-nano 等）。

主要特点

• OpenAI 兼容：完整支持 /v1/models、/v1/chat/completions、/v1/responses 接口
• 流式输出：支持 Chat Completions 与 Responses API 的完整 SSE 流式响应
• 推理控制：支持 reasoning_effort 参数，可控制推理强度
• Docker 部署：一键部署，自动启动 OpenCode 后端
• 工具安全：默认禁用工具调用，确保安全
• 外部工具桥接：支持外部客户端传入 tools，通过代理桥接为 OpenAI-compatible 的 tool_calls
• 内置 web_fetch 透传：可选择性放行 OpenCode 内置 web_fetch 工具
• 开源免费：基于 MIT 协议开源，可免费使用和修改

应用场景

• 免费使用 AI 模型：在主流 OpenAI 客户端中免费使用 OpenCode 提供的模型
• 本地 AI 网关：搭建本地 API 网关，保护隐私的同时使用 AI 能力
• 开发测试：开发人员可以在本地快速测试 OpenAI 兼容的 API 调用

opencode2api 是一个让你在本地轻松使用 OpenCode 模型的实用工具。

安装

在群晖上以 Docker 方式安装。

提示：由于镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行拉取镜像。

env.txt

env.txt 中必须配置的只有 API_KEY 和 OPENCODE_SERVER_PASSWORD

# Copy this file to .env before running docker compose.API_KEY=123456OPENCODE_SERVER_PASSWORD=laosu123# Safer default. Keep true unless you really want model tool access.DISABLE_TOOLS=true# External tool bridge is implemented by the proxy, not by OpenCode internal tools.# Supported values today:# - OPENCODE_EXTERNAL_TOOLS_MODE=proxy-bridge# - OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY=namespaceOPENCODE_EXTERNAL_TOOLS_MODE=proxy-bridgeOPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY=namespace# Helpful when running behind OpenClaw or other clients that already manage prompts.OPENCODE_PROXY_PROMPT_MODE=plugin-injectOPENCODE_PROXY_OMIT_SYSTEM_PROMPT=true# Periodically clean proxy-owned conversation/session storage.OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=trueOPENCODE_PROXY_CLEANUP_INTERVAL_MS=43200000OPENCODE_PROXY_CLEANUP_MAX_AGE_MS=86400000# Optional overrides# OPENCODE_PROXY_PORT=10000# OPENCODE_SERVER_PORT=10001# OPENCODE_USE_ISOLATED_HOME=false# OPENCODE_PROXY_REQUEST_TIMEOUT_MS=180000# OPENCODE_PROXY_DEBUG=false# OPENCODE_ZEN_API_KEY=

• API_KEY：用于 Bearer Token 认证，请求时需要在 Header 中传入
• OPENCODE_SERVER_PASSWORD：OpenCode 后端登录密码

docker-compose.yml

我们使用的是预编译镜像，所以 - .:/home/node/project 必须要注释，否则反而会报错

services:opencode2api:image: ghcr.io/tiarabasori/opencode2api:latestcontainer_name: opencode2apirestart: unless-stoppedports:- "${OPENCODE_PROXY_PORT:-10000}:${OPENCODE_PROXY_PORT:-10000}"volumes:- ./data:/home/node/.local/share/opencode- ./config:/home/node/.config/opencode#   - .:/home/node/projectenvironment:- PUID=${PUID:-1000}- PGID=${PGID:-1000}- OPENCODE_SERVER_PASSWORD=${OPENCODE_SERVER_PASSWORD:-}- OPENCODE_ZEN_API_KEY=${OPENCODE_ZEN_API_KEY:-}- API_KEY=${API_KEY:-}- BIND_HOST=0.0.0.0- DISABLE_TOOLS=${DISABLE_TOOLS:-true}- OPENCODE_USE_ISOLATED_HOME=${OPENCODE_USE_ISOLATED_HOME:-false}- OPENCODE_PROXY_DEBUG=${OPENCODE_PROXY_DEBUG:-false}- OPENCODE_PROXY_PROMPT_MODE=${OPENCODE_PROXY_PROMPT_MODE:-standard}- OPENCODE_PROXY_OMIT_SYSTEM_PROMPT=${OPENCODE_PROXY_OMIT_SYSTEM_PROMPT:-false}- OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=${OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS:-false}- OPENCODE_PROXY_CLEANUP_INTERVAL_MS=${OPENCODE_PROXY_CLEANUP_INTERVAL_MS:-43200000}- OPENCODE_PROXY_CLEANUP_MAX_AGE_MS=${OPENCODE_PROXY_CLEANUP_MAX_AGE_MS:-86400000}- OPENCODE_PROXY_REQUEST_TIMEOUT_MS=${OPENCODE_PROXY_REQUEST_TIMEOUT_MS:-180000}- OPENCODE_PROXY_PORT=${OPENCODE_PROXY_PORT:-10000}- OPENCODE_SERVER_PORT=${OPENCODE_SERVER_PORT:-10001}healthcheck:test: ["CMD","curl","-f","http://localhost:${OPENCODE_PROXY_PORT:-10000}/health"]interval: 30stimeout: 10sretries: 3start_period: 60s

然后通过 SSH 登录到您的群晖，执行下面的命令：

# 新建文件夹 opencode2api 和 子目录mkdir -p /volume1/docker/opencode2api/{config,data}# 进入 opencode2api 目录cd /volume1/docker/opencode2api# 将 docker-compose.yml 和 env.txt 放入当前目录# 一键启动docker-compose --env-file env.txt up -d  

运行

在浏览器中访问 http://<群晖IP>:10000/health 即可检查服务健康状态。

API 调用示例

更多更详细的示例可以参考官方文档：https://github.com/TiaraBasori/opencode2api/blob/main/docs/api-reference.md

Chat Completions

curl -X POST http://<群晖IP>: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 -X POST http://192.168.0.197:10000/v1/chat/completions \  -H "Authorization: Bearer 123456" \  -H "Content-Type: application/json" \  -d '{    "model": "opencode/big-pickle",    "messages": [{"role": "user", "content": "你好!"}],    "stream": false  }'

Responses API (带推理)

curl -N -X POST http://<群晖IP>: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 -N -X POST http://192.168.0.197:10000/v1/responses \  -H "Authorization: Bearer 123456" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt5-nano",    "input": "用一句话打招呼",    "reasoning": {"effort": "high"},    "stream": true  }'

Cherry Studio

添加新的模型服务

• API 密钥：对应的是环境变量 API_KEY 的值
• API 地址：对应的是 http://群晖IP:{OPENCODE_PROXY_PORT}，所以这里是 http://192.168.0.197:10000

点 获取模型列表，如果设置无误，会看到模型

都可以添加

可以测试一下模型

注意事项

1. 安全配置：建议保持 DISABLE_TOOLS=true，除非确实需要使用工具
2. 端口冲突：确保 10000 和 10001 端口未被占用
3. 认证安全：请使用强密码作为 API_KEY，不要使用默认值
4. 模型名称：使用完整模型 ID（如 opencode/big-pickle）或别名（如 gpt5-nano）
5. 首次启动：首次启动会自动拉取 OpenCode 后端镜像，可能需要较长时间

除了 opencode2api 外，其实更简单的是直接注册 OpenCode Zen，并获取 API Key，一样可以使用免费模型

参考文档

TiaraBasori/opencode2api: 将运行在本地的 OpenCode 转换为 OpenAI 兼容 API，以在任何 OpenAI 客户端中使用免费模型地址：https://github.com/TiaraBasori/opencode2api

ghcr.io/tiarabasori/opencode2api – Container Image | GitHub Container Registry地址：https://github.com/users/TiaraBasori/packages

OpenCode – AI Coding Assistant地址：https://opencode.ai