LowHow 文档

中文

English

中文

English

深色模式

OpenCode 多提供商配置实战教程：连接 OpenAI、Ollama 等 AI 模型 ​

📚 分类: 开发者工具 / AI 集成 ⏱️ 预计耗时: 30-60 分钟（取决于你选择的提供商数量） 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode TUI 或 CLI 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 的提供商（Provider）概念和认证机制
  • [ ] 通过 /connect 命令为 5 种不同类型的提供商配置 API 密钥
  • [ ] 通过 opencode.json 配置文件自定义提供商（包括 Base URL、本地模型和自定义请求头）
  • [ ] 独立解决常见的提供商配置错误

最终效果 ​

你将掌握在 OpenCode 中连接并使用各种 AI 模型的通用技能。无论是云端的大模型（如 OpenAI、Anthropic），还是本地运行的模型（如 Ollama、LM Studio），你都能在 OpenCode 的模型选择列表中看到它们，并像使用内置模型一样流畅地进行对话和代码生成。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
OpenCode已安装最新版opencode --version
网络连接能够访问外网ping google.com

💡 提示：如果你还没有安装 OpenCode，请先访问 OpenCode 官方文档 完成安装。

第 1 步：理解提供商的核心概念 ​

🎯 目标：理解 OpenCode 中“提供商”是什么，以及如何管理其凭据。

在 OpenCode 中，一个“提供商”（Provider）代表一个你可以连接的 AI 模型服务。例如，OpenAI、Anthropic 或你本地运行的 Ollama 都是提供商。

要使用一个提供商，你需要做两件事：

  1. 添加凭据：使用 /connect 命令告诉 OpenCode 你的 API 密钥。
  2. （可选）配置细节：通过 opencode.json 文件，你可以自定义提供商的行为，比如修改 API 地址、指定模型等。

第 2 步：为云端提供商添加 API 密钥（以 OpenAI 为例） ​

🎯 目标：通过 /connect 命令，为 OpenAI 添加 API 密钥，并验证连接成功。

这是最常用的方式，适用于大多数云端服务。我们以 OpenAI 为例，但流程同样适用于 Anthropic、DeepSeek、Groq 等数十家提供商。

📝 操作：

  1. 启动 OpenCode TUI：

    bash
    $ opencode

  2. 执行 /connect 命令：在 OpenCode 的命令输入框中，输入 /connect 并回车。

    bash
    # 在 OpenCode 中输入
/connect

  3. 选择提供商：终端会显示一个提供商列表。使用方向键上下滚动，找到 OpenAI，然后按回车键选中。

  4. 选择认证方式：你会看到几个选项：

    text
    ┌ Select auth method│
│ ChatGPT Plus/Pro│
│ Manually enter API Key│
└
    • ChatGPT Plus/Pro：如果你有 ChatGPT 订阅，选择此项，浏览器会自动打开引导你完成授权。
    • Manually enter API Key：如果你已经有 OpenAI 的 API 密钥，选择此项。

  5. 输入 API 密钥：选择“Manually enter API Key”后，终端会提示你粘贴 API 密钥。

    text
    ┌ API key│
│ sk-... │
└ enter

    粘贴你的密钥（以 sk- 开头）并回车。

✅ 验证： 操作成功后，OpenCode 不会有特别提示，但凭据已经存储。你可以通过以下方式验证：

  1. 输入 /models 命令。
  2. 你应该能看到一个模型列表，例如 gpt-4o、gpt-4-turbo 等。
  3. 选择一个模型，开始一个新对话，如果能正常发送消息并收到回复，就说明配置成功了。

第 3 步：为需要环境变量的提供商配置（以 Amazon Bedrock 为例） ​

🎯 目标：为 Amazon Bedrock 配置 AWS 认证，使其能在 OpenCode 中工作。

有些提供商（如 Amazon Bedrock、Google Vertex AI）不直接使用简单的 API 密钥，而是需要更复杂的认证方式（如 AWS 的 Access Key 和 Secret Key）。你需要通过环境变量或配置文件来提供这些信息。

📝 操作：

  1. 准备 AWS 凭据：你需要拥有一个 AWS 账户，并创建一个 IAM 用户，该用户需要有调用 Bedrock 模型的权限。记下该用户的 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

  2. 设置环境变量：在运行 opencode 命令之前，在终端中设置环境变量。这是最快速的方法。

    bash
    # 在终端中，先设置环境变量，再启动 opencode
$ export AWS_ACCESS_KEY_ID=你的AccessKeyID
$ export AWS_SECRET_ACCESS_KEY=你的SecretAccessKey
$ export AWS_REGION=us-east-1
$ opencode

    💡 提示：为了避免每次都输入，你可以将 export 命令添加到你的 shell 配置文件中（如 ~/.bash_profile 或 ~/.zshrc）。

  3. （推荐）使用配置文件：对于项目级别的持久化配置，更推荐在 opencode.json 中设置。在项目根目录创建或编辑 opencode.json 文件：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile" // 如果你使用 AWS CLI 的命名配置文件
      }
    }
  }
}

    🤔 为什么要这样做？：opencode.json 文件可以跟随你的项目，方便团队共享配置，也避免了在系统环境中设置全局变量。

✅ 验证： 在 OpenCode 中执行 /models 命令。如果配置正确，你应该能看到 Amazon Bedrock 提供的模型列表（如 anthropic.claude-sonnet-4 等）。选择一个模型，开始对话进行测试。

第 4 步：为本地模型提供商配置（以 Ollama 为例） ​

🎯 目标：通过 opencode.json 配置文件，将本地运行的 Ollama 服务添加为自定义提供商。

如果你运行了本地模型（如通过 Ollama、LM Studio、llama.cpp），你可以通过“自定义提供商”的方式让 OpenCode 连接它们。

📝 操作：

  1. 确保本地服务已启动：首先，确保你的 Ollama 服务正在运行，并且你已经拉取了一个模型（例如 llama2）。

    bash
    $ ollama serve
# 在另一个终端窗口
$ ollama pull llama2

  2. 编辑 opencode.json 配置文件：在项目根目录创建或编辑 opencode.json 文件，添加以下内容：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": { // 自定义提供商ID，可以任意取名，如 "my-local-llm"
      "npm": "@ai-sdk/openai-compatible", // 使用这个包连接任何兼容 OpenAI 的 API
      "name": "Ollama (Local)", // 在 OpenCode UI 中显示的名称
      "options": {
        "baseURL": "http://localhost:11434/v1" // Ollama 的 API 端点
      },
      "models": {
        "llama2": { // 模型ID，必须与 Ollama 中的模型名一致
          "name": "Llama 2 (Local)" // 在模型选择列表中显示的名称
        }
      }
    }
  }
}

    🤔 为什么要这样做？：Ollama 提供的 API 与 OpenAI 的 API 格式兼容，因此我们使用 @ai-sdk/openai-compatible 包来桥接。baseURL 告诉 OpenCode 去哪里找你的本地服务。

  3. 重启 OpenCode：退出 OpenCode 并重新启动，以使配置文件生效。

✅ 验证： 在 OpenCode 中执行 /models 命令。你应该能在列表中找到名为 Llama 2 (Local) 的模型。选择它并开始对话。如果一切正常，你会收到来自你本地模型的回复。

⚠️ 常见错误： 如果 OpenCode 无法连接，请检查：

  • Ollama 服务是否正在运行？ollama ps
  • baseURL 的端口（11434）是否正确？
  • models 下的模型 ID（llama2）是否与你用 ollama list 看到的名称完全一致？

第 5 步：为兼容 OpenAI 的第三方提供商配置（以自定义提供商为例） ​

🎯 目标：通过“自定义提供商”功能，连接 /connect 命令列表中未列出的任何 OpenAI 兼容 API 服务。

很多新兴的 AI 服务提供商都提供与 OpenAI 兼容的 API。你可以通过“自定义提供商”功能来集成它们。

📝 操作：

  1. 添加凭据：在 OpenCode 中执行 /connect 命令。在提供商列表中，向下滚动到最底部，选择 Other。

    bash
    $ /connect
# ... 滚动到最底部
┌ Add credential
│ ◆ Select provider
│ ...
│ ● Other
└

  2. 输入提供商 ID：系统会要求你输入一个唯一的 ID，用于在配置文件中引用它。例如，输入 my-custom-ai。

    bash
    $ /connect
┌ Add credential
│ ◇ Enter provider id
│ my-custom-ai
└

  3. 输入 API 密钥：粘贴该服务提供商给你的 API 密钥。

    bash
    ┌ Add credential
│ ◇ Enter your API key
│ sk-...
└

  4. 编辑 opencode.json 配置文件：现在，你需要告诉 OpenCode 这个 my-custom-ai 提供商的具体信息。在 opencode.json 中添加：

    json
    {
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-custom-ai": { // 必须与第2步输入的 ID 一致
      "npm": "@ai-sdk/openai-compatible", // 对于兼容 OpenAI 的 API 使用此包
      "name": "My Custom AI Service", // UI 中显示的名称
      "options": {
        "baseURL": "https://api.my-custom-service.com/v1" // 替换为实际的 API 地址
      },
      "models": {
        "my-cool-model": { // 模型ID，从服务商文档获取
          "name": "My Cool Model Display Name"
        }
      }
    }
  }
}

✅ 验证： 重启 OpenCode 并执行 /models 命令。你应该能看到 My Cool Model Display Name 出现在列表中。选择它并开始对话，测试连接是否成功。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 自定义请求头：一些服务（如 Helicone）需要特定的请求头来实现缓存、用户跟踪等功能。你可以在 options.headers 中设置。

    json
    "options": {
  "baseURL": "https://ai-gateway.helicone.ai",
  "headers": {
    "Helicone-Cache-Enabled": "true",
    "Helicone-User-Id": "my-opencode-user"
  }
}

  2. 设置模型 Token 限制：为本地模型或自定义模型明确设置上下文窗口和输出长度限制，帮助 OpenCode 更好地管理上下文。

    json
    "models": {
  "my-model": {
    "name": "My Model",
    "limit": {
      "context": 128000,
      "output": 65536
    }
  }
}

常见问题 (FAQ) ​

Q1: 执行 /models 后看不到我配置的模型？A: 请检查以下几点：

  1. 配置文件路径：确认 opencode.json 文件在你启动 OpenCode 的当前工作目录下。
  2. JSON 格式：确保 opencode.json 是有效的 JSON 格式，没有多余的逗号或拼写错误。可以使用在线 JSON 校验工具检查。
  3. 提供商 ID 一致：对于自定义提供商，确保 /connect 时输入的 ID 与 opencode.json 中 provider 下的 key 完全一致。

Q2: 报错 401 Unauthorized 或认证失败？A: 这通常意味着 API 密钥无效或未正确配置。

  1. 检查凭据：运行 opencode auth list 查看已存储的凭据列表。确认你的提供商在列表中。
  2. 重新输入：执行 /connect 命令，选择你的提供商，重新输入正确的 API 密钥。
  3. 环境变量：对于依赖环境变量的提供商（如 Bedrock），确认变量名和值都已正确设置并导出。

Q3: 配置了本地模型（如 Ollama），但 OpenCode 连接不上？A:

  1. 服务未启动：确保你的本地模型服务（如 ollama serve）正在运行。
  2. 端口错误：检查 opencode.json 中的 baseURL 端口号是否与你的本地服务一致。Ollama 默认是 11434，LM Studio 默认是 1234。
  3. 模型 ID 不匹配：models 下的 key（如 llama2）必须与你本地服务中拉取的模型名称完全一致（包括大小写）。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 核心概念：提供商是连接 AI 模型的桥梁，通过 /connect 管理凭据，通过 opencode.json 进行详细配置。
  2. 三种配置模式：
    • 简单模式（如 OpenAI）：只用 /connect 输入 API 密钥即可。
    • 环境变量模式（如 Bedrock）：通过环境变量或 opencode.json 提供复杂的认证信息。
    • 自定义模式（如 Ollama）：通过 opencode.json 手动定义所有连接参数。
  3. 通用性：任何兼容 OpenAI API 的服务，都可以通过“自定义提供商”的方式集成到 OpenCode 中。

© 2026 LowHow