OpenCode CLI 设置

学习如何配置 OpenCode CLI 使用 CiYuanX 的 API。本指南涵盖 Windows、macOS 和 Linux 的安装和配置。

什么是 OpenCode？

OpenCode 是一个基于 Go 语言的开源命令行编程工具（CLI），为开发者提供强大的 AI 辅助功能。它提供直观的终端用户界面（TUI），支持多种 LLM 提供商，包括 OpenAI、Anthropic、Gemini 等。

通过将 OpenCode 与 CiYuanX API 集成，你可以通过统一的接口、一个密钥和一个基础 URL 访问 CiYuanX 上的任何模型（包括 Claude、GPT、Gemini 等）。

前置条件

开始之前，请确保你拥有：

一个 CiYuanX 账户（在此注册）
一个 CiYuanX API 密钥（获取密钥）
计算机上的终端 / 命令提示符访问权限

终端模拟器

OpenCode 需要现代终端模拟器。推荐选项：

WezTerm（跨平台）
Alacritty（跨平台）
Ghostty（Linux 和 macOS）
Kitty（Linux 和 macOS）

Windows 用户也可以使用 PowerShell 或 Windows Terminal。macOS 用户可以使用内置的 Terminal.app 或 iTerm2。Linux 用户可以使用内置终端或 GNOME Terminal、Konsole 等。

安装

选择你的操作系统以查看安装说明。

macOS 和 Linux

最简单的方式是通过安装脚本：

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

或使用 Homebrew：

brew install anomalyco/tap/opencode

验证安装：

opencode --version

Windows

Windows 用户应首先安装 Node.js，然后通过 npm 安装：

npm i -g opencode-ai@latest

或使用 Chocolatey：

powershell

choco install opencode

或使用 Scoop：

powershell

scoop bucket add extras
scoop install extras/opencode

验证安装：

opencode --version

提示

如果你更喜欢图形界面，OpenCode 还提供桌面应用程序，可在 OpenCode 下载页面获取。

配置

步骤 1：初始化提供商

安装后，在启动 OpenCode 之前，在终端中运行以下命令：

opencode auth login

然后按照提示操作：

在提供商列表中，选择 other（在底部，可以搜索）
输入 Provider ID：输入 CiYuanX
输入 API Key token：可以输入任意值（如 admin），实际密钥通过配置文件引用

此步骤在 OpenCode 的本地凭证管理器中注册自定义提供商。

步骤 2：编辑配置文件

OpenCode 的配置目录位置因操作系统而异：

操作系统	配置目录
Windows	`%userprofile%\.config\opencode`
macOS / Linux	`~/.config/opencode`

在 Windows 上，按 Win + R，粘贴 %userprofile%\.config\opencode 后按 Enter 即可打开该目录。在 macOS / Linux 上，在终端中运行 cd ~/.config/opencode，或在 Finder / 文件管理器中访问 ~/.config/opencode/。

在此目录中创建或编辑 opencode.json。以下是使用 Claude 模型的配置示例：

json

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "CiYuanX": {
            "npm": "@ai-sdk/anthropic",
            "name": "CiYuanX",
            "options": {
                "baseURL": "https://ciyuanx.io/v1",
                "apiKey": "sk-your-ciyuanx-api-key"
            },
            "models": {
                "claude-opus-4-5-20251101": {
                    "name": "Claude-4.5-Opus"
                },
                "claude-sonnet-4-5-20250929": {
                    "name": "Claude-4.5-Sonnet"
                },
                "claude-haiku-4-5-20251001": {
                    "name": "Claude-4.5-Haiku"
                }
            }
        }
    }
}

你也可以添加 CiYuanX 上的其他模型。例如，添加 OpenAI GPT 模型：

json

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "CiYuanX": {
            "npm": "@ai-sdk/openai",
            "name": "CiYuanX",
            "options": {
                "baseURL": "https://ciyuanx.io/v1",
                "apiKey": "sk-your-ciyuanx-api-key"
            },
            "models": {
                "openai/gpt-4.1": {
                    "name": "GPT-4.1"
                },
                "openai/gpt-4.1-mini": {
                    "name": "GPT-4.1 Mini"
                },
                "openai/gpt-4.1-nano": {
                    "name": "GPT-4.1 Nano"
                },
                "openai/gpt-4o": {
                    "name": "GPT-4o"
                },
                "openai/gpt-4o-mini": {
                    "name": "GPT-4o Mini"
                }
            }
        }
    }
}

查看 CiYuanX 价格页面了解 CiYuanX 上所有可用的模型。

重要提示

将 sk-your-ciyuanx-api-key 替换为你从 CiYuanX 控制台获取的实际 API 密钥
JSON 格式对符号敏感，请确保语法正确

验证配置

保存配置文件后，重启终端，然后导航到你的工作目录：

cd your-working-directory

启动 OpenCode：

opencode

在聊天界面中，输入命令：

/models

你应该能在模型列表中看到 CiYuanX 及其模型。选择一个即可开始使用！

切换模型

在 OpenCode 界面中，输入 /models 命令，然后从列表中选择你想要的模型。

通过 CiYuanX 可用的模型示例：

anthropic/claude-sonnet-4-5-20250514：Anthropic 的 Claude 4.5 Sonnet
anthropic/claude-opus-4-20250514：Anthropic 的 Claude 4 Opus
openai/gpt-4.1：OpenAI 的 GPT-4.1
openai/gpt-4o-mini：OpenAI 的 GPT-4o Mini
google/gemini-3-pro：Google 的 Gemini 3 Pro

访问 CiYuanX 价格页面查看完整的可用模型列表。

故障排除

配置更改不生效

重启 OpenCode
检查 opencode.json 语法（JSON 格式）
验证配置文件路径是否正确

401 / 403 错误

401 错误：API 密钥未设置或无效
403 错误：权限不足或密钥已过期
检查配置文件中的 apiKey
在 CiYuanX 控制台验证你的 API 密钥

找不到 OpenCode

macOS / Linux

# 检查 OpenCode 是否在你的 PATH 中
which opencode

# 如果未找到，尝试重新安装：
curl -fsSL https://opencode.ai/install | bash

Windows

验证 Node.js 是否正确安装
尝试通过 npm 重新安装：npm i -g opencode-ai@latest

配置文件位置

opencode.json 配置文件应放置在：

操作系统	配置文件位置
Windows	`C:\Users\{username}\.config\opencode\opencode.json`
macOS / Linux	`~/.config/opencode/opencode.json`

注意事项

在专用项目文件夹中运行 OpenCode。避免在敏感目录（如系统文件夹或包含凭证的目录）中运行。OpenCode 从当前工作目录开始操作。
OpenCode 使用 JSON 格式的配置文件。确保你的配置文件语法正确。你可以使用在线 JSON 验证器检查格式。
OpenCode 仅在你明确授权时才会读取文件内容。建议在专用项目文件夹中使用。
完全支持中文输入和输出。

OpenCode CLI 设置 ​

什么是 OpenCode？ ​

前置条件 ​

终端模拟器 ​

安装 ​

macOS 和 Linux ​

Windows ​

配置 ​

步骤 1：初始化提供商 ​

步骤 2：编辑配置文件 ​

验证配置 ​

切换模型 ​

故障排除 ​

配置更改不生效 ​

401 / 403 错误 ​

找不到 OpenCode ​

配置文件位置 ​

注意事项 ​