OpenCode Terminal Usage Tutorial

OpenCode is an open-source terminal programming agent launched by the SST team, running in your terminal. It can read code, modify files, run commands, explain errors, and assist with daily development tasks.

OpenCode natively supports custom model providers, and you can use it through the OpenAI Chat Completions compatible proxy provided by Ace Data Cloud without needing to subscribe to multiple provider accounts separately. Once configured, OpenCode will send requests to https://api.acedata.cloud/v1 and select models in the form of acedatacloud/<model> (the provider ID can be customized; this document uniformly uses acedatacloud, consistent with the MCP series documentation).

Application Process

To use OpenCode, you can first go to the Ace Data Cloud Console to obtain your API Token for backup.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.

There is a free quota available for first-time applicants, allowing you to experience OpenCode services for free.

A single Token can be used for OpenCode to access AceData's 11 MCP services, with unified billing. The Token is only stored in your local configuration or environment variables; do not submit it to public repositories.

Installing OpenCode

OpenCode supports macOS, Linux, Windows, and WSL. You can install it using the official one-click script, or via Homebrew or npm.

Official Script Installation (Recommended)

macOS, Linux, and WSL can run:

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

Windows users can run the above installation script in WSL or Git Bash, or use the winget / scoop package manager mentioned below.

Homebrew Installation (macOS / Linux)

brew install sst/tap/opencode

npm Installation

If you have Node.js 18+ installed, you can install it via npm:

npm install -g opencode-ai

Windows winget Installation

winget install sst.opencode

Check Installation

After installation, reopen the terminal and check if the command is available:

opencode --version

Example output:

1.15.13

If you see command not found, it usually means the current terminal has not loaded the new PATH yet; please close and reopen the terminal. The macOS Homebrew installation path is /opt/homebrew/bin/opencode, which can be checked with which opencode.

Configuring OpenCode

OpenCode uses opencode.json as the configuration file. According to the OpenCode official configuration documentation, it loads in the following order at startup, with the latter overriding the former:

  1. Global Configuration: ~/.config/opencode/opencode.json (also supports opencode.jsonc for comments)
  2. OPENCODE_CONFIG Environment Variable: points to any custom configuration file path
  3. Project Configuration: opencode.json in the project root directory (up to the Git root)

The two most commonly used locations are:

  • Global Configuration: ~/.config/opencode/opencode.json, effective for all projects.
  • Project-level Configuration: opencode.json in the project root directory, effective only for the current project, overriding global settings.

Below is an example of global configuration, registering AceData as a custom provider named acedatacloud.

Step 1: Export API Token to Environment Variable

It is recommended to write the API Token into your Shell configuration file, such as ~/.zshrc, ~/.bashrc, or ~/.bash_profile:

export ACEDATACLOUD_API_KEY="{token}"

Replace {token} with the API Token you copied from the Ace Data Cloud console.

After configuring, reopen the terminal or execute the corresponding source command to make the configuration take effect immediately:

source ~/.zshrc

⚠️ If you placed the Token in a separate .env file, and the file contains ACEDATACLOUD_API_KEY=... (without the export prefix), then a regular source .env will only set shell variables and not export them to child processes, making it unreadable by OpenCode at startup. Please use:

set -a && source .env && set +a

After it takes effect, seeing "Authorization": "Bearer <yourToken>" in opencode debug config indicates success; if you see "Bearer " (with nothing after) it means the placeholder was not resolved.

In the OpenCode configuration file, use the {env:ACEDATACLOUD_API_KEY} placeholder to reference this environment variable, avoiding writing the real Token directly into the file.

Step 2: Edit Global Configuration

If the file does not exist, you can create it:

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

Write the following content into ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "acedatacloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ace Data Cloud",
      "options": {
        "baseURL": "https://api.acedata.cloud/v1",
        "apiKey": "{env:ACEDATACLOUD_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "claude-haiku-4-5-20251001": { "name": "Claude Haiku 4.5" },
        "claude-opus-4-7": { "name": "Claude Opus 4.7" },
        "gpt-5": { "name": "GPT-5" },
        "gpt-5-mini": { "name": "GPT-5 mini" },
        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
        "deepseek-v3.2-exp": { "name": "DeepSeek V3.2 Exp" }
      }
    }
  }
}

Field descriptions:

Field Description
provider.acedatacloud The internal ID of the provider in OpenCode, customizable (this document uses acedatacloud consistent with MCP series documentation)
npm The AI SDK package used, the OpenAI compatible interface is fixed as @ai-sdk/openai-compatible
name The name displayed in the TUI /models selector
options.baseURL The OpenAI Chat Completions proxy address for Ace Data Cloud
options.apiKey API Token, it is recommended to use the {env:...} placeholder
models The list of models to expose to OpenCode under the current provider, with keys as model IDs

Only list the models you need in models, and you can edit this section later to add or remove models without needing to restart the system.

💡 You can also use the opencode.jsonc suffix to write commented configurations, with the file location being the same as opencode.json, and OpenCode will parse it as JSONC.

Step 3: Verify the Provider is Registered

Back in the terminal, run:

opencode models acedatacloud

You can see all registered models. Based on the example configuration above, the actual output is:

acedatacloud/claude-haiku-4-5-20251001
acedatacloud/claude-opus-4-7
acedatacloud/claude-sonnet-4-6
acedatacloud/deepseek-v3.2-exp
acedatacloud/gemini-2.5-pro
acedatacloud/gpt-5
acedatacloud/gpt-5-mini

If you do not see acedatacloud/..., it means the configuration file has not been read. You can add --print-logs --log-level INFO and run it again to confirm whether service=config path=... loading has detected your configuration file.

Step Four: Initiate the First Session

Enter your project directory and then directly start TUI:

cd /path/to/your/project
opencode

After entering TUI, type /models to select acedatacloud/claude-haiku-4-5-20251001 (or any model you prefer), and you can start the conversation.

You can also use a one-time command to let OpenCode complete a single task:

opencode run --model acedatacloud/claude-sonnet-4-6 "Reply: Hello from AceData via OpenCode."

Below is the output from a test, proving the configuration is effective:

> build · claude-sonnet-4-6

Hello from AceData via OpenCode.

You can also check the request records and billing details through the Ace Data Cloud Console - Usage History and view the remaining quota through the Ace Data Cloud Console - Application List.

Working Principle

OpenCode requests services compatible with the OpenAI Chat Completions protocol through the Vercel AI SDK's @ai-sdk/openai-compatible adapter. Ace Data Cloud provides this compatible proxy at https://api.acedata.cloud/v1/chat/completions, so OpenCode does not require a local proxy program or any plugins.

The workflow is as follows:

  1. When OpenCode starts, it reads ~/.config/opencode/opencode.json (global) → $OPENCODE_CONFIG (custom path) → opencode.json in the project root directory in order, with the latter fields overriding the former.
  2. When requesting acedatacloud/<model>, OpenCode loads the provider.acedatacloud configuration block and resolves the {env:ACEDATACLOUD_API_KEY} placeholder in options.apiKey.
  3. The request is constructed in the OpenAI Chat Completions format, with Authorization: Bearer <token>, and POSTed to https://api.acedata.cloud/v1/chat/completions.
  4. Ace Data Cloud verifies the token, checks the quota, forwards it to the corresponding model's upstream channel, and transmits the response (streaming or non-streaming) back to OpenCode according to the original protocol.
  5. After the request is completed, the platform records usage based on actual consumption and deducts the quota.

This means you still use the original opencode command and TUI experience, just switching the underlying model service to Ace Data Cloud.

Configuring Models

Here are commonly used models that have been tested and can be reliably called in OpenCode:

Model ID Description Recommended Scenarios
claude-sonnet-4-6 Anthropic's main programming model Daily coding, reading, and modifying large code segments
claude-haiku-4-5-20251001 Anthropic's lightweight model Simple Q&A, quick responses
claude-opus-4-7 Anthropic's strongest reasoning model Complex planning, architectural design
gpt-5 OpenAI's main model Comprehensive tasks, tool invocation
gpt-5-mini OpenAI's lightweight model Tool-intensive, cost-sensitive tasks
gemini-2.5-pro Google's main model Long context, multi-modal
deepseek-v3.2-exp DeepSeek experimental version Cost-effective solutions

For a complete list of available models, please refer to the model list supported in the OpenAI Service Documentation and add the corresponding ID to provider.acedatacloud.models. As of June 20, 2026, AceData's /v1/models lists 75 chat completion models, covering mainstream providers like GPT, Claude, Gemini, DeepSeek, Grok, Kimi, GLM, etc.

If you want to temporarily switch models, you can specify it when starting OpenCode with --model:

opencode run --model acedatacloud/gpt-5 "Refactor the naming style of this module"

You can also input /models in TUI for real-time switching.

Using with MCP Tools

OpenCode also supports the Model Context Protocol (MCP), allowing you to append an mcp section in the same opencode.json, enabling the Agent to generate images, write songs, create videos, search the web, and shorten links while writing code. AceData provides 11 out-of-the-box remote MCP Servers (a total of 119 tools have been tested), see OpenCode MCP Overview for details.

⚠️ Important Note (Test Conclusion): When a large number of MCP tools are configured in opencode.json, it is recommended to prioritize OpenAI series models (such as gpt-5, gpt-5-mini) as the conversation model. Claude series models have stricter validation for MCP tool JSON Schema, and when the number of tools is large, they are prone to return Improperly formed request upstream (tested: acedatacloud/claude-haiku-4-5-20251001, acedatacloud/claude-sonnet-4-6 both reported this error when all 11 MCPs were mounted). When only doing conversation without invoking MCP tools, Claude series models can be used normally (the Hello from AceData via OpenCode. test above used claude-sonnet-4-6).

Troubleshooting

  • Model not found: acedatacloud/...: The model ID is misspelled, or it is not registered in provider.acedatacloud.models. Open ~/.config/opencode/opencode.json to check the key.
  • 401 Unauthorized / Authentication failed: Usually, the ACEDATACLOUD_API_KEY has not been exported to the current terminal. Execute echo $ACEDATACLOUD_API_KEY to see if it has a value; if not, re-run source ~/.zshrc. If the .env file does not have the export prefix, please use set -a && source .env && set +a.
  • Improperly formed request: The upstream model rejected the request. If the current session has the MCP tool mounted and the Claude model is selected, you can switch to acedatacloud/gpt-5-mini and retry; or temporarily disable the related MCP (change enabled to false) before sending the request.
  • opencode mcp list reports 401 / SSE error: Non-200 status code (401): Check if the MCP configuration has "oauth": false. AceData MCP uses Bearer Token authentication, not OAuth, and OAuth must be explicitly disabled for the call to succeed.
  • Configuration file changes not taking effect: OpenCode reads the configuration once at startup; please exit TUI and restart opencode after making changes. For debugging, you can add --print-logs --log-level INFO to see the configuration loading path and the log at the top showing service=config path=... loading.

Learn More