ApiFluxAI | 使用 ApiFlux 配置 OpenCode

安装 OpenCode，新增 ApiFlux Provider 与 API Key，选择模型并验证请求。

本指南介绍如何将 OpenCode 连接到 ApiFlux。配置完成后，OpenCode 可以通过 ApiFlux 的 OpenAI-compatible 界面发送模型请求。

适用场景

适合希望在 OpenCode 中使用 ApiFlux 统一管理模型接入、用量、记录和模型切换的用户。

如果用户还没有安装终端或 Node.js，建议先阅读：

ApiFlux 使用前准备：安装终端和基础环境

准备工作

开始前，请准备：

一个 ApiFlux API Key
一个 ApiFlux 支持的模型 ID
ApiFlux Base URL：

https://apiflux.ai/v1

模型 ID 请从 ApiFlux Models 页面复制。

1. 安装 OpenCode

Windows

OpenCode 官方文件建议 Windows 用户优先使用 WSL，以获得更接近 Linux / macOS 的开发体验。

如果使用 Windows 原生 PowerShell，可以选择以下任一方式安装。

使用 npm：

npm install -g opencode-ai

使用 Chocolatey：

choco install opencode

使用 Scoop：

scoop install opencode

如果使用 WSL，请在 WSL 终端中按 macOS / Linux 命令安装。

macOS / Linux

使用官方安装指令码：

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

也可以使用 npm：

npm install -g opencode-ai

macOS 用户也可以使用 Homebrew：

brew install anomalyco/tap/opencode

安装完成后，关闭终端并重新打开。

2. 确认 OpenCode 已安装

在终端中执行：

opencode --version

如果能看到版本号，说明 OpenCode 已安装成功。

如果提示 command not found 或「不是内部或外部命令」，请重新打开终端；如果仍然失败，请重新执行安装命令。

3. 使用 /connect 查看内建 Provider

启动 OpenCode：

opencode

进入后输入：

/connect

如果列表中已经包含 ApiFlux，可以按界面提示填写 API Key。

如果列表中没有 ApiFlux，可以使用 OpenAI-compatible custom provider 手动设置。

4. 配置 API Key 环境变量

建议通过环境变量提供 API Key，而不是把真实 Key 直接写入配置文件。

Windows PowerShell

当前窗口暂时生效：

$env:APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

检查是否生效：

echo $env:APIFLUX_API_KEY

长期生效：

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

设置长期环境变量后，请关闭 PowerShell，再重新打开。

macOS / Linux

当前窗口暂时生效：

export APIFLUX_API_KEY="YOUR_APIFLUX_API_KEY"

检查是否生效：

echo $APIFLUX_API_KEY

macOS 默认通常是 zsh，长期生效可以写入 ~/.zshrc：

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

Linux 常见是 bash，长期生效可以写入 ~/.bashrc：

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

[!WARNING] 不要将真实 API Key 提交到 GitHub，也不要出现在公开视频、公开截图或团队共享文档中。

5. 配置 OpenCode Provider

建议先使用项目级配置文件。也就是说，在用户当前项目文件夹下建立：

opencode.json

这样 Windows、macOS、Linux 都可以使用同样的配置文件名。

如果已有 opencode.json，请合并 provider 设置，不要覆盖原有配置。

加入以下配置：

{
  "$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": {}
      }
    }
  }
}

将 YOUR_MODEL_ID 替换为 ApiFlux Models 页面中显示的模型 ID。

示例：

{
  "$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 是示例模型。实际可用模型请以 ApiFlux Models 页面为准。

6. 选择模型并测试

重新启动 OpenCode：

opencode

进入后输入：

/models

选择刚刚设置的 ApiFlux 模型。

然后发送测试请求：

用一句话介绍 ApiFlux 是什么

如果 OpenCode 正常回复，请回到 ApiFlux 控制台，打开 Logs 查看请求记录。

常见问题

OpenCode 找不到 ApiFlux Provider

请检查：

opencode.json 是否放在当前项目文件夹
JSON 格式是否正确
是否在已有设置中正确合并了 provider
启动 OpenCode 的目录是否正确

API Key missing

Windows PowerShell 检查：

echo $env:APIFLUX_API_KEY

macOS / Linux 检查：

echo $APIFLUX_API_KEY

如果没有输出，请重新配置环境变量。

模型不存在

请确认配置中的模型 ID 来自 ApiFlux Models 页面。

插件导致 OpenCode 启动失败

如果 OpenCode 启动时报类似错误：

fn3 is not a function

通常是本机 OpenCode 插件异常，不是 ApiFlux 配置错误。

可以暂时打开全局设置。

macOS / Linux / WSL：

~/.config/opencode/opencode.json

Windows 原生环境中，设置路径可能位于：

C:\Users\你的用户名\.config\opencode\opencode.json

将 plugin 临时配置为空数组后再测试：

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

确认 OpenCode 能正常启动后，再逐个恢复插件。

function tools 或 reasoning_effort 不支持

如果某个模型不适合 OpenCode 的工具调用请求，可以换用更适合编码场景的模型，例如：

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

使用 ApiFlux 配置 OpenCode

目录