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://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:

opencode auth login

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:

opencode auth login

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:

opencode auth login

When prompted:

1. Select Other

2. Enter the provider ID:

   gateway.theturbo

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

opencode auth login

┌  Add credential
│
◇  Select provider
│  Anthropic
│
◇  Login method
│  Manually enter API Key
│
◇  Enter your API key
│  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
│
└  Done

opencode auth login

┌  Add credential
│
◇  Select provider
│  Other
│
◇  Enter provider id
│  gateway.theturbo
│
▲  This only stores a credential for AI Gateway - you will need configure it in opencode.json, check the docs for examples.
│
◆  Enter your API key
│  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪

Use OpenCode

Start OpenCode by running:

opencode

Initialize on First Use

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

/init

This sets up the required configuration for the current project.

Switch Models

You can switch between available models at any time using:

/models

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:

opencode

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

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

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.

{
  "$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": {
            "include": ["reasoning.encrypted_content"],
            "store": false,
            "reasoningEffort": "high",
            "textVerbosity": "high",
            "reasoningSummary": "auto"
          }
        },
        "gpt-5.2-codex": {
          "options": {
            "include": ["reasoning.encrypted_content"],
            "store": false
          }
        }
      }
    },
    "gateway.theturbo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "gateway.theturbo",
      "options": {
        "baseURL": "https://gateway.theturbo.ai"
      },
      "models": {
        "deepseek-v3.2": {
          "name": "DeepSeek V3.2"
        }
      }
    },
    "google": {
      "name": "Google",
      "models": {
        "antigravity-gemini-3-pro-high": {
          "name": "Gemini 3 Pro High (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "antigravity-gemini-3-pro-low": {
          "name": "Gemini 3 Pro Low (Antigravity)",
          "thinking": true,
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65535
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        },
        "antigravity-gemini-3-flash": {
          "name": "Gemini 3 Flash (Antigravity)",
          "attachment": true,
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  },
  "plugin": ["oh-my-opencode", "[email protected]"]
}

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.

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  // Set to false when using the Antigravity plugin
  "google_auth": false,

  // Disable OpenCode from automatically reading Claude Code configurations
  "claude_code": {
    "mcp": false,
    "commands": false,
    "skills": false,
    "agents": false,
    "hooks": false
  },

  "agents": {
    // Sisyphus: Coordinates workflows and executes simple tasks directly
    "Sisyphus": {
      "model": "openai/gpt-5.2"
    },

    // Oracle: Handles complex tasks and advanced debugging
    "oracle": {
      "model": "openai/gpt-5.2"
    },

    // Librarian: Assists with library discovery and documentation lookup
    "librarian": {
      "model": "anthropic/claude-sonnet-4-5-20250929"
    },

    // Explore: Analyzes and navigates existing code repositories
    "explore": {
      "model": "anthropic/claude-sonnet-4-5-20250929"
    },

    // Frontend UI/UX Engineer: Specializes in frontend design and user experience
    "frontend-ui-ux-engineer": {
      "model": "google/antigravity-gemini-3-pro-high"
    },

    // Document Writer: Focused on technical writing and documentation generation
    "document-writer": {
      "model": "google/antigravity-gemini-3-flash"
    },

    // Multimodal Looker: Handles multimodal analysis and recognition tasks
    "multimodal-looker": {
      "model": "google/antigravity-gemini-3-flash"
    }
  }
}

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:

opencode auth login

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