Configure OpenCode

Goal

让 OpenCode 通过 Nexus 调用一条明确的 ProviderConnection。

Outcome

配置文件只保存 Nexus Gateway Base URL 和环境变量引用；模型 Key 仍是目标 Provider 的原始模型名。

Prerequisites

• 已安装 OpenCode。
• Gateway Base URL、Inference Key 和目标 Provider 接受的模型名。

Lifecycle note

顶层自定义 Provider 名称只是 OpenCode 配置；真正的 Workspace 选择来自 Inference Key，连接选择来自 URL 中不可变的 providerConnectionId。

1. Save the complete configuration

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nexus-openrouter/provider/opaque-model-v9",
  "provider": {
    "nexus-openrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Nexus OpenRouter",
      "options": {
        "baseURL": "https://gateway.nexus.microvoid.io/providers/00000000-0000-0000-0000-000000000141",
        "apiKey": "{env:NEXUS_API_KEY}"
      },
      "models": {
        "provider/opaque-model-v9": {
          "name": "Provider opaque model"
        }
      }
    }
  }
}

2. Run OpenCode

export NEXUS_API_KEY="<NEXUS_INFERENCE_KEY>"
opencode

Check your work

运行 /models 时能选择 nexus-openrouter/provider/opaque-model-v9；一次请求在 Nexus Usage 中关联同一模型、Access 和 ProviderConnection。

Failure modes

• 找不到模型：检查顶层 model 是否由自定义 Provider 名和原始模型 Key 组成。
• 401：环境变量未传入 OpenCode，或 Key 已撤销/过期。
• Provider 模型错误：不要让 Nexus 风格名称替换原始上游模型 Key。

Security notes

保留 {env:NEXUS_API_KEY}，不要把 Key 明文提交到 opencode.json。Inference Key 也不能进入 Admin API。

Next steps

需要解释配置字段时阅读 OpenCode integration；需要轮换时阅读 Rotate an inference key。