OpenCode转OpenAI兼容API工具opencode2api

发表于 分类于 Waline： 阅读次数： 本文字数： 7k 阅读时长 ≈ 6 分钟
opencode2api 是一个将本地 OpenCode 运行时转换为 OpenAI 兼容 API 的网关工具，支持在任何 OpenAI 客户端中使用免费模型。

简介

什么是 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Copy this file to .env before running docker compose.

API_KEY=123456
OPENCODE_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=namespace
OPENCODE_EXTERNAL_TOOLS_MODE=proxy-bridge
OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY=namespace

# Helpful when running behind OpenClaw or other clients that already manage prompts.
OPENCODE_PROXY_PROMPT_MODE=plugin-inject
OPENCODE_PROXY_OMIT_SYSTEM_PROMPT=true

# Periodically clean proxy-owned conversation/session storage.
OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS=true
OPENCODE_PROXY_CLEANUP_INTERVAL_MS=43200000
OPENCODE_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 后端登录密码
变量名 说明 默认/示例值 是否必填 备注
API_KEY API 访问密钥 change-me 是 用于客户端调用鉴权
OPENCODE_SERVER_PASSWORD OpenCode 服务密码 change-me-too 是 保护内部服务访问
DISABLE_TOOLS 是否禁用模型工具调用 true 否 建议保持 true，提升安全性
OPENCODE_EXTERNAL_TOOLS_MODE 外部工具接入模式 proxy-bridge 否 当前仅支持 proxy-bridge
OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY 外部工具冲突处理策略 namespace 否 使用命名空间避免冲突
OPENCODE_PROXY_PROMPT_MODE Prompt 处理模式 plugin-inject 否 适配已有 prompt 管理系统
OPENCODE_PROXY_OMIT_SYSTEM_PROMPT 是否省略系统提示词 true 否 常用于已有上层 prompt 控制
OPENCODE_PROXY_AUTO_CLEANUP_CONVERSATIONS 是否自动清理会话 true 否 防止数据堆积
OPENCODE_PROXY_CLEANUP_INTERVAL_MS 清理任务执行间隔（毫秒） 43200000 否 即 12 小时
OPENCODE_PROXY_CLEANUP_MAX_AGE_MS 会话最大保留时间（毫秒） 86400000 否 即 24 小时
OPENCODE_PROXY_PORT Proxy 服务端口 10000（示例） 否 默认未启用需手动设置
OPENCODE_SERVER_PORT OpenCode 服务端口 10001（示例） 否 与 proxy 分离
OPENCODE_USE_ISOLATED_HOME 是否使用隔离的 HOME 目录 false 否 提升隔离性
OPENCODE_PROXY_REQUEST_TIMEOUT_MS 请求超时时间（毫秒） 180000 否 默认 3 分钟
OPENCODE_PROXY_DEBUG 是否开启调试模式 false 否 开启后输出更多日志
OPENCODE_ZEN_API_KEY Zen API Key（可选） 空 否 用于扩展功能

docker-compose.yml

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
services:
  opencode2api:
    image: ghcr.io/tiarabasori/opencode2api:latest
    container_name: opencode2api
    restart: unless-stopped
    ports:
      - "${OPENCODE_PROXY_PORT:-10000}:${OPENCODE_PROXY_PORT:-10000}"
    volumes:
      - ./data:/home/node/.local/share/opencode
      - ./config:/home/node/.config/opencode
    #   - .:/home/node/project
    environment:
      - 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: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

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

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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 (带推理)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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