OpenCode 自定义提供商配置：添加任意 OpenAI 兼容 API

OpenCode 的提供商目录支持 75+ 个 LLM 提供商，但自定义提供商依然有其价值。你可以通过它们接入网关、本地运行时、内部推理端点，或尚未收录到目录中的模型。

整体流程很简单：保存凭据、添加提供商配置块、重启 OpenCode，然后从 /models 中选择模型。

只想配置 Haimaker？ 跳过手动步骤——运行 npx -y @haimaker/connect --opencode，命令行工具会自动写入提供商配置块并保存你的凭据（加上 --project 参数可生成项目级配置）。下文是适用于任何 OpenAI 兼容提供商的通用教程——Ollama、LM Studio、内部网关，或任何尚未收录到目录中的服务。如需一条命令接入，请参阅连接指南。

何时使用自定义提供商

如果目标模型或端点不在 OpenCode 的内置提供商列表中，就可以使用自定义提供商。

适用场景：

• Haimaker——通过 OpenAI 兼容网关用一个 API Key 访问多个模型系列。
• Ollama——本地模型，接口地址为 http://localhost:11434/v1。
• LM Studio——本地模型，接口地址为 http://127.0.0.1:1234/v1。
• 内部网关——企业自建的 OpenAI 兼容端点。
• 新提供商——任何支持 OpenAI 兼容 Chat API 但尚未被 OpenCode 目录收录的服务。

如果某个提供商已内置到 OpenCode，请优先使用内置的接入方式。自定义配置最适合需要自定义 Base URL、接入网关，或使用默认列表中缺失模型的场景。

第一步：添加凭据

根据当前 OpenCode 文档，可以通过 opencode auth login 添加提供商凭据。对于自定义 OpenAI 兼容提供商，选择 Other，输入提供商 ID，然后粘贴 API Key：

opencode auth login

选择一个简短的提供商 ID，后续配置中也会用到。例如：

haimaker
ollama
mygateway

OpenCode 将凭据保存在：

~/.local/share/opencode/auth.json

需要时可以手动编辑该文件，但使用 opencode auth login 可避免密钥格式写错。

第二步：配置提供商

打开或创建你的 OpenCode 配置文件。根据使用场景，它可能是项目中的 opencode.json，也可能是 ~/.config/opencode/ 下的全局文件。

添加一个 provider 块，使用与认证时相同的提供商 ID。下面以 haimaker.ai 为例展示配置写法：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "z-ai/glm-4.6": {
          "name": "GLM 4.6"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

各字段说明：

• npm：SDK 适配器。对于任何 OpenAI 兼容 API，使用 @ai-sdk/openai-compatible。OpenCode 会按需加载适配器。
• name：在 OpenCode 中显示的名称。
• options.baseURL：提供商 API 的 Base URL。应以 /v1 或提供商使用的版本前缀结尾。
• models：你希望在 OpenCode 中可用的模型。键名必须与提供商 API 在补全请求的 model 字段中实际接受的名称完全一致。

你可以添加任意数量的自定义提供商，每个作为 provider 下的独立条目。

第三步：重启并验证

OpenCode 可能需要重启才能识别新的提供商配置。完全退出后重新启动，然后运行：

/models

你应该能看到提供商的显示名称和已配置的模型。选择一个模型，发送一条简短的提示词进行测试，确认无误后再用于实际代码。

完整示例：Haimaker 网关

当你想通过一个 OpenAI 兼容端点访问多个模型系列时，可以使用此配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Haimaker",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "openai/gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "minimax/minimax-m2.5": {
          "name": "MiniMax M2.5"
        },
        "qwen/qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

这种配置的优势在于：OpenCode 只看到一个提供商，而 Haimaker 负责对接多个上游模型系列。这样你的 OpenCode 配置更精简，模型切换也更省心。

完整示例：Ollama 本地提供商

Ollama 在 http://localhost:11434/v1 暴露了一个 OpenAI 兼容的本地端点：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "Qwen3 Coder 30B"
        },
        "gemma4:e4b": {
          "name": "Gemma 4 E4B"
        }
      }
    }
  }
}

启动 OpenCode 之前先拉取模型：

ollama pull qwen3-coder:30b
ollama pull gemma4:e4b

如果 OpenCode 要求为该本地提供商进行认证，运行 opencode auth login，选择 Other，使用 ollama 作为提供商 ID，输入任意非空密钥（如 ollama）。Ollama 不会验证本地 API Key。

常见错误及修复方法

提供商未出现在 /models 中

检查以下四点：

1. 通过 opencode auth login 设置的提供商 ID 与配置中的 provider 键名一致。
2. 配置文件是有效的 JSON 或 JSONC。
3. 编辑提供商配置后已重启 OpenCode。
4. 模型已列在提供商的 models 对象下。

首次请求时认证失败

凭据缺失或绑定到了错误的提供商 ID。运行：

opencode auth list

然后确认提供商 ID 与配置完全匹配。不要在密钥字段中包含 Bearer。

模型显示但请求失败

模型 ID 很可能与上游 API 期望的不一致。自定义提供商会原样传递模型 ID。如果你的配置写的是 qwen/qwen3-coder，那么 API 必须接受完全相同的 qwen/qwen3-coder。

对于 Haimaker，测试密钥和端点：

curl https://api.haimaker.ai/v1/models \
  -H "Authorization: Bearer your-haimaker-api-key"

对于 Ollama，检查本地模型：

ollama list

使用该输出中的确切模型名称。

本地模型的工具调用失败

本地模型对上下文长度限制和工具调用格式更为敏感。建议从擅长智能体编程的模型开始，例如 Qwen3 Coder，并保持上下文长度适中。OpenCode 文档还建议在工具调用不工作时增大 Ollama 的 num_ctx。

内置提供商停止工作

你可能不小心替换了过多的配置内容。将自定义提供商放在 provider 对象下，避免删除已有的提供商条目。拿不准时，尽量做最小化的配置变更：添加一个提供商 ID 和一个模型，重启，测试，然后再逐步添加更多。

实用配置方案

对于大多数 OpenCode 用户，推荐的配置组合是：

1. Haimaker——用于云端模型和单密钥路由。
2. Ollama——用于本地隐私工作。
3. 一个更强的备用模型——用于复杂调试和多文件重构。

这样既能保证敏感场景下的本地隐私，又能用低成本云端模型处理日常任务，遇到高难度编码任务时再切换到更强的模型。

在 OpenCode 中使用 Haimaker

---

本地配置请参阅 在 OpenCode 中使用 Ollama。更全面的本地模型排名请参阅 最适合编码智能体的 Ollama 模型。