OpenCode CLI 配置指南 (CC Switch)

本文档用于指导客户在 Windows 环境下安装 OpenCode CLI，并通过 CC Switch 使用 koalaapi 提供的模型服务。配置完成后，用户可以在 PowerShell、CMD 或 WSL 终端中运行 opencode，并通过 koalaapi 调用模型。

一、准备工作

开始配置前，请先确认已具备以下条件：

已拥有可正常登录的 koalaapi 账号。

已安装或准备安装 OpenCode CLI。

已安装或准备安装 CC Switch。

当前网络环境可以正常访问 https://koalaapi.com。

已确认要使用的 koalaapi 令牌分组中包含 OpenCode 可用的模型。

如果使用 npm 安装 OpenCode CLI，请提前安装 Node.js 和 npm。可以在 PowerShell 或 CMD 中执行下面的命令检查：

如果两条命令都能正常显示版本号，说明 Node.js 和 npm 已安装完成。

二、安装 OpenCode CLI

OpenCode 官方建议 Windows 用户优先使用 WSL 获得更完整的终端体验。如果你已经在使用 WSL，可以在 WSL 终端中执行：

如果你希望直接在 Windows 的 PowerShell 或 CMD 中使用 OpenCode CLI，可以使用 npm 安装：

如果你已经安装 Scoop 或 Chocolatey，也可以选择对应方式安装：

scoop install opencode

choco install opencode

安装完成后，关闭当前终端，再重新打开 PowerShell、CMD 或 WSL 终端，执行下面的命令确认安装是否成功：

如果能正常显示版本号，说明 OpenCode CLI 已安装完成。

三、安装 CC Switch

请先按照 4SAPI 官方文档完成 CC Switch 安装：

【CC Switch 安装教程】https://koalaapi.apifox.cn/8659863m0

安装完成后，请确认 CC Switch 可以正常打开。后续需要在 CC Switch 中手动添加 OpenCode 供应商配置。

打开 CC Switch 后，请确认顶部应用列表中可以找到 OpenCode 对应入口。

四、创建 OpenCode 专用令牌

打开 koalaapi 官网并登录账号：

https://koalaapi.com

登录后，依次点击 控制台 → 令牌管理 → 添加令牌。

在创建令牌页面，按需填写以下信息：

名称：建议填写容易识别的名称，例如 OpenCode令牌。

令牌分组：选择用于 OpenCode 的分组。请确保该分组中包含你需要使用的模型。

额度设置：按实际需求设置额度。如果不需要限制额度，可保持默认配置。

访问限制：如无特殊网络限制要求，可保持默认配置。

确认信息无误后，点击提交。

五、复制令牌密钥

令牌创建成功后，页面会返回令牌列表。

在令牌列表中找到刚创建的令牌，点击该令牌所在行中间密钥旁边的复制按钮，然后选择 复制密钥。

注意：这里需要选择 复制密钥，不要选择 复制连接信息。

六、在 CC Switch 中手动添加 OpenCode 配置

打开 CC Switch，点击顶部应用列表中的 OpenCode 图标，然后点击右上角的加号。

在添加供应商页面中，点击 自定义配置。

进入自定义配置页面后，按以下要求填写：

供应商名称：填写容易识别的名称，例如 My OpenCode。

备注：可选，可填写用途说明。

官网链接：填写 https://koalaapi.com/v1。

API Key：粘贴刚刚从 4SAPI 令牌列表复制的密钥。

请求地址：填写 4SAPI 的 OpenAI 兼容请求地址，通常为 https://koalaapi.com/v1。如果 koalaapi 页面或客服给出的地址不同，请以实际地址为准。

额外选项：键名和值保持默认。

模型 ID：填写要在 OpenCode CLI 中使用的模型 ID。模型 ID 必须来自当前令牌分组中的可用模型。

如果页面支持 获取模型列表，可以先点击 获取模型列表。如果无法自动获取，请点击 添加模型，手动填写模型 ID。

模型添加完成后，选择要使用的模型，然后点击添加或保存。

七、启用配置并测试连通性

添加成功后，CC Switch 会返回 OpenCode 配置列表。

在列表中找到刚添加的配置，例如 My OpenCode，点击添加。

启用后，点击该配置右侧的 连通性测试 按钮。

如果页面上方提示 连通正常，说明 CC Switch 配置已生效。

注意：启用配置后，建议 关闭所有已打开的 PowerShell、CMD 或 WSL 终端，再重新打开终端。这样可以确保 OpenCode CLI 读取到 CC Switch 写入的最新配置。

八、验证 OpenCode CLI

重新打开 PowerShell、CMD 或 WSL 终端，进入你的项目目录。

执行下面的命令启动 OpenCode CLI：

如果首次进入时提示选择供应商、登录或初始化，请先确认 CC Switch 中 OpenCode 配置已经处于 使用中 状态，再回到终端继续。

选择自己模型后，输入一个简单问题进行测试，例如：

请用一句话说明你已经连接成功。

如果模型可以正常回复，说明 OpenCode CLI 已通过 CC Switch 使用 4SAPI 配置完成。

如果这是第一次在当前项目中使用 OpenCode，也可以在 OpenCode CLI 中执行：

/init

该命令会让 OpenCode 分析项目，并在项目根目录创建或更新 AGENTS.md。

九、常见问题

输入 `opencode` 后提示命令不存在

通常是 OpenCode CLI 没有安装成功，或者 npm、Scoop、Chocolatey 的全局命令目录没有加入环境变量。

请重新执行安装命令，安装完成后 关闭终端，再重新打开 PowerShell、CMD 或 WSL 终端。

启用配置后 OpenCode CLI 仍然走默认服务

请优先检查以下内容：

CC Switch 当前启用的是刚添加的 My OpenCode 配置。

当前选中的是 OpenCode 页面。

启用配置后，是否已经重新打开 PowerShell、CMD 或 WSL 终端。

项目目录下是否存在 .env 文件，并且里面配置了旧的 API Key 或 Base URL。

本机是否手动设置过旧的 OPENAI_API_KEY、OPENAI_BASE_URL 或其他相关环境变量。

如果之前手动执行过 opencode auth login，OpenCode 可能已经保存过旧供应商凭据。可以执行下面的命令查看已登录的供应商：

如确认旧凭据会干扰当前配置，请先在 OpenCode 或 CC Switch 中清理旧配置后再测试。

添加后无法连通

请优先检查以下内容：

koalaapi 令牌是否已启用。

令牌分组中是否包含所选模型。

CC Switch 中是否已点击启用。

API Key 是否复制完整。

请求地址 是否为 koalaapi 的 OpenAI 兼容请求地址。

模型 ID 是否和 koalaapi 后台可用模型 ID 完全一致。

当前网络是否可以正常访问 https://koalaapi.com。

运行 `opencode` 后提示需要登录

如果已经通过 CC Switch 启用了 koalaapi 配置，但 OpenCode CLI 仍提示登录，请先关闭所有终端窗口，再重新打开终端运行 opencode。

如果仍然提示登录，请回到 CC Switch，确认 My OpenCode 配置处于 使用中 状态，并重新执行 连通性测试。

可以从 koalaapi 官网一键导入 OpenCode 配置吗

当前 OpenCode CLI 配置需要在 CC Switch 中手动添加。koalaapi 官网用于创建令牌并复制密钥，不要使用官网的一键 CC Switch 导入流程配置 OpenCode CLI。

找不到 OpenCode 应用入口

请先确认 CC Switch 已更新到较新的版本。如果当前版本没有 OpenCode 入口，请参考 koalaapi 的 CC Switch 使用教程更新或重新安装 CC Switch。

OpenCode CLI 配置指南 (CC Switch)

一、准备工作#

二、安装 OpenCode CLI#

三、安装 CC Switch#

四、创建 OpenCode 专用令牌#

五、复制令牌密钥#

六、在 CC Switch 中手动添加 OpenCode 配置#

七、启用配置并测试连通性#

八、验证 OpenCode CLI#

九、常见问题#

输入 opencode 后提示命令不存在#

启用配置后 OpenCode CLI 仍然走默认服务#

添加后无法连通#

运行 opencode 后提示需要登录#

可以从 koalaapi 官网一键导入 OpenCode 配置吗#

找不到 OpenCode 应用入口#