Connect OpenCode to AvalAI

Use OpenCode as a terminal coding agent with AvalAI providing model inference. Start with an explicit Chat Completions provider, a dedicated key, and approval prompts for tools. OpenCode—not AvalAI—controls file access, shell commands, plugins, and sharing.

Source-reviewed on 2026-09-08. Configuration is checked against official OpenCode documentation; no credentialed session was run.

1. Install and choose a workspace

Install the official CLI with Node.js and pnpm, or choose a platform-specific method in the installation guide:

pnpm install -g opencode-ai
opencode --version

Record the version you test before rolling it out to a team. Use a disposable project containing no secrets for the first session. OpenCode can load repository instructions, configuration, and plugins; inspect those before opening an unfamiliar repository.

2. Add the provider configuration

Merge the following into ~/.config/opencode/opencode.json; do not overwrite existing settings. A project-local opencode.json can override global values, so inspect it too.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "avalai/gpt-5.4-mini",
  "small_model": "avalai/gpt-5.4-mini",
  "share": "disabled",
  "permission": {
    "*": "ask",
    "external_directory": "deny"
  },
  "provider": {
    "avalai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AvalAI",
      "options": {
        "baseURL": "https://api.avalai.ir/v1"
      },
      "models": {
        "gpt-5.4-mini": {
          "name": "AvalAI GPT-5.4 mini",
          "limit": {
            "context": 272000,
            "output": 128000
          }
        }
      }
    }
  }
}

This uses the upstream @ai-sdk/openai-compatible adapter for /v1/chat/completions, not the @ai-sdk/openai Responses adapter. Both the main and small model are explicit so auxiliary tasks do not silently select another model.

The model metadata comes from the AvalAI catalog checked on 2026-09-08. These are capacity values, not a per-task output budget. Check the current model catalog before substituting another model, especially for tools, vision, context size, or output limits.

3. Store the key and select the model

Start opencode from your chosen project, then:

1. Run /connect.
2. Select Other.
3. Enter provider ID avalai, exactly matching the configuration.
4. Paste your dedicated AvalAI key into the credential prompt.
5. Run /models and select AvalAI GPT-5.4 mini.

The credential prompt stores a local secret; it does not configure the base URL or model by itself. Protect OpenCode's auth store and backups. Do not put the real key in opencode.json.

For environments using a secret manager instead, options.apiKey supports the literal value "{env:AVALAI_API_KEY}". Supply that variable to the OpenCode process and use one credential method consistently.

avalai/gpt-5.4-mini is OpenCode's provider/model selector. The upstream AvalAI request uses the bare ID gpt-5.4-mini. It is not the same namespace as a 9Router gateway prefix.

4. Verify chat, then one tool

First ask:

Reply with exactly: AvalAI connected
Do not use tools or read files.

Then ask it to read one non-sensitive file you name and explain one function. Approve only the expected read. Check that the answer references content actually present in that file.

A text answer proves only inference. A successful file read tests an additional agent/tool path. Before enabling changes, follow the small coding-agent exercise.

The configuration asks before tools and denies access outside the working directory. Do not start with --auto or enable auto-approve: it changes how ask rules behave. Permissions and prompts are not an OS sandbox; use a disposable workspace and least-privilege credentials.

5. Handle optional capabilities separately

• Tools: Require model function calling, compatible schemas, and approved OpenCode permissions.
• Vision: Requires model vision support and compatible image input; test separately.
• Responses: Uses a different adapter. Do not change the adapter just to fix an unrelated authentication problem.
• Embeddings, images, audio, web search and MCP: The language-provider configuration does not automatically configure these services or their credentials.
• 9Router: Add a separate provider if needed; its base URL, downstream key and prefixed model ID are different. See 9Router setup.

Troubleshooting

Symptom	Check
Provider missing in /models	provider.avalai.models exists; credential ID and provider ID match.
401 / 403	Correct dedicated AvalAI key and account access; do not print auth files.
404	Base URL includes exactly one /v1; use the Chat Completions adapter.
Unexpected model or permissions	Project configuration, profiles, plugins or managed settings may override global values.
Tool call appears as text	Verify model function calling, adapter choice, and one minimal read-only tool.
Context or output error	Recheck catalog limits; reduce context and start a fresh bounded session.
High usage	Agent loops and small-model tasks add calls. Check AvalAI usage; local estimates are not invoices.

Official sources and next steps

• OpenCode repository, custom providers, configuration, and permissions.
• Choose a practical workflow, coding-agent exercise, and rate limits.

This guide does not establish end-to-end AvalAI compatibility for every OpenCode release, model, or plugin. Validate a low-risk pilot before using company repositories. No package was installed, key stored, tool executed, or paid request sent during the documentation review.