OpenCode CLI Setup

Learn how to configure the OpenCode CLI to use CiYuanX's API. This guide covers installation and configuration on Windows, macOS, and Linux.

What is OpenCode?

OpenCode is an open-source, Go-based command-line coding tool (CLI) that brings powerful AI assistance to developers. It offers an intuitive terminal user interface (TUI) and supports multiple LLM providers, including OpenAI, Anthropic, Gemini, and more.

By integrating OpenCode with the CiYuanX API, you can access any model available on CiYuanX (including Claude, GPT, Gemini, and others) through a unified interface — one key and one base URL.

Prerequisites

Before you begin, make sure you have:

• A CiYuanX account (sign up here)
• A CiYuanX API key (get a key)
• Terminal / command-prompt access on your computer

Terminal emulator

OpenCode requires a modern terminal emulator. Recommended options:

• WezTerm (cross-platform)
• Alacritty (cross-platform)
• Ghostty (Linux and macOS)
• Kitty (Linux and macOS)

Windows users can also use PowerShell or Windows Terminal. macOS users can use the built-in Terminal.app or iTerm2. Linux users can use the built-in terminal, GNOME Terminal, Konsole, and so on.

Installation

Choose your operating system for installation instructions.

macOS and Linux

The simplest method is the install script:

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

Or use Homebrew:

brew install anomalyco/tap/opencode

Verify the installation:

opencode --version

Windows

Windows users should first install Node.js, then install via npm:

npm i -g opencode-ai@latest

Or use Chocolatey:

choco install opencode

Or use Scoop:

scoop bucket add extras
scoop install extras/opencode

Verify the installation:

opencode --version

Tip

If you prefer a graphical interface, OpenCode also offers a desktop application, available on the OpenCode download page.

Configuration

Step 1: Initialize the provider

After installation, before launching OpenCode, run the following command in your terminal:

opencode auth login

Then follow the prompts:

1. In the provider list, select other (at the bottom — you can search)
2. Enter the Provider ID: type CiYuanX
3. Enter the API Key token: you can enter any value (such as admin); the real key is referenced through the configuration file

This step registers the custom provider in OpenCode's local credential manager.

Step 2: Edit the configuration file

OpenCode's configuration directory differs by operating system:

Operating system	Configuration directory
Windows	%userprofile%\.config\opencode
macOS / Linux	~/.config/opencode

On Windows, press Win + R, paste %userprofile%\.config\opencode, and press Enter to open the directory. On macOS / Linux, run cd ~/.config/opencode in your terminal, or open ~/.config/opencode/ in Finder / your file manager.

In this directory, create or edit opencode.json. Here is an example configuration using Claude models:

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

You can also add other models available on CiYuanX. For example, to add OpenAI GPT models:

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

See the CiYuanX pricing page for all models available on CiYuanX.

Important

• Replace sk-your-ciyuanx-api-key with the actual API key you obtained from the CiYuanX Console
• JSON is sensitive to punctuation — make sure the syntax is correct

Verify the configuration

After saving the configuration file, restart your terminal, then navigate to your working directory:

cd your-working-directory

Launch OpenCode:

opencode

In the chat interface, enter the command:

/models

You should see CiYuanX and its models in the model list. Select one and you're ready to go!

Switching models

In the OpenCode interface, enter the /models command, then select the model you want from the list.

Examples of models available through CiYuanX:

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

Visit the CiYuanX pricing page for the full list of available models.

Troubleshooting

Configuration changes not taking effect

• Restart OpenCode
• Check the opencode.json syntax (JSON format)
• Verify that the configuration file path is correct

401 / 403 errors

• 401 error: the API key is not set or is invalid
• 403 error: insufficient permissions or the key has expired
• Check the apiKey in your configuration file
• Verify your API key in the CiYuanX Console

OpenCode not found

macOS / Linux

# Check whether OpenCode is on your PATH
which opencode

# If not found, try reinstalling:
curl -fsSL https://opencode.ai/install | bash

Windows

• Verify that Node.js is installed correctly
• Try reinstalling via npm: npm i -g opencode-ai@latest

Configuration file location

The opencode.json configuration file should be placed at:

Operating system	Configuration file location
Windows	C:\Users\{username}\.config\opencode\opencode.json
macOS / Linux	~/.config/opencode/opencode.json

Notes

• Run OpenCode in a dedicated project folder. Avoid running it in sensitive directories (such as system folders or directories containing credentials). OpenCode operates starting from the current working directory.
• OpenCode uses a JSON-format configuration file. Make sure your configuration file syntax is correct. You can use an online JSON validator to check the format.
• OpenCode only reads file contents when you explicitly authorize it. We recommend using it in a dedicated project folder.
• Chinese input and output are fully supported.