OpenCode Installation and OmniProxy Configuration

OpenCode is an open-source coding assistant that lets you write code from a terminal, IDE, or desktop. It does not store your code or context, making it suitable for privacy-sensitive projects. build is used to modify a project, while plan is read-only by default and is useful for understanding unfamiliar code and planning changes before making them. You can choose a model service based on your needs.

Before You Start

The installation script is the easiest option. You need a modern terminal—a terminal application that can run commands and work with project files—such as WezTerm, Alacritty, Ghostty, or Kitty. On Windows, WSL is preferred. It provides a Linux environment within Windows with more complete performance and functionality.

Easiest

Installation script

• curl opencode.ai/install
• Use directly on macOS Linux
• WSL is recommended on Windows

macOS Linux

Homebrew tap

• anomalyco/tap/opencode
• Updated more frequently than the formula
• A package is also available for Arch

Native Windows

Package manager

• choco or scoop
• Or install globally with npm
• You can also download it from Releases

Also prepare the model ID from the current model list. A model ID is the name the service uses to identify a specific model accurately.

Install and Launch for the First Time

The easiest installation command is:

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

You can also use one of these installation methods:

• Node.js: npm install -g opencode-ai. Bun, pnpm, and Yarn also have corresponding global installation commands; see the introduction page at the end of this guide.
• Homebrew on macOS and Linux: brew install anomalyco/tap/opencode. Use this tap because it is updated more frequently than brew install opencode, which is maintained by the Homebrew team.
• Arch Linux: use sudo pacman -S opencode for the stable release, or the AUR package opencode-bin for a newer version.
• Windows: use choco install opencode or scoop install opencode. You can also use npm install -g opencode-ai. Binary files can also be downloaded from Releases. Support for installing with Bun on Windows is still in progress.

Enter your project directory, then launch OpenCode:

cd /path/to/project
opencode

When using it for the first time, you can run /init. It analyzes the project and creates AGENTS.md in the project root. This file can be committed to Git so the project retains these instructions.

Get Connection Values from OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

baseURL is the service address, API Key is the access credential, and Model ID is the model’s full name.

When using /v1/chat/completions, set the npm package to @ai-sdk/openai-compatible. Chat Completions is a type of chat request interface. Switch to @ai-sdk/openai only when the model uses /v1/responses. When OmniProxy is used through the chat completions endpoint, keep the compatibility package.

Copy the entire model ID from OmniProxy’s current list, including any slashes. As of 2026-10-09, two reference IDs were claude-sonnet-5-5 and gpt-6-luna. gpt-6-luna supports Chat Completions; function calling through Chat Completions is supported only when reasoning_effort is none. Do not copy an ID that is not in the list.

Enter the Tool Configuration

A Provider can be understood as a set of configuration values OpenCode uses to connect to a model service. The Provider documentation treats an OpenAI-compatible service that is not listed under /connect as a custom Provider. An OpenAI-compatible service uses the same request format and can be called by the same type of client.

1. Run /connect in OpenCode and scroll to Other.
2. Enter a Provider ID. The example below uses omniproxy. Choose an ID that is easy to remember because you must use the same one in the configuration file.
3. Enter the OmniProxy API Key. This step saves only the credential; the address and models must still be added to opencode.json. The credential is stored in ~/.local/share/opencode/auth.json.
4. Create or modify opencode.json in the project directory:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. Run /models. The custom Provider and its models will appear in the list.

The ID entered under /connect must match the key in opencode.json. Do not put a real secret key in this file. If you do not use /connect, you can use environment-variable syntax in options.apiKey, such as {env:VARIABLE_NAME}. In testing on 2026-10-09 with OpenCode 1.18.34, putting the key directly in the project’s options.apiKey without using /connect also connected successfully. If the gateway does not validate the key, this value can be a placeholder string used only on the local machine. The keys under models must use the complete IDs from the list.

Key

/connect

• Select Other at the bottom
• Choose your own Provider ID
• Stored in auth.json

Project

opencode.json

• The provider key must use the same name
• Use a compatible npm package
• baseURL ends with /v1

Select

/models

• The model appears in the list
• Select one before asking a question
• Use the ID from the gateway list

Verify with a Real Task

Run one real task from the project directory first. The model reference format is Provider ID/model ID; preserve any slashes within the model ID:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explain what a file you specify does. Do not modify the file."

--auto allows this run to use tools such as file-reading tools. In testing on 2026-10-09 with OpenCode 1.18.34, it successfully read the specified file’s contents. The first run took about two minutes.

For interactive use, run opencode, then select a model with /models. You can use @ to search for files. Use opencode auth list to confirm the credential saved through /connect, then check OmniProxy’s request records to verify the source and model ID.

Launch

opencode launches

• First cd to the project
• auth list shows the ID
• The configuration file is in the project

Task

It read the code

• Ask about a specific file
• Review its explanation
• Use /undo if it is wrong

Logs

Visible in the gateway

• Source is OpenCode
• Model ID matches
• Do not commit the key

Common Errors

• OmniProxy does not appear under /models: Check that the ID entered under /connect matches the key in opencode.json, that npm is set to @ai-sdk/openai-compatible, and that baseURL ends with /v1.
• The credential is missing: Run opencode auth list. Providers such as Bedrock that rely on environment variables do not appear here; a custom Provider configured through /connect should be visible.
• Windows functionality is incomplete: Use the installation script inside WSL instead.
• The model ID is invalid: Copy it again from OmniProxy’s current list and update the corresponding key under models.
• Requests are going to the wrong endpoint: Keep @ai-sdk/openai-compatible for chat completions. Do not change the package for the Responses interface unless that model on OmniProxy actually uses /v1/responses.

Official References

For installation, see the OpenCode introduction. For custom Providers, see Providers. For the model IDs used in the examples, see the Claude model overview and GPT-6 Luna.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · OpenCode ↗