opencode 添加自定义模型

opencode 支持接入任何兼容 OpenAI API 格式的模型服务（如 vLLM、Ollama、TGI 等），无需等待官方集成。

本文以接入本地 vLLM 服务 http://10.0.19.38:8060 上的 qwen3.5-27b 模型为例。

1. 确认模型信息

访问模型服务的接口列表地址：

http://xxxxxxx/v1/models

返回示例：

{
  "object": "list",
  "data": [
    {
      "id": "qwen3.5-27b",
      "object": "model",
      "created": 1782968146,
      "owned_by": "vllm",
      "max_model_len": 262144
    }
  ]
}

需要记住以下信息：

模型 ID: qwen3.5-27b（与 model 字段值一致）
API 地址: http://10.0.19.38:8060/v1（去掉 /models 后的 base URL）
上下文长度: 262144（max_model_len，可选，用于配置 limit）

2. 编辑配置文件

opencode 的配置文件位于 ~/.config/opencode/opencode.json，也支持在项目根目录放置 opencode.json 进行覆盖。

方式一：V1 格式（推荐）

在 provider 中添加一条配置，npm 指定为 @ai-sdk/openai-compatible：

{
  "provider": {
    "local-vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "",
        "baseURL": "http://xxxxxxx/v1"
      },
      "models": {
        "qwen3.5-27b": {
          "limit": {
            "context": 262144,
            "output": 4096
          }
        }
      }
    }
  },
  "model": "local-vllm/qwen3.5-27b"
}

各字段说明：

字段	说明
`local-vllm`	provider 名称，自定义，将作为模型 ID 的前缀
`npm`	必须设为 `@ai-sdk/openai-compatible`，告诉 opencode 这是 OpenAI 兼容服务
`options.baseURL`	API 地址，去掉末尾的 `/models`
`options.apiKey`	API 密钥，如果服务不需要鉴权留空即可
`models`	该 provider 下的模型列表，key 为模型 ID
`model`	默认模型，格式为 `{provider}/{model-id}`

方式二：V2 格式（完整版）

如果配置文件使用 V2 格式（不含 provider、plugin 等 V1 特有字段），则使用 api 和 request 字段：

{
  "providers": {
    "local-vllm": {
      "name": "Local vLLM",
      "api": {
        "type": "aisdk",
        "package": "@ai-sdk/openai-compatible",
        "url": "http://10.0.19.38:8060/v1"
      },
      "request": {
        "body": {
          "apiKey": ""
        }
      },
      "models": {
        "qwen3.5-27b": {
          "limit": {
            "context": 262144,
            "output": 4096
          }
        }
      }
    }
  },
  "model": "local-vllm/qwen3.5-27b"
}

3. 重启 opencode

配置文件在 opencode 启动时加载一次，修改后需要完全退出并重新启动 opencode 才能生效。

# 退出 opencode 后重新启动
opencode

4. 验证

启动后使用 model 命令确认当前模型：

/model

也可以发起一次对话验证模型是否能正常响应。

常见问题

"Provider not found" 或 "Model not found"

最常见的原因是没有设置 npm 字段（V1 格式）或 api.type/api.package 字段（V2 格式）。确认配置中包含 "npm": "@ai-sdk/openai-compatible" 或 "api": { "type": "aisdk", "package": "@ai-sdk/openai-compatible" }。

连接超时

如果模型服务在同一台机器的非标准端口上运行，检查 baseURL 是否正确，以及防火墙是否放行。可以在 opencode 中设大 options.timeout：

"options": {
  "baseURL": "http://xxxxxxxx/v1",
  "timeout": 120000
}

模型不支持工具调用

如果模型不支持 tool calling，可以在模型定义中关闭：

"models": {
  "qwen3.5-27b": {
    "capabilities": {
      "tools": false
    }
  }
}

多个模型

同一个 provider 下可以添加多个模型：

"models": {
  "qwen3.5-27b": { "limit": { "context": 262144, "output": 4096 } },
  "qwen3.5-14b": { "limit": { "context": 32768, "output": 4096 } }
}

使用 small_model 指定轻量模型用于标题生成等简单任务：

{
  "model": "local-vllm/qwen3.5-27b",
  "small_model": "local-vllm/qwen3.5-14b"
}

opencode添加自定义模型