OpenCode

OpenCode is a terminal coding agent that resolves its providers from the public models.dev catalog. NEAR AI Cloud is already in that catalog as the nearai provider, so in the common case you do not write a provider block at all: set an API key, point model at a NEAR AI model, and OpenCode handles the rest. You only need a manual provider entry when the model you want is newer than the catalog or your OpenCode version predates the catalog’s nearai entry. Both cases use the Gateway configuration below.

Prerequisites

OpenCode installed (verified against 1.18.31).
A NEAR AI Cloud API key from the NEAR AI Cloud Dashboard.

Store the key in the environment variable the catalog declares for this provider, NEARAI_API_KEY:

export NEARAI_API_KEY="YOUR_NEAR_AI_API_KEY"

Alternatively, run /connect inside the OpenCode TUI, pick NEAR AI Cloud, and paste the key. OpenCode stores it in ~/.local/share/opencode/auth.json so you do not need the environment variable.

Do not paste a literal key into opencode.json. Config files are frequently committed to source control. Use NEARAI_API_KEY, /connect, or the {env:NEARAI_API_KEY} substitution syntax shown below.

Base URL

The catalog already sets the gateway base URL for the nearai provider:

https://cloud-api.near.ai/v1

You only set options.baseURL yourself in a full provider block. Do not append /chat/completions; OpenCode adds the path when it calls the API.

Model ID

OpenCode addresses a model as <provider>/<model-id>. Because NEAR AI model IDs already contain a slash, the resulting string has two:

nearai/z-ai/glm-5.3-flash

This is expected. The provider is nearai; everything after the first slash is the NEAR AI model ID. Check Model Discovery and Refresh for the current list.

Configure

Catalog models

For any model already in the models.dev catalog, a model line is the whole configuration. Put it in ~/.config/opencode/opencode.json for all projects, or opencode.json in a project root to override it there:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nearai/anthropic/claude-haiku-4-5"
}

With NEARAI_API_KEY exported, opencode starts against NEAR AI Cloud. You can also skip the config file entirely and pick the model with /models in the TUI. z-ai/glm-5.3-flash is not in the catalog yet, so it needs the extra step in the next section. Use the check under Refresh models to see which side of the line a given model falls on.

Models newer than the catalog

The catalog lags NEAR AI Cloud releases. If /models does not list the model you want, declare it under provider.nearai.models. OpenCode merges this with the catalog entry, so you only supply what is missing:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nearai/z-ai/glm-5.3-flash",
  "provider": {
    "nearai": {
      "models": {
        "z-ai/glm-5.3-flash": {
          "name": "GLM 5.3 Flash",
          "tool_call": true,
          "reasoning": true,
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        }
      }
    }
  }
}

Set tool_call and reasoning to match the model’s supported_features in /v1/models, and set limit from its context_length and max_output_length. OpenCode uses these to decide whether to offer tool use and thinking-effort variants; a model with tool support left at the default will behave as though it has none.

Full provider block

If your OpenCode version predates the catalog’s nearai entry, define the provider outright:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "nearai/z-ai/glm-5.3-flash",
  "provider": {
    "nearai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "NEAR AI Cloud",
      "options": {
        "baseURL": "https://cloud-api.near.ai/v1",
        "apiKey": "{env:NEARAI_API_KEY}"
      },
      "models": {
        "z-ai/glm-5.3-flash": {
          "name": "GLM 5.3 Flash",
          "tool_call": true,
          "reasoning": true,
          "limit": {
            "context": 1048576,
            "output": 131072
          }
        }
      }
    }
  }
}

Trimming the model picker

NEAR AI Cloud exposes 50+ models. OpenCode’s documented whitelist and blacklist options keep /models short:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "nearai": {
      "whitelist": ["z-ai/glm-5.3-flash"]
    }
  }
}

Refresh models

OpenCode does not call NEAR AI Cloud’s /v1/models. Its picker comes from the models.dev catalog, so a newly released NEAR AI model appears only after the catalog updates. To check whether a model is available without a manual entry:

curl -s https://models.dev/api.json | jq -r '.nearai.models | keys[]'

Compare that against the live list:

curl -s https://cloud-api.near.ai/v1/models | jq -r '.data[].id'

Anything present in the second list but not the first needs a manual provider.nearai.models entry until the catalog catches up. opencode models nearai shows what OpenCode currently resolves, catalog plus your config combined.

NEAR AI model IDs are aliased. Retired IDs often keep working because they resolve to their successor — z-ai/glm-5.2 and zai-org/GLM-5.1-FP8 both route to z-ai/glm-5.3-flash today. Prefer the canonical ID from /v1/models; an alias can be repointed without notice.

Quick test

Verify the key, base URL, and model against the API before debugging OpenCode:

curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.3-flash",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 256
  }'

Keep max_tokens generous on reasoning models. GLM 5.3 Flash spends its first tokens on reasoning_content, so a tight limit returns "content": null with "finish_reason": "length" and looks like a failure. Once curl succeeds, test the same path through OpenCode:

opencode run "Reply with only: near-ai-ok"

Troubleshooting

Symptom	Fix
model not listed: the model is missing from `/models`	The models.dev catalog is behind. Add it under `provider.nearai.models` as shown above, then confirm with `opencode models nearai`.
Requests return `401`	`NEARAI_API_KEY` is not set in the shell that launched OpenCode, or no credential was stored. Export the variable, or run `/connect` and select NEAR AI Cloud.
wrong base URL includes `/chat/completions`	Set `options.baseURL` to `https://cloud-api.near.ai/v1`. The `/chat/completions` path belongs only in full request URLs such as the curl test.
OpenCode reports an unknown provider or model	The provider key must be `nearai`, and `model` must be `nearai/<model-id>` — including the slash inside the model ID, as in `nearai/z-ai/glm-5.3-flash`.
The model replies but never calls tools	The manual model entry is missing `tool_call: true`. Catalog entries set this; hand-written ones default to off.
Replies are empty or truncated mid-thought	A reasoning model hit the output limit. Raise `limit.output` in the model entry to match `max_output_length` from `/v1/models`.

Sources Checked

Sources checked on 2026-09-22, against OpenCode 1.18.31:

OpenCode providers
OpenCode config
models.dev catalog — nearai provider entry
NEAR AI Cloud GET /v1/models

Get Started

Models

Private Inference

Guides

Experimental

Prerequisites

Base URL

Model ID

Configure

Catalog models

Models newer than the catalog

Full provider block

Trimming the model picker

Refresh models

Quick test

Troubleshooting

Sources Checked

​Prerequisites

​Base URL

​Model ID

​Configure

​Catalog models

​Models newer than the catalog

​Full provider block

​Trimming the model picker

​Refresh models

​Quick test

​Troubleshooting

​Related guides

​Sources Checked

Prerequisites

Base URL

Model ID

Configure

Catalog models

Models newer than the catalog

Full provider block

Trimming the model picker

Refresh models

Quick test

Troubleshooting

Related guides

Sources Checked