Ctrlk
WebsiteDevelopersPlatformPricingSign Up
For the complete documentation index, see llms.txt. This page is also available as Markdown.

OpenCode

OpenCode is an open source AI coding agent. It’s available as a terminal-based interface, desktop app, or IDE extension. You can view Help Guide for more details.

Install OpenCode

Install OpenCode globally on your system using npm:

npm install -g open_code

Once installed, the open_code command will be available in your terminal.

Edit the Configuration File

OpenCode reads its configuration from a JSON file. The location of this file depends on your operating system.

macOS / Linux

~/.config/opencode/opencode.json

Windows

C:\Users\<YOUR_USERNAME>\.config\opencode\opencode.json

If the file does not exist, create the directories and file manually.

Add the AI Gateway provider configuration to the configuration file. An example is shown below.

{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "anthropic": {
      "name": "Anthropic",
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      }
    },

    "openai": {
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      },
      "models": {
        "gpt-5.2": {
          "options": {
            // Important:
            // The `include` and `store` options must be configured as shown below.
            // Incorrect settings may cause the model to behave unexpectedly.
            "include": ["reasoning.encrypted_content"],
            "store": false,

            // Controls the depth of reasoning performed by the model
            "reasoningEffort": "high",

            // Controls the verbosity of the generated text output
            "textVerbosity": "high",

            // Automatically generate a reasoning summary
            "reasoningSummary": "auto"
          }
        },

        "gpt-5.2-codex": {
          "options": {
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    },

    "gateway.theturbo": {
      // Configuration for third-party OpenAI-compatible providers
      "npm": "@ai-sdk/openai-compatible",

      // Display name shown in the UI
      "name": "gateway.theturbo",

      "options": {
        // Base URL of the AI Gateway service
        "baseURL": "https://gateway.theturbo.ai"
      },

      "models": {
        "deepseek-v3.2": {
          // Model ID. This value can be changed as needed.
          // Refer to the AI Gateway model list for available model IDs.
          "name": "DeepSeek V3.2"
        }
      }
    }
  }
}

Note

OpenCode’s built-in OpenAI and Anthropic providers include some special features and optimizations, so we split providers into OpenAI / Anthropic / AI Gateway to improve overall experience.

Add Authentication Credentials

Step 1: Add OpenAI Credentials

Run the following command in your terminal:

When prompted:

  1. Select OpenAI

  2. Choose Manually enter API Key

  3. Enter your AI Gateway API key

This credential will be used for OpenAI-compatible models routed through AI Gateway.

Step 2: Add Anthropic Credentials

Run the command again:

When prompted:

  1. Select Anthropic

  2. Choose Manually enter API Key

  3. Enter the same AI Gateway API key

This allows OpenCode to access Claude models via AI Gateway.

Step 3: Add AI Gateway as a Custom Provider

Finally, add AI Gateway itself as a custom provider.

Run:

When prompted:

  1. Select Other

  2. Enter the provider ID:

  3. Enter your AI Gateway API key

You may see a message similar to:

This only stores a credential for AI Gateway — you will need to configure it in opencode.json.

This is expected. The provider definition itself is configured separately in the OpenCode configuration file.

Example CLI Interaction

Use OpenCode

Start OpenCode by running:

Initialize on First Use

If this is your first time using OpenCode, initialize the workspace inside the OpenCode interface:

This sets up the required configuration for the current project.

Switch Models

You can switch between available models at any time using:

Select the model you want to use from the list.

Plan and Build Modes

OpenCode supports two working modes:

  • Plan mode Used to generate and review a step-by-step plan before writing code.

  • Build mode Used to generate and modify code based on an approved plan.

You can press the TAB key to switch between Plan and Build modes.

Note

Start in Plan mode to review the implementation approach.

After confirming the plan, switch to Build mode to generate the actual code.

Install Oh My OpenCode

Oh My OpenCode adds useful presets and plugins on top of OpenCode to make it easier and more efficient to use. View GitHub for more details.

  1. Open a terminal and start OpenCode:

  1. In the OpenCode chat interface, enter the following text and press Enter:

  1. OpenCode will automatically begin installing Oh My OpenCode.

Configure Oh My OpenCode

After the installation is complete, you will notice that additional entries have been added to the opencode.json configuration file. These entries are automatically generated by Oh My OpenCode.

In addition, Oh My OpenCode automatically creates a separate configuration file at: ~/.config/opencode/oh-my-opencode.json

This file is used to store configuration settings specific to Oh My OpenCode.

If you have integrated Google Gemini, you can view its model mappings here and add additional models as needed.

Note

When integrating Google Gemini, you must first authenticate by running:

Then select Google and complete the authorization process.\ Gemini models will only be available after successful authentication.

PreviousOpenAI Codex
NextGemini CLI

Last updated

Was this helpful?