---
title: OpenCode 自定义提供商配置：添加任意 OpenAI 兼容 API
description: >-
  将 Haimaker、Ollama、OpenRouter 或任意 OpenAI 兼容 API 添加到 OpenCode。涵盖 opencode auth
  login、opencode.json 配置、本地模型设置及常见提供商错误。
date: 2026-04-12T00:00:00.000Z
updatedDate: 2026-06-26T00:00:00.000Z
location: 美国加利福尼亚州旧金山，2026年4月12日
image: /images/opencode-custom-provider-setup-hero.jpg
keywords: >-
  opencode 自定义提供商, opencode 添加提供商, opencode 模型提供商, opencode openai 兼容, opencode
  haimaker, opencode llm 提供商, opencode 提供商配置, opencode 本地提供商
faq:
  - question: 如何在 OpenCode 中添加自定义 LLM 提供商？
    answer: >-
      运行 'opencode auth login' 并选择 Other 来保存提供商凭据，然后在 opencode.json 中添加对应的
      provider 条目，将 npm 设为 '@ai-sdk/openai-compatible'，baseURL 指向你的 API 地址，并在
      'models' 下配置所需模型。重启 OpenCode 后使用 /models 选择即可。如果你使用的是 Haimaker，运行 'npx -y
      @haimaker/connect --opencode' 即可自动写入凭据和提供商配置块。
  - question: 为什么我的自定义提供商没有出现在 /models 中？
    answer: >-
      常见原因包括：凭据与配置中的提供商 ID 不匹配、opencode.json 中存在无效 JSON、模型 ID 与上游 API
      不一致，或者编辑提供商配置后忘记重启 OpenCode。
  - question: 能否在 OpenCode 中为多个提供商使用同一个 OpenAI 兼容 API？
    answer: >-
      可以。'provider' 块中的每个条目都是独立的，因此你可以将 Haimaker、Ollama、OpenRouter、LM Studio
      和内部网关分别添加为不同的提供商。使用唯一的提供商 ID 可以让 /models 列表保持清晰易读。
locale: zh-cn
translationKey: opencode-custom-provider-setup
---
OpenCode 的提供商目录支持 75+ 个 LLM 提供商，但自定义提供商依然有其价值。你可以通过它们接入网关、本地运行时、内部推理端点，或尚未收录到目录中的模型。

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

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

## 何时使用自定义提供商

如果目标模型或端点不在 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：

```bash
opencode auth login
```

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

```text
haimaker
ollama
mygateway
```

OpenCode 将凭据保存在：

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

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

## 第二步：配置提供商

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

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

```jsonc
{
  "$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 可能需要重启才能识别新的提供商配置。完全退出后重新启动，然后运行：

```text
/models
```

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

## 完整示例：Haimaker 网关

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

```jsonc
{
  "$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 兼容的本地端点：

```jsonc
{
  "$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 之前先拉取模型：

```bash
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。运行：

```bash
opencode auth list
```

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

#### 模型显示但请求失败

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

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

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

对于 Ollama，检查本地模型：

```bash
ollama list
```

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

#### 本地模型的工具调用失败

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

#### 内置提供商停止工作

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

## 实用配置方案

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

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

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

<a href="https://app.haimaker.ai/sign-up?utm_source=openclaw_blog&utm_medium=cta&utm_campaign=opencode_custom_provider" class="cta-button">在 OpenCode 中使用 Haimaker</a>

---

*本地配置请参阅 [在 OpenCode 中使用 Ollama](/zh-cn/blog/opencode连接ollama本地模型/)。更全面的本地模型排名请参阅 [最适合编码智能体的 Ollama 模型](/zh-cn/blog/适合编程智能体的最佳ollama模型/)。*