集成

OpenCode

以 Markdown 格式查看

OpenCode logo

将 OpenModels 作为 OpenCode 的自定义 OpenAI 兼容供应商。OpenCode 保留其终端 UI、CLI、agents、tools、permissions 和项目配置。OpenModels 提供模型端点、API 密钥、模型 ID 和积分计费。

本指南聚焦 OpenCode 通过 https://api.getopenmodels.com/v1 调用 OpenModels。

适用场景

当你希望实现以下目标时，请使用此配置：

  • 将 OpenCode 用作本地仓库的 AI coding agent。
  • 将 OpenModels 用作上游模型市场。
  • 使用一个 ale-... OpenModels API 密钥进行 OpenCode 模型调用。
  • 通过 @ai-sdk/openai-compatible 使用兼容 OpenAI 的聊天补全。
  • 使用可提交到仓库、但不包含 secrets 的 project-level config。

前置条件

  • 在你工作的机器上安装 OpenCode。
  • 一个 ale-... 格式的 OpenModels API 密钥。
  • 您的 OpenModels 账户中有可用积分。
  • 一个受支持的 OpenModels chat 或 coding model ID，例如 qwen3.5-flash 或 kimi-k2.7-code。

1. 安装 OpenCode

使用官方安装脚本安装 OpenCode：

curl -fsSL https://opencode.ai/install | bash

其他受支持安装方式包括 npm、Bun、pnpm、Yarn、Homebrew、Arch Linux packages、Chocolatey、Scoop、Docker 和 release binaries。

2. 添加 OpenModels 凭证

最直接的方式是使用 OpenCode 的 /connect flow 并选择 Other：

/connect

使用此 provider ID：

openmodels

然后粘贴你的 OpenModels API 密钥：

ale-...

OpenCode 会将 credentials 存储在其 auth store 中，而不是 opencode.json。

对于 headless 或 project-local setups，也可以使用环境变量：

export OM_API_KEY="ale-..."

不要将真实的 ale-... 密钥提交到应用仓库。

3. 将 OpenModels 配置为供应商

在项目根目录创建或更新 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openmodels/kimi-k2.7-code",
  "small_model": "openmodels/qwen3.5-flash",
  "provider": {
    "openmodels": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OpenModels",
      "options": {
        "baseURL": "https://api.getopenmodels.com/v1"
      },
      "models": {
        "kimi-k2.7-code": {
          "name": "kimi-k2.7-code",
          "limit": {
            "context": 256000,
            "output": 8192
          }
        },
        "qwen3.5-flash": {
          "name": "qwen3.5-flash",
          "limit": {
            "context": 1000000,
            "output": 8192
          }
        }
      }
    }
  }
}

如果你使用 OM_API_KEY 而不是 /connect，请在 options 下添加 apiKey：

"options": {
  "baseURL": "https://api.getopenmodels.com/v1",
  "apiKey": "{env:OM_API_KEY}"
}

说明：

  • openmodels 是 provider ID。它必须与 /connect 中使用的 ID 匹配。
  • npm: "@ai-sdk/openai-compatible" 告诉 OpenCode 使用兼容 OpenAI 的聊天补全适配器。
  • model 使用 provider_id/model_id 格式。
  • small_model 用于更便宜的 lightweight tasks，例如标题生成。
  • limit.context 和 limit.output 帮助 OpenCode 理解可用 context。更新这些值前请检查 OpenModels Models 页面。

4. 启动 OpenCode

从你的项目目录运行 OpenCode：

opencode

如果这是新项目，请初始化 project instructions：

/init

然后验证所选模型：

/models

从你的 config 中选择 openmodels/kimi-k2.7-code 或其他 OpenModels model。

5. 使用 OpenModels 模型 ID

opencode.json 中的模型 ID 必须匹配 OpenModels 模型 ID。

推荐起点：

使用场景模型
低成本 smoke testsqwen3.5-flash
Coding-heavy repository workkimi-k2.7-code
更大 context 或推理从 Models 页面选择 high-context chat 或 coding model

对于 production-like usage，依赖某个模型前请在 Models 页面检查 pricing、context、routes、supply 和 live status。

6. 将密钥排除在项目配置之外

当项目级 opencode.json 只包含供应商配置、模型 ID 和限制时，可以提交它。不要提交 API 密钥。

请改用以下方式之一：

  • /connect，它会将 credentials 存储在 OpenCode 的 auth store 中。
  • options.apiKey: "{env:OM_API_KEY}"，并在仓库外设置 OM_API_KEY。

故障排查

症状检查项
OpenCode 找不到 provider确认 opencode.json 中存在 provider.openmodels key
认证失败确认 /connect 使用了 provider ID openmodels，或在使用 {env:OM_API_KEY} 时设置 OM_API_KEY
OpenModels 返回 401确认 API 密钥是有效的 ale-... 密钥并且仍处于启用状态
Balance 或 billing failure发送请求前向 OpenModels 账号添加 credits
Model 未出现在 /models 中确认 model 已列在 provider.openmodels.models 下
Model call 失败确认 options.baseURL 精确为 https://api.getopenmodels.com/v1
Context warnings 或截断根据 OpenModels Models 页面更新 limit.context

参考资料