diff --git a/cloud/guides/integrations/cline-roo-kilo.mdx b/cloud/guides/integrations/cline-roo-kilo.mdx index cf8ad75..d2c1c32 100644 --- a/cloud/guides/integrations/cline-roo-kilo.mdx +++ b/cloud/guides/integrations/cline-roo-kilo.mdx @@ -168,4 +168,5 @@ Sources checked on 2026-06-23: Cline OpenAI Compatible provider docs, Roo Code O - [Available Models](/cloud/models) - [Continue](/cloud/guides/integrations/continue) - [Aider and Zed](/cloud/guides/integrations/aider-zed) -- [OpenCode and Goose](/cloud/guides/opencode-goose) +- [OpenCode](/cloud/guides/integrations/opencode) +- [Goose](/cloud/guides/opencode-goose) diff --git a/cloud/guides/integrations/index.mdx b/cloud/guides/integrations/index.mdx index 55c9a3e..70cde8e 100644 --- a/cloud/guides/integrations/index.mdx +++ b/cloud/guides/integrations/index.mdx @@ -21,11 +21,12 @@ Use the OpenAI client guide when you are configuring code directly. Use the inte ### Coding agents and IDEs +- [OpenCode](/cloud/guides/integrations/opencode) - [Cursor](/cloud/guides/integrations/cursor) - [Continue](/cloud/guides/integrations/continue) - [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo) - [Aider and Zed](/cloud/guides/integrations/aider-zed) -- [OpenCode and Goose](/cloud/guides/opencode-goose) +- [Goose](/cloud/guides/opencode-goose) ### Self-hosted and team apps diff --git a/cloud/guides/integrations/librechat.mdx b/cloud/guides/integrations/librechat.mdx index 3a728d3..6a3c360 100644 --- a/cloud/guides/integrations/librechat.mdx +++ b/cloud/guides/integrations/librechat.mdx @@ -29,17 +29,21 @@ Do not append `/chat/completions` to `baseURL`. LibreChat appends the chat-compl Use the NEAR AI Cloud gateway model ID: ```text -z-ai/glm-5.2 +z-ai/glm-5.3-flash ``` Check [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) before adding newer model IDs. + +Retired NEAR AI model IDs are kept as aliases onto their successor, so an older ID such as `z-ai/glm-5.2` still resolves today. Prefer the canonical ID from `/v1/models`; an alias can be repointed without notice. + + ## Configure Create or edit `librechat.yaml` in the LibreChat project root: ```yaml librechat.yaml -version: 1.3.13 +version: 1.3.16 cache: true endpoints: @@ -49,13 +53,24 @@ endpoints: baseURL: 'https://cloud-api.near.ai/v1' models: default: - - 'z-ai/glm-5.2' + - 'z-ai/glm-5.3-flash' titleConvo: true - titleModel: 'z-ai/glm-5.2' + titleModel: 'z-ai/glm-5.3-flash' modelDisplayLabel: 'NEAR AI Cloud' + customParams: + reasoningFormat: reasoning_object + reasoningKey: reasoning_content ``` -The custom endpoint name `nearai` is intentionally not a built-in LibreChat endpoint name. Do not add a `provider` field for NEAR AI Cloud; LibreChat uses the OpenAI-compatible custom endpoint path when that field is omitted. +The custom endpoint name `nearai` is intentionally not a built-in LibreChat endpoint name. Omit the `provider` field to get LibreChat's OpenAI-compatible custom endpoint path, which is what this guide configures. + +### Reasoning models + +GLM 5.3 Flash is a reasoning model. It returns its thinking in a `reasoning_content` field, both in complete responses and as streamed deltas. The `customParams` block above tells LibreChat where to find that field so the thinking renders as a reasoning block instead of being discarded. Omit it and you lose the reasoning trace. + +### Title generation + +`titleModel` is called once per conversation. Because GLM 5.3 Flash is a reasoning model, each title costs a short reasoning pass. Set `titleModel: 'current_model'` to follow whichever model the conversation uses, or point it at a cheaper non-reasoning model from `/v1/models` if title cost matters at your volume. Add the key to `.env` in the same project root: @@ -98,16 +113,16 @@ The primary refresh path is manual because this guide keeps a short, explicit mo 3. Add it under `models.default` in `librechat.yaml`. 4. Restart LibreChat so the endpoint selector reads the updated config. -LibreChat's custom endpoint reference also documents `models.fetch: true` for OpenAI-compatible custom endpoints. If you want LibreChat to try `GET /v1/models`, add `fetch: true` under `models` after you confirm the curl check works in your environment: +LibreChat's custom endpoint reference also documents `models.fetch: true` for OpenAI-compatible custom endpoints. NEAR AI Cloud serves `GET /v1/models` without authentication, so fetching works: ```yaml models: default: - - 'z-ai/glm-5.2' + - 'z-ai/glm-5.3-flash' fetch: true ``` -Keep `models.default` populated even when using fetch. LibreChat uses the default list as the fallback if fetching is slow or fails. +Fetching returns every model on the gateway, 50+ of them, including embedding and reranker models that are not chat models, so stay with the manual list if you want a short endpoint selector. Either way, keep `models.default` populated: LibreChat falls back to it when fetching is slow or fails. ## Quick test @@ -118,24 +133,28 @@ 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.2", + "model": "z-ai/glm-5.3-flash", "messages": [ {"role": "user", "content": "Reply with only: near-ai-ok"} ], - "max_tokens": 20 + "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 when the request actually succeeded. + If curl fails, fix the NEAR AI Cloud key, model ID, or network path before changing LibreChat settings. ## Troubleshooting | Symptom | Likely cause | Fix | | --- | --- | --- | -| model not listed | `librechat.yaml` was not mounted, LibreChat was not restarted, or `z-ai/glm-5.2` is missing from `models.default`. | Confirm the Docker mount points to `/app/librechat.yaml`, run `docker compose logs api` for config errors, add the exact model ID under `models.default`, and restart LibreChat. | +| model not listed | `librechat.yaml` was not mounted, LibreChat was not restarted, or `z-ai/glm-5.3-flash` is missing from `models.default`. | Confirm the Docker mount points to `/app/librechat.yaml`, run `docker compose logs api` for config errors, add the exact model ID under `models.default`, and restart LibreChat. | | `401` | `NEARAI_API_KEY` is missing from `.env`, the API container did not reload the environment, or the key is invalid. | Add `NEARAI_API_KEY=...` to `.env`, restart LibreChat, and rerun the curl smoke test without logging the key. | | Wrong base URL includes `/chat/completions` | The full curl request URL was pasted into `baseURL`. | Set `baseURL: 'https://cloud-api.near.ai/v1'`. Use `/chat/completions` only in full request URLs such as the curl smoke test. | | Endpoint not visible | The custom endpoint name conflicts with a built-in endpoint, YAML parsing failed, or the config file is in the wrong directory. | Keep `name: 'nearai'`, validate the YAML, make sure the file is in the LibreChat project root, and check `docker compose logs api`. | +| Replies are empty or cut off mid-thought | A reasoning model consumed the output budget on `reasoning_content`. | Raise the model's max output in LibreChat, and confirm with the curl test at a higher `max_tokens`. | +| The model thinks but the reasoning is never shown | `customParams.reasoningKey` is not set, so LibreChat does not know where NEAR AI puts the trace. | Add `reasoningFormat: reasoning_object` and `reasoningKey: reasoning_content` under `customParams`, then restart LibreChat. | | New NEAR AI model does not appear after release | LibreChat is reading the old manual list or cached endpoint config. | Recheck `/v1/models`, add the model ID under `models.default`, and restart LibreChat. If using `fetch: true`, keep the default fallback list and restart after changing fetch settings. | ## Related guides @@ -150,9 +169,12 @@ If curl fails, fix the NEAR AI Cloud key, model ID, or network path before chang ## Sources Checked -Sources checked on 2026-06-23: +Sources checked on 2026-09-22: - [LibreChat Custom Endpoints](https://www.librechat.ai/docs/quick_start/custom_endpoints) - [LibreChat Custom Config](https://www.librechat.ai/docs/configuration/librechat_yaml) - [LibreChat Custom Endpoint Object Structure](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint) +- [`librechat.example.yaml`](https://github.com/danny-avila/LibreChat/blob/main/librechat.example.yaml) — config `version` +- [`docker-compose.override.yml.example`](https://github.com/danny-avila/LibreChat/blob/main/docker-compose.override.yml.example) — mount target - [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) +- NEAR AI Cloud `GET /v1/models` and `POST /v1/chat/completions` diff --git a/cloud/guides/integrations/opencode.mdx b/cloud/guides/integrations/opencode.mdx new file mode 100644 index 0000000..9a020cd --- /dev/null +++ b/cloud/guides/integrations/opencode.mdx @@ -0,0 +1,237 @@ +--- +title: "OpenCode" +description: "Configure OpenCode to use NEAR AI Cloud as an OpenAI-compatible provider." +--- + + +[OpenCode](https://opencode.ai/) is a terminal coding agent that resolves its providers from the public [models.dev](https://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 in two cases: the model you want is newer than the catalog, or you want to reach a model's TEE directly instead of going through the gateway. Both are covered below. + +## Prerequisites + +- OpenCode installed (verified against `1.18.31`). +- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations). + +Store the key in the environment variable the catalog declares for this provider, `NEARAI_API_KEY`: + +```bash +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: + +```text +https://cloud-api.near.ai/v1 +``` + +You only set `options.baseURL` yourself when overriding it, for example to use a direct completions endpoint. Do not append `/chat/completions`; OpenCode adds the path when it calls the API. + +## Model ID + +OpenCode addresses a model as `/`. Because NEAR AI model IDs already contain a slash, the resulting string has two: + +```text +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](/cloud/guides/integrations/model-discovery) 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: + +```json 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](#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: + +```json 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: + +```json 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: + +```json opencode.json +{ + "$schema": "https://opencode.ai/config.json", + "provider": { + "nearai": { + "whitelist": ["z-ai/glm-5.3-flash"] + } + } +} +``` + +### Direct completions + +To bypass the gateway and connect straight to a model's TEE, override `baseURL` with that model's direct endpoint: + +```json opencode.json +{ + "$schema": "https://opencode.ai/config.json", + "model": "nearai/z-ai/glm-5.3-flash", + "provider": { + "nearai": { + "options": { + "baseURL": "https://glm-5-3-flash.completions.near.ai/v1" + } + } + } +} +``` + +A direct endpoint serves exactly one model, so this override applies to the whole `nearai` provider. If you switch between models, keep the gateway base URL instead. See [Direct Completions](/cloud/private-inference#direct-completions). + +## 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: + +```bash +curl -s https://models.dev/api.json | jq -r '.nearai.models | keys[]' +``` + +Compare that against the live list: + +```bash +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: + +```bash +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: + +```bash +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/` — 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`. | +| A direct completions base URL rejects the model | Each `*.completions.near.ai` endpoint serves one model. Confirm with `curl https:///v1/models` that it advertises the ID you configured. | + +## Related guides + +- [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) +- [OpenAI Compatibility](/cloud/guides/openai-compatibility) +- [Available Models](/cloud/models) +- [Private Inference - Direct Completions](/cloud/private-inference#direct-completions) +- [Goose](/cloud/guides/opencode-goose) +- [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo) + +## Sources Checked + +Sources checked on 2026-09-22, against OpenCode `1.18.31`: + +- [OpenCode providers](https://opencode.ai/docs/providers/) +- [OpenCode config](https://opencode.ai/docs/config/) +- [models.dev catalog](https://models.dev/) — `nearai` provider entry +- NEAR AI Cloud `GET /v1/models` diff --git a/cloud/guides/opencode-goose.mdx b/cloud/guides/opencode-goose.mdx index c0c96b7..7f00994 100644 --- a/cloud/guides/opencode-goose.mdx +++ b/cloud/guides/opencode-goose.mdx @@ -1,127 +1,65 @@ --- -title: "OpenCode and Goose" -description: "Configure OpenCode and Goose to use NEAR AI Cloud as an OpenAI-compatible provider" +title: "Goose" +description: "Configure Goose to use NEAR AI Cloud as an OpenAI-compatible provider." --- -NEAR AI Cloud exposes an OpenAI-compatible API, so agent clients that support OpenAI-compatible providers can use NEAR AI models with only a base URL, API key, and model ID. +[Goose](https://block.github.io/goose/) is an open-source AI agent from Block that runs as a desktop app and a CLI. It ships a first-class **NEAR AI Cloud** provider, described in its own docs as "TEE-backed private inference through an OpenAI-compatible API with dynamic model discovery." -Use this guide when a model is available through NEAR AI Cloud but does not yet appear in an agent client's model picker. For example, the primary GLM 5.2 model ID is `z-ai/glm-5.2`, available through the gateway base URL `https://cloud-api.near.ai/v1`. The direct completions endpoint `https://glm-5-2.completions.near.ai/v1` also advertises `z-ai/glm-5.2` and `zai-org/GLM-5.2-FP8`. +Dynamic discovery is the part that matters day to day: Goose asks the gateway for its model list instead of reading a static catalog, so a newly released NEAR AI model shows up in the picker without a config change. -For the general refresh workflow, see [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery). - -Source status checked on 2026-06-23: OpenCode's model catalog comes from public [models.dev](https://models.dev/). Check the catalog status before assuming a model is built in; if the `nearai` provider does not list `z-ai/glm-5.2`, use a manual `provider.nearai.models` entry until the catalog includes it. Goose can use its NEAR AI Cloud provider, refresh the provider model list, or use a custom model ID. + +Looking for OpenCode? It now has its own page: [OpenCode](/cloud/guides/integrations/opencode). + ## Prerequisites -Create an API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations), then keep it in an environment variable: +- Goose Desktop or the Goose CLI installed. +- A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations). + +Goose reads the key from `NEARAI_API_KEY`. Export it, or let Goose store it when you configure the provider: ```bash export NEARAI_API_KEY="YOUR_NEAR_AI_API_KEY" ``` -You can use either base URL: - -| Base URL | Use when | -|----------|----------| -| `https://cloud-api.near.ai/v1` | You want the gateway to route any NEAR AI Cloud model by model ID. | -| `https://glm-5-2.completions.near.ai/v1` | You want to connect directly to the GLM 5.2 private inference endpoint. | - -The gateway is the easiest default. Direct completions use the same API key and API shape, but connect straight to the model's TEE. See [Direct Completions](/cloud/private-inference#direct-completions) for details. - -## OpenCode - -OpenCode reads its built-in provider and model catalog from [models.dev](https://models.dev/), as described in the public [OpenCode config](https://opencode.ai/docs/config/) and [provider](https://opencode.ai/docs/providers/) docs. If a newly launched NEAR AI model is not listed there yet, add it manually to your OpenCode config. - -For GLM 5.2, set `tool_call` and `reasoning` to `true` in the manual model metadata so OpenCode can expose tool use and thinking-effort variants through `/variants`. The limits below match the live NEAR AI Cloud `/v1/models` metadata checked for this guide. - -Create or edit `~/.config/opencode/opencode.json`: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "model": "nearai/z-ai/glm-5.2", - "provider": { - "nearai": { - "models": { - "z-ai/glm-5.2": { - "name": "GLM 5.2", - "tool_call": true, - "reasoning": true, - "limit": { - "context": 500000, - "output": 131072 - } - } - } - } - } -} -``` +## Base URL -Then start OpenCode with the API key in your shell: +The NEAR AI Cloud provider already targets the gateway: -```bash -export NEARAI_API_KEY="YOUR_NEAR_AI_API_KEY" -opencode +```text +https://cloud-api.near.ai/v1 ``` -If your OpenCode version does not include the built-in `nearai` provider yet, define the provider explicitly: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "model": "nearai/z-ai/glm-5.2", - "provider": { - "nearai": { - "npm": "@ai-sdk/openai-compatible", - "name": "NEAR AI Cloud", - "env": ["NEARAI_API_KEY"], - "options": { - "baseURL": "https://cloud-api.near.ai/v1", - "apiKey": "{env:NEARAI_API_KEY}" - }, - "models": { - "z-ai/glm-5.2": { - "name": "GLM 5.2", - "tool_call": true, - "reasoning": true, - "limit": { - "context": 500000, - "output": 131072 - } - } - } - } - } -} -``` +You do not set this by hand when using the built-in provider. Do not append `/chat/completions`; Goose adds the path when it calls the API. -To use the direct completions endpoint instead of the gateway, change `baseURL`: +## Model ID -```json -{ - "baseURL": "https://glm-5-2.completions.near.ai/v1" -} +Use the gateway model ID exactly as `/v1/models` reports it: + +```text +z-ai/glm-5.3-flash ``` -When using the direct completions endpoint, keep the model set to either `z-ai/glm-5.2` or `zai-org/GLM-5.2-FP8`; both IDs are served by that endpoint. +Because Goose discovers models dynamically, the picker should already offer the current list. See [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) if you need to confirm an ID. -## Goose + +Retired NEAR AI model IDs are kept as aliases onto their successor, so an older ID such as `z-ai/glm-5.2` still resolves today. Prefer the canonical ID from `/v1/models`; an alias can be repointed without notice. + -Goose includes a NEAR AI Cloud provider with model discovery, as described in the public [Goose provider docs](https://goose-docs.ai/docs/getting-started/providers/). Configure it from Goose Desktop or the CLI. +## Configure ### Goose Desktop 1. Open Goose. -2. Go to **Settings**. +2. Open the sidebar, then **Settings**. 3. Open the **Models** tab. 4. Click **Configure providers**. 5. Select **NEAR AI Cloud**. -6. Enter your NEAR AI API key. -7. Switch models and select `z-ai/glm-5.2`. +6. Enter your NEAR AI Cloud API key and submit. +7. Click **Switch models**, then pick a NEAR AI Cloud model. -If GLM 5.2 does not appear in the dropdown, choose the custom model option and enter the model ID manually. +If the model you want is not in the dropdown, choose **Use custom model** and type the model ID. ### Goose CLI @@ -135,116 +73,87 @@ Then select: 1. **Configure Providers** 2. **NEAR AI Cloud** -3. Enter your NEAR AI Cloud API key value, or skip the prompt if `NEARAI_API_KEY` is already set in the environment. -4. Select `z-ai/glm-5.2` +3. Enter your API key, or skip the prompt if `NEARAI_API_KEY` is already exported. +4. Select a model. + +### Config file -If the CLI does not show GLM 5.2 in the model picker, set the model manually in Goose's config: +Goose keeps provider settings in `~/.config/goose/config.yaml` on macOS and Linux, or `%APPDATA%\Block\goose\config\config.yaml` on Windows. Current versions use nested `active_provider` and `providers` keys: -```yaml -# ~/.config/goose/config.yaml -GOOSE_PROVIDER: nearai -GOOSE_MODEL: z-ai/glm-5.2 +```yaml config.yaml +active_provider: nearai +providers: + nearai: + enabled: true + model: z-ai/glm-5.3-flash + configured: true ``` -Restart Goose after changing the provider or model. +Prefer `goose configure` or the Desktop settings over editing this file, so Goose writes the shape its current version expects. -## When NEAR releases a model - -First confirm the new model ID in [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery), then update the client that has the stale picker. - -For OpenCode, check `https://models.dev/api.json` before assuming the model is built in. If the `nearai` provider does not list the new model, add it under `provider.nearai.models` in `~/.config/opencode/opencode.json` and set `model` to `nearai/`. For GLM 5.2, use: - -```json -{ - "model": "nearai/z-ai/glm-5.2", - "provider": { - "nearai": { - "models": { - "z-ai/glm-5.2": { - "name": "GLM 5.2", - "tool_call": true, - "reasoning": true, - "limit": { - "context": 500000, - "output": 131072 - } - } - } - } - } -} + +Older guides show flat `GOOSE_PROVIDER` and `GOOSE_MODEL` keys at the root of `config.yaml`. Goose still reads that legacy form and migrates it when it next updates provider settings, but it is not the current format. The same two names remain valid as environment variables, where they override the config file for that process: + +```bash +GOOSE_PROVIDER=nearai GOOSE_MODEL=z-ai/glm-5.3-flash goose ``` + + +Restart Goose after changing the provider or model. -For Goose, refresh or re-save the NEAR AI Cloud provider so it requests the current model list. If the picker still does not show the model, use the custom model field in Goose Desktop or set `GOOSE_MODEL` manually: +## Refresh models -```yaml -# ~/.config/goose/config.yaml -GOOSE_PROVIDER: nearai -GOOSE_MODEL: z-ai/glm-5.2 -``` +Goose queries NEAR AI Cloud for its model list, so new models normally appear on their own. If the picker looks stale: + +1. Confirm the model exists: `curl https://cloud-api.near.ai/v1/models`. +2. Re-save the NEAR AI Cloud provider in Desktop settings, or re-run `goose configure`, so Goose requests the list again. +3. Restart Goose. +4. If it still does not appear, use **Use custom model** in Desktop or set the model directly in `config.yaml`. ## Quick test -Verify the model works with the same OpenAI-compatible API before debugging an agent client: +Verify the key, base URL, and model against the API before debugging Goose: ```bash 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.2", + "model": "z-ai/glm-5.3-flash", "messages": [ - { - "role": "user", - "content": "Reply with one sentence confirming GLM 5.2 is reachable." - } + {"role": "user", "content": "Reply with only: near-ai-ok"} ], - "max_tokens": 64 + "max_tokens": 256 }' ``` -For the direct completions endpoint: - -```bash -curl https://glm-5-2.completions.near.ai/v1/chat/completions \ - -H "Authorization: Bearer $NEARAI_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "z-ai/glm-5.2", - "messages": [ - { - "role": "user", - "content": "Reply with one sentence confirming GLM 5.2 is reachable." - } - ], - "max_tokens": 64 - }' -``` +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 when the request actually succeeded. ## Troubleshooting | Symptom | Fix | |---------|-----| -| model not listed: GLM 5.2 is not in OpenCode's model picker | Check the public models.dev catalog status, then add it under `provider.nearai.models` in `opencode.json` until the catalog includes the model. | -| OpenCode says the provider or model is unknown | Use `model: "nearai/z-ai/glm-5.2"` and make sure the provider key is `nearai`. | -| model not listed: Goose does not show GLM 5.2 in the model picker | Refresh or re-save the NEAR AI Cloud provider, then use Goose Desktop's custom model entry or set `GOOSE_MODEL: z-ai/glm-5.2` in Goose config. | -| Requests return 401 | Confirm `NEARAI_API_KEY` is set in the same shell or app environment that starts the agent client. | -| wrong base URL includes `/chat/completions` | Check that the client uses `https://cloud-api.near.ai/v1` or `https://glm-5-2.completions.near.ai/v1` as the base URL, not the full `/chat/completions` path. | +| model not listed: the model is missing from the Goose picker | Re-save the NEAR AI Cloud provider or re-run `goose configure` so Goose refetches the list, then restart Goose. If it is still missing, use **Use custom model** or set `model` in `config.yaml`. | +| Requests return `401` | Confirm `NEARAI_API_KEY` is set in the environment that launched Goose, or re-enter the key in **Configure providers**. Desktop and a shell-launched CLI do not always share an environment. | +| wrong base URL includes `/chat/completions` | The built-in provider sets the base URL itself. If you overrode it, use `https://cloud-api.near.ai/v1`; `/chat/completions` belongs only in full request URLs such as the curl test. | +| NEAR AI Cloud is not in the provider list | Update Goose. The provider is listed in current Goose documentation; older builds predate it. As a fallback, configure NEAR AI Cloud through Goose's OpenAI-compatible provider with the gateway base URL. | +| Config edits have no effect | Goose may have migrated a legacy `GOOSE_PROVIDER`/`GOOSE_MODEL` block. Check that `active_provider` and `providers` reflect your intent, and restart Goose. | +| Replies are empty or cut off mid-thought | A reasoning model hit the output limit. Raise `GOOSE_MAX_TOKENS`, and confirm with the curl test at a higher `max_tokens`. | ## Related guides +- [OpenCode](/cloud/guides/integrations/opencode) - [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery) - [OpenAI Compatibility](/cloud/guides/openai-compatibility) - [Available Models](/cloud/models) - [Private Inference - Direct Completions](/cloud/private-inference#direct-completions) -- [Continue](/cloud/guides/integrations/continue) - [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo) ## Sources Checked -Sources checked on 2026-06-23: +Sources checked on 2026-09-22. The Goose steps come from Goose's published documentation and repository; they were not run against a local Goose install. -- [OpenCode config](https://opencode.ai/docs/config/) -- [OpenCode providers](https://opencode.ai/docs/providers/) -- [Goose providers](https://goose-docs.ai/docs/getting-started/providers/) -- [models.dev catalog](https://models.dev/) +- [Goose providers](https://goose-docs.ai/docs/getting-started/providers/) — NEAR AI Cloud provider and `NEARAI_API_KEY` +- [Goose configuration files](https://goose-docs.ai/docs/guides/config-file) — `config.yaml` location, `active_provider`/`providers` shape, legacy key migration +- [`documentation/docs/getting-started/providers.md`](https://github.com/block/goose/blob/main/documentation/docs/getting-started/providers.md) — provider table entry +- NEAR AI Cloud `GET /v1/models` and `POST /v1/chat/completions` diff --git a/docs.json b/docs.json index de09674..257f4de 100644 --- a/docs.json +++ b/docs.json @@ -89,6 +89,7 @@ { "group": "Coding Agents and IDEs", "pages": [ + "cloud/guides/integrations/opencode", "cloud/guides/integrations/cursor", "cloud/guides/integrations/continue", "cloud/guides/integrations/cline-roo-kilo",