---
title: "Configure OpenCode"
description: "Configure the tested OpenCode OpenAI-compatible provider without changing the upstream model name."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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


```json title="opencode.json"
{
  "$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

```sh title="Terminal"
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](/docs/make-model-requests/opencode)；需要轮换时阅读 [Rotate an inference key](/cookbook/rotate-inference-key)。

Source: https://nexus.microvoid.io/cookbook/opencode/index.mdx