> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/integrations/coding/opencode.md). # OpenCode ## OpenCode Integration Guide This document explains how to integrate [OpenCode](https://opencode.ai) with the AVIS OpenAI-compatible API. ### What is OpenCode OpenCode is an open-source AI coding agent available as a terminal interface (TUI), a desktop app (macOS/Windows/Linux), and an IDE extension. It supports many model providers through pluggable AI SDK adapters — AVIS is registered as a **custom provider** pointing at AVIS's OpenAI-compatible surface, since AVIS isn't one of OpenCode's built-in named providers. ### 1) Install OpenCode ```bash # Install script curl -fsSL https://opencode.ai/install | bash # npm npm install -g opencode-ai # Homebrew brew install anomalyco/tap/opencode ``` ### 2) Get an AVIS API key See Authentication — sign in at [avis.xyz](https://avis.xyz), go to **Settings → API Keys**, and create one. ### 3) Configure AVIS as a custom provider Set the key in your shell so `opencode.json` can reference it without inlining the raw value: ```bash export AVIS_API_KEY="" ``` Edit the config file — project-level `opencode.json` at your project root, or global `~/.config/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "avis": { "npm": "@ai-sdk/openai-compatible", "name": "AVIS", "options": { "baseURL": "https://api.avis.xyz/api/openai/v1", "apiKey": "{env:AVIS_API_KEY}" }, "models": { "claude-sonnet-5": { "name": "Claude Sonnet 5", "limit": { "context": 200000, "output": 64000 } }, "claude-opus-5": { "name": "Claude Opus 5", "limit": { "context": 200000, "output": 128000 } }, "gpt-5.5": { "name": "GPT-5.5" } } } }, "model": "avis/claude-sonnet-5" } ``` Notes: * `npm: "@ai-sdk/openai-compatible"` is the AI SDK adapter for a generic OpenAI-compatible endpoint — this is the one to use for AVIS. * `models` keys must be the **exact flat id** AVIS's OpenAI-compat catalog returns (no `anthropic/`/`openai/` prefix) — e.g. `claude-sonnet-5`, not `anthropic/claude-sonnet-5`. Confirm against the live catalog: ```bash curl https://api.avis.xyz/api/openai/v1/models \ -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id' ``` * `"model": "avis/"` sets the default — the prefix here is your provider block's key (`avis`), not part of the AVIS catalog id. * `{env:AVIS_API_KEY}` is resolved from the environment at runtime; OpenCode doesn't need `AVIS_API_KEY` for anything else, it's just a name you chose in §3's `export`. ### 4) Run OpenCode ```bash cd your-project opencode ``` Inside the session, list configured models to confirm `avis` shows up: ``` /models ``` Run one-shot (non-interactive), useful for a quick smoke test or scripting: ```bash opencode run "Reply with exactly one word: pong" --model avis/claude-haiku-4-5 ``` ### 5) Troubleshooting * Provider `avis` doesn't appear in `/models` * Config changes to `opencode.json` require restarting `opencode` — quit and re-run. * Validate the JSON itself (a syntax error silently drops the whole `provider` block on some versions) — run it through any JSON linter/`jq . opencode.json`. * `401 Unauthorized` * `AVIS_API_KEY` isn't exported in the shell `opencode` was launched from — `{env:AVIS_API_KEY}` resolves empty if the var isn't set there. * AVIS key is invalid or revoked — verify directly: `curl -H "x-api-key: $AVIS_API_KEY" https://api.avis.xyz/api/openai/v1/models`. * `404` / model not found / model slug rejected * The id under `models` doesn't match AVIS's catalog exactly (case-sensitive, no prefix) — re-check against `GET /api/openai/v1/models` (§3). * `403` with a valid key * Account balance is depleted — see Errors. * Wrong npm adapter used * `@ai-sdk/openai-compatible` is for `/chat/completions`-style calls. If you instead want the `/responses`-style path, use `@ai-sdk/openai` with the same `baseURL`/`apiKey` — but for AVIS, `@ai-sdk/openai-compatible` against `/api/openai/v1` covers every model in the catalog regardless of brand (Anthropic, Gemini, etc. included), so there's normally no need to switch. ### 6) Minimal End-to-End Checklist 1. AVIS API key created (§2) and exported as `AVIS_API_KEY` in the shell. 2. `opencode.json` has an `avis` provider block with `npm`, `baseURL`, `apiKey`, and at least one entry under `models` matching a real AVIS catalog id (§3). 3. `opencode` restarted after any config edit. 4. `/models` inside a session lists the `avis` provider's models. 5. A message sent through OpenCode returns model output, using `avis/` as the active model. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avis.xyz/integrations/coding/opencode.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.