Connect OpenCode to ApiFlux

This guide connects OpenCode to the OpenAI-compatible ApiFlux endpoint. After setup, OpenCode sends model requests through ApiFlux.

Who this guide is for

Use this guide if you want to manage OpenCode model access, usage, logs, and model selection through ApiFlux.

If you have not set up a terminal or Node.js, start here:

Prepare your terminal and development environment

Before you start

Before you start, make sure you have:

• An ApiFlux API key
• A model ID supported by ApiFlux
• ApiFlux Base URL:

https://apiflux.ai/v1

Copy the model ID from the ApiFlux Models page.

1. Install OpenCode

Windows

OpenCode recommends WSL for Windows users who want an environment closer to Linux or macOS.

If you use Windows native PowerShell, you can choose any of the following installation methods.

Use npm:

npm install -g opencode-ai

Using Chocolatey:

choco install opencode

Use Scoop:

scoop install opencode

If using WSL, install using the macOS/Linux command in the WSL terminal.

macOS/Linux

Use the official installation script:

curl -fsSL https://opencode.ai/install | bash

You can also use npm:

npm install -g opencode-ai

macOS users can also use Homebrew:

brew install anomalyco/tap/opencode

Once the installation is complete, close the terminal and reopen it.

2. Confirm OpenCode is installed

Run in terminal:

opencode --version

If the command prints a version number, OpenCode is installed.

If you see command not found or “not recognized as an internal or external command,” reopen the terminal. If the error remains, run the installation command again.

3. Check the built-in providers with /connect

Start OpenCode:

opencode

After entering, enter:

/connect

If ApiFlux appears in the list, select it and enter your API key when prompted.

If ApiFlux is not in the list, you can configure it manually using the OpenAI-compatible custom provider.

4. Set API key environment variable

Provide the API key through an environment variable instead of writing it directly in the configuration file.

Windows PowerShell

For the current terminal session:

$env:APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

Verify the variable:

echo $env:APIFLUX_API_KEY

To persist the variable for future sessions:

[Environment]::SetEnvironmentVariable("APIFLUX_API_KEY","YOUR_APIFLUX_API_KEY","User")

After setting persistent environment variables, close PowerShell and reopen it.

macOS/Linux

For the current terminal session:

export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

Verify the variable:

echo $APIFLUX_API_KEY

macOS usually uses zsh. To persist the variable, add it to ~/.zshrc:

echo 'export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"' >> ~/.zshrc
source ~/.zshrc

Linux usually uses bash. To persist the variable, add it to ~/.bashrc:

echo 'export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"' >> ~/.bashrc
source ~/.bashrc

[!WARNING] Do not submit real API keys to GitHub, or appear in public videos, public screenshots, or team-shared documents.

5. Configure OpenCode Provider

Start with a project-level configuration file. Create this file in your project directory:

opencode.json

The same filename works on Windows, macOS, and Linux.

If opencode.json already exists, merge the provider object into it instead of overwriting the file.

Add the following configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiflux": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiFlux",
      "options": {
        "baseURL": "https://apiflux.ai/v1",
        "apiKey": "{env:APIFLUX_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": {}
      }
    }
  }
}

Replace YOUR_MODEL_ID with the model ID shown in the ApiFlux Models page.

Example:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apiflux": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ApiFlux",
      "options": {
        "baseURL": "https://apiflux.ai/v1",
        "apiKey": "{env:APIFLUX_API_KEY}"
      },
      "models": {
        "deepseek-v4-pro": {}
      }
    }
  }
}

[!NOTE] deepseek-v4-pro is an example model. Please refer to the ApiFlux Models page for the actual available models.

6. Select model and test

Restart OpenCode:

opencode

After entering, enter:

/models

Select the ApiFlux model you just configured.

Then send a test request:

Explain what ApiFlux is in one sentence

After OpenCode returns a response, open Logs in the ApiFlux console and confirm that the request appears.

FAQ

OpenCode cannot find ApiFlux Provider

Please check:

• opencode.json is in the current project directory
• The JSON is valid
• provider was merged correctly with the existing configuration
• OpenCode was started from the intended project directory

API key missing

Windows PowerShell check:

echo $env:APIFLUX_API_KEY

macOS/Linux check:

echo $APIFLUX_API_KEY

If there is no output, reset the environment variables.

Model not found

Please confirm that the model ID in the configuration comes from the ApiFlux Models page.

A plugin prevents OpenCode from starting

If OpenCode starts with a similar error:

fn3 is not a function

This usually indicates an OpenCode plugin error, not an ApiFlux configuration error.

Open the global configuration file.

macOS/Linux/WSL:

~/.config/opencode/opencode.json

In a Windows native environment, the configuration path may be located at:

C:\Users\YOUR_USERNAME\.config\opencode\opencode.json

Temporarily set plugin to an empty array and test again:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": []
}

After OpenCode starts successfully, restore the plugins one at a time.

Not supported by function tools or reasoning_effort

If the current model does not support OpenCode's tool calls, switch to a coding model that does, for example:

deepseek-v4-pro
qwen3.7-plus
glm-5.2

References

• ApiFlux Quickstart
• OpenCode Providers
• OpenCode Install