> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.agnes-ai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Opencode Integration Guide

> Opencode Integration Guide for Agnes Models

***

## Overview

This guide explains how to connect **OpenCode** to the **Agnes-2.0-Flash** model.

After configuration, you can use Agnes models in OpenCode for code generation, project analysis, code editing, and multi-turn development conversations.

<Info>This guide is based on OpenCode `1.15.13`.</Info>

***

## Prerequisites

Before you start, make sure you have completed the following steps:

1. Registered an Agnes AI account
2. Logged in to the Agnes API Platform
3. Created and copied your API Key
4. Confirmed that your network can access the Agnes API Gateway

| Item     | Value                            |
| -------- | -------------------------------- |
| Provider | `Agnes`                          |
| Base URL | `https://apihub.agnes-ai.com/v1` |
| Model    | `agnes-2.0-flash`                |
| API Key  | Your API Key from Agnes Platform |

<Warning>
  Only paste the API Key itself. Do not add `Bearer` before the key.
</Warning>

***

# OpenCode CLI Configuration

## Use Case

This method is for users who use OpenCode through the terminal.

If you already have an OpenCode configuration file, you only need to add the `agnes` provider and set the default model to:

```json theme={null}
"model": "agnes/agnes-2.0-flash"
```

***

## Configuration Example

Open your OpenCode configuration file and add the following configuration:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",

  "model": "agnes/agnes-2.0-flash",

  "provider": {
    "agnes": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Agnes",
      "options": {
        "baseURL": "https://apihub.agnes-ai.com/v1",
        "apiKey": "{env:AGNES_API_KEY}"
      },
      "models": {
        "agnes-2.0-flash": {
          "name": "agnes-2.0-flash"
        }
      }
    }
  }
}
```

<Info>
  If your configuration file already contains other providers, do not overwrite
  the entire file. Add `agnes` under `provider`, then set `model` to
  `agnes/agnes-2.0-flash`.
</Info>

***

## Configure the Environment Variable

Set your Agnes API Key in the terminal:

```bash theme={null}
export AGNES_API_KEY="your Agnes API Key"
```

To make it permanent, add it to your shell configuration file.

For bash users:

```bash theme={null}
echo 'export AGNES_API_KEY="your Agnes API Key"' >> ~/.bashrc
source ~/.bashrc
```

For macOS or zsh users:

```bash theme={null}
echo 'export AGNES_API_KEY="your Agnes API Key"' >> ~/.zshrc
source ~/.zshrc
```

***

## Verify CLI Configuration

Start OpenCode and run:

```bash theme={null}
/models
```

If the configuration is successful, you should see:

```text theme={null}
Agnes
agnes-2.0-flash
```

Select:

```text theme={null}
Agnes / agnes-2.0-flash
```

You can now use Agnes in OpenCode CLI.

***

# OpenCode Desktop Configuration

## Use Case

This method is for users who use the **OpenCode Desktop** graphical interface.

***

## Configuration Steps

<Steps>
  <Step title="Open Settings">
    Launch OpenCode Desktop and click the settings button in the lower-left corner.
  </Step>

  <Step title="Go to Providers">
    In the settings page, click **Providers** from the left-side menu.
  </Step>

  <Step title="Choose Custom Provider">
    Find **Custom Provider** in the provider list and click **Connect**.
  </Step>

  <Step title="Fill in Provider Information">
    Enter the Agnes provider information according to the table below.
  </Step>
</Steps>

***

## Provider Configuration

| Field              | Value                            |
| ------------------ | -------------------------------- |
| Provider ID        | `agnes`                          |
| Display Name       | `Agnes`                          |
| Base URL           | `https://apihub.agnes-ai.com/v1` |
| API Key            | Your Agnes API Key               |
| Model ID           | `agnes-2.0-flash`                |
| Model Display Name | `Agnes 2.0 Flash`                |

Example:

```text theme={null}
Provider ID: agnes
Display Name: Agnes
Base URL: https://apihub.agnes-ai.com/v1
API Key: sk-xxxxxxxx
Model ID: agnes-2.0-flash
Model Display Name: Agnes 2.0 Flash
```

After completing the form, click **Submit**.

***

## Verify Desktop Configuration

Return to the OpenCode Desktop main interface.

In the model selector, choose:

```text theme={null}
Agnes / agnes-2.0-flash
```

Send a test message:

```text theme={null}
Hello, what model are you?
```

If the model responds normally, the configuration is complete.

***

## Common Issues

### Agnes model does not appear

Check the following items:

1. The Provider ID is `agnes`
2. The Base URL is `https://apihub.agnes-ai.com/v1`
3. The Model ID is `agnes-2.0-flash`
4. The API Key is correct
5. The API Key does not include `Bearer`

***

### API Key error

Make sure the API Key is copied from Agnes Platform and does not contain extra spaces.

Correct example:

```text theme={null}
sk-xxxxxxxxxxxxxxxx
```

Incorrect example:

```text theme={null}
Bearer sk-xxxxxxxxxxxxxxxx
```

***

### Request failed or cannot connect

Check the following items:

1. Your network can access the Agnes API Gateway
2. The Base URL only ends with `/v1`
3. The Base URL is not written as `/v1/chat/completions`
4. Your API Key is still valid

Correct Base URL:

```text theme={null}
https://apihub.agnes-ai.com/v1
```

***

## Recommended Model

| Scenario                            | Recommended Model |
| ----------------------------------- | ----------------- |
| Daily coding                        | `agnes-2.0-flash` |
| Project analysis                    | `agnes-2.0-flash` |
| Code editing                        | `agnes-2.0-flash` |
| Multi-turn development conversation | `agnes-2.0-flash` |

***

## Quick Reference

| Parameter           | Value                            |
| ------------------- | -------------------------------- |
| Provider Name       | `Agnes`                          |
| Provider ID         | `agnes`                          |
| NPM Provider        | `@ai-sdk/openai-compatible`      |
| Base URL            | `https://apihub.agnes-ai.com/v1` |
| API Key Env         | `AGNES_API_KEY`                  |
| Model ID            | `agnes-2.0-flash`                |
| OpenCode Model Path | `agnes/agnes-2.0-flash`          |