> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/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.net](https://avis.net), 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.net/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.net/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.net/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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/integrations/coding/opencode.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.