OpenCode 是目前最热门的开源 AI 编程 Agent 之一。它在终端中运行，支持连接多个 LLM 提供商，让你无需离开命令行就能用 AI 构建、调试和探索代码。

让大家头疼的往往不是安装，而是提供商配置。

OpenCode 支持 75+ 个提供商，但如果你想通过单一端点访问 GPT-4o、Claude、Gemini、Grok 和 DeepSeek，就需要一个统一 API 网关。Omniside 正是为此而生——一个 API Key，一个 Base URL，覆盖所有主流模型。

本指南涵盖所有主流平台的安装与配置：Ubuntu、Debian、CentOS、macOS 和 Windows。

前置条件

开始前需要准备两样东西：

  1. 终端 — 任何现代终端均可（Terminal.app、WezTerm、Alacritty、Windows Terminal 等）
  2. Omniside API Key — 在这里注册（约 30 秒，无需最低充值）

其余步骤在下面逐一介绍。

第一步：安装 OpenCode

OpenCode 安装界面

macOS

最快的方式是 Homebrew：

Terminal window
brew install anomalyco/tap/opencode

或使用通用安装脚本：

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

Ubuntu / Debian

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

或通过 npm 安装（需要 Node.js 18+）：

Terminal window
# 如需安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs


# 安装 OpenCode
npm install -g opencode-ai

CentOS / RHEL / Fedora

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

或通过 npm：

Terminal window
# 如需安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs    # CentOS/RHEL
# 或：sudo dnf install -y nodejs  # Fedora


# 安装 OpenCode
npm install -g opencode-ai

Arch Linux

Terminal window
sudo pacman -S opencode
# 或从 AUR：
paru -S opencode-bin

Windows

推荐使用 WSL（Windows Subsystem for Linux）以获得最佳体验：

Terminal window
# 在 PowerShell（管理员）中安装 WSL（如尚未安装）
wsl --install


# 进入 WSL 后运行：
curl -fsSL https://opencode.ai/install | bash

也支持 Windows 原生安装：

Terminal window
# Chocolatey
choco install opencode


# Scoop
scoop install opencode


# npm
npm install -g opencode-ai

验证安装

安装完成后，确认 OpenCode 正常运行：

Terminal window
opencode --version

看到版本号输出即为成功。如果提示找不到命令，检查二进制文件是否在 PATH 中。

第二步：获取 Omniside API Key

  1. 前往 platform.omniside.ai

    Omniside 平台

  2. 注册或登录

  3. 进入 API Keys 页面

  4. 点击 Create API Key

    创建 API Key

  5. 复制 Key（以 sk- 开头）

    复制 API Key

记好这个 Key，下一步会用到。

第三步：将 Omniside 配置为自定义提供商

OpenCode 使用 opencode.json 配置文件，可以放在两个位置：

  • 全局（所有项目）：~/.config/opencode/opencode.json
  • 项目级：项目根目录下的 opencode.json

我们先做全局配置，让所有项目默认使用 Omniside。

创建配置目录

Terminal window
mkdir -p ~/.config/opencode

根据需求选择以下三种预设之一。

方案 A：完整版 — 所有模型 + 故障转移

最佳体验。以 Claude Sonnet 4.5 为主模型，GPT-4o、Gemini、DeepSeek 作为备用。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniside": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Omniside",
      "options": {
        "baseURL": "https://api.omniside.ai/v1"
      },
      "models": {
        "claude-sonnet-4-5-20250514": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 8192 }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": { "context": 128000, "output": 16384 }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro",
          "limit": { "context": 1000000, "output": 65536 }
        },
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": { "context": 64000, "output": 8192 }
        },
        "grok-3": {
          "name": "Grok 3",
          "limit": { "context": 131072, "output": 8192 }
        }
      }
    }
  }
}

方案 B：智能版 — 最佳性价比（推荐）

以 Claude Sonnet 4.5 为主，GPT-4o 作为备用。适合大多数开发者。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniside": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Omniside",
      "options": {
        "baseURL": "https://api.omniside.ai/v1"
      },
      "models": {
        "claude-sonnet-4-5-20250514": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 8192 }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}

方案 C：经济版 — 最低成本

以 DeepSeek V3 为主。适合日常编码任务。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniside": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Omniside",
      "options": {
        "baseURL": "https://api.omniside.ai/v1"
      },
      "models": {
        "deepseek-chat": {
          "name": "DeepSeek V3",
          "limit": { "context": 64000, "output": 8192 }
        },
        "gpt-4o-mini": {
          "name": "GPT-4o Mini",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}

保存配置文件

在 Linux / macOS 上一行命令完成（以方案 B 为例）：

Terminal window
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniside": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Omniside",
      "options": {
        "baseURL": "https://api.omniside.ai/v1"
      },
      "models": {
        "claude-sonnet-4-5-20250514": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 8192 }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}
EOF

在 Windows（PowerShell）：

Terminal window
$configDir = "$env:USERPROFILE\.config\opencode"
New-Item -ItemType Directory -Force -Path $configDir | Out-Null


@'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniside": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Omniside",
      "options": {
        "baseURL": "https://api.omniside.ai/v1"
      },
      "models": {
        "claude-sonnet-4-5-20250514": {
          "name": "Claude Sonnet 4.5",
          "limit": { "context": 200000, "output": 8192 }
        },
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": { "context": 128000, "output": 16384 }
        }
      }
    }
  }
}
'@ | Set-Content -Path "$configDir\opencode.json" -Encoding UTF8

第四步：添加 API Key

连接 Omniside API Key。启动 OpenCode 并使用 /connect 命令：

Terminal window
opencode

在 TUI 界面中输入：

/connect

提示时选择 “Other” 添加自定义提供商，然后输入：

  • Provider name：Omniside
  • API key：你的 sk-... Key

Key 会安全存储在 ~/.local/share/opencode/auth.json（Linux/macOS）或 %USERPROFILE%\.local\share\opencode\auth.json（Windows）。

提示：不确定 OpenCode 把文件存在哪？运行 opencode paths 查看你系统上的所有配置、数据和缓存路径。

你也可以通过环境变量设置 Key。在 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.profile）中添加：

Terminal window
export OMNISIDE_API_KEY="sk-your-key-here"

然后在配置文件中用 {env:...} 语法引用：

"options": {
  "baseURL": "https://api.omniside.ai/v1",
  "apiKey": "{env:OMNISIDE_API_KEY}"
}

第五步：选择模型

在任意项目目录启动 OpenCode：

Terminal window
cd /path/to/your/project
opencode

使用 /models 命令选择模型：

/models

你会看到 Omniside 的模型列表。选择一个——例如 omniside/claude-sonnet-4-5-20250514。

完成。现在你可以在终端中通过 Omniside 使用 Claude、GPT-4o、Gemini 或任何其他模型进行编程了。

切换模型

在 OpenCode 内部随时切换：

/models

或启动时用 -m 参数指定：

Terminal window
opencode -m omniside/gpt-4o

使用环境变量替代配置文件

如果你偏好不写配置文件的极简方式，可以直接设置环境变量：

Terminal window
export OPENAI_API_KEY="sk-your-omniside-key"
export OPENAI_BASE_URL="https://api.omniside.ai/v1"

由于 Omniside 兼容 OpenAI API，OpenCode 内置的 OpenAI 提供商会自动通过 Omniside 路由。缺点是你只能看到 OpenCode 已知的模型（如 gpt-4o），Claude 和 Gemini 不会出现在模型列表中。

如需完整的多模型体验，请使用第三步的配置文件方式。

各平台注意事项

Ubuntu / Debian

如果 npm install -g 出现权限错误，可以：

  • 使用 sudo npm install -g opencode-ai，或
  • 设置 npm 全局目录：npm config set prefix ~/.npm-global，并将 ~/.npm-global/bin 加入 PATH

CentOS / RHEL

CentOS 7 上可能需要更新 gcc 和 glibc 才能运行 Node.js 22。建议使用 CentOS Stream 9 或 Rocky Linux 9 以获得更顺畅的体验。

macOS

首次运行时 macOS 可能弹出安全提示。前往系统设置 → 隐私与安全性，允许 OpenCode 运行。

如果使用 Homebrew tap（anomalyco/tap/opencode），你始终能获取最新版本。官方 brew install opencode 由 Homebrew 团队维护，可能有版本滞后。

Windows

推荐使用 WSL。如需原生 Windows 安装：

  • 使用 Windows Terminal 获得最佳 TUI 体验
  • 推荐 PowerShell 7+ 而非旧版 PowerShell
  • 部分 OpenCode 功能（如文件监听）在 WSL 下表现更好

ARM / 树莓派

OpenCode 支持 ARM Linux，通过 npm 安装：

Terminal window
npm install -g opencode-ai

Omniside 配置完全相同，架构不影响 API 配置。

验证配置是否正常

运行快速测试确认配置无误：

Terminal window
# 检查 OpenCode 是否识别到你的模型
opencode models


# 或启动 OpenCode 提问
opencode

在 TUI 中尝试一个简单提示：

这个目录里有哪些文件？

如果 OpenCode 使用你选择的 Omniside 模型回答了文件列表，说明一切正常。

问题排查

”Route /api/messages not found”

baseURL 必须以 /v1 结尾，不能是 /v1/chat/completions。确认配置中是：

"baseURL": "https://api.omniside.ai/v1"

模型未出现在 /models 中

检查：

  1. 配置文件中 provider 部分格式是否正确
  2. npm 字段是否设置为 "@ai-sdk/openai-compatible"
  3. 修改配置后是否重启了 OpenCode

认证错误

确认 API Key 已通过以下方式之一设置：

  • OpenCode 内部的 /connect 命令，或
  • 配置文件的 options.apiKey 字段，或
  • 用 {env:VARIABLE_NAME} 引用的环境变量

连接超时

如果你在企业代理或防火墙后面，可能需要设置 HTTPS_PROXY 环境变量：

Terminal window
export HTTPS_PROXY="http://your-proxy:8080"

为什么选择 Omniside 搭配 OpenCode？

常规的 OpenCode 配置需要你逐一注册每个 AI 提供商。如果你想同时使用 Claude、GPT-4o 和 Gemini，那就是三次注册、三个 API Key、三个账单账户。

使用 Omniside，你只需在 OpenCode 中配置一个提供商，即可访问所有主流模型。用 /models 随时切换——无需重新配置。

在 platform.omniside.ai/models 查看完整模型列表。

前往 platform.omniside.ai 获取你的 API Key，开始编程。