Skip to content

docs: add OpenCode guide, split Goose out, fix LibreChat accuracy - #52

Merged
sergeiest merged 2 commits into
mainfrom
docs/opencode-goose-librechat-integrations
Sep 22, 2026
Merged

sergeiest merged 2 commits into
mainfrom
docs/opencode-goose-librechat-integrations

Conversation

@sergeiest

Copy link
Copy Markdown
Contributor

Adds a dedicated OpenCode integration guide, separates Goose onto its own page, and corrects stale facts found while verifying both against the live gateway.

OpenCode — new page

cloud/guides/integrations/opencode.mdx, following the section contract in .github/INTEGRATION_GUIDE_TEMPLATE.md.

The thing that shaped the page: models.dev now carries the nearai provider, so OpenCode needs no provider block at all. The minimum working config is a single model line. The guide then covers the three cases that still need config — models newer than the catalog, trimming the 50+ model picker, and direct completions.

Verified end to end against OpenCode 1.18.31:

Check Result
Zero-config path (model line + NEARAI_API_KEY) opencode run → near-ai-ok
Manual provider.nearai.models entry near-ai-ok on z-ai/glm-5.3-flash
Direct-completions baseURL override near-ai-ok via glm-5-3-flash.completions.near.ai/v1
opencode models nearai resolves 32 catalog models

Goose — split onto its own page

cloud/guides/opencode-goose.mdx is now Goose-only. Rewritten rather than trimmed, because verification turned up two errors:

  • Config format was stale. The page showed flat GOOSE_PROVIDER / GOOSE_MODEL keys. Current Goose uses nested active_provider / providers. The old form is read for compatibility and migrated on update, so it wasn't broken — just legacy. Both are now documented, since those names remain valid as environment variables.
  • The refresh story was backwards. The page treated Goose like OpenCode — stale picker, manual workarounds. Goose's NEAR AI Cloud provider does dynamic model discovery, so new models appear on their own. Manual steps are now the fallback.

Also removed https://glm-5-2.completions.near.ai/v1, which no longer resolves (TLS connect failure).

LibreChat — accuracy fixes

  • The smoke test didn't work. max_tokens: 20 against a reasoning model returns content: null with finish_reason: length — 61 of 66 completion tokens went to reasoning_content. The guide then told readers to go fix their key or network path. Raised to 256.
  • Reasoning output was silently dropped. Added customParams.reasoningFormat / reasoningKey: reasoning_content; the gateway streams the trace in that field.
  • titleModel was a reasoning model, paying for a reasoning pass on every conversation title. Moved to google/gemini-2.5-flash-lite.
  • Config version: 1.3.13 → 1.3.16, matching upstream librechat.example.yaml.
  • Softened the blanket "do not add a provider field" — accurate for the OpenAI-compatible path, but it forecloses the native Anthropic one.

Across all three

z-ai/glm-5.2 → z-ai/glm-5.3-flash. The old ID survives only as an alias onto its successor, which is now noted inline on each page.

Reviewer notes

  • Goose steps are not locally verified. Goose isn't installed on the authoring machine, so those steps come from Goose's published docs and block/goose's own providers.md, stated as such in Sources Checked. Worth a real Goose run before merge. One loose end: NEAR AI Cloud appears in Goose's docs and provider table, but there is no near* file under crates/goose/src/providers/ on main, so the config key nearai is inferred from the NEARAI_API_KEY convention rather than confirmed in source.
  • The Goose page still lives at /cloud/guides/opencode-goose. Renaming it to cloud/guides/integrations/goose.mdx would match its siblings but needs a redirects entry. Left out of this PR deliberately.
  • /v1/messages is undocumented. The gateway serves a native Anthropic Messages endpoint plus count_tokens — verified working with streaming and tool use — but neither appears in api-reference/openapi.json, so they are absent from the API Reference tab. Upstream spec gap; it also blocks documenting LibreChat's provider: anthropic path.
  • The alias <Note> is now duplicated across pages. If it keeps spreading it probably belongs in model-discovery.mdx.

mint validate and mint broken-links both pass.

🤖 Generated with Claude Code

Sergey and others added 2 commits September 22, 2026 14:28
Add a dedicated OpenCode integration guide and separate Goose onto its
own page, then correct stale facts found while verifying both against
the live gateway.

OpenCode (new page):
- models.dev now carries the `nearai` provider, so the minimum config is
  a single `model` line with no provider block. Verified end to end
  against OpenCode 1.18.31.
- Cover the cases that still need config: models newer than the catalog,
  trimming the 50+ model picker, and direct completions.

Goose (cloud/guides/opencode-goose.mdx, now Goose-only):
- Document the current nested `active_provider`/`providers` config shape.
  The flat GOOSE_PROVIDER/GOOSE_MODEL keys the page used are legacy and
  migrated on update; they remain valid as environment variables.
- Goose's provider does dynamic model discovery, so reframe "refresh
  models" around that rather than manual workarounds.
- Drop https://glm-5-2.completions.near.ai/v1, which no longer resolves.

LibreChat:
- Smoke test used max_tokens: 20 against a reasoning model, returning
  content: null with finish_reason: length. Raised to 256.
- Add customParams.reasoningKey: reasoning_content so reasoning output
  renders; the gateway streams it in that field.
- Move titleModel off a reasoning model to google/gemini-2.5-flash-lite.
- Config version 1.3.13 -> 1.3.16 to match librechat.example.yaml.
- Soften the blanket "do not add a provider field"; it is accurate only
  for the OpenAI-compatible path.

Across all three:
- z-ai/glm-5.2 -> z-ai/glm-5.3-flash. The old ID survives only as an
  alias, noted inline on each page.

Goose steps come from Goose's published docs and repository; they were
not run against a local install. Everything else was executed live.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Drop google/gemini-2.5-flash-lite from the LibreChat guide and keep one
model throughout: models.default and titleModel both use
z-ai/glm-5.3-flash. The title-generation note now states the reasoning
cost and points at current_model rather than adding a second model.

Lead the OpenCode Model ID section with z-ai/glm-5.3-flash alone and
narrow the whitelist example to it.

The OpenCode catalog-models example keeps a models.dev model,
anthropic/claude-haiku-4-5, because that section exists to show the
zero-config path and z-ai/glm-5.3-flash is not in the catalog yet.
Added a line saying so and pointing at the check under Refresh models.
Verified against OpenCode 1.18.31.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@sergeiest
sergeiest merged commit a268529 into main Sep 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant