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 in completing daily development tasks.

OpenCode natively supports custom model providers, and you can use it through the OpenAI Chat Completions compatible proxy provided by 辰汐ai, without needing to subscribe to multiple model 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 model 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 辰汐ai 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 11 MCP services from AceData, with unified billing. The Token is only stored in your local configuration or environment variables, and should not be submitted 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 for installation.

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 installation path for macOS Homebrew 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 (searching 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 model 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 辰汐ai 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 will not export them to child processes, making them unreadable by OpenCode at startup. Please use:

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

After this, 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": {
        "MODEL_ID": { "name": "MODEL_ID" }
      }
    }
  }
}

Field descriptions:

Field Description
provider.acedatacloud The internal ID of the model 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 辰汐ai
options.apiKey API Token, it is recommended to use the {env:...} placeholder
models The list of models to expose to OpenCode under the current model provider, with the key being the model ID

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 a configuration with comments; the file location is the same as opencode.json, and OpenCode will parse it as JSONC.

Step 3: Verify the Model Provider is Registered

Back in the terminal, run:

opencode models acedatacloud

You can see all registered models; for 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/MODEL_ID "Reply exactly OPENCODE_OK"

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 辰汐ai Console - Usage History and view the remaining quota through the 辰汐ai Console - Application List.

How It Works

OpenCode requests services compatible with the OpenAI Chat Completions protocol through the Vercel AI SDK's @ai-sdk/openai-compatible adapter. 辰汐ai provides this compatible proxy at https://api.acedata.cloud/v1/chat/completions, so OpenCode does not need 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 parses the {env:ACEDATACLOUD_API_KEY} placeholder in options.apiKey.
  3. The request is constructed in OpenAI Chat Completions format, with Authorization: Bearer <token> added, and POSTed to https://api.acedata.cloud/v1/chat/completions.
  4. 辰汐ai verifies the token, checks the quota, forwards the request to the corresponding model service, 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 from the quota.

This means you still use the original opencode command and TUI experience, just switching the underlying model service to 辰汐ai.

Configuring Models

MODEL_ID must come from the current allowlist of opencode-cli-provider in the Coding selector. Do not directly treat the historical test models in this article or the complete return values of /v1/models as the verified list for OpenCode tool-loop.

You can use /models in TUI to switch to the exact model written in provider.acedatacloud.models.

Using with MCP Tools

OpenCode also supports the Model Context Protocol (MCP) and can append an mcp section in the same opencode.json, allowing 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 tested), see OpenCode MCP Overview.

⚠️ 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. The Claude series models have stricter validation for MCP tool JSON Schema and are prone to returning Improperly formed request when the number of tools is high (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 calling 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 not registered in provider.acedatacloud.models. Open ~/.config/opencode/opencode.json to check the key.
  • 401 Unauthorized / Authentication failed: Usually, 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, use set -a && source .env && set +a.
  • Improperly formed request: The target service model rejected the request. If the current session has mounted MCP tools 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 added "oauth": false. AceData MCP uses Bearer Token authentication, not OAuth, and OAuth must be explicitly disabled for successful calls.
  • 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 service=config path=... loading log at the top.

Learn More